SmartCommunicator™ User Management APIs

This guide describes the APIs available to manage your SmartCommunicator users. Using these APIs you can:

Onboard Agents
Retrieve Information for a Single Agent
Retrieve Information for Multiple Agents
Update a Single Agent
Update Multiple Agents

Offboard a Single Agent
Offboard Multiple Agents
Create an Inbox
Manage Inbox Assignments
Retrieve Registered Phone Numbers

Overview

SmartCommunicator API are general-purpose endpoints for managing users, inboxes, and phone numbers within the SmartCommunicator app.

For more information about SmartCommunicator, check out the Quick Start Guide.

Base URL

All of the SmartCommunicator endpoints share the same base URL:

https://smartcommunicator-api-users.intelepeer.com

(e.g, GET https://smartcommunicator-api-users.intelepeer.com/{customer_id}/agents).

Prerequisites

Prior to working with the SmartCommunicator APIs, make sure the following are in place:

SmartCommunicator is enabled for the account
Messaging is enabled for SMS/MMS
The numbers have been 10DLC registered
All telephone numbers (TNs) are in the SComm database
All TNs have two-factor verification (2FV) in the SComm database
Your users have API Access set up up for their

Authorization

Important: To authenticate, you must first have API Access set up for your username and password. For more information, check out API Authentication. This topic includes how to set up new users with API access. If you are using Postman to send your API requests, make sure to add the following Keys in the Headers section: Content-Type: application/json and Accept: application/json. Check out the Sample for details.

The POST API takes a body consisting of username and password and makes an Authenticate API call to voice services:

POST https://atmosphere-api.intelepeer.com/rest/v1/authenticate

The response returns a 200 response with a token or 401 Unauthorized. If you are unauthorized, you receive an error message.

If you receive a 200 response, the encoded JSON Web Token (JWT) contains the eID, expirationTime, productID, and username.

JWT Request Body Example

{   
    "username": "someone@yourmail.com",
    "password": "enter_password_here"
}

Response Token Example

{ "data": "eyJhbGciOiJSUzI1NiJ9.eyJhaWQiOjAsImNpZCI6MSwiY3J0IjoxNzExOTg2NDg5LCJleHAiOjE3MTIwNzI4OTAsInVpZCI6InNiZWRveWEiLCJzcmMiOiJhcGktZ3R3In0.clYxxuFBW62FQj-nQLIjtE4HBG1iPKjlWsTfLlEqo_u6UN4D6u9Mk26LXsTYUgsTzZ6-wHCWOctYghh0VfQVpA}"}

Sample

The following sample shows the header setup for authentication using Postman. In this case, both the Accept and Content-Type values must be set to application/json.

Using the APIs

Keep in mind the following when using the SmartCommunicator endpoints:

Authentication tokens must be included in all requests (except the Authentication token request above).
All phone numbers must be in E.164 format (e.g., +11234567890).
Batch operations are limited to 10 items per request.

SmartCommunicator APIs

Click the following API titles to view the parameters and code samples associated with each endpoint.

User Management

Agent Onboarding

Add new SmartCommunicator agents to your account. Include up to 10 agents in a single request.

Endpoint

POST /{customer_id}/agents

Header

Accept: application/json
Authorization (*required): Your authentication token
Content-Type: application/json

Path Parameters

Customer ID (*required): Your account ID.

Query Parameters

continueOnError (optional): If an error occurs will your request continue or stop (defaults to false).
reassignInbox (optional): When onboarding an agent with a provision type of “supervised”, and the target number is assigned to an inbox of an offboarded or deactivated agent, this parameter indicates wether the newly onboarded agent should take ownership of the existing supervised inbox (defaults to false).

Body Parameters

user_object_id (*required): The unique identifier from the Azure Active Directory for the user.
tenant_id (*required): The unique identifier from the Azure Active Directory for your account (Tenant ID).
name (*required): The display name of the agent.
upn (optional): User Principal Name, typically the agent's email address.
consistency_id (optional): Unique customer-defined identifier.
brand_name (optional): Any applicable brand name.
department (optional): The department the agent belongs to.
region (optional): Geographic region where the agent is located.
state (optional): State/province where the agent is located.
district (optional): District or area code.
store (optional): Store identifier, if applicable.
roles (optional): List of roles the onboarded agent will be assigned. If not provided, the "member" role will be assigned by default.
number_provisioning (optional): Array of phone number configurations. It can have up to two elements, one for each type of number provisioning:
- type: Type of number ("supervised" or "messaging"):
  - "supervised": This will provision a Supervised Inbox where the onboarded agent is the owner. Can be used in conjunction with a supervisors key (below).
  - "messaging": This will provision a private messaging phone number for the onboarded agent.
- phone_number: The E.164 formatted phone number.
- supervisors: List of supervisors for a Supervised Inbox. Can only be used when type is "supervised". If this parameter is not provided, only the onboarded agent will be assigned to the inbox. This can be changed later through the Manage Inbox Assignments endpoint.
  - identifier: A piece of data to identify the supervisors (user_object_id, upn, consistency_id).
  - values: Identifier value(s). The values must match the type of identifier chosen above. For example, if your identifier was "user_object_id" the value would be "17c528d0...".
enabled_services (optional): Indicates the application tabs the agent will have access to. If not provided, the endpoint will dynamically determine which tabs the agent has access to based on number provisioning parameters.
- messages: User access to the Messages tab.
- supervisedInbox: User access to the Supervised Inbox tab.
- calls: User access to the Calls tab.
- sharedInbox: User access to the Shared Inbox tab.

Request Example

[
	{
		"user_object_id": "17c528d0-dcfa-49bf-bb2b-8955bf377e5a",
		"tenant_id": "80573892-bfe7-40c8-bd85-2b479110b2df",
		"name": "Agent name",
		"upn": "agent.email@domain.com",
		"consistency_id": "customer-defined-id-123",
		"brand_name": "Company name",
		"department": "Sales",
		"region": "US-East",
		"state": "CA",
		"district": "90210",
		"store": "1234",
		"city": "Los Angeles",
		"zip_code": "90210",
		"roles": [ "member", "manager" ],
		"number_provisioning": [
			{
				"type": "supervised",
				"phone_number": "+1234567890",
				"supervisors": {
					"identifier": "user_object_id",
					"values": ["17c528d0-dcfa-49bf-bb2b-8955bf377e5a"]
				}
			},
			{
				"type": "messaging",
				"phone_number": "+1234567891"
			}
		],
		"enabled_services": {
		"messages": true,
		"supervisedInbox": true,
		"calls": true,
		"sharedInbox": true
		}
	}
]

Response Examples

Code 200 Success Response

{
	"message": "Onboarded successfully",
	"errors": []
}

Code 400 Error Response

{
	"message": "Onboarding failed",
	"errors": [
		{
			"itemIndex": 0,
			"errors": ["An agent with the same user_object_id already exists"]
		}
	]
}

Retrieve Information for a Single Agent

Use this endpoint to view details for a single existing agent.

Endpoint

GET /{customer_id}/agents/{agent_id}

Header

Authorization (*required): Your authentication token.

Path Parameters

customer_id (*required): Your account ID.
agent_id (*required): The ID of the agent you want to view. Refers to the value of the key_id query parameter (below). If not provided, user_object_id will be used by default.

Query Parameters

key_id (optional): Field to identify the agent. Allowed values: user_object_id, consistency_id, or upn. If not provided, user_object_id will be used by default.
upn (optional): User Principal Name, typically the agent's email address.

Request Body

None

Response Examples

Code 200 Success Response

{
	"user_object_id": "64b50f0f-aea3-4251-9e58-6e56b234ddf1",
	"name": "Test Agent",
	"upn": "test@domain.tld",
	"tenant_id": "1234567890",
	"consistency_id": "customer-defined-id-123",
	"brand_name": "Company name",
	"department": "Some department",
	"region": "US-East",
	"state": "CA",
	"district": "90210",
	"store": "1234",
	"city": "Los Angeles",
	"zip_code": "90210",
	"phone_number": [
		{
			"type": "messaging",
			"value": "+1234567890"
		},
		{
			"type": "supervised",
			"value": "+1234567891"
		}
	],
	"roles": ["member", "manager", "admin"],
	"enabled_services": {
		"messages": true,
		"supervisedInbox": true,
		"calls": true,
		"sharedInbox": true
	},
	"supervisors": [
		{
			"user_object_id": "e0753fdc-321f-45e3-97ed-cc06e606aa93",
			"status": "active",
			"name": "Test SUpervisor",
			"upn": "supervisor@test.tld"
		}
	],
	"shared_inbox": [
		{
			"name": "Tech Support",
			"phone_number": "+15550000005"
		},
		{
			"name": "Sales",
			"phone_number": "+15550000006"
		}
	]
	"status": "active",
	"active": true
}

Code 404 Not Found Error Response

{
	"status": "error",
	"message": "object not found"
}

Retrieve Information For Multiple Agents

Use this endpoint to view details for all of your existing agents.

Endpoint

GET /{customer_id}/agents

Header

Authorization (*required): Your authentication token.

Path Parameters

customer_id (*required): Your account ID.

Query Parameters

user_object_id (optional): Filter results by agentuser_object_id.
tenant_id (optional): Filter results by agent tenant.
consistency_id (optional): Filter results by agent consistency_id.
phone_number (optional): Filter results by agent phone number (both messaging and Supervised Inbox numbers).
upn (optional): User Principal Name, typically the agent's email address.

Request Body

None

Response Examples

Code 200 Success Response

{
	"user_object_id": "64b50f0f-aea3-4251-9e58-6e56b234ddf1",
	"name": "Test Agent",
	"upn": "test@domain.tld",
	"tenant_id": "1234567890",
	"consistency_id": "customer-defined-id-123",
	"brand_name": "Company name",
	"department": "Some department",
	"region": "US-East",
	"state": "CA",
	"district": "90210",
	"store": "1234",
	"city": "Los Angeles",
	"zip_code": "90210",
	"phone_number": [
		{
			"type": "messaging",
			"value": "+1234567890"
		},
		{
			"type": "supervised",
			"value": "+1234567891"
		}
	],
	"roles": ["member", "manager", "admin"],
	"enabled_services": {
		"messages": true,
		"supervisedInbox": true,
		"calls": true,
		"sharedInbox": true
	},
	"supervisors": [
		{
			"user_object_id": "e0753fdc-321f-45e3-97ed-cc06e606aa93",
			"status": "active",
			"name": "Test SUpervisor",
			"upn": "supervisor@test.tld"
		}
	],
	"shared_inbox": [
		{
			"name": "Tech Support",
			"phone_number": "+15550000005"
		},
		{
			"name": "Sales",
			"phone_number": "+15550000006"
		}
	]
	"status": "active",
	"active": true
}

Code 404 Not Found Error Response

{
	"status": "error",
	"message": "object not found"
}

Update a Single Agent

Update agent information for a single existing SmartCommunicator agent matching the provided filters.

Endpoint

PATCH /{customer_id}/agents/{agent_id}

Header

Authorization (*required): Your authentication token.
Content-Type: application/json

Path Parameters

customer_id (*required): Your account ID.
agent_id (*required): The ID of the agent you want to update. Refers to the value of the key_id query parameter (below). If not provided, user_object_id will be used by default.

Query Parameters

key_id (optional): Field to identify the agent. Allowed values: user_object_id, consistency_id, or id. If not provided, user_object_id will be used by default.

Body Parameters

user_object_id (optional): The unique identifier from the Azure Active Directory for the user.
upn (optional): User Principal Name, typically the agent's email address.
consistency_id (optional): Unique customer-defined identifier.
tenant_id: Azure Active Directory Tenant ID.
brand_name (optional): Any applicable brand name.
name (optional): Display name.
department (optional): The department the agent belongs to.
region (optional): Geographic region where the agent is located.
state (optional): State/province where the agent is located.
district (optional): District or area code.
store (optional): Store identifier, if applicable.
city (optional): User's city.
zip_code (optional): User's zip code.
roles (optional): Include to add or remove role assignments.
- assign (optional): Array of roles to add. Allowed values: member, manager, or admin.
- remove (optional): Array of roles to remove. Allowed values: member, manager, or admin.
phone_number (optional): Include for phone number assignment changes.
- type (*required): The type of number. Allowed values: messaging or supervised.
- value (*required): The E.164 formatted phone number (e.g., +1234567890).
enabled_services (optional): Include to update the application tabs the agent will have access to.
- messages (optional): Access to the Messages tab.
- supervisedInbox (optional): Access to the Supervised Inbox tab.
- calls (optional): Access to the Calls tab.
- sharedInbox (optional): Access to the Shared Inbox tab.
active (optional): Flag to enable or disable the agent's account. When set to false, the agent will not be able to access the app.

Request Example

PATCH /12345678/agents/5f7ca4beb854df0ac6b8bee1

{
	"user_object_id": "17c528d0-dcfa-49bf-bb2b-8955bf377e5a",
	"upn": "agent.email@domain.com",
	"department": "Sales",
	"phone_number": [
		{
			"type": "messaging",
			"value": "+1234567890"
		}
	],
	"enabled_services": {
		"messages": true,
		"supervisedInbox": true,
		"calls": true,
		"sharedInbox": true
	}
}

Response Examples

Code 200 Success Response

{
	"itemIndex": 0,
	"user_object_id": "17c528d0-dcfa-49bf-bb2b-8955bf377e5a",
	"name": "Agent name",
	"upn": "agent.email@domain.com",
	"consistency_id": "customer-defined-id-123",
	"brand_name": "Company name",
	"department": "Sales",
	"region": "US-East",
	"state": "CA",
	"district": "90210",
	"store": "1234",
	"city": "Los Angeles",
	"zip_code": "90210",
	"phone_number": [
		{
			"type": "messaging",
			"value": "+1234567890"
		}
	],
	"roles": ["member", "admin"],
	"enabled_services": {
		"messages": true,
		"supervisedInbox": true,
		"calls": true,
		"sharedInbox": true
	},
	"active": true
}

Code 400 Error Response

{
	"message": "Update failed",
	"errors": [
		{
			"itemIndex": 0,
			"errors": ["Invalid phone number format"]
		}
	]
}

Update Multiple Agents

Bulk update agent information for existing SmartCommunicator agents matching the provided filters.

Endpoint

PATCH /{customer_id}/agents

Header

Authorization (*required): Your authentication token.
Content-Type: application/json

Path Parameters

customer_id (*required): Your account ID.

Query Parameters

continueOnError (optional): If an error occurs will your request continue or stop (defaults to false).

Body Parameters

target (*required): The identifier and value to target the agents you want to update.
- identifier (*required): A piece of data to identify the agents by. Allowed values: user_object_id, consistency_id, or upn.
- value (*required): The value matching your chosen identifier.
updates (*required): The details you want to update.
- user_object_id (optional): The unique identifier from the Azure Active Directory for the user.
- upn (optional): User Principal Name, typically the agent's email address.
- consistency_id (optional): Unique customer-defined identifier.
- tenant_id (optional): Azure Active Directory Tenant ID.
- brand_name (optional): Any applicable brand name.
- name (optional): Display name.
- department (optional): The department the agent belongs to.
- region (optional): Geographic region where the agent is located.
- state (optional): State/province where the agent is located.
- district (optional): District or area code.
- store (optional): Store identifier, if applicable.
- city (optional): User's city.
- zip_code (optional): User's zip code.
- roles (optional): Include to add or remove role assignments.
  - assign (optional): Array of roles to add. Allowed values: member, manager, or admin.
  - remove (optional): Array of roles to remove. Allowed values: member, manager, or admin.
- phone_number (optional): Include for phone number assignment changes.
  - type (*required): The type of number. Allowed values: messaging or supervised.
  - value (*required): The E.164 formatted phone number (e.g., +1234567890).
- enabled_services (optional): Include to update the application tabs the agent will have access to.
  - messages (optional): Access to the Messages tab.
  - supervisedInbox (optional): Access to the Supervised Inbox tab.
  - calls (optional): Access to the Calls tab.
  - sharedInbox (optional): Access to the Shared Inbox tab.
- active (optional): Flag to enable or disable the agent's account. When set to false, the agent will not be able to access the app.

Request Example

[
	{
		"target": {
			"identifier": "user_object_id",
			"value": "17c528d0-dcfa-49bf-bb2b-8955bf377e5a"
		},
		"updates": {
			"user_object_id": "6409c0b8-cfb8-4f18-accf-f44184a299c3",
			"upn": "agent.email@domain.com",
			"department": "Sales",
			"roles": {
				"assign": ["admin"],
				"remove": ["manager"]
		},
		"active": "true",
		"phone_number": [
			{
				"type": "messaging",
				"value": "+1234567890"
			}
		],
		"enabled_services": {
			"messages": true,
			"supervisedInbox": true,
			"calls": true,
			"sharedInbox": true
			}
		}
	}
]

Response Examples

Code 200 Success Response

{
	"message": "Updated successfully",
	"errors": [],
	"result": [
		{
			"itemIndex": 0,
			"user_object_id": "17c528d0-dcfa-49bf-bb2b-8955bf377e5a",
			"name": "Agent name",
			"upn": "agent.email@domain.com",
			"consistency_id": "customer-defined-id-123",
			"brand_name": "Company name",
			"department": "Sales",
			"region": "US-East",
			"state": "CA",
			"district": "90210",
			"store": "1234",
			"city": "Los Angeles",
			"zip_code": "90210",
			"phone_number": [
				{
					"type": "messaging",
					"value": "+1234567890"
				}
			],
			"roles": ["member", "admin"],
			"enabled_services": {
				"messages": true,
				"supervisedInbox": true,
				"calls": true,
				"sharedInbox": true
			},
			"active": true
		}
	]
}

Code 400 Error Response

{
	"message": "Update failed",
	"errors": [
		{
			"itemIndex": 0,
			"errors": ["Invalid phone number format", "User with the specified user_object_id not found"]
		}
	]
}

Offboard a Single Agent

Offboard a single agent from your SmartCommunicator account.

Endpoint

DELETE /{customer_id}/agents/{agent_id}

Header

Authorization (*required): Your authentication token.

Path Parameters

customer_id (*required): Your account ID.
agent_id (*required): The ID of the agent you want to update. Refers to the value of the key_id query parameter (below). If not provided, user_object_id will be used by default.

Query Parameters

key_id (optional): Field to identify the agent. Allowed values: user_object_id, consistency_id, or id. If not provided, user_object_id will be used by default.
deprovisionSupervisedInbox (optional): When true, this will deprovision the offboarding agent's Supervised Inbox and deassign the number from the agent.

Body Parameters

None

Response Examples

Code 200 Success Response

{
	"message": "Agent successfully offboarded"
}

Code 400 Error Response

{
	"message": "Unsuccessful offboarding",
	"errors": ["Agent not found"]
}

Offboard Multiple Agents

Bulk offboard multiple agents from your SmartCommunicator account.

Endpoint

POST /{customer_id}/agents/offboard

Header

Authorization (*required): Your authentication token.
Content-Type: application/json

Path Parameters

customer_id (*required): Your account ID.

Query Parameters

continueOnError (optional): If an error occurs will your request continue or stop (defaults to false).
deprovisionSupervisedInbox (optional): When true, this will deprovision the offboarding agents Supervised Inboxes and deassign the numbers from the agents.

Body Parameters

identifier (*required): Include data to identify the agents you want to offboard. Allowed identifiers:
- user_object_id (optional): Filter results by agentuser_object_id.
- tenant_id (optional): Filter results by agent tenant.
- consistency_id (optional): Filter results by agent consistency_id.
value (*required): Identifier value(s). The values must match the type of identifier chosen above. For example, if your identifier was "user_object_id" the value would be "17c528d0...".

Request Examples

User Object ID Request

[
	{
		"identifier": "user_object_id",
		"value": ["17c528d0-dcfa-49bf-bb2b-8955bf377e5a", "17c528d0-dcfa-49bf-bb2b-8955bf377e5b"]
	}
]

UPN Request

[
	{
		"identifier": "upn",
		"value": ["agent.email@domain.com", "agent2.email@domain.com"]
	}
]

Sample Responses

Code 200 Success Response

{
	"message": "Offboarded successfully",
	"errors": []
}

Code 400 Error Response

{
	"message": "Offboarding failed",
	"errors": [
		{
			"itemIndex": 0,
			"errors": ["Azure Object ID is not registered with SmartCommunicator"]
		}
	]
}

Inbox Management

Create an Inbox

Create a new Shared or Supervised Inbox.

Endpoint

POST /{customer_id}/inboxes

Header

Authorization (*required): Your authentication token.
Content-Type: application/json

Path Parameters

customer_id (*required): Your account ID.

Query Parameters

continueOnError (optional): If an error occurs will your request continue or stop (defaults to false).

Body Parameters

name (*required): The name of your new inbox.
type (*required): The type of inbox you're creating:
- shared: A Shared Inbox, which multiple agents can access.
- supervised: A Supervised Inbox, where the owner's messages are monitored by supervisors.
phone_number (*required): The phone number assigned to the inbox in E.164 format (e.g., +11234567890).
owner (*required for Supervised Inboxes): Information about the owner of the new inbox:
- identifier (*required): Include data to identify the inbox owner. Allowed identifiers:
  - user_object_id: Azure Active Directory Object ID.
  - upn: User Principal Name, typically the user's email address.
  - consistency_id: Custom defined identifier.
- value (*required): Identifier value. The value must match the type of identifier chosen above. For example, if your identifier was "user_object_id" the value would be "17c528d0...".

users (*required): Information about the agent(s) assigned to the new inbox:
- identifier (*required): Include data to identify the inbox user. Allowed identifiers:
  - user_object_id: Azure Active Diretory Object ID.
  - upn: User Principal Name, typically the user's email address.
  - consistency_id: Custom defined identifier.
- value (*required): Identifier value. The value must match the type of identifier chosen above. For example, if your identifier was "user_object_id" the value would be "17c528d0...".

Request Examples

Shared Inbox

[
	{
		"name": "Shared Inbox",
		"type": "shared",
		"phone_number": "+1234567890",
		"users": {
			"identifier": "user_object_id",
			"values": ["17c528d0-dcfa-49bf-bb2b-8955bf377e5a", "17c528d0-dcfa-49bf-bb2b-8955bf377e5b"]
		}
	}
]

Supervised Inbox

[
	{
		"name": "Supervised Inbox",
		"type": "supervised",
		"phone_number": "+1234567890",
		"owner": {
			"identifier": "user_object_id",
			"value": "17c528d0-dcfa-49bf-bb2b-8955bf377e5a"
		},
		"users": {
			"identifier": "user_object_id",
			"values": ["17c528d0-dcfa-49bf-bb2b-8955bf377e5a", "17c528d0-dcfa-49bf-bb2b-8955bf377e5b"]
		}
	}
]

Response Examples

Code 200 Success Response

{
	"message": "Success"
}

Code 400 Error Response

{
	"message": "Creating inboxes failed",
	"errors": [
		{
			"itemIndex": 0,
			"errors": ["Inbox already exists"]
		}
	]
}

Manage Inbox Assignments

Manage the user's assigned to Shared and/or Supervised Inboxes.

Endpoint

POST /{customer_id}/inboxes/assignments

Header

Authorization (*required): Your authentication token.
Content-Type: application/json

Path Parameters

customer_id (*required): Your account ID.

Query Parameters

None

Body Parameters

inbox (*required): Information about the inbox you're updating:
- type (*required): The type of inbox you're updating. Allowed values: shared or supervised.
- identifier (*required): Details to find the inbox you want to update:
  - phone_number: For Shared Inboxes, use the inbox phone number.
  - user_object_id: Only valid for Supervised Inboxes. Use the owner's Azure Active Directory Object ID.
  - consistency_id: Only valid for Supervised Inboxes. Use the owner's custom defined ID.
  - upn: For Supervised Inboxes, use the owner's User Principal Name.
- value (*required): Identifier value. The value must match the type of identifier chosen above. For example, if your identifier was "user_object_id" the value would be "17c528d0...".
agents (*required): Information about the agent(s) to assign or remove.
- identifier (*required): Details to find the agent(s) you want to update:
  - user_object_id: The user's Azure Active Directory Object ID.
  - consistency_id: The user's custom defined ID.
  - upn: The user's User Principal Name, typically email address.
- vlaues (*required): Identifier values. The values must match the type of identifier chosen above.
Operation (*required): The action you want to take on the inbox. Allowed values:
- add: Add the specified agent(s) to the inbox.
- remove: Remove the specified agent(s) from the inbox.

Request Examples

Add Agent to Shared Inbox

[
	{
		"inbox": {
			"type": "shared",
			"identifier": "phone_number",
			"value": "+1234567890"
		},
		"agents": {
			"identifier": "user_object_id",
			"values": ["17c528d0-dcfa-49bf-bb2b-8955bf377e5a"]
		},
		"operation": "add"
	}
]

Remove Supervisor from Supervised Inbox

[
	{
		"inbox": {
			"type": "supervised",
			"identifier": "user_object_id",
			"value": "17c528d0-dcfa-49bf-bb2b-8955bf377e5a"
		},
		"agents": {
			"identifier": "user_object_id",
			"values": ["78dfa17f-d9a9-49ff-b579-d0f946d7c3f1"]
		},
		"operation": "remove"
	}
]

Response Examples

Code 200 Success Response

{
	"message": "Assignment successful",
	"errors": []
}

Code 400 Error Response

{
	"message": "Assignment failed",
	"errors": [
		{
			"itemIndex": 0,
			"errors": ["Target inbox not found"]
		}
	]
}

Phone Number Management

Retrieve Registered Phone Numbers

View your registered phone numbers (with optional filtering).

Endpoint

GET /{customer_id}/numbers

Header

Authorization (*required): Your authentication token.

Path Parameters

customer_id (*required): Your account ID.

Query Parameters

status (optional): Filter by the number status (assigned or active).
- assigned: Numbers that are assigned to agents or inboxes.
- active: Numbers that are unassigned and available for use in SmartCommunicator.
match (optional): Match a phone number substring (1-11 digits). Only numeric characters are allowed.

Body Parameters

None

Response Examples

Code 200 Success Response

[
	{
		"number": "+1234567890",
		"status": "assigned",
		"assignedTo": {
			"name": "Agent name",
			"user_object_id": "d25feff0-cf61-4847-a40c-91eaf3f68de5",
			"upn": "agent@domain.com",
			"consistency_id": "12345"
		}
	}
]