Overview

The Donorfy API allows web sites, 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.

The Basics

Allowing Access via the API

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

  • Constituents - i.e. people and organisations - see this
  • Transactions - i.e. one off payments or donations - see this
  • Recurring Payment Instructions - i.e. recurring payments or donations - see this

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 api documentation page lists the endpoint available and the properties that can be used with an endpoint

To make test calls you can download and use Postman - the Postman documentation will help you get started, but you will need to

  • set up permission as described above
  • use basic authentication header containing the user name and the access key 
  • include the Content-Type application/json header

 

 

Have more questions? Submit a request

Comments

Powered by Zendesk