Getting started with the API

There are only a few concepts you should know before integrating with our API: The compulsory headers we use, how we version the API and how to navigate between resources.

Standard HTTP Headers

We have three standard headers that we expect, detailed below. To summarise, we expect all API users to send these on every request, where $API_KEY is replaced by your API key:

Authorization: GriffinAPIKey $API_KEY
Content-Type: application/json
Accept: application/json

Authorization

All API requests require the Authorization header. The value of the header is always GriffinAPIKey plus your API key. You don't need to encode the API key in any way; just send it as plain text.

We do not support Basic as an authorization method in our API.

🚧

The API key is shown once and only once after creation in the Griffin application. If you've forgotten your API key, you need to log in, delete it, and create a new one.

Accept

The Accept header determines what format you receive the response in. All API requests should specify application/json for our JSON representation.

🚧

Long-running reports typically return either a CSV file or a ZIP file containing multiple CSVs. This is to both keep file sizes down, and to facillitate importing in to a spreadsheet or another tool for further processing. This is clearly marked in the documentation.

Content-Type

The Content-Type header has the same rules as the Accept header. You may supply a HTTP request body in either application/json (recommended) or application/edn format.

Note that we treat Accept and Content-Type separately, therefore both should be supplied as application/json to ensure requests are processed as JSON and that responses are returned as JSON.

API Versions

Version 0

The Griffin API is versioned via a prefix in the URL. The current version for
the sandbox is v0.

An example endpoint is: https://api.beta.griffin.sh/v0/index.

v0 indicates that the sandbox is under active development as we add features.
It is, nonetheless, intended to be stable, with few breaking changes. Breaking
changes may be made where absolutely necessary.

Version 1 onwards

Once you have a production account with Griffin, you will use version v1. At this point, we provide a backwards compatibility guarantee:

  • We will not change the meaning of a key in a request or a response.
  • We will not remove keys from requests or responses.
  • We may choose to add new keys. These keys will be optional, with sensible defaults.

Changing the meaning of a key or removing one is considered a breaking change, and will always result in a version change.

After you have integrated with a particular version, we will not break your integration for as long as we support that version.

📘

You should always accept and ignore unknown keys in our responses. As we develop the system and add functionality, it's inevitable for us to add keys. They are safe to ignore, while the version number remains the same.

If we release a new version, all customers will have 12 months to upgrade to it.

However, our goal is to avoid releasing new versions. We do not want to support multiple versions over time, nor do we want to force you to change working code. The Griffin platform is intended to be stable over time.

Navigating the API

The API is designed to be navigable. That is, responses contain URLs as well as IDs in many cases. If you have successfully created an API key for the sandbox, you will have seen an example of this by calling /index.

The primary method of navigating our API is through following URLs you find in responses. For exploration purposes, you should never need to construct URLs yourself using IDs.

The consequence of this design choice is that you can explore our API by making a single initial request and following links from one resource to another.

Of course, if you know the ID of a resource, you can use our API Reference to construct a direct URL to it.

📘

This pattern is often known as 'Hypertext As The Engine Of Application State' (HATEOAS). You can think of navigating the API in the same way as clicking links within your web browser.

Example

In this example, you will be able to walk the API from your user, to querying the transactions for a bank account.

Once you have your API key ($API_KEY) and user ID ($USER_ID), you can request a list of all organisations your user has access to (typically one):

curl "https://api.beta.griffin.sh/v0/users/$USER_ID/organizations" \
  -H "Authorization: GriffinAPIKey $API_KEY" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json'

The response will look something like the below - the organisation ID starting with og. will be unique to you. The definition of each URL is available in the API Reference.

{
  "organizations": [
    {
      "organization-users-url": "/v0/organizations/og.3Uh8Vu6J7XmUbje_NC_2LQ/users",
      "organization-individuals-url": "/v0/organizations/og.3Uh8Vu6J7XmUbje_NC_2LQ/individuals",
      "ledgers-url": "/v0/organizations/og.3Uh8Vu6J7XmUbje_NC_2LQ/ledger/accounts",
      "organization-sovereigns-url": "/v0/organizations/og.3Uh8Vu6J7XmUbje_NC_2LQ/sovereigns",
      "accounts-url": "/v0/organizations/og.3Uh8Vu6J7XmUbje_NC_2LQ/bank/accounts",
      "display-name": "My Organisation",
      "transfers-url": "/v0/organizations/og.3Uh8Vu6J7XmUbje_NC_2LQ/bank/transfers",
      "own-legal-person-url": "/v0/corporations/lp.aDBVsDJYVyaPeU2V6PqkmQ",
      "organization-trial-balance-url": "/v0/organizations/og.3Uh8Vu6J7XmUbje_NC_2LQ/ledger/trial-balance",
      "organization-corporations-url": "/v0/organizations/og.3Uh8Vu6J7XmUbje_NC_2LQ/corporations",
      "organization-invitations-url": "/v0/organizations/og.3Uh8Vu6J7XmUbje_NC_2LQ/invitations",
      "exports-url": "/v0/organizations/og.3Uh8Vu6J7XmUbje_NC_2LQ/exports",
      "ledger-entries-url": "/v0/organizations/og.3Uh8Vu6J7XmUbje_NC_2LQ/ledger/transfers",
      "organization-url": "/v0/organizations/og.3Uh8Vu6J7XmUbje_NC_2LQ",
      "organization-api-keys-url": "/v0/organizations/og.3Uh8Vu6J7XmUbje_NC_2LQ/api-keys",
      "journal-entries-url": "/v0/organizations/og.3Uh8Vu6J7XmUbje_NC_2LQ/ledger/journal-entries",
      "charts-of-accounts-url": "/v0/organizations/og.3Uh8Vu6J7XmUbje_NC_2LQ/charts-of-accounts"
    }
  ]
}

You might then be interested in a listing of all bank accounts. To do so, you look up accounts-url in the data structure above, and request the URL. In the example, the URL is /v0/organizations/og.3Uh8Vu6J7XmUbje_NC_2LQ/bank/accounts; appending that to https://api.griffin.sh will return the list of bank accounts.

curl "https://api.beta.griffin.sh/v0/organizations/og.3Uh8Vu6J7XmUbje_NC_2LQ/bank/accounts" \
  -H "Authorization: GriffinAPIKey $API_KEY" \
  -H 'Accept: application/json' \
  -H 'Content-Type: application/json'

The response will look similar to the below, if you have a single account defined:

{
  "accounts": [
    {
      "account-url": "/v0/bank/accounts/ac.yGeZn1SrXX6z4wsylawrHA",
      "display-name": "My Account",
      "beneficiary-url": "/v0/corporations/lp.aDBVscJYVya5eU2V6PqkmQ",
      "account-balance": {
        "currency": "GBP",
        "value": "100.00"
      },
      "account-transactions-url": "/v0/bank/accounts/ac.yGeZn1SrXX6z4wsylawrHA/transactions",
      "bank-product-type": "business-demand-account",
      "owner-url": "/v0/corporations/lp.aDBVscJYVya5eU2V6PqkmQ",
      "controller-url": "/v0/corporations/lp.aDBVsDJYXyaAeU2V6PqkmQ"
    }
  ]
}

Fetching the URL found under account-transactions-url will now return a list of transactions for the account.

In this way, you can navigate the API in its entirety, starting from your user ID.