Contacts API
8x8 Contacts API for managing contacts and contact groups used as recipients across the Connect messaging and voice products.
OpenAPI Specification
{
"openapi": "3.0.0",
"info": {
"title": "Contacts API",
"version": "1",
"description": "Contacts API v1",
"contact": {
"name": "8x8 Inc",
"url": "https://cpaas.8x8.com",
"email": "cpaas-support@8x8.com"
},
"termsOfService": "https://cpaas.8x8.com/sg/terms-and-conditions/"
},
"servers": [
{
"url": "https://contacts.8x8.com",
"description": "Asia-Pacific region"
},
{
"url": "https://contacts.us.8x8.com",
"description": "North America region"
},
{
"url": "https://contacts.8x8.uk",
"description": "Europe region"
},
{
"url": "https://contacts.8x8.id",
"description": "Indonesia region"
}
],
"tags": [
{
"name": "Contacts API"
}
],
"paths": {
"/api/v1/accounts/{accountId}/contacts": {
"get": {
"responses": {
"200": {
"description": "",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/contact-list"
},
"examples": {}
}
}
},
"400": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/get/responses/400"
}
},
"summary": "Search contacts",
"parameters": [
{
"$ref": "#/components/parameters/limit"
},
{
"$ref": "#/components/parameters/offset"
},
{
"schema": {
"type": "string",
"maxLength": 320
},
"in": "query",
"name": "query",
"description": "Some arbitrary string to search for. Can be name or one of addresses (email, phone number, etc)"
},
{
"schema": {
"type": "integer",
"minimum": 0
},
"in": "query",
"name": "groupId",
"description": "Search contacts in a particular group"
},
{
"schema": {
"type": "string",
"minLength": 2,
"maxLength": 2,
"example": "US"
},
"in": "query",
"name": "country",
"description": "To search for a contact or contacts using country, please use Alpha-2 country code ([two character country codes](https://www.iban.com/country-codes))"
}
],
"description": "Search for contacts",
"operationId": "contact-search",
"tags": ["Contacts API"]
},
"parameters": [
{
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/parameters/0"
}
],
"post": {
"summary": "Create contact",
"operationId": "create-contact",
"responses": {
"200": {
"description": "You'll receive 200 OK if the contact has been merged with another contact based on one of provided addresses",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/contact"
}
}
}
},
"201": {
"description": "You'll receive 201 Created if the contact has been created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/contact"
},
"examples": {
"example-1": {
"value": {
"id": 41764986,
"createdAt": "2022-04-18T07:39:55.52Z",
"externalId": "87668",
"country": "US",
"groups": [
{
"id": 8199,
"contacts": 1,
"createdAt": "2022-04-13T08:41:47.82Z",
"name": "some group",
"description": "General",
"isBlacklist": false
}
],
"addresses": {
"msisdn": "16511112222"
},
"customAttributes": {}
}
}
}
}
}
},
"400": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/get/responses/400"
},
"409": {
"description": "Conflict: more than one contact was found based on a provided set of addresses.",
"content": {
"application/json": {
"schema": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/post/responses/409/content/application~1json/schema"
}
}
}
}
},
"description": "Create a new contact",
"tags": ["Contacts API"],
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/create-contact"
}
}
}
}
}
},
"/api/v1/accounts/{accountId}/contacts/blacklist/{msisdn}": {
"parameters": [
{
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/parameters/0"
},
{
"schema": {
"type": "string"
},
"name": "msisdn",
"in": "path",
"required": true,
"description": "Msisdn to blacklist",
"example": 6512345678
}
],
"post": {
"summary": "Blacklist msisdn for a specific account",
"operationId": "blacklist-msisdn",
"tags": ["Contacts API"],
"requestBody": {
"required": false,
"content": {
"application/json": {
"schema": {
"type": "string"
}
}
}
},
"responses": {
"200": {
"description": "OK"
},
"400": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/get/responses/400"
},
"401": {
"description": "Request was not authenticated response",
"content": {
"application/json": {
"schema": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/post/responses/409/content/application~1json/schema"
},
"example": {
"code": 1200,
"message": "Request was not authenticated properly",
"errorId": "db9dced4-3534-4d86-9d18-6b448af0d621",
"timestamp": "2018-08-02T09:42:38.8988997+00:00"
}
}
}
}
}
}
},
"/api/v1/accounts/{accountId}/contacts/{contactId}": {
"parameters": [
{
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/parameters/0"
},
{
"schema": {
"type": "string"
},
"name": "contactId",
"in": "path",
"required": true,
"description": "Contact Id"
}
],
"get": {
"summary": "Get contact information by id",
"tags": ["Contacts API"],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/contact"
},
"examples": {}
}
}
},
"404": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1batches~1%7BbatchId%7D/get/responses/404"
}
},
"operationId": "get-contact-by-id",
"description": "Get contact information by contact id"
},
"delete": {
"summary": "Delete single contact",
"operationId": "delete-single-contact",
"tags": ["Contacts API"],
"responses": {
"204": {
"description": "No Content"
}
},
"description": "Delete single contact by id"
},
"patch": {
"summary": "Update contact information",
"operationId": "update-contact",
"tags": ["Contacts API"],
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/contact"
}
}
}
},
"400": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/get/responses/400"
},
"404": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1batches~1%7BbatchId%7D/get/responses/404"
}
},
"description": "Update contact information",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/update-contact"
},
"examples": {
"Update the first name and the last name": {
"value": [
{
"op": "replace",
"path": "/firstName",
"value": "John"
},
{
"op": "replace",
"path": "/lastName",
"value": "Black"
}
]
},
"Add LineId to address list and remove MSISDN": {
"value": [
{
"op": "add",
"path": "/addresses/lineId",
"value": "line"
},
{
"op": "remove",
"path": "/addresses/msisdn"
}
]
},
"Add custom attributes": {
"value": [
{
"op": "add",
"path": "/customAttributes/Department",
"value": "Sales"
},
{
"op": "add",
"path": "/customAttributes/Position",
"value": "VP"
}
]
}
}
}
}
}
}
},
"/api/v1/accounts/{accountId}/groups": {
"parameters": [
{
"name": "accountId",
"in": "path",
"description": "You must replace *{accountId}* with the accountid that you want to use.",
"required": true,
"schema": {
"maxLength": 36,
"minLength": 32,
"pattern": "^[0-9A-Fa-f]{8}[-]?(?:[0-9A-Fa-f]{4}[-]?){3}[0-9A-Fa-f]{12}$",
"type": "string"
}
}
],
"get": {
"summary": "Search for groups",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/group-list"
}
}
}
},
"400": {
"description": "Bad request error response",
"content": {
"application/json": {
"schema": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/post/responses/409/content/application~1json/schema"
},
"example": {
"code": 1002,
"message": "Invalid MSISDN format (not E.164 international number)",
"errorId": "b4478860-b76c-e811-814e-022a35cc1c71",
"timestamp": "2018-08-04T09:25:40.9235752+00:00"
}
}
}
}
},
"operationId": "search-groups",
"description": "Search for groups",
"parameters": [
{
"$ref": "#/components/parameters/limit"
},
{
"$ref": "#/components/parameters/offset"
},
{
"schema": {
"type": "string"
},
"in": "query",
"name": "name",
"description": "Group name to search for"
}
],
"tags": ["Groups API"]
},
"post": {
"summary": "Create a group",
"operationId": "create-group",
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/group"
}
}
}
},
"400": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/get/responses/400"
},
"409": {
"description": "Conflict: the group with the same name already exists",
"content": {
"application/json": {
"schema": {
"title": "ErrorResponse",
"required": ["code", "errorId", "timestamp"],
"type": "object",
"properties": {
"code": {
"type": "integer",
"description": "Error code"
},
"message": {
"type": "string",
"description": "Error description"
},
"errorId": {
"type": "string",
"description": "Unique id of error. You can use it as reference when sending enquiries to 8x8 support",
"format": "uuid"
},
"timestamp": {
"type": "string",
"description": "Data and time of the error occurence",
"format": "date-time"
}
},
"description": "Response in case of error",
"example": {
"code": 1001,
"message": "Provided subAccountId doesn't belongs to your account",
"errorId": "91b106f0-c0da-4aba-a43a-7af9c5893a80",
"timestamp": "2017-04-19T02:31:19.4297387+00:00"
}
},
"examples": {
"Conflicting group name": {
"value": {
"code": 5003,
"message": "A group with the same name already exists",
"errorId": "6f24a5c7-0fa2-48f4-a47a-ae7b009829ef",
"timestamp": "2022-04-18T09:14:00.7458733+00:00"
}
}
}
}
}
}
},
"description": "Create a group",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/create-group"
}
}
}
},
"tags": ["Groups API"]
}
},
"/api/v1/accounts/{accountId}/groups/{groupId}": {
"parameters": [
{
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/parameters/0"
},
{
"$ref": "#/components/parameters/groupId"
}
],
"get": {
"summary": "Get group information by id",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/group"
}
}
}
},
"404": {
"description": "Not Found",
"content": {
"application/json": {
"schema": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/post/responses/409/content/application~1json/schema"
},
"examples": {
"Group not found": {
"value": {
"code": 1300,
"message": "Unable to find group with id 6776",
"errorId": "200171e8-4d61-45d1-a8b7-ae7b009a3dfe",
"timestamp": "2022-04-18T09:21:34.74Z"
}
}
}
}
}
}
},
"operationId": "get-group-by-id",
"description": "Get group information by id",
"tags": ["Groups API"]
},
"delete": {
"summary": "Delete group",
"operationId": "delete-group",
"responses": {
"204": {
"description": "No Content",
"content": {
"application/json": {
"schema": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/post/responses/409/content/application~1json/schema"
},
"examples": {
"Group not found": {
"value": {
"code": 1300,
"message": "Unable to find a group with id 6812",
"errorId": "8f6127c9-941f-42f7-953b-ae7b009a8865",
"timestamp": "2022-04-18T09:22:38.2853374+00:00"
}
}
}
}
}
},
"404": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1batches~1%7BbatchId%7D/get/responses/404"
}
},
"description": "Delete group",
"tags": ["Groups API"]
},
"patch": {
"summary": "Update group information",
"operationId": "update-group",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/group"
}
}
}
},
"400": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/get/responses/400"
},
"404": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1batches~1%7BbatchId%7D/get/responses/404"
},
"409": {
"description": "Conflict: the group with the same name already exists",
"content": {
"application/json": {
"schema": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/post/responses/409/content/application~1json/schema"
},
"examples": {
"Conflicting group name": {
"value": {
"code": 5003,
"message": "A group with the same name already exists",
"errorId": "6f24a5c7-0fa2-48f4-a47a-ae7b009829ef",
"timestamp": "2022-04-18T09:14:00.7458733+00:00"
}
}
}
}
}
}
},
"description": "Update group information",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/update-group"
},
"examples": {
"Mark group as a blacklist": {
"value": [
{
"op": "replace",
"path": "/isblacklist",
"value": "true"
}
]
},
"Change group name": {
"value": [
{
"op": "replace",
"path": "/name",
"value": "New group name"
}
]
},
"Add group description": {
"value": [
{
"op": "add",
"path": "/description",
"value": "Group description"
}
]
}
}
}
}
},
"tags": ["Groups API"]
}
},
"/api/v1/accounts/{accountId}/groups/{groupId}/contacts": {
"parameters": [
{
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/parameters/0"
},
{
"$ref": "#/components/parameters/groupId"
}
],
"post": {
"summary": "Add a contact to a group",
"operationId": "add-contacts-to-group",
"parameters": [
{
"$ref": "#/components/parameters/groupId"
}
],
"responses": {
"201": {
"description": "Created",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/group"
}
}
}
},
"404": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1batches~1%7BbatchId%7D/get/responses/404"
}
},
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/contact-id-list"
}
}
}
},
"description": "Add a contact to a group",
"tags": ["Groups API"]
},
"delete": {
"summary": "Remove contacts from a group",
"operationId": "delete-contacts-from-group",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/group"
}
}
}
},
"404": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1batches~1%7BbatchId%7D/get/responses/404"
}
},
"description": "Delete contacts from group",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/contact-id-list"
}
}
}
},
"tags": ["Groups API"]
}
},
"/api/v1/accounts/{accountId}/contacts/batches/createContacts": {
"parameters": [
{
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/parameters/0"
}
],
"post": {
"summary": "Batch create contacts",
"operationId": "batch-upload-contacts",
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/batch-upload-job"
}
}
}
},
"400": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/get/responses/400"
}
},
"description": "Batch create contacts using file. The file can be either CSV or Excel. The CSV file can contain a header row (the mapping of the columns will be automatic in this case), or not. For files without a header, the `fileColumns` property should be specified for a columns mapping.",
"requestBody": {
"content": {
"multipart/form-data": {
"schema": {
"$ref": "#/components/schemas/batch-upload-contacts"
},
"examples": {
"Upload a csv file with header and add contacts to groups": {
"value": {
"file": {},
"groups": "11566,88996",
"fileHasHeader": true
}
},
"Upload a file": {
"value": {
"file": {}
}
},
"Upload a csv file without a header with specified columns": {
"value": {
"file": {},
"fileHasHeader": false,
"fileColumns": "msisdn, firstName, lastName"
}
}
}
}
}
},
"tags": ["Batch API"]
}
},
"/api/v1/accounts/{accountId}/contacts/batches/deleteContacts": {
"parameters": [
{
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/parameters/0"
}
],
"post": {
"summary": "Batch delete contacts",
"operationId": "batch-delete-contacts",
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/batch-job"
}
}
}
},
"400": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/get/responses/400"
}
},
"description": "Use this endpoint to delete multiple/all contacts in batch. Provide `ids` or `msisdns` to remove specific contacts, or set `\"all\": true` to delete all contacts in your account.",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/batch-delete-contacts"
},
"examples": {
"Specify contacts to delete": {
"value": {
"ids": [41764539, 41764538],
"msisdns": ["+6512345678", "6523456789"]
}
},
"Specify only contacts ids to delete": {
"value": {
"ids": [41764539, 41764538]
}
},
"Specify only msisdns to delete": {
"value": {
"msisdns": ["+6512345678", "6523456789"]
}
},
"Delete all contacts": {
"value": {
"all": true
}
}
}
}
}
},
"tags": ["Batch API"]
}
},
"/api/v1/accounts/{accountId}/groups/batches/copyContacts": {
"parameters": [
{
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/parameters/0"
}
],
"post": {
"summary": "Copy contacts between groups",
"operationId": "batch-copy-contacts",
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/batch-job"
}
}
}
},
"400": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/get/responses/400"
}
},
"parameters": [
{
"schema": {
"type": "integer"
},
"in": "query",
"name": "from",
"description": "Identifier of the source group",
"required": true
},
{
"schema": {
"type": "integer"
},
"in": "query",
"name": "to",
"description": "Identifier of the destination group",
"required": true
}
],
"description": "Copy contacts from ony group to another one.",
"tags": ["Batch API"]
}
},
"/api/v1/accounts/{accountId}/groups/batches/moveContacts": {
"parameters": [
{
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/parameters/0"
}
],
"post": {
"summary": "Move contacts between groups",
"operationId": "batch-move-contacts",
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/batch-job"
}
}
}
},
"400": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/get/responses/400"
}
},
"description": "Move contacts from one group to another one. This operation will delete contacts in the original group.",
"parameters": [
{
"schema": {
"type": "integer"
},
"in": "query",
"name": "from",
"description": "Identifier of the source group",
"required": true
},
{
"schema": {
"type": "integer"
},
"in": "query",
"name": "to",
"description": "Identifier of the destination group",
"required": true
}
],
"tags": ["Batch API"]
}
},
"/api/v1/accounts/{accountId}/groups/batches/deleteGroups": {
"parameters": [
{
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/parameters/0"
}
],
"post": {
"summary": "Batch delete groups",
"operationId": "batch-delete-groups",
"responses": {
"202": {
"description": "Accepted",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/batch-job"
}
}
}
},
"400": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/get/responses/400"
}
},
"description": "Batch delete groups",
"requestBody": {
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/batch-delete-groups"
}
}
}
},
"tags": ["Batch API"]
}
},
"/api/v1/accounts/{accountId}/batches/{batchId}": {
"parameters": [
{
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/parameters/0"
},
{
"schema": {
"type": "string",
"format": "uuid"
},
"name": "batchId",
"in": "path",
"required": true,
"description": "Batch Id"
}
],
"get": {
"summary": "Get batch information by id",
"responses": {
"200": {
"description": "OK",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/batch-job"
}
}
}
},
"404": {
"description": "The entity doesn't exist",
"content": {
"application/json": {
"schema": {
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/post/responses/409/content/application~1json/schema"
},
"example": {
"code": 4018,
"message": "Invalid jobId",
"errorId": "aa400d4b-fffe-ea11-8277-00155d4ff7ed",
"timestamp": "2020-09-25T07:18:22.78Z"
}
}
}
}
},
"operationId": "get-batch-by-id",
"description": "Get batch information by id",
"tags": ["Batch API"]
}
},
"/api/v1/accounts/{accountId}/batches": {
"parameters": [
{
"$ref": "#/paths/~1api~1v1~1accounts~1%7BaccountId%7D~1groups/parameters/0"
}
],
"get": {
"
# --- truncated at 32 KB (57 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/8x8/refs/heads/main/openapi/8x8-connect-contacts-api.json