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

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.linkedin_urn

string | null

data.contact.linkedin_headline

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.last_note

object | null

data.contact.last_note.id

string (uuid)

data.contact.last_note.preview

string

data.contact.last_note.event_time

string (date-time)

data.contact.last_note.emoji

string | null

data.contact.last_note.meeting_type

string | 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 — 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/ \
  --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 } }`.