Get Conversation

Request

GET /v2/conversations/123 HTTP/1.1
Authorization: Bearer oauth_token

URL Parameters

Parameter Description
embed Allows embedding/loading of sub-entities, allowed values are:
threads

Moved or merged conversation

When a conversation is moved to a new mailbox or it is merged with another conversation, it is no longer accessible. The request will return a HTTP 301 Moved Permanently status code and the response will contain a Location header with the URI of the new conversation.

Response

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

{
  "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" : "..."
    }
  }
}

Response fields

Path Type Description
id Number Unique identifier
number Number Number
threads Number Number of threads the conversation has
type String Type of the conversation, one of:
chat
email
phone
folderId Number Id of the folder
status String Status of the conversation, one of:
active
all
closed
open
pending
spam
state String State of the conversation, one of
deleted
draft
published
subject String Subject
preview String Preview text from the start of the conversation
mailboxId Number Mailbox ID
assignee Object Who the conversation is assigned to. Contains a name, id and email of the user
createdBy Object Id, email and type of who created the conversation
createdAt String UTC time when the conversation was created
closedBy Number Id of the user that closed the conversation
closedAt String UTC time when the conversation was closed
userUpdatedAt String UTC time when the last user update occurred
customerWaitingSince Object Object containing the timestamp of when the conversation was last updated
source.via String Originating source of the conversation - user or customer
source.type String Originating type of the conversation (email, web, API etc)
tags Array List of tags
cc Array List of emails that are cc’d
bcc Array List of emails that are bcc’d
primaryCustomer Object The primary customer in the conversation
customFields Array Custom field values

Customer Waiting Since object

Path Type Description
time String UTC time since the last reply sent to the customer
friendly String Friendly string version of the waiting period
latestReplyFrom String Whether the last reply was from a user or a customer

Custom Fields

Path Type Description
[].id Number Custom field’s unique ID
[].name String Custom field’s name
[].value String Custom field’s value. The value type depends on custom field type. It contains an option ID for dropdown custom field type for example.
Relation Description
mailbox The mailbox of where the conversation resides
primaryCustomer The primary customer of the conversation
createdByCustomer The customer who created the conversation
createdByUser The user who created the conversation
closedBy The user who closed the conversation
threads conversation threads
assignee User who is assignee (owner) of the conversation
web Link that will open this conversation in Help Scout web application (might require login)