The Griffin API (2026-07-09)

The Griffin API is based on REST. It has resource-oriented URLs, accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response verbs and response codes.

Our API deviates from strict RESTful principles if it makes sense to do so, such as when we enforce tighter access controls around certain operations. For example, when closing a bank account: rather than send a PATCH request to the bank account resource to update its status to "closed", we provide a dedicated account closure resource.

Anyone can create an account with Griffin and try out our API in sandbox mode.

New to Griffin? Check out our getting started guide.

Our API is designed to be navigated programmatically. When you request any resource, you will find the URLs for related resources in the response body.

The API is structured as a tree with your organization at the top. Everything that you own will be a sub-resource of your organization.

To bootstrap the navigation process, request the index endpoint: the response will contain your organization-url.

For a walkthrough, see our getting started guide.

Our list APIs support pagination (e.g. list bank accounts and list payments). By default, a list API returns up to 25 results. If there are more results available, the response payload will include links to the previous/next pages.

Change page size

You can request a different number of results (between 1 and 200, inclusive) by using the page[size] query parameter:

GET /organizations/:id/bank/accounts?page[size]=100

Navigating between pages

List responses will include a links object with prev and next attributes, as shown below. Perform a GET request to the value of the attribute to fetch the previous/next page of results.

{
  "accounts": [
    // ...
  ],
  "links": {
    "prev": "/organizations/og.IG9yZ2FuaXphdGlvbi1pZA/bank/accounts?page[before]=djE6WxSPxfYUTnCU9XtWzj9gGA",
    "next": "/organizations/og.IG9yZ2FuaXphdGlvbi1pZA/bank/accounts?page[after]=djE6aw79PXZySUOL16LD8HRJ3A"
  }
}

If there is no previous or next page available, the value of the attribute will be null.

Any other query parameters included in the initial request will also be included in the response payload's links. If you want to change parameters (see filtering and sorting), request the first page and follow the links from there.

Sort results

By default, resources will be listed in descending order, usually based on the created-at attribute. You can change the sorting behaviour of a list of results by using the sort query parameter.

For example, to list bank accounts in ascending order (oldest first):

GET /organizations/:id/bank/accounts?sort=created-at

To explicitly sort in descending order (newest first), prefix the sort attribute with -:

GET /organizations/:id/bank/accounts?sort=-created-at

Filter results

Some list APIs allow you to filter the results. Filters are expressed as nested data structures encoded into query parameters. For example, you can list bank accounts that are in either the opening or open state with:

GET /organizations/:id/bank/accounts?filter[account-status][in][]=opening&filter[account-status][in][]=open

Similarly, you can list legal persons with a specific application-status:

GET /organizations/:id/legal-persons?filter[application-status][eq]=accepted

Include resources

Some list APIs allow you to include associated resources in the response, reducing the number of requests needed to fetch related data. For instance, when listing bank accounts, you can include each bank account's beneficiary legal person by using the include query parameter:

GET /organizations/:id/bank/accounts?include=beneficiary

The response returns the usual list of bank accounts, but it will also have an included object with a legal-persons attribute:

{
  "accounts": [
    // ...
  ],
  "links": {
    // ...
  }
  "included": {
    "legal-persons": [
      // ...
    ]
  }
}

Check the documentation for each list API to see all options for sorting and filtering

Each organization is allowed up to 50 concurrent (in-flight) API requests. Exceeding this threshold results in a 429 - Too Many Requests response. Upon receiving a 429 response, you should implement a backoff strategy, pausing to allow your outstanding requests to complete before attempting new requests. To manage your request rate effectively and avoid surpassing this limit, consider using a controlled approach such as a finite pool of threads or workers.

The api-key-secret field is only shown once when you create an API key. We cannot recover the value, so you should store it securely.

Pass an Authorization header with GriffinAPIKey api-key-secret to authenticate.

Each API key is only valid for one organization. If you are a member of multiple organizations, you will need to create a new API key for each one. There is currently no limit on the number of API keys you can create.

Check your connection to the Griffin API.

The index is the entry point for navigating the API. It contains the URLs of global resources, from which every other resource can be reached.

An event records a change to a resource in your organization. The event-type determines the shape of the event-payload. You can list your organization's events, or receive them as they happen with a webhook.

A webhook delivers events to a URL you control as they happen. A webhook can be activated or deactivated, and you can send it a test event to check that your endpoint receives it.

Message Signatures confirm the identity of the sender and integrity of request messages.

Key points:

• Uses Ed25519 algorithm
• Requires registering a public key with Griffin
• Signatures cover specific message components
• Includes Signature-Input and Signature headers

How to create message signatures provides a detailed guide.

In the Griffin API, your organization and your customers are all represented by legal persons. When you sign up with Griffin, your organization will be automatically assigned a unique legal person ID. When onboarding your customers, you will create legal persons to represent them.

Every legal person has a legal-person-type with the value: individual or corporation.

An individual represents an individual human.

A corporation represents any non-human entity (not just companies). A corporation should have at least one director or person with significant control attached to it, who must also be represented as a distinct individual legal person.