BoldDesk API Guide: Assigning Tickets to Agents and Agent Groups

In today’s fast-paced customer support environment, automating ticket assignment is crucial for ensuring swift and efficient handling of requests. One of the simplest and most effective ways to assign a ticket is by using an agent’s Email ID via the REST API. This guide will walk you through the process of assigning a ticket to an agent using their Email ID and provide helpful tips to ensure smooth integration.

Agent Account: Ensure the agent has an active account in the portal with the appropriate permissions to manage tickets. The Email ID provided must already exist in the system as an agent. The system will not automatically create a new user if the email does not exist.

Assigning an Agent to a New Ticket (Create Ticket API)

To assign an agent to a newly created ticket, you can use the Create Ticket API. This API allows you to specify the agent who will be responsible for the ticket through their email ID.

In the payload for creating a ticket, use the following field:

{
  "agentEmailId": "james@example.com"
}

Use POST /api/v1/tickets, for example:

{
  "subject": "New Support Ticket",
  "description": "The customer is facing issues with the product.",
  "agentEmailId": "james@example.com"
}

In this example, a new ticket is created, and the agent with the email james@example.com is automatically assigned to this ticket.

Updating the Assigned Agent for an Existing Ticket (Update Field API)

If you want to update the agent for an existing ticket, you can do so using the Update Ticket API. In this case, the agent is updated by specifying the Email ID within the existing agent field. There’s no need to modify the structure of the field; you simply provide the email ID of the new agent.

For updating an agent on an existing ticket, the API payload looks like this:

{
  "fields": {
    "agentId": "james@example.com"
  }
}

Use PUT /api/v1/tickets/{ticketId}

{
  "fields": {
    "agentId": "james@example.com"
  }
}

In this request, the ticket with the given ticketId is updated, and the new agent with the email james@example.com is assigned to it.

Assigning Tickets to Specific Groups (Create Ticket API)

To streamline ticket routing and ensure tickets reach the right teams, you can assign tickets to specific groups during creation using the groupId parameter in the Create Ticket API. This article explains how to retrieve group IDs and use them in your ticket creation payload.

Step 1: Retrieve Group IDs

Before assigning a ticket to a group, you need to fetch the available group IDs using the List Groups API.

Use the following cURL request in a terminal or API testing tool (like Postman) to fetch the list of groups configured in your BoldDesk account:

curl -X GET "https://{yourdomain}/api/v1/groups?Filter=Admin&Page=1&PerPage=10&RequiresCounts=true&OrderBy=groupName&GroupModuleId=1" \
-H "x-api-key: {yourapikey}"

Replace:

{yourdomain} with your BoldDesk domain.
{yourapikey} with your actual API key.

This request returns a JSON response containing group details, including their names and IDs. You’ll use one of these groupId values in the next step.

Step 2: Create a Ticket and Assign It to a Group

Once you have the group ID, you can assign a ticket to a specific group using the Create Ticket API.

The following sample cURL request demonstrates how to create a ticket and assign it to a group using the groupId field. While this example includes several other fields required for ticket creation, you can modify them based on your use case. The key focus here is on correctly setting the groupId.

Run this request in a terminal or API testing tool (like Postman):

curl -X POST "https://{yourdomain}/api/v1/tickets" \
-H "x-api-key: {yourapikey}" \
-H "Content-Type: application/json" \
-d '{
  "brandId": 1,
  "subject": "Subject of the ticket",
  "categoryId": 2518,
  "isVisibleInCustomerPortal": true,
  "requesterId": 0,
  "description": "Description of the ticket",
  "agentId": 0,
  "groupId": [Your Group ID],
  "attachments": "null",
  "priorityId": 2,
  "dueDate": "2022-02-16T12:38:29.766Z",
  "typeId": 579,
  "tag": null,
  "isSpam": true,
  "requesterEmailId": "James@example.com",
  "requesterName": "James",
  "contactGroupId": 1,
  "phoneNumber": "3324567890",
  "dontAppendOnBehalfOfRequesterMessage": true
}'

Replace:

{yourdomain} with your BoldDesk domain.
{yourapikey} with your actual API key.
[Your Group ID] with the actual ID retrieved from the previous step.

You can customize other fields such as subject, priorityId, or requesterEmailId to suit your ticketing needs. However, ensure the groupId is valid and corresponds to a group configured in your BoldDesk account. Invalid IDs may result in errors or unassigned tickets.

By integrating the groupId into your ticket creation logic, you can automatically route tickets to the correct team.

FAQ

1. Can I assign a ticket to an agent who is not in BoldDesk?
No. The agent must have an active BoldDesk account. The API does not create new users automatically.

2. What happens if I provide an invalid groupId?
The ticket will not be assigned to any group, and you may receive an error response.

3. Can I assign both an agent and a group in the same API call?
Yes. Include both agentEmailId and groupId in the Create Ticket API payload.

4. Is it possible to automate ticket assignment rules without API?
Yes. BoldDesk offers automation rules in the admin panel for assigning tickets based on conditions.

5. Does BoldDesk support bulk ticket assignment via API?
Currently, bulk assignment is not supported in a single API call. You need to update tickets individually.

BoldDesk API Authentication
How to Generate a BoldDesk API Key?
How to Test the BoldDesk Rest API Using Swagger

Was this article useful?

Dislike

Comments (0)