Upsert Contact

Create a new contact or update an existing one. The match is based on email and/or phone, following the "Allow Duplicate Contact" setting configured at the location level.

POST/contacts/upsert

Scope

contacts.write

Auth Method

Bearer Token

Token Type

Sub-Account / Company

Header Parameters

Parameter	Type	Description
`Authorization`required	string	Bearer {access_token}
`Version`required	string	API Version Possible values: `2021-07-28`
`Content-Type`required	string	application/json

Body Parameters

Parameter	Type	Description
`firstName`	string	First name.
`lastName`	string	Last name.
`name`	string	Full name.
`email`	string	Email address. Used for matching existing contacts.
`phone`	string	Phone number (E.164). Used for matching existing contacts.
`locationId`required	string	Sub-account ID.
`address1`	string	Street address.
`city`	string	City.
`state`	string	State or province.
`postalCode`	string	ZIP or postal code.
`country`	string	Country code (ISO 3166-1 alpha-2).
`website`	string	Website URL.
`timezone`	string	IANA timezone.
`dnd`	boolean	Global Do Not Disturb flag.
`dndSettings`	object	Per-channel DND settings.
`tags`	string[]	Tags to assign.
`customFields`	object[]	Custom field values.
`source`	string	Lead source.
`companyName`	string	Company name.
`dateOfBirth`	string	Birth date.
`assignedTo`	string	User ID to assign.

Example RequestcURL

curl -X POST \
  'https://services.leadconnectorhq.com/contacts/upsert' \
  -H 'Authorization: Bearer {access_token}' \
  -H 'Version: 2021-07-28' \
  -H 'Content-Type: application/json' \
  -d '{
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phone": "+15559876543",
    "locationId": "ve9EPM428h8vShlRW1KT",
    "tags": ["upserted"],
    "source": "api"
  }'

Response — 200 OK

The response includes a new boolean indicating whether the contact was created (true) or updated (false).

Example ResponseJSON

{
  "new": false,
  "contact": {
    "id": "ocQHyuzHvuMOe5N5jjXF",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "phone": "+15559876543",
    "locationId": "ve9EPM428h8vShlRW1KT",
    "tags": ["upserted"],
    "source": "api",
    "dateUpdated": "2024-06-16T15:00:00.000Z"
  }
}

Duplicate Contact Logic

The Upsert API follows the "Allow Duplicate Contact" setting at the Location level. If configured to check both Email and Phone, the API matches on the first field in the configured priority sequence.

If two separate contacts exist — one matching the email and another matching the phone — the API updates the contact matching the higher-priority field and ignores the second to prevent duplication.

← Delete Contact Get Contacts →