Issues
Returns a paginated list of issues within a required time range (max 365 days).
Rate limit: 30 requests per minute
Authorization: Bearer
The start time (RFC3339) of the time range to get issues for. The duration between start_time and end_time must be less than or equal to 365 days.
The end time (RFC3339) of the time range to get issues for. 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 authenticated caller or organization is not allowed to access this endpoint or operation.
An unexpected internal error occurred.
GET /issues?start_time=text&end_time=text HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": [],
"request_id": "req_123"
}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)
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 authenticated caller or organization is not allowed to access this endpoint or operation.
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": {
"id": "issue_123",
"state": "new",
"title": "Unable to sign in",
"type": "conversation"
},
"request_id": "req_123"
}Create an issue group 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 authenticated caller or organization is not allowed to access this endpoint or operation.
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": "text",
"csat_responses": [
{
"comment": "text",
"score": 1
}
],
"custom_fields": {
"priority": {
"value": "high"
}
},
"customer_portal_visible": true,
"external_issues": [
{
"external_id": "text",
"link": "text",
"source": "text"
}
],
"first_response_breach_time": "text",
"first_response_seconds": 1,
"first_response_time": "text",
"id": "text",
"is_issue_group": true,
"latest_message_time": "text",
"link": "text",
"number": 1,
"number_of_touches": 1,
"parent_issue_group": {
"id": "text",
"number": 1,
"title": "text"
},
"requester": {
"email": "text",
"id": "text"
},
"resolution_breach_time": "text",
"resolution_seconds": 1,
"resolution_time": "text",
"slack": {
"channel_id": "text",
"message_ts": "text",
"workspace_id": "text"
},
"snoozed_until_time": "text",
"source": "slack",
"state": "new",
"tags": [
"text"
],
"team": {
"id": "text"
},
"team_slas": [
{
"first_response": {
"breach_time": "text",
"business_hours_seconds": 1,
"seconds": 1,
"time": "text"
},
"resolution": {
"breach_time": "text",
"business_hours_seconds": 1,
"seconds": 1,
"time": "text"
},
"team_id": "text"
}
],
"time_in_status_seconds": {
"new": 120,
"waiting_on_customer": 3600
},
"title": "text",
"type": "conversation",
"updated_at": "text",
"workspace_email": "text"
},
"request_id": "text"
}Add children to an issue group 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 authenticated caller or organization is not allowed to access this endpoint or operation.
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
}Remove a child from an issue group 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 authenticated caller or organization is not allowed to access this endpoint or operation.
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 authenticated caller or organization is not allowed to access this endpoint or operation.
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.
Rate limit: 30 requests per minute
Authorization: Bearer
The request ID for tracking.
The request was invalid or could not be completed.
The authenticated caller or organization is not allowed to access this endpoint or operation.
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 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 authenticated caller or organization is not allowed to access this endpoint or operation.
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": "text",
"duration_sec": 1,
"from_phone_number": "text",
"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 authenticated caller or organization is not allowed to access this endpoint or operation.
An unexpected internal error occurred.
GET /issues/{id} HTTP/1.1
Host: api.usepylon.com
Authorization: Bearer YOUR_SECRET_TOKEN
Accept: */*
{
"data": {
"id": "issue_123",
"state": "new",
"title": "Unable to sign in",
"type": "conversation"
},
"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. If provided, the issue tags will be updated to be exactly the given tags.
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 authenticated caller or organization is not allowed to access this endpoint or operation.
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: 268
{
"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"
],
"team_id": "text",
"title": "text",
"type": "conversation"
}{
"data": {
"id": "issue_123",
"state": "waiting_on_you",
"title": "Unable to sign in",
"type": "conversation"
},
"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 authenticated caller or organization is not allowed to access this endpoint or operation.
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
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
title
string_contains, string_does_not_contain
body_html
string_contains, string_does_not_contain
assignee_id
equals, in, not_in, is_set, is_unset
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
Timestamp values use RFC3339 format. Standard state values are new, waiting_on_you, waiting_on_customer, on_hold, and closed; custom status slugs are also supported. issue_type values are conversation and ticket.
For tag filters, pass the tag name. For custom fields, pass the field slug as field. slack_channel_id identifies the Slack channel where the issue was created. workspace_email identifies the email address connected to the Pylon workspace through which the issue's email conversation is routed.
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 greater than 0 and less than 1000.
Fuzzy text search. Results are intersected with any provided filter.
The request was invalid or could not be completed.
The authenticated caller or organization is not allowed to access this endpoint or operation.
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 authenticated caller or organization is not allowed to access this endpoint or operation.
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: 23
{
"snooze_until": "text"
}{
"data": {
"id": "issue_123",
"state": "on_hold",
"title": "Unable to sign in",
"type": "conversation"
},
"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 authenticated caller or organization is not allowed to access this endpoint or operation.
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": "user"
}
],
"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 authenticated caller or organization is not allowed to access this endpoint or operation.
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": "user"
}
],
"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 authenticated caller or organization is not allowed to access this endpoint or operation.
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": "text",
"csat_responses": [
{
"comment": "text",
"score": 1
}
],
"custom_fields": {
"priority": {
"value": "high"
}
},
"customer_portal_visible": true,
"external_issues": [
{
"external_id": "text",
"link": "text",
"source": "text"
}
],
"first_response_breach_time": "text",
"first_response_seconds": 1,
"first_response_time": "text",
"id": "text",
"is_issue_group": true,
"latest_message_time": "text",
"link": "text",
"number": 1,
"number_of_touches": 1,
"parent_issue_group": {
"id": "text",
"number": 1,
"title": "text"
},
"requester": {
"email": "text",
"id": "text"
},
"resolution_breach_time": "text",
"resolution_seconds": 1,
"resolution_time": "text",
"slack": {
"channel_id": "text",
"message_ts": "text",
"workspace_id": "text"
},
"snoozed_until_time": "text",
"source": "slack",
"state": "new",
"tags": [
"text"
],
"team": {
"id": "text"
},
"team_slas": [
{
"first_response": {
"breach_time": "text",
"business_hours_seconds": 1,
"seconds": 1,
"time": "text"
},
"resolution": {
"breach_time": "text",
"business_hours_seconds": 1,
"seconds": 1,
"time": "text"
},
"team_id": "text"
}
],
"time_in_status_seconds": {
"new": 120,
"waiting_on_customer": 3600
},
"title": "text",
"type": "conversation",
"updated_at": "text",
"workspace_email": "text"
},
"request_id": "text"
}
Last updated
Was this helpful?