Convert a Contact

Advance a contact lead → contact (won/customer).

The contact already exists; this stamps stage=‘contact’ + contact_at and, optionally, creates/links an account and creates a deal. Steps run sequentially (no transaction) — a deal failure is reported but does not block the stage advance.

POST /contacts/{contact_id}/convert

Convert Contact

cURL

curl --request POST \
  --url https://api.example.com/contacts/{contact_id}/convert \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "account_id": "<string>",
  "create_account": false,
  "new_account": {
    "name": "<string>",
    "domain": "<string>",
    "website": "<string>"
  },
  "create_deal": false,
  "deal_payload": {
    "name": "<string>",
    "stage_id": "<string>",
    "value": 123,
    "close_date": "<string>",
    "currency": "USD",
    "notes": "<string>"
  }
}
'

200

{}

The most involved endpoint on this router. Advances a lead → contact (won/customer), stamping contact_at and converted_at (and backfilling lead_at if the contact skipped straight from target). Optionally also creates or links an account, and optionally creates a deal on that account — all in one call.

Steps run sequentially, not in a transaction:

1. If create_account is true, create a new account (new_account.name → falls back to the contact’s company, then its display name, then "Untitled Account"). Otherwise use account_id (body) or the contact’s existing account_id.
2. If create_deal is true and an account is now known, create a deal on it (deal_payload.name → falls back to "Deal with {company}").
3. Patch the contact: stage = "contact", contact_at, converted_at, and (if an account was resolved) account_id + converted_to_account_id, and (if a deal was created) converted_to_deal_id.

A failure in step 2 (deal creation) does not abort the request — it’s reported back as deal_error and the contact is still advanced in step 3. A failure in step 3 is reported as convert_status_error rather than raising, so a client must check for these keys rather than assuming a 200 means every requested side-effect happened.

Auth

Requires a CRM manage scope and an active organization on the token. Any *:manage scope qualifies — in practice contacts:manage, deals:manage, companies:manage, or activities:manage.

Response

Field	Type	Description
contact_id	string (uuid)	Echo of the path parameter.
account_id	string (uuid) | null	The account that ended up linked (existing, newly created, or none).
deal_id	string (uuid)	Present only if a deal was created.
deal_error	string	Present only if deal creation was requested and failed.
contact	object	The updated contact row, present unless the final patch itself failed.
convert_status_error	string	Present only if the final stage-advance patch failed.

Errors

Status	Cause
400	Both account_id and create_account=true given, or no active organization.
404	Contact not found, or account_id doesn’t resolve to an account in the caller’s organization.
500 / 502	Account creation (step 1) failed — 502 if the failure came back from the database call, 500 for any other error creating the account. Deal-creation failures (step 2) never raise; they’re reported as deal_error in the 200 response instead.

Authorizations

Authorization · string · header · required

Bearer authentication header of the form Bearer <token>, where <token> is your auth token.

Path Parameters

contact_id · string · required

The contact's id.

Body

application/json

Advance a contact lead→contact (won/customer), optionally creating or linking an account and creating a deal. The contact already exists, so there is no "create contact" step (unlike the old lead-convert flow).

account_id · string | null

Existing account to link the contact to. Mutually exclusive with create_account.

create_account · boolean · default: false

If true, create a new account from new_account (or fall back to the contact's company/name).

new_account · NewAccountFields · object | null

Fields for the new account when create_account is true.

Show child attributes

create_deal · boolean · default: false

If true, also create a deal linked to the resulting account.

deal_payload · DealFields · object | null

Fields for the new deal when create_deal is true.

Show child attributes

Response

200

application/json

Successful Response

The response is of type Response Convert Contact Route Contacts Contact Id Convert Post · object.