GuidesAPI EndpointsKnowledge BaseSupportTalkdesk WebsiteMarketplaceDiscussionsDevelopers Blog
Guides

Agent Management

Suggest Edits

Agent Management

The Agent Management endpoints allow you to retrieve and manage detailed information about your workforce, including personal details and system roles.

📘

API Authentication

All requests require the following headers:

  • X-Api-Version: 2.0
  • Ocp-Apim-Subscription-Key: YOUR_API_KEY

Get All Agents

GET /Advanced Dialer/api/agent

Retrieves a collection of agents using the AgentBase model with optional search filtering.

Query Parameters

ParameterTypeRequiredDescription
searchTermstringNoFilter agents by search term (name/username).

Example Request

curl --request GET \
     --url '[https://api.talkdeskapp.com/Advanced%20Dialer/api/agent?searchTerm=john](https://api.talkdeskapp.com/Advanced%20Dialer/api/agent?searchTerm=john)' \
     --header 'Ocp-Apim-Subscription-Key: YOUR_API_KEY' \
     --header 'X-Api-Version: 2.0'

Response Example

{
  "statusCode": 0,
  "message": null,
  "payload": [
    {
      "id": 1001,
      "username": "john.smith",
      "firstName": "John",
      "lastName": "Smith",
      "isActive": true,
      "title": "Senior Agent"
    }
  ]
}

Get Single Agent

GET /Advanced Dialer/api/agent/{userId}

Returns basic AgentBase data for a specific agent.

Path Parameters

ParameterTypeDescription
userIdintegerThe unique identifier of the agent.

Example Request

curl --request GET \
     --url '[https://api.talkdeskapp.com/Advanced%20Dialer/api/agent/1001](https://api.talkdeskapp.com/Advanced%20Dialer/api/agent/1001)' \
     --header 'Ocp-Apim-Subscription-Key: YOUR_API_KEY' \
     --header 'X-Api-Version: 2.0'

Get Agent Details

GET /Advanced Dialer/api/agent/{userId}/details

Returns comprehensive AgentDetailed information, including personal information, team assignments, and address details.

Path Parameters

ParameterTypeDescription
userIdintegerThe unique identifier of the agent.

Response Example

{
  "statusCode": 0,
  "message": null,
  "payload": {
    "id": 1001,
    "username": "john.smith",
    "title": "Senior Agent",
    "userInformation": {
      "homeTeam": { "id": 5, "name": "Sales Team" },
      "role": { "id": 2, "name": "Agent" },
      "teamLeader": "sarah.johnson"
    },
    "personalInformation": {
      "email": "[email protected]",
      "mobile": "+1-555-0123",
      "address": {
        "addressLine1": "456 Oak Avenue",
        "postcode": "54321"
      }
    }
  }
}

Update Agent Details

PUT /Advanced Dialer/api/agent/{userId}/details

Updates specific fields for an agent. This endpoint supports partial updates.

Request Body

FieldTypeDescription
titlestringNew job title for the agent.
personalInformationobjectNested object containing mobile and address updates.

Example Request

curl --request PUT \
     --url '[https://api.talkdeskapp.com/Advanced%20Dialer/api/agent/1001/details](https://api.talkdeskapp.com/Advanced%20Dialer/api/agent/1001/details)' \
     --header 'Content-Type: application/json' \
     --header 'Ocp-Apim-Subscription-Key: YOUR_API_KEY' \
     --header 'X-Api-Version: 2.0' \
     --data '
{
  "title": "Senior Customer Success Agent",
  "personalInformation": {
    "mobile": "+1-555-9999",
    "address": {
      "addressLine1": "789 New Street",
      "postcode": "67890"
    }
  }
}'

Create Agent

PUT /Advanced Dialer/api/agent

Creates a new agent record with complete profile information, including team assignments, personal details, attributes, and skills.

Request Body

FieldTypeDescription
usernamestringRequired. Unique identifier for the agent login.
passwordstringRequired. The secure password for the new account.
userInformationobjectDetails regarding team ID and system roles.
personalInformationobjectContact details and physical address.
skillsarrayList of skills and ability levels (0-100).

Example Request

curl --request PUT \
     --url 'https://api.talkdeskapp.com/Advanced%20Dialer/api/agent' \
     --header 'Content-Type: application/json' \
     --header 'Ocp-Apim-Subscription-Key: YOUR_API_KEY' \
     --header 'X-Api-Version: 2.0' \
     --data '
{
  "username": "new.agent",
  "firstName": "Jane",
  "lastName": "Doe",
  "title": "Agent",
  "password": "SecurePassword123!",
  "isActive": true,
  "dateOfBirth": "1990-03-20T00:00:00Z",
  "userInformation": {
    "homeTeam": { "id": 5, "name": "Sales Team" },
    "role": { "id": 2, "name": "Agent" },
    "teamLeader": "sarah.johnson",
    "isActiveDirectory": false
  },
  "personalInformation": {
    "email": "[email protected]",
    "mobile": "+1-555-0123",
    "address": {
      "addressLine1": "123 Main Street",
      "postcode": "12345"
    }
  },
  "attributes": [
    { "name": "Department", "value": "Sales" }
  ],
  "skills": [
    { "skillId": 1, "name": "Customer Service", "ability": 85 }
  ]
}'

Response Example

{
  "statusCode": 0,
  "message": "Agent created successfully",
  "payload": {
    "id": 1003,
    "username": "new.agent"
  }
}

Updated about 2 hours ago