API Details

From Charitylog Manual
Revision as of 11:39, 22 July 2019 by Msim (talk | contribs) (→‎Updating Records)
Jump to: navigation, search
Helpheader small.png

On this page you will find some technical details of the Dizions API that works with the system. This enables you to interact with your data without having to log in to the web interface. It is a RESTful API using JSON over https. For prices, please call the office.


File:API.png


Authentication

The API grants access based on three headers:

  • Source. Identifies the 3rd party software provider
  • Org. Identifies the charity or company
  • User. Identifies the user within the charity or company. This controls branch, project and field visibility, as if the user were using the web interface.

Groups

The API is based around a range of groups that map to various entities.

  • clients (organisations that are "people")
  • referrals (diary)
  • done_contacts (completed actions)
  • due_contacts (outstanding actions)
  • workers (support workers)
  • schedules (job cards)
  • external_referrals (referrals collected externally, e.g. a self-referral form on your website )

An example URL would look like (GET) https://api.dizions.co.uk/v2/clients

Filters

If you want to filter your results, you can keep adding up to 10 key/value pairs to the URL. The value can usually take multiple values separated by a semi-colon.

The following fields can be used as filters in the /clients endpoint:

  • accommodation
  • active
  • age_range
  • blue_badge_holder
  • consent
  • county
  • deceased
  • district
  • employment_status
  • ethnicity
  • external_id
  • gender
  • gp_name
  • gp_surgery
  • id
  • main_disability
  • main_language
  • marital_status
  • nhs_number
  • people_in_household
  • postcode
  • preferred_communication_method
  • registered_disabled
  • religion
  • school
  • sexual_orientation
  • social_services_number
  • usual_support_worker

The example below would get all clients that have a religion (org_religion) ID of 1,3 or 10 and an ethnicity (org_ethnic_group) ID of 1.

[GET] https://api.dizions.co.uk/v2/clients/religion/1;3;10/ethnicity/1

The following fields can be used as filters in the /referrals endpoint:

  • additional_org_person
  • client
  • client_accommodation
  • client_active
  • client_age_range
  • client_blue_badge_holder
  • client_county
  • client_district
  • client_employment_status
  • client_ethnicity
  • client_external_id
  • client_gender
  • client_gp_name
  • client_gp_surgery
  • client_main_disability
  • client_main_language
  • client_marital_status
  • client_nhs_number
  • client_people_in_household
  • client_postcode
  • client_preferred_communication_method
  • client_registered_disabled
  • client_religion
  • client_school
  • client_sexual_orientation
  • client_type
  • contact_method
  • contact_type
  • date
  • description
  • funding_sponsor
  • id
  • introduction_source
  • priority
  • project
  • project_active
  • project_category
  • project_name
  • referral_complete
  • referrer
  • response_method
  • stage
  • template
  • updated

The following fields can be used as filters in the /done_contacts endpoint:

  • client
  • client_accommodation
  • client_active
  • client_age_range
  • client_blue_badge_holder
  • client_county
  • client_district
  • client_employment_status
  • client_ethnicity
  • client_external_id
  • client_gender
  • client_gp_name
  • client_gp_surgery
  • client_main_disability
  • client_main_language
  • client_marital_status
  • client_nhs_number
  • client_people_in_household
  • client_postcode
  • client_preferred_communication_method
  • client_registered_disabled
  • client_religion
  • client_school
  • client_sexual_orientation
  • client_type
  • contact_method
  • contact_type
  • due_stage
  • end_date
  • funding_sponsor
  • id
  • introduction_source
  • priority
  • project
  • project_active
  • project_category
  • project_name
  • referral
  • referral_complete
  • referrer
  • response_method
  • stage
  • template
  • travel_mileage
  • travel_time
  • user

The example below would get completed actions for project ID 5, where the client was unemployed and registered disabled.

[GET] https://api.dizions.co.uk/v2/done_contacts/client_registered_disabled/Y/client_employment_status/N/project/5


You can also filter by the record ID (getting a single record), e.g.

[GET] https://api.dizions.co.uk/v2/referrals/id/510.

For referrals and clients you can filter by single record extension database value(s).

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

For referrals, contacts and schedules you can restrict the results to a date range.

[GET] https://api.dizions.co.uk/v2/referrals/date_active/2018-10-01,2018-10-31

Selecting Specific Fields

When you hit an endpoint, a range of default fields are automatically returned. If you want something that isn't default, or you want to return less data to speed things up, you can pick the fields to be returned. In the case of referrals or clients you can also return any single record extension databases. Use /field/ with semicolon separated field names to choose the fields you want to return.

'[GET] https://api.dizions.co.uk/clients/field/id;surname;website_photo_consent

The API can tell you which fields are available by appending /selectable_fields to the group.

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

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

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

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

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

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

Creating Records

To create a record you need to do a [PUT] request, with fields in the body. Many of these will have a selection of mandatory fields.

Create a client:

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

Create a client by an external ID (e.g a reference to the client in another system):

[PUT] https://api.dizions.co.uk/v2/clients/external_id/EXTERNAL_ID

Create a referral (Record a Contact):

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

Create a due contact (incomplete action) for a referral:

[PUT] https://api.dizions.co.uk/v2/due_contacts/referral/REFERRAL_ID

Updating Records

To update records you need to use the [POST] method, with fields in the body. There will be some mandatory fields and some fields that need a value if present.

Update a client:

[POST] https://api.dizions.co.uk/v2/clients/id/CLIENT_ID

Most of the fields are the same fields available via GET, such as name, address and demographic details. In addition to it, relationships can also be created with these fields in the body: id_second (the id number of the related person), relationship_first_to_second and relationship_second_to_first (see /dictionary/relationships), and optionally, relationship_first_to_second_carer and relationship_second_to_first_carer (see /dictionary/carer_relationships)

Update a referral:

[POST] https://api.dizions.co.uk/v2/referrals/id/REFERRAL_ID

Update due contact

[POST] https://api.dizions.co.uk/v2/due_contacts/id/CONTACT_ID

Update done contact, or complete due contact (complete by completing the start_date and end_date in the body)

[POST] https://api.dizions.co.uk/v2/done_contacts/id/CONTACT_ID

External Referrals

External Referrals are held in a staging area, to be imported or rejected by the system administrator.

[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, with 1 notable exception: project. Including project will save the user who processes the referrals from having to select it each time they import.

File Uploads

You can upload files against clients and referrals, these can only be uploaded to Amazon S3.

[POST] https://api.dizions.co.uk/v2/clients/id/CLIENT_ID/uploads

[POST] https://api.dizions.co.uk/v2/referrals/id/REFERRAL_ID/uploads

In the body you'll need the files along with user_visibility and group_visibility settings which are IDs (comma separated if there's more than one)

Single Record Extension Databases

As mentioned previously, for referrals and clients you can select single record extension database data, or filter by these values. To expose these fields to the API you need to edit that field in the front end, setting Allow collaborator API access? to Yes and choosing a suitable Name to share with collaborators. You can then reference that extension database field by the collaborator name.

Multiple Record Extension Databases [GET]

Multiple record extension databases work as their own entity. They can be accessed in the API by a combination of their name and ID. Convert the name to lowercase, and replace spaces with underscores. Then separate the name and ID with an underscore. For example, this end point that gets all records for extension database 13, called Staff Disciplinary:

[GET] https://api.dizions.co.uk/v2/extension_database/staff_disciplinary_13

You can also specify which fields you want to select, to make things more efficient. Extension database records can be filtered in the same way as other requests, to get all results for a particular referral you can do this:

[GET] https://api.dizions.co.uk/v2/extension_database/wellcheck_notes_9/referral/2289

Multiple Record Extension Databases [PUT]

To create a new record you need to do a [PUT] request.

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

Then add the body:

referral 2289

date_43 2018-11-08

The ID of the new record will be returned.

Multiple Record Extension Databases [POST]

To update a record you also need to supply the ID:

[POST] https://api.dizions.co.uk/v2/extension_database/wellcheck_notes_9/id/17 Then add the POST body in the same way as a PUT request.

Reports

Reporting is based on dimensions and metrics, conceptually similar to an X and Y axis, although metrics are optional. If you pass in a dimension against a group, you will get a breakdown of the number of records in that group. For examplem, this will show you how many clients there are in each district:

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

If you want this further broken down by gender:

[GET] https://api.dizions.co.uk/v2/clients/dimension/district/metric/gender

You can also filter the results in the same way as other [GET] requests:

[GET] https://api.dizions.co.uk/v2/clients/dimension/district/metric/gender/main_disability/7;9/blue_badge_holder/Y

To view a user's completed contacts by day for a range of time, you can do this:

[GET] https://api.dizions.co.uk/v2/done_contacts/dimension/day/date_active/2018-10-01,2018-10-31/user/*USER_ID*

Dictionaries

Many of the values returned by the API are IDs, so there's a selection of dictionaries to get the friendly names. As a (slow and heavy) reference you can get all datadict dictionaries:

[GET] https://api.dizions.co.uk/v2/dictionary (not suggested for general use)

If the dictionary is set up in datadict you can access via api_group/table_reference. The end points below will return the full list of IDs and friendly names.

[GET] https://api.dizions.co.uk/v2/dictionary/organisations/district

[GET] https://api.dizions.co.uk/v2/dictionary/referrals/project

[GET] https://api.dizions.co.uk/v2/dictionary/contacts/contact_type

You can also search for items in the dictionary:

[GET] https://api.dizions.co.uk/v2/dictionary/search/referrals/project/SEARCH_TERM

[GET] https://api.dizions.co.uk/v2/dictionary/search/referrals/referrer/SEARCH_TERM

Retrieved from ‘https://wiki.dizions.co.uk/index.php?title=API_Details&oldid=12571’