Convert a Contact

Convert Contact

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>"
  }
}
'

import requests

url = "https://api.example.com/contacts/{contact_id}/convert"

payload = {
    "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>"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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>'
    }
  })
};

fetch('https://api.example.com/contacts/{contact_id}/convert', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/contacts/{contact_id}/convert",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/contacts/{contact_id}/convert"

	payload := strings.NewReader("{\n  \"account_id\": \"<string>\",\n  \"create_account\": false,\n  \"new_account\": {\n    \"name\": \"<string>\",\n    \"domain\": \"<string>\",\n    \"website\": \"<string>\"\n  },\n  \"create_deal\": false,\n  \"deal_payload\": {\n    \"name\": \"<string>\",\n    \"stage_id\": \"<string>\",\n    \"value\": 123,\n    \"close_date\": \"<string>\",\n    \"currency\": \"USD\",\n    \"notes\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/contacts/{contact_id}/convert")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"account_id\": \"<string>\",\n  \"create_account\": false,\n  \"new_account\": {\n    \"name\": \"<string>\",\n    \"domain\": \"<string>\",\n    \"website\": \"<string>\"\n  },\n  \"create_deal\": false,\n  \"deal_payload\": {\n    \"name\": \"<string>\",\n    \"stage_id\": \"<string>\",\n    \"value\": 123,\n    \"close_date\": \"<string>\",\n    \"currency\": \"USD\",\n    \"notes\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/contacts/{contact_id}/convert")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"account_id\": \"<string>\",\n  \"create_account\": false,\n  \"new_account\": {\n    \"name\": \"<string>\",\n    \"domain\": \"<string>\",\n    \"website\": \"<string>\"\n  },\n  \"create_deal\": false,\n  \"deal_payload\": {\n    \"name\": \"<string>\",\n    \"stage_id\": \"<string>\",\n    \"value\": 123,\n    \"close_date\": \"<string>\",\n    \"currency\": \"USD\",\n    \"notes\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

{}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

POST

contacts

{contact_id}

convert

Convert Contact

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>"
  }
}
'

import requests

url = "https://api.example.com/contacts/{contact_id}/convert"

payload = {
    "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>"
    }
}
headers = {
    "Authorization": "Bearer <token>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

const options = {
  method: 'POST',
  headers: {Authorization: 'Bearer <token>', 'Content-Type': 'application/json'},
  body: JSON.stringify({
    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>'
    }
  })
};

fetch('https://api.example.com/contacts/{contact_id}/convert', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

<?php

$curl = curl_init();

curl_setopt_array($curl, [
  CURLOPT_URL => "https://api.example.com/contacts/{contact_id}/convert",
  CURLOPT_RETURNTRANSFER => true,
  CURLOPT_ENCODING => "",
  CURLOPT_MAXREDIRS => 10,
  CURLOPT_TIMEOUT => 30,
  CURLOPT_HTTP_VERSION => CURL_HTTP_VERSION_1_1,
  CURLOPT_CUSTOMREQUEST => "POST",
  CURLOPT_POSTFIELDS => json_encode([
    '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>'
    ]
  ]),
  CURLOPT_HTTPHEADER => [
    "Authorization: Bearer <token>",
    "Content-Type: application/json"
  ],
]);

$response = curl_exec($curl);
$err = curl_error($curl);

curl_close($curl);

if ($err) {
  echo "cURL Error #:" . $err;
} else {
  echo $response;
}

package main

import (
	"fmt"
	"strings"
	"net/http"
	"io"
)

func main() {

	url := "https://api.example.com/contacts/{contact_id}/convert"

	payload := strings.NewReader("{\n  \"account_id\": \"<string>\",\n  \"create_account\": false,\n  \"new_account\": {\n    \"name\": \"<string>\",\n    \"domain\": \"<string>\",\n    \"website\": \"<string>\"\n  },\n  \"create_deal\": false,\n  \"deal_payload\": {\n    \"name\": \"<string>\",\n    \"stage_id\": \"<string>\",\n    \"value\": 123,\n    \"close_date\": \"<string>\",\n    \"currency\": \"USD\",\n    \"notes\": \"<string>\"\n  }\n}")

	req, _ := http.NewRequest("POST", url, payload)

	req.Header.Add("Authorization", "Bearer <token>")
	req.Header.Add("Content-Type", "application/json")

	res, _ := http.DefaultClient.Do(req)

	defer res.Body.Close()
	body, _ := io.ReadAll(res.Body)

	fmt.Println(string(body))

}

HttpResponse<String> response = Unirest.post("https://api.example.com/contacts/{contact_id}/convert")
  .header("Authorization", "Bearer <token>")
  .header("Content-Type", "application/json")
  .body("{\n  \"account_id\": \"<string>\",\n  \"create_account\": false,\n  \"new_account\": {\n    \"name\": \"<string>\",\n    \"domain\": \"<string>\",\n    \"website\": \"<string>\"\n  },\n  \"create_deal\": false,\n  \"deal_payload\": {\n    \"name\": \"<string>\",\n    \"stage_id\": \"<string>\",\n    \"value\": 123,\n    \"close_date\": \"<string>\",\n    \"currency\": \"USD\",\n    \"notes\": \"<string>\"\n  }\n}")
  .asString();

require 'uri'
require 'net/http'

url = URI("https://api.example.com/contacts/{contact_id}/convert")

http = Net::HTTP.new(url.host, url.port)
http.use_ssl = true

request = Net::HTTP::Post.new(url)
request["Authorization"] = 'Bearer <token>'
request["Content-Type"] = 'application/json'
request.body = "{\n  \"account_id\": \"<string>\",\n  \"create_account\": false,\n  \"new_account\": {\n    \"name\": \"<string>\",\n    \"domain\": \"<string>\",\n    \"website\": \"<string>\"\n  },\n  \"create_deal\": false,\n  \"deal_payload\": {\n    \"name\": \"<string>\",\n    \"stage_id\": \"<string>\",\n    \"value\": 123,\n    \"close_date\": \"<string>\",\n    \"currency\": \"USD\",\n    \"notes\": \"<string>\"\n  }\n}"

response = http.request(request)
puts response.read_body

{}

{
  "detail": [
    {
      "loc": [
        "<string>"
      ],
      "msg": "<string>",
      "type": "<string>"
    }
  ]
}

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:

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.
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}").
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

Successful Response

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

Contacts

Deals

Accounts

Activities

Tags

Files

Folders

Notifications

Reports

PATs

Integrations

AI

Analytics Assistant

Feedback

Customer Intelligence

Outreach

AnyCard

AnyCard Events

AnyCard Share Links

Public Media

Account Readiness

Service Health

Auth

Response

Errors

Authorizations

Path Parameters

Body

Response

​Auth

​Response

​Errors

Authorizations

Path Parameters

Body

Response

Auth

Response

Errors