Provision a new Garfield account for a referred business
POST/onboardings
Creates a partner-originated prospect, seeds a Garfield entity, and (unless the partner is configured to suppress it) emails the user a magic link to finish onboarding. Use this for businesses new to Garfield. If automatic onboarding cannot be completed for the details supplied, the request is rejected with onboarding_unavailable (see below); fall back to POST /connect-requests.
Idempotency. The prospect is keyed deterministically on (partner_id, partner_user_id). Repeating the call with the same partner_user_id returns the original onboarding_id with already_existed: true and HTTP 200, and does not re-send the email. On a replay the original magic link cannot be recovered, so magic_link_url is null even when link-in-response is enabled.
Request
Responses
- 200
- 201
- 400
- 401
- 403
- 422
- 429
- 500
- 503
Idempotent replay. An onboarding already existed for this (partner_id, partner_user_id). When your account is configured for link-in-response, magic_link_url is always null on a replay: the original link cannot be recovered.
A new onboarding was created and (unless suppressed) the email was sent. magic_link_url appears only when your account has the "return link in response" setting enabled; by default it is omitted.
The request body was malformed or failed validation. code is one of validation_failed (schema validation; see details), invalid_json (body was not valid JSON), or body_required (no JSON body: sent with a missing body or a Content-Type other than application/json).
Authentication failed. The code distinguishes the cause: auth_missing (no Authorization header), auth_invalid_format (malformed token), auth_unknown_partner (no such partner), auth_revoked (partner or key revoked), auth_bad_secret (bad key id or secret).
The partner is authenticated but not authorised. code is auth_partner_not_approved (the partner account is still pending approval; no endpoint will work until it is approved), entity_not_owned (no connection to the entity), or partner_disconnected (the entity disconnected the partner).
Automatic onboarding could not be completed for this request. Fall back to POST /connect-requests.
The per-partner rate limit (120 requests per minute, shared across all partner endpoints) was exceeded. Inspect Retry-After and the X-RateLimit-* headers before retrying.
Response Headers
Seconds to wait before retrying.
The request ceiling for the window.
Requests remaining in the current window.
Unix epoch milliseconds when the window resets.
An unexpected server error occurred. The message is always the generic string Internal error; key on code, not message.
A dependency the request relies on is temporarily unavailable. The partner did nothing wrong; retry after the delay in Retry-After.
Response Headers
Seconds to wait before retrying.