Skip to main content

Get started with the API

Welcome to the Griffin API! This guide will take you through creating an API key and introduce some concepts you need to get started.

Anyone can create a sandbox account with Griffin and try out our API in sandbox mode. For now, if you want to go live, you'll need to contact us.

Creating an API key

  1. Create a sandbox account at https://app.griffin.sh/register
  2. Click Developers to create an API key.
  3. Give your API key a memorable name and store it somewhere safe.
caution

The API key will only be shown once. If you lose it, you'll need to log in, delete it and create a new one. There is currently no limit on the number of API keys you can create.

Throughout our docs, the API key will be referred to as $GRIFFIN_API_KEY - you can replace this with your own API key.

Check that you can connect to the API by calling the index resource. The API key is provided in the Authorization header.

curl -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY" "https://api.griffin.sh/v0/index"

If successful, you will be returned something like this:

{
"organizations-url": "/organizations",
"api-key-url": "/v0/api-keys/ak.0j3-IZIOSFytCD-9SqMdPw",
"roles-url": "/v0/roles",
"users-url": "/users"
}

Standard HTTP headers

We have three standard headers relevant to most requests:

Authorization: GriffinAPIKey $GRIFFIN_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.

Accept

The Accept header determines what format you receive the response in. We suport only application/json at present, which is the default.

Content-Type

When a request has a body, you must provide the Content-Type header specifying its media type. At present, we only support application/json.

The primary method of navigating our API is following URLs you find in responses. While exploring, you should never need to construct URLs yourself using IDs: instead, you can make a single initial request and follow links from one resource to another.

If you already know the ID of a resource, you can use our API Reference to construct a direct URL to it.

info

We have a Postman collection for the Griffin API. Set your API key as an environment variable named griffin-api-key within your Postman workspace to get started.

Example

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

Once you have your API key, you can request the index resource:

curl "https://api.griffin.sh/v0/index" -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"

The response will include a set of URLs you can use to begin navigating the API:

{
"api-key-url": "/v0/api-keys/ak.0j3-IZIOSFytCD-9SqMdPw",
"organizations-url": "/v0/organizations",
"roles-url": "/v0/roles",
"users-url": "/v0/users"
}

Follow the api-key-url to discover your organization-url. This organization-url is unique to you and most API resources, e.g. bank accounts and legal persons will be a child of it.

curl "https://api.griffin.sh/v0/api-keys/ak.0j3-IZIOSFytCD-9SqMdPw" -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"

{
"api-key-live?": false,
"api-key-name": "foo",
"api-key-url": "/v0/api-keys/ak.0j3-IZIOSFytCD-9SqMdPw",
"organization-url": "/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA",
"user-url": "/v0/users/ur.Etc0gzcURoSjMOAOZrnjmg"
}

Requesting organization-url returns a list of related resource URLs:

curl "https://api.griffin.sh/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA" -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"

{
"charts-of-accounts-url": "/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA/charts-of-accounts",
"display-name": "jamie corp",
"exports-url": "/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA/exports",
"journal-entries-url": "/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA/ledger/journal-entries",
"ledgers-url": "/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA/ledger/accounts",
"organization-api-keys-url": "/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA/api-keys",
"organization-bank-accounts-url": "/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA/bank/accounts",
"organization-invitations-url": "/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA/invitations",
"organization-legal-persons-url": "/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA/legal-persons",
"organization-memberships-url": "/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA/memberships",
"organization-mode": "test-mode",
"organization-trial-balance-url": "/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA/ledger/trial-balance",
"organization-url": "/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA",
"organization-verifications-url": "/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA/verifications",
"own-legal-person-url": "/v0/legal-persons/lp.Yvzfs9oJUeKsqHmu3-Us_g",
"transfers-url": "/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA/bank/transfers"
}

If you want to see a list of bank accounts, look up accounts-url in the data structure above, and request the URL. In the example, the URL is /v0/organizations/og.o1rsp7efTN6CpMRybuu4OA/bank/accounts: appending that to https://api.griffin.sh will return the list of bank accounts.

curl "https://api.griffin.sh/v0/organizations/og.o1rsp7efTN6CpMRybuu4OA/bank/accounts" -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY"

The response will look like this, where there is a single account defined:

{
"accounts": [
{
"account-url": "/v0/bank/accounts/ac.yGeZn1SrXX6z4wsylawrHA",
"display-name": "My Account",
"beneficiary-url": "/v0/legal-persons/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/legal-persons/lp.aDBVscJYVya5eU2V6PqkmQ",
"controller-url": "/v0/legal-persons/lp.aDBVsDJYXyaAeU2V6PqkmQ"
}
]
}

To see a list of transactions for a bank account, fetch the URL found under account-transactions-url.

In this way, you can navigate the API in its entirety, starting with only your API key.

API Versions

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

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

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 required keys from a response.
  • We may stop requiring a key in a request.
  • We may add new optional keys to a request.
  • We may add new keys to a response.
info

As we add features, we will inevitably add keys. Unknown keys are safe to accept and ignore while the version number remains the same.

We will not break your integration with a particular version for as long as we support that version.

If we release a new version, you will have 12 months to upgrade to it. That said, our goal is to avoid releasing new versions. We don’t want to end up supporting multiple versions and we don’t want to force you to change working code. The Griffin platform is intended to be stable over time.