Create a new issue

Creates a new issue and its first message. Requires either an account_id or requester information.

The requester, first-message author, and delivery destination are independent:

• requester_id or requester_email identifies the customer the issue is for.

• user_id or contact_id controls who appears as the author of the first message. If neither is provided, the API token's user is the author.

• destination_metadata controls whether and where the first message is delivered. If omitted, the first message is an internal note and no customer is contacted.

The requester and message author may differ because an issue can be created either on behalf of a customer or from a customer-authored message. For example, an agent may open an issue for a requester while authoring the first message themselves, or an integration may record an inbound message authored by the customer.

Account and requester resolution:

• account_id alone creates an issue for that account without setting a requester.

• requester_id uses an existing contact and, when account_id is omitted, uses the contact's primary account if available.

• requester_email without account_id finds or creates a contact and associates an account when possible. requester_name is optional and is used when creating the contact.

• account_id with requester_email finds or creates the contact in the specified account.

• account_id with requester_id requires the contact to belong to the specified account.

• If requester_id and requester_email are both provided, requester_id takes precedence.

Destination requirements:

• If destination_metadata is omitted or destination is internal, the first message remains internal and no customer is contacted. contact_id cannot author an internal note.

• For email, email is required and identifies the configured Pylon sender address, not a recipient. email_ccs and email_bccs are supported only for email.

• For slack, the resolved account must be connected to a Slack channel; the first message is delivered to that channel.

• For in_app_chat, chat_widget_app_id can select the chat widget app used for delivery.

• For sms, from_sms_phone_number_id is required. Also provide requester_id or requester_email for a contact with a phone number.

• For whatsapp, whatsapp_app_id, whatsapp_message_template_name, and whatsapp_message_template_language are required. Also provide requester_id or requester_email for a contact with a phone number.

Create an internal issue without contacting a customer:

{

"account_id": "acc_123",

"title": "Investigate usage spike",

"body_html": "<p>Check recent activity.</p>"

}

Create an issue and email an existing requester:

{

"requester_id": "contact_123",

"title": "Following up",

"body_html": "<p>Here is the requested update.</p>",

"destination_metadata": {

"destination": "email",

"email": "support@example.com"

}
}

Create an issue whose first message is attributed to a customer:

{

"requester_id": "contact_123",

"contact_id": "contact_123",

"title": "Unable to sign in",

"body_html": "<p>I cannot access my account.</p>",

"destination_metadata": {

"destination": "in_app_chat"

}
}

Rate limit: 10 requests per minute