---
title: "List and filter all conversations available to the organization"
method: GET
path: "/conversations"
tags: ["Conversations"]
---

# List and filter all conversations available to the organization

`GET /conversations`

This operation lists all conversations available to the organization. This is an eventually consistent view and may take a short time before new conversations appear in results.


To iterate through all conversations in the organization, list the first page of conversations (without specifying `paginationToken` or `startFrom`). If `hasMore=true`, the provide the `paginationToken` to the API to list subsequent pages of conversations until `hasMore=false`.


## Detecting conversations with new messages

Note that the conversations are ordered by created date by default. You can also order them by the time of last activity in the conversation by specifying `orderBy=last_message`. This is particularly helpful when trying to determine conversations with new activity in them. In this particular case, you can query the list of conversations with `orderBy=last_message` and capture the `lastMessageAt` time for the last conversation in the list. On the next query, you can then `startFrom=<lastMessageAt time you saved>` and `orderBy=last_message` to return any conversations with new activity since your last query.


While you can determine the conversations with new activity, it is also important to know if the latest messages in each conversation were from your teammates or from an external contact (like a patient). To determine this, you can use the [listing of conversation items API](/reference/conversationitems) to query for the latest items since a particular time with the `startFrom` field. If any message in the list returned has `direction=inbound` then it indicates a message received since the last query for message items.

## Query parameters

- `pageSize` integer
- `paginationToken` string — Token given in a previous response to allow requesting the next page
- `orderBy` 'created' | 'last_message', required — The order of the conversations returned
- `startFrom` string, date-time

## Response `200`

Expected response to a valid request

- object
  - `conversations` Conversation[], required
    - `apiURL` string, url, required — An absolute URL for fetching this conversation from the API
    - `appURL` string, url, required — An absolute URL to view the conversation in the Spruce app
    - `archived` boolean, required — Whether or not the conversation is archived
    - `assignedToMemberId` string — The id of the teammate the conversation is assigned to
    - `associatedContactIds` string[] — The ids of the contacts associated with the conversation. This may include contacts that are not a part of the conversation. For example, the conversation may be with parents, but associated with a contact representing their child.
    - `createdAt` string, date-time, required — The date the conversation was created
    - `externalParticipants` object[] — The external participants in the conversation.
      - `contact` string — The id of the contact associated with the participant. This will be omitted if the participant is not a saved contact.
      - `displayName` string, required — The display name of the participant
      - `endpoint` Endpoint
        - `channel` 'email' | 'phone' | 'fax' | 'secure', required — The channel of the endpoint (e.g. 'email', 'phone', 'fax', etc.). More endpoint channels may be added in the future, so ensure while parsing this that you gracefully handle any new/unexpected values.
        - `displayValue` string, required — The display value of the endpoint. This is the value that should be displayed to the user when showing the endpoint, along with the label if it's populated.
        - `id` string, required — The id of the endpoint. For secure (Spruce Link) endpoints, the id format depends on where the endpoint is returned: the list internal endpoints API returns the underlying organization invite id, while a secure endpoint that appears on a conversation is returned with a different, derived value. To determine whether a conversation belongs to a particular Spruce Link, compare `endpoint.rawValue` rather than `endpoint.id`. Endpoint ids for phone, fax, and email channels use the same format across responses.
        - `isInternal` boolean, required — Internal endpoints are endpoints that are owned by your organization, such as your organization's Spruce Phone Numbers or Spruce Links.
        - `label` string — The optional label of the endpoint
        - `object` string, required — String representing the object's type
        - `rawValue` string, required — The raw value of the endpoint. This can be used for programmatically comparing contact values, and is the stable identifier to use when matching a secure endpoint on a conversation back to the corresponding Spruce Link returned by the list internal endpoints API. The raw value for a phone/fax number will be in E164 format.
    - `id` string, required — Spruce's conversation ID
    - `internalEndpoint` Endpoint
      - `channel` 'email' | 'phone' | 'fax' | 'secure', required — The channel of the endpoint (e.g. 'email', 'phone', 'fax', etc.). More endpoint channels may be added in the future, so ensure while parsing this that you gracefully handle any new/unexpected values.
      - `displayValue` string, required — The display value of the endpoint. This is the value that should be displayed to the user when showing the endpoint, along with the label if it's populated.
      - `id` string, required — The id of the endpoint. For secure (Spruce Link) endpoints, the id format depends on where the endpoint is returned: the list internal endpoints API returns the underlying organization invite id, while a secure endpoint that appears on a conversation is returned with a different, derived value. To determine whether a conversation belongs to a particular Spruce Link, compare `endpoint.rawValue` rather than `endpoint.id`. Endpoint ids for phone, fax, and email channels use the same format across responses.
      - `isInternal` boolean, required — Internal endpoints are endpoints that are owned by your organization, such as your organization's Spruce Phone Numbers or Spruce Links.
      - `label` string — The optional label of the endpoint
      - `object` string, required — String representing the object's type
      - `rawValue` string, required — The raw value of the endpoint. This can be used for programmatically comparing contact values, and is the stable identifier to use when matching a secure endpoint on a conversation back to the corresponding Spruce Link returned by the list internal endpoints API. The raw value for a phone/fax number will be in E164 format.
    - `internalMemberIds` string[] — The ids of the teammates, teams and/or your organization that are members of the conversation.
    - `isReadOnly` boolean, required — If the conversation is read-only, messages cannot be sent to it.
    - `lastMessageAt` string, date-time — The time of the conversations latest message
    - `object` string, required — String representing the object's type
    - `subtitle` string — The subtitle of the conversation
    - `tags` ConversationTag[], required
      - `id` string, required — Spruce's conversation tag ID
      - `object` string, required — String representing the object's type
      - `value` string, required — The text value of a conversation tag
    - `title` string, required — The title of the conversation
    - `type` 'email' | 'phone' | 'secure' | 'fax' | 'team' | 'note' | 'other', required — The type of the conversation (e.g. 'email', 'phone', 'secure', etc.). Note that SMS will be in a 'phone' conversation, and video calls will be in a 'secure' conversation. More conversation types may be added in the future, so ensure while parsing this that you gracefully handle any new/unexpected values.
  - `hasMore` boolean, required
  - `paginationToken` string — Token given in a previous response to allow requesting the next page
  - `totalCount` integer, required

## Other responses

- `400` — bad request
- `500` — unexpected error

---

[API](https://skmtc.net/sprucehealth/apis/spruce-health-api.md) · [All operations](https://skmtc.net/sprucehealth/apis/spruce-health-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/sprucehealth/spruce-health-api/revisions/988e298cd9fd/schema)