List Conversations

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

Request

GET /v2/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 mailbox, call:


curl https://api.helpscout.net/v2/conversations?mailbox=123&status=closed

By default only active conversations are listed and they are sorted by createdAt (from newest to oldest). This is equivalent to ?status=active&sortField=createdAt&sortOrder=desc. If you want to list all conversations, use ?status=all

URL Parameters

URL query params will not be carried into page reference links

All pagination links (_links.next, _links.previous etc) are affected. We're aware of the issue and we are working on a fix.

Parameter Description
mailbox Filters conversations from a specific mailbox id. Use comma separated values for more mailboxes: ?mailbox=123,456
folder Filters conversations from a specific folder id: ?folder=993
status Filter conversation by status (defaults to active):
active
all
closed
open
pending
spam
tag Filter conversation by tags. Use comma separated values for more tags that: ?tag=red,blue
assigned_to Filters conversations by assignee id: ?assigned_to=1771
modifiedSince Filters conversations modified after this timestamp - ISO 8061 date time
number Looks up conversation by conversation number
sortField Sorts the result by specified field:
createdAt
customerEmail
customerName
mailboxid
modifiedAt
number
score
status
subject
sortOrder Sort order, either desc or asc, default is desc
query Advanced search query. If you use other filtering request parameters, they will be combined with AND operator.For example ?mailbox=567&query=tag:fire effectively means mailbox=567 AND tag=fire.
page Page number

Query

You can create complex search queries by combining operators:

?query=(assigned:"spock" AND status:active AND (customerIds: 123 OR customerIds: 567))

Subject

Example What it does
query=(subject:"rainbow") Searches for conversation subjects that contain the word “rainbow”
query=(subject:"have a question") Searches for conversation subjects that contain the phrase “have a question” (not case sensitive)
query=(subject:"coffee" OR subject:"tea") Searches for conversations with a subject that contain the word “coffee” or the word “tea”
query=(subject:"coffee tea") Searches for conversation subjects that contain the word “coffee” and the word “tea” in no particular order

Tags

Example What it does
query=(tag:"carrots") Searches for conversations that have the tag “carrots”
query=(tag:"dogs love carrots") Searches for conversations that have the tag “dogs love carrots”
query=(tag:"dogs" OR tag:"carrots") Searches for conversations that are tagged with either “dogs” or “carrots”

Mailbox

Example What it does
query=(mailbox:"Orders") Searches the “Orders” mailbox by exact match
query=(mailboxid:100) Searches the mailbox with an id of 100

Modified At

Example What it does
query=(modifiedAt:[2014-02-27T00:00:00Z TO *]) Searches conversations that have been modified since 2014-02-27
query=(modifiedAt:[2014-02-27T00:00:00Z TO 2014-02-27T23:59:59Z]) Searches conversations that were modified on 2014-02-27
query=(modifiedAt:[NOW-1HOUR]) Searches conversations that were modified in the last hour
query=(modifiedAt:[2013-01-01T00:00:00Z/YEAR]) Searches conversations that were modified in 2013

Created At

Example What it does
query=(createdAt:[2014-02-27T00:00:00Z TO *]) Searches conversations that have been created since 2014-02-27
query=(createdAt:[2014-02-27T00:00:00Z TO 2014-02-27T23:59:59Z]) Searches conversations that were created on 2014-02-27
query=(createdAt:[NOW-1HOUR]) Searches conversations that were created in the last hour
query=(createdAt:[2013-01-01T00:00:00Z/YEAR]) Searches conversations that were created in 2013

Email

Example What it does
query=(email:"john@appleseed.com") Searches conversations where the mailjohn@appleseed.com is either in to, cc, bcc fields or it’s one of the emails in a customer profile.
query=(email:(john@appleseed.com OR vbear@mywork.com)) Searches conversations using the fields mentioned above, but returns results for multiple emails or customers

Body

Example What it does
query=(body:"what a beautiful day") Searches conversation threads for the phrase, “what a beautiful day”
query=(body:"what a day" OR body:"how about tomorrow") Searches conversation threads for the phrases “what a day” or “how about tomorrow”

Status

Example What it does
query=(status:active) Searches conversations that have a status of active. Valid values are active, pending, closed and spam.
query=(status:active OR status:pending) Searches conversations that have a status of active or pending

Other

Example What it does
query=(customerIds:100) Returns conversations (across all mailboxes) belonging to the given customer
query=(number:1234) Searches for conversation #1234
query=(id:123456) Searches for the unique conversation ID
query=(assigned:"spock") Searches for conversations assigned to Spock
query=(attachments:true) Searches for conversations with attachments
query=(assigned:"Unassigned") Searches for unassigned conversations

Response

HTTP/1.1 200 OK
Content-Type: application/hal+json;charset=UTF-8

{
  "_embedded" : {
    "conversations" : [ {
      "id" : 123,
      "number" : 12,
      "threads" : 2,
      "type" : "email",
      "folderId" : 11,
      "status" : "closed",
      "state" : "published",
      "subject" : "Help",
      "preview" : "Preview",
      "mailboxId" : 13,
      "assignee" : {
        "id" : 256,
        "type" : "customer",
        "first" : "Mr",
        "last" : "Robot",
        "email" : "none@nowhere.com"
      },
      "createdBy" : {
        "id" : 12,
        "type" : "customer",
        "email" : "bear@acme.com"
      },
      "createdAt" : "2012-03-15T22:46:22Z",
      "closedBy" : 14,
      "closedAt" : "2012-03-16T14:07:23Z",
      "userUpdatedAt" : "2012-03-16T14:07:23Z",
      "customerWaitingSince" : {
        "time" : "2012-07-24T20:18:33Z",
        "friendly" : "20 hours ago",
        "latestReplyFrom" : "customer"
      },
      "source" : {
        "type" : "email",
        "via" : "customer"
      },
      "tags" : [ {
        "id" : 9150,
        "color" : "#929499",
        "tag" : "vip"
      } ],
      "cc" : [ "bear@normal.com" ],
      "bcc" : [ "bear@secret.com" ],
      "primaryCustomer" : {
        "id" : 238604
      },
      "customFields" : [ {
        "id" : 8,
        "name" : "Account Type",
        "value" : "8518"
      }, {
        "id" : 6688,
        "name" : "Account Status",
        "value" : "33077"
      } ],
      "_links" : {
        "assignee" : {
          "href" : "..."
        },
        "closedBy" : {
          "href" : "..."
        },
        "createdByCustomer" : {
          "href" : "..."
        },
        "mailbox" : {
          "href" : "..."
        },
        "primaryCustomer" : {
          "href" : "..."
        },
        "self" : {
          "href" : "..."
        },
        "threads" : {
          "href" : "..."
        },
        "web" : {
          "href" : "..."
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "..."
    },
    "last" : {
      "href" : "..."
    },
    "page" : {
      "href" : "...",
      "templated" : true
    },
    "self" : {
      "href" : "..."
    }
  },
  "page" : {
    "size" : 50,
    "totalElements" : 0,
    "totalPages" : 0,
    "number" : 0
  }
}

Response fields

Path Type Description
_embedded.conversations Array Conversation objects