Contacts

Bulk-create contacts

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

POST /v2/contacts/batch

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

contacts

array<object> required

contacts[].full_name

string

contacts[].first_name

string

contacts[].last_name

string

contacts[].description

string

contacts[].job_title

string

contacts[].legacy_location

string

contacts[].company

string

contacts[].education

string

contacts[].starred

boolean

contacts[].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"

contacts[].coordinates

object

contacts[].coordinates.operation

string enum

Possible values: "set", "delete"

contacts[].coordinates.data

object

contacts[].coordinates.data.latitude

number

contacts[].coordinates.data.longitude

number

contacts[].priority_tier

integer

contacts[].image_url

string (uri)

contacts[].image_source

string (uri)

contacts[].business_card_url

string (uri)

contacts[].website

any

contacts[].birthday

string (date)

contacts[].birthday_year

number

contacts[].frequency

string

contacts[].last_seen_at

any

contacts[].first_met_at

any

contacts[].never_keep_in_touch

boolean

contacts[].next_reminder_at

any

contacts[].linkedin

string

contacts[].twitter

string

contacts[].facebook

string

contacts[].instagram

string

contacts[].telegram

string

contacts[].tiktok

string

contacts[].youtube

string

contacts[].whatsapp_message_link

string

contacts[].whatsapp_message_snippet

string

contacts[].whatsapp_last_message_at

any

contacts[].imessage_message_link

string

contacts[].imessage_message_snippet

string

contacts[].imessage_last_message_at

any

contacts[].linkedin_message_link

string

contacts[].linkedin_last_message_snippet

string

contacts[].linkedin_last_message_at

any

contacts[].linkedin_data

object

contacts[].instagram_message_link

string

contacts[].instagram_message_snippet

string

contacts[].instagram_last_message_at

any

contacts[].gmail_last_interaction_at

any

contacts[].gmail_last_interaction_provider_id

string

contacts[].gmail_last_interaction_subject

string

contacts[].gmail_last_interaction_provider

string enum

Possible values: "GOOGLE", "OFFICE365"

contacts[].gcal_last_interaction_at

any

contacts[].gcal_last_interaction_provider_id

string

contacts[].gcal_last_interaction_title

string

contacts[].gcal_last_interaction_provider

string enum

Possible values: "GOOGLE", "OFFICE365"

contacts[].phone_call_last_interaction_at

any

contacts[].phone_call_interaction_snippet

string

contacts[].web_search_summary

object

contacts[].legacy_contact_addresses

array<object>

contacts[].legacy_contact_addresses[].formatted

string

contacts[].contact_emails

array<object>

contacts[].contact_emails[].email

string

contacts[].contact_emails[].label

string

contacts[].contact_emails[].ranking

number

contacts[].contact_phone_numbers

array<object>

contacts[].contact_phone_numbers[].phone_number

string

contacts[].contact_phone_numbers[].country_code

string

contacts[].contact_phone_numbers[].phone_number_sanitized

string

contacts[].contact_phone_numbers[].label

string

contacts[].contact_phone_numbers[].ranking

number

contacts[].groups_contacts

array<object>

contacts[].groups_contacts[].group_id

string (uuid)

contacts[].tags_contacts

array<object>

contacts[].tags_contacts[].tag_id

string (uuid)

contacts[].custom_fields

array<object>

contacts[].custom_fields[].id

string (uuid)

contacts[].custom_fields[].type

string enum

Possible values: "input"

contacts[].custom_fields[].text_value

string

contacts[].custom_fields[].custom_field

any

contacts[].contact_birthdays

object

contacts[].contact_birthdays.contact_id

string (uuid)

contacts[].contact_birthdays.last_dismissal_year

number

contacts[].id

string (uuid)

contacts[].related_contacts

array<object>

contacts[].related_contacts[].destination

string (uuid)

contacts[].related_contacts[].source_contact

any

contacts[].related_contacts[].destination_contact

any

Example

{
  "contacts": [
    {
      "full_name": "string",
      "first_name": "string"
    }
  ]
}

Responses

201 — Created

Content-Type: application/json

data

object required

data.contacts

array<object> required

data.contacts[].id

string (uuid) required

data.contacts[].user_id

string

data.contacts[].first_name

string | null

data.contacts[].last_name

string | null

data.contacts[].full_name

string | null

data.contacts[].description

string | null

data.contacts[].job_title

string | null

data.contacts[].company

string | null

data.contacts[].education

string | null

data.contacts[].legacy_location

string | null

data.contacts[].image_url

string | null

data.contacts[].business_card_url

string | null

data.contacts[].website

string | null

data.contacts[].image_source

string | null

data.contacts[].birthday

string (date-time)

data.contacts[].birthday_year

integer | null

data.contacts[].linkedin

string | null

data.contacts[].twitter

string | null

data.contacts[].facebook

string | null

data.contacts[].instagram

string | null

data.contacts[].telegram

string | null

data.contacts[].tiktok

string | null

data.contacts[].youtube

string | null

data.contacts[].starred

boolean

data.contacts[].is_archived

boolean

data.contacts[].ignore_merge

boolean

data.contacts[].never_keep_in_touch

boolean

data.contacts[].source

string

data.contacts[].priority_tier

integer | null

data.contacts[].frequency

string | null

data.contacts[].frequency_text

string | null

data.contacts[].last_seen_at

string (date-time)

data.contacts[].last_reminder_at

string (date-time)

data.contacts[].next_reminder_at

string (date-time)

data.contacts[].first_met_at

string (date-time)

data.contacts[].first_interaction_at

string (date-time)

data.contacts[].linkedin_companies

string | null

data.contacts[].linkedin_education

string | null

data.contacts[].linkedin_enhance_date

string (date-time)

data.contacts[].linkedin_last_message_at

string (date-time)

data.contacts[].linkedin_last_message_snippet

string | null

data.contacts[].linkedin_message_link

string | null

data.contacts[].whatsapp_message_link

string | null

data.contacts[].whatsapp_message_snippet

string | null

data.contacts[].whatsapp_last_message_at

string (date-time)

data.contacts[].imessage_message_link

string | null

data.contacts[].imessage_message_snippet

string | null

data.contacts[].imessage_last_message_at

string (date-time)

data.contacts[].instagram_message_link

string | null

data.contacts[].instagram_message_snippet

string | null

data.contacts[].instagram_last_message_at

string (date-time)

data.contacts[].gmail_last_interaction_at

string (date-time)

data.contacts[].gmail_last_interaction_provider

string enum

Possible values: "GOOGLE", "OFFICE365"

data.contacts[].gmail_last_interaction_provider_id

string | null

data.contacts[].gmail_last_interaction_subject

string | null

data.contacts[].gcal_last_interaction_at

string (date-time)

data.contacts[].gcal_last_interaction_provider

string enum

Possible values: "GOOGLE", "OFFICE365"

data.contacts[].gcal_last_interaction_provider_id

string | null

data.contacts[].gcal_last_interaction_title

string | null

data.contacts[].phone_call_interaction_snippet

string | null

data.contacts[].phone_call_last_interaction_at

string (date-time)

data.contacts[].web_search_summary

any | null

data.contacts[].created_at

string (date-time)

data.contacts[].updated_at

string (date-time)

data.contacts[].geocode_attempts

integer

data.contacts[].geocode_failed_at

string (date-time)

data.contacts[]._count

object

data.contacts[]._count.groups_contacts

integer

data.contacts[].frequency_interval

any

data.contacts[].linkedin_data

object | null

data.contacts[].latitude

number | null

data.contacts[].longitude

number | null

data.contacts[].contact_emails

array<object>

data.contacts[].contact_phone_numbers

array<object>

data.contacts[].contact_birthdays

object | null

data.contacts[].contact_locations

array<object>

data.contacts[].contacts_custom_fields

array<object>

data.contacts[].legacy_contact_addresses

array<object>

data.contacts[].groups_contacts

array<object>

data.contacts[].tags_contacts

array<object>

data.contacts[].timeline_items_contacts

array<object>

data.contacts[].reminders_contacts

array<object>

data.contacts[].contact_relations_contact_relations_sourceTocontacts

array<object>

data.contacts[].contact_relations_contact_relations_destinationTocontacts

array<object>

data.contacts[].feed_items

array<object>

data.contacts[].keep_in_touch_reminders

object | null

data.pagination

object

data.pagination.nextCursor

string | null

data.pagination.count

integer

Example

{
  "data": {
    "contacts": [
      {
        "id": "00000000-0000-0000-0000-000000000000"
      }
    ]
  }
}

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 \
  --request POST \
  --header 'Authorization: Bearer YOUR_API_KEY' \
  --header 'Content-Type: application/json' \
  --data '{
  "contacts": [
    {
      "full_name": "string",
      "first_name": "string"
    }
  ]
}'

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

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

Get a contact

Retrieve a contact by ID. Email and phone relations are omitted by default; request them with `?include[contact_emails]=true` or `?include[contact_phone_numbers]=true`.

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