Contacts API
A contact is one person, identified by a phone number. Calls, WhatsApp conversations, appointments and campaign enrollments link to it, and it holds your workspace's own contact fields.
contacts:readcontacts:writecampaigns:readcampaigns:writeconversions:write15 endpointsShow
International numbers only
Creating a contact or changing its number needs the full international number: a + and the country code, such as +14155551234. The API never guesses a country, because a wrong guess binds the contact to another person's number. Older contacts may still hold national numbers; reads return them as stored.
/v1/contactsList contacts
Lists contacts, newest first, with optional search and tag filters. Each contact carries fields: its contact field values by key.
contacts:readQuery parameters
limitinteger · 1–100Results per page. Default: 20.
offsetinteger · at least 0Results to skip. Default: 0.
searchstringSubstring of the phone number, first, last or display name, or email (case-insensitive; commas and parentheses are ignored).
tagstringOnly contacts carrying this tag.
Errors
400validation_errorA query parameter is invalid (details.errors lists each one).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl "https://www.nutalk.ai/v1/contacts?search=jane&limit=10" \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": [
{
"id": "9595b646-ab97-4485-b1b8-e8b58dfcdd19",
"phone_number": "+14155551234",
"first_name": "Jane",
"last_name": "Smith",
"display_name": null,
"email": "jane@example.com",
"company": "Tech Startup",
"notes": null,
"tags": [
"prospect",
"inbound"
],
"source": "api",
"do_not_contact_at": null,
"first_contact_at": null,
"last_contact_at": "2026-10-02T02:14:49.108017+00:00",
"created_at": "2026-10-02T02:25:06.947918+00:00",
"updated_at": "2026-10-02T02:25:06.947918+00:00",
"fields": {
"interes": "Departamento",
"presupuesto": "2500000"
}
}
],
"pagination": {
"total": 1,
"limit": 10,
"offset": 0,
"has_more": false
}
}/v1/contactsCreate a contact
Creates a contact. The phone number must be international (a + and the country code): the API never guesses a country. Each phone number belongs to one contact per workspace; Mexican mobile numbers with and without the 1 after +52 count as the same number.
contacts:writeRequest body
phone_numberstring · up to 20requiredE.164 number with the country code, e.g. +14155551234.
first_namestring · up to 100First name.
last_namestring · up to 100Last name.
display_namestring · up to 200Name to show instead of first + last.
emailstringEmail address.
companystring · up to 200Company.
notesstring · up to 2,000Internal notes.
tagsstring[]Tags. On update the list replaces the current tags.
fieldsobjectContact field values by field key (GET /v1/contact-fields lists the keys), e.g. {"interes": "Departamento"}. A value is a string, number or boolean and must fit the field's type (a number field takes 1,234.50 or 1234.5 and stores 1234.5; a date field YYYY-MM-DD; a choice field one of its options). null clears a value; keys you leave out keep theirs. One value that doesn't fit fails the whole request (422, every problem in details.issues).
Show 5 more fields
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).400validation_errorThe phone number is not a complete international number (details.phoneUnroutable).422validation_errorA value in fields doesn't fit its field, or names no field (details.issues). Nothing was created.409validation_errorA contact with this phone number already exists. Find it with GET /v1/contacts?search=<number>.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X POST https://www.nutalk.ai/v1/contacts \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"phone_number": "+14155551234",
"first_name": "Jane",
"last_name": "Smith",
"email": "jane@example.com",
"company": "Tech Startup",
"tags": [
"prospect",
"inbound"
],
"fields": {
"interes": "Departamento"
}
}'source is api){
"success": true,
"data": {
"id": "9595b646-ab97-4485-b1b8-e8b58dfcdd19",
"phone_number": "+14155551234",
"first_name": "Jane",
"last_name": "Smith",
"display_name": null,
"email": "jane@example.com",
"company": "Tech Startup",
"notes": null,
"tags": [
"prospect",
"inbound"
],
"source": "api",
"created_at": "2026-10-02T02:25:06.947918+00:00",
"updated_at": "2026-10-02T02:25:06.947918+00:00",
"fields": {
"interes": "Departamento"
}
}
}/v1/contacts/:idGet a contact
Returns one contact, including crm_ids (its record ids in connected CRMs such as HubSpot or Kommo) and fields (its contact field values by key).
contacts:readPath parameters
iduuidrequiredThe contact id.
Errors
404not_foundNo contact with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/contacts/9595b646-ab97-4485-b1b8-e8b58dfcdd19 \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"id": "9595b646-ab97-4485-b1b8-e8b58dfcdd19",
"phone_number": "+14155551234",
"first_name": "Jane",
"last_name": "Smith",
"display_name": null,
"email": "jane@example.com",
"company": "Tech Startup",
"notes": null,
"tags": [
"prospect",
"inbound"
],
"source": "api",
"do_not_contact_at": null,
"first_contact_at": null,
"last_contact_at": "2026-10-02T02:14:49.108017+00:00",
"created_at": "2026-10-02T02:25:06.947918+00:00",
"updated_at": "2026-10-02T02:25:06.947918+00:00",
"fields": {
"interes": "Departamento",
"presupuesto": "2500000"
},
"crm_ids": {
"hubspot": "12345"
}
}
}/v1/contacts/:idUpdate a contact
Changes the fields you send. do_not_contact: true opts the person out of every campaign call and message (do_not_contact_at is set); false lifts it. A new phone number must be international, and is refused while the contact's history (calls, conversations, appointments, campaign outreach) is tied to the old one.
contacts:writeCan wait for approvalPath parameters
iduuidrequiredThe contact id.
Request body
phone_numberstring · up to 20New E.164 number with the country code.
first_namestring · up to 100First name.
last_namestring · up to 100Last name.
display_namestring · up to 200Name to show instead of first + last.
emailstringEmail address.
companystring · up to 200Company.
notesstring · up to 2,000Internal notes.
tagsstring[]Tags. On update the list replaces the current tags.
do_not_contactbooleantrue: never call or message this person from campaigns; false: allow again.
confirm_phone_changebooleanOnly for repairing a legacy contact whose stored phone identities disagree: confirms that the number you send is the right one.
fieldsobjectContact field values by field key (GET /v1/contact-fields lists the keys), e.g. {"interes": "Departamento"}. A value is a string, number or boolean and must fit the field's type (a number field takes 1,234.50 or 1234.5 and stores 1234.5; a date field YYYY-MM-DD; a choice field one of its options). null clears a value; keys you leave out keep theirs. One value that doesn't fit fails the whole request (422, every problem in details.issues).
Show 7 more fields
Nothing changes yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).400validation_errorNo field to change was sent.422validation_errorA value in fields doesn't fit its field, names no field or an archived one (details.issues). Nothing was changed.404not_foundNo contact with this id in your workspace (ids of other workspaces answer the same).409validation_errorThe phone change is blocked by linked history (details.phoneChangeBlocked), another contact already has the number, or the contact changed meanwhile (retry).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X PATCH https://www.nutalk.ai/v1/contacts/9595b646-ab97-4485-b1b8-e8b58dfcdd19 \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"company": "Enterprise Corp",
"tags": [
"customer",
"enterprise"
],
"fields": {
"presupuesto": 2500000,
"interes": null
}
}'fields (all its values after the change) when the request sent fields.{
"success": true,
"data": {
"id": "9595b646-ab97-4485-b1b8-e8b58dfcdd19",
"phone_number": "+14155551234",
"first_name": "Jane",
"last_name": "Smith",
"display_name": null,
"email": "jane@example.com",
"company": "Enterprise Corp",
"notes": null,
"tags": [
"customer",
"enterprise"
],
"source": "api",
"do_not_contact_at": null,
"first_contact_at": null,
"last_contact_at": "2026-10-02T02:14:49.108017+00:00",
"created_at": "2026-10-02T02:25:06.947918+00:00",
"updated_at": "2026-10-02T02:25:15.469118+00:00",
"fields": {
"presupuesto": "2500000"
}
}
}/v1/contacts/:idDelete a contact
Permanently deletes a contact that has no history. A contact with calls, conversations, appointments or campaign outreach cannot be deleted (409), so that history is never reassigned to another person; opt it out with do_not_contact instead.
contacts:writeWaits for approvalPath parameters
iduuidrequiredThe contact id.
Unless its key was set not to wait, nothing is removed yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
404not_foundNo contact with this id in your workspace (ids of other workspaces answer the same).409validation_errorThe contact has linked history.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X DELETE https://www.nutalk.ai/v1/contacts/9595b646-ab97-4485-b1b8-e8b58dfcdd19 \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"deleted": true
}
}/v1/exclusionsAdd numbers to the exclusion list
Adds up to 1000 phone numbers to the workspace's exclusion list: no campaign calls or messages them again. The contacts that own each number are opted out (do_not_contact_at is set, the same as do_not_contact: true) and their pending campaign enrollments close; a number that is not a contact yet becomes a contact already opted out (source is exclusion_list). Numbers must be international (a + and the country code). Every number gets an answer, in the order sent: excluded, already_excluded (nothing changed), own_number (one of the workspace's own lines, never a contact), duplicate (the same number earlier in the request) or invalid. Sending the same numbers again changes nothing.
contacts:writeTakes an Idempotency-KeyTo lift an opt-out, PATCH the contact with do_not_contact: false.
Request body
phone_numbersstring[] · 1–1000 itemsrequiredNumbers to exclude, 1 to 1000.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X POST https://www.nutalk.ai/v1/exclusions \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"phone_numbers": [
"+528112345678",
"+14155551234",
"8112345678"
]
}'{
"success": true,
"data": {
"excluded": 2,
"already_excluded": 0,
"created": 1,
"own_number": 0,
"invalid": 1,
"duplicate": 0,
"results": [
{
"phone_number": "+528112345678",
"e164": "+528112345678",
"status": "excluded",
"contact_id": "9595b646-ab97-4485-b1b8-e8b58dfcdd19",
"created": false
},
{
"phone_number": "+14155551234",
"e164": "+14155551234",
"status": "excluded",
"contact_id": "c2b3c4d5-e6f7-4a81-9bac-1d2e3f4a5b6c",
"created": true
},
{
"phone_number": "8112345678",
"e164": null,
"status": "invalid",
"contact_id": null,
"created": false
}
]
}
}/v1/contacts/:id/listsList a contact's lists
The workspace's contact lists the contact is a member of, by name, as the contact's page shows them.
contacts:readNeeds contact_lists:read as well as contacts:read.
Path parameters
iduuidrequiredThe contact id.
Errors
404not_foundNo contact with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/contacts/9595b646-ab97-4485-b1b8-e8b58dfcdd19/lists \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": [
{
"id": "d2406224-509f-4177-9a5a-b50bee1e7590",
"name": "Q2 Prospects",
"description": "Imported prospect list",
"contact_count": 2,
"created_at": "2026-10-02T02:25:25.707964+00:00",
"updated_at": "2026-10-02T02:25:25.707964+00:00"
}
]
}/v1/contacts/bulk-tagsTag many contacts
Adds tags to up to 200 contacts, removes tags from them, or both, as the contacts board's bulk "Add tag" does: each contact keeps its other tags.
contacts:writeCan wait for approvalWorkspace keys only · acts as the key's creatorTags match exactly ("VIP" and "vip" are two tags). A tag both added and removed is removed.
A key whose changes wait for approval holds this request until an owner or admin approves it.
Request body
contact_idsuuid[] · 1–200 itemsrequiredThe contacts.
addstring[] · 0–10 itemsTags to add (trimmed, 1 to 60 characters each).
removestring[] · 0–10 itemsTags to remove. Send at least one tag to add or remove.
Nothing changes yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X POST https://www.nutalk.ai/v1/contacts/bulk-tags \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"contact_ids": [
"9595b646-ab97-4485-b1b8-e8b58dfcdd19",
"eaa5bc4d-b54a-4cb2-bcf8-c1b523f716eb"
],
"add": [
"vip"
],
"remove": [
"prospect"
]
}'{
"success": true,
"data": {
"add": [
"vip"
],
"remove": [
"prospect"
],
"updated": [
"9595b646-ab97-4485-b1b8-e8b58dfcdd19"
],
"unchanged": [
"eaa5bc4d-b54a-4cb2-bcf8-c1b523f716eb"
],
"not_found": []
}
}/v1/contact-rulesGet the contact rules
The rules every campaign of the workspace follows (Settings → Workspace → Campaign calls): after someone talks with your agent on a call, no campaign calls that number again for cooldown_days days (null: the rule is off), and cooldown_action says what a campaign does with a number still inside that period. The same campaign's retries and the callbacks people ask for still go out.
campaigns:readcooldown_action: wait calls the number once the period ends (it stays in the campaign); skip leaves it out of the campaign.
Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/contact-rules \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"cooldown_days": 90,
"cooldown_action": "wait"
}
}/v1/contact-rulesSet the contact rules
Sets the rules every campaign of the workspace follows, as Settings → Workspace → Campaign calls does. A changed period re-dates every number the rule holds in the workspace's campaigns.
campaigns:writeCan wait for approvalWorkspace keys only · acts as the key's creatorThe change is made as the member who created the key, and a key whose changes wait for approval holds it until an owner or admin approves it.
Request body
cooldown_daysinteger | null · 30–365requiredDays no campaign calls a number again after someone talked with your agent on it; null turns the rule off.
cooldown_actionwait | skipWhat a campaign does with a number inside the period. Left out, it stays as it is.
Nothing changes yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).403forbiddenThe member who created the key can't change the workspace's settings (only owners and admins can), or has left the workspace.503service_unavailableThe setting isn't available while an update is being deployed; retry in a few minutes.Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X PUT https://www.nutalk.ai/v1/contact-rules \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"cooldown_days": 90,
"cooldown_action": "wait"
}'{
"success": true,
"data": {
"cooldown_days": 90,
"cooldown_action": "wait"
}
}/v1/contacts/:id/touchesRecord where a contact came from
Records a touch: the contact reached the business from an ad or a tagged link that NuTalk didn't see, such as your landing page's form or your CRM. Their later conversions take it as their first or last touch, and its click ids let the ad platforms match them. Part of Conversions: only while it is on for the workspace.
conversions:writeTakes an Idempotency-KeyOnly the listed keys are kept: anything else in click_ids, ad or utm is refused, so no personal data rides along. One touch per Idempotency-Key.
Path parameters
iduuidrequiredThe contact id.
Request body
occurred_atdatetimeWhen they arrived (now when left out): at most 365 days ago, never in the future.
click_idsobjectThe click ids, each up to 500 characters: ctwa_clid, fbclid, fbc, fbp, gclid, gbraid, wbraid, ttclid, ttp. One platform's per touch.
platformmeta | google | tiktokThe ad platform. Read from the click ids when they carry it; required for an ad without click ids.
adobjectWhat the platform said about the ad: id, adset_id, campaign_id, form_id, page_id, placement, lead_id, ref, source_type, url, headline.
utmobjectThe link's UTMs, each up to 200 characters: source, medium, campaign, term, content.
page_urlstring · up to 2,000The page they landed on (http or https). Its query and fragment are dropped.
Show 2 more fields
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).400validation_errorThe click ids are of two platforms, or don't match platform, or an ad without click ids has no platform.400validation_errorThe Idempotency-Key header is missing, or isn't 1 to 150 letters, digits and . _ : - (details.reason idempotency_key_required).404not_foundNo contact with this id in your workspace (ids of other workspaces answer the same).409conflictThe Idempotency-Key already recorded a touch with other details (details.reason idempotency_key_reused, details.fields, details.touch_id).403forbiddenConversions is off for the workspace (details.reason conversions_off): NuTalk switches it on per workspace during the beta.429rate_limitedThe workspace recorded 600 conversions and touches through the API in the last hour, or 60 in the last minute (on top of its general limit).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X POST https://www.nutalk.ai/v1/contacts/9595b646-ab97-4485-b1b8-e8b58dfcdd19/touches \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Idempotency-Key: $(uuidgen)" \
-H "Content-Type: application/json" \
-d '{
"occurred_at": "2026-10-24T09:03:44-06:00",
"click_ids": {
"gclid": "example-gclid"
},
"ad": {
"campaign_id": "21000000001"
},
"utm": {
"source": "google",
"medium": "cpc",
"campaign": "primera-consulta"
},
"page_url": "https://clinica.example.com/promo?email=redacted"
}'kind is ad (click ids or an ad), tagged (UTMs only) or direct.{
"success": true,
"data": {
"id": "8a4c1e6b-3d9f-4a5c-8e7b-2f1d9c8a6e43",
"contact_id": "9595b646-ab97-4485-b1b8-e8b58dfcdd19",
"occurred_at": "2026-10-24T15:03:44+00:00",
"recorded_at": "2026-10-24T15:03:45.120+00:00",
"channel": "api",
"platform": "google",
"kind": "ad",
"click_ids": {
"gclid": "example-gclid"
},
"ad": {
"campaign_id": "21000000001"
},
"utm": {
"source": "google",
"medium": "cpc",
"campaign": "primera-consulta"
},
"page_url": "https://clinica.example.com/promo"
}
}{
"success": true,
"data": {
"id": "8a4c1e6b-3d9f-4a5c-8e7b-2f1d9c8a6e43",
"contact_id": "9595b646-ab97-4485-b1b8-e8b58dfcdd19",
"occurred_at": "2026-10-24T15:03:44+00:00",
"recorded_at": "2026-10-24T15:03:45.120+00:00",
"channel": "api",
"platform": "google",
"kind": "ad",
"click_ids": {
"gclid": "example-gclid"
},
"ad": {
"campaign_id": "21000000001"
},
"utm": {
"source": "google",
"medium": "cpc",
"campaign": "primera-consulta"
},
"page_url": "https://clinica.example.com/promo"
}
}/v1/contact-fieldsList contact fields
Lists the workspace's contact fields in their order: the custom data each contact can hold (Settings › Contact fields).
contacts:readA field's key is made from its label when it is created and never changes: accents are spelled out and every other character becomes _ ("Interés" is interes, "Código postal" is codigo_postal). Labels that differ only by accents, case or punctuation name the same field.
A workspace has at most 200 active fields. Archived fields keep their values and can be restored.
Query parameters
include_archivedtrue | falsetrue also lists archived fields.
Errors
400validation_errorA query parameter is invalid (details.errors lists each one).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/contact-fields \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": [
{
"id": "5a7c9e1b-3d5f-4a7b-9c1d-3e5f7a9b1c2d",
"key": "interes",
"label": "Interés",
"type": "choice",
"options": [
"Casa",
"Departamento",
"Terreno"
],
"position": 0,
"variable": "{{contact.interes}}",
"archived_at": null,
"created_at": "2026-10-09T16:00:00.000000+00:00",
"updated_at": "2026-10-09T16:00:00.000000+00:00"
}
]
}/v1/contact-fieldsCreate a contact field
Adds a contact field. Its key comes from the label. A label whose key another field already has is that field (409).
contacts:writeA field's key is made from its label when it is created and never changes: accents are spelled out and every other character becomes _ ("Interés" is interes, "Código postal" is codigo_postal). Labels that differ only by accents, case or punctuation name the same field.
A workspace has at most 200 active fields. Archived fields keep their values and can be restored.
Request body
labelstring · up to 80requiredWhat people see, e.g. Interés.
typetext | number | date | choice | email | phone | urlWhat the values are (dates are written YYYY-MM-DD; a choice needs options). Default: text.
optionsstring[] · 0–100 itemsChoice fields only (required for them): the allowed values.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).409validation_errorA field with the same key exists (details.reason contact_field_exists, or contact_field_archived when archived: restore it with PATCH), the label names a contact detail such as Email (contact_field_reserved), or the workspace has 200 active fields (contact_fields_limit).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X POST https://www.nutalk.ai/v1/contact-fields \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"label": "Interés",
"type": "choice",
"options": [
"Casa",
"Departamento",
"Terreno"
]
}'{
"success": true,
"data": {
"id": "5a7c9e1b-3d5f-4a7b-9c1d-3e5f7a9b1c2d",
"key": "interes",
"label": "Interés",
"type": "choice",
"options": [
"Casa",
"Departamento",
"Terreno"
],
"position": 0,
"variable": "{{contact.interes}}",
"archived_at": null,
"created_at": "2026-10-09T16:00:00.000000+00:00",
"updated_at": "2026-10-09T16:00:00.000000+00:00"
}
}/v1/contact-fields/:idGet a contact field
Returns one contact field, by id or by key.
contacts:readPath parameters
idstringrequiredThe field's id or key.
Errors
404not_foundNo contact field with this id in your workspace (ids of other workspaces answer the same).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl https://www.nutalk.ai/v1/contact-fields/9595b646-ab97-4485-b1b8-e8b58dfcdd19 \ -H "Authorization: Bearer $NUTALK_API_KEY"
{
"success": true,
"data": {
"id": "5a7c9e1b-3d5f-4a7b-9c1d-3e5f7a9b1c2d",
"key": "interes",
"label": "Interés",
"type": "choice",
"options": [
"Casa",
"Departamento",
"Terreno"
],
"position": 0,
"variable": "{{contact.interes}}",
"archived_at": null,
"created_at": "2026-10-09T16:00:00.000000+00:00",
"updated_at": "2026-10-09T16:00:00.000000+00:00"
}
}/v1/contact-fields/:idUpdate a contact field
Renames (the key stays), retypes, reorders, archives or restores a field, or changes a choice field's options. A new type must fit every value contacts already have (they are rewritten that type's way; past 10,000 values a field only changes to text), and a choice field keeps every option in use.
contacts:writeCan wait for approvalPath parameters
idstringrequiredThe field's id or key.
Request body
labelstring · up to 80New label.
typetext | number | date | choice | email | phone | urlNew type.
optionsstring[] · 0–100 itemsChoice fields: the allowed values (they replace the current list).
positioninteger · at least 0Place in the list (0 first).
archivedbooleantrue archives the field (values kept); false restores it.
Show 1 more field
Nothing changes yet: the call answers 202 with data.change_request, and runs once an owner or admin approves it in Settings → API keys. Follow it with GET /v1/change-requests/:id.
Errors
400validation_errorThe body is not JSON, or a field is missing or invalid (details.errors lists each field).404not_foundNo contact field with this id in your workspace (ids of other workspaces answer the same).409validation_errorSome values don't fit the new type or options (details.reason contact_field_values_incompatible, with count and examples), the field has more than 10,000 values (contact_field_too_many_values), or restoring it would pass 200 active fields (contact_fields_limit).Plus the errors every request can return (401, 403, 429, 500): Errors.
curl -X PATCH https://www.nutalk.ai/v1/contact-fields/9595b646-ab97-4485-b1b8-e8b58dfcdd19 \
-H "Authorization: Bearer $NUTALK_API_KEY" \
-H "Content-Type: application/json" \
-d '{
"label": "Tipo de propiedad"
}'{
"success": true,
"data": {
"id": "5a7c9e1b-3d5f-4a7b-9c1d-3e5f7a9b1c2d",
"key": "interes",
"label": "Tipo de propiedad",
"type": "choice",
"options": [
"Casa",
"Departamento",
"Terreno"
],
"position": 0,
"variable": "{{contact.interes}}",
"archived_at": null,
"created_at": "2026-10-09T16:00:00.000000+00:00",
"updated_at": "2026-10-09T16:00:00.000000+00:00"
}
}Contact sources
source records how the contact first arrived. Contacts created with POST /v1/contacts have api; contacts created by a campaign enrollment have campaign. Contacts created by calls, WhatsApp, imports and CRM integrations carry the label of that path.
Campaign call rules
/v1/contact-rules holds the rule every campaign of the workspace follows: after someone talks with your agent on a call, no campaign calls that number again for a number of days. Reading it needs campaigns:read; changing it needs campaigns:write and a key created by an owner or admin, because the change is made as that person.