List Conversations (v3)

List and filter conversations. Use the threads resource link inside the Conversation entity to load conversation threads.

Request

GET /v3/conversations HTTP/1.1
Authorization: Bearer oauth_token

Request parameters can be used to filter conversations. All parameters are joined by the AND operator. If you want closed conversations in a specific inbox, call:


curl https://api.helpscout.net/v3/conversations?inboxId=123&status=closed

Every filter is a typed URL parameter. Parameters that accept more than one value (inboxId, contactId, tag, status) take them comma separated, and a conversation matches when it has any of the values given. Unknown parameters, blank values and values of the wrong type are rejected with a 400 Bad Request.

By default only active conversations are listed. This is equivalent to ?status=active. If you want to list all conversations, use ?status=all.

Conversations are sorted by conversation id (id) from newest to oldest, which is equivalent to sorting by creation date (createdAt).

Note: If using the embed=threads parameter with this call, you will see truncated chat threads. This is by design. To view Beacon chat threads in full, call the List Threads (v3) endpoint for that conversation instead.

URL Parameters

Parameter Type Examples Description
inboxId number inboxId=123
inboxId=123,567
 Filters conversations from a specific inbox id. Use comma separated values for more inboxes
contactId number contactId=123
contactId=123,567
 Filters conversations belonging to a specific contact (customer) id. Use comma separated values for more contacts
email string email=john@appleseed.com
 Filters conversations by the exact email address of the contact (customer). Accepts a single address
status enumeration status=active
status=open,closed
 Filter conversations by status (defaults to active):
active
all
closed
open
pending
spam

See Status values for details
tag string tag=red
tag=red,blue
 Filter conversations by tag name. Use comma separated values for more tags
assignedId number assignedId=1771
 Filters conversations by assignee id
number number number=123
 Looks up conversation by conversation number
createdSince date createdSince=2018-05-04T12:00:03Z
 Filters conversations created after this timestamp
modifiedSince date modifiedSince=2018-05-04T12:00:03Z
 Filters conversations modified after this timestamp
customFieldsByIds special customFieldsByIds=123:blue
customFieldsByIds=123:blue,234:99
 Filters conversations by custom fields, using custom field IDs. Requires exactly one inboxId value.
Expected format is id:value,id:value

See Custom Fields search for details
embed enumeration embed=threads
Allows embedding/loading of sub-entities, allowed values are:
threads
cursor string cursor=eyJpZCI6MTIzfQ==
 Cursor for pagination. See Pagination

Status values

Value What it lists
active Active conversations (the default when status is omitted)
pending Pending conversations
closed Closed conversations
spam Conversations marked as spam
open Active and pending conversations, shorthand for status=active,pending
all Conversations in every status; any other value passed alongside all is ignored

Values can be combined with a comma, for example ?status=active,closed lists conversations that are either active or closed.

customFieldsByIds

This is a fairly low level search - the values are expected in a fieldId:value format and you can either

  • use multiple customFieldsByIds params like this ?customFieldsByIds=123:green&customFieldsByIds=234:blue
  • or join the values yourself: ?customFieldsByIds=123:green,234:blue.

Rules:

  • customFieldsByIds requires exactly one inboxId — custom field ids are inbox-scoped, so this filter must be combined with a single inboxId value. Omitting inboxId, or passing more than one, returns a 400 Bad Request response.
  • the filtering is done via an exact match for all field types with the exception of text fields, which are searched in a full text search manner
  • multiple filters use the AND operator - all custom field filters must match
  • for the Dropdown custom field type the value is the dropdown option ID (you can use the Inbox Fields endpoint to fetch all IDs)

Pagination

This endpoint uses cursor-based pagination. Follow the next link in the response to load the next page of results.

  • The response _links contains self, first, and (when more results are available) next.
  • To page forward, request the URL in _links.next.href, or pass its cursor value in the cursor parameter.
  • When _links.next is absent, there are no more results.
  • There are no last or prev links, and no page object.

Response

HTTP/1.1 200 OK
Content-Type: application/hal+json

{
  "_embedded" : {
    "conversations" : [ {
      "_links" : {
        "self" : {
          "href" : "..."
        },
        "mailbox" : {
          "href" : "..."
        },
        "primaryCustomer" : {
          "href" : "..."
        },
        "createdByUser" : {
          "href" : "..."
        },
        "closedBy" : {
          "href" : "..."
        },
        "threads" : {
          "href" : "..."
        },
        "assignee" : {
          "href" : "..."
        },
        "web" : {
          "href" : "..."
        }
      },
      "id" : 10,
      "number" : 12,
      "threads" : 2,
      "type" : "email",
      "folderId" : 11,
      "status" : "closed",
      "state" : "published",
      "subject" : "Help",
      "preview" : "Preview",
      "mailboxId" : 13,
      "assignee" : {
        "id" : 99,
        "type" : "user",
        "first" : "Mr",
        "last" : "Robot",
        "email" : "none@nowhere.com"
      },
      "createdBy" : {
        "id" : 12,
        "type" : "system_user",
        "email" : "bear@acme.com"
      },
      "createdAt" : "2012-03-15T22:46:22Z",
      "closedBy" : 14,
      "closedByUser" : {
        "id" : 14,
        "type" : "user",
        "first" : "Clo",
        "last" : "Ser",
        "photoUrl" : "pic.jpg",
        "email" : "closer@closers.com"
      },
      "closedAt" : "2012-03-16T14:07:23Z",
      "userUpdatedAt" : "2012-03-16T14:07:23Z",
      "customerWaitingSince" : {
        "time" : "2012-07-24T20:18:33Z",
        "friendly" : "20 hours ago"
      },
      "source" : {
        "type" : "email",
        "via" : "customer"
      },
      "tags" : [ {
        "id" : 9150,
        "color" : "#929499",
        "tag" : "vip",
        "styles" : {
          "dark" : {
            "background" : {
              "fill" : "#37A4FF"
            },
            "text" : {
              "fill" : "#161616"
            }
          },
          "default" : {
            "background" : {
              "fill" : "#ACE3FF"
            },
            "text" : {
              "fill" : "#1D2B36"
            }
          }
        }
      } ],
      "cc" : [ "bear@normal.com" ],
      "bcc" : [ "bear@secret.com" ],
      "primaryCustomer" : {
        "id" : 238604,
        "type" : "customer",
        "first" : "Rob",
        "last" : "Robertovic",
        "email" : "rob@acme.com"
      },
      "snooze" : {
        "snoozedBy" : 4,
        "snoozedUntil" : "2024-06-03T12:00:00Z",
        "unsnoozeOnCustomerReply" : true
      },
      "nextEvent" : {
        "time" : "2024-06-03T12:00:00Z",
        "eventType" : "snooze",
        "userId" : 4,
        "cancelOnCustomerReply" : true
      },
      "customFields" : [ {
        "id" : 8,
        "name" : "Account Type",
        "value" : "8518",
        "text" : "Free"
      }, {
        "id" : 6688,
        "name" : "Account Status",
        "value" : "33077",
        "text" : "Trial"
      }, {
        "id" : 9105,
        "name" : "ai-topic",
        "value" : "41194",
        "text" : "Billing",
        "systemType" : "topic"
      } ],
      "_embedded" : {
        "threads" : [ ]
      }
    } ]
  },
  "_links" : {
    "next" : {
      "href" : "..."
    },
    "self" : {
      "href" : "..."
    },
    "first" : {
      "href" : "..."
    }
  }
}

Response fields

Path Type Description
_embedded.conversations Array Array of Conversation (v3) objects
_links.self Object Link to the current page
_links.first Object Link to the first page
_links.next Object Link to the next page (only present when more results are available)
↑Back to top