Creating trouble tickets

Minimum creation criteria

The following fields are required to create a trouble ticket:


Field	Description	Note
`title`	A short summary of the issue.
`ticketType`	The category of the issue. Specify a typekey reference to the `TroubleTicketType` typelist.	Valid codes: `dispute`, `processingerror`, `customercomplaint`, `customerquestion`, `reporterror`, `disasterhold`, `automatic`.
`priority`	The urgency of the issue. Specify as a typekey reference to the `Priority` typelist.	Valid codes: `urgent`, `high`, `normal`, `low`.
`detailedDescription`	A description of the issue.
`initialAssignment`	The group (and optionally user) to assign the ticket to on creation.	See Initial assignment.

The following optional fields can also be set at creation:

escalationDate – The date by which the ticket should be escalated if unresolved. Nullable.
targetDate – The target resolution date. Nullable.

Note: In the call to create the trouble ticket, you cannot associate the trouble ticket with the relevant accounts, policies, policy periods, producers, or transactions. You can make additional calls to link trouble tickets with their associated business entities. This is described in Trouble ticket join entities. Role assignments are not currently supported through Cloud API.

Initial assignment

Every trouble ticket must be assigned to a group at creation via the initialAssignment field. The following sub-fields are available:


Field	Description	Note
`groupId`	The ID of the group to assign the ticket to.	Required if `autoAssign` is not provided.
`userId`	The ID of a specific user within the group to assign the ticket to.	Required if `groupId` is provided. The user must be a member of the specified group.
`autoAssign`	Boolean. When `true`, the trouble ticket has an `assignmentStatus` of unassigned.	Required if `groupId` is not provided. Cannot be used if `groupId` is provided.

When assigning to a group only (without a userId), BillingCenter automatically selects an available user from that group based on load factor. The assigned user appears in the assignedUser field of the response.

Example of creating a trouble ticket

The following example creates a trouble ticket with the minimum required fields and assigns it to a group.

Command

POST /billing/v1/trouble-tickets

Request body

{
  "data": {
    "attributes": {
      "detailedDescription": "There is a mismatch between the expected and actual charges on the policy renewal invoice.",
      "initialAssignment": {
        "groupId": "bc:SPPgqvDjRNnbKkSQQKihf"
      },
      "priority": {
        "code": "urgent"
      },
      "ticketType": {
        "code": "dispute"
      },
      "title": "Billing discrepancy on account renewal"
    }
  }
}

Response

{
    "data": {
        "attributes": {
            "assignedByUser": {
                "displayName": "Super User",
                "id": "default_data:1",
                "type": "User",
                "uri": "/admin/v1/users/default_data:1"
            },
            "assignedGroup": {
                "displayName": "Test Group",
                "id": "bc:SPPgqvDjRNnbKkSQQKihf",
                "type": "Group",
                "uri": "/admin/v1/groups/bc:SPPgqvDjRNnbKkSQQKihf"
            },
            "assignedUser": {
                "displayName": "Bruce Baker",
                "id": "bc:SXtDPcN9YuKUkmezeu6Fz",
                "type": "User",
                "uri": "/admin/v1/users/bc:SXtDPcN9YuKUkmezeu6Fz"
            },
            "assignmentDate": "2026-05-11T18:53:57.354Z",
            "assignmentStatus": {
                "code": "assigned",
                "name": "Assigned"
            },
            "createTime": "2026-05-11T18:53:57.354Z",
            "createUser": {
                "displayName": "Super User",
                "id": "default_data:1",
                "type": "User",
                "uri": "/admin/v1/users/default_data:1"
            },
            "detailedDescription": "There is a mismatch between the expected and actual charges on the policy renewal invoice.",
            "escalated": false,
            "id": "bc:SEyIzYv_UUbqo57yO12dV",
            "priority": {
                "code": "urgent",
                "name": "Urgent"
            },
            "ticketStatus": "Open",
            "ticketType": {
                "code": "dispute",
                "name": "Dispute"
            },
            "title": "Billing discrepancy on account renewal",
            "troubleTicketNumber": "1000000012"
        },
        ...
    }
}