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
To set channel permissions (e.g. ok to email etc) you need to provide an integer value for the ChannelPermissions property, these are the 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
When you are adding a constituent or adding timeline items - e.g. transactions - you can add active or excluded tags to constituents by passing details using the ActiveTags & ExcludedTags properties - the ActiveTags contains details of tags you want to add, the ExcludedTags are tags that should be added in an excluded state - e.g. for opting out of something.
The tag you want to add is identified by the tag category & the tag name with an underscore between the tag category and the tag name - for example if you wanted to add a tag called Newsletter in the Mailings category you would add Mailings_Newsletter into ActiveTags property. If you include multiple tags then separate them with a comma - e.g. Mailings_Appeals,Mailings_Newsletter
To work with tags for existing constituents you can
- Get all active tags by calling https://data.donorfy.com/api/v1/<your api key>/constituents/<id>/ActiveTags
- Get all excluded tags by calling https://data.donorfy.com/api/v1/<your api key>/constituents/<id>/ExcludedTags
- To add an active tag https://data.donorfy.com/api/v1/<your api key>/constituents/<id>/AddActiveTags
- To add an excluded tag https://data.donorfy.com/api/v1/<your api key>/constituents/<id>/AddExcludedTags
Note if you add an active or excluded tag and the constituent already had that tag as an excluded or active tag then the existing tag is automatically removed before the new tag is added.
When using the methods above you pass in a list of tags prefixed with the tag category as described above
To remove a tag you can use https://data.donorfy.com/api/v1/<your api key>/constituents/<id>/RemoveTag - passing in one tag description prefixed with its category
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.