Contacts

Create a contact

Create ONE contact. The common case — TanStack DB optimistic mutations, mobile add-contact, MCP tools. **Requires `Idempotency-Key`.** Returns `{ data: { contact: {...} } }` with status 201. For bulk

POST /v2/contacts/

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

full_name

string

first_name

string

last_name

string

description

string

job_title

string

legacy_location

string

company

string

education

string

starred

boolean

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"

coordinates

object

coordinates.operation

string enum

Possible values: "set", "delete"

coordinates.data

object

coordinates.data.latitude

number

coordinates.data.longitude

number

priority_tier

integer

image_url

string (uri)

image_source

string (uri)

business_card_url

string (uri)

website

any

birthday

string (date)

birthday_year

number

frequency

string

last_seen_at

any

first_met_at

any

never_keep_in_touch

boolean

next_reminder_at

any

string

twitter

string

facebook

string

instagram

string

tiktok

string

youtube

string

whatsapp_message_link

string

whatsapp_message_snippet

string

whatsapp_last_message_at

any

imessage_message_link

string

imessage_message_snippet

string

imessage_last_message_at

any

linkedin_message_link

string

linkedin_last_message_snippet

string

linkedin_last_message_at

any

linkedin_data

object

instagram_message_link

string

instagram_message_snippet

string

instagram_last_message_at

any

gmail_last_interaction_at

any

gmail_last_interaction_provider_id

string

gmail_last_interaction_subject

string

gmail_last_interaction_provider

string enum

Possible values: "GOOGLE", "OFFICE365"

gcal_last_interaction_at

any

gcal_last_interaction_provider_id

string

gcal_last_interaction_title

string

gcal_last_interaction_provider

string enum

Possible values: "GOOGLE", "OFFICE365"

phone_call_last_interaction_at

any

phone_call_interaction_snippet

string

web_search_summary

object

legacy_contact_addresses

array<object>

legacy_contact_addresses[].formatted

string

contact_emails

array<object>

contact_emails[].email

string

contact_emails[].label

string

contact_emails[].ranking

number

contact_phone_numbers

array<object>

contact_phone_numbers[].phone_number

string

contact_phone_numbers[].country_code

string

contact_phone_numbers[].phone_number_sanitized

string

contact_phone_numbers[].label

string

contact_phone_numbers[].ranking

number

groups_contacts

array<object>

groups_contacts[].group_id

string (uuid)

tags_contacts

array<object>

tags_contacts[].tag_id

string (uuid)

custom_fields

array<object>

custom_fields[].id

string (uuid)

custom_fields[].type

string enum

Possible values: "input"

custom_fields[].text_value

string

custom_fields[].custom_field

any

contact_birthdays

object

contact_birthdays.contact_id

string (uuid)

contact_birthdays.last_dismissal_year

number

string (uuid)

related_contacts

array<object>

related_contacts[].destination

string (uuid)

related_contacts[].source_contact

any

related_contacts[].destination_contact

any

Example

{
  "full_name": "string",
  "first_name": "string"
}

Responses

201 — Created

Content-Type: application/json

data

object required

data.contact

object required

data.contact.id

string (uuid) required

data.contact.user_id

string

data.contact.first_name

string | null

data.contact.last_name

string | null

data.contact.full_name

string | null

data.contact.description

string | null

data.contact.job_title

string | null

data.contact.company

string | null

data.contact.education

string | null

data.contact.legacy_location

string | null

data.contact.image_url

string | null

data.contact.business_card_url

string | null

data.contact.website

string | null

data.contact.image_source

string | null

data.contact.birthday

string (date-time)

data.contact.birthday_year

integer | null

data.contact.linkedin

string | null

data.contact.twitter

string | null

data.contact.facebook

string | null

data.contact.instagram

string | null

data.contact.telegram

string | null

data.contact.tiktok

string | null

data.contact.youtube

string | null

data.contact.starred

boolean

data.contact.is_archived

boolean

data.contact.ignore_merge

boolean

data.contact.never_keep_in_touch

boolean

data.contact.source

string

data.contact.priority_tier

integer | null

data.contact.frequency

string | null

data.contact.frequency_text

string | null

data.contact.last_seen_at

string (date-time)

data.contact.last_reminder_at

string (date-time)

data.contact.next_reminder_at

string (date-time)

data.contact.first_met_at

string (date-time)

data.contact.first_interaction_at

string (date-time)

data.contact.linkedin_companies

string | null

data.contact.linkedin_education

string | null

data.contact.linkedin_enhance_date

string (date-time)

data.contact.linkedin_last_message_at

string (date-time)

data.contact.linkedin_last_message_snippet

string | null

data.contact.linkedin_message_link

string | null

data.contact.whatsapp_message_link

string | null

data.contact.whatsapp_message_snippet

string | null

data.contact.whatsapp_last_message_at

string (date-time)

data.contact.imessage_message_link

string | null

data.contact.imessage_message_snippet

string | null

data.contact.imessage_last_message_at

string (date-time)

data.contact.instagram_message_link

string | null

data.contact.instagram_message_snippet

string | null

data.contact.instagram_last_message_at

string (date-time)

data.contact.gmail_last_interaction_at

string (date-time)

data.contact.gmail_last_interaction_provider

string enum

Possible values: "GOOGLE", "OFFICE365"

data.contact.gmail_last_interaction_provider_id

string | null

data.contact.gmail_last_interaction_subject

string | null

data.contact.gcal_last_interaction_at

string (date-time)

data.contact.gcal_last_interaction_provider

string enum

Possible values: "GOOGLE", "OFFICE365"

data.contact.gcal_last_interaction_provider_id

string | null

data.contact.gcal_last_interaction_title

string | null

data.contact.phone_call_interaction_snippet

string | null

data.contact.phone_call_last_interaction_at

string (date-time)

data.contact.web_search_summary

any | null

data.contact.created_at

string (date-time)

data.contact.updated_at

string (date-time)

data.contact.geocode_attempts

integer

data.contact.geocode_failed_at

string (date-time)

data.contact._count

object

data.contact._count.groups_contacts

integer

data.contact.frequency_interval

any

data.contact.linkedin_data

object | null

data.contact.latitude

number | null

data.contact.longitude

number | null

data.contact.contact_emails

array<object>

data.contact.contact_phone_numbers

array<object>

data.contact.contact_birthdays

object | null

data.contact.contact_locations

array<object>

data.contact.contacts_custom_fields

array<object>

data.contact.legacy_contact_addresses

array<object>

data.contact.groups_contacts

array<object>

data.contact.tags_contacts

array<object>

data.contact.timeline_items_contacts

array<object>

data.contact.reminders_contacts

array<object>

data.contact.contact_relations_contact_relations_sourceTocontacts

array<object>

data.contact.contact_relations_contact_relations_destinationTocontacts

array<object>

data.contact.feed_items

array<object>

data.contact.keep_in_touch_reminders

object | null

Example

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

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

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

List contacts

Retrieve contacts for the authenticated user with cursor pagination, filtering (`where`), sorting (`orderBy`), and field selection (`include` / `select`). Returns `{ data: { contacts: [...], paginatio

Count contacts

Return the count of contacts matching the optional `where` filter. Returns `{ data: { count } }`.