Managing Agents Using SmartCommunicator™ APIs

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	ID of the customer
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

 

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"
}