Upserting Contacts

Beta

Create new contacts or update existing ones in a single request. Upserts match on your workspace identity field (email by default) and only update attributes provided in the payload.

How Upsert Works

Understanding create-or-update behavior

  • Upsert searches for an existing contact using the workspace identity field.
  • If a match is found, only the attributes included in the request are updated.
  • If no match is found, a new contact is created and subscribed by default.
  • Use upsert to avoid duplicate identity errors when syncing contacts.
POST

Upsert Contact

https://api.leadpush.io/v1/workspaces/{workspace_uuid}/contacts/upsert

Create or update a contact by identity

Path parameters

workspace_uuidstring Required

ID of your workspace

Request body

attributesobject Required
Upsert Contact
curl -X POST https://api.leadpush.io/v1/workspaces/{workspace_uuid}/contacts/upsert \
-H "Content-Type: application/json" \
-H "Authorization: Bearer {token}" \
-d '{
  "attributes": {
    "email": "jane.smith@example.com",
    "first_name": "Jane",
    "last_name": "Smith",
    "company": "Acme Corp"
  }
}'
Example Response
{
"uuid": "<contact_uuid>",
"subscribed": true,
"attributes": {
  "email": "jane.smith@example.com",
  "phone": "+1234567890",
  "first_name": "Jane",
  "last_name": "Smith",
  "company": "Acme Corp"
},
"created_at": "2021-01-01T00:00:00.000Z",
"updated_at": "2021-01-02T12:30:00.000Z"
}

Identity Requirements

Ensure the correct identity attribute is provided

  • The required identity field is determined by the workspace configuration.
  • If the identity attribute is missing or invalid, the API returns a 422 error.
  • If contact limits apply to your account, the API may return 403 errors when limits are exceeded.