API referrals

From Charitylog Manual
Revision as of 14:51, 22 April 2024 by Msim (talk | contribs)
(diff) ← Older revision | Latest revision (diff) | Newer revision → (diff)
Jump to: navigation, search

Go to API overview

These are a groups of cohesive actions. These are typically called 'cases' in the web application. The web application's terminology section allows these to be renamed, but they are always called 'referrals' in the API.

Typically, you might get referrals with at least a project and date filter, like this:

[GET] https://api.dizions.co.uk/v2/referrals/date/2022-01-01,2022-12-31/project/1;2;3

The filter 'date' is the new referral date, i.e. the date of the first done_contact on the referral. If you want all referrals with a done_contact during the date range, use 'date_active', like this:

[GET] https://api.dizions.co.uk/v2/referrals/date_active/2022-01-01,2022-12-31/project/1;2;3


To create a referral, post to the endpoint, like this:

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

The body should be x-wwww-form-urlencoded, and contain the following keys and values:

client
client_type
date
project
template
stage
response_description

If using a branch system, 'branch' is also required.

Optionally, you can also add:

project_category
contact_method
funding_sponsor
contact_type
referrer
introduction_source
additional_org_person
priority

There are various validation rules in the web to make optional field compulsory for users of the web app, for example if you require a priority for every referral. These settings are not implemented in the API, as the data avilable to the API caller may be different to user of the web app. The assumption is that the caller will perform its own validation.

Note that, unlike the web app, referrals cannot be created with an outstanding action. As such, they will be marked as completed (and closed if the project is set to automatically close completed referrals). The due_contacts endpoint can be called using the returned referral id to add outstanding actions afterwards.

Referrals can be updating in much the same way, by doing a PUT with at least one of the required or optional fields:

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