Authentication
Include your project API password in every request header:Method 1 — Fetch by Mobile Number
Use this method when you know the contact’s phone number but not their Convo contact ID.Endpoint
Path Parameters
string
required
Your Convo project ID.
Query Parameters
string
required
Must be set to
FetchContact to look up a contact by phone number.string
required
The contact’s phone number including country code. Do not include a leading
+ sign. Example: 917089379345.Example Request
Method 2 — Fetch by Contact ID
Use this method when you already have the Convo contact ID (returned by Create Contact or a previous fetch).Endpoint
Path Parameters
string
required
Your Convo project ID.
string
required
The Convo contact ID (e.g.,
64f3a1e0c8e4d500123abc00).Example Request
Response
Both methods return the same contact object on success. 200 OKstring
The Convo-assigned unique ID for this contact.
string
The Convo project this contact belongs to.
string
The contact’s WhatsApp phone number (with country code, no
+).string
The contact’s display name.
string
The numeric country dialing code (e.g.,
"91" for India).boolean
true if the phone number is registered and active on WhatsApp.boolean
true if the conversation with this contact is marked as closed in the Convo inbox.boolean
true if a human agent is currently handling this contact’s conversation.boolean
true if the contact has an active pending request awaiting a human agent response.number
Unix timestamp in milliseconds of the contact’s most recent activity.
array
List of tag strings applied to this contact from the Convo dashboard or API.
object
Key-value map of custom attributes stored for this contact. You can set and update these via Update Contact.
object
Object containing
id and added_at for the contact’s first inbound message. null if no messages have been received.number
Unix timestamp in milliseconds when this contact was first created.