Contacts

Bulk-update contacts

Update multiple contacts in a single request. Per-row results are settled (some can succeed, others fail). **Requires `Idempotency-Key`.** Returns `{ data: { affected, ids } }` where `ids` lists the c

POST /v2/contacts/batch-update

Parameters

Header parameters

Idempotency-Key

string required

Required. UUID per logical operation, reused on every retry. See apps/rest-api/src/shared/idempotency.ts for the full contract. Missing → 400 BadRequest; same key + different body → 409 Conflict.

Request body

Content-Type: application/json

updates

array<object> required

updates[].contactId

string (uuid) required

updates[].data

object required

updates[].data.full_name

string

updates[].data.first_name

string

updates[].data.last_name

string

updates[].data.description

string

updates[].data.job_title

string

updates[].data.legacy_location

string

updates[].data.company

string

updates[].data.education

string

updates[].data.starred

boolean

updates[].data.source

string enum

Possible values: "linkedin_sync", "facebook_import", "cal_ingest", "email_ingest", "web_import", "csv_import", "whatsapp_sync", "imessage_sync", "phone_calls_sync", "mobile", "mobile_import", "instagram_sync", "oauth_interaction"

updates[].data.coordinates

object

updates[].data.coordinates.operation

string enum

Possible values: "set", "delete"

updates[].data.coordinates.data

object

updates[].data.coordinates.data.latitude

number

updates[].data.coordinates.data.longitude

number

updates[].data.priority_tier

integer

updates[].data.image_url

string (uri)

updates[].data.image_source

string (uri)

updates[].data.business_card_url

string (uri)

updates[].data.website

any

updates[].data.birthday

string (date)

updates[].data.birthday_year

number

updates[].data.frequency

string

updates[].data.last_seen_at

any

updates[].data.first_met_at

any

updates[].data.never_keep_in_touch

boolean

updates[].data.next_reminder_at

any

updates[].data.linkedin

string

updates[].data.twitter

string

updates[].data.facebook

string

updates[].data.instagram

string

updates[].data.telegram

string

updates[].data.tiktok

string

updates[].data.youtube

string

updates[].data.whatsapp_message_link

string

updates[].data.whatsapp_message_snippet

string

updates[].data.whatsapp_last_message_at

any

updates[].data.imessage_message_link

string

updates[].data.imessage_message_snippet

string

updates[].data.imessage_last_message_at

any

updates[].data.linkedin_message_link

string

updates[].data.linkedin_last_message_snippet

string

updates[].data.linkedin_last_message_at

any

updates[].data.linkedin_data

object

updates[].data.instagram_message_link

string

updates[].data.instagram_message_snippet

string

updates[].data.instagram_last_message_at

any

updates[].data.gmail_last_interaction_at

any

updates[].data.gmail_last_interaction_provider_id

string

updates[].data.gmail_last_interaction_subject

string

updates[].data.gmail_last_interaction_provider

string enum

Possible values: "GOOGLE", "OFFICE365"

updates[].data.gcal_last_interaction_at

any

updates[].data.gcal_last_interaction_provider_id

string

updates[].data.gcal_last_interaction_title

string

updates[].data.gcal_last_interaction_provider

string enum

Possible values: "GOOGLE", "OFFICE365"

updates[].data.phone_call_last_interaction_at

any

updates[].data.phone_call_interaction_snippet

string

updates[].data.web_search_summary

object

updates[].data.legacy_contact_addresses

array<object>

updates[].data.legacy_contact_addresses[].formatted

string

updates[].data.contact_emails

array<object>

updates[].data.contact_emails[].email

string

updates[].data.contact_emails[].label

string

updates[].data.contact_emails[].ranking

number

updates[].data.contact_phone_numbers

array<object>

updates[].data.contact_phone_numbers[].phone_number

string

updates[].data.contact_phone_numbers[].country_code

string

updates[].data.contact_phone_numbers[].phone_number_sanitized

string

updates[].data.contact_phone_numbers[].label

string

updates[].data.contact_phone_numbers[].ranking

number

updates[].data.groups_contacts

array<object>

updates[].data.groups_contacts[].group_id

string (uuid)

updates[].data.tags_contacts

object

updates[].data.tags_contacts.append

array<object>

updates[].data.tags_contacts.append[].tag_id

string (uuid)

updates[].data.tags_contacts.remove

array<object>

updates[].data.tags_contacts.remove[].tag_id

string (uuid)

updates[].data.tags_contacts.remove[].contact_id

string (uuid)

updates[].data.tags_contacts.replace

any

updates[].data.custom_fields

array<object>

updates[].data.custom_fields[].id

string (uuid)

updates[].data.custom_fields[].type

string enum

Possible values: "input"

updates[].data.custom_fields[].text_value

string

updates[].data.custom_fields[].custom_field

any

updates[].data.contact_birthdays

object

updates[].data.contact_birthdays.contact_id

string (uuid)

updates[].data.contact_birthdays.last_dismissal_year

number

updates[].data.is_archived

boolean

updates[].data.ignore_merge

boolean

updates[].data.related_contacts

object

updates[].data.related_contacts.append

array<object>

updates[].data.related_contacts.append[].destination

string (uuid)

updates[].data.related_contacts.append[].source_contact

any

updates[].data.related_contacts.append[].destination_contact

any

updates[].data.related_contacts.remove

array<object>

updates[].data.related_contacts.remove[].source

string (uuid)

updates[].data.related_contacts.remove[].destination

any

updates[].data.related_contacts.replace

any

Example

{
  "updates": [
    {
      "contactId": "00000000-0000-0000-0000-000000000000",
      "data": {
        "full_name": "string",
        "first_name": "string"
      }
    }
  ]
}

Responses

200 — Successful response

Content-Type: application/json

data

object required

data.affected

integer required

data.ids

array<string>

data.failed

array<object>

data.failed[].id

string

data.failed[].error

object

data.failed[].error.code

string

data.failed[].error.message

string

Example

{
  "data": {
    "affected": 0
  }
}

400

No response body.

401

No response body.

403

No response body.

404

No response body.

409

No response body.

429

No response body.

500

No response body.

Code samples

curl https://api.prod.getdex.com/v2/contacts/batch-update \
  --request POST \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "updates": [
    {
      "contactId": "00000000-0000-0000-0000-000000000000",
      "data": {
        "full_name": "string",
        "first_name": "string"
      }
    }
  ]
}'

fetch('https://api.prod.getdex.com/v2/contacts/batch-update', {
  method: 'POST',
  headers: {
    Authorization: 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    updates: [
      {
        contactId: '00000000-0000-0000-0000-000000000000',
        data: {
          full_name: 'string',
          first_name: 'string'
        }
      }
    ]
  })
})

requests.post(
    "https://api.prod.getdex.com/v2/contacts/batch-update",
    headers={
      "Authorization": "Bearer YOUR_API_KEY",
      "Content-Type": "application/json"
    },
    json={
      "updates": [
        {
          "contactId": "00000000-0000-0000-0000-000000000000",
          "data": {
            "full_name": "string",
            "first_name": "string"
          }
        }
      ]
    }
)

Bulk-create contacts

Create multiple contacts in a single request. **Requires `Idempotency-Key`.** Returns the created contacts as `{ data: { contacts: [...] } }` with status 201.

Bulk-delete contacts

Permanently delete multiple contacts in a single request. Returns `{ data: { affected, ids } }` where `ids` is the array of deleted contact IDs (echoed from the request body). `Idempotency-Key` is opt