Introduction

The Give.io REST API utilizes predictable, resource-oriented endpoints, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs. JSON is returned by all API responses, including errors.

At this time, public registration for Developer Keys is not available.

Requirements

To use the latest version of the REST API you must be:

• Using a valid API Key
• Accessing the API over HTTPS

The base API is located here:

https://api.give.io/v1/

Response Structure

Give.io sends its API responses in a response wrapper along with additional information, such as whether or not the request was successful, any error messages if it was not, or pagination links for large collections. If the endpoint you requested returns any data, it will be in the response object's data property.

Response Object example:

{
  "data" : [
    {...},
    {...}
  ],
  "success" : "true",
  "links": {
    "first": "https://api.give.io/v1/donors?page=1",
    "last": "https://api.give.io/v1/donors?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://api.give.io/v1/donors",
    "per_page": 15,
    "to": 10,
    "total": 10
  }
}

Errors

Occasionally you might encounter errors when accessing the API. There are four possible types:

Error Code	Meaning
400	Bad Request -- Invalid requests, such as using an unsupported HTTP method will result in 400 Bad Request.
401	Unauthorized -- Authentication or permission errors, such as incorrect API keys will result in 401 Unauthorized.
403	Forbidden -- The request is hidden for administrators only.
404	Not Found -- Requests to resources that don't exist or are missing required parameters will result in 404 Not Found.
429	Too Many Requests -- Request too large. Slow down!
500	Internal Server Error -- Requests that cannot be processed due to a server error will result in 500 Internal Server Error.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.

400 Bad Request example:

{
  "data" :     {
    "code" : "giveio_api_unsupported_method",
    "message" : "Unsupported request method"
  },
  "success" : "false"
}

401 Unauthorized example:

{
  "data" :     {
    "code" : "giveio_api_authentication_error",
    "message" : "Consumer Key is invalid"
  },
  "success" : "false"
}

404 Not Found example:

{
  "data" :     {
    "code" : "giveio_api_invalid_order",
    "message" : "Invalid order"
  },
  "success" : "false"
}

500 Internal Server Error example:

{
  "data" :     {
    "code" : "giveio_api_invalid_handler",
    "message" : "The handler for the route is invalid"
  },
  "success" : "false"
}

Errors return both an appropriate HTTP status code and response object which contains a code and message attribute. If an endpoint has any custom errors, they are documented within that endpoint.

HTTP Verbs

The API uses the appropriate HTTP verb for each action:

Verb	Description
HEAD	Can be used for any endpoint to return just the HTTP header information
GET	Used for retrieving resources
PUT	Used for updating resources
POST	Used for creating resources
DELETE	Used for deleting resources

Tools

• Postman - A multi platform REST API GUI client (using Google Chrome or installing the app on Mac OS X or Windows).
• CocoaRestClient - A free, easy to use Mac OS X GUI client for interacting with the API, most useful when your test store has SSL enabled.
• Paw HTTP Client - Another excellent HTTP client for Mac OS X.
• RESTClient, a debugger for RESTful web services - Free Firefox add-on.
• Advanced REST client - Free Google Chrome extension.

Authentication

Client API Key

To make a successful request with both a client API Key and an Authenticated JWT, use this code:

# With shell, you can just pass the correct headers with each request
curl https://api.give.io/v1/<endpoint>
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

// Javascript Examples Coming Soon

Make sure to replace <API_KEY> with your valid API key.

Give.io uses API Client keys to allow access to the API, and JSON Web Tokens for individual user authentication. During beta development, public access is not available.

Give.io expects the API Client key to be included in all API requests to the server in a header that looks like the following:

give-client: <API_KEY>

User authentication

JSON Web Token (JWT) is an open standard (RFC 7519) that defines a compact and self-contained way for securely transmitting information between parties as a JSON object. This information can be verified and trusted because it is digitally signed by the originating server.

Give.io uses these tokens for user authentication within the application. You will need to pass this token with each request as a typical Authentication header. You can request this initial token from the authentication endpoint with an Authorization header that contains the word Basic word followed by a space and a base64-encoded string username:password.

To request an Authenticated JWT, use this code:

curl https://api.give.io/v1/authenticate/token
  -H "give-client: <API_KEY>"
  -H "Authorization: Basic dXNlcm5hbWU6cGFzc3dvcmQ="

The above request returns a basic JSON response object containing your new token:

{
    "success": true,
    "data": {
        "token": "eyJ0eXAiOiJKV1QiLCJhbGciOiJIUzI1NiJ9.eyJzdWIiOjQsImlzcyI6Imh0dHA6Ly9sb2NhbGhvc3Q6ODg4OC9tZXNhbi1sYXJhdmVsLWp3dC1hdXRoZW50aWNhdGlvbjIvcHVibGljL2FwaS9sb2dpbiIsImlhdCI6MTUwMjU2NzE5MSwiZXhwIjoxNTAyNTcwNzkxLCJuYmYiOjE1MDI1NjcxOTEsImp0aSI6IkVIVWV6dVp0UDhhSmQ2QUUifQ.OjlzNKmTItphLs29B7WsFstmrtgDW2qE7gv26LcR3Og"
    }
}```

Index

By default, the API provides information about all available endpoints on the site. Authentication is not required to access the API index.

HTTP request

GET https://api.give.io/v1/

curl https://api.give.io/v1/
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

Users

User Object

Property	Description
ID	Unique ID
first_name	First Name
last_name	Last Name
email	Valid Contact Email
organizations	A collection of organizations that this user belongs to
avatar	URL to User's Avatar image
created_at	ISO8601 Timestamp of Account Creation
updated_at	ISO8601 Timestamp of the last account update
last_login	ISO8601 Timestamp of the last valid login

Roles

Role	Permissions
Owner	TBD
Administrator	TBD
Manager	TBD
Developer	TBD
Analyst	TBD
Support	TBD

Get All Users

$ curl https://api.give.io/v1/users
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

// Javascript Examples Coming Soon

The above request returns a collection of JSON objects structured like this:

[
  {
    "ID": 862,
    "first_name": "John",
    "last_name": "Doe",
    "email": "jdoe@email.com",
    "organizations": [
      {
        "ID": 234,
        "name": "",
        "role": "owner"
      }
    ],
    "avatar": "https://avatars.give.io/862/240.jpg",
    "created_at": "2018-07-30 13:28:32",
    "last_login": "2018-08-12 08:04:00"
  }
]

This endpoint retrieves all users as a paginated collection.

HTTP Request

GET https://api.give.io/v1/users

Query Parameters

Parameter	Default	Description
limit	25	Limit number of results returned per page.
page	1	Used along with limit to determine offset.

Get Users From Organization

$ curl https://api.give.io/v1/organization/234/users
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

// Javascript Examples Coming Soon

The above request returns a collection of JSON objects structured like this:

[
  {
    "ID": 862,
    "first_name": "John",
    "last_name": "Doe",
    "email": "jdoe@email.com",
    "organizations": [
      {
        "ID": 234,
        "name": "",
        "role": "owner"
      }
    ],
    "avatar": "https://avatars.give.io/862/240.jpg",
    "created_at": "2018-07-30 13:28:32",
    "last_login": "2018-08-12 08:04:00"
  }
]

This endpoint retrieves all users belonging to a given organization as a paginated collection.

HTTP Request

GET https://api.give.io/v1/organization/<ID>/users

Query Parameters

Parameter	Default	Description
limit	25	Limit number of results returned per page.
page	1	Used along with limit to determine offset.

Get a Specific User

$ curl https://api.give.io/v1/users/2
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

// javascript

The above command returns JSON structured like this:

{
  "ID": 862,
  "first_name": "John",
  "last_name": "Doe",
  "email": "jdoe@email.com",
  "organizations": [
    {
      "ID": 234,
      "name": "",
      "role": "owner"
    }
  ],
  "avatar": "https://avatars.give.io/862/240.jpg",
  "created_at": "2018-07-30 13:28:32",
  "last_login": "2018-08-12 08:04:00"
}

This endpoint retrieves a specific user.

HTTP Request

GET https://api.give.io/v1/users/<ID>

Create a New User

Create a new user within Give.io. Data must be sent as JSON.

# As a data string
$ curl https://api.give.io/v1/users
  -X POST
  -d '{"first_name":"John", "last_name":"Doe", "email": "jdoe@email.com", "password": "ABC123"}'
  -H "Content-Type: application/json"
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

# From a file
$ curl https://api.give.io/v1/users
  -X POST
  -d "@data.json"
  -H "Content-Type: application/json"
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

// Javscript

HTTP Request

POST https://api.give.io/v1/users

Query Parameters

Parameter	Required	Description
email	YES	Valid Email Address
password	YES	User's initial password
first_name	YES	User's First Name
last_name	NO	User's Last Name
organization	NO	ID of initial organization
role	NO	Initial Permissions Role, ignored if organization is not set

Update a User

Update a user's profile details. Data must be sent as JSON. Data should be sent as a POST request, not a PUT request. Only the fields that are passed are evaluated. To remove a field, pass an empty string as the property value.

# As a data string
$ curl https://api.give.io/v1/users/2
  -X POST
  -d '{"first_name":"John", "last_name":"Doe", "email": "jdoe@email.com", "password": "ABC123"}'
  -H "Content-Type: application/json"
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

# From a file
$ curl https://api.give.io/v1/users/2
  -X POST
  -d "@data.json"
  -H "Content-Type: application/json"
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

// Javscript

HTTP Request

POST https://api.give.io/v1/users/<ID>

Upload an Avatar

Uploads a file to the system to be used as a User Avatar, or profile image.

$ curl https://api.give.io/v1/users/2/avatar
  -X POST
  -d "@john-headshot.jpg"
  -H "Content-Type: application/json"
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

// Javscript

The above command returns a User object, with an updated avatar property:

{
  "ID": 862,
  "first_name": "John",
  "last_name": "Doe",
  "email": "jdoe@email.com",
  "organizations": [
    {
      "ID": 234,
      "name": "",
      "role": "owner"
    }
  ],
  "avatar": "https://avatars.give.io/862/240.jpg",
  "created_at": "2018-07-30 13:28:32",
  "last_login": "2018-08-12 08:04:00"
}

HTTP Request

POST https://api.give.io/v1/users/<ID>/avatar

Delete a Specific User

$ curl https://api.give.io/v1/users/2
  -X DELETE
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

// Javscript

The above command returns the user as it existed before deletion:

{
  "ID": 862,
  "first_name": "John",
  "last_name": "Doe",
  "email": "jdoe@email.com",
  "organizations": [
    {
      "ID": 234,
      "name": "",
      "role": "owner"
    }
  ],
  "avatar": "https://avatars.give.io/862/240.jpg",
  "created_at": "2018-07-30 13:28:32",
  "last_login": "2018-08-12 08:04:00",
  "deleted_at": "2018-08-15 11:14:58"
}

This endpoint deletes a specific user from the system entirely. The user will be removed from any organizations they belong. This call will return an error if the user has an Owner role in any organization that has not been removed first.

HTTP Request

DELETE https://api.give.io/v1/users/<ID>

Donors

Get All Donors

curl https://api.give.io/v1/users/2/donors
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

// Javascript Examples Coming Soon

The above request returns a collection of JSON objects structured like this:

[
  {
    "ID": 1,
    "first_name": "",
    "middle_initial": "",
    "last_name": "",
    "title": "",
    "company_name": "",
    "primary_email": "",
    "created_at": "",
    "donation_count": "",
    "donation_value": "",
    "additional_emails": [],
    "subscriptions": [],
    "donations": [],
    "addresses": []
  }
]

This endpoint retrieves all donors tied to an account.

HTTP Request

GET https://api.give.io/v1/users/<ID>/donors

Get a Specific Donor

curl https://api.give.io/v1/donors/2
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

// javascript

The above command returns JSON structured like this:

{
  "ID": 8,
  "first_name": "Jake",
  "middle_initial": "E",
  "last_name": "Smith",
  "title": "Mr.",
  "email": "jakes@email.org",
  "created_at": "22018-07-30 13:28:32",
  "purchase_count": "0",
  "purchase_value": "0",
  "subscriptions": [],
  "donations": []
}

This endpoint retrieves a specific donor.

HTTP Request

GET https://api.give.io/v1/donors/<ID>

Create a Donor

Manually create a new Donor within Give.io. Data must be sent as JSON. A donor object would also be created when a donation or subscription is created.

$ curl https://api.give.io/v1/donors
  -X POST
  -d '{"first_name":"John", "last_name":"Doe", "email": "jdoe@email.com"}'
  -H "Content-Type: application/json"
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

// Javscript

HTTP Request

POST https://api.give.io/v1/donors

Query Parameters

Parameter	Required	Description
email	YES	Valid Email Address
first_name	YES	Donor's First Name
middle_initial	NO	Donor's Middle Initial
last_name	YES	Donor's Last Name
title	NO	Donor's preferred title (eg. Mr, Mrs, Dr, etc)

Update a Donor

Update a donor's details. Data must be sent as JSON. Data should be sent as a POST request, not a PUT request. Only the fields that are passed are evaluated. To remove a field, pass an empty string as the property value.

$ curl https://api.give.io/v1/donors/8
  -X POST
  -d '{"first_name":"Jake", "last_name":"Smith", "email": "jsmith@email.com"}'
  -H "Content-Type: application/json"
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

// Javscript

HTTP Request

POST https://api.give.io/v1/donors/<ID>

Delete a Specific Donor

$ curl https://api.give.io/v1/donors/8
  -X DELETE
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

// Javscript

The above command returns the donor as it existed before deletion:

{
  "ID": 8,
  "first_name": "Jake",
  "middle_initial": "E",
  "last_name": "Smith",
  "title": "Mr.",
  "email": "jakes@email.org",
  "created_at": "22018-07-30 13:28:32",
  "deleted_at": "2018-08-15 11:14:58",
  "purchase_count": "0",
  "purchase_value": "0",
  "subscriptions": [],
  "donations": []
}

This endpoint deletes a specific donor from the system entirely. This call will return an error if the donor has any subscriptions or donations that have not been removed first.

HTTP Request

DELETE https://api.give.io/v1/users/<ID>

Donations

Get All Donations

curl https://api.give.io/v1/donations
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

// Javascript Examples Coming Soon

The above request returns a collection of JSON objects structured like this:

[{
  "ID": 98,
  "campaign_ID": 67,
  "created_at": "2018-09-18 11:14:58",
  "customer": 8,
  "transaction_ID": "ch_1Bqa2P2eZvKYlo2CVaJa8DbC",
  "status": "succeeded",
  "amount": 100,
  "currency": "usd",
  "description": "",
  "metadata": { },
  "receipt_email": "jsmith@email.com"
}]

This endpoint retrieves all donations.

HTTP Request

GET https://api.give.io/v1/donations

Get All Donations by Donors

curl https://api.give.io/v1/donor/8/donations
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

// Javascript Examples Coming Soon

The above request returns a collection of JSON objects structured like this:

[{
  "ID": 98,
  "campaign_ID": 67,
  "created_at": "2018-09-18 11:14:58",
  "customer": 8,
  "transaction_ID": "ch_1Bqa2P2eZvKYlo2CVaJa8DbC",
  "status": "succeeded",
  "amount": 100,
  "currency": "usd",
  "description": "",
  "metadata": { },
  "receipt_email": "jsmith@email.com"
}]

This endpoint retrieves all donations tied to a specific donor.

HTTP Request

GET https://api.give.io/v1/donors/<ID>/donations

Get All Donations by Campaign

curl https://api.give.io/v1/campaign/67/donations
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

// Javascript Examples Coming Soon

The above request returns a collection of JSON objects structured like this:

[{
  "ID": 98,
  "campaign_ID": 67,
  "created_at": "2018-09-18 11:14:58",
  "customer": 8,
  "transaction_ID": "ch_1Bqa2P2eZvKYlo2CVaJa8DbC",
  "status": "succeeded",
  "amount": 100,
  "currency": "usd",
  "description": "",
  "metadata": { },
  "receipt_email": "jsmith@email.com"
}]

This endpoint retrieves all donations tied to a specific campaign.

HTTP Request

GET https://api.give.io/v1/campaigns/<ID>/donations

Get a Specific Donation

curl https://api.give.io/v1/donations/98
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

// Javascript Examples Coming Soon

The above request returns a JSON object structured like this:

{
  "ID": 98,
  "campaign_ID": 67,
  "created_at": "2018-09-18 11:14:58",
  "customer": 8,
  "transaction_ID": "ch_1Bqa2P2eZvKYlo2CVaJa8DbC",
  "status": "succeeded",
  "amount": 100,
  "currency": "usd",
  "description": "",
  "metadata": { },
  "receipt_email": "jsmith@email.com"
}

This endpoint retrieves a specific donation transaction.

HTTP Request

GET https://api.give.io/v1/donations/<ID>

Create a Donation

This endpoint creates a new donation transaction. If a donor ID is not supplied then a new donor will be created.

HTTP Request

POST https://api.give.io/v1/donations

Update a Donation

This endpoint updates a specific donation transaction.

HTTP Request

POST https://api.give.io/v1/donations/<ID>

Delete a Specific Donation

This endpoint deletes a specific donation transaction.

HTTP Request

DELETE https://api.give.io/v1/donations/<ID>

Subscriptions

Get All Subscriptions

curl https://api.give.io/v1/subscriptions?filter=user&ID=2
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

// Javascript Examples Coming Soon

The above request returns a collection of JSON objects structured like this:

[
  {
    "ID": 1,
    "donor": 2,
    "frequency": "",
    "donation_count": "",
    "initial_amount": "",
    "recurring_amount": "",
    "subscription_changes": [],
    "status": "",
    "notes": [],
    "expiration_date": "",
    "created_at": "",
    "updated_at": ""
  }
]

This endpoint retrieves all subscriptions tied to a donor, user, organization, chapter or campaign.

HTTP Request

GET https://api.give.io/v1/subscriptions

Query Parameters

Parameter	Default	Description
filter	NULL	How to refine the results returned. Possible values: 'donor', 'user', 'organization', or 'chapter'
ID	0	The ID of the filter object used to limit results.

Get a Specific Subscription

Create a Subscription

Update a Subscription

Delete a Specific Subscription

Campaigns

Get All Campaigns

curl https://api.give.io/v1/campaigns
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

// Javascript Examples Coming Soon

The above request returns a collection of JSON objects structured like this:

[
  {
    "ID": 1,
    "title": "",
    "created_at": "",
    "last_modified": "",
    "type": "standard",
    "start_at": "",
    "end_at": "",
    "has_end": true,
    "has_landing": false,
    "landing_url": "",
    "goal": {
      "enabled": true,
      "type": "amount",
      "value": "1000",
      "progress_color": "",
      "auto_close": true
    },

    "terms": {
      "enabled": true,
      "label": "Terms & Conditions",
      "content": ""
    }
  }
]

This endpoint retrieves all users.

HTTP Request

GET https://api.give.io/v1/campaigns/

Get a Specific Campaign

GET https://api.give.io/v1/campaigns/<ID>/

This endpoint retrieves a specific campaign.

curl https://api.give.io/v1/campaigns/
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

HTTP Request

GET https://api.give.io/v1/campaigns/ID/

Create a New Campaign

Create a new campaign within Give.io. Data must be sent as JSON.

curl https://api.give.io/v1/campaigns/
  -H "give-client: <API_KEY>"
  -H "Authorization: Bearer <token>"

HTTP Request

POST https://api.give.io/v1/campaigns/

Parameter	Required	Description
title	Yes	"Campaign "

Update a Campaign

Delete a Specific Campaign

Organizations

Get All Organizations

Get a Specific Organization

Create a Organization

Update a Organization

Delete a Specific Organization