Connect a business

To create a claim, you need the entity_id of a connected business. How you get it depends on the business.

The business…	What to do
Does not use Garfield	Onboard it
Uses Garfield	Send a connect link
Is your own Garfield account	No connection needed

In every case, copy the entity_id from the console's Businesses page, or read it from GET /entities. Then create a claim.

List your entities

GET /entities lists every entity that has connected to you, including those that have since disconnected, and your own entities. Entities that connected to you come newest first, by connection date or by disconnection date once they disconnect. Your own entities come last:

curl "$BASE/entities" \
  -H "Authorization: Bearer $TOKEN"

Each entity has entity_id, entity_name, entity_email, access, verified, partner_user_id, connected_at and disconnected_at. access is connected, disconnected or own. You can create claims for an entity when access is connected or own and verified is true. Once an entity disconnects from you, you cannot read or create its claims, and its entity_email is null.

partner_user_id is your id for the business. Use a stable id from your own system.

The business is new to Garfield

POST /onboardings creates a Garfield entity for the business and a user for user_email. Garfield emails that user a magic link to complete onboarding. The link signs the user in, so Garfield sends it only to the user and never returns it to you.

Required: partner_user_id, company_name, user_email, and either company_number or business_type.

The business is	Send
A limited company, LLP or limited partnership	`company_number`. `business_type` is optional.
A sole trader or partnership	`business_type`: `sole_trader` or `partnership`. No `company_number`.

company_number is the 8-character Companies House number, for example 01234567 or SC123456. The API removes spaces and uppercases letters. It rejects a shorter number, so include the leading zeros. Each of these returns 400 validation_failed:

A malformed or short company_number.
A company_number sent with business_type sole_trader or partnership.
business_type limited_company, limited_liability_partnership or limited_partnership without a company_number.

Garfield checks the number with Companies House and takes the business type from it:

Response	When
`422` `company_not_found`	Companies House has no company with this number.
`422` `company_not_active`	The company is dissolved, in liquidation or otherwise not active.
`422` `company_type_not_supported`	The company is a type Garfield does not onboard, for example a charitable incorporated organisation.
`422` `business_type_mismatch`	You sent a `business_type` that differs from the type at Companies House.

For an active company, Garfield pre-fills the incorporation date, registered address, current individual directors or LLP members and a description of the business from its SIC codes. Shortly after the API responds to you, Garfield attaches the certificate of incorporation, articles and latest accounts to the onboarding, so the user does not have to upload them. If Companies House is unreachable, Garfield still creates the onboarding. It takes the business type from your business_type, or uses limited_company if you did not send one, and the user enters the company details themselves.

Garfield pre-fills "How did you hear about us?" in the onboarding with "Through a partner".

You can also send details the user would otherwise type in. The user sees each one in their onboarding and can change it:

Field	Notes
`address`	The registered address. Garfield uses it only when Companies House has no registered office for the company.
`trading_address`	Where the business trades, if different.
`user_name`	The user's name, up to 200 characters.
`website`, `vat_number`	`website` up to 200 characters, `vat_number` up to 40.
`claim_number_estimate`	Claims expected in the next 12 months. A whole number from 0 to 100,000.
`claim_value_estimate`	The total value of the claims counted in `claim_number_estimate`, in whole pounds.
`accounting_platform`	`xero`, `quickbooks`, `sage`, `freeagent`, `in_house`, `other` or `none`.
`accounting_platform_other`	The software's name when `accounting_platform` is `other`. If you send it with any other `accounting_platform`, or without one, the request fails with `400` `validation_failed`.

You cannot send directors, beneficial owners or company documents. They come only from Companies House or from the business.

curl -X POST "$BASE/onboardings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "partner_user_id": "acme-crm-7741",
    "company_name": "Riverside Joinery Ltd",
    "company_number": "09876543",
    "user_email": "owner@riverside-joinery.co.uk",
    "user_name": "Jamie Rivers",
    "address": {
      "first_line": "2 Market Square",
      "locality": "London",
      "region": "Greater London",
      "postcode": "EC2A 2BB",
      "country": "United Kingdom"
    },
    "website": "https://riverside-joinery.co.uk",
    "claim_number_estimate": 20,
    "claim_value_estimate": 15000,
    "accounting_platform": "xero"
  }'

201 Created, or 200 OK on a replay:

{
  "onboarding_id": "pp_3f1c...",
  "entity_id": "aZ4kQ9pX2",
  "already_existed": false
}

entity_id is the Garfield entity for the business. Pass it to POST /claims. A replay returns the same entity_id, or null for an onboarding created before Garfield began storing entity ids. With a test key it is a sandbox entity. GET /entities shows when the business is ready for claims (verified: true).

The business appears on the console's Businesses page at once, marked Not verified until the user completes onboarding and Garfield verifies it. Until then, document and claim requests for it return entity_not_verified.

If Garfield cannot onboard the business automatically, the API returns 422 onboarding_unavailable. Send a connect link instead.

The business already uses Garfield

POST /connect-requests returns a single-use link. Send it to the business's Garfield user yourself, because Garfield does not email it. The user opens it in Garfield and selects Connect your company name. Until they do, document and claim requests for the business return 403 entity_not_owned.

Required: partner_user_id. label is optional. The business sees it on the connect screen as Linked to your record “<label>” in their system, so use the name of their record in your system.

curl -X POST "$BASE/connect-requests" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "partner_user_id": "acme-crm-7741", "label": "Riverside Joinery Ltd" }'

201 Created:

{
  "connect_url": "https://garfield.law/connect?token=ab12...cd34",
  "expires_at": "2026-05-31T15:04:05.000Z"
}

The link expires one hour after you get it. Each call returns a new link. After the user connects you, the business appears on the console's Businesses page.

Your own business

If your own business uses Garfield, your key can create claims for it. You do not need an onboarding or a connect link.

On the console's Businesses page, your business carries the label Your business.
partner_user_id is optional. Garfield only stores it on the claim, so you can filter GET /claims by it together with entity_id.
In Garfield, a claim created with your key shows Pushed by your company name, using the Company name from the console's Settings page.
GET /claims lists only the claims your keys created. It leaves out the claims you raise in the Garfield app.
To stop your key creating claims for your business, revoke the key.
Requests for your business return 403 entity_not_owned while Require two-factor authentication for everyone is on (in the Garfield app's Settings, on the Account tab, in the Security card), and 403 partner_disconnected if your business connected to you as a partner and then disconnected.

List your entities​

The business is new to Garfield​

The business already uses Garfield​

Your own business​

List your entities

The business is new to Garfield

The business already uses Garfield

Your own business