Issues
Applies the same changes to up to 100 issues. Only provided fields are modified. Issues that do not exist, or that the caller cannot update, are skipped and listed in skipped_issues instead of failing the request.
Rate limit: 30 requests per minute
Authorization: Bearer
The ID of the user to assign the issues to. If empty string is passed in, the issues will be unassigned.
Whether the issues should be visible in the customer portal.
The IDs of the issues to update. Must contain between 1 and 100 IDs.
The state to move the issues to. Standard values are new, waiting_on_you, waiting_on_customer, on_hold, and closed; custom status slugs are also supported.
closedTags to apply to the issues, according to tags_apply_mode.
The mode for applying tags. Valid values: "append_only", "remove_only", "replace". Defaults to "replace".
replaceExample: append_onlyPossible values: The ID of the team to assign the issues to. If empty string is passed in, the team will be removed. Team assignment is applied asynchronously.
The request ID for tracking.
The request was invalid or could not be completed.
The request could not be authenticated for this API.
The authenticated caller or organization is not allowed to access this endpoint or operation.
The request exceeded the applicable rate limit.
An unexpected internal error occurred.
PATCH /issues HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 223
{
"assignee_id": "text",
"custom_fields": [
{
"slug": "text",
"value": "text",
"values": [
"text"
]
}
],
"customer_portal_visible": true,
"issue_ids": [
"text"
],
"state": "closed",
"tags": [
"text"
],
"tags_apply_mode": "append_only",
"team_id": "text"
}{
"data": {
"skipped_issues": [
{
"issue_id": "text",
"reason": "text"
}
],
"succeeded_issue_ids": [
"text"
]
},
"request_id": "text"
}Marks up to 100 email issues as spam. Each issue is deleted, and the sender's email address is blocked unless it belongs to your own domains or support inboxes. If an issue's account has no issues left afterwards, the account is deleted too. Issues from other sources are skipped with reason unsupported_source. Issues that do not exist, or that the caller cannot mark as spam, are skipped and listed in skipped_issues instead of failing the request.
Rate limit: 30 requests per minute
Authorization: Bearer
The IDs of the issues to mark as spam. Must contain between 1 and 100 IDs.
The request ID for tracking.
The request was invalid or could not be completed.
The request could not be authenticated for this API.
The authenticated caller or organization is not allowed to access this endpoint or operation.
The request exceeded the applicable rate limit.
An unexpected internal error occurred.
POST /issues/mark-spam HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 22
{
"issue_ids": [
"text"
]
}{
"data": {
"skipped_issues": [
{
"issue_id": "text",
"reason": "text"
}
],
"succeeded_issue_ids": [
"text"
]
},
"request_id": "text"
}Merges one or more issues into a primary issue. All issues must belong to the same account (or, without an account, the same requester). All issues are found and validated before anything changes, so a request rejected for a missing or ineligible issue merges nothing. Closing messages are sent before the merge and are not recalled: if sending one fails, or the merge fails afterwards, duplicates processed earlier may already have received it. This cannot be undone.
Rate limit: 30 requests per minute
Authorization: Bearer
Optional plain-text message sent to the customer on each merged Slack or form issue before it is merged.
The IDs or numbers of the issues to merge into the primary issue. Must contain between 1 and 50 issues, all in the same account as the primary issue.
The ID or number of the issue to merge into. It keeps its ID and receives the messages of the merged issues.
The request ID for tracking.
The request was invalid or could not be completed.
The request could not be authenticated for this API.
The authenticated caller or organization is not allowed to access this endpoint or operation.
The request exceeded the applicable rate limit.
An unexpected internal error occurred.
POST /issues/merge HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 83
{
"closing_message": "text",
"duplicate_issue_ids": [
"text"
],
"primary_issue_id": "text"
}{
"data": {
"account": {
"external_ids": [
{
"external_id": "text",
"label": "text"
}
],
"id": "text"
},
"active_time_by_user": [
{
"active_time_seconds": 1,
"business_hours_active_time_seconds": 1,
"user_id": "text"
}
],
"active_time_seconds": 1,
"assignee": {
"email": "text",
"id": "text"
},
"attachment_urls": [
"text"
],
"author_unverified": true,
"body_html": "text",
"business_hours_active_time_seconds": 1,
"business_hours_first_response_seconds": 1,
"business_hours_resolution_seconds": 1,
"business_hours_time_in_status_seconds": {
"new": 120,
"waiting_on_customer": 1800
},
"chat_widget_info": {
"page_url": "text"
},
"child_issues": [
{
"id": "text",
"number": 1,
"title": "text"
}
],
"created_at": "2026-01-01T00:00:00.000Z",
"csat_responses": [
{
"comment": "text",
"score": 1
}
],
"custom_fields": {
"priority": {
"value": "high"
}
},
"customer_portal_visible": true,
"external_incidents": [
{
"external_id": "text",
"link": "text",
"reference": "text",
"source": "text"
}
],
"external_issues": [
{
"external_id": "text",
"key": "text",
"link": "text",
"source": "text",
"state": "text"
}
],
"first_resolution_time": "2026-01-01T00:00:00.000Z",
"first_response_assignee_id_at_breach": "text",
"first_response_breach_time": "2026-01-01T00:00:00.000Z",
"first_response_resolving_user_id": "text",
"first_response_seconds": 1,
"first_response_time": "2026-01-01T00:00:00.000Z",
"follow_up": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"id": "text",
"is_issue_group": true,
"latest_message_time": "2026-01-01T00:00:00.000Z",
"link": "text",
"next_reply": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"number": 1,
"number_of_touches": 1,
"parent_issue_group": {
"id": "text",
"number": 1,
"title": "text"
},
"requester": {
"email": "text",
"id": "text"
},
"resolution_assignee_id_at_breach": "text",
"resolution_breach_time": "2026-01-01T00:00:00.000Z",
"resolution_resolving_user_id": "text",
"resolution_seconds": 1,
"resolution_time": "2026-01-01T00:00:00.000Z",
"slack": {
"channel_id": "text",
"message_ts": "text",
"workspace_id": "text"
},
"snoozed_until_time": "2026-01-01T00:00:00.000Z",
"source": "text",
"state": "new",
"tags": [
"text"
],
"team": {
"id": "text"
},
"team_slas": [
{
"first_resolution": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"first_response": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"follow_up": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"next_reply": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"resolution": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"team_id": "text"
}
],
"time_in_status_seconds": {
"new": 120,
"waiting_on_customer": 3600
},
"title": "text",
"type": "text",
"updated_at": "2026-01-01T00:00:00.000Z",
"workspace_email": "text",
"workspace_phone_number": "+14155551234"
},
"request_id": "text"
}Returns a paginated list of issues created within a required time range (max 365 days). Results are sorted by created_at, newest first. To filter on updated_at or other timestamps, use POST /issues/search.
Rate limit: 30 requests per minute
Authorization: Bearer
The start of the time range, filtering on the issue's created_at (inclusive). Use RFC3339 with Z or a URL-encoded offset (%2B). The duration between start_time and end_time must be less than or equal to 365 days.
The end of the time range, filtering on the issue's created_at (exclusive). Use RFC3339 with Z or a URL-encoded offset (%2B). The duration between start_time and end_time must be less than or equal to 365 days.
The cursor to use for pagination.
The number of issues to fetch. Defaults to 20000. Set to 0 or omit to use the default. Must be between 0 and 20000.
The request ID for tracking.
The request was invalid or could not be completed.
The request could not be authenticated for this API.
The authenticated caller or organization is not allowed to access this endpoint or operation.
The request exceeded the applicable rate limit.
An unexpected internal error occurred.
GET /issues?start_time=2026-01-01T00%3A00%3A00.000Z&end_time=2026-01-01T00%3A00%3A00.000Z HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": [],
"request_id": "req_123"
}Links an incident from one of the organization's connected incident systems (incident.io or Rootly). An issue can have several linked incidents, and linking one that is already linked has no effect. To unlink, set the operation field to "unlink".
Rate limit: 120 requests per minute
Authorization: Bearer
The ID or number of the issue to link the incident to.
The incident's reference (such as INC-123 or ROOT-123) or its ID in the incident system.
Operation to perform. Use "link" to link the incident (default) or "unlink" to unlink it.
The incident system the incident belongs to. It must be connected to the organization. Valid values: "incident_io", "rootly"
incident_ioPossible values: The request ID for tracking.
The request was invalid or could not be completed.
The request could not be authenticated for this API.
The authenticated caller or organization is not allowed to access this endpoint or operation.
The request exceeded the applicable rate limit.
An unexpected internal error occurred.
POST /issues/{id}/external-incidents HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 64
{
"incident_id": "text",
"operation": "text",
"source": "incident_io"
}{
"data": {
"account": {
"external_ids": [
{
"external_id": "text",
"label": "text"
}
],
"id": "text"
},
"active_time_by_user": [
{
"active_time_seconds": 1,
"business_hours_active_time_seconds": 1,
"user_id": "text"
}
],
"active_time_seconds": 1,
"assignee": {
"email": "text",
"id": "text"
},
"attachment_urls": [
"text"
],
"author_unverified": true,
"body_html": "text",
"business_hours_active_time_seconds": 1,
"business_hours_first_response_seconds": 1,
"business_hours_resolution_seconds": 1,
"business_hours_time_in_status_seconds": {
"new": 120,
"waiting_on_customer": 1800
},
"chat_widget_info": {
"page_url": "text"
},
"child_issues": [
{
"id": "text",
"number": 1,
"title": "text"
}
],
"created_at": "2026-01-01T00:00:00.000Z",
"csat_responses": [
{
"comment": "text",
"score": 1
}
],
"custom_fields": {
"priority": {
"value": "high"
}
},
"customer_portal_visible": true,
"external_incidents": [
{
"external_id": "text",
"link": "text",
"reference": "text",
"source": "text"
}
],
"external_issues": [
{
"external_id": "text",
"key": "text",
"link": "text",
"source": "text",
"state": "text"
}
],
"first_resolution_time": "2026-01-01T00:00:00.000Z",
"first_response_assignee_id_at_breach": "text",
"first_response_breach_time": "2026-01-01T00:00:00.000Z",
"first_response_resolving_user_id": "text",
"first_response_seconds": 1,
"first_response_time": "2026-01-01T00:00:00.000Z",
"follow_up": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"id": "text",
"is_issue_group": true,
"latest_message_time": "2026-01-01T00:00:00.000Z",
"link": "text",
"next_reply": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"number": 1,
"number_of_touches": 1,
"parent_issue_group": {
"id": "text",
"number": 1,
"title": "text"
},
"requester": {
"email": "text",
"id": "text"
},
"resolution_assignee_id_at_breach": "text",
"resolution_breach_time": "2026-01-01T00:00:00.000Z",
"resolution_resolving_user_id": "text",
"resolution_seconds": 1,
"resolution_time": "2026-01-01T00:00:00.000Z",
"slack": {
"channel_id": "text",
"message_ts": "text",
"workspace_id": "text"
},
"snoozed_until_time": "2026-01-01T00:00:00.000Z",
"source": "text",
"state": "new",
"tags": [
"text"
],
"team": {
"id": "text"
},
"team_slas": [
{
"first_resolution": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"first_response": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"follow_up": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"next_reply": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"resolution": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"team_id": "text"
}
],
"time_in_status_seconds": {
"new": 120,
"waiting_on_customer": 3600
},
"title": "text",
"type": "text",
"updated_at": "2026-01-01T00:00:00.000Z",
"workspace_email": "text",
"workspace_phone_number": "+14155551234"
},
"request_id": "text"
}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: 30 requests per minute
Authorization: Bearer
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.
The user the issue should be assigned to.
URLs of files to attach to the issue's first message.
Whether the requester's identity has NOT been verified. Defaults to false (verified).
The HTML content of the body of the issue.
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.
Timestamp of when the issue was created. If not specified, the current time will be used. (RFC3339)
The ID of a custom issue source (created in the App Directory under Chat > Add Custom Chat App). Sets the issue source to the custom source's slug. Use this for channels Pylon doesn't natively support (e.g. WeChat). Cannot be combined with destination_metadata.
Whether the issue should be visible in the customer portal. When destination is "customer_portal", this is set to true and cannot be false.
The priority of the issue. Can be one of: urgent, high, medium, or low.
mediumPossible values: The URL of an avatar of the requester.
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.
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.
The optional full name of the requester. Used when creating a new contact via requester_email.
The phone number of a new requester. Only supported for direct WhatsApp delivery and cannot be combined with requester_id, requester_email, requester_name, or requester_avatar_url. The number is normalized to E.164 format and used to create a phone-only contact in the same transaction as the issue.
An array of strings to use as tags on this issue. If provided, the issue tags will be updated to the given tags.
The ID of the team this issue should be assigned to.
The title of the issue.
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.
The request ID for tracking.
The request was invalid or could not be completed.
The request could not be authenticated for this API.
The authenticated caller or organization is not allowed to access this endpoint or operation.
The request exceeded the applicable rate limit.
An unexpected internal error occurred.
POST /issues HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 187
{
"body_html": "<p>I cannot access my account.</p>",
"contact_id": "contact_123",
"destination_metadata": {
"destination": "in_app_chat"
},
"requester_id": "contact_123",
"title": "Unable to sign in"
}{
"data": {
"body_html": "<p>I can't sign in to the dashboard.</p>",
"created_at": "2025-01-02T15:04:05Z",
"customer_portal_visible": false,
"id": "issue_123",
"is_issue_group": false,
"link": "https://app.usepylon.com/issues?issueNumber=123",
"number": 123,
"number_of_touches": 1,
"source": "email",
"state": "new",
"title": "Unable to sign in",
"type": "conversation",
"updated_at": "2025-01-02T15:04:05Z"
},
"request_id": "req_123"
}Creates an issue group and attaches its initial child issues atomically.
Rate limit: 30 requests per minute
Authorization: Bearer
The IDs of the issues to include in the group. At least one is required.
The title of the issue group.
The request ID for tracking.
The request was invalid or could not be completed.
The request could not be authenticated for this API.
The authenticated caller or organization is not allowed to access this endpoint or operation.
The request exceeded the applicable rate limit.
An unexpected internal error occurred.
POST /issue-groups HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 43
{
"child_issue_ids": [
"text"
],
"title": "text"
}{
"data": {
"account": {
"external_ids": [
{
"external_id": "text",
"label": "text"
}
],
"id": "text"
},
"active_time_by_user": [
{
"active_time_seconds": 1,
"business_hours_active_time_seconds": 1,
"user_id": "text"
}
],
"active_time_seconds": 1,
"assignee": {
"email": "text",
"id": "text"
},
"attachment_urls": [
"text"
],
"author_unverified": true,
"body_html": "text",
"business_hours_active_time_seconds": 1,
"business_hours_first_response_seconds": 1,
"business_hours_resolution_seconds": 1,
"business_hours_time_in_status_seconds": {
"new": 120,
"waiting_on_customer": 1800
},
"chat_widget_info": {
"page_url": "text"
},
"child_issues": [
{
"id": "text",
"number": 1,
"title": "text"
}
],
"created_at": "2026-01-01T00:00:00.000Z",
"csat_responses": [
{
"comment": "text",
"score": 1
}
],
"custom_fields": {
"priority": {
"value": "high"
}
},
"customer_portal_visible": true,
"external_incidents": [
{
"external_id": "text",
"link": "text",
"reference": "text",
"source": "text"
}
],
"external_issues": [
{
"external_id": "text",
"key": "text",
"link": "text",
"source": "text",
"state": "text"
}
],
"first_resolution_time": "2026-01-01T00:00:00.000Z",
"first_response_assignee_id_at_breach": "text",
"first_response_breach_time": "2026-01-01T00:00:00.000Z",
"first_response_resolving_user_id": "text",
"first_response_seconds": 1,
"first_response_time": "2026-01-01T00:00:00.000Z",
"follow_up": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"id": "text",
"is_issue_group": true,
"latest_message_time": "2026-01-01T00:00:00.000Z",
"link": "text",
"next_reply": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"number": 1,
"number_of_touches": 1,
"parent_issue_group": {
"id": "text",
"number": 1,
"title": "text"
},
"requester": {
"email": "text",
"id": "text"
},
"resolution_assignee_id_at_breach": "text",
"resolution_breach_time": "2026-01-01T00:00:00.000Z",
"resolution_resolving_user_id": "text",
"resolution_seconds": 1,
"resolution_time": "2026-01-01T00:00:00.000Z",
"slack": {
"channel_id": "text",
"message_ts": "text",
"workspace_id": "text"
},
"snoozed_until_time": "2026-01-01T00:00:00.000Z",
"source": "text",
"state": "new",
"tags": [
"text"
],
"team": {
"id": "text"
},
"team_slas": [
{
"first_resolution": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"first_response": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"follow_up": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"next_reply": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"resolution": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"team_id": "text"
}
],
"time_in_status_seconds": {
"new": 120,
"waiting_on_customer": 3600
},
"title": "text",
"type": "text",
"updated_at": "2026-01-01T00:00:00.000Z",
"workspace_email": "text",
"workspace_phone_number": "+14155551234"
},
"request_id": "text"
}Adds one or more child issues atomically. Issues already attached to this group are ignored.
Rate limit: 120 requests per minute
Authorization: Bearer
The ID of the issue group.
The IDs of the issues to add to the group. At least one is required.
The request ID for tracking.
Whether the mutation succeeded.
The request was invalid or could not be completed.
The request could not be authenticated for this API.
The authenticated caller or organization is not allowed to access this endpoint or operation.
The request exceeded the applicable rate limit.
An unexpected internal error occurred.
POST /issue-groups/{issue_group_id}/children HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 28
{
"child_issue_ids": [
"text"
]
}{
"request_id": "text",
"success": true
}Removes one child issue. An issue group must retain at least one child.
Rate limit: 120 requests per minute
Authorization: Bearer
The ID of the issue group.
The ID of the child issue to remove.
The request ID for tracking.
Whether the mutation succeeded.
The request was invalid or could not be completed.
The request could not be authenticated for this API.
The authenticated caller or organization is not allowed to access this endpoint or operation.
The request exceeded the applicable rate limit.
An unexpected internal error occurred.
DELETE /issue-groups/{issue_group_id}/children/{child_issue_id} HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"request_id": "text",
"success": true
}Generates an AI response for the specified issue using the given agent.
Rate limit: 120 requests per minute
Authorization: Bearer
The ID or number of the issue to create an AI response for.
The ID of the AI agent to use to create the AI response.
Whether to post the AI response as an internal note on the issue.
The request ID for tracking.
The HTML content of the AI response.
Whether the AI was able to answer the question.
The request was invalid or could not be completed.
The request could not be authenticated for this API.
The authenticated caller or organization is not allowed to access this endpoint or operation.
The request exceeded the applicable rate limit.
An unexpected internal error occurred.
POST /issues/{id}/ai-response HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 51
{
"ai_agent_id": "text",
"post_as_internal_note": true
}{
"request_id": "text",
"response_html": "text",
"response_valid": true
}Returns all issue statuses for the organization. Use slug as state in PATCH /issues and issue search filters.
Rate limit: 30 requests per minute
Authorization: Bearer
The request ID for tracking.
The request was invalid or could not be completed.
The request could not be authenticated for this API.
The authenticated caller or organization is not allowed to access this endpoint or operation.
The request exceeded the applicable rate limit.
An unexpected internal error occurred.
GET /issue-statuses HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": [
{
"category": "text",
"is_archived": true,
"is_default_status": true,
"label": "text",
"slug": "text"
}
],
"pagination": {
"cursor": "text",
"has_next_page": true
},
"request_id": "text"
}Returns voice call records for the specified phone issue. Each call includes its participants and its recordings, with parsed transcript segments and a presigned download URL for the audio file. Recordings whose transcript has not yet completed are omitted; refetch later to see them.
Rate limit: 120 requests per minute
Authorization: Bearer
The ID of the issue to fetch voice calls for.
The request ID for tracking.
The request was invalid or could not be completed.
The request could not be authenticated for this API.
The authenticated caller or organization is not allowed to access this endpoint or operation.
The request exceeded the applicable rate limit.
An unexpected internal error occurred.
GET /issues/{id}/voice-calls HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": [
{
"created_at": "2026-01-01T00:00:00.000Z",
"duration_sec": 1,
"from_phone_number": "text",
"id": "text",
"participants": [
{
"contact_id": "text",
"id": "text",
"joined_at": "2026-01-01T00:00:00.000Z",
"left_at": "2026-01-01T00:00:00.000Z",
"phone_number": "text",
"recording_consent": "text",
"role": "text",
"status": "text",
"user_id": "text"
}
],
"recordings": [
{
"download_url": "text",
"id": "text",
"transcript_segments": [
{
"speaker": "text",
"text": "text"
}
]
}
],
"to_phone_number": "text"
}
],
"request_id": "text"
}Returns a single issue by ID or issue number.
Rate limit: 300 requests per minute
Authorization: Bearer
The ID or number of the issue to fetch.
The request ID for tracking.
The request was invalid or could not be completed.
The request could not be authenticated for this API.
The authenticated caller or organization is not allowed to access this endpoint or operation.
The request exceeded the applicable rate limit.
An unexpected internal error occurred.
GET /issues/{id} HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": {
"body_html": "<p>I can't sign in to the dashboard.</p>",
"created_at": "2025-01-02T15:04:05Z",
"customer_portal_visible": false,
"id": "issue_123",
"is_issue_group": false,
"link": "https://app.usepylon.com/issues?issueNumber=123",
"number": 123,
"number_of_touches": 1,
"source": "email",
"state": "new",
"title": "Unable to sign in",
"type": "conversation",
"updated_at": "2025-01-02T15:04:05Z"
},
"request_id": "req_123"
}Updates an existing issue. Only provided fields are modified.
Rate limit: 120 requests per minute
Authorization: Bearer
The ID of the issue to update.
The ID of the account that this issue belongs to. To remove the account, pass an empty string and also provide requester_id. The requester can be cleared with an empty string or retained if it has no account memberships. Account removal is supported only for manual, form, and email issues.
The ID of the user who should be assigned to this issue. If empty string is passed in, the issue assignee will be removed.
Whether the issue should be visible in the customer portal.
The ID of the requester that this issue is on behalf of. If an empty string is passed, the requester will be removed. This field must be provided when removing the issue's account, and a retained requester must not belong to any account.
Deprecated: Use requester_id instead.
The state this issue should be moved to. Standard values are new, waiting_on_you, waiting_on_customer, on_hold, and closed; custom status slugs are also supported.
newAn array of strings to use as tags on this issue, applied according to tags_apply_mode. By default the issue tags will be updated to be exactly the given tags.
The mode for applying tags. Valid values: "append_only", "remove_only", "replace". Defaults to "replace".
replaceExample: append_onlyPossible values: The ID of the team this issue should be assigned to. If empty string is passed in, any assigned team will be removed.
The title of the issue.
The type of the issue. Set to "ticket" to upgrade a conversation to a support ticket. Cannot be downgraded from "ticket" to "conversation".
The request ID for tracking.
The request was invalid or could not be completed.
The request could not be authenticated for this API.
The authenticated caller or organization is not allowed to access this endpoint or operation.
The request exceeded the applicable rate limit.
An unexpected internal error occurred.
PATCH /issues/{id} HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 300
{
"account_id": "text",
"assignee_id": "text",
"custom_fields": [
{
"slug": "text",
"value": "text",
"values": [
"text"
]
}
],
"customer_portal_visible": true,
"requester_id": "text",
"requestor_id": "text",
"state": "new",
"tags": [
"text"
],
"tags_apply_mode": "append_only",
"team_id": "text",
"title": "text",
"type": "conversation"
}{
"data": {
"body_html": "<p>I can't sign in to the dashboard.</p>",
"created_at": "2025-01-02T15:04:05Z",
"customer_portal_visible": false,
"id": "issue_123",
"is_issue_group": false,
"link": "https://app.usepylon.com/issues?issueNumber=123",
"number": 123,
"number_of_touches": 1,
"source": "email",
"state": "waiting_on_you",
"title": "Unable to sign in",
"type": "conversation",
"updated_at": "2025-01-02T15:04:05Z"
},
"request_id": "req_123"
}Permanently deletes an issue by ID.
Rate limit: 120 requests per minute
Authorization: Bearer
The ID of the issue to delete.
The request ID for tracking.
The request could not be authenticated for this API.
The authenticated caller or organization is not allowed to access this endpoint or operation.
The request exceeded the applicable rate limit.
An unexpected internal error occurred.
DELETE /issues/{id} HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"request_id": "text"
}Filterable fields and their allowed operators:
created_at
time_is_after, time_is_before, time_range
account_id
equals, in, not_in, is_set, is_unset
customer_portal_visible
equals, in, not_in
ticket_form_id
equals, in, not_in, is_set, is_unset
requester_id
equals, in, not_in, is_set, is_unset
follower_user_id
equals, in, not_in
follower_contact_id
equals, in, not_in
state
equals, in, not_in
tags
contains, does_not_contain, in, not_in, includes_exactly
subject
string_contains, string_does_not_contain
body_html
string_contains, string_does_not_contain
assignee_id
equals, in, not_in, is_set, is_unset, belongs_to, not_belongs_to
team_id
equals, in, not_in
issue_type
equals, in, not_in, is_set, is_unset
issue_is_issue_group
equals, in, not_in
resolved_at
time_is_after, time_is_before, time_range
latest_message_activity_at
time_is_after, time_is_before, time_range
updated_at
time_is_after, time_is_before, time_range
slack_channel_id
equals, in, not_in
workspace_email
equals, in, not_in, is_set, is_unset
reopened
equals, in, not_in
number
equals, in, not_in
source
equals, in, not_in
first_response_at
time_is_after, time_is_before, time_range, time_is_in_last, time_is_not_in_last, is_set, is_unset
latest_customer_message_activity_at
time_is_after, time_is_before, time_range, time_is_in_last, time_is_not_in_last, is_set, is_unset
latest_vendor_message_activity_at
time_is_after, time_is_before, time_range, time_is_in_last, time_is_not_in_last, is_set, is_unset
partner_account_id
equals, in, not_in, is_set, is_unset
is_snoozed
equals, in, not_in
requester_email
the operators of the requester's email
parent_issue_group_id
equals, in, not_in, is_set, is_unset
number_of_touches
equals, greater_than, greater_than_or_equals, less_than, less_than_or_equals
email_subject
string_contains, string_does_not_contain, starts_with, ends_with, is_set, is_unset
first_message_from
equals, in, not_in, is_set
last_message_from
equals, in, not_in, is_set
latest_public_message_activity_at
time_is_after, time_is_before, time_range, time_is_in_last, time_is_not_in_last, is_set, is_unset
number_of_customer_messages
equals, greater_than, greater_than_or_equals, less_than, less_than_or_equals, is_set, is_unset
message_redaction_used
equals, in, not_in
time_to_first_response
greater_than, greater_than_or_equals, less_than, less_than_or_equals, is_set
from_email
equals, in, not_in, string_contains, string_does_not_contain, starts_with, ends_with, is_set
cc_email
equals, in, not_in, string_contains, string_does_not_contain, starts_with, ends_with, is_set, is_unset
ccs
equals, in, not_in, string_contains, string_does_not_contain, starts_with, ends_with, is_set, is_unset
asana_product_issue
equals, in, not_in, is_set, is_unset
github_product_issue
equals, in, not_in, is_set, is_unset
jira_product_issue
equals, in, not_in, string_contains, starts_with, ends_with, is_set, is_unset
linear_product_issue
equals, in, not_in, string_contains, starts_with, is_set, is_unset
shortcut_product_issue
equals, in, not_in, is_set, is_unset
product_issue_source
equals, in, not_in, is_set, is_unset
product_ticket_completion
equals
number_of_child_issues
equals, greater_than, greater_than_or_equals, less_than, less_than_or_equals, is_set, is_unset
created_in_channel_id
equals, in, not_in, string_contains, starts_with, ends_with, is_set, is_unset
product_area
equals, in, not_in, is_set, is_unset
Filter syntax and operators
See Search filters for filter structure, combining conditions, related objects, and operator definitions. The table above lists the operators supported by each issue field.
Status and issue properties
Standard state values:
new waiting_on_you waiting_on_customer on_hold closed
Custom status slugs are also supported.
issue_type
conversation or ticket.
is_snoozed
true or false.
customer_portal_visible
true or false. Issue groups always match false.
reopened
true or false. Set the first time an issue is reopened after being resolved; stays set and records no timestamp.
parent_issue_group_id
The ID of the issue group the issue belongs to.
product_area
A product area slug, such as billing.
tags
A tag name or ID.
Messages, timestamps, and counts
Timestamp values use RFC 3339 format, such as 2026-10-01T00:00:00Z.
subject
The issue title. title is also accepted as a field name.
subject, body_html
contains and does_not_contain are aliases for string_contains and string_does_not_contain.
latest_vendor_message_activity_at
The timestamp of the latest message from your team.
latest_customer_message_activity_at
The timestamp of the latest message from the customer.
first_message_from, last_message_from
customer, vendor, or a team ID to match messages from that team's members. For example, "value": "customer".
time_to_first_response
Seconds by default. Use "value": "3600" with greater_than for over an hour. "<N>,seconds" and "<N>,milliseconds" are also accepted.
number_of_touches
The issue's number_of_touches value.
number_of_customer_messages, number_of_child_issues
Whole numbers.
message_redaction_used
true or false.
Sources, channels, and email
source
The issue's source, such as slack, email, chat_widget, or manual. Issues created with a custom_issue_source_id match that custom source's slug.
slack_channel_id
The Slack channel ID where the issue was created.
workspace_email
The email address connected to the Pylon workspace through which the issue's email conversation is routed.
requester_email
Shorthand for a related_object filter on the requester's email.
ccs
The CC addresses on the issue's latest email.
cc_email
The CC recipients recorded on the issue.
For from_email, ccs, and cc_email, use an address such as jane@acme.com, or string_contains with @acme.com to match a domain.
created_in_channel_id matches the channel where the issue was created. The value depends on the operator:
equals, in, not_in
Channel ID; for email issues, an email address.
C0123ABCDEF or support@acme.com
string_contains, starts_with, ends_with
Channel name.
support
Linked engineering tickets
Use the linked ticket's external_id from the issue's external_issues entry. Each integration uses a different ID format:
linear_product_issue
Linear issue UUID.
2f8c1d3e-6b1a-4c55-9e0f-7a2b3c4d5e6f
jira_product_issue
Jira issue numeric ID.
10042
github_product_issue
owner/repo/number.
acme/api/123
shortcut_product_issue
Story numeric ID.
1234
asana_product_issue
Task numeric ID.
1204567890123456
Human-readable ticket keys such as ENG-123, PROJ-42, and sc-1234 aren't accepted for these filters.
product_issue_source accepts:
asana github jira linear shortcut
product_ticket_completion accepts any_done or all_done.
Custom fields
Set field to the custom field's slug. If a custom field has the same slug as one of the built-in fields listed above, the custom field is matched instead.
Rate limit: 120 requests per minute
Authorization: Bearer
The cursor to use for pagination.
The number of issues to fetch. Defaults to 100. Must be between 1 and 1000.
Fuzzy text search. Results are intersected with any provided filter.
The request was invalid or could not be completed.
The request could not be authenticated for this API.
The authenticated caller or organization is not allowed to access this endpoint or operation.
The request exceeded the applicable rate limit.
An unexpected internal error occurred.
POST /issues/search HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 62
{
"filter": {
"field": "state",
"operator": "equals",
"value": "new"
}
}{
"data": [],
"request_id": "req_123"
}Snoozes an issue until the specified date and time.
Rate limit: 120 requests per minute
Authorization: Bearer
The ID or number of the issue to snooze.
The date and time to snooze the issue until. (RFC3339)
The request ID for tracking.
The request was invalid or could not be completed.
The request could not be authenticated for this API.
The authenticated caller or organization is not allowed to access this endpoint or operation.
The request exceeded the applicable rate limit.
An unexpected internal error occurred.
POST /issues/{id}/snooze HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 43
{
"snooze_until": "2026-01-01T00:00:00.000Z"
}{
"data": {
"body_html": "<p>I can't sign in to the dashboard.</p>",
"created_at": "2025-01-02T15:04:05Z",
"customer_portal_visible": false,
"id": "issue_123",
"is_issue_group": false,
"link": "https://app.usepylon.com/issues?issueNumber=123",
"number": 123,
"number_of_touches": 1,
"source": "email",
"state": "on_hold",
"title": "Unable to sign in",
"type": "conversation",
"updated_at": "2025-01-02T15:04:05Z"
},
"request_id": "req_123"
}Returns the list of followers for the specified issue.
Rate limit: 300 requests per minute
Authorization: Bearer
The ID or number of the issue to get followers for.
The request ID for tracking.
The request was invalid or could not be completed.
The request could not be authenticated for this API.
The authenticated caller or organization is not allowed to access this endpoint or operation.
The request exceeded the applicable rate limit.
An unexpected internal error occurred.
GET /issues/{id}/followers HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": [
{
"id": "text",
"type": "text"
}
],
"request_id": "text"
}By default, adds followers. To remove followers, set the operation field to "remove".
Rate limit: 120 requests per minute
Authorization: Bearer
The ID or number of the issue to add followers to.
The IDs of contacts to add as followers.
Operation to perform. Use "add" to add followers (default) or "remove" to remove followers.
The IDs of users to add as followers.
The request ID for tracking.
The request was invalid or could not be completed.
The request could not be authenticated for this API.
The authenticated caller or organization is not allowed to access this endpoint or operation.
The request exceeded the applicable rate limit.
An unexpected internal error occurred.
POST /issues/{id}/followers HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 63
{
"contact_ids": [
"text"
],
"operation": "text",
"user_ids": [
"text"
]
}{
"data": [
{
"id": "text",
"type": "text"
}
],
"request_id": "text"
}By default, links external issues. To unlink issues, set the operation field to "unlink".
Rate limit: 120 requests per minute
Authorization: Bearer
The ID or number of the issue to link external issues to.
The ID of the external issue in the source system.
Operation to perform. Use "link" to link issues (default) or "unlink" to unlink issues.
The source system of the external issue (e.g., "linear", "asana", "jira", "github", "shortcut").
The request ID for tracking.
The request was invalid or could not be completed.
The request could not be authenticated for this API.
The authenticated caller or organization is not allowed to access this endpoint or operation.
The request exceeded the applicable rate limit.
An unexpected internal error occurred.
POST /issues/{id}/external-issues HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Content-Type: application/json
Accept: */*
Content-Length: 63
{
"external_issue_id": "text",
"operation": "text",
"source": "text"
}{
"data": {
"account": {
"external_ids": [
{
"external_id": "text",
"label": "text"
}
],
"id": "text"
},
"active_time_by_user": [
{
"active_time_seconds": 1,
"business_hours_active_time_seconds": 1,
"user_id": "text"
}
],
"active_time_seconds": 1,
"assignee": {
"email": "text",
"id": "text"
},
"attachment_urls": [
"text"
],
"author_unverified": true,
"body_html": "text",
"business_hours_active_time_seconds": 1,
"business_hours_first_response_seconds": 1,
"business_hours_resolution_seconds": 1,
"business_hours_time_in_status_seconds": {
"new": 120,
"waiting_on_customer": 1800
},
"chat_widget_info": {
"page_url": "text"
},
"child_issues": [
{
"id": "text",
"number": 1,
"title": "text"
}
],
"created_at": "2026-01-01T00:00:00.000Z",
"csat_responses": [
{
"comment": "text",
"score": 1
}
],
"custom_fields": {
"priority": {
"value": "high"
}
},
"customer_portal_visible": true,
"external_incidents": [
{
"external_id": "text",
"link": "text",
"reference": "text",
"source": "text"
}
],
"external_issues": [
{
"external_id": "text",
"key": "text",
"link": "text",
"source": "text",
"state": "text"
}
],
"first_resolution_time": "2026-01-01T00:00:00.000Z",
"first_response_assignee_id_at_breach": "text",
"first_response_breach_time": "2026-01-01T00:00:00.000Z",
"first_response_resolving_user_id": "text",
"first_response_seconds": 1,
"first_response_time": "2026-01-01T00:00:00.000Z",
"follow_up": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"id": "text",
"is_issue_group": true,
"latest_message_time": "2026-01-01T00:00:00.000Z",
"link": "text",
"next_reply": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"number": 1,
"number_of_touches": 1,
"parent_issue_group": {
"id": "text",
"number": 1,
"title": "text"
},
"requester": {
"email": "text",
"id": "text"
},
"resolution_assignee_id_at_breach": "text",
"resolution_breach_time": "2026-01-01T00:00:00.000Z",
"resolution_resolving_user_id": "text",
"resolution_seconds": 1,
"resolution_time": "2026-01-01T00:00:00.000Z",
"slack": {
"channel_id": "text",
"message_ts": "text",
"workspace_id": "text"
},
"snoozed_until_time": "2026-01-01T00:00:00.000Z",
"source": "text",
"state": "new",
"tags": [
"text"
],
"team": {
"id": "text"
},
"team_slas": [
{
"first_resolution": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"first_response": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"follow_up": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"next_reply": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"resolution": {
"assignee_id_at_breach": "text",
"breach_time": "2026-01-01T00:00:00.000Z",
"business_hours_seconds": 1,
"resolving_user_id": "text",
"seconds": 1,
"time": "2026-01-01T00:00:00.000Z"
},
"team_id": "text"
}
],
"time_in_status_seconds": {
"new": 120,
"waiting_on_customer": 3600
},
"title": "text",
"type": "text",
"updated_at": "2026-01-01T00:00:00.000Z",
"workspace_email": "text",
"workspace_phone_number": "+14155551234"
},
"request_id": "text"
}
Last updated
Was this helpful?

