How to Manage Requester Emails When Creating Tickets Using the BoldDesk API
When creating tickets via the BoldDesk REST API, it’s important to understand how the system handles requesters based on their email address. This article explains what happens when the email exists, when it doesn’t, and what fields you must include to avoid errors.
Scenario 1: Email Exists in BoldDesk
If the requesterEmailId you provide is already associated with an existing contact:
- The ticket is automatically linked to that contact.
- The User ID is retrieved internally by BoldDesk.
- You do not need to provide requesterId explicitly.
Example Payload
{
"brandId": 1,
"subject": "Issue with login",
"description": "Unable to log in to the portal.",
"priorityId": 2,
"isVisibleInCustomerPortal": true,
"requesterEmailId": "erick@xyzcompany.com"
}
Scenario 2: Email Does Not Exist in BoldDesk
If the requester does not exist in your BoldDesk contacts:
- You must include requesterName and requesterEmailId in the payload.
- Set requesterId to null.
- This ensures BoldDesk creates the contact automatically and continues ticket creation.
- If you do not include these fields:
- The API request will fail because the ticket cannot be linked to a valid requester.
Example Payload
{
"brandId": 1,
"subject": "New user inquiry",
"description": "First-time user needs assistance.",
"priorityId": 1,
"isVisibleInCustomerPortal": true,
"requesterName": "Jane Smith",
"requesterEmailId": "jane.smith@example.com",
"requesterId": null
}
API Endpoint
POST https://{your-domain}/api/v1.0/tickets
Key Parameters
- brandId: ID of the brand under which the ticket is created.
- subject: Ticket title.
- description: Detailed issue description.
- priorityId: Priority level (1 = Low, 2 = Medium, etc.).
- isVisibleInCustomerPortal: Boolean to show ticket in the portal.
- requesterEmailId: Email of the requester.
- requesterName: Required only if the requester does not exist.
- requesterId: Set to null when creating a new contact.
FAQ
-
Can I create a ticket without providing requesterEmailId via API?
No. requesterEmailId is mandatory because BoldDesk uses it to identify or create the requester contact. Without it, the API cannot link the ticket to a user. -
What happens if I provide both requesterId and requesterEmailId in the API payload?
If both are provided, BoldDesk prioritizes requesterId. However, it’s best practice to provide only one to avoid conflicts. -
Can I use an email alias or distribution list as requesterEmailId in the API payload?
Yes, but the ticket will be linked to that alias as a single contact. If you need individual tracking, use personal email addresses. -
How do I handle duplicate contacts with the same email address?
BoldDesk uses the email address as the unique identifier for contacts.
- When creating a contact manually: You cannot add a contact with an email that already exists; BoldDesk will show an error.
- When importing contacts: You can choose to skip duplicates or overwrite existing contacts with new data.
-
Is it possible to create a ticket without showing it in the Customer Portal via API?
Yes. Set isVisibleInCustomerPortal to false in the payload to hide the ticket from the requester’s portal view. -
What happens if I omit brandId in the payload?
The API will return an error because brandId is required to associate the ticket with the correct brand. -
Can I attach files when creating a ticket via API?
Yes. You can include attachments by using the file upload endpoint and referencing the attachment IDs in the ticket creation payload. -
How do I set the ticket type or category during creation via API?
Include typeId and categoryId in the payload. These IDs can be retrieved from your BoldDesk settings via the respective API endpoints.
