Upsert contacts

Create or update up to 100 contacts in one request (note: this endpoint’s batch limit is 100 items). Each item is matched against existing contacts by a single key: the normalized email when the item has a non-empty email, otherwise the normalized phone. A matched contact is updated with the item’s remaining fields (status: updated); an unmatched item creates a new contact (status: created, with original_source defaulting to Public API and original_source_detail to client_item_id unless supplied).

Because matching uses only that single key, an item whose email is new but whose phone already belongs to a different contact is not treated as an update — the creation collides on the phone and the item is rejected with error_code: conflict and the conflicting contact in existing_contact. (A create collision on the item’s own match key — e.g. from a concurrent insert — is resolved as an update of that contact instead.) Updates that would change an email or phone to collide with another contact are likewise rejected with conflict, and updates that would leave a contact with neither a valid email nor phone are rejected with bad_request.

Partial success is normal — inspect each item result; successful items include the full contact with custom_fields. Body-level validation failures (an invalid email or phone format, more than 100 items, unknown fields) reject the entire request with 400 before any item is processed.

POST /v1/contacts/upsert

Upsert contacts

cURL

curl --request POST \
  --url https://api.tented.ai/v1/contacts/upsert \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "items": [
    {
      "client_item_id": "<string>",
      "email": "<string>",
      "phone": "<string>",
      "display_name": "<string>",
      "first_name": "<string>",
      "last_name": "<string>",
      "email_domain": "<string>",
      "company": "<string>",
      "job_title": "<string>",
      "address": "<string>",
      "address2": "<string>",
      "city": "<string>",
      "state": "<string>",
      "country": "<string>",
      "zip_code": "<string>",
      "original_source": "<string>",
      "original_source_detail": "<string>",
      "lead_status": "<string>",
      "lifecycle_stage": "<string>",
      "tented_score": 123,
      "unsubscribed": true,
      "marketing_email_subscribed": true,
      "marketing_sms_subscribed": true,
      "marketing_sms_invalid": true,
      "custom_fields": {}
    }
  ]
}
'

200

{
  "status": "<string>",
  "created_count": 123,
  "updated_count": 123,
  "rejected_count": 123,
  "items": [
    {
      "index": 123,
      "status": "created",
      "client_item_id": "<string>",
      "contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
      "contact": {
        "contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "display_name": "<string>",
        "first_name": "<string>",
        "last_name": "<string>",
        "email": "<string>",
        "phone": "<string>",
        "email_domain": "<string>",
        "company": "<string>",
        "job_title": "<string>",
        "address": "<string>",
        "address2": "<string>",
        "city": "<string>",
        "state": "<string>",
        "country": "<string>",
        "zip_code": "<string>",
        "original_source": "<string>",
        "original_source_detail": "<string>",
        "lead_status": "<string>",
        "lifecycle_stage": "<string>",
        "tented_score": 123,
        "unsubscribed": true,
        "marketing_email_subscribed": true,
        "marketing_sms_subscribed": true,
        "marketing_email_invalid": true,
        "marketing_sms_invalid": true,
        "last_activity_at": "2023-11-07T05:31:56Z",
        "created_at": "2023-11-07T05:31:56Z",
        "updated_at": "2023-11-07T05:31:56Z"
      },
      "error_code": "bad_request",
      "message": "<string>",
      "existing_contact": {
        "contact_id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "display_name": "<string>",
        "email": "<string>",
        "phone": "<string>"
      }
    }
  ]
}

Authorizations

Authorization · string · header · required

Workspace API key, e.g. Authorization: Bearer tented_.... Create keys in Workspace Settings → API Keys.

Body

application/json

items · object[] · required

Contacts to create or update (1–100).

Required array length: 1 - 100 elements

Show child attributes

Response

200

application/json

Batch processed (individual items may still be rejected).

status · string · required

Always completed once the batch has been processed.

created_count · integer · required

Contacts created.

updated_count · integer · required

Contacts updated.

rejected_count · integer · required

Number of rejected items.

items · object[] · required

Per-item results, in request order. Created and updated items include the full contact (with custom_fields).

Show child attributes