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 and Starter 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
Important
The current rate limit is set to be 301 requests per minute which should be ample to recall and insert all of the data in to Donorfy and not impact normal use of the Donorfy API for yourself and other users.
If you exceed this limit, the API will be disabled temporarily resulting in a 400 error message. We will contact the Donorfy account Main Contact to discuss the best usage of the API.
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.
ChangeLog
Changes made to Constituent Contact information, permissions, and Timeline entries can be found within the Changelog on the Timeline - the username who made the change would be that which was used as the name for the relevant API (as per the API authentication settings).