How to Create a Ticket Using BoldDesk API

3 mins read

Updated:

Creating tickets programmatically using the BoldDesk API provides a seamless way to integrate ticket management into your workflows. This guide covers:

API authentication
Structuring ticket creation requests
Handling responses
Managing ticket visibility
Common issues and FAQs

Ensure you have a valid API key generated from your BoldDesk account. Please refer to this article for steps to generate an API key.

Steps to Create a Ticket

When creating tickets via API, please follow the steps below:

1. Authenticate API Request

BoldDesk API uses API key-based authentication to ensure secure access. Please refer to this article for more details on API authentication. Add the API key to the request header as shown below:

curl -X GET "https://{your domain}/api/v1.0/tickets" -H "x-api-key: {API Key}"

Replace {your domain} in the API request URL with your actual BoldDesk domain.
Replace {API Key} with your actual API key.
Ensure the API key has sufficient permissions to access the requested resource.

2. Structure the Ticket Creation Request

To create a ticket, send a POST request to the following endpoint:

https://{your domain}/api/v1.0/tickets

By default, the skipDependencyValidation parameter is set to ‘false’. To bypass field validation, set skipDependencyValidation to ‘true’. If you leave it as false, ensure that the mandatory fields are included in the request payload.

Example JSON payload with required fields:

{
    "brandId": 1,
    "subject": "Subject of the ticket",
    "description": "Description of the ticket",
    "priorityId": 1,
    "isVisibleInCustomerPortal": true,
    "requesterEmailId": "john@example.com"
}

You can also tailor the request by including the required fields according to your specific use case.

If the requester does not exist in your BoldDesk contacts, include requesterName and requesterEmailId in the API payload, and set requesterId to null. This ensures BoldDesk automatically creates the contact and continues with ticket creation. If not done: The API request will fail because the ticket cannot be linked to a valid requester.
BoldDesk’s API does not support adding CC users directly using their email addresses in the cc field. Instead, it requires contact IDs.

Key Parameters:

brandId: The ID of the brand under which the ticket will be created.
subject: The title or summary of the ticket.
description: Detailed information about the issue or request.
priorityId: The priority level of the ticket (For instance, 1 for low, 2 for medium, etc.).
isVisibleInCustomerPortal: Boolean value indicating whether the ticket should be visible in the customer portal.
requesterEmailId: The email address of the requester.

3. Send the Request

Use tools like curl, Postman, or any HTTP client library to send the request. Example using curl:

curl -X POST "https://{your domain}/api/v1.0/tickets?skipDependencyValidation=true" \
-H "Content-Type: application/json" \
-H "x-api-key: {API Key}" \
-d '{
    "brandId": 1,
    "subject": "Subject of the ticket",
    "description": "Description of the ticket",
    "priorityId": 1,
    "isVisibleInCustomerPortal": true,
    "requesterEmailId": "john@example.com"
}'

4. Handle the Response

If the API key is valid and the request is correctly structured, the server will return a success response containing the ticket details. Example response:

{
    "ticketId": 12345,
    "message": "Ticket created successfully."
}

In the event of errors, review the error message and verify that all parameters are correctly provided. Additionally, you may test the BoldDesk REST API using Swagger. Please refer to this article for more insights.

When creating a ticket using the v1/create-ticket/ API, a confirmation email should be sent to the requester. If the email is not received:

Check Email Delivery Status in the BoldDesk portal.
Verify if the email address is suspended, as suspended emails can block ticket creation or email delivery. For further insights on suspended emails, please refer to this article.

How to Change the Ticket Visibility

After a ticket is created, its visibility can be modified via the API from Private to Public or the reverse. To set the ticket visibility to Public, use the developer API and provide the prompt indicated below to update the visibility programmatically.

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

{
  "fields": {
      "isVisibleInCustomerPortal": true
  }
}

To switch the visibility to Private, set the “isVisibleInCustomerPortal” value to false.

Frequently Asked Questions (FAQ)

Q1: Can I create a ticket for a new contact?
Yes. Set requesterId to null and provide requesterName and requesterEmailId.

Q2: Why is my ticket creation failing?
Check if the requester exists or if required fields are missing.

Q3: Can I add CC users via email?
No. BoldDesk requires contact IDs for CC users.

Q4: How do I test the API?
Use Swagger or Postman. Please refer to this article for more insights.

Was this article useful?

Dislike

Comments (0)