Quick Start

This guide will help you get up and running making your first Chariot API call in just a few minutes. You will create an access token, get a CID for a nonprofit, and query for the grants of that CID.

🚧

This guide assumes you have already been shared a client_id and client_secret. If that is not the case, please email [email protected].

1. Generate an access token 🔑

First, you'll need to create an access token that lets you access the APIs. Fill in the provided client_id and client_secret to in the preferred code snippet and get an access token.

curl --request POST \
  --url 'https://chariot-sandbox.us.auth0.com/oauth/token' \
  --header 'content-type: application/x-www-form-urlencoded' \
  --data 'audience=https://api.givechariot.com&grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET'

POST https://chariot-sandbox.us.auth0.com/oauth/token
Content-Type: application/x-www-form-urlencoded

audience=https://api.givechariot.com&grant_type=client_credentials&client_id=YOUR_CLIENT_ID&client_secret=YOUR_CLIENT_SECRET

var request = require("request");

var options = { method: 'POST',
  url: 'https://chariot-sandbox.us.auth0.com/oauth/token',
  headers: { 'content-type': 'application/x-www-form-urlencoded' },
  form:
   { client_id: 'YOUR_CLIENT_ID',
     client_secret: 'YOUR_CLIENT_SECRET',
     audience: 'https://api.givechariot.com',
     grant_type: 'client_credentials' }
   };

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

2. Create a CID for a nonprofit 🪪

With your access token, you can now make an API call. We will use Chariot's APIs to create a CID for a nonprofit. A CID stands for "Connect Identifier" and is how Chariot knows how to configure the Chariot Connect flow.

In order to create a CID for a nonprofit, we need to provide the nonprofit's ID. There are two ways to get a nonprofit's ID, Get Nonprofit by EIN and Create Nonprofit.

Get Nonprofit by EIN 🔎

First, we need to check if the nonprofit is in the Chariot system. We do this by providing the nonprofit's EIN number and calling the Get nonprofit by EIN endpoint. Run the following command to try it out! Remember to add your access token from step 1 and replace EIN_NUMBER with a real EIN number. 

curl --request GET \
     --url https://sandboxapi.givechariot.com/v1/nonprofit/EIN_NUMBER \
     --header 'accept: application/json' \
     --header 'authorization: Bearer ACCESS_TOKEN_FROM_STEP_1_HERE'

const options = {
  method: 'GET',
  headers: {accept: 'application/json', authorization: 'Bearer YOUR_TOKEN_FROM_STEP_1_HERE'}
};

fetch('https://sandboxapi.givechariot.com/v1/nonprofit/EIN_NUMBER', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

If you received a record back, then great! Save down the nonprofit's id for when we create a Connect. Otherwise, we need to create a nonprofit record for this EIN.

Create Nonprofit :hospital:

The Create nonprofit endpoint registers a new nonprofit or returns 201 if that nonprofit already exists in the Chariot system.

To do so, we must provide a nonprofit's EIN number and information about a user at that nonprofit that Chariot can contact for customer support.

Below are a few examples of different implementations. Modify the user object, ein field, and access token from step 1 before making the request. 

curl --request POST \
     --url https://sandboxapi.givechariot.com/v1/nonprofits \
     --header 'accept: application/json' \
     --header 'authorization: Bearer YOUR_TOKEN_FROM_STEP_1_HERE' \
     --header 'content-type: application/json' \
     --data '
{
     "user": {
          "email": "[email protected]",
          "phone": "3051234321",
          "firstName": "Han",
          "lastName": "Solo"
     },
     "ein": "123456789"
}
'

const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer <YOUR_TOKEN_FROM_STEP_1_HERE>'
  },
  body: JSON.stringify({
    user: {
      email: '[email protected]',
      phone: '3051234321',
      firstName: 'Han',
      lastName: 'Solo'
    },
    ein: '123456789'
  })
};

fetch('https://sandboxapi.givechariot.com/v1/nonprofits', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Bravo! You have just created a nonprofit in the Chariot system. That nonprofit can now accept DAF payments thanks to you ❤️. Mark down the nonprofit's id and now let's create a Connect for this nonprofit.

Create Connect 🪪

The Create Connect endpoint creates a Connect record or returns 201 if a Connect already exists for this nonprofit in the Chariot system.

To create a Connect, the nonprofit's id must be provided, which you should have from the previous two steps!

Below are a few examples of different implementations. Modify the NONPROFIT_ID query parameter with the nonprofit's id. Don't forget to add the access_token! 

curl --request POST \
     --url 'https://sandboxapi.givechariot.com/v1/connects?nonprofit=NONPROFIT_ID' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer YOUR_TOKEN_FROM_STEP_1_HERE' \
     --header 'content-type: application/json'

const options = {
  method: 'POST',
  headers: {
    accept: 'application/json',
    'content-type': 'application/json',
    authorization: 'Bearer YOUR_TOKEN_FROM_STEP_1_HERE'
  }
};

fetch('https://sandboxapi.givechariot.com/v1/connects?nonprofit=NONPROFIT_ID', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));

Amazing! You can now start Integrating Connect to build a front end and start receiving grants for this nonprofit.

3. List Grants 💵

Once you have submitted a couple of grants through Chariot Connect, you will be able to hit Chariot's APIs to get the grant data.

The List Grants endpoint lists all the grants for a particular CID.

To list grants, the Connect's API key must be provided. But what the heck is a Connect's API Key?? Since the CID is client-facing, it is not private. We do not want anyone with the CID to be able to query all the data generated by that CID. Therefore, this request requires an API Key. Get it by calling the Get Connect route.

Now we are ready to list grants. Below are a few examples of different implementations. Modify the API_KEY with the Connect's API key. Don't forget to add the access_token! 

curl --request GET \
     --url 'https://sandboxapi.givechariot.com/v1/grants?pageLimit=10' \
     --header 'accept: application/json' \
     --header 'authorization: Bearer YOUR_TOKEN_FROM_STEP_1_HERE' \
     --header 'x-chariot-api-key: API_KEY'

const options = {
  method: 'GET',
  headers: {
    accept: 'application/json',
    authorization: 'Bearer YOUR_TOKEN_FROM_STEP_1_HERE',
    'x-chariot-api-key': 'API_KEY'
  }
};

fetch('https://sandboxapi.givechariot.com/v1/grants?pageLimit=10', options)
  .then(response => response.json())
  .then(response => console.log(response))
  .catch(err => console.error(err));