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

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.