Create a Garfield entity for a new business
Creates a Garfield entity for a business that does not use Garfield, and emails user_email a magic link. The response has the new entity_id to pass to POST /claims, and GET /entities shows when Garfield has verified the business. Idempotent on partner_user_id: a replay returns the same onboarding_id and entity_id, and a replay with a different body returns 409 idempotency_key_reused. See Connect a business.
Send company_number for a business registered at Companies House. Garfield checks it, takes the business type from Companies House, and pre-fills the incorporation date, registered address, current individual directors or LLP members, and a description from the company's SIC codes. Shortly after the API responds, Garfield attaches the certificate of incorporation, articles and latest accounts. If Companies House is unreachable, Garfield still creates the onboarding without the pre-fill, and takes the business type from business_type, or uses limited_company if you sent none. For a sole trader or partnership, leave company_number out and send business_type. With a test key, the API checks only the format of company_number.
Request
POST/onboardings
Responses
- 200
- 201
- 400
- 401
- 403
- 409
- 422
- 429
- 500
- 503
Replay: you already created an onboarding with this partner_user_id. Garfield does not email the user again.
Response Headers
The maximum number of requests your partner account can send in each window. Only production enforces limits and sends this header.
The window length in seconds, always 60. The API does not report how much of the current window is left. Only production sends this header.
Garfield created the onboarding and emailed the user a magic link to complete it. The link signs the user in, so the API never returns it to you.
Response Headers
The maximum number of requests your partner account can send in each window. Only production enforces limits and sends this header.
The window length in seconds, always 60. The API does not report how much of the current window is left. Only production sends this header.
The body is not valid. code is validation_failed (see details), invalid_json (not valid JSON) or body_required (no body, or Content-Type is not application/json). POST /claims and POST /claims/{claim_id}/messages also return document_path_invalid (a storage_path is not in the upload folder for this entity and partner_claim_id, or, on POST /claims/{claim_id}/messages, is already attached to the claim) or document_not_uploaded (a file in document_refs is not in storage).
Authentication failed. code gives the cause: auth_missing (no Authorization header), auth_invalid_format (the token has no pk_test_ or pk_live_ prefix, or its format is not valid), auth_revoked (Garfield revoked your partner account or rejected your application, or you revoked the key) or auth_bad_secret (the partner id, key id or secret is incorrect, or the prefix does not match the key's mode).
The key is valid but does not have access. code gives the cause: auth_partner_not_approved (Garfield has not approved your partner account yet, so only test keys work), entity_not_owned (the entity is not connected to you and is not your own), partner_disconnected (the entity disconnected from you, so you cannot read or write its claims) or entity_not_verified (Garfield has not verified the business yet, or rejected it, so uploads, claims and messages fail while every read still works).
idempotency_key_reused: you already sent this partner_user_id with a different body. Garfield created nothing and sent no email. An onboarding created before Garfield began storing request bodies replays whatever body you send.
company_not_found: Companies House has no company with this number. company_not_active: the company is dissolved, in liquidation or otherwise not active. company_type_not_supported: Companies House lists an organisation type Garfield does not onboard. business_type_mismatch: business_type differs from the type at Companies House. onboarding_unavailable: Garfield cannot onboard this business automatically. Send a connect link with POST /connect-requests.
Too many requests. Each partner can send 120 requests per minute across all endpoints and keys, and only requests with a verified key count. Until Garfield approves a partner, the limit is 30 requests per minute. Requests that fail authentication count separately, 10 per minute for each IP address. Past that, fix the key before you send more requests. For the partner limit, wait the number of seconds in Retry-After, then retry. The API counts requests per minute as they arrive, so treat the limits as approximate.
Response Headers
The number of seconds to wait before you retry.
The maximum requests in each window, for the limit you exceeded.
Only on a 429, where it is 0. The API does not report a running count.
The window length in seconds, always 60. The API does not report how much of the current window is left. Only production sends this header.
A server error. code is internal_error. Retry with exponential backoff.
A dependency is temporarily unavailable. code is service_unavailable, or document_verification_failed when the API could not check an uploaded document in storage. Retry after Retry-After when the response has it, otherwise with exponential backoff.
Response Headers
The number of seconds to wait before you retry.