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.