Managing Contacts - Tented Help Center

Endpoints

GET    /v1/contacts
GET    /v1/contacts/{contact_id}
PATCH  /v1/contacts/{contact_id}
DELETE /v1/contacts/{contact_id}
GET    /v1/contacts/{contact_id}/activities
POST   /v1/contacts
POST   /v1/contacts/upsert
POST   /v1/contacts/update
POST   /v1/contacts/delete
DELETE /v1/contacts
POST   /v1/contacts/search

Use these endpoints to sync CRM contacts from external systems. Batch write requests accept an items array with up to 100 records. For bulk file-based ingestion, see Importing Contacts; for field definitions, see Managing Contact Fields.

Contact writes support partial success. Tented processes each item independently and returns accepted or rejected results in request order.

Look Up Contacts

GET /v1/contacts

GET /v1/contacts has two modes. With an email or phone query parameter it is an identifier lookup returning zero or one contact (shown here). Without an identifier it becomes a paginated listing — see List Contacts.

Query Parameters

Parameter	Type	Required	Notes
`email`	`string`	Conditionally	Either `email` or `phone` is required. Matched on the normalized value.
`phone`	`string`	Conditionally	Either `email` or `phone` is required. Matched on the normalized value.

Lookup Request Example

curl --request GET \
  --url 'https://api.tented.ai/v1/contacts?email=jane%40example.com' \
  --header 'Authorization: Bearer tented_your_api_key'

Lookup Response Example

Returns items with the matching contact, or an empty array when no contact matches. custom_fields is keyed by each custom field’s API name.

{
  "items": [
    {
      "contact_id": "11111111-1111-4111-8111-111111111111",
      "display_name": "Jane Doe",
      "first_name": "Jane",
      "last_name": "Doe",
      "email": "jane@example.com",
      "phone": null,
      "company": "Acme",
      "job_title": "CEO",
      "original_source": "Public API",
      "lifecycle_stage": "subscriber",
      "unsubscribed": false,
      "custom_fields": {
        "favorite_color": "Green"
      },
      "created_at": "2026-04-30T12:00:00.000Z",
      "updated_at": "2026-04-30T12:00:00.000Z"
    }
  ]
}

Get a Contact

GET /v1/contacts/{contact_id}

Fetch a single contact by its ID — the contact_id returned by create, update, and lookup responses.

Path Parameters

Parameter	Type	Required	Notes
`contact_id`	`uuid`	Yes	Returns `404` when no contact matches, `400` when malformed

Get Request Example

curl --request GET \
  --url 'https://api.tented.ai/v1/contacts/11111111-1111-4111-8111-111111111111' \
  --header 'Authorization: Bearer tented_your_api_key'

Get Response Example

Returns the contact object directly, including custom_fields keyed by each custom field’s API name — the same shape as a lookup item.

{
  "contact_id": "11111111-1111-4111-8111-111111111111",
  "display_name": "Jane Doe",
  "first_name": "Jane",
  "last_name": "Doe",
  "email": "jane@example.com",
  "phone": null,
  "company": "Acme",
  "job_title": "CEO",
  "original_source": "Public API",
  "lifecycle_stage": "subscriber",
  "unsubscribed": false,
  "custom_fields": {
    "favorite_color": "Green"
  },
  "created_at": "2026-04-30T12:00:00.000Z",
  "updated_at": "2026-04-30T12:00:00.000Z"
}

List Contacts

GET /v1/contacts?page=1&limit=100&updated_after=2026-07-01T00:00:00Z

Without an email/phone identifier, GET /v1/contacts pages through the workspace’s contacts.

Parameter	Type	Required	Notes
`page`	`integer`	No	1-based page number (default `1`)
`limit`	`integer`	No	Page size, max `100` (default `25`)
`sort`	`string`	No	`created_at` (default) \| `updated_at` \| `last_activity_at` \| `display_name` \| `first_name` \| `last_name` \| `normalized_email` \| `original_source`
`order`	`string`	No	`asc` \| `desc` (default)
`search`	`string`	No	Matches name, email, phone, and company
`updated_after`	`string`	No	ISO 8601 timestamp — only contacts updated after it. The building block for incremental syncs

Returns {items, pagination}. List items do not include custom_fields — fetch a single contact for those.

Update a Single Contact

PATCH /v1/contacts/{contact_id}

Single-record alternative to the batch update: the request body takes the same fields as an update item (minus contact_id), returns the updated contact directly, 404 when missing, and 409 with existing_contact when an email/phone change collides with another contact.

Delete a Single Contact

DELETE /v1/contacts/{contact_id}

Returns 204 on success, 404 when the contact does not exist.

Contact Activities

GET /v1/contacts/{contact_id}/activities?page=1&limit=25&order=desc

Read-only, paginated activity timeline: contact_created, contact_updated, email engagement events (sent, delivered, opened, clicked, bounced, unsubscribed), and flow entry/exit — each with a type, timestamp, and event-specific metadata.

Create Contacts

POST /v1/contacts

Request Body

Field	Type	Required	Notes
`items`	`array`	Yes	Between `1` and `100` contacts

Create Item Fields

Field	Type	Required	Notes
`email`	`string`	Conditionally	Either `email` or `phone` is required
`phone`	`string`	Conditionally	Either `email` or `phone` is required
`client_item_id`	`string`	No	Your own per-item identifier for reconciliation
`display_name`	`string`	No	Maximum `255` characters
`first_name`	`string`	No	Maximum `255` characters
`last_name`	`string`	No	Maximum `255` characters
`company`	`string`	No	Maximum `255` characters
`job_title`	`string`	No	Maximum `255` characters
`address`	`string`	No	Maximum `500` characters
`address2`	`string`	No	Maximum `255` characters
`city`	`string`	No	Maximum `255` characters
`state`	`string`	No	Maximum `255` characters
`country`	`string`	No	Maximum `255` characters
`zip_code`	`string`	No	Maximum `50` characters
`lead_status`	`string`	No	Maximum `100` characters
`lifecycle_stage`	`string`	No	Maximum `100` characters
`tented_score`	`number \| null`	No	Optional contact score
`unsubscribed`	`boolean`	No	Defaults to `false` when omitted
`marketing_email_subscribed`	`boolean \| null`	No	Email subscription state
`marketing_sms_subscribed`	`boolean \| null`	No	SMS subscription state

Create Request Example

curl --request POST \
  --url https://api.tented.ai/v1/contacts \
  --header "Authorization: Bearer $TENTED_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "items": [
      {
        "client_item_id": "crm-row-001",
        "email": "jane@example.com",
        "first_name": "Jane",
        "last_name": "Doe",
        "company": "Acme",
        "job_title": "CEO"
      },
      {
        "client_item_id": "crm-row-002",
        "phone": "+15551234567",
        "display_name": "Sam Rivera"
      }
    ]
  }'

Create Response Example

201 Created

{
  "status": "completed",
  "created_count": 2,
  "rejected_count": 0,
  "items": [
    {
      "index": 0,
      "client_item_id": "crm-row-001",
      "contact_id": "11111111-1111-4111-8111-111111111111",
      "status": "created",
      "contact": {
        "contact_id": "11111111-1111-4111-8111-111111111111",
        "display_name": "Jane Doe",
        "first_name": "Jane",
        "last_name": "Doe",
        "email": "jane@example.com",
        "phone": null,
        "company": "Acme",
        "job_title": "CEO",
        "original_source": "Public API",
        "created_at": "2026-04-30T12:00:00.000Z",
        "updated_at": "2026-04-30T12:00:00.000Z"
      }
    },
    {
      "index": 1,
      "client_item_id": "crm-row-002",
      "contact_id": "22222222-2222-4222-8222-222222222222",
      "status": "created",
      "contact": {
        "contact_id": "22222222-2222-4222-8222-222222222222",
        "display_name": "Sam Rivera",
        "email": null,
        "phone": "+15551234567",
        "original_source": "Public API",
        "created_at": "2026-04-30T12:00:00.000Z",
        "updated_at": "2026-04-30T12:00:00.000Z"
      }
    }
  ]
}

Duplicate Contacts

Tented checks normalized email and phone values before creating a contact. If an item matches an existing contact, that item is rejected with error_code: "conflict". If you want matches to be updated instead of rejected, use Upsert Contacts.

{
  "index": 0,
  "client_item_id": "crm-row-001",
  "status": "rejected",
  "error_code": "conflict",
  "message": "Contact already exists",
  "existing_contact": {
    "contact_id": "11111111-1111-4111-8111-111111111111",
    "display_name": "Jane Doe",
    "email": "jane@example.com",
    "phone": null
  }
}

Upsert Contacts

POST /v1/contacts/upsert

Create-or-update in one call — no conflict handling required. Each item (up to 100) is matched by its normalized email (or phone, for phone-only items): a match updates that contact, no match creates one. Items accept the full update field set including custom_fields, and each result reports status: "created" or "updated".

Matching is identifier-scoped: an item is only ever matched on its own identifier. If a new email’s item carries a phone that belongs to a different contact, the item is rejected with error_code: "conflict" and the existing_contact — it never silently modifies the phone-matched contact.

curl --request POST \
  --url 'https://api.tented.ai/v1/contacts/upsert' \
  --header 'Authorization: Bearer tented_your_api_key' \
  --header 'Content-Type: application/json' \
  --data '{
    "items": [
      {
        "email": "jane@example.com",
        "first_name": "Jane",
        "company": "Acme",
        "custom_fields": {"account_tier": "enterprise"}
      }
    ]
  }'

Response mirrors the batch format with created_count, updated_count, and rejected_count.

Search Contacts

POST /v1/contacts/search

Filter contacts with a rule tree — the same engine that powers dynamic lists and blast audiences.

Field	Type	Required	Notes
`rules`	`object`	Yes	AND/OR rule group over standard fields, custom fields, activity, and list membership (max depth `5`, max `100` conditions)
`page` / `limit`	`integer`	No	Pagination, `limit` ≤ `100`
`search`	`string`	No	Free-text filter applied alongside the rules
`sort` / `order`	`string`	No	Same sort keys as List Contacts

Discover the available fields and operators with GET /v1/contact-fields/rule-metadata.

Update Contacts

POST /v1/contacts/update

Request Body

Field	Type	Required	Notes
`items`	`array`	Yes	Between `1` and `100` update records

Update Item Fields

Field	Type	Required	Notes
`contact_id`	`uuid`	Yes	Contact to update
`client_item_id`	`string`	No	Your own per-item identifier for reconciliation
`email`	`string \| null`	No	Set to `null` to clear, as long as phone remains present
`phone`	`string \| null`	No	Set to `null` to clear, as long as email remains present
`display_name`	`string \| null`	No	Maximum `255` characters
`first_name`	`string`	No	Maximum `255` characters
`last_name`	`string`	No	Maximum `255` characters
`email_domain`	`string \| null`	No	Usually derived automatically from email
`company`	`string`	No	Maximum `255` characters
`job_title`	`string`	No	Maximum `255` characters
`address`	`string`	No	Maximum `500` characters
`address2`	`string`	No	Maximum `255` characters
`city`	`string`	No	Maximum `255` characters
`state`	`string`	No	Maximum `255` characters
`country`	`string`	No	Maximum `255` characters
`zip_code`	`string`	No	Maximum `50` characters
`original_source`	`string \| null`	No	Maximum `255` characters
`original_source_detail`	`string \| null`	No	Maximum `255` characters
`lead_status`	`string`	No	Maximum `100` characters
`lifecycle_stage`	`string`	No	Maximum `100` characters
`tented_score`	`number \| null`	No	Optional contact score
`unsubscribed`	`boolean`	No	Unsubscribe flag
`marketing_email_subscribed`	`boolean \| null`	No	Email subscription state
`marketing_sms_subscribed`	`boolean \| null`	No	SMS subscription state
`marketing_sms_invalid`	`boolean`	No	SMS validity flag
`custom_fields`	`object`	No	Editable custom fields by API name

A contact must always have at least one valid email or phone. An update that clears both identity fields is rejected for that item.

marketing_email_invalid is system-managed and read-only: Tented sets it to true when a marketing email to the contact hard-bounces, and resets it to false when the contact’s email address changes. It appears in contact responses and audience rules, but requests that include it are rejected.

Update Request Example

curl --request POST \
  --url https://api.tented.ai/v1/contacts/update \
  --header "Authorization: Bearer $TENTED_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "items": [
      {
        "client_item_id": "crm-row-001",
        "contact_id": "11111111-1111-4111-8111-111111111111",
        "company": "Acme Enterprise",
        "lead_status": "qualified",
        "custom_fields": {
          "favorite_color": "Green"
        }
      }
    ]
  }'

Update Response Example

200 OK

{
  "status": "completed",
  "updated_count": 1,
  "rejected_count": 0,
  "items": [
    {
      "index": 0,
      "client_item_id": "crm-row-001",
      "contact_id": "11111111-1111-4111-8111-111111111111",
      "status": "updated",
      "contact": {
        "contact_id": "11111111-1111-4111-8111-111111111111",
        "email": "jane@example.com",
        "company": "Acme Enterprise",
        "lead_status": "qualified",
        "updated_at": "2026-04-30T12:05:00.000Z"
      }
    }
  ]
}

Delete Contacts

POST /v1/contacts/delete
DELETE /v1/contacts

Use POST /v1/contacts/delete if your HTTP client does not support request bodies on DELETE.

Request Body

Field	Type	Required	Notes
`items`	`array`	Yes	Between `1` and `100` delete records

Delete Item Fields

Field	Type	Required	Notes
`contact_id`	`uuid`	Yes	Contact to delete
`client_item_id`	`string`	No	Your own per-item identifier for reconciliation

Delete Request Example

curl --request POST \
  --url https://api.tented.ai/v1/contacts/delete \
  --header "Authorization: Bearer $TENTED_API_KEY" \
  --header "Content-Type: application/json" \
  --data '{
    "items": [
      {
        "client_item_id": "crm-row-001",
        "contact_id": "11111111-1111-4111-8111-111111111111"
      }
    ]
  }'

Delete Response Example

200 OK

{
  "status": "completed",
  "deleted_count": 1,
  "rejected_count": 0,
  "items": [
    {
      "index": 0,
      "client_item_id": "crm-row-001",
      "contact_id": "11111111-1111-4111-8111-111111111111",
      "status": "deleted"
    }
  ]
}

Batch Response Format

Every contacts write endpoint returns:

Field	Type	Notes
`status`	`string`	Always `completed` after the request has been processed
`created_count`	`number`	Present on create responses
`updated_count`	`number`	Present on update responses
`deleted_count`	`number`	Present on delete responses
`rejected_count`	`number`	Number of rejected items
`items`	`array`	Per-item results in request order

Rejected items include:

Field	Type	Notes
`index`	`number`	Zero-based item index from the request
`client_item_id`	`string`	Returned when supplied
`contact_id`	`uuid`	Returned when supplied
`status`	`string`	`rejected`
`error_code`	`string`	`bad_request`, `not_found`, `conflict`, or `error`
`message`	`string`	Human-readable failure reason
`existing_contact`	`object`	Returned for duplicate conflicts

Common Item-Level Rejections

Error Code	Cause
`bad_request`	No fields to update
`bad_request`	Update would remove both email and phone
`bad_request`	Custom field is missing, inactive, non-editable, or has an invalid value
`not_found`	Contact does not exist in the workspace
`conflict`	Email or phone matches another existing contact

Common Request Errors

Status	Cause
`400 Bad Request`	Invalid JSON body
`400 Bad Request`	Request body is missing
`400 Bad Request`	`items` is missing, empty, or contains more than `100` records
`400 Bad Request`	A create item has neither `email` nor `phone`
`400 Bad Request`	Invalid email, phone, UUID, or field format
`401 Unauthorized`	Missing or invalid bearer token

Back to API Overview

Review the full Tented API endpoint map.

​Endpoints

​Look Up Contacts

​Query Parameters

​Lookup Request Example

​Lookup Response Example

​Get a Contact

​Path Parameters

​Get Request Example

​Get Response Example

​List Contacts

​Update a Single Contact

​Delete a Single Contact

​Contact Activities

​Create Contacts

​Request Body

​Create Item Fields

​Create Request Example

​Create Response Example

​Duplicate Contacts

​Upsert Contacts

​Search Contacts

​Update Contacts

​Request Body

​Update Item Fields

​Update Request Example

​Update Response Example

​Delete Contacts

​Request Body

​Delete Item Fields

​Delete Request Example

​Delete Response Example

​Batch Response Format

​Common Item-Level Rejections

​Common Request Errors

Back to API Overview

Endpoints

Look Up Contacts

Query Parameters

Lookup Request Example

Lookup Response Example

Get a Contact

Path Parameters

Get Request Example

Get Response Example

List Contacts

Update a Single Contact

Delete a Single Contact

Contact Activities

Create Contacts

Request Body

Create Item Fields

Create Request Example

Create Response Example

Duplicate Contacts

Upsert Contacts

Search Contacts

Update Contacts

Request Body

Update Item Fields

Update Request Example

Update Response Example

Delete Contacts

Request Body

Delete Item Fields

Delete Request Example

Delete Response Example

Batch Response Format

Common Item-Level Rejections

Common Request Errors