Skip to main content

Work with Constituents Using the API

Retrieve, create, update, and manage constituent records securely through the Donorfy API.

Cristina Gruita avatar
Written by Cristina Gruita
Updated over a month ago

Find Constituents

You can retrieve constituent details using several supported lookup methods.

Find by Constituent ID

Use this method when you already know the unique identifier.

  1. Send a GET request using the constituent GUID:
    ​https://data.donorfy.com/api/v1/<your api key>/53530b0c-5eed-4fad-b400-347afc0a389a

  2. Review the returned constituent record.

Find by Constituent Number

Use this method when referencing an internal numeric identifier.

  1. Send a GET request using the constituent number:
    ​https://data.donorfy.com/api/v1/<your api key>/77

  2. Confirm the correct record is returned.

Find by External Key

External keys allow you to link Donorfy constituents to external systems.

  1. Send a GET request with the external key value:
    ​https://data.donorfy.com/api/v1/<your api key>/search?searchFor=Smith

  2. Review all constituents returned with that external key.

Multiple constituents can share the same external key.

Search for Constituents

The keyword search endpoint allows flexible searching.

  1. Pass keywords using the searchFor query parameter.

  2. Ensure all search terms are URL encoded .

Search behaviour includes:

  1. Multiple words return constituents matching all words.

  2. Use OR to match any word.

  3. Use * as a wildcard for partial matches.

  4. Use NOT to exclude terms.

  5. Use brackets to group complex logic.

📌 Note: Keyword search returns a maximum of 100 constituents per request.

Provide Mandatory and Optional Properties

When adding or updating a constituent, some properties must match values already configured in Donorfy.

Mandatory Property

You must provide a valid ConstituentType that exists in your Donorfy settings.

Optional Properties

If supplied, these values must also exist in Donorfy.

  1. RecruitmentCampaign.

  2. Gender.

  3. Country.

  4. EmailFormat, which must be HTML or PlainText.

If an optional value does not exist in Donorfy, the request fails or the property is ignored.

Manage Contact Details

Constituent contact details vary by constituent type.

  1. Individual constituents use personal contact details.

  2. Organisations and groups use work contact details.

You can retrieve or update contact details using dedicated endpoints:

  • 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

Personal Contact Details

Use this endpoint for individual constituents.

  1. Send a request to the personal contact details endpoint.

  2. Update or retrieve address, phone, and email data.

Work Contact Details

Use this endpoint for organisational constituents.

  1. Send a request to the work contact details endpoint.

  2. Update or retrieve organisation contact information.

Other Contact Details

Use this endpoint for additional or alternative contact information.

  1. Send a request to the other contact details endpoint.

  2. Store supplementary contact data as required.

Set Channel Permissions

Channel permissions control how a constituent can be contacted.

Permissions are stored as a single integer value calculated by summing channel values.

Available channel values include:

  1. Do not keep in touch equals 0.

  2. Email equals 2.

  3. Post equals 4.

  4. SMS equals 8.

  5. Phone equals 16.

Unconfirmed channel values are also supported.

📌 Note: If ChannelPermissions is not provided when adding a new constituent, all channels are blocked by default.

Manage Purpose Permissions

Purpose permissions, such as consent for fundraising or newsletters, are managed through dedicated purpose endpoints.

Purpose permissions cannot be set using the ChannelPermissions property.

Update Email Status

You can update the status of a constituent’s email address.

  1. Provide the new status as a quoted string.

  2. Use one of the supported values: Active, Bounced, or Inactive.

⚠️Important: "Bounced": make sure you percent encode (also known as URL encode) the email address - see this article or this article for more information

Work with Tags

Tags can be used to categorise and segment constituents.

Tag creation and assignment are handled using dedicated tag endpoints and rules.

Handle Country Values Correctly

When adding addresses, country values must exist in your Donorfy country list.

If a specified country does not exist, the request fails.

If you do not want to add a country to settings, combine the country name with the county value instead.

Link New Entities to Constituents

When creating new entities such as transactions, you can associate them with a constituent.

Link to an Existing Constituent

Use this option when you already know the constituent.

  1. Set ExistingConstituentId to the constituent ID.

  2. Submit the entity creation request.

Create a New Constituent Automatically

Use this option when the constituent does not yet exist.

  1. Leave ExistingConstituentId empty or omit it.

  2. Provide required constituent details, including ConstituentType.

If the new constituent is an organisation and first or last name is supplied, Donorfy creates a main contact using that name.

⚠️Important:The Donorfy API is a Professional-only feature. Essential subscribers, please contact us to find out more about upgrading.

Related Articles
Connections via the API
Constituent Tags
Lookups and Campaigns Using the API
Manage Gift Aid Declarations Using the API
Use Lists via the API
Did this answer your question?