Skip to main content
API docs by Redocly

The Griffin API

Download OpenAPI specification:Download

Introduction

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 it's 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.

Navigation

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.

Pagination

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 /v0/organizations/:id/bank/accounts?page[size]=100

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": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA/bank/accounts?page[before]=djE6WxSPxfYUTnCU9XtWzj9gGA",
    "next": "/v0/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.

Filtering and sorting

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 /v0/organizations/:id/bank/accounts?sort=created-at

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

GET /v0/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 /v0/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 /v0/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 /v0/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

Request limits

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 Submit Payment API imposes an additional limit: there may be at most 3 concurrent requests to submit a payment from a single bank account. For more details, see the Submit Payment API documentation.

Versioning

The Griffin API is versioned via a prefix in the URL. The current version is v0. An example endpoint is: https://api.griffin.com/v0/index.

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.

API keys

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.

Get API key

Returns the API key without api-key-secret.

Authorizations:
api-key-auth
path Parameters
api-key-id
required
string

Responses

Response samples

Content type
application/json
{
  • "api-key-url": "/v0/api-keys/ak.ICAgICAgYXBpLWtleS1pZA",
  • "api-key-name": "buildserver",
  • "api-key-live?": true,
  • "organization-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA",
  • "user-url": "/v0/users/ur.ICAgICAgICAgdXNlci1pZA",
  • "created-at": "2019-08-24T14:15:22Z"
}

Delete API key

Deletes the API Key. This operation cannot be undone.

Authorizations:
api-key-auth
path Parameters
api-key-id
required
string

Responses

List API keys

List all active API keys in your organization.

Authorizations:
api-key-auth
path Parameters
organization-id
required
string
query Parameters
sort
string
Enum: "-created-at" "created-at"
page[size]
integer <int64> [ 1 .. 200 ]
page[after]
string <byte>

A base64 encoded opaque string returned in paginated responses.

page[before]
string <byte>

A base64 encoded opaque string returned in paginated responses.

Responses

Response samples

Content type
application/json
{
  • "api-keys": [
    ],
  • "links": {
    },
  • "included": null
}

Create API Key

Create a new API key. This is the only time api-key-secret is shown.

Authorizations:
api-key-auth
path Parameters
organization-id
required
string
Request Body schema: application/json
api-key-name
required
string (api-key-name) non-empty

The name of the API Key. Cannot contain whitespace.

Responses

Request samples

Content type
application/json
{
  • "api-key-name": "string"
}

Response samples

Content type
application/json
{
  • "api-key-url": "/v0/api-keys/ak.ICAgICAgYXBpLWtleS1pZA",
  • "api-key-name": "buildserver",
  • "api-key-live?": true,
  • "organization-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA",
  • "user-url": "/v0/users/ur.ICAgICAgICAgdXNlci1pZA",
  • "created-at": "2019-08-24T14:15:22Z",
  • "api-key-secret": "g-test-buildserver-RrUZ5fUG4pSKwYVVG1C3Ft1xrMRxy1T7KUIyTva5bTk"
}

List API keys

List all your active API keys.

Authorizations:
api-key-auth
path Parameters
user-id
required
string
query Parameters
sort
string
Enum: "-created-at" "created-at"
page[size]
integer <int64> [ 1 .. 200 ]
page[after]
string <byte>

A base64 encoded opaque string returned in paginated responses.

page[before]
string <byte>

A base64 encoded opaque string returned in paginated responses.

Responses

Response samples

Content type
application/json
{
  • "api-keys": [
    ],
  • "links": {
    }
}

Connectivity

Ping

Check your connection to the Griffin API.

Responses

Navigation

Index

Contains various global URL paths. Follow api-key-url to discover your organization-url.

Authorizations:
api-key-auth

Responses

Response samples

Content type
application/json
{
  • "organizations-url": "/v0/organizations",
  • "users-url": "/v0/users",
  • "roles-url": "/v0/roles",
  • "session-url": "/v0/session",
  • "api-key-url": "/v0/api-keys/ak.ICAgICAgYXBpLWtleS1pZA",
  • "organization-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA"
}

Events

Get an event

The event-type may be one of:

account-status-created

{
  "event-url" : "/v0/events/ev.d9ImQpReWO2qvCk_wMQjxw",
  "event-type" : "account-status-created",
  "event-payload" : {
    "account-url" : "/v0/bank/accounts/ba.JZjyiHUbXEOqy6YWyaR_Jw",
    "account-status" : "open"
  },
  "created-at" : "2024-01-01T13:30:00.000Z"
}

account-status-updated

{
  "created-at" : "2024-01-01T17:55:00.000Z",
  "event-url" : "/v0/events/ev.d9ImQpReWO2qvCk_wMQjxw",
  "event-type" : "account-status-updated",
  "event-payload" : {
    "account-url" : "/v0/bank/accounts/ba.JZjyiHUbXEOqy6YWyaR_Jw",
    "account-status" : "closed"
  }
}

admission-created

{
  "event-url" : "/v0/events/ev.d9ImQpReWO2qvCk_wMQjxw",
  "event-type" : "admission-created",
  "event-payload" : {
    "admission-status" : "processing",
    "admission-scheme-information" : {
      "payment-scheme" : "fps",
      "end-to-end-identification" : "FQ36X73Jb44ZyQE331GYuxLuWM8N85"
    },
    "payment-url" : "/v0/payments/pm.x2UcETQsU4enORzXPgL9bQ",
    "created-at" : "2024-01-01T13:20:00.123Z",
    "admission-url" : "/v0/admissions/pa.oRFnmBymXIKoknlbwroj8g",
    "unique-scheme-identifier" : "AB123456789123456N1020220426826159900     ",
    "original-unique-scheme-identifier" : "ZZ123456789123456N1020220426826159900     ",
    "account-url" : "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA"
  },
  "created-at" : "2024-01-01T13:30:00.000Z"
}

admission-updated

{
  "event-url" : "/v0/events/ev.d9ImQpReWO2qvCk_wMQjxw",
  "event-type" : "admission-updated",
  "event-payload" : {
    "admission-status" : "delivered",
    "admission-scheme-information" : {
      "payment-scheme" : "fps",
      "end-to-end-identification" : "FQ36X73Jb44ZyQE331GYuxLuWM8N85"
    },
    "payment-url" : "/v0/payments/pm.x2UcETQsU4enORzXPgL9bQ",
    "created-at" : "2024-01-01T18:40:00.014Z",
    "admission-url" : "/v0/admissions/pa.oRFnmBymXIKoknlbwroj8g",
    "unique-scheme-identifier" : "AB123456789123456N1020220426826159900     ",
    "original-unique-scheme-identifier" : "ZZ123456789123456N1020220426826159900     ",
    "account-url" : "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA"
  },
  "created-at" : "2024-01-01T18:45:00.000Z"
}

decision-created

{
  "created-at" : "2020-01-01T00:00:00.000Z",
  "event-url" : "/v0/events/ev.d9ImQpReWO2qvCk_wMQjxw",
  "event-type" : "decision-created",
  "event-payload" : {
    "legal-person-url" : "/v0/legal-persons/lp.7oKVYzj1V-2Y4gXEvdowYA",
    "verification-url" : "/v0/verifications/vn.yY5hFwg3URayMz6iqXQcpA",
    "decision-outcome" : "accepted",
    "decision-maker" : "system",
    "decision-notes" : "auto-accepted",
    "created-at" : "1900-01-01T00:00:00.130Z"
  }
}

onboarding-application-created

{
  "created-at" : "2020-01-01T00:00:00.000Z",
  "event-url" : "/v0/events/ev.d9ImQpReWO2qvCk_wMQjxw",
  "event-type" : "onboarding-application-created",
  "event-payload" : {
    "onboarding-application-url" : "/v0/onboarding/applications/oa.frwOX_PxXnG6PDDp7n6jwQ",
    "created-at" : "1900-01-01T08:55:12.120Z",
    "workflow-url" : "/v0/workflows/wf.ESz-T8PUUfyzYDrxBIUjJg",
    "legal-person-url" : "/v0/legal-persons/lp.7oKVYzj1V-2Y4gXEvdowYA",
    "verification-url" : "/v0/verifications/vn.yY5hFwg3URayMz6iqXQcpA",
    "onboarding-application-status" : "processing"
  }
}

onboarding-application-updated

{
  "event-url" : "/v0/events/ev.d9ImQpReWO2qvCk_wMQjxw",
  "event-type" : "onboarding-application-updated",
  "event-payload" : {
    "onboarding-application-url" : "/v0/onboarding/applications/oa.frwOX_PxXnG6PDDp7n6jwQ",
    "created-at" : "2024-02-03T10:00:00.000Z",
    "workflow-url" : "/v0/workflows/wf.ESz-T8PUUfyzYDrxBIUjJg",
    "legal-person-url" : "/v0/legal-persons/lp.7oKVYzj1V-2Y4gXEvdowYA",
    "verification-url" : "/v0/verifications/vn.yY5hFwg3URayMz6iqXQcpA",
    "decision-outcome" : "accepted",
    "onboarding-application-status" : "complete"
  },
  "created-at" : "2020-01-01T00:00:00.000Z"
}

payment-created

{
  "created-at" : "2024-01-01T15:45:00.000Z",
  "event-url" : "/v0/events/ev.d9ImQpReWO2qvCk_wMQjxw",
  "event-type" : "payment-created",
  "event-payload" : {
    "creditor" : {
      "account-url" : "/v0/bank/accounts/ba.JZjyiHUbXEOqy6YWyaR_Jw",
      "creditor-type" : "griffin-bank-account"
    },
    "payment-direction" : "inbound-payment",
    "created-at" : "2024-01-01T15:00:20.237Z",
    "payment-url" : "/v0/payments/pm.x2UcETQsU4enORzXPgL9bQ",
    "payment-reference" : "Dinner",
    "payment-amount" : {
      "currency" : "GBP",
      "value" : "16.00"
    },
    "payment-admissions-url" : "/v0/payments/pm.x2UcETQsU4enORzXPgL9bQ/admissions",
    "payment-submissions-url" : "/v0/payments/pm.x2UcETQsU4enORzXPgL9bQ/submissions",
    "debtor" : {
      "account-url" : "/v0/bank/accounts/ba.JZjyiHUbXEOqy6YWyaR_Jw",
      "account-holder" : "ZxB7REHskP2ghVt9Lh23I5",
      "account-number" : "92526719",
      "account-number-code" : "bban",
      "bank-id" : "053515",
      "bank-id-code" : "gbdsc"
    }
  }
}

submission-created

{
  "created-at" : "2024-01-01T00:00:00.000Z",
  "event-url" : "/v0/events/ev.d9ImQpReWO2qvCk_wMQjxw",
  "event-type" : "submission-created",
  "event-payload" : {
    "unique-scheme-identifier" : "AB123456789123456N1020220426826159900     ",
    "submission-status" : "processing",
    "submission-scheme-information" : {
      "scheme-status-code-description" : "The payment was accepted by the scheme",
      "scheme-status-code" : "0000",
      "end-to-end-identification" : "AHFIWSJFSOK",
      "payment-scheme" : "fps"
    },
    "payment-url" : "/v0/payments/pm.x2UcETQsU4enORzXPgL9bQ",
    "created-at" : "2024-01-01T13:23:01.529Z",
    "submission-url" : "/v0/submissions/ps.oRFnmBymXIKoknlbwroj8g",
    "account-url" : "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA"
  }
}

submission-updated

{
  "event-url" : "/v0/events/ev.d9ImQpReWO2qvCk_wMQjxw",
  "event-type" : "submission-updated",
  "event-payload" : {
    "unique-scheme-identifier" : "AB123456789123456N1020220426826159900     ",
    "submission-status" : "delivered",
    "submission-scheme-information" : {
      "end-to-end-identification" : "FQ36X73Jb44ZyQE331GYuxLuWM8N85",
      "payment-scheme" : "fps"
    },
    "payment-url" : "/v0/payments/pm.x2UcETQsU4enORzXPgL9bQ",
    "created-at" : "2024-01-01T10:38:32.973Z",
    "submission-url" : "/v0/submissions/ps.oRFnmBymXIKoknlbwroj8g",
    "account-url" : "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA"
  },
  "created-at" : "2024-01-01T00:00:00.000Z"
}

test-event

{
  "event-url" : "/v0/events/ev.d9ImQpReWO2qvCk_wMQjxw",
  "event-type" : "test-event",
  "event-payload" : { },
  "created-at" : "2020-01-01T00:00:00.000Z"
}

transaction-created

{
  "event-url" : "/v0/events/ev.d9ImQpReWO2qvCk_wMQjxw",
  "event-type" : "transaction-created",
  "event-payload" : {
    "account-transaction-url" : "/v0/bank/transactions/tr.KXXPmz1DVQS-X_HVLlTfWQ",
    "post-datetime" : "2024-01-01T00:00:00.000Z",
    "balance-change-direction" : "debit",
    "transaction-origin-type" : "payment",
    "payment-url" : "/v0/payments/pm.x2UcETQsU4enORzXPgL9bQ",
    "reference" : "Dinner",
    "account-url" : "/v0/bank/accounts/ba.JZjyiHUbXEOqy6YWyaR_Jw",
    "balance-change" : {
      "currency" : "GBP",
      "value" : "200.00"
    },
    "account-balance" : {
      "currency" : "GBP",
      "value" : "800.00"
    }
  },
  "created-at" : "2024-01-01T00:00:00.000Z"
}

verification-created

{
  "created-at" : "2020-01-01T00:00:00.000Z",
  "event-url" : "/v0/events/ev.d9ImQpReWO2qvCk_wMQjxw",
  "event-type" : "verification-created",
  "event-payload" : {
    "workflow-url" : "/v0/workflows/wf.ESz-T8PUUfyzYDrxBIUjJg",
    "created-at" : "1900-01-01T00:00:01.063Z",
    "legal-person-url" : "/v0/legal-persons/lp.7oKVYzj1V-2Y4gXEvdowYA",
    "verification-status" : "in-progress",
    "verification-url" : "/v0/verifications/vn.yY5hFwg3URayMz6iqXQcpA",
    "verification-checks-url" : "/v0/verifications/vn.yY5hFwg3URayMz6iqXQcpA/checks"
  }
}

verification-resource-created

{
  "created-at" : "2025-02-13T17:15:17.865Z",
  "event-url" : "/v0/events/ev.d9ImQpReWO2qvCk_wMQjxw",
  "event-type" : "verification-resource-created",
  "event-payload" : {
    "verification-resource-id" : "vr.aVi78djZTiSymFpU-zV60Q",
    "idv-check-status" : "errored",
    "idv-check-url" : "TEST",
    "verification-url" : "/v0/verifications/vn.0khMbqbVSomz4YDdG2YEPQ",
    "display-name" : "02t1y9jKLQp5CdQ4RsxiEuF7QuNDb177Q1Q9Dp0WSL28gDdia5gW7O8lhA2l9Y8w90B1eV1Q23fly6r20ENNJeR",
    "legal-person-url" : "/v0/legal-persons/lp.eopIWRwdVVuk6WsW9GzA2w",
    "idv-check-expires-at" : "2154-10-20",
    "organization-url" : "/v0/organizations/og.VxGLrVDKSB2e1Ps4TtJKrg",
    "verification-resource-type" : "idv-check"
  }
}

verification-resource-updated

{
  "created-at" : "2025-02-13T17:15:17.865Z",
  "event-url" : "/v0/events/ev.d9ImQpReWO2qvCk_wMQjxw",
  "event-type" : "verification-resource-updated",
  "event-payload" : {
    "verification-resource-id" : "vr.aVi78djZTiSymFpU-zV60Q",
    "idv-check-status" : "errored",
    "idv-check-url" : "TEST",
    "verification-url" : "/v0/verifications/vn.0khMbqbVSomz4YDdG2YEPQ",
    "display-name" : "02t1y9jKLQp5CdQ4RsxiEuF7QuNDb177Q1Q9Dp0WSL28gDdia5gW7O8lhA2l9Y8w90B1eV1Q23fly6r20ENNJeR",
    "legal-person-url" : "/v0/legal-persons/lp.eopIWRwdVVuk6WsW9GzA2w",
    "idv-check-expires-at" : "2154-10-20",
    "organization-url" : "/v0/organizations/og.VxGLrVDKSB2e1Ps4TtJKrg",
    "verification-resource-type" : "idv-check"
  }
}

verification-updated

{
  "created-at" : "2020-01-01T00:00:00.000Z",
  "event-url" : "/v0/events/ev.d9ImQpReWO2qvCk_wMQjxw",
  "event-type" : "verification-updated",
  "event-payload" : {
    "verification-url" : "/v0/verifications/vn.yY5hFwg3URayMz6iqXQcpA",
    "updated-at" : "1900-01-01T00:03:10.221Z",
    "legal-person-url" : "/v0/legal-persons/lp.7oKVYzj1V-2Y4gXEvdowYA",
    "workflow-url" : "/v0/workflows/wf.ESz-T8PUUfyzYDrxBIUjJg",
    "created-at" : "1900-01-01T00:00:00.408Z",
    "verification-checks-url" : "/v0/verifications/vn.yY5hFwg3URayMz6iqXQcpA/checks",
    "risk-rating" : "low-risk",
    "verification-status" : "checks-complete",
    "verification-risk-assessments-url" : "/v0/verifications/vn.yY5hFwg3URayMz6iqXQcpA/risk-assessments"
  }
}
Authorizations:
api-key-auth
path Parameters
event-id
required
string

Responses

Response samples

Content type
application/json
{
  • "event-url": "/v0/events/ev.ICAgICAgICBldmVudC1pZA",
  • "event-type": "onboarding-application-updated",
  • "event-payload": { },
  • "created-at": "2019-08-24T14:15:22Z"
}

List all events for an organization

List all events for an organization

Authorizations:
api-key-auth
path Parameters
organization-id
required
string
query Parameters
sort
string
Enum: "-created-at" "created-at"
page[size]
integer <int64> [ 1 .. 200 ]
page[before]
string <byte>

A base64 encoded opaque string returned in paginated responses.

page[after]
string <byte>

A base64 encoded opaque string returned in paginated responses.

filter[event-type][eq]
string
Enum: "onboarding-application-updated" "decision-created" "payment-created" "transaction-created" "verification-updated" "admission-updated" "verification-created" "account-status-updated" "onboarding-application-created" "submission-created" "test-event" "admission-created" "verification-resource-updated" "account-status-created" "verification-resource-created" "submission-updated"

The type of webhook event. Usually has the form {resource}-{operation}, e.g. payment-updated

filter[created-at][lte]
string <date-time>

Return only events with a created-at less than or equal to the given timestamp.

filter[created-at][lt]
string <date-time>

Return only events with a created-at less than the given timestamp.

filter[created-at][gte]
string <date-time>

Return only events with a created-at greater than or equal to the given timestamp.

filter[created-at][gt]
string <date-time>

Return only events with a created-at greater than the given timestamp.

Responses

Response samples

Content type
application/json
{
  • "events": [
    ],
  • "links": {
    }
}

Webhooks

Get all webhooks for the organization

Get all webhooks for the organization

Authorizations:
api-key-auth
path Parameters
organization-id
required
string

Responses

Response samples

Content type
application/json
{
  • "organization-webhooks": [
    ]
}

Create a webhook

Create a webhook

Authorizations:
api-key-auth
path Parameters
organization-id
required
string
Request Body schema: application/json
webhook-destination-url
required
string (webhook-destination-url)

The callback URL of the webhook

webhook-description
string (webhook-description) non-empty

A description of the webhook

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "organization-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA",
  • "webhook-url": "/v0/webhooks/wh.ICAgICAgd2ViaG9vay1pZA",
  • "webhook-destination-url": "https://example.com/griffin/webhook/",
  • "test-webhook-url": "/v0/webhooks/wh.ICAgICAgd2ViaG9vay1pZA/actions/test",
  • "activate-webhook-url": "/v0/webhooks/wh.ICAgICAgd2ViaG9vay1pZA/actions/activate",
  • "deactivate-webhook-url": "/v0/webhooks/wh.ICAgICAgd2ViaG9vay1pZA/actions/deactivate",
  • "webhook-description": "Griffin API webhook"
}

Fetch a webhook

Fetch a webhook

Authorizations:
api-key-auth
path Parameters
webhook-id
required
string

Responses

Response samples

Content type
application/json
{
  • "organization-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA",
  • "webhook-url": "/v0/webhooks/wh.ICAgICAgd2ViaG9vay1pZA",
  • "webhook-destination-url": "https://example.com/griffin/webhook/",
  • "test-webhook-url": "/v0/webhooks/wh.ICAgICAgd2ViaG9vay1pZA/actions/test",
  • "activate-webhook-url": "/v0/webhooks/wh.ICAgICAgd2ViaG9vay1pZA/actions/activate",
  • "deactivate-webhook-url": "/v0/webhooks/wh.ICAgICAgd2ViaG9vay1pZA/actions/deactivate",
  • "webhook-description": "Griffin API webhook"
}

Delete a webhook

Delete a webhook

Authorizations:
api-key-auth
path Parameters
webhook-id
required
string

Responses

Update a webhook

Update a webhook

Authorizations:
api-key-auth
path Parameters
webhook-id
required
string
Request Body schema: application/json
webhook-description
string (webhook-description) non-empty

A description of the webhook

Responses

Request samples

Content type
application/json
{
  • "webhook-description": "Griffin API webhook"
}

Response samples

Content type
application/json
{
  • "organization-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA",
  • "webhook-url": "/v0/webhooks/wh.ICAgICAgd2ViaG9vay1pZA",
  • "webhook-destination-url": "https://example.com/griffin/webhook/",
  • "test-webhook-url": "/v0/webhooks/wh.ICAgICAgd2ViaG9vay1pZA/actions/test",
  • "activate-webhook-url": "/v0/webhooks/wh.ICAgICAgd2ViaG9vay1pZA/actions/activate",
  • "deactivate-webhook-url": "/v0/webhooks/wh.ICAgICAgd2ViaG9vay1pZA/actions/deactivate",
  • "webhook-description": "Griffin API webhook"
}

Activate a webhook

Activate a webhook

Authorizations:
api-key-auth
path Parameters
webhook-id
required
string

Responses

Response samples

Content type
application/json
{
  • "organization-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA",
  • "webhook-url": "/v0/webhooks/wh.ICAgICAgd2ViaG9vay1pZA",
  • "webhook-destination-url": "https://example.com/griffin/webhook/",
  • "test-webhook-url": "/v0/webhooks/wh.ICAgICAgd2ViaG9vay1pZA/actions/test",
  • "activate-webhook-url": "/v0/webhooks/wh.ICAgICAgd2ViaG9vay1pZA/actions/activate",
  • "deactivate-webhook-url": "/v0/webhooks/wh.ICAgICAgd2ViaG9vay1pZA/actions/deactivate",
  • "webhook-description": "Griffin API webhook"
}

Deactivate a webhook

Deactivate a webhook

Authorizations:
api-key-auth
path Parameters
webhook-id
required
string

Responses

Response samples

Content type
application/json
{
  • "organization-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA",
  • "webhook-url": "/v0/webhooks/wh.ICAgICAgd2ViaG9vay1pZA",
  • "webhook-destination-url": "https://example.com/griffin/webhook/",
  • "test-webhook-url": "/v0/webhooks/wh.ICAgICAgd2ViaG9vay1pZA/actions/test",
  • "activate-webhook-url": "/v0/webhooks/wh.ICAgICAgd2ViaG9vay1pZA/actions/activate",
  • "deactivate-webhook-url": "/v0/webhooks/wh.ICAgICAgd2ViaG9vay1pZA/actions/deactivate",
  • "webhook-description": "Griffin API webhook"
}

Get the status of the latest test event

Get the status of the latest test event

Authorizations:
api-key-auth
path Parameters
webhook-id
required
string

Responses

Response samples

Content type
application/json
Example
{
  • "webhook-request-status": "default",
  • "updated-at": "2019-08-24T14:15:22Z"
}

Send a test event to the webhook

Send a test event to the webhook

Authorizations:
api-key-auth
path Parameters
webhook-id
required
string

Responses

Response samples

Content type
application/json
Example
{
  • "webhook-request-status": "default",
  • "updated-at": "2019-08-24T14:15:22Z"
}

Message Signatures

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.

HTTP Signature Debug

Yields the status of the http signature validation

header Parameters
header-signature
string

Message Signatures: signature header containing a signature label with the components used to generate the signature

header-signature-input
string

Message Signatures: signature-input header containing a signature label with the components used to generate the signature

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "busy": true
}

Yields the status of the http signature validation

Yields the status of the http signature validation

header Parameters
header-signature
string

Message Signatures: signature header containing a signature label with the components used to generate the signature

header-signature-input
string

Message Signatures: signature-input header containing a signature label with the components used to generate the signature

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "busy": true
}

Yields the status of the http signature validation

Yields the status of the http signature validation

header Parameters
header-signature
string

Message Signatures: signature header containing a signature label with the components used to generate the signature

header-signature-input
string

Message Signatures: signature-input header containing a signature label with the components used to generate the signature

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "busy": true
}

Yields the status of the http signature validation

Yields the status of the http signature validation

header Parameters
header-signature
string

Message Signatures: signature header containing a signature label with the components used to generate the signature

header-signature-input
string

Message Signatures: signature-input header containing a signature label with the components used to generate the signature

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "busy": true
}

Yields the status of the http signature validation

Yields the status of the http signature validation

header Parameters
header-signature
string

Message Signatures: signature header containing a signature label with the components used to generate the signature

header-signature-input
string

Message Signatures: signature-input header containing a signature label with the components used to generate the signature

Responses

Response samples

Content type
application/json
{
  • "message": "string",
  • "busy": true
}

Legal persons

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.

Get legal person

Yields the legal-person.

Authorizations:
api-key-auth
path Parameters
legal-person-id
required
string

Responses

Response samples

Content type
application/json
{
  • "latest-decision": {
    },
  • "legal-person-type": "individual",
  • "latest-risk-rating-url": "/v0/risk-ratings/rr.ICByaXNrLXJhdGluZy1pZA",
  • "display-name": "Company name",
  • "application-status": "referred",
  • "legal-person-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "legal-person-decisions-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA/decisions",
  • "status-changed-at": "2019-08-24T14:15:22Z",
  • "created-at": "2019-08-24T14:15:22Z",
  • "legal-person-claims-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA/claims",
  • "legal-person-bank-payees-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA/bank/payees",
  • "legal-person-verifications-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA/verifications",
  • "legal-name": "string",
  • "legal-person-documents-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA/documents"
}

Update legal person

Updates the legal-person.

Authorizations:
api-key-auth
path Parameters
legal-person-id
required
string
Request Body schema: application/json
display-name
required
string (display-name) non-empty

A human readable label for an entity

Responses

Request samples

Content type
application/json
{
  • "display-name": "string"
}

Response samples

Content type
application/json
{
  • "latest-decision": {
    },
  • "legal-person-type": "individual",
  • "latest-risk-rating-url": "/v0/risk-ratings/rr.ICByaXNrLXJhdGluZy1pZA",
  • "display-name": "Company name",
  • "application-status": "referred",
  • "legal-person-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "legal-person-decisions-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA/decisions",
  • "status-changed-at": "2019-08-24T14:15:22Z",
  • "created-at": "2019-08-24T14:15:22Z",
  • "legal-person-claims-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA/claims",
  • "legal-person-bank-payees-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA/bank/payees",
  • "legal-person-verifications-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA/verifications",
  • "legal-name": "string",
  • "legal-person-documents-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA/documents"
}

List legal persons

Returns a paginated list of all legal persons for the given organization.

By default, results are sorted descending by created-at (newest first). To sort ascending by created-at, provide a ?sort=created-at query parameter.

Authorizations:
api-key-auth
path Parameters
organization-id
required
string
query Parameters
sort
string
Enum: "-status-changed-at" "status-changed-at" "-created-at" "created-at"
include
Array of strings
Items Enum: "latest-risk-rating" "latest-verification"

For each legal person returned, include its latest verification (if one exists), and/or its latest risk rating (if one exists) in the response under the included attribute.

filter[application-status][eq]
string
Enum: "referred" "errored" "declined" "submitted" "accepted"

Return only legal persons with the given application-status.

filter[has][]
Array of strings
Items Value: "application-status"

Return only legal persons with the given attributes.

page[size]
integer <int64> [ 1 .. 200 ]
page[after]
string <byte>

A base64 encoded opaque string returned in paginated responses.

page[before]
string <byte>

A base64 encoded opaque string returned in paginated responses.

Responses

Response samples

Content type
application/json
{
  • "legal-persons": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Create legal person

Creates a new Legal Person. A collection of Claims may be provided.

Authorizations:
api-key-auth
path Parameters
organization-id
required
string
Request Body schema: application/json
display-name
required
string (display-name) non-empty

A human readable label for an entity

legal-person-type
required
string (legal-person-type)
Enum: "individual" "corporation"

Specifies if the legal person is an individual or a corporation.

Array of mobile-number (object) or properties-origins-of-deposits (object) or individual-identity (object) or sole-trader (object) or property-types (object) or (commercial-property-industries (Not applicable (object) or List of industries and lines of business (object))) or (uk-company-register ((IM (both building-name and building-number (object) or only building-name (object) or only building-number (object))) or GB (object) or (GG (both building-name and building-number (object) or only building-name (object) or only building-number (object))) or (JE (both building-name and building-number (object) or only building-name (object) or only building-number (object))))) or individual-income (object) or business-website (object) or initial-deposit (object) or international-payments-countries (object) or company-telephone-number (object) or managed-properties (object) or person-with-significant-control (object) or business-industry (object) or verified-bank-account (object) or company-email-address (object) or tax-residency (object) or uk-financial-services-register (object) or non-tenant-balance (object) or business-description (object) or hmrc-register (object) or vat-registration (object) or hmo-license (object) or business-email-address (object) or client-money-protection-scheme (object) or individual-sources-of-funds (object) or nominal-person-with-significant-control (object) or hmo-verification (object) or commercial-property-ratio (object) or business-address (object) or (employment (self-employed (object) or retired (object) or unemployed (object) or employed (object))) or annual-turnover (object) or purposes-of-account (object) or sic-codes (object) or international-operations-countries (object) or sources-of-funds (object) or business-owner (object) or business-telephone-number (object) or business-start-date (object) or contact-details (object) or reliance-verification (object) or business-name (object) or individual-purposes-of-account (object) or nationality (object) or trading-name (object) or numbers-of-employees (object) or social-media (object) or trading-address (object) or company-website (object) or director (object) or alternative-number (object) or cash-payments (object) or tax-identification-number (object) or (individual-residence ((IM (both building-name and building-number (object) or only building-name (object) or only building-number (object))) or (GB (both building-name and building-number (object) or only building-name (object) or only building-number (object))) or (GG (both building-name and building-number (object) or only building-name (object) or only building-number (object))) or (JE (both building-name and building-number (object) or only building-name (object) or only building-number (object))))) (claim)

Responses

Request samples

Content type
application/json
{
  • "display-name": "string",
  • "legal-person-type": "individual",
  • "claims": [
    ]
}

Response samples

Content type
application/json
{
  • "latest-decision": {
    },
  • "legal-person-type": "individual",
  • "latest-risk-rating-url": "/v0/risk-ratings/rr.ICByaXNrLXJhdGluZy1pZA",
  • "display-name": "Company name",
  • "application-status": "referred",
  • "legal-person-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "legal-person-decisions-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA/decisions",
  • "status-changed-at": "2019-08-24T14:15:22Z",
  • "created-at": "2019-08-24T14:15:22Z",
  • "legal-person-claims-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA/claims",
  • "legal-person-bank-payees-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA/bank/payees",
  • "legal-person-verifications-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA/verifications",
  • "legal-name": "string",
  • "legal-person-documents-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA/documents"
}

Legal person history

Lists history of events for the given legal person

Lists history of events for the given legal person.

Authorizations:
api-key-auth
path Parameters
legal-person-id
required
string
query Parameters
page[size]
integer <int64> [ 1 .. 200 ]
page[after]
string <byte>

A base64 encoded opaque string returned in paginated responses.

page[before]
string <byte>

A base64 encoded opaque string returned in paginated responses.

Responses

Response samples

Content type
application/json
{
  • "legal-person-history": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Claims

A claim is an unverified data point or series of data points attached to a legal person. Claims are verified by running a verification against the legal person.

Deletes an existing claim about a Legal Person.

Deletes an existing claim about a Legal Person.

Authorizations:
api-key-auth
path Parameters
claim-id
required
string

Responses

List claims

Yields a list of all current claims about this Legal Person.

Authorizations:
api-key-auth
path Parameters
legal-person-id
required
string
query Parameters
filter[verification-status][eq]
string
Enum: "unverified" "verified"

The verification-status of a claim changes from "unverified" to "verified" when it has successfully been used in a verification as part of an accepted application. Claims of errored or declined applications are "unverified".

sort
string
Enum: "-created-at" "created-at"
page[size]
integer <int64> [ 1 .. 200 ]
page[after]
string <byte>

A base64 encoded opaque string returned in paginated responses.

page[before]
string <byte>

A base64 encoded opaque string returned in paginated responses.

Responses

Response samples

Content type
application/json
{
  • "claims": [
    ],
  • "links": {
    }
}

Create claim

Creates a new claim about a Legal Person.

Authorizations:
api-key-auth
path Parameters
legal-person-id
required
string
Request Body schema: application/json
Any of
mobile-number
required
string (mobile-number) (\+[1-9])?\d{1,14}
claim-type
required
string
Value: "mobile-number"

Responses

Request samples

Content type
application/json
Example
{
  • "mobile-number": "+442012345678",
  • "claim-type": "mobile-number"
}

Response samples

Content type
application/json
Example
{
  • "mobile-number": "+442012345678",
  • "claim-type": "mobile-number",
  • "created-at": "2019-08-24T14:15:22Z",
  • "claim-url": "/v0/claims/cl.ICAgICAgICBjbGFpbS1pZA"
}

Workflows

A workflow determines which checks will be run against a legal person as part of a verification

List organization workflows

Lists workflows for use when creating a verification.

Authorizations:
api-key-auth
path Parameters
organization-id
required
string
query Parameters
sort
string
Enum: "-created-at" "created-at"
page[size]
integer <int64> [ 1 .. 200 ]
page[after]
string <byte>

A base64 encoded opaque string returned in paginated responses.

page[before]
string <byte>

A base64 encoded opaque string returned in paginated responses.

Responses

Response samples

Content type
application/json
{
  • "workflows": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Get workflow

Fetch the workflow.

Authorizations:
api-key-auth
path Parameters
workflow-id
required
string

Responses

Response samples

Content type
application/json
{
  • "workflow-url": "/v0/workflows/wf.ICAgICB3b3JrZmxvdy1pZA",
  • "display-name": "string",
  • "description": "string",
  • "legal-person-type": "individual",
  • "created-at": "2019-08-24T14:15:22Z",
  • "required-claim-types": {
    },
  • "workflow-rules": [
    ]
}

Verifications

List verifications for a legal person

List verifications for the given legal person.

Authorizations:
api-key-auth
path Parameters
legal-person-id
required
string
query Parameters
sort
string
Enum: "-created-at" "created-at"
page[size]
integer <int64> [ 1 .. 200 ]
page[after]
string <byte>

A base64 encoded opaque string returned in paginated responses.

page[before]
string <byte>

A base64 encoded opaque string returned in paginated responses.

Responses

Response samples

Content type
application/json
{
  • "verifications": [
    ],
  • "links": {
    },
  • "meta": {
    }
}

Perform verification of a legal person

Initiates verification of the subject legal person.

The request body must include a workflow-url to determine checks to be performed by the verification. The workflow specified determines which claims must exist for the subject legal person, as identified in the request URL, and any associated legal persons (i.e. directors and people with significant control of a corporation).

These claims can be found in the required-claim-types field on a Workflow.

Once a verification is created, the system will perform checks on the claim details. The status of check processing is indicated by the verification-status in the response body. Initially it will be pending, and will transition through in-progress to a final status of checks-complete.

A verification-status of failed indicates something went wrong during check processing. You can initiate another verification to retry the check processing.

Authorizations:
api-key-auth
path Parameters
legal-person-id
required
string
Request Body schema: application/json
workflow-url
required
string (workflow-url)

A link to the workflow.

Responses

Request samples

Content type
application/json
{
  • "workflow-url": "/v0/workflows/wf.ICAgICB3b3JrZmxvdy1pZA"
}

Response samples

Content type
application/json
{
  • "verification-profiles-url": "/v0/verifications/vn.IHZlcmlmaWNhdGlvbi1pZA/profiles",
  • "verification-url": "/v0/verifications/vn.IHZlcmlmaWNhdGlvbi1pZA",
  • "verification-resources-url": "/v0/verifications/vn.IHZlcmlmaWNhdGlvbi1pZA/resources",
  • "updated-at": "2019-08-24T14:15:22Z",
  • "legal-person-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "workflow-url": "/v0/workflows/wf.ICAgICB3b3JrZmxvdy1pZA",
  • "created-at": "2019-08-24T14:15:22Z",
  • "verification-checks-url": "string",
  • "risk-rating": "high-risk",
  • "verification-status": "in-progress",
  • "verification-risk-assessments-url": "string"
}

Get verification

Fetch the verification.

Authorizations:
api-key-auth
path Parameters
verification-id
required
string

Responses

Response samples

Content type
application/json
{
  • "verification-profiles-url": "/v0/verifications/vn.IHZlcmlmaWNhdGlvbi1pZA/profiles",
  • "verification-url": "/v0/verifications/vn.IHZlcmlmaWNhdGlvbi1pZA",
  • "verification-resources-url": "/v0/verifications/vn.IHZlcmlmaWNhdGlvbi1pZA/resources",
  • "updated-at": "2019-08-24T14:15:22Z",
  • "legal-person-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "workflow-url": "/v0/workflows/wf.ICAgICB3b3JrZmxvdy1pZA",
  • "created-at": "2019-08-24T14:15:22Z",
  • "verification-checks-url": "/v0/verifications/vn.IHZlcmlmaWNhdGlvbi1pZA/checks",
  • "risk-rating": "high-risk",
  • "verification-status": "in-progress",
  • "verification-risk-assessments-url": "/v0/verifications/vn.IHZlcmlmaWNhdGlvbi1pZA/risk-assessments"
}

Get verification profiles

GET a verification's profiles. A profile is the collection of claims used in a verification.

Authorizations:
api-key-auth
path Parameters
verification-id
required
string

Responses

Response samples

Content type
application/json
{
  • "verification-subject-profile": {
    },
  • "verification-related-party-profiles": [
    ]
}

Get verification resources

Yields details of the verification resources for this verification.

Authorizations:
api-key-auth
path Parameters
verification-id
required
string
query Parameters
page[size]
integer <int64> [ 1 .. 200 ]
page[after]
string <byte>

A base64 encoded opaque string returned in paginated responses.

page[before]
string <byte>

A base64 encoded opaque string returned in paginated responses.

Responses

Response samples

Content type
application/json
{
  • "verification-url": "/v0/verifications/vn.IHZlcmlmaWNhdGlvbi1pZA",
  • "legal-person-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "organization-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA",
  • "verification-resources": [
    ],
  • "links": {
    }
}

Decisions

List decisions

Lists all decisions for the given legal-person.

Authorizations:
api-key-auth
path Parameters
legal-person-id
required
string
query Parameters
sort
string
Enum: "-created-at" "created-at"
page[size]
integer <int64> [ 1 .. 200 ]
page[after]
string <byte>

A base64 encoded opaque string returned in paginated responses.

page[before]
string <byte>

A base64 encoded opaque string returned in paginated responses.

Responses

Response samples

Content type
application/json
{
  • "decisions": [
    ],
  • "links": {
    }
}

Create decision

Creates a decision against the legal person.

The provided verification must have a verification-status of checks-complete, otherwise a 422 is served.

When a decision is successfully created, the legal person's application-status is updated accordingly.

Multiple decisions may be made against the same legal person.

Authorizations:
api-key-auth
path Parameters
legal-person-id
required
string
Request Body schema: application/json
verification-url
required
string (verification-url)

A link to the verification.

decision-outcome
required
string (decision-outcome)
Enum: "accepted" "declined"
decision-notes
required
string (decision-notes)

Free-text field to explain the reasons behind the decision.

Responses

Request samples

Content type
application/json
{
  • "verification-url": "/v0/verifications/vn.IHZlcmlmaWNhdGlvbi1pZA",
  • "decision-outcome": "accepted",
  • "decision-notes": "string"
}

Response samples

Content type
application/json
{
  • "decision-outcome": "accepted",
  • "decision-notes": "string",
  • "verification-url": "/v0/verifications/vn.IHZlcmlmaWNhdGlvbi1pZA",
  • "legal-person-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "created-at": "2019-08-24T14:15:22Z",
  • "decision-maker": "system",
  • "decision-user-url": "/v0/users/ur.ICAgICAgICAgdXNlci1pZA",
  • "decision-ops-user": "griffin-ops-user",
  • "decision-user-username": "user@example.com"
}

Companies House

Lookup company

Lookup Companies House company by company number. Includes information about the company, its directors, and persons with significant control.

Authorizations:
api-key-auth
path Parameters
company-number
required
string

UK Companies House company number

Responses

Response samples

Content type
application/json
{
  • "company-address": {
    },
  • "date-of-latest-accounts": "2019-08-24",
  • "entity-name": "string",
  • "directors": [],
  • "date-of-latest-confirmation-statement": "2019-08-24",
  • "corporation-type": "private-limited-guarant-nsc-limited-exemption",
  • "company-status": "dissolved",
  • "accounts-overdue": true,
  • "sic-codes": [
    ],
  • "persons-with-significant-control": [],
  • "confirmation-statement-overdue": true,
  • "date-of-incorporation": "2019-08-24",
  • "entity-registration-number": "string"
}

Reliance onboarding

Reliance onboarding allows you to create and submit an application on behalf of your customer, using information about them you have already collected. For more information, checkout our onboarding guides.

Get onboarding application

Fetch an onboarding application.

Authorizations:
api-key-auth
path Parameters
onboarding-application-id
required
string

Responses

Response samples

Content type
application/json
Example
{
  • "onboarding-application-url": "/v0/onboarding/applications/oa.b25ib2FyZGluZy1hcHBsaQ",
  • "created-at": "2019-08-24T14:15:22Z",
  • "workflow-url": "/v0/workflows/wf.ICAgICB3b3JrZmxvdy1pZA",
  • "legal-person-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "verification-url": "/v0/verifications/vn.IHZlcmlmaWNhdGlvbi1pZA",
  • "onboarding-application-status": "processing"
}

Create an onboarding application

Create an onboarding application and submit it for processing.

The request body must include a workflow-url to determine checks to be performed by the verification. The workflow specified determines which claims must exist for the subject profile, and any related profile (i.e. directors and people with significant control of a corporation).

At the moment we only support 3 reliance workflows: Reliance LTD Company, Reliance Individual and Reliance Sole Trader.

You need to provide different claims depending on the type of customer you wish to onboard via reliance.

LTD Company Individual Sole trader
Subject profile:
uk-company-register
trading-address
reliance-verification

Related profiles:
individual-identity
individual-residence
reliance-verification		 Subject profile:
individual-identity
individual-residence
reliance-verification		 Subject profile:
business-name
individual-identity
individual-residence
reliance-verification

For more information, check out our onboarding guides.

Authorizations:
api-key-auth
path Parameters
organization-id
required
string
Request Body schema: application/json
workflow-url
required
string (workflow-url)

A link to the workflow.

required
object (subject-profile)

The subject profile to be onboarded. Directors and PSCs must be declared via subject-association in related profiles instead of director & PSC claims in the subject profile.

Array of objects (related-profiles)

A list profiles related to the subject (e.g. directors, person with significant control).

Responses

Request samples

Content type
application/json
{}

Response samples

Content type
application/json
{
  • "onboarding-application-url": "/v0/onboarding/applications/oa.b25ib2FyZGluZy1hcHBsaQ",
  • "onboarding-application-status": "processing"
}

Bank accounts

Bank accounts are used for managing funds. You can open different types of bank account using the "bank-product-type" field. Some account types are for managing your own funds and some are for managing your customers' funds. For information, check out our guides for opening bank accounts:

Get bank account

Fetch a bank account

Authorizations:
api-key-auth
path Parameters
bank-account-id
required
string

Responses

Response samples

Content type
application/json
{
  • "account-submissions-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/submissions",
  • "account-restricted": true,
  • "account-payments-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/payments",
  • "pooled-account-memberships-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/membership",
  • "account-admissions-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/admissions",
  • "bank-product-type": "savings-account",
  • "display-name": "Reserve a/c",
  • "controller-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "pooled-funds": true,
  • "account-status": "closing",
  • "client-money-type": "designated-client-fund",
  • "owner-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "closed-at": "2019-08-24T14:15:22Z",
  • "created-at": "2019-08-24T14:15:22Z",
  • "opened-at": "2019-08-24T14:15:22Z",
  • "close-account-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/actions/close",
  • "available-balance": {
    },
  • "pooled-account-membership-updates-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/membership-updates",
  • "bank-addresses": [
    ],
  • "account-transactions-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/transactions",
  • "account-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA",
  • "beneficiary-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "primary-account": false,
  • "account-balance": {
    },
  • "savings-type": "easy-access"
}

Update a bank account

Update a bank account

Authorizations:
api-key-auth
path Parameters
bank-account-id
required
string
Request Body schema: application/json
display-name
required
string (display-name) non-empty

A human readable label for an entity

Responses

Request samples

Content type
application/json
{
  • "display-name": "string"
}

Response samples

Content type
application/json
{
  • "account-submissions-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/submissions",
  • "account-restricted": true,
  • "account-payments-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/payments",
  • "pooled-account-memberships-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/membership",
  • "account-admissions-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/admissions",
  • "bank-product-type": "savings-account",
  • "display-name": "Reserve a/c",
  • "controller-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "pooled-funds": true,
  • "account-status": "closing",
  • "client-money-type": "designated-client-fund",
  • "owner-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "closed-at": "2019-08-24T14:15:22Z",
  • "created-at": "2019-08-24T14:15:22Z",
  • "opened-at": "2019-08-24T14:15:22Z",
  • "close-account-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/actions/close",
  • "available-balance": {
    },
  • "pooled-account-membership-updates-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/membership-updates",
  • "bank-addresses": [
    ],
  • "account-transactions-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/transactions",
  • "account-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA",
  • "beneficiary-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "primary-account": false,
  • "account-balance": {
    },
  • "savings-type": "easy-access"
}

Close a bank account

Close a bank account

Authorizations:
api-key-auth
path Parameters
bank-account-id
required
string

Responses

Response samples

Content type
application/json
{
  • "account-submissions-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/submissions",
  • "account-restricted": true,
  • "account-payments-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/payments",
  • "pooled-account-memberships-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/membership",
  • "account-admissions-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/admissions",
  • "bank-product-type": "savings-account",
  • "display-name": "Reserve a/c",
  • "controller-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "pooled-funds": true,
  • "account-status": "closing",
  • "client-money-type": "designated-client-fund",
  • "owner-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "closed-at": "2019-08-24T14:15:22Z",
  • "created-at": "2019-08-24T14:15:22Z",
  • "opened-at": "2019-08-24T14:15:22Z",
  • "close-account-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/actions/close",
  • "available-balance": {
    },
  • "pooled-account-membership-updates-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/membership-updates",
  • "bank-addresses": [
    ],
  • "account-transactions-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/transactions",
  • "account-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA",
  • "beneficiary-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "primary-account": false,
  • "account-balance": {
    },
  • "savings-type": "easy-access"
}

List bank accounts

Yields a list of all bank accounts under the control of this Organization.

Authorizations:
api-key-auth
path Parameters
organization-id
required
string
query Parameters
filter[beneficiary-url][eq]
string

Link to the legal person that represents the beneficiary of the account.

page[size]
integer <int64> [ 1 .. 200 ]
include
Array of strings
Items Enum: "beneficiary" "owner"

For each bank account returned, include its owner and/or beneficiary in the response under the included.legal-persons attribute.

filter[account-status][in][]
Array of strings
Items Enum: "closing" "open" "closed" "opening"
sort
string
Enum: "-created-at" "display-name" "created-at" "-display-name"
page[after]
string <byte>

A base64 encoded opaque string returned in paginated responses.

filter[account-restricted][in][]
boolean

Specifies whether the bank account has restrictions applied by Griffin.

filter[pooled-funds][eq]
boolean

Specifies whether the bank account holds funds belonging to multiple beneficiaries.

filter[bank-product-type][in][]
Array of strings
Items Enum: "savings-account" "client-money-account" "safeguarding-account" "embedded-account" "operational-account"
filter[owner-url][eq]
string

Link to the legal person that represents the owner of the account.

page[before]
string <byte>

A base64 encoded opaque string returned in paginated responses.

Responses

Response samples

Content type
application/json
{
  • "accounts": [
    ],
  • "links": {
    },
  • "included": null
}

Open bank account

Open a new bank account

Authorizations:
api-key-auth
path Parameters
organization-id
required
string
Request Body schema: application/json
Any of
Any of
required
owner-url (string) or owner-url (string) (owner-url)

Link to the legal person that represents the owner of the account.

display-name
string (display-name) non-empty

A human readable label for an entity

savings-type
required
string
Value: "easy-access"
bank-product-type
required
string
Value: "savings-account"

Responses

Request samples

Content type
application/json
Example
{
  • "bank-product-type": "savings-account",
  • "owner-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "display-name": "string",
  • "savings-type": "easy-access"
}

Response samples

Content type
application/json
{
  • "account-submissions-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/submissions",
  • "account-restricted": true,
  • "account-payments-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/payments",
  • "pooled-account-memberships-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/membership",
  • "account-admissions-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/admissions",
  • "bank-product-type": "savings-account",
  • "display-name": "Reserve a/c",
  • "controller-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "pooled-funds": true,
  • "account-status": "closing",
  • "client-money-type": "designated-client-fund",
  • "owner-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "closed-at": "2019-08-24T14:15:22Z",
  • "created-at": "2019-08-24T14:15:22Z",
  • "opened-at": "2019-08-24T14:15:22Z",
  • "close-account-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/actions/close",
  • "available-balance": {
    },
  • "pooled-account-membership-updates-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/membership-updates",
  • "bank-addresses": [
    ],
  • "account-transactions-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/transactions",
  • "account-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA",
  • "beneficiary-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "primary-account": false,
  • "account-balance": {
    },
  • "savings-type": "easy-access"
}

Pooled account membership

List legal person in a pooled account membership

List legal persons in a pooled account membership

Authorizations:
api-key-auth
path Parameters
bank-account-id
required
string
query Parameters
include
Array of strings
Items Enum: "latest-risk-rating" "legal-person" "latest-verification"

For each member returned, include its legal person details, latest verification (if one exists), and/or latest risk rating (if one exists) in the response under the included attribute.

page[size]
integer <int64> [ 1 .. 200 ]
page[after]
string <byte>

A base64 encoded opaque string returned in paginated responses.

page[before]
string <byte>

A base64 encoded opaque string returned in paginated responses.

Responses

Response samples

Content type
application/json
{
  • "pool-members": [
    ],
  • "links": {
    },
  • "meta": {
    },
  • "included": {
    }
}

Manage pooled account members

Add and update the legal persons in a pooled account membership. Limited to 1000 legal persons per operation.

Authorizations:
api-key-auth
path Parameters
bank-account-id
required
string
Request Body schema: application/json
required
Array of legal-person-url (string) or legal-person-url (string) (legal-person-url)
required
Array of legal-person-url (string) or legal-person-url (string) (legal-person-url)

Responses

Request samples

Content type
application/json
{
  • "additions": [
    ],
  • "deletions": [
    ]
}

Response samples

Content type
application/json
{
  • "pooled-account-memberships-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA/membership"
}

Payments

A payment captures the intent to move funds from a bank account to another bank account. Outbound payments can be made from your bank account to a payee. Griffin accepts inbound payments to your bank accounts on your behalf. If it's your first time using our payments API, check out our guide for making a payment

Get payment admission

Yields an admission.

Authorizations:
api-key-auth
path Parameters
admission-id
required
string

Responses

Response samples

Content type
application/json
{
  • "admission-status": "processing",
  • "admission-scheme-information": {
    },
  • "payment-url": "/v0/payments/pm.ICAgICAgcGF5bWVudC1pZA",
  • "created-at": "2019-08-24T14:15:22Z",
  • "admission-url": "/v0/admissions/pa.ICAgIGFkbWlzc2lvbi1pZA",
  • "unique-scheme-identifier": "PGIT2IS7AJG77D2HK23020240212826NatWes ",
  • "account-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA",
  • "original-unique-scheme-identifier": "PGIT2IS7AJG77D2HK23020240212826NatWes "
}

List bank account admissions

Lists admissions targeting a bank account

Authorizations:
api-key-auth
path Parameters
bank-account-id
required
string
query Parameters
sort
string
Enum: "-created-at" "created-at"
page[size]
integer <int64> [ 1 .. 200 ]
page[before]
string <byte>

A base64 encoded opaque string returned in paginated responses.

page[after]
string <byte>

A base64 encoded opaque string returned in paginated responses.

filter[created-at][lte]
string <date-time>

Return only resources with a created-at less than or equal to the given timestamp.

filter[created-at][lt]
string <date-time>

Return only resources with a created-at less than the given timestamp.

filter[created-at][gte]
string <date-time>

Return only resources with a created-at greater than or equal to the given timestamp.

filter[created-at][gt]
string <date-time>

Return only resources with a created-at greater than the given timestamp.

filter[admission-status][in]
Array of strings
Items Enum: "processing" "returned" "delivered"

Responses

Response samples

Content type
application/json
{
  • "admissions": [
    ],
  • "links": {
    }
}

List bank account payments

Lists payments made from a bank account.

Authorizations:
api-key-auth
path Parameters
bank-account-id
required
string
query Parameters
sort
string
Enum: "-created-at" "created-at"
page[size]
integer <int64> [ 1 .. 200 ]
page[before]
string <byte>

A base64 encoded opaque string returned in paginated responses.

page[after]
string <byte>

A base64 encoded opaque string returned in paginated responses.

filter[created-at][lte]
string <date-time>

Return only resources with a created-at less than or equal to the given timestamp.

filter[created-at][lt]
string <date-time>

Return only resources with a created-at less than the given timestamp.

filter[created-at][gte]
string <date-time>

Return only resources with a created-at greater than or equal to the given timestamp.

filter[created-at][gt]
string <date-time>

Return only resources with a created-at greater than the given timestamp.

Responses

Response samples

Content type
application/json
{
  • "payments": [
    ],
  • "links": {
    }
}

Create payment

Registers a new payment request for the bank account

Authorizations:
api-key-auth
path Parameters
bank-account-id
required
string
Request Body schema: application/json
required
payee (object) or griffin-bank-account (object) or uk-domestic (object) (creditor)
required
object (payment-amount)

Compound value representing both the currency and amount of money being sent.

payment-reference
string (payment-reference) [ 1 .. 35 ] characters
Default: "Sent from X"

Free-text field to help identify and categorise payments.

X is the legal person who owns the account. This will be the entity-name or business-name for companies, or the given-name and surname for individuals. This is also subject to a 35 character limit, so longer names may be cut off. When making a payment to a payee with an associated Confirmation of Payee request containing secondary reference data (SRD), the SRD will take precedence over any payment-reference set in the payment creation request.

Responses

Request samples

Content type
application/json
{
  • "creditor": {
    },
  • "payment-amount": {
    },
  • "payment-reference": "test reference"
}

Response samples

Content type
application/json
{
  • "creditor": {
    },
  • "rejected-at": "2019-08-24T14:15:22Z",
  • "rejected-by-url": "/v0/users/ur.ICAgICAgICAgdXNlci1pZA",
  • "payment-direction": "inbound-payment",
  • "created-by-url": "/v0/users/ur.ICAgICAgICAgdXNlci1pZA",
  • "created-via": "api",
  • "created-at": "2019-08-24T14:15:22Z",
  • "payment-url": "/v0/payments/pm.ICAgICAgcGF5bWVudC1pZA",
  • "payment-reference": "test reference",
  • "payment-amount": {
    },
  • "ultimate-debtor": {
    },
  • "payment-admissions-url": "/v0/payments/pm.ICAgICAgcGF5bWVudC1pZA/admissions",
  • "payment-submissions-url": "/v0/payments/pm.ICAgICAgcGF5bWVudC1pZA/submissions",
  • "debtor": {
    },
  • "rejection-reason": "string"
}

List bank account submissions

Lists submissions originating from a bank account

Authorizations:
api-key-auth
path Parameters
bank-account-id
required
string
query Parameters
sort
string
Enum: "-created-at" "created-at"
page[size]
integer <int64> [ 1 .. 200 ]
page[before]
string <byte>

A base64 encoded opaque string returned in paginated responses.

page[after]
string <byte>

A base64 encoded opaque string returned in paginated responses.

filter[submission-status][in]
Array of strings
Items Enum: "scheduled" "failed" "processing" "returned" "delivered"
filter[created-at][lte]
string <date-time>

Return only resources with a created-at less than or equal to the given timestamp.

filter[created-at][lt]
string <date-time>

Return only resources with a created-at less than the given timestamp.

filter[created-at][gte]
string <date-time>

Return only resources with a created-at greater than or equal to the given timestamp.

filter[created-at][gt]
string <date-time>

Return only resources with a created-at greater than the given timestamp.

Responses

Response samples

Content type
application/json
{
  • "submissions": [
    ],
  • "links": {
    }
}

Get payment

Yields payment details

Authorizations:
api-key-auth
path Parameters
payment-id
required
string

Responses

Response samples

Content type
application/json
{
  • "creditor": {
    },
  • "rejected-at": "2019-08-24T14:15:22Z",
  • "rejected-by-url": "/v0/users/ur.ICAgICAgICAgdXNlci1pZA",
  • "payment-direction": "inbound-payment",
  • "created-by-url": "/v0/users/ur.ICAgICAgICAgdXNlci1pZA",
  • "created-via": "api",
  • "created-at": "2019-08-24T14:15:22Z",
  • "payment-url": "/v0/payments/pm.ICAgICAgcGF5bWVudC1pZA",
  • "payment-reference": "test reference",
  • "payment-amount": {
    },
  • "ultimate-debtor": {
    },
  • "payment-admissions-url": "/v0/payments/pm.ICAgICAgcGF5bWVudC1pZA/admissions",
  • "payment-submissions-url": "/v0/payments/pm.ICAgICAgcGF5bWVudC1pZA/submissions",
  • "debtor": {
    },
  • "rejection-reason": "string"
}

Updates a payment

Updates a payment

Authorizations:
api-key-auth
path Parameters
payment-id
required
string
Request Body schema: application/json
rejection-reason
string or null (non-empty-string) non-empty

Responses

Request samples

Content type
application/json
{
  • "rejection-reason": "string"
}

List payment admissions

Lists admissions for a payment. A payment may have at most one admission.

Authorizations:
api-key-auth
path Parameters
payment-id
required
string

Responses

Response samples

Content type
application/json
{
  • "admissions": [
    ]
}

List payment submissions

Lists submissions for a payment. The presence of a submission means that the payment has been submitted.

Authorizations:
api-key-auth
path Parameters
payment-id
required
string

Responses

Response samples

Content type
application/json
{
  • "submissions": [
    ]
}

Submit payment

Submits a previously created payment for execution.

Please note: An organization may have up to 3 concurrent API requests for submitting payments from the same bank account. Exceeding this limit will result in additional requests receiving a 429 'Too Many Requests' HTTP status code. If this occurs, wait for other in-flight requests to complete before retrying. This concurrency limit is specific to each bank account; submissions across different bank accounts are not affected.

Authorizations:
api-key-auth
path Parameters
payment-id
required
string
Request Body schema: application/json
payment-scheme
string (payment-scheme)
Value: "fps"

Specifies the scheme over which a payment is executed.

Responses

Request samples

Content type
application/json
{
  • "payment-scheme": "fps"
}

Response samples

Content type
application/json
{
  • "submission-status": "scheduled",
  • "submission-scheme-information": {
    },
  • "payment-url": "/v0/payments/pm.ICAgICAgcGF5bWVudC1pZA",
  • "created-at": "2019-08-24T14:15:22Z",
  • "submission-url": "/v0/submissions/ps.ICAgc3VibWlzc2lvbi1pZA",
  • "account-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA",
  • "unique-scheme-identifier": "PGIT2IS7AJG77D2HK23020240212826NatWes ",
  • "scheduled-at": "2019-08-24T14:15:22Z"
}

Get payment submission

Yields a submission.

Authorizations:
api-key-auth
path Parameters
submission-id
required
string

Responses

Response samples

Content type
application/json
{
  • "submission-status": "scheduled",
  • "submission-scheme-information": {
    },
  • "payment-url": "/v0/payments/pm.ICAgICAgcGF5bWVudC1pZA",
  • "created-at": "2019-08-24T14:15:22Z",
  • "submission-url": "/v0/submissions/ps.ICAgc3VibWlzc2lvbi1pZA",
  • "account-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA",
  • "unique-scheme-identifier": "PGIT2IS7AJG77D2HK23020240212826NatWes ",
  • "scheduled-at": "2019-08-24T14:15:22Z"
}

Transactions

The transaction resource represents any form of activity in a bank account that results in a change to the account’s balance. Transactions can be categorised by their type (balance-change-origin-type). Here is the enumeration of types of bank transactions:

  1. payment: Sending funds to, or receiving funds from, another bank account.
  2. transfer: Sending funds to, or receiving funds from, another Griffin bank account.
  3. manual-payment: A transfer initiated by Griffin operations.
  4. interest: Money paid to the account holder based on deposited funds.
  5. commission: Money paid to the organisation based on their customers' deposited funds.
  6. fee: Charges applied to the bank account by Griffin.
  7. deposit: [SANDBOX ONLY] Adding funds to a sandbox bank account when it is created.

List transactions

Lists balance changes on a bank account. Use an Accept: application/vnd.griffin+xero-csv header to receive balance changes in a CSV format suitable for importing into Xero. This endpoint will only return CSV files with up to 100,000 rows to match the Xero import limit. To ensure that no transactions are missing from the CSV export, specify a time period that contains fewer than 100,000 transactions.

Authorizations:
api-key-auth
path Parameters
bank-account-id
required
string
query Parameters
sort
string
Enum: "-created-at" "processed-at" "-processed-at" "created-at"
page[size]
integer <int64> [ 1 .. 200 ]
page[before]
string <byte>

A base64 encoded opaque string returned in paginated responses.

page[after]
string <byte>

A base64 encoded opaque string returned in paginated responses.

include
string
Value: "payment"

For each transaction returned, include its payment (if one exists) in the response under the included attribute.

filter[processed-at][lte]
string <date-time>

Return only transactions processed at or before the given timestamp.

filter[processed-at][lt]
string <date-time>

Return only transactions processed before the given timestamp.

filter[processed-at][gte]
string <date-time>

Return only transactions processed at or after the given timestamp.

filter[processed-at][gt]
string <date-time>

Return only transactions processed after the given timestamp.

Responses

Response samples

Content type
application/json
{
  • "account-transactions": [
    ],
  • "links": {
    },
  • "included": null
}

Get transaction

Yields a bank account transaction

Authorizations:
api-key-auth
path Parameters
transaction-id
required
string

Responses

Response samples

Content type
application/json
{
  • "account-transaction-url": "/v0/bank/transactions/tr.ICB0cmFuc2FjdGlvbi1pZA",
  • "processed-at": "2019-08-24T14:15:22Z",
  • "post-datetime": "2019-08-24T14:15:22Z",
  • "balance-change-direction": "credit",
  • "effective-at": "2019-08-24T14:15:22Z",
  • "transaction-origin-type": "interest",
  • "payment-url": "/v0/payments/pm.ICAgICAgcGF5bWVudC1pZA",
  • "reference": "Restaurant Charge - Sushi Palace",
  • "account-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA",
  • "balance-change": {
    },
  • "account-balance": {
    },
  • "description": "Interest earned in April from Alexa account."
}

Payees

A payee is the person or business to whom you are paying money. When you create a payee, you need to provide their name ("account-holder"), and their bank account number ("account-number") and sort code ("bank-id").

You may also register the outcome of a Confirmation of Payee (CoP) check with your payee by supplying a cop-request-url.

Read more about payees in our guides.

List legal person payees

Lists payees belonging to the legal person.

Authorizations:
api-key-auth
path Parameters
legal-person-id
required
string
query Parameters
sort
string
Enum: "-created-at" "created-at"
include
Array of strings
Items Value: "cop-requests"

For each payee returned, include its Confirmation of Payee (CoP) details (if they exist) in the response under the included attribute.

page[size]
integer <int64> [ 1 .. 200 ]
page[after]
string <byte>

A base64 encoded opaque string returned in paginated responses.

page[before]
string <byte>

A base64 encoded opaque string returned in paginated responses.

Responses

Response samples

Content type
application/json
{
  • "payees": [
    ],
  • "links": {
    },
  • "included": null
}

Create payee

Registers a new payee with a legal person.

You may associate the outcome of a CoP request with the payee by supplying a cop-request-url.

Authorizations:
api-key-auth
path Parameters
legal-person-id
required
string
Request Body schema: application/json
account-holder
required
string (account-holder) non-empty

The name of the account holder.

account-number
required
string (account-number) = 8 characters ^[0-9]{8}$

Must be a UK account number.

bank-id
required
string (bank-id) = 6 characters ^[0-9]{6}$

Must be a UK Sort Code.

cop-request-url (string) or cop-request-url (string) (cop-request-url)

Link to a CoP request.

Responses

Request samples

Content type
application/json
{
  • "account-holder": "string",
  • "account-number": "12345678",
  • "bank-id": "123456",
  • "cop-request-url": "/v0/cop-request/cp.ICBjb3AtcmVxdWVzdC1pZA"
}

Response samples

Content type
application/json
{
  • "cop-request-url": "/v0/cop-request/cp.ICBjb3AtcmVxdWVzdC1pZA",
  • "payee-url": "/v0/payees/pe.ICAgICAgICBwYXllZS1pZA",
  • "account-number": "12345678",
  • "account-holder": "string",
  • "legal-person-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "bank-id": "123456",
  • "created-at": "2019-08-24T14:15:22Z",
  • "account-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA",
  • "payee-status": "deactivated",
  • "country-code": "GB"
}

Get payee

Returns the payee details.

Authorizations:
api-key-auth
path Parameters
payee-id
required
string

Responses

Response samples

Content type
application/json
{
  • "cop-request-url": "/v0/cop-request/cp.ICBjb3AtcmVxdWVzdC1pZA",
  • "payee-url": "/v0/payees/pe.ICAgICAgICBwYXllZS1pZA",
  • "account-number": "12345678",
  • "account-holder": "string",
  • "legal-person-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "bank-id": "123456",
  • "created-at": "2019-08-24T14:15:22Z",
  • "account-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA",
  • "payee-status": "deactivated",
  • "country-code": "GB"
}

Update payee

Updates an existing payee.

You can update a payee with the outcome of a CoP request by supplying a cop-request-url.

A payee can be deactivated by updating the payee-status of an active payee to deactivated. Any attempt to create or submit a payment to a deactivated payee will fail.

A 422 is served when attempting to deactivate an already-deactivated payee.

Authorizations:
api-key-auth
path Parameters
payee-id
required
string
Request Body schema: application/json
cop-request-url (string) or cop-request-url (string) (cop-request-url)

Link to a CoP request.

payee-status
string (payee-status)
Value: "deactivated"

The status of the payee; you can only make payments to active payees.

Responses

Request samples

Content type
application/json
{
  • "cop-request-url": "/v0/cop-request/cp.ICBjb3AtcmVxdWVzdC1pZA",
  • "payee-status": "deactivated"
}

Response samples

Content type
application/json
{
  • "cop-request-url": "/v0/cop-request/cp.ICBjb3AtcmVxdWVzdC1pZA",
  • "payee-url": "/v0/payees/pe.ICAgICAgICBwYXllZS1pZA",
  • "account-number": "12345678",
  • "account-holder": "string",
  • "legal-person-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "bank-id": "123456",
  • "created-at": "2019-08-24T14:15:22Z",
  • "account-url": "/v0/bank/accounts/ba.IGJhbmstYWNjb3VudC1pZA",
  • "payee-status": "deactivated",
  • "country-code": "GB"
}

Confirmation of payee

Get a CoP request

Returns the result of a Confirmation of Payee (CoP) request.

Authorizations:
api-key-auth
path Parameters
cop-request-id
required
string

Responses

Response samples

Content type
application/json
{
  • "cop-request-url": "/v0/cop-request/cp.ICBjb3AtcmVxdWVzdC1pZA",
  • "account": {
    },
  • "cop-response": {
    }
}

Create a CoP request

Create a Confirmation of Payee (CoP) request.

Authorizations:
api-key-auth
path Parameters
organization-id
required
string
Request Body schema: application/json
account-number
required
string (account-number) = 8 characters ^[0-9]{8}$

Must be a UK account number.

bank-id
required
string (bank-id) = 6 characters ^[0-9]{6}$

Must be a UK Sort Code.

account-classification
required
string (account-classification)
Enum: "personal" "business"
name
required
any (name)

The name of the payee.

required
requester-legal-person-url (string) or requester-legal-person-url (string) (requester-legal-person-url)

A contextual link to the legal person.

secondary-reference-data
any (secondary-reference-data)

Secondary reference data, such as a building society roll number or a credit card number.

Responses

Request samples

Content type
application/json
{
  • "account-number": "12345678",
  • "bank-id": "123456",
  • "account-classification": "personal",
  • "name": "John Smith",
  • "requester-legal-person-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "secondary-reference-data": "1234567890"
}

Response samples

Content type
application/json
{
  • "cop-request-url": "/v0/cop-request/cp.ICBjb3AtcmVxdWVzdC1pZA",
  • "account": {
    },
  • "cop-response": {
    }
}

[Alpha] Simulate a CoP request

Simulate the creation of a CoP Request. Note: This is an alpha API and may change anytime.

Authorizations:
api-key-auth
path Parameters
organization-id
required
string
cop-simulation-type
required
string
Enum: "match-name-business-personal" "account-not-found" "full-match" "no-match-name" "no-match-secondary-ref" "close-match-name-business-personal" "close-match-name-personal-business" "account-switched" "close-match-name" "account-not-supported" "match-name-personal-business"

The type of simulation to run.

Request Body schema: application/json
account-number
required
string (account-number) = 8 characters ^[0-9]{8}$

Must be a UK account number.

bank-id
required
string (bank-id) = 6 characters ^[0-9]{6}$

Must be a UK Sort Code.

account-classification
required
string (account-classification)
Enum: "personal" "business"
name
required
any (name)

The name of the payee.

required
requester-legal-person-url (string) or requester-legal-person-url (string) (requester-legal-person-url)

A contextual link to the legal person.

secondary-reference-data
any (secondary-reference-data)

Secondary reference data, such as a building society roll number or a credit card number.

Responses

Request samples

Content type
application/json
{
  • "account-number": "12345678",
  • "bank-id": "123456",
  • "account-classification": "personal",
  • "name": "John Smith",
  • "requester-legal-person-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "secondary-reference-data": "1234567890"
}

Response samples

Content type
application/json
{
  • "cop-request-url": "/v0/cop-request/cp.ICBjb3AtcmVxdWVzdC1pZA",
  • "account": {
    },
  • "cop-response": {
    }
}

Organizations

The organization resource represents your company and acts as a container for the majority of other resources, including legal persons and bank accounts. When you register for an account with Griffin, a new organization is created alongside your user account (unless you have received an invitation to join an existing organization). Your user account is associated with an organization via a membership.

Your organization can be in one of two modes:

  • test-mode for organizations created when you sign up for the sandbox.
  • live-mode for when you go live with Griffin.

Learn more about sandbox vs. live mode.

Get organization

Yields the organization details

Authorizations:
api-key-auth
path Parameters
organization-id
required
string

Responses

Response samples

Content type
application/json
{
  • "own-legal-person-url": "/v0/legal-persons/lp.IGxlZ2FsLXBlcnNvbi1pZA",
  • "organization-mode": "test-mode",
  • "organization-memberships-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA/memberships",
  • "organization-invitations-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA/invitations",
  • "organization-onboarding-applications-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA/onboarding/applications",
  • "display-name": "Company Org",
  • "organization-api-keys-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA/api-keys",
  • "organization-live-access-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA/live-access",
  • "organization-webhooks-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA/webhooks",
  • "organization-workflows-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA/workflows",
  • "organization-bank-accounts-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA/bank/accounts",
  • "available-roles": [
    ],
  • "organization-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA",
  • "organization-individuals-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA/individuals",
  • "organization-corporations-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA/corporations",
  • "organization-legal-persons-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA/legal-persons",
  • "organization-events-url": "/v0/organizations/og.IG9yZ2FuaXphdGlvbi1pZA/events"
}

Users

Users represent individuals who use the Griffin platform. A user must have a membership in at least one organization, and may have memberships in multiple organizations.

Get user

Get the User resource for the current user.

Authorizations:
api-key-auth
path Parameters
user-id
required
string

Responses

Response samples

Content type
application/json
{
  • "user-email": "user@example.com",
  • "user-url": "/v0/users/ur.ICAgICAgICAgdXNlci1pZA",
  • "user-username": "user@example.com",
  • "api-keys-url": "/v0/users/ur.ICAgICAgICAgdXNlci1pZA/api-keys",
  • "user-memberships-url": "/v0/users/ur.ICAgICAgICAgdXNlci1pZA/memberships",
  • "given-name": "string",
  • "surname": "string"
}

Roles

A role represents a pre-defined set of capabilities that can be assigned to a user via their membership in an organization. By default, the first user in an organization gets assigned an administration role. Subsequent users get assigned the most limited set of capabilities.

List membership roles

Returns the roles assigned to this membership.

Authorizations:
api-key-auth
path Parameters
membership-id
required
string

Responses

Response samples

Content type
application/json
{
  • "roles": [
    ]
}

Update role

Assigns roles to the membership.

A 422 Unprocessable Entity is served if either:

  • one role url provided in the body is not in the Organisations "available-roles"
  • the request attempts to remove the last admin role of the organization, thus making the organisation unusable.
Authorizations:
api-key-auth
path Parameters
membership-id
required
string
Request Body schema: application/json
required
Array of role-url (string) or role-url (string) (role-url)
Array
Any of
string (role-url)

Link to the role.

Responses

Request samples

Content type
application/json
{
  • "role-urls": [
    ]
}

Response samples

Content type
application/json
{
  • "roles": [
    ]
}

List roles

Yields a list of all Role resources.

Responses

Response samples

Content type
application/json
{
  • "roles": [
    ]
}

Get role

Yields the Role resource.

path Parameters
role-id
required
string

Responses

Response samples

Content type
application/json
{
  • "display-name": "string",
  • "description": "string",
  • "role-url": "/v0/roles/re.ICAgICAgICAgcm9sZS1pZA",
  • "role-category": "string"
}

Memberships

Memberships represents the relationship between a user and an organization. A membership must have at least one role assigned to it.

Get membership

Returns the user's membership information.

Authorizations:
api-key-auth
path Parameters
membership-id
required
string

Responses

Response samples

Content type
application/json
{
  • "membership-url": "/v0/memberships/mp.ICAgbWVtYmVyc2hpcC1pZA",
  • "membership-roles-url": "/v0/memberships/mp.ICAgbWVtYmVyc2hpcC1pZA/roles",
  • "organization": {
    },
  • "roles": [
    ],
  • "user": {
    },
  • "created-at": "2019-08-24T14:15:22Z"
}

Delete membership

Removes a user from an organization.

Authorizations:
api-key-auth
path Parameters
membership-id
required
string

Responses

List organization memberships

Returns this organization's memberships.

Authorizations:
api-key-auth
path Parameters
organization-id
required
string
query Parameters
sort
string
Enum: "-created-at" "created-at"
page[size]
integer <int64> [ 1 .. 200 ]
page[after]
string <byte>

A base64 encoded opaque string returned in paginated responses.

page[before]
string <byte>

A base64 encoded opaque string returned in paginated responses.

Responses

Response samples

Content type
application/json
{
  • "memberships": [
    ],
  • "links": {
    }
}

List user memberships

Returns this user's memberships.

Authorizations:
api-key-auth
path Parameters
user-id
required
string
query Parameters
sort
string
Enum: "-created-at" "created-at"
page[size]
integer <int64> [ 1 .. 200 ]
page[after]
string <byte>

A base64 encoded opaque string returned in paginated responses.

page[before]
string <byte>

A base64 encoded opaque string returned in paginated responses.

Responses

Response samples

Content type
application/json
{
  • "memberships": [
    ],
  • "links": {
    }
}

Invitations

Invitations enable users to create new memberships for their organization. The new membership is only created once when the invitation is accepted.

If the email-address provided is linked to an existing user, the invitation will create a membership for that user. This does not affect any other memberships the user may have.

If the email-address is not linked to an existing user, the invitee will be prompted to set up a Griffin account when they accept the invitation.

When a new membership is created, the invited user is assigned the role with the most limited set of capabilities by default.

Create invitation

POST creates a new invitation to the organization.

Sends an email invitation to join the organization to the specified email-address.

Authorizations:
api-key-auth
path Parameters
organization-id
required
string
Request Body schema: application/json
email-address
required
string (email-address) .+\@.+\..+

Responses

Request samples

Content type
application/json
{
  • "email-address": "user@example.com"
}