---
title: "Import an issue"
method: POST
path: "/import/issues"
tags: ["import"]
---

# Import an issue

`POST /import/issues`

Imports an issue with its messages and metadata. At least one message is required.

**Rate limit:** 20 requests per minute

## Request body

- ImportIssueRequest
  - `account_id` string — AccountID that the issue should belong to.
  - `assignee_id` string — UserID that the issue should be assigned to.
  - `attachment_urls` string[] — An array of attachment URLs to attach to this issue.
  - `created_at` string — CreatedAt is the time the issue was created (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.
  - `external_issues` ImportExternalIssue[] — External issues to link to this issue.
    - `external_issue_id` string, required — The ID of the external issue in the source system.
    - `source` string, required — The source system of the external issue (e.g., "linear", "asana", "jira", "github").
  - `external_refs` ImportIssueExternalRefs
    - `intercom_conversation_id` string — The Intercom conversation ID associated with this issue, if any.
    - `zendesk_ticket_id` string — The Zendesk ticket ID associated with this issue, if any.
  - `first_response_time` string — FirstResponseTime is the time the issue was first responded to (RFC3339).
  - `issue_number` integer — An optional issue number to preserve from the platform the issue is being imported from. Usually, do not set this field. Pylon normally assigns its own auto-incrementing ticket numbers. Use it only for customers who require their historical ticket numbers to be preserved. When set, it must be positive and lower than the organization's current ticket number counter.
  - `messages` ImportIssueMessage[], required — Messages to be imported for this issue. At least one message is required.
    - `attachment_urls` string[] — An array of attachment URLs to attach to this message.
    - `body_html` string, required — The HTML content of the message.
    - `contact_id` string — The contact that sent the message. Only one of user_id or contact_id can be specified.
    - `created_at` string — CreatedAt is the time the message was created (RFC3339).
    - `is_private` boolean, required — Whether the message is private.
    - `user_id` string — The user that sent the message. Only one of user_id or contact_id can be specified.
  - `requester_id` string — ContactID that the issue should be on behalf of.
  - `resolution_time` string — ResolutionTime is the time the issue was resolved (RFC3339).
  - `state` string, required — The state of the issue. Can be one of new, waiting_on_you, waiting_on_customer, on_hold, closed, or a custom status.
  - `tags` string[] — An array of strings to use as tags on this issue.
  - `team_id` string — TeamID that the issue should be assigned to.
  - `title` string, required — The title of the issue.
  - `updated_at` string — UpdatedAt is the time the issue was last updated (RFC3339).

## Response `200`

- ImportIssueResponseBody
  - `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.
  - `warnings` ImportWarnings
    - `skipped_attachments` string[] — Attachment URLs that were skipped because they failed security validation. Present only when at least one was skipped.

## 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)