POST /onboardings

Provision a brand-new Garfield entity and user for a business that does not yet use Garfield, then email them a magic link to finish onboarding. Idempotent on partner_user_id.

Request

Required: partner_user_id, company_name, user_email. Everything else is optional.

curl -X POST "$BASE/onboardings" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d @onboarding.json

onboarding.json
{
  "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",
    "second_line": null,
    "locality": "London",
    "region": "Greater London",
    "postcode": "EC2A 2BB",
    "country": "United Kingdom"
  }
}

Response

201 Created (new) / 200 OK (idempotent replay):

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

Magic link delivery

Garfield emails the magic link to the user by default. magic_link_url is included in the response only if your partner account has the "return link in response" setting enabled. The link is a credential, so the setting is off by default:

{
  "onboarding_id": "pp_3f1c...",
  "already_existed": false,
  "magic_link_url": "https://garfield.law/prospect-onboarding?token=..."
}

A companion "suppress email" setting lets you stop Garfield's email when you deliver the link yourself. You control both from the Settings tab of the developer console. On a replay, magic_link_url is null; the original link cannot be recovered.

When automatic onboarding isn't available

If automatic onboarding can't be completed for the details you submit, the call returns 422 onboarding_unavailable. Use POST /connect-requests instead.

Request​

Response​

Request

Response