Skip to main content

Open an embedded account

Deprecated

Do not use this endpoint for new integrations. Opening accounts directly against organization-bank-accounts-url with a bank-product-type field has been replaced by the bank-product-based flow.

For new integrations, or when updating an existing one, follow Opening a bank account instead. This page is kept only as a reference for integrations that have not yet migrated.

An embedded account enables you to offer a real bank account to your customers. Learn more about embedded accounts.

Prerequisites​

  • You will need your organization-bank-accounts-url (shown as $ORGANIZATION_BANK_ACCOUNTS_URL in the examples below). Your organization-bank-accounts-url is one of the URLs returned when you request your organization-url. If you don't have your organization-url yet, check out our getting started guide.

Request​

  • Set the bank-product-type to embedded-account
  • Set the owner-url to the legal person URL who is entitled to the money in the account
note
  • The beneficiary and owner are the same legal person.
curl "https://api.griffin.com${ORGANIZATION_BANK_ACCOUNTS_URL}" \
  -X 'POST' \
  -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY" \
  -H 'Content-Type: application/json' \
  --data '
{
  "bank-product-type": "embedded-account",
  "owner-url": "$CUSTOMER_LEGAL_PERSON_URL"
}'

Synchronous Response​

A successful response looks like this.

{
	"account-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A",
	"pooled-funds": false,
	"available-balance": {
		"currency": "GBP",
		"value": "0.00"
	},
	"account-restricted": false,
	"display-name": "embedded-1",
	"beneficiary-url": "$CUSTOMER_LEGAL_PERSON_URL",
	"account-balance": {
		"currency": "GBP",
		"value": "0.00"
	},
	"account-transactions-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A/transactions",
	"created-at": "2023-12-07T17:03:20.757Z",
	"account-payments-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A/payments",
	"bank-product-type": "embedded-account",
	"bank-addresses": [],
	"owner-url": "$CUSTOMER_LEGAL_PERSON_URL",
	"close-account-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A/actions/close",
	"account-admissions-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A/admissions",
	"account-status": "opening",
	"account-submissions-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A/submissions",
	"controller-url": "/v0/legal-persons/lp.Ph9xPUvzULGohmZ4_u_TDw"
}

This response indicates that you have successfully requested the creation of a new embedded account. The account-status will likely be opening since there are some background preparatory tasks that need to finish before the account can be used. These take place automatically, so you can simply poll the account-url endpoint until the account-status is open.

NOTE: If you have created a webhook for your organisation you can also listen for the account-status-updated webhook event and track account-status.

Learn more about the account lifecycle.

Poll for status​

Poll the account-url endpoint.

curl "https://api.griffin.com${ACCOUNT_URL}" \
  -X 'GET' \
  -H "Authorization: GriffinAPIKey $GRIFFIN_API_KEY" \
  -H 'Content-Type: application/json' \

When the account-status is open, the account is ready for use.

{
	"account-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A",
	"pooled-funds": false,
	"available-balance": {
		"currency": "GBP",
		"value": "0.00"
	},
	"account-restricted": false,
	"display-name": "embedded-1",
	"beneficiary-url": "$CUSTOMER_LEGAL_PERSON_URL",
	"account-balance": {
		"currency": "GBP",
		"value": "0.00"
	},
	"account-transactions-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A/transactions",
	"created-at": "2023-12-07T17:03:20.757Z",
	"account-payments-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A/payments",
	"bank-product-type": "embedded-account",
	"bank-addresses": [],
	"owner-url": "$CUSTOMER_LEGAL_PERSON_URL",
	"close-account-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A/actions/close",
	"account-admissions-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A/admissions",
	"account-status": "open",
	"account-submissions-url": "/v0/bank/accounts/ba.IcqDdMDxT7OaYRznoit-7A/submissions",
	"controller-url": "/v0/legal-persons/lp.Ph9xPUvzULGohmZ4_u_TDw"
}