Get a contact
One contact, with their tags, custom fields and whether they are on your stop list.
/v1/contacts/{id}
One contact, with their tags, custom fields and whether they are on your stop list.
Needs a key with the contacts:read scope.
Path parameters
idstringrequiredThe contact’s id.
Starts with
ct_.
Example
/v1/contacts/ct_1Hq2LxW9cVbN3mKpRtYs0acurl "https://getdogbot.com/api/v1/contacts/ct_1Hq2LxW9cVbN3mKpRtYs0a" \
-H "Authorization: Bearer $DOGBOT_API_KEY"Response
200: The contact.
idstringrequiredA ct_ id.
Starts with
ct_.object"contact"requiredhandlestringrequiredA phone number in E.164 (
+15555550123) or an email address an Apple ID uses (iMessage only).kindstringrequiredphoneoremail.One of
phone,email.first_namestring or nullrequiredlast_namestring or nullrequiredcompanystring or nullrequiredstatestring or nullrequiredThe two-letter code of the US state they live in, or DC or PR, when you know it. Texting hours follow it, and without it they follow the area code.
One of
AL,AK,AZ,AR,CA,CO,CT,DE,FL,GA,HI,ID,IL,IN,IA,KS,KY,LA,ME,MD,MA,MI,MN,MS,MO,MT,NE,NV,NH,NJ,NM,NY,NC,ND,OH,OK,OR,PA,RI,SC,SD,TN,TX,UT,VT,VA,WA,WV,WI,WY,DC,PR.tagsarray of stringsrequiredThe contact’s tags.
custom_fieldsmap of stringrequiredYour own fields, for templates.
stoppedbooleanrequiredTrue when the person is on your stop list. Texts to them are canceled.
stopped_attimestamp or nullrequiredWhen they were put on the stop list.
stop_sourcestring or nullrequiredHow:
reply(they texted a stop word),dashboard,api,importoradmin.One of
reply,dashboard,api,import,admin.last_servicestring or nullrequiredThe service of the newest text with them.
One of
imessage,sms.first_message_attimestamp or nullrequiredThe first text either way. Null for somebody you have never texted with, who counts as a new person.
last_message_attimestamp or nullrequiredThe newest text either way.
created_viastringrequiredWhat first added them.
One of
message,inbound,import,api,dashboard,widget,hook,mcp,assistant.created_attimestamprequiredWhen the contact was added.
{
"id": "ct_1Hq2LxW9cVbN3mKpRtYs0a",
"object": "contact",
"handle": "+15555550123",
"kind": "phone",
"first_name": "Maria",
"last_name": "Alvarez",
"company": null,
"state": "FL",
"tags": [
"buyer"
],
"custom_fields": {
"showing": "412 Oak St"
},
"stopped": false,
"stopped_at": null,
"stop_source": null,
"last_service": "imessage",
"first_message_at": "2026-11-02T15:20:00.000Z",
"last_message_at": "2026-11-13T19:41:00.000Z",
"created_via": "message",
"created_at": "2026-11-02T15:20:00.000Z"
}Errors
Every refusal has the same envelope and a page of its own. These are the ones this operation can give.
| Code | Status | What it means |
|---|---|---|
| 401 | The request carried no key, or a key DogBot doesn’t know: mistyped, revoked, or a test key sent to the live API. | |
| 403 | The key doesn’t carry the scope the endpoint needs. Each endpoint’s reference names its scope. | |
| 429 | Too many requests. A key may make 120 requests a minute. The RateLimit header says how many are left, and Retry-After how long to wait. | |
| 500 | Something went wrong on DogBot’s side. It was reported. Send the request again; with an Idempotency-Key that is always safe. | |
| 404 | There is no such thing on this account. Ids are prefixed by kind, so a message id starts with msg_. |
Try it
Call this operation from the page with your own key. The key stays in this tab and is forgotten when you leave.