Work with this as data
Every API here is available over the APIs.io API and to AI agents over MCP.
MCP server
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
Tools for apis
7 MCP tools reach this
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.
Call it yourself
curl for this page
This API
curl "https://apis.io/api/v1/apis/chatwoot-contacts-api"
All apis
curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Get an API key
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
OpenAPI Specification
openapi: 3.2.0
info:
title: Chatwoot Contacts API
termsOfService: https://www.chatwoot.com/terms-of-service/
version: '1.0'
description: 'Operations tagged Contacts across 2 of this provider''s published API definitions: chatwoot-application-api-openapi.yml, chatwoot-openapi.yml. Each path carries the servers of the definition it was published in.'
servers:
- url: https://app.chatwoot.com/
- url: https://app.chatwoot.com
description: Chatwoot Cloud. For self-hosted installations, substitute your own host.
tags:
- name: Contacts
description: Contact management APIs
paths:
/api/v1/accounts/{account_id}/contacts:
get:
tags:
- Contacts
operationId: contactList
description: Listing all the resolved contacts with pagination (Page size = 15). Resolved contacts are the ones with a value for identifier, email or phone number
summary: List Contacts
security:
- userApiKey: []
parameters:
- $ref: '#/components/parameters/account_id'
- $ref: '#/components/parameters/contact_sort_param'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/contacts_list_response'
'400':
description: Bad Request Error
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
post:
tags:
- Contacts
operationId: contactCreate
description: Create a new Contact
summary: Create Contact
security:
- userApiKey: []
parameters:
- $ref: '#/components/parameters/account_id'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/contact_create_payload'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/extended_contact'
'400':
description: Bad Request Error
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
parameters:
- $ref: '#/components/parameters/AccountId'
servers:
- url: https://app.chatwoot.com/
/api/v1/accounts/{account_id}/contacts/{id}:
parameters:
- $ref: '#/components/parameters/account_id'
- name: id
in: path
required: true
schema:
type: number
description: ID of the contact
get:
tags:
- Contacts
operationId: contactDetails
summary: Show Contact
security:
- userApiKey: []
description: Get a contact belonging to the account using ID
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/contact_show_response'
'404':
description: Contact not found
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'403':
description: Access denied
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
put:
tags:
- Contacts
operationId: contactUpdate
summary: Update Contact
security:
- userApiKey: []
description: Update a contact belonging to the account using ID
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/contact_update_payload'
responses:
'204':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/contact_base'
'404':
description: Contact not found
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'403':
description: Access denied
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
delete:
tags:
- Contacts
operationId: contactDelete
summary: Delete Contact
security:
- userApiKey: []
description: Delete a contact belonging to the account using ID
responses:
'200':
description: Success
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'404':
description: Contact not found
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
servers:
- url: https://app.chatwoot.com/
/api/v1/accounts/{account_id}/contacts/{id}/conversations:
parameters:
- $ref: '#/components/parameters/account_id'
- name: id
in: path
required: true
schema:
type: number
description: ID of the contact
get:
tags:
- Contacts
operationId: contactConversations
summary: Contact Conversations
description: Get conversations associated with that contact
parameters:
- name: id
in: path
required: true
schema:
type: number
description: ID of the contact
security:
- userApiKey: []
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/contact_conversations_response'
'404':
description: Contact not found
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'403':
description: Access denied
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
servers:
- url: https://app.chatwoot.com/
/api/v1/accounts/{account_id}/contacts/search:
get:
tags:
- Contacts
operationId: contactSearch
description: Search the resolved contacts using a search key, currently supports email search (Page size = 15). Resolved contacts are the ones with a value for identifier, email or phone number
summary: Search Contacts
security:
- userApiKey: []
parameters:
- $ref: '#/components/parameters/account_id'
- name: q
in: query
schema:
type: string
description: Search using contact `name`, `identifier`, `email` or `phone number`
- $ref: '#/components/parameters/contact_sort_param'
- $ref: '#/components/parameters/page'
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/contacts_list_response'
'401':
description: Authentication error
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
parameters:
- $ref: '#/components/parameters/AccountId'
servers:
- url: https://app.chatwoot.com/
/api/v1/accounts/{account_id}/contacts/filter:
post:
tags:
- Contacts
operationId: contactFilter
description: Filter contacts with custom filter options and pagination
summary: Contact Filter
security:
- userApiKey: []
parameters:
- $ref: '#/components/parameters/account_id'
- name: page
in: query
schema:
type: number
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
payload:
type: array
items:
type: object
properties:
attribute_key:
type: string
description: filter attribute name
filter_operator:
type: string
description: filter operator name
enum:
- equal_to
- not_equal_to
- contains
- does_not_contain
values:
type: array
items:
type: string
description: array of the attribute values to filter
query_operator:
type: string
description: query operator name
enum:
- AND
- OR
example:
- attribute_key: name
filter_operator: equal_to
values:
- en
query_operator: AND
- attribute_key: country_code
filter_operator: equal_to
values:
- us
query_operator: null
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/contacts_list_response'
'400':
description: Bad Request Error
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
parameters:
- $ref: '#/components/parameters/AccountId'
servers:
- url: https://app.chatwoot.com/
/api/v1/accounts/{account_id}/contacts/{id}/contact_inboxes:
post:
tags:
- Contacts
operationId: contactInboxCreation
description: Create a contact inbox record for an inbox
summary: Create contact inbox
parameters:
- $ref: '#/components/parameters/account_id'
- name: id
in: path
schema:
type: number
description: ID of the contact
required: true
security:
- userApiKey: []
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- inbox_id
properties:
inbox_id:
type: number
description: The ID of the inbox
example: 1
source_id:
type: string
description: Contact Inbox Source Id
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/contact_inboxes'
'401':
description: Authentication error
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'422':
description: Incorrect payload
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
servers:
- url: https://app.chatwoot.com/
/api/v1/accounts/{account_id}/contacts/{id}/contactable_inboxes:
get:
tags:
- Contacts
operationId: contactableInboxesGet
description: Get List of contactable Inboxes
summary: Get Contactable Inboxes
security:
- userApiKey: []
parameters:
- $ref: '#/components/parameters/account_id'
- name: id
in: path
schema:
type: number
description: ID of the contact
required: true
responses:
'200':
description: Success
content:
application/json:
schema:
$ref: '#/components/schemas/contactable_inboxes_response'
'401':
description: Authentication error
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'422':
description: Incorrect payload
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
servers:
- url: https://app.chatwoot.com/
/api/v1/accounts/{account_id}/actions/contact_merge:
parameters:
- $ref: '#/components/parameters/account_id'
post:
tags:
- Contacts
operationId: contactMerge
summary: Merge Contacts
security:
- userApiKey: []
description: 'Merge two contacts into a single contact. The base contact remains and receives all
data from the mergee contact. After the merge, the mergee contact is permanently deleted.
This action is irreversible. All conversations, labels, and custom attributes from the
mergee contact will be moved to the base contact.
'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- base_contact_id
- mergee_contact_id
properties:
base_contact_id:
type: integer
description: ID of the contact that will remain after the merge and receive all data
example: 1
mergee_contact_id:
type: integer
description: ID of the contact that will be merged into the base contact and deleted
example: 2
responses:
'200':
description: Contacts merged successfully
content:
application/json:
schema:
$ref: '#/components/schemas/contact_base'
'400':
description: Bad request - invalid contact IDs or contacts cannot be merged
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'401':
description: Unauthorized
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
'404':
description: One or both contacts not found
content:
application/json:
schema:
$ref: '#/components/schemas/bad_request_error'
servers:
- url: https://app.chatwoot.com/
components:
schemas:
contact_base:
allOf:
- $ref: '#/components/schemas/generic_id'
- $ref: '#/components/schemas/contact'
contact_inboxes:
type: object
properties:
source_id:
type: string
description: Contact Inbox Source Id
inbox:
$ref: '#/components/schemas/inbox_contact'
inbox_contact:
type: object
properties:
id:
type: number
description: ID of the inbox
avatar_url:
type: string
description: The avatar image of the inbox
channel_id:
type: number
description: The ID of the channel
name:
type: string
description: The name of the inbox
channel_type:
type: string
description: The type of the inbox
provider:
type: string
description: The provider of the inbox
contact_inbox:
type: object
properties:
source_id:
type: string
description: Source identifier for the contact inbox
inbox:
type: object
properties:
id:
type: integer
description: ID of the inbox
avatar_url:
type: string
description: URL for the inbox avatar
channel_id:
type: integer
description: ID of the channel
name:
type: string
description: Name of the inbox
channel_type:
type: string
description: Type of channel
provider:
type:
- string
- 'null'
description: Provider of the inbox
bad_request_error:
title: data
type: object
properties:
description:
type: string
errors:
type: array
items:
$ref: '#/components/schemas/request_error'
contact:
type: object
properties:
payload:
type: array
items:
type: object
properties:
additional_attributes:
type: object
description: The object containing additional attributes related to the contact
availability_status:
type: string
description: The availability status of the contact
email:
type: string
description: The email address of the contact
id:
type: integer
description: The ID of the contact
name:
type: string
description: The name of the contact
phone_number:
type: string
description: The phone number of the contact
blocked:
type: boolean
description: Whether the contact is blocked
identifier:
type: string
description: The identifier of the contact
thumbnail:
type: string
description: The thumbnail of the contact
custom_attributes:
type: object
description: The custom attributes of the contact
example:
attribute_key: attribute_value
signed_up_at: dd/mm/yyyy
last_activity_at:
type: integer
description: The last activity at of the contact
created_at:
type: integer
description: The created at of the contact
contact_inboxes:
type: array
items:
$ref: '#/components/schemas/contact_inboxes'
generic_id:
type: object
properties:
id:
type: number
message:
type: object
properties:
id:
type: number
description: The ID of the message
content:
type: string
description: The text content of the message
account_id:
type: number
description: The ID of the account
inbox_id:
type: number
description: The ID of the inbox
conversation_id:
type: number
description: The ID of the conversation
message_type:
type: integer
enum:
- 0
- 1
- 2
- 3
description: The type of the message
created_at:
type: integer
description: The time at which message was created
updated_at:
type: integer
description: The time at which message was updated
private:
type: boolean
description: The flags which shows whether the message is private or not
status:
type:
- string
- 'null'
enum:
- sent
- delivered
- read
- failed
- null
description: The status of the message
source_id:
type:
- string
- 'null'
description: The source ID of the message
content_type:
type:
- string
- 'null'
enum:
- text
- input_text
- input_textarea
- input_email
- input_select
- cards
- form
- article
- incoming_email
- input_csat
- integrations
- sticker
- voice_call
- null
description: The type of the template message
content_attributes:
type: object
description: The content attributes for each content_type
sender_type:
type:
- string
- 'null'
enum:
- Contact
- User
- AgentBot
- Captain::Assistant
- null
description: The type of the sender
sender_id:
type:
- number
- 'null'
description: The ID of the sender
external_source_ids:
type: object
description: The external source IDs of the message
additional_attributes:
type: object
description: The additional attributes of the message
processed_message_content:
type:
- string
- 'null'
description: The processed message content
sentiment:
type:
- object
- 'null'
description: The sentiment of the message
conversation:
type:
- object
- 'null'
description: The conversation object
attachment:
type:
- object
- 'null'
description: The file object attached to the image
sender:
type: object
description: User/Agent/AgentBot object
contact_list_item:
type: object
properties:
additional_attributes:
type: object
description: The object containing additional attributes related to the contact
properties:
city:
type: string
description: City of the contact
country:
type: string
description: Country of the contact
country_code:
type:
- string
- 'null'
description: Country code of the contact
created_at_ip:
type: string
description: IP address when the contact was created
availability_status:
type: string
description: Availability status of the contact
enum:
- online
- offline
email:
type:
- string
- 'null'
description: The email address of the contact
id:
type: integer
description: The ID of the contact
name:
type: string
description: The name of the contact
phone_number:
type:
- string
- 'null'
description: The phone number of the contact
blocked:
type: boolean
description: Whether the contact is blocked
identifier:
type:
- string
- 'null'
description: The identifier of the contact
thumbnail:
type: string
description: The thumbnail of the contact
custom_attributes:
type: object
description: The custom attributes of the contact
last_activity_at:
type:
- integer
- 'null'
description: Timestamp of last activity
created_at:
type: integer
description: Timestamp when contact was created
contact_inboxes:
type: array
description: List of inboxes associated with this contact
items:
$ref: '#/components/schemas/contact_inbox'
contact_update_payload:
type: object
properties:
name:
type: string
description: name of the contact
example: Alice
email:
type: string
description: email of the contact
example: alice@acme.inc
blocked:
type: boolean
description: whether the contact is blocked or not
example: false
phone_number:
type: string
description: phone number of the contact
example: '+123456789'
avatar:
type: string
format: binary
description: Send the form data with the avatar image binary or use the avatar_url
avatar_url:
type: string
description: The url to a jpeg, png file for the contact avatar
example: https://example.com/avatar.png
identifier:
type: string
description: A unique identifier for the contact in external system
example: '1234567890'
additional_attributes:
type: object
description: An object where you can store additional attributes for contact. example {"type":"customer", "age":30}
example:
type: customer
age: 30
custom_attributes:
type: object
description: An object where you can store custom attributes for contact. example {"type":"customer", "age":30}, this should have a valid custom attribute definition.
example: {}
contact_show_response:
type: object
properties:
payload:
$ref: '#/components/schemas/contact_list_item'
extended_contact:
allOf:
- $ref: '#/components/schemas/contact'
- type: object
properties:
id:
type: number
description: Id of the user
availability_status:
type: string
enum:
- online
- offline
description: Availability status of the user
conversation:
type: object
properties:
id:
type: number
description: ID of the conversation
messages:
type: array
items:
$ref: '#/components/schemas/message'
account_id:
type: number
description: Account Id
uuid:
type: string
description: UUID of the conversation
additional_attributes:
type: object
description: The object containing additional attributes related to the conversation
agent_last_seen_at:
type: number
description: The last activity at of the agent
assignee_last_seen_at:
type: number
description: The last activity at of the assignee
can_reply:
type: boolean
description: Whether the conversation can be replied to
contact_last_seen_at:
type: number
description: The last activity at of the contact
custom_attributes:
type: object
description: The object to save custom attributes for conversation, accepts custom attributes key and value
inbox_id:
type: number
description: ID of the inbox
labels:
type: array
items:
type: string
description: The labels of the conversation
muted:
type: boolean
description: Whether the conversation is muted
snoozed_until:
type:
- number
- 'null'
description: The time at which the conversation will be unmuted
status:
type: string
enum:
- open
- resolved
- pending
description: The status of the conversation
created_at:
type: number
description: The time at which conversation was created
updated_at:
type: number
description: The time at which conversation was updated
timestamp:
type: number
description: The time at which conversation was created
first_reply_created_at:
type:
- number
- 'null'
description: The time at which the first reply was created
unread_count:
type: number
description: The number of unread messages
last_non_activity_message:
oneOf:
- $ref: '#/components/schemas/message'
- type: 'null'
description: The last non activity message
last_activity_at:
type: number
description: The last activity at of the conversation
priority:
type:
- string
- 'null'
description: The priority of the conversation
waiting_since:
type:
- number
- 'null'
description: The time at which the conversation was waiting
sla_policy_id:
type:
- number
- 'null'
description: The ID of the SLA policy
applied_sla:
type: object
description: The applied SLA
sla_events:
type: array
items:
type: object
description: SLA event objects
contact_conversations_response:
type: object
properties:
payload:
type: array
items:
allOf:
- $ref: '#/components/schemas/conversation'
- type: object
properties:
meta:
type: object
properties:
sender:
type: object
properties:
additional_attributes:
type: object
description: The additional attributes of the sender
availability_status:
type: string
description: The availability status of the sender
email:
type:
- string
- 'null'
description: The email of the sender
id:
type: number
description: ID fo the sender
name:
type: string
description: The name of the sender
phone_number:
type:
- string
- 'null'
description: The phone number of the sender
blocked:
type: boolean
description: Whether the sender is blocked
identifier:
type:
- string
- 'null'
description: The identifier of the sender
thumbnail:
type:
- string
- 'null'
description: Avatar URL of the contact
custom_attributes:
type: object
description: The custom attributes of the sender
last_activity_at:
type: number
description: The last activity at of the sender
created_at:
type: number
description: The created at of the sender
channel:
type: string
description: Channel Type
assignee:
$ref: '#/components/schemas/user'
hmac_verified:
type: boolean
description: Whether the hmac is verified
description: List of conversations for the contact
contact_create_payload:
type: object
required:
- inbox_id
properties:
inbox_id:
type: number
description: ID of the inbox to which the contact belongs
example: 1
name:
type: string
description: name of the contact
example: Alice
email:
type: string
description: email of the contact
example: alice@acme.inc
blocked:
type: boolean
description: whether the c
# --- truncated at 32 KB (40 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/chatwoot/refs/heads/main/openapi/chatwoot-contacts-api-openapi.yml