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

Parameter Type Examples Description
mailbox number mailbox=123
mailbox=123,567
Filters conversations from a specific mailbox id. Use comma separated values for more mailboxes
folder number folder=993
Filters conversations from a specific folder id
status enumeration status=active
Filter conversation by status (defaults to active):
active
all
closed
open
pending
spam
tag string tag=red
tag=red,blue
Filter conversation by tags. Use comma separated values for more tags
assigned_to number assigned_to=1771
Filters conversations by assignee id
modifiedSince date modifiedSince=2018-05-04T12:00:03Z
Filters conversations modified after this timestamp
number number number=123
Looks up conversation by conversation number
sortField enumeration sortField=createdAt
Sorts the result by specified field:
createdAt
customerEmail
customerName
mailboxid
modifiedAt
number
score
status
subject
sortOrder enumeration sortOrder=desc
Sort order, either desc or asc, default is desc
query special query=(number: 123)
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 number page=1
Page number
customFieldsByIds special customFieldsByIds=123:blue
customFieldsByIds=123:blue,234:99
Filters conversations by custom fields, using custom field IDs. This filter must be accompanied by mailbox parameter as well.
Expected format is id:value,id:value

See Custom Fields Search for details

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:

  • the filtering is done via an exact match for all field types with the exception of single line text field - for example a custom field with a number type and ID 123 with the following filter of 123:1000 will only match if the value is precisely 1000
  • single line text fields are searched in full text search manner
  • multiple filters use AND operator - all custom fields filters must match
  • for Dropdown custom field type the value is the dropdown option ID (you can use Mailbox Fields endpoint to fetch all IDs)
  • Multiline custom fields are not supported

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,
      "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",
        "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,
        "type" : "customer",
        "first" : "Rob",
        "last" : "Robertovic",
        "email" : "rob@acme.com"
      },
      "customFields" : [ {
        "id" : 8,
        "name" : "Account Type",
        "value" : "8518",
        "text" : "Free"
      }, {
        "id" : 6688,
        "name" : "Account Status",
        "value" : "33077",
        "text" : "Trial"
      } ],
      "_links" : {
        "assignee" : {
          "href" : "..."
        },
        "closedBy" : {
          "href" : "..."
        },
        "createdByCustomer" : {
          "href" : "..."
        },
        "mailbox" : {
          "href" : "..."
        },
        "primaryCustomer" : {
          "href" : "..."
        },
        "self" : {
          "href" : "..."
        },
        "threads" : {
          "href" : "..."
        },
        "web" : {
          "href" : "..."
        }
      }
    } ]
  },
  "_links" : {
    "first" : {
      "href" : "..."
    },
    "last" : {
      "href" : "..."
    },
    "page" : {
      "href" : "..."
    },
    "self" : {
      "href" : "..."
    }
  },
  "page" : {
    "size" : 50,
    "totalElements" : 0,
    "totalPages" : 0,
    "number" : 0
  }
}

Response fields

Path Type Description
_embedded.conversations Array Conversation objects