Find or create a contact
Build a request to copy
This page never sends a request. Fill in the fields, then copy the request and run it from your server.
curl -X POST 'https://api.whatsable.app/v1/contacts' \
-H 'Content-Type: application/json' \
-d '{
"phone": "+5491155550000",
"name": "Ana Pérez"
}'bearerAuthAuthorizationBearer <nfy_live_<32 characters>>An API key from Settings > API keys, sent as Authorization: Bearer <key>.
Idempotency-Key?stringAny string up to 255 characters. A repeat with the same key and body answers the stored response; with another body, 409 idempotency_key_reused.
length <= 255application/json- body
Find a contact by phone or wa_user_id, or create it. An existing contact answers 200, a new one 201.
phone?stringA phone number in E.164. The +, spaces and dashes may be omitted; the canonical +digits form is what is stored and returned.
wa_user_id?stringA Business-Scoped User ID: a country code, a period, then letters and digits.
^[A-Z]{2}\.[A-Za-z0-9]{8,128}$name?stringSet on a contact this call creates. An existing contact keeps its name.
1 <= length <= 200A contact with this identity already existed.
application/json- response
A person the organization talks to on WhatsApp.
object*stringid*string1 <= length <= 64phone*|Null when WhatsApp withheld the number and only a user id is known.
wa_user_id*|The Business-Scoped User ID, when WhatsApp gave one.
username*|The WhatsApp username, without @.
name*string|nullnote*|The contact's note, as the inbox shows it.
automation_note*|A note kept for automations, separate from note.
labels*array<>conversations*array<>One per number the person has talked to, among the numbers this key may use.
follow_ups*stringThe inbox's Follow up switch. off: the AI never follows up with this person, on any number, until it is switched back on. on does not mean a follow-up is coming: that also depends on the bot's follow-up settings and the conversation's AI status.
"on""off"created_at*stringdate-timeupdated_at*stringdate-timecurl -X POST 'https://api.whatsable.app/v1/contacts' \ -H 'Content-Type: application/json' \ -d '{ "phone": "+5491155550000", "name": "Ana Pérez"}'{ "object": "contact", "id": "cm2v8k1a00001qz8h8x9y0z1a", "phone": "+5491155550000", "wa_user_id": null, "username": null, "name": "Ana Pérez", "note": null, "automation_note": null, "labels": [ { "id": "cm2v8l1a00001qz8h2b3c4d5e", "name": "VIP" } ], "conversations": [ { "id": "cm2v8c1a00001qz8h4t5u6v7w", "number_id": "cm2v8a1b20002qz8h9i0j1k2l" } ], "follow_ups": "on", "created_at": "2026-09-01T12:00:00Z", "updated_at": "2026-10-20T19:51:21Z"}