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", "granola_sync"

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 — Request body failed validation.

Content-Type: application/json

(body)

any

401 — Missing or invalid API key.

Content-Type: application/json

(body)

any

403 — Valid key, insufficient permission.

Content-Type: application/json

(body)

any

404 — Resource does not exist.

Content-Type: application/json

(body)

any

409 — Request conflicts with the current state of the resource.

Content-Type: application/json

(body)

any

429 — Rate limit exceeded.

Content-Type: application/json

(body)

any

500 — Unexpected server error.

Content-Type: application/json

(body)

any

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, alongside a `data.batch` partial-suc

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