Getting Started

Introduction

Swiftaid is a service that fully automates the process of creating Gift Aid declarations on behalf of donors and filing Gift Aid charitable claims with HMRC on behalf of charities.

Swiftaid is designed to sit alongside and complement a charitable giving service, so if you are currently building a solution that allows people to give money to charity then integrating the Swiftaid service will unlock the ability for your eligible users to boost the money received by good causes they are choosing to donate to at no cost to themselves.

Swiftaid community (opens new window)

Join our Swiftaid community, we're always happy to help and answer any questions.

Getting Started

1. Reach out to dev support to get a sandbox account.
2. Head over to our active API specification where you can use your sandbox keys to try out the API.

Authentication

The Swiftaid API implements the OAuth 2.0 (opens new window) client credentials (opens new window) flow for authorising other applications to interact with it based on them having valid client id and client secret values.

DANGER

The client credentials flow is designed for backend to backend interaction and it is critical that client secrets are never included in public (mobile or browser-based) applications.

How it works

1. Your application authenticates with the Swiftaid Authorization Server using its Client ID and Client Secret (/oauth2/token endpoint).
2. The Swiftaid Authorization Server validates your Client ID and Client Secret.
3. The Swiftaid Authorization Server responds with an Access Token.
4. Your application can use the Access Token to call the Swiftaid API.
5. The Swiftaid API responds with requested data.

Example authorisation flow

Request Token

To access the Swiftaid API, you must request an Access Token for it. To do so, you will need to POST to the token URL.

curl --request POST \
  --url 'https://auth.streeva.com/oauth2/token' \
  -u client_id:client_secret \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data grant_type=client_credentials \
  --data audience=https://sandbox.swiftaid.co.uk/integrations/v1 \
  --data 'scope=read:donor create:donation create:donor'

Parameters

Parameter Name	Description
grant_type	Set this to "client_credentials".
client_id	Your application's Client ID (encoded in to the authorization header).
client_secret	Your application's Client Secret (encoded in to the authorization header).
audience	The audience for the token, which is the Swiftaid API. The example includes the address for the sandbox instance of the API.
scope	The access scopes for the token.

Authorization Header The Streeva auth service expects client authentication using the HTTP Basic auth header. The above cURL example is using the -u parameter which is doing this for you, functionally it is constructing a header of the form "Authorization: Basic b64encode(client_id:client_secret)" which could technically be replaced with the following:

--header "Authorization: Basic $(echo client_id:client_secret | base64)"

Response

If all goes well, you'll receive an HTTP 200 response with a payload containing access_token, token_type, and expires_in values:

{
 "access_token":"eyJz93a...k4laUWw",
 "token_type":"Bearer",
 "expires_in":86400
}

Call the Swiftaid API

To call the Swiftaid API from your application, you must pass the retrieved Access Token as a Bearer token in the Authorization header of your HTTP request.

curl --request GET \
  --url 'https://sandbox.swiftaid/co.uk/integrations/v1/donors?type=email&value=bruce.banner@example.com' \
  --header 'authorization: Bearer ACCESS_TOKEN' \
  --header 'content-type: application/json'