Welcome

Welcome to the Divvy API! You can use our API to extend and enhance Divvy into your internal systems and workflows. This API is made using GraphQL. The sections below will help you get up and running with GraphQL and our API.

Divvy's API can also be explored interactively using the Apollo Studio Explorer where you can build queries and mutations, and see the responses from the API.

Endpoint & Authentication

The Divvy GraphQL API endpoint can be found at:

# Production GraphQL Endpoint
https://api.divvy.co/graphql

All requests require a valid access token. Tokens can be generated by visiting your user settings page in the main Divvy application.

Include your token as a x-divvy-api-token header on all API requests. In addition, the x-api-version header must be passed with the value of 2 :

# Required Headers
x-api-version: 2
x-divvy-api-token: <YOUR API TOKEN>

Below is an example of making a GraphQL query request using curl:

curl --request POST \
    --url https://api.divvy.co/graphql \
  --header 'Content-Type: application/json' \
  --header 'x-api-version: 2' \
  --header 'x-divvy-api-token: <YOUR API TOKEN HERE>' \
  --url https://api.divvy.co/graphql \
  --data '{"query":"{ currentUser { company { budgets(first: 2) { edges { node { name } } } } } }"}'

GraphQL Basics

In GraphQL, all CRUD (Create, Read, Update, Delete) operations are performed by sending POST HTTP requests to a single endpoint. The endpoint for the Divvy API is https://api.divvy.co/graphql. This is different from a REST API where you would have many endpoints using various HTTP methods to retrieve and update data from a server.

There are two types of operations in GraphQL: queries and mutations. Both are performed by sending a POST request along with a query string using the JSON content type. We will discuss each below.

Queries

Queries are used for accessing data and are most equivalent to the GET request used in REST APIs. It is a read-only operation; you cannot create, update, or delete data using queries. (To perform these actions, see the Mutations section below).

Here is an example of what a typical query for fetching budget data looks like:

query OptionalQueryName {
  currentUser {
    company {
      budgets(first: 2) {
        edges {
          node {
            id
            name
          }
        }
      }
    }
  }

Let’s walk through the query above:

1. Queries begin with the query keyword. An optional name can be provided and in this case we use OptionalQueryName as our name.
2. We first begin by selecting the currentUser root query type. This fetches data about the API user making the request (based on the API key in the request header). This is the primary way to fetch data about your user and all data related to your user in the system.
3. We then select the company field off of the user. The company field contains all data pertaining to the company to which you belong, and is the best way to get company-wide data such as budgets, transactions, and other company users.
4. Within the company field we select budgets, which will select a list of all budgets within the company. The parenthesis with first: 2 after the budgets field is a query argument that is asking for the first two budgets from the list.
5. Because we are querying for a list of items (budgets), we then specify the edges field, which is how we will select for the list of budgets in the company.
6. The actual data for each budget will be contained in an object under the node field, so that field must be added next.
7. Finally, we select the id and name fields within each budget object so that we get only those two back in our response.

While there are many more fields that could have been added to the query (for instance, each budget node contains more fields about the budget) we only asked for name and id. This makes GraphQL more flexible and efficient in that you only get data back that the query asks for, preventing under-fetching or over-fetching data.

This query results in the JSON response below:

{
  "data": {
    "currentUser": {
      "company": {
        "budgets": {
          "edges": [
            {
              "node": {
                "id": "QnVkZ2V0OjI2NjQ1MA==",
                "name": "Accounting"
              }
            },
            {
              "node": {
                "id": "QnVkZ2V0OjMyNjM1MQ==",
                "name": "Administration"
              }
            }
          ]
        }
      }
    }
  }
}

Mutations

Mutations allow you to create, update, and delete data. They are structured similar to queries:

mutation {
    createVirtualCardForBudget(input: {
        amount: 1000,
        budgetId: "QnVkZ2V0OjI2NjQ1MA==",
        ownerId: "VXNlcjoxMzQ1NQ==",
        name: "New Card",
        type: "RECURRING"
    }) {
        newCardEdge {
            expirationDate
            id
            name
            lastFour
            type
            user {
                id
            }
        }
    }
}

1. Similar to the query keyword, we must specify the mutation keyword.
2. The name of the mutation being performed is specified next. In this case, the mutation name is createVirtualCardForBudget.
3. This mutation takes an argument called input, which in this case is an object containing a number of properties (some are required, some are not). Here we pass in the IDs and other data needed to create a new virtual card.
4. Mutations also contain a query block after the arguments, in which fields can be queried for in response to the mutation succeeding. For this mutation, we want to retrieve relevant data about the newly created card back, which is in the newCardEdge field.

This mutation results in the response below:

{
  "data": {
    "createVirtualCardForBudget": {
      "newCardEdge": {
        "node": {
          "expirationDate": "09/25",
          "id": "Q2FyZDo3NTcyMTI0",
          "lastFour": "0123",
          "name": "New Card",
          "type": "RECURRING",
          "user": {
            "id": "VXNlcjoxMzQ1NQ=="
          }
        }
      }
    }
  }
}

The currentUser Query

The main root query type of the Divvy API is currentUser. This query returns the User type, which contains all the data related to your user account in the Divvy system. This includes personal information (e.g. your name, email, phone number, etc) as well as your company data (e.g. budgets, transactions, other users, etc).

The company data you can access is determined by your user permission levels and is a subset of what you are able to see and do in the web application. For example, if you are a company admin who can see all budgets in your organization using the web application, you can also query for all the same budgets using the API.

The best way of accessing your company data is by querying for the company field on currentUser. This field returns the Company type, which contains all company-level fields described above. Below is an example query that queries for the budgets, transactions, and users fields, with placeholder fragments indicating subsequent fields on those objects can be selected.

query {
  currentUser {
    company {
      budgets {
        ...BudgetConnectionFragment
      }
      transactions {
        ...TransactionConnectionFragment
      }
      users {
        ...UserConnectionFragment
      }
    }
  }
}

Pagination & Sorting

In order to paginate through a list of results, we need to use the cursor field available on any Edge type and provide that as a query argument to a query. Let’s take the same example of querying for budgets that we looked at above and see how to paginate the results.

First, we will start off by querying for our list of budgets, limiting to two results and this time adding the cursor field to our query:

query {
  currentUser {
    company {
     budgets(first: 2) {
       pageInfo {
         startCursor
         endCursor
         hasNextPage
         hasPreviousPage
       }
       edges {
         cursor
         node {
           id
           name
         }
       }
     }
    }
  }
}

Note how we also query for the pageInfo field on budgets . This provides data related to the page results specific to our query.

We will then receive the following response, which includes the cursor data we queried for:

{
  "data": {
    "currentUser": {
      "company": {
        "budgets": {
          "edges": [
            {
              "cursor": "YXJyYXljb25uZWN0aW9uOjA=",
              "node": {
                "id": "QnVkZ2V0OjI2NjQ1MA==",
                "name": "Accounting"
              }
            },
            {
              "cursor": "YXJyYXljb25uZWN0aW9uOjE=",
              "node": {
                "id": "QnVkZ2V0OjMyNjM1MQ==",
                "name": "Administration"
              }
            }
          ],
          "pageInfo": {
            "endCursor": "YXJyYXljb25uZWN0aW9uOjE=",
            "hasNextPage": true,
            "hasPreviousPage": false,
            "startCursor": "YXJyYXljb25uZWN0aW9uOjA="
          }
        }
      }
    }
  }
}

Within each budget object, we now have a cursor ID that indicates where in the list that budget object resides. We also receive our pageInfo data, which tells us the start and end cursors for this particular query result. Because we only queried for 2 budgets, the start and end cursor IDs represent the two budgets in our list.

Now we can take the cursor ID from the second result (YXJyYXljb25uZWN0aW9uOjE=) and pass that in as the after argument to our budgets field to get to the next page of budgets, keeping our page length to two items:

query {
  currentUser {
    company {
     budgets(first: 2, after: "YXJyYXljb25uZWN0aW9uOjE=") {
       pageInfo {
         startCursor
         endCursor
         hasNextPage
         hasPreviousPage
       }
       edges {
         cursor
         node {
           id
           name
         }
       }
     }
    }
  }
}

In response, we receive the next two budgets in the list:

{
  "data": {
    "currentUser": {
      "company": {
        "budgets": {
          "edges": [
            {
              "cursor": "YXJyYXljb25uZWN0aW9uOjI=",
              "node": {
                "id": "QnVkZ2V0OjEyOTMzMg==",
                "name": "Finance"
              }
            },
            {
              "cursor": "YXJyYXljb25uZWN0aW9uOjM=",
              "node": {
                "id": "QnVkZ2V0OjMyOTgyNg==",
                "name": "Communications"
              }
            }
          ],
          "pageInfo": {
            "endCursor": "YXJyYXljb25uZWN0aW9uOjM=",
            "hasNextPage": true,
            "hasPreviousPage": true,
            "startCursor": "YXJyYXljb25uZWN0aW9uOjI="
          }
        }
      }
    }
  }
}

We can also pass in arguments of sortColumn and sortDirection to indicate the order of our paginated results. See more in the types section about the values for those arguments and their defaults for specific fields. Below is a simple example of how we would sort our budgets by name in descending order:

query {
  currentUser {
    company {
     budgets(first: 2, after: "YXJyYXljb25uZWN0aW9uOjE=", sortColumn: "name", sortDirection: "desc") {
       edges {
         cursor
         node {
           id
           name
         }
       }
     }
    }
  }
}

Guides

How to Create Virtual Cards

Step 1: Use currentUser query to fetch available Budget IDs and User IDs

In order to create virtual cards and have them assigned to a specific user and budget, we will first fetch the relevant user IDs and budget IDs.

The best way to do this is to query for them using the currentUser query:

query {
  currentUser {
    company {
      budgets(first: 1) {
        edges {
          node {
            id
            name
            users(first: 1) {
              edges {
                node {
                  id
                }
              }
            }
          }
        }
      }
    }
  }
}

This will return the requested list of budget IDs and user IDs we will need for the next step:

{
  "data": {
    "currentUser": {
      "company": {
        "budgets": {
          "edges": [
            {
              "node": {
                "id": "QnVkZ2V0OjI2NjQ1MA==",
                "name": "Accounting",
                "users": {
                  "edges": [
                    {
                      "node": {
                        "id": "VXNlcjoxMzQ1NQ=="
                      }
                    }
                  ]
                }
              }
            }
          ]
        }
      }
    }
  }
}

Step 2: Use createVirtualCardForBudget mutation to create the virtual cards

Using the budget and user IDs acquired in the above query, pass them in as the mutation input and select for the newCardEdge field in the mutation body. We also pass in an amount, name and type for the card. In the mutation body we select the id, expirationDate, lastFour, and user for this card.

mutation {
    createVirtualCardForBudget(input: {
        amount: 1000,
        budgetId: "QnVkZ2V0OjI2NjQ1MA==",
        ownerId: "VXNlcjoxMzQ1NQ==",
        name: "New Card",
        type: "RECURRING"
    }) {
        newCardEdge {
            expirationDate
            id
            name
            lastFour
            type
            user {
                id
            }
        }
    }
}

This will return the following response with the new card data that was selected for in the mutation body:

{
  "data": {
    "createVirtualCardForBudget": {
      "newCardEdge": {
        "node": {
          "expirationDate": "09/25",
          "id": "Q2FyZDo3NTcyMTI0",
          "lastFour": "0123",
          "name": "New Card",
          "type": "RECURRING",
          "user": {
            "id": "VXNlcjoxMzQ1NQ=="
          }
        }
      }
    }
  }
}

How to query for transaction data

Use the currentUser query to select the company and then transactions fields. Here we pass in the first argument to select the first two transactions. We also select for some user and card data about the transaction.

query {
  currentUser {
    company {
      transactions(first: 2) {
        edges {
          node {
            id
            amount
            user {
              id
              lastName
            }
            card {
              id
              lastFour
            }
          }
        }
      }
    }
  }
}

This results in the following JSON response:

{
  "data": {
    "currentUser": {
      "company": {
        "transactions": {
          "edges": [
            {
              "node": {
                "amount": 17682,
                "card": {
                  "id": "Q2FyZDo1MTA0MTU4",
                  "lastFour": "3384"
                },
                "id": "VHJhbnNhY3Rpb246MTZmNjQ5Y2YtYjJkMi00YTllLWE2ODQtZDViN2FkNjRiOTZj",
                "user": {
                  "id": "VXNlcjozNjExNzc=",
                  "lastName": "Nez"
                }
              }
            },
            {
              "node": {
                "amount": 22225,
                "card": {
                  "id": "Q2FyZDo3MTIzMjc=",
                  "lastFour": "0842"
                },
                "id": "VHJhbnNhY3Rpb246MGU2NGRkZGItOWIwMS00NGEzLWE4Y2QtZjMzZTFhZjk2MWU3",
                "user": {
                  "id": "VXNlcjoxMDM3NDg=",
                  "lastName": "Doe"
                }
              }
            }
          ]
        }
      }
    }
  }
}

How to retrieve virtual credit card numbers

Primary Account Numbers for virtual cards are secured behind a separate API endpoint, at api.divvy.co/de/rest/pan. In order to use it, a temporary access token is needed. Each card has a token field which is a permanent identifier for the card. Since this token does not change, it is unsafe to use it for access control.

Step 1: Create a virtual card, and request the token field in the return data

mutation {
  createVirtualCardForBudget(input: {
    amount: 1000,
    budgetId: "QnVkZ2V0OjI2NjQ1MA==",
    ownerId: "VXNlcjoxMzQ1NQ==",
    name: "New Card",
    type: "RECURRING"
  }) {
    newCardEdge {
      expirationDate
      token
      id
      name
      lastFour
      type
      user {
        id
      }
    }
  }
}

{
  "data": {
    "createVirtualCardForBudget": {
      "newCardEdge": {
        "node": {
          "expirationDate": "09/25",
          "token": "002.R.c05c9fb4-fake-fake-fake-963a49553cec",
          "id": "Q2FyZDo3NTcyMTI0",
          "lastFour": "0123",
          "name": "New Card",
          "type": "RECURRING",
          "user": {
            "id": "VXNlcjoxMzQ1NQ=="
          }
        }
      }
    }
  }
}

Step 2: Use the getPanToken mutation to retrieve a PAN token for the de/rest/pan endpoint

This mutation generates a JWT token which contains all the necessary information to retrieve the virtual card's Primary Account Number. The token has a lifespan of five minutes.

mutation {
  getPanToken(input: {
    cardToken: "002.R.c05c9fb4-fake-fake-fake-963a49553cec"
  }) {
    token
  }
}

{
  "data": {
    "getPanToken": {
      "token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"
    }
  }
}

Step 3: Submit the PAN token to the de/rest/pan endpoint

No additional arguments or authentication is required for this endpoint; all the necessary information is encoded in the JWT token we received in the last step.

curl --location --request POST 'https://api.divvy.co/de/rest/pan' \
--header 'Content-Type: application/json' \
--data-raw '
{"token":"eyJhbGciOiJIUzI1NiIsInR5cCI6IkpXVCJ9.eyJzdWIiOiIxMjM0NTY3ODkwIiwibmFtZSI6IkpvaG4gRG9lIiwiaWF0IjoxNTE2MjM5MDIyfQ.SflKxwRJSMeKKF2QT4fwpMeJf36POk6yJV_adQssw5c"}'

The endpoint returns the expiration date, CVV, and card number for the requested card.

{"expirationDate":"010101","cvv":"999","cardNumber":"4482123456781234"}