Get started

The Garfield Partner API is a server-to-server REST API. Use it to onboard or connect businesses to Garfield and to create debt-recovery claims for them. Request and response bodies are JSON.

Get your keys

1. Open the developer console:
   • Garfield users: in Settings, open the Account tab, find the Partner API card and select Open the developer console.
   • New users: sign up for API access.
2. On the console's Keys page, create a pk_test_… key. You can build against the sandbox while Garfield reviews your application.
3. Once Garfield approves your application, create a pk_live_… key for production.

The console shows the full key once, so store it in your secrets manager straight away. If a key leaks, revoke it and create a new one. Revoking is permanent. Rotating a key on the Keys page creates its replacement and revokes the old key in the same step.

The examples in these docs use two shell variables:

export BASE="https://www.garfield.law/api/partner/v1"
export TOKEN="pk_test_..." # your full key from the console's Keys page

Send the key

Send the key as a bearer token on each request:

Authorization: Bearer pk_test_<partner_id>.<key_id>.<secret>

Part	Example	Notes
pk_test_ / pk_live_	pk_test_	The key's mode, test or live.
<partner_id>	acme	Your partner id.
<key_id>	k_7Yh2	Which key this is. A rotated key gets a new id.
<secret>	s_3Fb…	The key's secret. To change it, rotate the key.

Test mode

Each key has a mode, which you choose when you create the key and cannot change later. The prefix you send must match the key's mode. A test key sent with pk_live_, or a live key sent with pk_test_, returns auth_bad_secret.

Prefix	Mode	Effect
pk_test_…	Test	The same endpoints, bodies, validation and errors, for made-up businesses and claims. Garfield processes nothing, bills nothing and sends no emails.
pk_live_…	Live	Claims and onboardings are real. Garfield processes and bills them, generates documents and sends emails.

Sandbox entities

A test key works only with sandbox entities. A real entity_id returns entity_not_found. Every sandbox entity is verified and stays connected, so you can create claims for it at once.

• sandbox is your own sandbox entity. It exists as soon as your partner account does.
• POST /onboardings connects a sandbox entity for the partner_user_id, names it after company_name, and returns its entity_id. Garfield creates no user and sends no email. It checks the format of company_number only, with no Companies House lookup.
• POST /connect-requests connects the sandbox entity for the partner_user_id at once. If that entity does not exist yet, Garfield creates it and names it after label, or Sandbox business <partner_user_id> if you send no label. The connect_url opens nothing, and expires_at is null. GET /entities lists the entity.

POST /onboardings and POST /connect-requests with the same partner_user_id use the same sandbox entity.

Simulated claims

A test claim's status moves on a fixed timetable, counted from when you create it. The defendant details you send decide where it ends:

Defendant	After 1 minute	After 5 minutes
Address postcode ZZ1 1ZZ	invalid, needs_attention: true, reason code invalid_postcode	No change
Name Sandbox Needs Attention Ltd	in_progress, needs_attention: true	No change
Anything else	in_progress	letter_sent

Every test claim starts as received. Garfield matches the postcode and name ignoring case and spaces, and the postcode wins if a defendant has both. You read test claims the same way as live ones, including polling with updated_since.

Test mode does not simulate:

• Any status after those in the table, such as court or resolved.
• Messages and documents changing a claim. Garfield stores them, and replays work as in production, but Garfield does not process them.
• Pending, rejected or disconnected entities, so you cannot test entity_not_verified or partner_disconnected.
• Onboarding failures, so you cannot test company_not_found, company_not_active, company_type_not_supported, business_type_mismatch or onboarding_unavailable.
• outstanding, which stays null.

Rate limits, authentication, validation and idempotency work as in production.

Auth errors

Status	code	Cause
401	auth_missing	No Authorization header.
401	auth_invalid_format	The token has no pk_test_ or pk_live_ prefix, or its format is not valid.
401	auth_revoked	Garfield revoked your partner account or rejected your application, or you revoked the key.
401	auth_bad_secret	The partner id, key id or secret is incorrect, or the prefix does not match the key's mode.
403	auth_partner_not_approved	Garfield has not approved your partner account yet. Until it does, only test keys work.

For all other errors, see Errors and limits.

Next steps

Connect a business, then create a claim. The console's Usage page shows your calls and your error rate.