The MessageBird Contacts API allows developers to manage contact information for end-users and customers across messaging platforms. It supports creating, reading, updating, and deleting contacts, as well as organizing them into groups for targeted messaging campaigns. A single contact can be associated with multiple communication channels such as SMS, WhatsApp, and Telegram.
openapi: 3.1.0
info:
title: MessageBird Contacts API
description: >-
The MessageBird Contacts API allows developers to manage contact
information for end-users and customers across messaging platforms. It
supports creating, reading, updating, and deleting contacts, as well as
organizing them into groups for targeted messaging campaigns. A single
contact can be associated with multiple communication channels such as
SMS, WhatsApp, and Telegram.
version: '1.0'
contact:
name: MessageBird Support
url: https://support.messagebird.com
termsOfService: https://www.messagebird.com/en/terms
externalDocs:
description: Contacts API Documentation
url: https://developers.messagebird.com/api/contacts/
servers:
- url: https://rest.messagebird.com
description: Production Server
tags:
- name: Contacts
description: >-
Operations for managing individual contacts.
- name: Groups
description: >-
Operations for managing contact groups.
security:
- accessKey: []
paths:
/contacts:
get:
operationId: listContacts
summary: List contacts
description: >-
Retrieves a paginated list of all contacts in the address book.
tags:
- Contacts
parameters:
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/limitParam'
responses:
'200':
description: A list of contacts
content:
application/json:
schema:
$ref: '#/components/schemas/ContactList'
'401':
description: Unauthorized
post:
operationId: createContact
summary: Create a contact
description: >-
Creates a new contact in the address book with the specified phone
number and optional details.
tags:
- Contacts
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContactCreate'
responses:
'201':
description: Contact created
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
'400':
description: Bad request
'401':
description: Unauthorized
'422':
description: Unprocessable entity
/contacts/{contactId}:
get:
operationId: viewContact
summary: View a contact
description: >-
Retrieves the details of a specific contact by its unique
identifier.
tags:
- Contacts
parameters:
- $ref: '#/components/parameters/contactIdParam'
responses:
'200':
description: Contact details
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
'401':
description: Unauthorized
'404':
description: Contact not found
patch:
operationId: updateContact
summary: Update a contact
description: >-
Updates an existing contact with the provided fields.
tags:
- Contacts
parameters:
- $ref: '#/components/parameters/contactIdParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/ContactUpdate'
responses:
'200':
description: Contact updated
content:
application/json:
schema:
$ref: '#/components/schemas/Contact'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Contact not found
delete:
operationId: deleteContact
summary: Delete a contact
description: >-
Deletes a contact from the address book by its unique identifier.
tags:
- Contacts
parameters:
- $ref: '#/components/parameters/contactIdParam'
responses:
'204':
description: Contact deleted
'401':
description: Unauthorized
'404':
description: Contact not found
/contacts/{contactId}/messages:
get:
operationId: listContactMessages
summary: List messages for a contact
description: >-
Retrieves all messages associated with a specific contact.
tags:
- Contacts
parameters:
- $ref: '#/components/parameters/contactIdParam'
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/limitParam'
responses:
'200':
description: A list of messages
content:
application/json:
schema:
type: object
properties:
offset:
type: integer
limit:
type: integer
count:
type: integer
totalCount:
type: integer
items:
type: array
items:
type: object
'401':
description: Unauthorized
'404':
description: Contact not found
/contacts/{contactId}/groups:
get:
operationId: listContactGroups
summary: List groups for a contact
description: >-
Retrieves all groups that a specific contact belongs to.
tags:
- Groups
parameters:
- $ref: '#/components/parameters/contactIdParam'
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/limitParam'
responses:
'200':
description: A list of groups
content:
application/json:
schema:
$ref: '#/components/schemas/GroupList'
'401':
description: Unauthorized
'404':
description: Contact not found
/groups:
get:
operationId: listGroups
summary: List groups
description: >-
Retrieves a paginated list of all contact groups.
tags:
- Groups
parameters:
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/limitParam'
responses:
'200':
description: A list of groups
content:
application/json:
schema:
$ref: '#/components/schemas/GroupList'
'401':
description: Unauthorized
post:
operationId: createGroup
summary: Create a group
description: >-
Creates a new contact group with the specified name.
tags:
- Groups
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GroupCreate'
responses:
'201':
description: Group created
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
'400':
description: Bad request
'401':
description: Unauthorized
/groups/{groupId}:
get:
operationId: viewGroup
summary: View a group
description: >-
Retrieves the details of a specific group by its unique identifier.
tags:
- Groups
parameters:
- $ref: '#/components/parameters/groupIdParam'
responses:
'200':
description: Group details
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
'401':
description: Unauthorized
'404':
description: Group not found
patch:
operationId: updateGroup
summary: Update a group
description: >-
Updates the name of an existing group.
tags:
- Groups
parameters:
- $ref: '#/components/parameters/groupIdParam'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/GroupCreate'
responses:
'200':
description: Group updated
content:
application/json:
schema:
$ref: '#/components/schemas/Group'
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Group not found
delete:
operationId: deleteGroup
summary: Delete a group
description: >-
Deletes an existing group. This does not delete the contacts in
the group.
tags:
- Groups
parameters:
- $ref: '#/components/parameters/groupIdParam'
responses:
'204':
description: Group deleted
'401':
description: Unauthorized
'404':
description: Group not found
/groups/{groupId}/contacts:
get:
operationId: listGroupContacts
summary: List contacts in a group
description: >-
Retrieves all contacts that belong to a specific group.
tags:
- Groups
parameters:
- $ref: '#/components/parameters/groupIdParam'
- $ref: '#/components/parameters/offsetParam'
- $ref: '#/components/parameters/limitParam'
responses:
'200':
description: A list of contacts
content:
application/json:
schema:
$ref: '#/components/schemas/ContactList'
'401':
description: Unauthorized
'404':
description: Group not found
put:
operationId: addContactsToGroup
summary: Add contacts to a group
description: >-
Adds one or more contacts to a group by their contact identifiers.
tags:
- Groups
parameters:
- $ref: '#/components/parameters/groupIdParam'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
ids:
type: array
description: >-
The list of contact identifiers to add.
items:
type: string
responses:
'204':
description: Contacts added to group
'400':
description: Bad request
'401':
description: Unauthorized
'404':
description: Group not found
/groups/{groupId}/contacts/{contactId}:
delete:
operationId: removeContactFromGroup
summary: Remove a contact from a group
description: >-
Removes a specific contact from a group.
tags:
- Groups
parameters:
- $ref: '#/components/parameters/groupIdParam'
- $ref: '#/components/parameters/contactIdParam'
responses:
'204':
description: Contact removed from group
'401':
description: Unauthorized
'404':
description: Resource not found
components:
securitySchemes:
accessKey:
type: apiKey
in: header
name: Authorization
description: >-
Access key authentication in the form of 'AccessKey {accessKey}'.
parameters:
contactIdParam:
name: contactId
in: path
required: true
description: >-
The unique identifier of the contact.
schema:
type: string
groupIdParam:
name: groupId
in: path
required: true
description: >-
The unique identifier of the group.
schema:
type: string
offsetParam:
name: offset
in: query
required: false
description: >-
The number of items to skip.
schema:
type: integer
default: 0
limitParam:
name: limit
in: query
required: false
description: >-
The maximum number of items to return.
schema:
type: integer
default: 20
schemas:
ContactCreate:
type: object
required:
- msisdn
properties:
msisdn:
type: string
description: >-
The phone number of the contact in international format.
firstName:
type: string
description: >-
The first name of the contact.
lastName:
type: string
description: >-
The last name of the contact.
custom1:
type: string
description: >-
Custom field 1.
custom2:
type: string
description: >-
Custom field 2.
custom3:
type: string
description: >-
Custom field 3.
custom4:
type: string
description: >-
Custom field 4.
ContactUpdate:
type: object
properties:
firstName:
type: string
description: >-
The first name of the contact.
lastName:
type: string
description: >-
The last name of the contact.
msisdn:
type: string
description: >-
The phone number of the contact.
custom1:
type: string
description: >-
Custom field 1.
custom2:
type: string
description: >-
Custom field 2.
custom3:
type: string
description: >-
Custom field 3.
custom4:
type: string
description: >-
Custom field 4.
Contact:
type: object
properties:
id:
type: string
description: >-
The unique identifier of the contact.
href:
type: string
format: uri
description: >-
The URL of the contact resource.
msisdn:
type: string
description: >-
The phone number of the contact.
firstName:
type: string
description: >-
The first name of the contact.
lastName:
type: string
description: >-
The last name of the contact.
custom1:
type: string
description: >-
Custom field 1.
custom2:
type: string
description: >-
Custom field 2.
custom3:
type: string
description: >-
Custom field 3.
custom4:
type: string
description: >-
Custom field 4.
groups:
type: object
description: >-
Links to the groups the contact belongs to.
properties:
href:
type: string
format: uri
totalCount:
type: integer
messages:
type: object
description: >-
Links to messages associated with the contact.
properties:
href:
type: string
format: uri
totalCount:
type: integer
createdDatetime:
type: string
format: date-time
description: >-
The date and time when the contact was created.
updatedDatetime:
type: string
format: date-time
description: >-
The date and time when the contact was last updated.
ContactList:
type: object
properties:
offset:
type: integer
description: >-
The offset of the result set.
limit:
type: integer
description: >-
The limit applied to the result set.
count:
type: integer
description: >-
The number of items returned.
totalCount:
type: integer
description: >-
The total number of contacts.
items:
type: array
items:
$ref: '#/components/schemas/Contact'
GroupCreate:
type: object
required:
- name
properties:
name:
type: string
description: >-
The name of the group.
Group:
type: object
properties:
id:
type: string
description: >-
The unique identifier of the group.
href:
type: string
format: uri
description: >-
The URL of the group resource.
name:
type: string
description: >-
The name of the group.
contacts:
type: object
description: >-
Links to the contacts in the group.
properties:
href:
type: string
format: uri
totalCount:
type: integer
createdDatetime:
type: string
format: date-time
description: >-
The date and time when the group was created.
updatedDatetime:
type: string
format: date-time
description: >-
The date and time when the group was last updated.
GroupList:
type: object
properties:
offset:
type: integer
description: >-
The offset of the result set.
limit:
type: integer
description: >-
The limit applied to the result set.
count:
type: integer
description: >-
The number of items returned.
totalCount:
type: integer
description: >-
The total number of groups.
items:
type: array
items:
$ref: '#/components/schemas/Group'