The Donorfy API allows websites, other systems and so on to retrieve and send data to Donorfy.

This is an advanced feature - you will need programming skills or help from a Donorfy partner to make use of this feature.

Requirements

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

Allowing Access via the API

First, you need to ask Donorfy Support to enable the API on your system. To do this please create a support request (ticket).

Note that Cross-Origin Resource Sharing CORs is not supported by the Donorfy API this is for security reasons to help keep the data in your Donorfy safe and secure.

We expect people to use the API from server-side code where CORs is not a concern - this has the added benefits of allowing API request to be locked down to known IP addresses and your API access keys can be safely stored server-side and do not have to be available to code that runs in the browser.

To allow access via the API you have to grant permission - go into Settings and find API Settings, click on the Add Permission button - from the form displayed enter the following:

• Name - enter a name for the permission - e.g. Website - this helps you recognise who is using this permission
• IP Address start & end - this is the range of IP addresses that are permitted to send or receive data to the API - this reduces the risk of unauthorised access to your data
• Press Save

The permission will then be displayed in the list of granted permissions - an 'Access Key' will have been generated for the permission.

You can change the name and IP Address start & end values for a permission.

If you delete a permission then access to the API will not be allowed.

Using the API

The API  

• Is a REST api
• The base url is https://data.donorfy.com/api/v1/<your api key>/ - see this article for help finding your api key - e.g. if your API key was ABCDEF the url would be https://data.donorfy.com/api/v1/ABCDEF/ 
• Only https access is allowed
• Uses basic authentication - note that
  • the user name can be any name you want to use - this name will be recorded in the change log against operations performed - this allows you to use the api permission for multiple users - e.g. at an agency - if required
  • the access key should be used as the password 
  • the user name and password should be passed to the api as a correctly formed authorization header
• Details for the endpoints the API has can be found at the api documentation page here - the information in the knowledge base articles should be used alongside the api documentation page
• JSON is used for data exchange - your HTTP headers must include Content-Type application/json
• Use these HTTP verbs
  • GET to retrieve data
  • POST to add data
  • PUT to update data - note that 
    • when updating existing data you can omit properties you don't want to change e.g. if you were updating a constituent and only wanted to change their last name - your request would just include the last name property and its new value, any other existing data e.g. title, first name etc would not be changed from their existing values
    • To clear an existing date value pass the value 0001-01-01 as the date
  • DELETE to delete data
  • The properties allowed or returned by the verbs above vary depending on the entity you are working with i.e. there are some properties that you can
    • set when adding an entity but not update
    • retrieve but not change
• Will ignore
  • unknown properties - i.e. if when adding or updating data your request (i.e. POST or PUT) contains a unknown property name the unknown property will be ignored - but any valid properties will still be handled by the request
  • Properties containing invalid values - e.g. a bad date - are ignored 
• Uses Universally Unique Identifiers or Guids for entity ids- e.g. ConstituentId - these are passed to the API as strings 
• Dates should be formatted as follows
  • A date without a time should be formatted like 2017-08-02
  • A date and timeshould be formatted like 2017-08-02T08:36:31.427Z
• Boolean properties should be set using true or false e.g. "NoGiftAid": true
• Numbers can optionally include 2 decimal places

For more information about working with other types of data - such as Constituents - i.e. people and organisations, Transactions - i.e. one off payments or donations, Recurring Payment Instructions - i.e. recurring payments or donations - see the API section of the knowledgebase

Successful Calls

If your call to the api is processed successful an Http 200 - OK response will be returned - depending on the operation you are performing the body of the response will contain for

• Get operations - the entity you requested
• Add operations - the id of the entity you added - e.g. transactionId and the Id of any associated constituent - whether it was added or you linked to an existing constituent

Errors

If there is an error we will return a Http error typically

• 400 - Bad Request - if
  • your request is badly formed - e.g. invalid Json 
  • If your call to the api results in an error - e.g. there is a data validation problem - an message will be returned 
• 404 - Not Found - the entity with id you passed could not be found

Getting Started with the API

The api documentation page lists the endpoints available and the properties that can be used with an endpoint

Testing and troubleshooting the API

To make test calls and to troubleshoot your code - please see this article.