Difference between revisions of "API: External Referrals"

From Charitylog Manual
Jump to: navigation, search
 
(40 intermediate revisions by 4 users not shown)
Line 1: Line 1:
 +
[[API Details| Go to API overview]]
 +
 
[[File:helpheader_small.png|right]]
 
[[File:helpheader_small.png|right]]
  
−
External Referrals are an alterative to making clients and referrals directly: they are held in a staging area, to be imported or rejected by the system administrator. This has the advantage that the caller of the API does not need to check whether the client they have is already known - the administrator can use the search tools in the GUI to prevent duplicates.
+
External Referrals are an alterative to making clients and referrals directly: they are held in a staging area, to be imported or rejected by the system administrator. This has the advantage that the caller of the API does not need to check whether the client they have is already known and the administrator can use the search tools in the GUI to prevent duplicates.
 +
----
  
−
[PUT] https://api.dizions.co.uk/v2/external_referral
+
[PUT] https<nowiki/>://api.dizions.co.uk/v2/external_referral
  
−
The org_type_id, surname and description fields must be passed as a minimum. Most optional fields are any field from the client endpoint, with 1 notable exception: project. Including project will save the user who processes the referrals from having to select it each time they import.
+
The org_type_id, surname and description fields must be passed as a minimum. Most optional fields are any field from the client endpoint, which can be found by calling
 +
[GET] https<nowiki/>://api.dizions.co.uk/v2/clients/selectable_fields
 +
or
 +
[GET] https<nowiki/>://api.dizions.co.uk/v2/external_referral/selectable_fields
 +
The body should look like this:
 +
  [
 +
    {
 +
        "org_type_id": "1",
 +
        "surname": "Smith",
 +
        "first_name": "Alice",
 +
        "description": "Wants support with..."
 +
    }
 +
  ]
 +
When the user imports the referral, after creating the organisation / person (or linking to an existing record), they will be taken through the Record a Contact process, and the description will form the start of the details of contact. Including project will save the user who processes the referrals from having to select it each time they import. Typically this would be done if all referrals are 'funnelled' through a single triage project. If you would like your users to choose the most appropriate project each time, like they would if they were manually creating a record, omit the project.
 +
  [
 +
    {
 +
        "org_type_id": "1",
 +
        "surname": "Smith",
 +
        "first_name": "Alice",
 +
        "description": "Wants support with...",
 +
        "project": "7"
 +
    }
 +
  ]
  
 
----
 
----
 +
Multiple people can be sent in one PUT, for instance a carer and their cared-fors, or a client and their social worker. In both cases, it may be useful to specify the relationships between them. The key-values for the relationship can be found in the dictionary. In the example below, Alice is the mother (relationship 5 in our demo system) of Bob and Charlie. Bob and Charlie are the sons (relationship 8) of Alice. Bob and Charlie are brothers (relationship 15). The people are referenced by a zero-indexed list, following their order in the JSON, e.g. Alice is 0, with a relationship to 1 (Bob) and 2 (Charlie).
 +
  [
 +
    {
 +
        "first_name": "Alice",
 +
        "surname": "Smith",
 +
        "org_type_id": "1",
 +
        "description": "Wants support with...",
 +
        "relationships": {
 +
            "1": "5",
 +
            "2": "5"
 +
        }
 +
    },
 +
    {
 +
        "first_name": "Bob",
 +
        "surname": "Smith",
 +
        "org_type_id": "2",
 +
        "relationships": {
 +
            "0": "8",
 +
            "2": "15"
 +
        }
 +
    },
 +
    {
 +
        "first_name": "Charlie",
 +
        "surname": "Smith",
 +
        "org_type_id": "2",
 +
        "relationships": {
 +
            "0": "8",
 +
            "1": "15"
 +
        }
 +
    }
 +
  ]
 +
Relationships are optional, but if specified, they must be in pairs. For instance, it is not possible to specify Bob as the son, without also specifying Alice as the mother.
 +
 +
Carer relationships can also be set, using the key carer_relationships. These must also be in pairs. Using the example above, if Alice cares for her sons, and Carer is relationship 3, and Cared-For is relationship is 4, the JSON would look like this:
 +
  [
 +
    {
 +
        "first_name": "Alice",
 +
        "surname": "Smith",
 +
        "org_type_id": "1",
 +
        "description": "Wants support with...",
 +
        "relationships": {
 +
            "1": "5",
 +
            "2": "5"
 +
        },
 +
        "carer_relationships": {
 +
            "1": "3",
 +
            "2": "3"
 +
        }
 +
    },
 +
    {
 +
        "first_name": "Bob",
 +
        "surname": "Smith",
 +
        "org_type_id": "2",
 +
        "relationships": {
 +
            "0": "8",
 +
            "2": "15"
 +
        },
 +
        "carer_relationships": {
 +
            "0": "4"
 +
        }
 +
    },
 +
    {
 +
        "first_name": "Charlie",
 +
        "surname": "Smith",
 +
        "org_type_id": "2",
 +
        "relationships": {
 +
            "0": "8",
 +
            "1": "15"
 +
        },
 +
        "carer_relationships": {
 +
            "0": "4"
 +
        }
 +
    }
 +
  ]

Latest revision as of 12:28, 3 September 2024

Go to API overview

Helpheader small.png

External Referrals are an alterative to making clients and referrals directly: they are held in a staging area, to be imported or rejected by the system administrator. This has the advantage that the caller of the API does not need to check whether the client they have is already known and the administrator can use the search tools in the GUI to prevent duplicates. 

[PUT] https://api.dizions.co.uk/v2/external_referral

The org_type_id, surname and description fields must be passed as a minimum. Most optional fields are any field from the client endpoint, which can be found by calling 

[GET] https://api.dizions.co.uk/v2/clients/selectable_fields

or 

[GET] https://api.dizions.co.uk/v2/external_referral/selectable_fields

The body should look like this: 

 [
   {
       "org_type_id": "1",
       "surname": "Smith",
       "first_name": "Alice",
       "description": "Wants support with..."
   }
 ]

When the user imports the referral, after creating the organisation / person (or linking to an existing record), they will be taken through the Record a Contact process, and the description will form the start of the details of contact. Including project will save the user who processes the referrals from having to select it each time they import. Typically this would be done if all referrals are 'funnelled' through a single triage project. If you would like your users to choose the most appropriate project each time, like they would if they were manually creating a record, omit the project. 

 [
   {
       "org_type_id": "1",
       "surname": "Smith",
       "first_name": "Alice",
       "description": "Wants support with...",
       "project": "7"
   }
 ]

Multiple people can be sent in one PUT, for instance a carer and their cared-fors, or a client and their social worker. In both cases, it may be useful to specify the relationships between them. The key-values for the relationship can be found in the dictionary. In the example below, Alice is the mother (relationship 5 in our demo system) of Bob and Charlie. Bob and Charlie are the sons (relationship 8) of Alice. Bob and Charlie are brothers (relationship 15). The people are referenced by a zero-indexed list, following their order in the JSON, e.g. Alice is 0, with a relationship to 1 (Bob) and 2 (Charlie). 

 [
   {
       "first_name": "Alice",
       "surname": "Smith",
       "org_type_id": "1",
       "description": "Wants support with...",
       "relationships": {
           "1": "5",
           "2": "5"
       }
   },
   {
       "first_name": "Bob",
       "surname": "Smith",
       "org_type_id": "2",
       "relationships": {
           "0": "8",
           "2": "15"
       }
   },
   {
       "first_name": "Charlie",
       "surname": "Smith",
       "org_type_id": "2",
       "relationships": {
           "0": "8",
           "1": "15"
       }
   }
 ]

Relationships are optional, but if specified, they must be in pairs. For instance, it is not possible to specify Bob as the son, without also specifying Alice as the mother.

Carer relationships can also be set, using the key carer_relationships. These must also be in pairs. Using the example above, if Alice cares for her sons, and Carer is relationship 3, and Cared-For is relationship is 4, the JSON would look like this: 

 [
   {
       "first_name": "Alice",
       "surname": "Smith",
       "org_type_id": "1",
       "description": "Wants support with...",
       "relationships": {
           "1": "5",
           "2": "5"
       },
       "carer_relationships": {
           "1": "3",
           "2": "3"
       }
   },
   {
       "first_name": "Bob",
       "surname": "Smith",
       "org_type_id": "2",
       "relationships": {
           "0": "8",
           "2": "15"
       },
       "carer_relationships": {
           "0": "4"
       }
   },
   {
       "first_name": "Charlie",
       "surname": "Smith",
       "org_type_id": "2",
       "relationships": {
           "0": "8",
           "1": "15"
       },
       "carer_relationships": {
           "0": "4"
       }
   }
 ]
Retrieved from ‘https://wiki.dizions.co.uk/index.php?title=API:_External_Referrals&oldid=18896’