Difference between revisions of "API clients"
| (11 intermediate revisions by the same user not shown) | |||
| Line 1: | Line 1: | ||
[[API Details|Go to API overview]] | [[API Details|Go to API overview]] | ||
| − | + | =Getting records= | |
| + | |||
| + | The records in the system are divided into types, which can be People types like clients, staff, volunteers, etc, or Organisation types like funders, schools, GP surgeries etc. The clients endpoint can be used to access any People type, e.g. if volunteers are type 7, a list of volunteers can be retrieved using: | ||
| + | |||
| + | [GET] https<nowiki/>://api.dizions.co.uk/v2/clients/type/7 | ||
| + | |||
| + | This is just one of many filters available, 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. Filters can be used for getting reporting data, e.g. districts or disabilities, or searching for records, e.g. NHS number or email address. The following fields can be used as filters: | ||
| + | |||
| + | A full list of filters is available at | ||
| + | [GET] https<nowiki/>://api.dizions.co.uk/v2/clients/filterable_fields | ||
| + | |||
| + | 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<nowiki/>://api.dizions.co.uk/v2/clients/religion/1;3;10/ethnicity/1 | ||
| + | |||
| + | This example demonstrates searching for a client by email address: | ||
| + | |||
| + | [GET] https<nowiki/>://api.dizions.co.uk/v2/clients/email/jsmith@example.com | ||
| + | |||
| + | =Creating records= | ||
| + | |||
| + | The type can be specified when creating records, e.g. if staff are type 8, a new staff record can be created like this: | ||
| + | |||
| + | [POST] https<nowiki/>://api.dizions.co.uk/v2/clients with this in the body: | ||
| + | first_name: John | ||
| + | surname: Smith | ||
| + | type: 8 | ||
| + | |||
| + | If the type is omitted, the record will be automatically be created with type 1. | ||
| + | |||
| + | These types of people are defined in the dictionary: | ||
[GET] https<nowiki/>://api.dizions.co.uk/v2/dictionary/client_type | [GET] https<nowiki/>://api.dizions.co.uk/v2/dictionary/client_type | ||
| − | + | An important difference with the web application is that it may have [[Customise_Orgs_%26_People#Minimum_Data_Sets|Minimum Data Sets]] defined, e.g. name, email, phone number etc, for creating records. The API deliberately ignores these, as it's assumed the API consumer will define its own. Instead, it just asks for a first_name and surname. | |
| − | [ | + | =Updating records= |
| + | Use the PUT method instead of POST for creating records. You can send any of the same data, e.g. to update the primary phone number for client 123 | ||
| + | [PUT] https<nowiki/>://api.dizions.co.uk/v2/clients/id/123 with this in the body: | ||
| + | telephone: 0123456789 | ||
Latest revision as of 20:36, 4 March 2025
Getting records
The records in the system are divided into types, which can be People types like clients, staff, volunteers, etc, or Organisation types like funders, schools, GP surgeries etc. The clients endpoint can be used to access any People type, e.g. if volunteers are type 7, a list of volunteers can be retrieved using:
[GET] https://api.dizions.co.uk/v2/clients/type/7
This is just one of many filters available, 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. Filters can be used for getting reporting data, e.g. districts or disabilities, or searching for records, e.g. NHS number or email address. The following fields can be used as filters:
A full list of filters is available at
[GET] https://api.dizions.co.uk/v2/clients/filterable_fields
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
This example demonstrates searching for a client by email address:
[GET] https://api.dizions.co.uk/v2/clients/email/jsmith@example.com
Creating records
The type can be specified when creating records, e.g. if staff are type 8, a new staff record can be created like this:
[POST] https://api.dizions.co.uk/v2/clients with this in the body: first_name: John surname: Smith type: 8
If the type is omitted, the record will be automatically be created with type 1.
These types of people are defined in the dictionary:
[GET] https://api.dizions.co.uk/v2/dictionary/client_type
An important difference with the web application is that it may have Minimum Data Sets defined, e.g. name, email, phone number etc, for creating records. The API deliberately ignores these, as it's assumed the API consumer will define its own. Instead, it just asks for a first_name and surname.
Updating records
Use the PUT method instead of POST for creating records. You can send any of the same data, e.g. to update the primary phone number for client 123
[PUT] https://api.dizions.co.uk/v2/clients/id/123 with this in the body: telephone: 0123456789
