Managing Agents Using SmartCommunicatorâ„¢ APIs
With IntelePeer SmartCommunicator APIs, you can manage your agents: view agents collectively or individually, onboard or offboard agents, and update current agents.
Base URL
All of the following endpoints share the same base URL:
atmosphere-api.intelepeer.com
Example
GET https://atmosphere-api.intelepeer.com/rest/v1/smartcomm/{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 Payload Example
{
"username": "someone@yourmail.com",
"password": "enter_password_here"
}
Token Example
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
.
SmartCommunicator APIs
Click the following API titles to view the parameters and code samples associated with each endpoint.

Add a new SmartCommunicator agent to your account. Required fields in the request body include the following:
-
user_object_id
-
tenant_id
-
phone_number
Note: You can add the consistency_id and upn later by using the Update Agent endpoint with the key_id parameter..
Method and Endpoint
POST {base URL}/rest/v1/smartcomm/{customer_id}/agents
Header
-
Accept: application/json
-
Authorization: JSON Web Token
-
Content-Type: application/json
Field | Type | Description |
---|---|---|
Accept |
String |
application/json |
Authorization |
String |
JSON Web Token (JWT) |
Content-Type |
String |
application/json |
Parameters
Field | Type | Description |
---|---|---|
customer_id(required) |
Integer |
Your customer account ID To find the customer_id number for your account, in the IntelePeer Customer Portal, in the left column, click Enterprise Settings > SFTP Settings > Customer ID Note: Viewing this page requires administration privileges. |
user_object_id(required) |
String |
Active Directory Object ID of the agemt |
tenant_id(required) |
String |
Active Directory Tenant ID of the agent |
phone_number(required) |
String |
Phone number assigned to the agent |
consistency_id (optional) |
String |
ID that identifies the user across different tenants |
upn (optional) |
String |
User Principal Name; example: jane.doe@company.com |
Request Example
{
"user_object_id": "f544917c-a2b7-4d99-8088-c4340dc854c1",
"tenant_id": "f67effe8-6d18-5c8f-df44-47c58b508420",
"phone_number": "+18680831601"
}
Response Examples and Schema
Code 200 Response
{
"data": {
"message": "Onboarded Successfully"
},
"error": null
Code 400 Response
Response code 400 returns an error that the MSDS Consistency GUID already exists.
{
"message": "MSDS Consistency GUID already exists",
"status": 400
}
Response code 400 returns an error that the Azure Object ID exists with a different MSDS Consistency GUID
{
"message": "Azure Object ID exists with a different MSDS Consistency GUID",
"status": 400
}
Response code 400 returns an error that the Tenant ID is not registered with SmartCommunicator.
{
"message": "Tenant ID is not registered with SmartCommunicator",
"status": 400
}
Response code 400 returns an error that the TN is already registered with a different MSDS Consistency GUID.
{
"message": "TN is already registered with a different MSDS Consistency GUID",
"status": 400
}
Response code 400 returns an error that the TN exists with the same MSDS Consistency GUID.
{
"message": "TN exists with the same MSDS Consistency GUID",
"status": 400
}
Response code 400 returns an error that the UPN is already registered with a different MSDS Consistency GUID.
{
"message": "UPN is already registered with a different MSDS Consistency GUID",
"status": 400
}
Response code 400 returns an error that the UPN exists with the same MSDS Consistency GUID.
{
"message": "UPN exists with the same MSDS Consistency GUID",
"status": 400
}
Response code 400 returns an error that the Azure Object ID already exists.
{
"message": "Azure Object ID already exists",
"status": 400
}
Response code 400 returns an error that the Tenant ID is not registered with SmartCommunicator.
{
"message": "Tenant ID is not registered with SmartCommunicator",
"status": 400
}
Response code 400 returns an error that the TN is already registered with a different Azure Object ID
{
"message": "TN is already registered with a different Azure Object ID",
"status": 400
}
Response code 400 returns an error that the TN exists with the same Azure Object ID.
{
"message": "TN exists with the same Azure Object ID",
"status": 400
}
Response code 400 returns an error that the UPN is already registered with a different Azure Object ID.
{
"message": "UPN is already registered with a different Azure Object ID",
"status": 400
}
Response code 400 returns an error that the UPN exists with the same Azure Object ID.
{
"message": "UPN exists with the same Azure Object ID",
"status": 400
}
Response code 400 returns an error that the Tenant ID is not registered with SmartCommunicator.
{
"message": "Tenant ID is not registered with SmartCommunicator",
"status": 400
}
Response code 400 returns an error that the TN is not part of the list of numbers that are already 10DLC registered.
{
"message": "TN is not part of the list of numbers that are already 10DLC registered",
"status": 400
}
Response code 400 returns an error that the TN is already registered with a different UPN.
{
"message": "TN is already registered with a different UPN",
"status": 400
}
Response code 400 returns an error that the UPN is already registered with SmartCommunicator.
{
"message": "UPN is already registered with SmartCommunicator",
"status": 400
}

Use these APIs to view either all current agents or an individual agent.
Methods and Endpoints
[All agents] GET {base URL}/rest/v1/smartcomm/{customer_id}/agents
[An individual agent] GET {base URL}/rest/v1/smartcomm/{customer_id}/agents/{agent_id}
Header
-
Accept: application/json
-
Authorization: JSON Web Token
-
Content-Type: application/json
Field | Type | Description |
---|---|---|
Accept |
String |
application/json |
Authorization |
String |
JSON Web Token (JWT) |
Content-Type |
String |
application/json |

Parameters
Field | Type | Description |
---|---|---|
customer_id (required) |
Integer | ID of the customer |
Response Examples and Schema
Success 200
Field | Type | Description |
---|---|---|
customer_id |
Integer | ID of the customer |
user_object_id |
String |
Active Directory Object ID of the agemt |
tenant_id |
String |
Active Directory Tenant ID of the agent |
consistency_id |
String |
MS DS Consistency Guid that identifies the user across different tenants |
phone_number |
String |
Phone number assigned to the agent |
status |
String |
Choices are active, (for onboarded agents), and offboarded (for agents that have been deactivated/offboarded) |
Success Response
HTTP/1.1 200 Agent Information
{
"data": [
{
"user_object_id": "e2f19e0a-0490-41f4-8509-44a3390ae0b6",
"tenant_id": "f67efc8f-df44-47c5-8b50-fe86d1858420",
"phone_number": "+13132095887",
"status": "active"
},
{
"user_object_id": "e2f19e0a-0490-41f4-8509-44a3390ae0b7",
"tenant_id": "f67efc8f-df44-47c5-8b50-fe86d1858420",
"phone_number": "+15127178432",
"status": "active"
},
{
"user_object_id": "f5449088-5c43-40dc-854c-17ca2b74d983",
"tenant_id": "f67efc8f-df44-47c5-8b50-fe86d1858420",
"phone_number": "+15727982188",
"status": "active"
},
{
"user_object_id": "f5449088-5c43-40dc-854c-17ca2b74d984",
"tenant_id": "f67efc8f-df44-47c5-8b50-fe86d1858420",
"phone_number": "+15727982189",
"status": "active"
}
],
"error": null
}
Errors
Field | Type | Description |
---|---|---|
code |
Integer | Error code |
error |
String |
Error description |
Code 404 Response
Response code 404: No Recods Found
HTTP/1.1 404 No Records Found
{
"requestId": "27a1a46d-384f-4f15-b89e-c24697d90163",
"message": "No Records found for any of the parameters provided"
}

Parameters
Field | Type | Description |
---|---|---|
customer_id (required) |
Integer | ID of the customer |
agent_id(required) |
String |
ID of the agent |
key_id |
String |
Field the agent_id path param is referencing to; default: user_object_id Available values: user_object_id, agent_id, upn, phone_number, and consistency_id |
Response Examples and Schema
Success 200
Field | Type | Description |
---|---|---|
consistency_id |
String |
ID that identifies the user across different tenants |
user_object_id |
String |
Active Directory Object ID of the agemt |
tenant_id |
String |
Active Directory Tenant ID of the agent |
phone_number |
String |
Phone number assigned to the agent; e.164 format; for example, +14835551212 |
upn |
String |
User Principal Name; derived from your Microsoft Teams account |
status |
String |
Choices are active, (for onboarded agents), and orphaned (for agents that have been deactivated/offboarded) |
Success Response
HTTP/1.1 200 Agent Information
{
"user_object_id": "f5449088-5c43-40dc-854c-17ca2b74d998",
"tenant_id": "f67efc8f-df44-47c5-8b50-fe86d1858420",
"phone_number": "+15727982113",
"status": "active"
}
Errors
Field | Type | Description |
---|---|---|
code |
Integer | Error code |
error |
String |
Error description |
Code 404 Response
Response code 404: No Matching Objects Found
HTTP/1.1 404 No Matching Objects Found
{
"requestId": "27a1a46d-384f-4f15-b89e-c24697d90163",
"message": "No Records found for any of the parameters provided"
}

Update agent information for an existing SmartCommunicator agent matching the provided filters. If more than one agent matches the provided filters, or any of the updates are invalid, an error is returned.
You can make changes to the following parameters:
-
consistency_id
-
user_object_id
-
phone_number
-
upn
Note: You can add the consistency_id and upn if you didn't include them during the initial onboarding.
Endpoint
PATCH {Base URL}/rest/v1/smartcomm/{customer_id}/agents/{agent_id}
Parameters
Field | Type | Description |
---|---|---|
customer_id (required) |
Integer |
ID of the customer |
agent_id (required) |
String |
ID of the agent to be updated |
key_id |
String |
Field the agent_id path param is referencing; defaults to user_object_id Available values: user_object_id, agent_id, consistency_id |
Sample Request
PATCH {Base URL}/rest/v1/smartcomm/12345678/agents/5f7ca4beb854df0ac6b8bee1
{
"phone_number": "+14715551212",
"upn": "string",
"user_object_id": "string",
"tenant_id": "string",
"consistency_id": "string",
"transfer_data": true
}
Sample Responses
Code 200 Response
{
"consistency_id": "string",
"user_object_id": "string",
"tenant_id": "string",
"phone_number": "+15426987505",
"upn": "string",
"status": "active"
}
Code 400 Response
Response code 400 returns an error that shows the undate was unsuccessful.
{
"status": "error",
"message": "Phone number is not registered with SmartCommunicator"
}
Code 404 Response
Response code 404 returns a message that no matching object was found.
{
"requestId": "c2469727-a1a4-6d38-4f4f-15b89ed90163",
"message": "Agent not found"
}

Offboard / delete an agent from your account.
Endpoint
DELETE {Base URL}/rest/v1/smartcomm/{customer_id}/agents/{agent_id}
Parameters
Field | Type | Description |
---|---|---|
customer_id (required) |
Integer |
ID of the customer |
agent_id (required) |
String |
ID of the agent to be updated |
key_id |
String |
Field the agent_id path param is referencing; defaults to user_object_id Available values: user_object_id, agent_id, consistency_id |
Sample Responses
Code 200 Response
Response code 200 returns a status of ok if the offboarding was successful.
{
"status": "ok"
}
Code 400 Response
Response code 401 returns an error if the offboarding was unsuccessful.
{
"status": "error",
"message": "Azure Object ID is not registered with SmartCommunicator"
}
Code 404 Response
Response code 404 returns a message that the agent was not found.
{
"requestId": "90163d27-a1a4-6d38-4f51-c2469790163d",
"message": "Agent not found"
}