This article provides information about working with Constituents via the API
You can retrieve details of constituents using
- Constituent Id - e.g. https://data.donorfy.com/api/v1/<your api key>/53530b0c-5eed-4fad-b400-347afc0a389a
- Constituent Number - e.g. https://data.donorfy.com/api/v1/<your api key>/77
- Constituent's external key - this will return all constituents with the external key passed - e.g. https://data.donorfy.com/api/v1/<your api key>/externalkey/ext123
- Pass in the keywords via the query string e.g. https://data.donorfy.com/api/v1/<your api key>/search?searchFor=Smith - the query string must be correctly url encoded
- Pass in the words you want to search for, if you enter 2 or more words constituents matching all the words will be returned
- If you want to find records containing any of the words you enter use OR e.g. Frank OR Smith.
- To find everything starting with a certain letters use * e.g. Sm*,
- Use NOT to exclude a word e.g. Smith NOT Frank
- You can build more complex searches using brackets e.g. (Frank Smith) OR (Jane Brown)
- The keyword search will return the first 100 constituents found matching the criteria passed
Mandatory and Optional Look Up Properties
When adding or updating constituents some properties of a constituent must contain values that exist in your Donorfy settings as follows:
You must pass in
- ConstituentType - e.g. Individual - i.e. a valid Constituent Types in your settings
Optionally you can pass in
- RecruitmentCampaign - e.g. General Campaign - if specified must be a valid campaign in your Donorfy
- Gender - if specified must be in the list of Genders in your settings
- Country - if specified must be in the list of Countries in your settings
- EmailFormat - if specified must be HTML or PlainText
Constituents data includes contact details information - i.e. address, phone numbers etc - for individual constituents the address information is from the personal contact details, for other types of constituents the work contact details are used.
You can also retrieve and update personal, work or other contact details via these methods
- https://data.donorfy.com/api/v1/<your api key>/constituents/<id>/PersonalContactDetails
- https://data.donorfy.com/api/v1/<your api key>/constituents/<id>/WorkContactDetails
- https://data.donorfy.com/api/v1/<your api key>/constituents/<id>/OtherContactDetails
Channel & Purpose Permissions
To set channel and purpose permissions (e.g. ok to email etc) you should use the endpoints described in this article
There is a legacy method to set channel permissions by providing an integer value for the ChannelPermissions property as described below - however, we recommend using the channel and purpose permissions endpoints.
The ChannelPermissions property can have these values for each channel
- DoNotKeepInTouch = 0
- Email = 2
- Post = 4
- Sms = 8
- Phone = 16
For example if someone wanted to be
- contacted by email and sms you would pass 10 in the ChannelPermissions property - i.e. the sum of the two values for Email & Sms
- never contacted you would pass 0
If the ChannelPermissions property is not passed when
- adding a new constituent then all channels will be blocked
- updating an existing constituent then existing channel permissions will not be changed
To update a constituent's email status (e.g. to indicate that emails to that address have bounced), the new status (one of "Active", "Bounced", or "Inactive") should be included, quoted, as a simple string in the message body (not as a JSON object).
For information about working with tags see this article
If you are adding an address for a new constituent and you specify a country then the country must exist in your country list in your Donorfy settings - if the country does not exist the addition will fail. If you do not want to add a country to your settings you should combine the country with the county before adding the address.
Linking new Entities to a New or an Existing Constituent
When you add a new entity - e.g. a transaction - you may
- know the Id of an existing constituent that the transaction should be associated with, or
- want to add a new constituent and associate the transaction with that
If you want to link the new entity to an existing constituent specify the constituent id in the ExistingConstituntId property
To add a new constituent either omit or leave the ExistingConstituntId empty and provide the details of the new constituent, e.g. name, address etc - you must provided a valid ConstituentType.
If the new constituent is an organisation and you all pass in a first and/or last name a constituent will be created using the first and/or last name as the main contact at the organisation.