--- title: "Create a new issue" method: POST path: "/issues" tags: ["issues"] --- # Create a new issue `POST /issues` 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: ```json { "account_id": "acc_123", "title": "Investigate usage spike", "body_html": "

Check recent activity.

" } ``` Create an issue and email an existing requester: ```json { "requester_id": "contact_123", "title": "Following up", "body_html": "

Here is the requested update.

", "destination_metadata": { "destination": "email", "email": "support@example.com" } } ``` Create an issue whose first message is attributed to a customer: ```json { "requester_id": "contact_123", "contact_id": "contact_123", "title": "Unable to sign in", "body_html": "

I cannot access my account.

", "destination_metadata": { "destination": "in_app_chat" } } ``` **Rate limit:** 10 requests per minute ## Request body - CreateIssueRequest - `account_id` string — The account that this issue belongs to. If requester_id is also provided, the requester must belong to this account. If requester_email is provided, the contact is found or created in this account. - `assignee_id` string — The user the issue should be assigned to. - `attachment_urls` string[] — URLs of files to attach to the issue's first message. - `author_unverified` boolean — Whether the requester's identity has NOT been verified. Defaults to false (verified). - `body_html` string, required — The HTML content of the body of the issue. - `contact_id` string — The contact to attribute the first message to. This controls the message author, not the issue requester. Makes the message appear as a customer message rather than an internal note. Only one of user_id or contact_id can be provided. Requires destination_metadata. - `created_at` string — Timestamp of when the issue was created. If not specified, the current time will be used. (RFC3339) - `custom_fields` CustomFieldValue[] — An array of custom fields to be used on this issue. - `slug` string — The slug of the custom field. - `value` string — The value of the custom field. Only to be used for single-valued custom fields. If unset, the custom field will be unset. If the custom field is a select field, the value must be the select option slug, which you can find from the GET /custom-fields endpoint. If the custom field is a relationship field, the value must be the related object ID. - `values` string[] — The values of the custom field. Only to be used for multi-valued custom fields (ex. multiselect). If unset, the custom field will be unset. If the custom field is a multiselect field, the values must be the select option slugs which you can find from the GET /custom-fields endpoint. - `customer_portal_visible` boolean — Whether the issue should be visible in the customer portal. - `destination_metadata` DestinationMetadata — Specifies if/how communication will be delivered to the customer. You can configure the issue to contact the requester via email, Slack, in-app chat, SMS, WhatsApp, or not at all. If a destination other than `internal` is specified, a message with the issue's BodyHTML will be delivered to the requester. To avoid contacting the requester, omit destination_metadata from the create-issue request or specify the `internal` destination. If destination_metadata is provided, destination is required. - `chat_widget_app_id` string — The ID of the chat widget app to use for in-app chat. - `destination` 'slack' | 'email' | 'in_app_chat' | 'internal' | 'sms' | 'whatsapp', required — The destination type of the issue. Can be "email", "slack", "in_app_chat", "sms", "whatsapp", or "internal". Required when destination_metadata is provided. To create an internal issue, omit destination_metadata or set this field to "internal". `slack`: Deliver to the issue's account's Slack channel. `email`: Deliver messages to the issue requester via email. `in_app_chat`: Deliver messages to the issue requester via in-app chat. `internal`: Keep the issue internal and don't contact the requester at all. `sms`: Deliver messages to the issue requester via SMS. `whatsapp`: Deliver messages to the issue requester via WhatsApp. - `email` string — The email that emails to the requester will be sent from. You must configure an email app in Pylon with this address. - `email_bccs` string[] — Emails that will be BCCed on emails to the requester. - `email_ccs` string[] — Emails that will be CCed on emails to the requester. - `from_sms_phone_number_id` string — The ID of the Telnyx phone number to send SMS from. Required if destination is "sms". - `whatsapp_app_id` string — The ID of the WhatsApp app to send messages from. Required if destination is "whatsapp". - `whatsapp_message_template_language` string — The language of the WhatsApp message template to use. Required if destination is "whatsapp". - `whatsapp_message_template_name` string — The name of the WhatsApp message template to use. Required if destination is "whatsapp". - `priority` string — The priority of the issue. Can be one of: urgent, high, medium, or low. - `requester_avatar_url` string — The URL of an avatar of the requester. - `requester_email` string — The email of the customer this issue is for. Used when requester_id is omitted. If no matching contact exists, one will be created. When account_id is provided, the contact is found or created in that account. This does not control who authored the first message. - `requester_id` string — The customer this issue is for. Sets the "Requester" shown in the issue sidebar but does not control who authored the first message. If account_id is omitted, the requester's primary account is used when available. If requester_email is also provided, requester_id takes precedence. - `requester_name` string — The optional full name of the requester. Used when creating a new contact via requester_email. - `tags` string[] — An array of strings to use as tags on this issue. If provided, the issue tags will be updated to the given tags. - `team_id` string — The ID of the team this issue should be assigned to. - `title` string, required — The title of the issue. - `user_id` string — The internal Pylon user to attribute the first message to. This does not assign the user as the requester. Only one of user_id or contact_id can be provided. If neither is set, the API token's user is used. ## Response `200` - CreateIssueResponseBody - `data` Issue - `account` MiniAccount - `external_ids` ExternalID[] — External IDs associated with the account. - `external_id` string — The external ID. Must be unique per object type (ex. account). - `label` string — The label of the external ID. Must be unique per object. - `id` string — The ID of the account. - `active_time_by_user` ActiveTimeByUser[] — Active time spent on the issue broken down per user, if any. - `active_time_seconds` integer — The user's active time on the issue in seconds. - `business_hours_active_time_seconds` integer — The user's business-hours active time on the issue in seconds. - `user_id` string — The ID of the user who spent the time. - `active_time_seconds` integer — The total active time spent on the issue in seconds, if any. Equals the sum of the per-user active time. - `assignee` MiniUser - `email` string — The email of the user. - `id` string — The ID of the user. - `attachment_urls` string[] — The attachment URLs attached to this issue, if any. - `author_unverified` boolean — Whether any message on the issue has an unverified author identity. True if any message author's identity has NOT been verified (e.g., from public forms). - `body_html` string — The body of the issue in HTML format. - `business_hours_active_time_seconds` integer — The total business-hours active time spent on the issue in seconds, if any. Equals the sum of the per-user business-hours active time. - `business_hours_first_response_seconds` integer — The business hours time in seconds it took for the first response to the issue, if any. - `business_hours_resolution_seconds` integer — The business hours time in seconds it took for the issue to be resolved, if any. - `business_hours_time_in_status_seconds` object — A map of status slug to the business hours time in seconds the issue has spent in that status. Includes both base statuses (e.g. "new", "waiting_on_you") and custom statuses. - `chat_widget_info` IssueChatWidgetInfo - `page_url` string — The URL of the page that the user was on when they started the chat widget issue. - `child_issues` MiniIssue[] — The child issues in this group, if this issue is an issue group. - `id` string — The ID of the issue. - `number` integer — The number of the issue. - `created_at` string — The time the issue was created. - `csat_responses` CSATResponse[] — The CSAT responses of the issue, if any. - `comment` string — The comment of the CSAT response. - `score` integer — The score of the CSAT response. - `custom_fields` object — Custom field values associated with the issue. - `customer_portal_visible` boolean — Whether the issue is visible in the customer portal. - `external_issues` ExternalIssue[] — The external issues associated with the issue, if any. - `external_id` string — The external ID of the external issue. Jira: ID of the issue (autoincrementing number from 10000). GitHub: Owner/Repo/IssueID. Linear: ID of the issue (UUID). Asana: ID of the task (Long number). - `link` string — Link to the product issue. - `source` string — The source of the external issue. - `first_response_breach_time` string — The time by which the issue's first response SLA will breach, if any. Only present for issues with an active first response SLA. - `first_response_seconds` integer — The time in seconds it took for the first response to the issue, if any. - `first_response_time` string — The time of the first response to the issue, if any. - `id` string — The ID of the issue. - `latest_message_time` string — The time of the latest message in the issue. - `link` string — The link to the issue in Pylon. - `number` integer — The number of the issue. - `number_of_touches` integer — The number of times the issue has been touched. - `parent_issue_group` MiniIssue - `id` string — The ID of the issue. - `number` integer — The number of the issue. - `requester` MiniContact - `email` string — The email of the contact. - `id` string — The ID of the contact. - `resolution_breach_time` string — The time by which the issue's resolution SLA will breach, if any. Only present for open issues with an active resolution SLA. - `resolution_seconds` integer — The time in seconds it took for the issue to be resolved, if any. - `resolution_time` string — The time of the resolution of the issue, if any. - `slack` SlackInfo - `channel_id` string — The Slack channel ID associated with the issue. - `message_ts` string — The root message ID of slack message that started issue. - `workspace_id` string — The Slack workspace ID associated with the issue. - `snoozed_until_time` string — The time the issue was snoozed until in RFC3339 format, if any. - `source` 'slack' | 'microsoft_teams' | 'microsoft_teams_chat' | 'chat_widget' | 'email' | 'manual' | 'form' | 'discord' | 'whatsapp' | 'sms' | 'telegram' | 'phone' — The source of the issue. - `state` string — The state of the issue. This could be one of `["new", "waiting_on_you", "waiting_on_customer", "on_hold", "closed"] or a custom status slug. - `tags` string[] — Tags associated with the issue. - `team` MiniTeam - `id` string — The ID of the team. - `team_slas` TeamSLA[] — The team-scoped SLAs on the issue, if any. One entry per team, mirroring the issue-level first response and resolution SLA fields. - `first_response` SLATimes - `breach_time` string — The time at which it breaches (or has breached), if any. - `business_hours_seconds` integer — The elapsed business-hours time in seconds, if any. - `seconds` integer — The elapsed time in seconds, if any. - `time` string — The time it was reached, if any. - `resolution` SLATimes - `breach_time` string — The time at which it breaches (or has breached), if any. - `business_hours_seconds` integer — The elapsed business-hours time in seconds, if any. - `seconds` integer — The elapsed time in seconds, if any. - `time` string — The time it was reached, if any. - `team_id` string — The ID of the team these are scoped to. - `time_in_status_seconds` object — A map of status slug to the time in seconds the issue has spent in that status. Includes both base statuses (e.g. "new", "waiting_on_you") and custom statuses. - `title` string — The title of the issue. - `type` 'conversation' | 'ticket' — The type of the issue. `conversation`: A conversation. `ticket`: A support ticket. - `updated_at` string — The time the issue was last updated. - `request_id` string — The request ID for tracking. ## Other responses - `400` — The request was invalid or could not be completed. - `404` - `500` — An unexpected internal error occurred. --- [API](https://skmtc.net/usepylon/apis/pylon-api.md) · [All operations](https://skmtc.net/usepylon/apis/pylon-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/usepylon/pylon-api/versions/999c51740b4e/schema)