API Dictionaries

From Charitylog Manual
Revision as of 11:02, 6 November 2023 by Msim (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Go to API overview

Helpheader small.png

Many of the values returned by the API are IDs, so there's a selection of dictionaries to get the friendly names. You can get all the dictionaries using:

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


This returns a large payload, so is not suggested for general use. A better option is to access the dictionaries for the fields you need, via entity/table_reference. The end points below will return the full list of IDs and friendly names, e.g.

[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
[GET] https://api.dizions.co.uk/v2/dictionary/branch
[GET] https://api.dizions.co.uk/v2/dictionary/client_type

you can get client/record related fields by using the following, however this will only display fields used in projects within your system.

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

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

For Extension Database which are "Select From Option List" or "Radio buttons", there is a dictionary for each field, using the collaboration name displayed on each Extension Database Field:

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

IDs or names?

For read-only applications, e.g. a reporting dashboard, it may be useful to ask the API for the names of options, instead of the IDs, e.g. "Private Rented" instead of "4" for accommodation. This is referred to as "resolving" the IDs. You can specify individual fields, like this:

[GET] https://api.dizions.co.uk/v2/clients/id/1/field/id;ethnicity;main_language;school/?resolveIds[]=ethnicity&resolveIds[]=main_language


or all fields, like this:


[GET] https://api.dizions.co.uk/v2/clients/id/1/field/id;ethnicity;main_language;school/?resolveIds[]=ALL


NB this only applies when GETing data, records must always be created and updated using IDs.