--- 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. Requester fields identify the customer, user_id or contact_id identifies the first-message author, and destination_metadata controls delivery. These choices are independent. If destination_metadata is omitted, the first message is an internal note and no customer is contacted. See the request-field descriptions and examples for destination-specific requirements. **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. When destination is "customer_portal", this is set to true and cannot be false. - `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, make it available only in the customer portal, or keep it internal. If an external destination is specified, a message with the issue's BodyHTML will be delivered to the requester. The `customer_portal` destination requires Customer Portal to be enabled and creates a customer-visible message without external delivery. 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' | 'customer_portal' | 'internal' | 'sms' | 'whatsapp', required — The destination type of the issue. Can be "email", "slack", "in_app_chat", "customer_portal", "sms", "whatsapp", or "internal". Required when destination_metadata is provided. Use "customer_portal" for a customer-visible issue with no external delivery; Customer Portal must be enabled for the organization. To create an internal issue, omit destination_metadata or set this field to "internal". - `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` 'urgent' | 'high' | 'medium' | 'low' — 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. - `title` string — The title 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. - `is_issue_group` boolean — Whether this issue is an issue group. - `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. - `title` string — The title 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' | 'customer_portal' | 'email' | 'manual' | 'form' | 'discord' | 'whatsapp' | 'sms' | 'telegram' | 'phone' — The source of the issue. - `state` string — The state of the issue. Standard values are `new`, `waiting_on_you`, `waiting_on_customer`, `on_hold`, and `closed`; custom status slugs are also supported. - `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. - `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/revisions/a7231589e927/schema)