Skip to main content
Version: 1.0.0

Garfield Partner API

Server-to-server API for partners that refer businesses to Garfield AI for debt recovery and create claims on their behalf.

All endpoints are authenticated with a partner API key (see the PartnerApiKey security scheme). Every request and response body is JSON. Every non-2xx response carries a stable, machine-readable code field. Clients should key on code, never on the human-readable message text.

The typical flow is:

  1. POST /onboardings: provision a brand-new Garfield account for a referred business that is not yet a Garfield customer, OR POST /connect-requests: generate a link that an existing Garfield user approves from inside the app to link their entity to you.
  2. POST /documents/upload-url: mint a signed URL and upload supporting documents (invoices, contracts) straight to storage.
  3. POST /claims: create the claim, referencing any uploaded documents.
  4. GET /claims: list and reconcile the claims you originated for an entity.

Authentication​

Send your API key as a bearer token: Authorization: Bearer pk_live_<partner_id>.<key_id>.<secret> (or pk_test_… for a test-mode key).

The token starts with a mandatory mode prefix (pk_live_ or pk_test_), followed by three dot-separated parts: the partner id, the key id, and the secret. A token without the mode prefix is rejected with auth_invalid_format. The secret is shown only once when the key is issued. Keys are revocable; a revoked partner or key returns auth_revoked, and a partner still awaiting approval returns auth_partner_not_approved (HTTP 403).

Test mode. A pk_test_ key behaves identically to a live key (same endpoints, same request and response shapes), but every write is fully sandboxed: claims and onboardings are isolated from production data and never enter document generation, billing, or any production pipeline, and onboarding emails are not sent. The magic_link_url returned in test mode is a synthetic placeholder: it points at a non-resolving host and cannot be opened or redeemed; use a live key for a working link. Use a test key to integrate end-to-end without creating real claims. A key's mode is fixed when it is issued, and the bearer prefix must match it.

Security Scheme Type:

http

HTTP Authorization Scheme:

bearer

Bearer format:

pk_live_PARTNER_ID.KEY_ID.SECRET (pk_test_ in the sandbox)