This article provides information about working with Constituents via the API
Finding constituents
You can retrieve details of constituents using:
- Constituent ID
https://data.donorfy.com/api/v1/<your api key>/53530b0c-5eed-4fad-b400-347afc0a389a
- Constituent Number
https://data.donorfy.com/api/v1/<your api key>/77
- Constituent's external key - this will return all constituents with the external key passed
https://data.donorfy.com/api/v1/<your api key>/externalkey/ext123
- Search
- Pass in the keywords via the query string
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 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
- Pass in the keywords via the query string
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 Type 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"
Contact Details
Constituent 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
- Channels
Channel permissions are set by providing an integer value for the ChannelPermissions property as described below:
The ChannelPermissions property can have these values for each channel
- DoNotKeepInTouch = 0
- Email = 2
- Post = 4
- Sms = 8
- Phone = 16
- Email Unconfirmed = 32
- Post Unconfirmed = 64
- SMS Unconfirmed = 128
- Phone Unconfirmed = 256
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 to be 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
- Purposes
For purpose permissions (e.g., OK to send a fundraising email, newsletter, etc.), you should use the endpoints described in this article.
Email Status
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).
"Bounced"
Important make sure you percent encode (also known as URL encode) the email address - see this article or this article for more information
Tags
For information about working with tags see this article
Country Names
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 ExistingConstituentId property
To add a new constituent either omit or leave the ExistingConstituentId empty and provide the details of the new constituent, e.g. name, address etc - you must provide a valid ConstituentType.
If the new constituent is an organisation and you pass in a first and/or last name a new constituent will be created using the first and/or last name as the main contact at the organisation.
The Donorfy API is a Professional-only feature. Essential subscribers, please contact us to find out more about upgrading.
Comments
ExistingConstituntId is mis-spelled, above. It should be ExistingConstituentId as on https://data.donorfy.com/help/index#!/Rpi/Rpi_Post
Thank you for spotting that.