Upsert contact

POST/v1/contacts/upsert

Authorization

bearerAuth

AuthorizationBearer <token>

API token issued from the dashboard (Settings → API Tokens). Sent as Authorization: Bearer <token>.

In: header

Request Body

application/json

TypeScript Definitions

Use the request body type in TypeScript.

firstName?|null

lastName?|null

name?|

Convenience: send a full name and we split into first/last.

email?|null

phone?string|null

mobile?string|null

addressLine1?|null

addressLine2?|null

city?|null

state?|null

country?|

Two-letter country code.

postalCode?|null

website?string|null

linkedinUrl?string|null

twitterUrl?string|null

timezone?|

IANA timezone. Auto-derived from the phone area code when omitted.

jobTitle?|null

dateOfBirth?string|null

companyId?|null

assignedTo?|

User id of the owner to assign.

leadStatus?string

Defaults to new on create.

Value in"new" | "contacted" | "qualified" | "unqualified" | "converted"

leadScore?integer

Range0 <= value <= 100

dnd?boolean

Global do-not-disturb flag.

dndSettings?

tags?array<string>|

Array of tags, or a comma-separated string ("fb lead, n8n-import").

customFields?|array<unknown>

Object { uuid: value } OR GHL-compatible array [{ id, key, field_value }]. Both forms are accepted.

source?string

Lengthlength <= 100

Response Body

`application/json`

cURL

curl -X POST "https://example.com/contacts/upsert" \  -H "Content-Type: application/json" \  -d '{}'

{
  "success": true,
  "contact": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "firstName": "string",
    "lastName": "string",
    "email": "user@example.com",
    "phone": "string",
    "mobile": "string",
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "postalCode": "string",
    "website": "string",
    "linkedinUrl": "string",
    "twitterUrl": "string",
    "timezone": "string",
    "jobTitle": "string",
    "dateOfBirth": "string",
    "companyId": "8bb73d03-06b4-47c7-80c7-59301f770eda",
    "assignedTo": "7869c1a9-a680-4086-b6f5-9e78a651f6f2",
    "leadStatus": "new",
    "leadScore": -9007199254740991,
    "dnd": true,
    "dndSettings": {
      "property1": {
        "status": "string",
        "message": "string",
        "code": "string"
      },
      "property2": {
        "status": "string",
        "message": "string",
        "code": "string"
      }
    },
    "tags": [],
    "customFields": {},
    "source": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  },
  "action": "created",
  "new": true
}

{
  "success": true,
  "contact": {
    "id": "497f6eca-6276-4993-bfeb-53cbbbba6f08",
    "firstName": "string",
    "lastName": "string",
    "email": "user@example.com",
    "phone": "string",
    "mobile": "string",
    "addressLine1": "string",
    "addressLine2": "string",
    "city": "string",
    "state": "string",
    "country": "string",
    "postalCode": "string",
    "website": "string",
    "linkedinUrl": "string",
    "twitterUrl": "string",
    "timezone": "string",
    "jobTitle": "string",
    "dateOfBirth": "string",
    "companyId": "8bb73d03-06b4-47c7-80c7-59301f770eda",
    "assignedTo": "7869c1a9-a680-4086-b6f5-9e78a651f6f2",
    "leadStatus": "new",
    "leadScore": -9007199254740991,
    "dnd": true,
    "dndSettings": {
      "property1": {
        "status": "string",
        "message": "string",
        "code": "string"
      },
      "property2": {
        "status": "string",
        "message": "string",
        "code": "string"
      }
    },
    "tags": [],
    "customFields": {},
    "source": "string",
    "createdAt": "2019-08-24T14:15:22Z",
    "updatedAt": "2019-08-24T14:15:22Z"
  },
  "action": "created",
  "new": true
}

{
  "error": "validation_failed",
  "message": "string",
  "issues": null
}

{
  "error": "unauthorized"
}

{
  "success": false,
  "error": "API key lacks write permission"
}

Authorization

Request Body

Response Body

200application/json

201application/json

400application/json

401application/json

403application/json

`application/json`

`application/json`

`application/json`

`application/json`

`application/json`