> For the complete documentation index, see [llms.txt](https://docs.360dialog.com/docs/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.360dialog.com/docs/inbox/inbox-api/api-ref/contacts.md). # Contacts WhatsApp Users' contact details The Inbox does not keep or manage your contacts. Instead, you can connect your existing contact books or databases, using Contact Providers. When one or more Contact Providers are successfully connected to your inbox, you will be able to request related contact data from endpoints described here. In the `/contacts/` section, there are also WhatsApp Business API provided endpoints like: verifying the Contact, blocking WhatsApp number, reporting WhatsApp user to Meta. ## GET /api/v1/contacts/ > List contacts. Use \`search\` to filter by name or WhatsApp ID. ```json {"openapi":"3.0.3","info":{"title":"360dialog Inbox API","version":"1.28.0"},"tags":[{"name":"Contacts","description":"WhatsApp Users' contact details\n\nThe Inbox does not keep or manage your contacts. Instead, you can connect your existing contact books or databases, using Contact Providers. \n\nWhen one or more Contact Providers are successfully connected to your inbox, you will be able to request related contact data from endpoints described here. \n\nIn the `/contacts/` section, there are also WhatsApp Business API provided endpoints like: verifying the Contact, blocking WhatsApp number, reporting WhatsApp user to Meta."}],"servers":[{"url":"https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/","description":"Your Inbox address. Open the Inbox from the 360dialog Hub to see it.","variables":{"YOUR_STACK_NAME":{"default":"your-stack","description":"The first part of your Inbox address"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"A user token, sent as `Token `. Create a user in the admin panel (group App integration) and get its token from `POST /api/v1/auth/token/`. The channel API key (`D360-Api-Key`) is not supported."}},"schemas":{"PaginatedContactModelList":{"type":"object","required":["count","results"],"properties":{"count":{"type":"integer"},"next":{"type":"string","nullable":true,"format":"uri"},"previous":{"type":"string","nullable":true,"format":"uri"},"results":{"type":"array","items":{"$ref":"#/components/schemas/ContactModel"}}}},"ContactModel":{"type":"object","description":"Serializes the Contact model similar to how Contact Providers serialized contacts in the past.","properties":{"name":{"type":"string","readOnly":true,"description":"Name of the person"},"initials":{"type":"string","description":"Contact name initials used for display when avatar image is missing"},"phone_numbers":{"type":"array","items":{"$ref":"#/components/schemas/ContactModelPhoneNumber"},"description":"At least one phone number (that should be equal to `wa_id`). "},"email_addresses":{"type":"array","items":{},"description":"Deprecated, always empty"},"urls":{"type":"array","items":{},"description":"Deprecated, always empty"},"contact_provider":{"description":"Deprecated, always a dummy value"}},"required":["contact_provider","email_addresses","initials","name","phone_numbers","urls"]},"ContactModelPhoneNumber":{"type":"object","properties":{"phone_number":{"type":"string","description":"Person's phone number. Should be equal to `wa_id`."}},"required":["phone_number"]}}},"paths":{"/api/v1/contacts/":{"get":{"operationId":"listContacts","description":"List contacts. Use `search` to filter by name or WhatsApp ID.","parameters":[{"in":"query","name":"limit","schema":{"type":"integer"},"description":"Number of results to return per page."},{"name":"offset","required":false,"in":"query","description":"The initial index from which to return the results.","schema":{"type":"integer"}},{"in":"query","name":"search","schema":{"type":"string"},"description":"Filter Contacts by string query.\n\n\nSearching is expensive, so when implementing this functionality on the frontend,\nmake sure the user really finished typing the search query before calling this endpoint."}],"tags":["Contacts"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/PaginatedContactModelList"}}},"description":""}}}}}} ``` ## GET /api/v1/contacts/{wa\_id}/ > Retrieves Contact details. You should try to use this endpoint as little as possible, for example:\ > \ > \* when a detailed view of one Person is displayed ```json {"openapi":"3.0.3","info":{"title":"360dialog Inbox API","version":"1.28.0"},"tags":[{"name":"Contacts","description":"WhatsApp Users' contact details\n\nThe Inbox does not keep or manage your contacts. Instead, you can connect your existing contact books or databases, using Contact Providers. \n\nWhen one or more Contact Providers are successfully connected to your inbox, you will be able to request related contact data from endpoints described here. \n\nIn the `/contacts/` section, there are also WhatsApp Business API provided endpoints like: verifying the Contact, blocking WhatsApp number, reporting WhatsApp user to Meta."}],"servers":[{"url":"https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/","description":"Your Inbox address. Open the Inbox from the 360dialog Hub to see it.","variables":{"YOUR_STACK_NAME":{"default":"your-stack","description":"The first part of your Inbox address"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"A user token, sent as `Token `. Create a user in the admin panel (group App integration) and get its token from `POST /api/v1/auth/token/`. The channel API key (`D360-Api-Key`) is not supported."}},"schemas":{"Contact":{"type":"object","properties":{"person":{"allOf":[{"$ref":"#/components/schemas/Person"}],"description":"Person related to this contact. Can be `null` if this person wasn't yet contacted via your inbox or related Person data was removed from your inbox."},"contact_provider_results":{"type":"array","items":{"$ref":"#/components/schemas/ContactProviderResult"},"description":"Deprecated, always empty"}},"required":["contact_provider_results"]},"Person":{"type":"object","properties":{"wa_id":{"type":"string","title":"WhatsApp id","description":"WhatsApp ID — either a phone number in canonical form (e.g. 48123123123) or a Business-Scoped User ID (e.g. US.13491208655302741918) for users who have hidden their phone number.","pattern":"^([A-Z]{2}\\.(ENT\\.)?[a-zA-Z0-9]+|[0-9]+)$","maxLength":200},"bsuid":{"type":"string","readOnly":true,"nullable":true,"title":"Business-Scoped User ID","description":"Business-Scoped User ID for this contact. Populated from the webhook's `user_id` field. Stable across phone number changes for the same user-portfolio pair, so this is the most reliable long-term identifier."},"phone_number":{"type":"string","readOnly":true,"nullable":true,"description":"Phone number when known. Equals `wa_id` for phone-primary contacts. For BSUID-primary contacts (where `wa_id` is a BSUID), populated when WhatsApp shares the phone number — e.g. recent interaction within the last 30 days, or via Contact Book."},"waba_payload":{"$ref":"#/components/schemas/WabaPayloadContact"},"initials":{"type":"string","description":"Contact user name initials used for display when avatar image is missing"},"last_message_timestamp":{"type":"number","format":"double","nullable":true,"description":"[POSIX timestamp](https://en.wikipedia.org/wiki/Unix_time) of last message that was sent by this contact. It is the floor of the customer care messaging window: a non-template message can always be delivered for some time after the customer last wrote to your business, and Meta may keep the window open for longer — see `messaging_window_expires_at`. Read more at WhatsApp Business API docs [Messages Cut-off Control](https://developers.facebook.com/docs/whatsapp/api/messages#cut-off-control)."},"messaging_window_expires_at":{"type":"number","format":"double","readOnly":true,"description":"[POSIX timestamp](https://en.wikipedia.org/wiki/Unix_time) after which a non-template message to this contact is rejected with HTTP 453. Derived from what Meta reported for this conversation, the customer's last message, and — for click-to-WhatsApp chats we have not replied to yet — the ad referral. Never assume a fixed duration: read this value."},"messaging_window_origin":{"type":"string","readOnly":true,"nullable":true,"description":"`conversation.origin.type` reported by Meta alongside `messaging_window_expires_at` — what opened the conversation (e.g. `service`, `marketing`, `utility`, `authentication`, or `referral_conversion` for a click-to-WhatsApp ad)."},"resolved":{"type":"boolean","description":"Whether this chat is considered resolved by the assigned agent. Can automatically be set to false if contact keeps sending messages."}},"required":["bsuid","initials","messaging_window_expires_at","messaging_window_origin","phone_number","wa_id","waba_payload"]},"WabaPayloadContact":{"type":"object","properties":{"profile":{"$ref":"#/components/schemas/WabaPayloadProfile"},"wa_id":{"type":"string"}},"required":["profile","wa_id"]},"WabaPayloadProfile":{"type":"object","properties":{"name":{"type":"string"}},"required":["name"]},"ContactProviderResult":{"type":"object","properties":{"name":{"type":"string","description":"Name of the person as returned by related Contact Provider"},"initials":{"type":"string","description":"Contact name initials used for display when avatar image is missing"},"avatar":{"type":"string","format":"uri","description":"URL leading to contact miniature avatar or miniature photo, if available"},"large_avatar":{"type":"string","format":"uri","description":"URL leading to contact large avatar or large photo, if available"},"phone_numbers":{"type":"array","items":{"$ref":"#/components/schemas/ContactProviderPhoneNumber"},"description":"At least one phone number (that should be equal to `wa_id`). "},"email_addresses":{"type":"array","items":{"$ref":"#/components/schemas/EmailAddress"},"description":"E-mail addresses of this Person, if provided."},"urls":{"type":"array","items":{"$ref":"#/components/schemas/Url"},"description":"URLs of this Person, if provided."},"contact_provider":{"allOf":[{"$ref":"#/components/schemas/ContactProvider"}],"description":"Contact Provider that provided this object"}},"required":["contact_provider","email_addresses","initials","name","phone_numbers","urls"]},"ContactProviderPhoneNumber":{"type":"object","properties":{"phone_number":{"type":"string","description":"Person's phone number. Should be equal to `wa_id`."},"description":{"type":"string","description":"Phone number description, like \"Work\", \"Home\" or \"Office\", if provided. (Can be any string value)"}},"required":["phone_number"]},"EmailAddress":{"type":"object","properties":{"email_address":{"type":"string","format":"email"},"description":{"type":"string","description":"E-mail address description, like \"Work\", \"Home\" or \"Office\", if provided. (Can be any string value)"}},"required":["email_address"]},"Url":{"type":"object","properties":{"url":{"type":"string","format":"uri"},"description":{"type":"string","description":"URL description, like \"Homepage\", \"Social\" or \"Shop\", if provided. (Can be any string value)"}},"required":["url"]},"ContactProvider":{"type":"object","properties":{"type":{"allOf":[{"$ref":"#/components/schemas/ContactProviderTypeEnum"}],"description":"Contact Provider type, if known.\n\nAllows you to identify contact provider type programmatically, so that you are able to display it accordingly or provide a valid linking to external app or system.\n\nIf data was returned by a Contact Provider type known to us (for example a Inbox-supported plugin), then this field will allow you to identify the exact source of contact data. In other case (for example external plugin), `\"other\"` is returned.\n\n* `google` - google\n* `hubspot` - hubspot\n* `other` - other"},"name":{"type":"string","description":"Contact Provider human-readable name, if known.\n\nAllows you to identify contact source visually. Should be displayed on the frontend."},"id":{"type":"string","format":"uuid","description":"Unique identifier of this Contact Provider.\n\nAllows you to distinguish different integrations of the same Contact Provider type."}},"required":["id","type"]},"ContactProviderTypeEnum":{"enum":["google","hubspot","other"],"type":"string","description":"* `google` - google\n* `hubspot` - hubspot\n* `other` - other"}}},"paths":{"/api/v1/contacts/{wa_id}/":{"get":{"operationId":"contactDetails","description":"Retrieves Contact details. You should try to use this endpoint as little as possible, for example:\n\n* when a detailed view of one Person is displayed","parameters":[{"in":"path","name":"wa_id","schema":{"type":"string","pattern":"^[^/]+$"},"required":true}],"tags":["Contacts"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Contact"}}},"description":""}}}}}} ``` ## POST /api/v1/contacts/{wa\_id}/block/ > Block contacts due to spam and abuse of WhatsApp. To block a contact they had to have sent you a message in the last 24 hours. ```json {"openapi":"3.0.3","info":{"title":"360dialog Inbox API","version":"1.28.0"},"tags":[{"name":"Contacts","description":"WhatsApp Users' contact details\n\nThe Inbox does not keep or manage your contacts. Instead, you can connect your existing contact books or databases, using Contact Providers. \n\nWhen one or more Contact Providers are successfully connected to your inbox, you will be able to request related contact data from endpoints described here. \n\nIn the `/contacts/` section, there are also WhatsApp Business API provided endpoints like: verifying the Contact, blocking WhatsApp number, reporting WhatsApp user to Meta."}],"servers":[{"url":"https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/","description":"Your Inbox address. Open the Inbox from the 360dialog Hub to see it.","variables":{"YOUR_STACK_NAME":{"default":"your-stack","description":"The first part of your Inbox address"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"A user token, sent as `Token `. Create a user in the admin panel (group App integration) and get its token from `POST /api/v1/auth/token/`. The channel API key (`D360-Api-Key`) is not supported."}},"schemas":{"ContactBlock":{"type":"object","properties":{"reason":{"type":"string","default":"","description":"Optional string with max length 60. Free form block reason. Will be used when another business account is being blocked. ","maxLength":60}}},"ContactsBlockOrReport400Response":{"type":"object","properties":{"meta":{},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ContactsBlockOrReport400ErrorResponse"}}},"required":["errors","meta"]},"ContactsBlockOrReport400ErrorResponse":{"type":"object","properties":{"code":{"type":"integer"},"title":{"type":"string"},"details":{"type":"string"}},"required":["code","details","title"]}}},"paths":{"/api/v1/contacts/{wa_id}/block/":{"post":{"operationId":"blockContact","description":"Block contacts due to spam and abuse of WhatsApp. To block a contact they had to have sent you a message in the last 24 hours.","parameters":[{"in":"path","name":"wa_id","schema":{"type":"string","pattern":"^[^/]+$"},"required":true}],"tags":["Contacts"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactBlock"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/ContactBlock"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ContactBlock"}}}},"responses":{"200":{"description":"No response body"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactsBlockOrReport400Response"}}},"description":"User error. Please check your request and API response."}}}}}} ``` ## POST /api/v1/contacts/{wa\_id}/report/ > Report contacts due to spam and abuse of WhatsApp. Before reporting a contact, they had to have sent you a message in the last 24 hours. ```json {"openapi":"3.0.3","info":{"title":"360dialog Inbox API","version":"1.28.0"},"tags":[{"name":"Contacts","description":"WhatsApp Users' contact details\n\nThe Inbox does not keep or manage your contacts. Instead, you can connect your existing contact books or databases, using Contact Providers. \n\nWhen one or more Contact Providers are successfully connected to your inbox, you will be able to request related contact data from endpoints described here. \n\nIn the `/contacts/` section, there are also WhatsApp Business API provided endpoints like: verifying the Contact, blocking WhatsApp number, reporting WhatsApp user to Meta."}],"servers":[{"url":"https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/","description":"Your Inbox address. Open the Inbox from the 360dialog Hub to see it.","variables":{"YOUR_STACK_NAME":{"default":"your-stack","description":"The first part of your Inbox address"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"A user token, sent as `Token `. Create a user in the admin panel (group App integration) and get its token from `POST /api/v1/auth/token/`. The channel API key (`D360-Api-Key`) is not supported."}},"schemas":{"ContactReport":{"type":"object","properties":{"reason":{"type":"string","default":"","description":"Optional string with max length 60. Free form block reason. Will be used when another business account is being blocked. ","maxLength":60},"block":{"type":"boolean","default":false,"description":"True or false optional boolean with default of false"},"message_id":{"type":"string","description":"Optional reported message id"}}},"ContactsBlockOrReport400Response":{"type":"object","properties":{"meta":{},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ContactsBlockOrReport400ErrorResponse"}}},"required":["errors","meta"]},"ContactsBlockOrReport400ErrorResponse":{"type":"object","properties":{"code":{"type":"integer"},"title":{"type":"string"},"details":{"type":"string"}},"required":["code","details","title"]}}},"paths":{"/api/v1/contacts/{wa_id}/report/":{"post":{"operationId":"reportContact","description":"Report contacts due to spam and abuse of WhatsApp. Before reporting a contact, they had to have sent you a message in the last 24 hours.","parameters":[{"in":"path","name":"wa_id","schema":{"type":"string","pattern":"^[^/]+$"},"required":true}],"tags":["Contacts"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactReport"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/ContactReport"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ContactReport"}}}},"responses":{"200":{"description":"No response body"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactsBlockOrReport400Response"}}},"description":""}}}}}} ``` ## POST /api/v1/contacts/{wa\_id}/unblock/ > Unblock contacts which were blocked or reported to block previously. ```json {"openapi":"3.0.3","info":{"title":"360dialog Inbox API","version":"1.28.0"},"tags":[{"name":"Contacts","description":"WhatsApp Users' contact details\n\nThe Inbox does not keep or manage your contacts. Instead, you can connect your existing contact books or databases, using Contact Providers. \n\nWhen one or more Contact Providers are successfully connected to your inbox, you will be able to request related contact data from endpoints described here. \n\nIn the `/contacts/` section, there are also WhatsApp Business API provided endpoints like: verifying the Contact, blocking WhatsApp number, reporting WhatsApp user to Meta."}],"servers":[{"url":"https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/","description":"Your Inbox address. Open the Inbox from the 360dialog Hub to see it.","variables":{"YOUR_STACK_NAME":{"default":"your-stack","description":"The first part of your Inbox address"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"A user token, sent as `Token `. Create a user in the admin panel (group App integration) and get its token from `POST /api/v1/auth/token/`. The channel API key (`D360-Api-Key`) is not supported."}},"schemas":{"ContactBlock":{"type":"object","properties":{"reason":{"type":"string","default":"","description":"Optional string with max length 60. Free form block reason. Will be used when another business account is being blocked. ","maxLength":60}}},"ContactsBlockOrReport400Response":{"type":"object","properties":{"meta":{},"errors":{"type":"array","items":{"$ref":"#/components/schemas/ContactsBlockOrReport400ErrorResponse"}}},"required":["errors","meta"]},"ContactsBlockOrReport400ErrorResponse":{"type":"object","properties":{"code":{"type":"integer"},"title":{"type":"string"},"details":{"type":"string"}},"required":["code","details","title"]}}},"paths":{"/api/v1/contacts/{wa_id}/unblock/":{"post":{"operationId":"unblockContact","description":"Unblock contacts which were blocked or reported to block previously.","parameters":[{"in":"path","name":"wa_id","schema":{"type":"string","pattern":"^[^/]+$"},"required":true}],"tags":["Contacts"],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactBlock"}},"application/x-www-form-urlencoded":{"schema":{"$ref":"#/components/schemas/ContactBlock"}},"multipart/form-data":{"schema":{"$ref":"#/components/schemas/ContactBlock"}}}},"responses":{"200":{"description":"No response body"},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactsBlockOrReport400Response"}}},"description":"User error. Please check your request and API response."}}}}}} ``` ## GET /api/v1/contacts/blocklist/ > View blocked contacts list. These phone numbers are blocked by the user due to spam and abuse of WhatsApp. ```json {"openapi":"3.0.3","info":{"title":"360dialog Inbox API","version":"1.28.0"},"tags":[{"name":"Contacts","description":"WhatsApp Users' contact details\n\nThe Inbox does not keep or manage your contacts. Instead, you can connect your existing contact books or databases, using Contact Providers. \n\nWhen one or more Contact Providers are successfully connected to your inbox, you will be able to request related contact data from endpoints described here. \n\nIn the `/contacts/` section, there are also WhatsApp Business API provided endpoints like: verifying the Contact, blocking WhatsApp number, reporting WhatsApp user to Meta."}],"servers":[{"url":"https://{YOUR_STACK_NAME}.inbox.getchat.360dialog.io/","description":"Your Inbox address. Open the Inbox from the 360dialog Hub to see it.","variables":{"YOUR_STACK_NAME":{"default":"your-stack","description":"The first part of your Inbox address"}}}],"security":[{"tokenAuth":[]}],"components":{"securitySchemes":{"tokenAuth":{"type":"apiKey","in":"header","name":"Authorization","description":"A user token, sent as `Token `. Create a user in the admin panel (group App integration) and get its token from `POST /api/v1/auth/token/`. The channel API key (`D360-Api-Key`) is not supported."}},"schemas":{"ContactsBlockListResponse":{"type":"object","properties":{"contacts":{"type":"array","items":{"$ref":"#/components/schemas/ContactsBlockListWabaContactsResponse"}},"pagination":{"$ref":"#/components/schemas/ContactsBlockListWabaPaginationResponse"}},"required":["contacts","pagination"]},"ContactsBlockListWabaContactsResponse":{"type":"object","properties":{"wa_id":{"type":"string"}},"required":["wa_id"]},"ContactsBlockListWabaPaginationResponse":{"type":"object","properties":{"limit":{"type":"integer"},"offset":{"type":"integer"},"total":{"type":"integer"}},"required":["limit","offset","total"]}}},"paths":{"/api/v1/contacts/blocklist/":{"get":{"operationId":"listBlockedContacts","description":"View blocked contacts list. These phone numbers are blocked by the user due to spam and abuse of WhatsApp.","parameters":[{"in":"query","name":"limit","schema":{"type":"integer"},"description":"Number of results to return per page."},{"in":"query","name":"offset","schema":{"type":"integer"},"description":"The initial index from which to return the results."}],"tags":["Contacts"],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ContactsBlockListResponse"}}},"description":""}}}}}} ``` --- # Agent Instructions This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com. ## Querying This Documentation If you need additional information that is not directly available in this page, you can query the documentation by asking a question. Perform an HTTP GET request on the following URL with the `ask` and `goal` query parameters: ``` GET https://docs.360dialog.com/docs/inbox/inbox-api/api-ref/contacts.md?ask=&goal= ``` `ask` is the immediate question: it should be specific, self-contained, and written in natural language. `goal` is what the user is ultimately trying to achieve, the reason they need the answer. Sharing it helps GitBook give you a better, more relevant answer. A goal is most helpful when it describes the outcome the user wants rather than restating the question. For example, with `ask=how do I create an API token`, a goal like `automate deployments from our CI pipeline` lets GitBook tailor the answer to that use case. The response will contain a direct answer to the question and relevant excerpts and sources from the documentation. Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.