---
updatedAt: 2026-05-20T23:04:33.000Z
agentTools:
  projectIndex: https://developer.sprucehealth.com/llms.txt
---

# Update a conversation

This operation updates a specific conversation by id.

Fields provided in the input object will be updated, omitted fields *(null)* will be unchanged.

# OpenAPI definition

```json
{
  "components": {
    "headers": {
      "s-ratelimit-limit": {
        "description": "Request limit per minute",
        "example": 100,
        "schema": {
          "type": "integer"
        }
      },
      "s-ratelimit-remaining": {
        "description": "Requests remaining this minute",
        "example": 94,
        "schema": {
          "type": "integer"
        }
      },
      "s-request-id": {
        "description": "The ID of the request",
        "example": "0E5QDGJC030000E5QDGJC03000",
        "schema": {
          "type": "string"
        }
      }
    },
    "parameters": {
      "s-idempotency-key": {
        "description": "A unique value generated by the client used to recognize subsequent retries of the same request. Idempotency keys can be up to 255 characters long.",
        "example": "S7uiKYMMRzAcuG8S",
        "in": "header",
        "name": "s-idempotency-key",
        "required": false,
        "schema": {
          "type": "string"
        }
      }
    },
    "schemas": {
      "conversation": {
        "properties": {
          "apiURL": {
            "description": "An absolute URL for fetching this conversation from the API",
            "example": "https://api.sprucehealth.com/conversations/t_0E5QDJJC03000",
            "format": "url",
            "type": "string"
          },
          "appURL": {
            "description": "An absolute URL to view the conversation in the Spruce app",
            "example": "https://app.sprucehealth.com/org/entity_0D4QABCC06000/thread/t_0E5QDJJC03000",
            "format": "url",
            "type": "string"
          },
          "archived": {
            "description": "Whether or not the conversation is archived",
            "example": false,
            "type": "boolean"
          },
          "assignedToMemberId": {
            "description": "The id of the teammate the conversation is assigned to",
            "example": "entity_0D4QABCC06000",
            "type": "string"
          },
          "associatedContactIds": {
            "description": "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.",
            "example": [
              "entity_0D4QABCC06000"
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "createdAt": {
            "description": "The date the conversation was created",
            "example": "2020-04-01T00:00:00Z",
            "format": "date-time",
            "type": "string"
          },
          "externalParticipants": {
            "description": "The external participants in the conversation.",
            "items": {
              "properties": {
                "contact": {
                  "description": "The id of the contact associated with the participant. This will be omitted if the participant is not a saved contact.",
                  "example": "entity_0D4QABCC06000",
                  "type": "string"
                },
                "displayName": {
                  "description": "The display name of the participant",
                  "example": [
                    "555-555-5555",
                    "John Doe",
                    "patient@example.com"
                  ],
                  "type": "string"
                },
                "endpoint": {
                  "$ref": "#/components/schemas/endpoint",
                  "description": "The endpoint of the participant, such as their phone number or email address. For secure conversations, there will not be an endpoint."
                }
              },
              "required": [
                "displayName"
              ],
              "type": "object"
            },
            "type": "array"
          },
          "id": {
            "$ref": "#/components/schemas/conversation_id"
          },
          "internalEndpoint": {
            "$ref": "#/components/schemas/endpoint",
            "description": "The internal endpoint of the conversation. For secure conversations, this will be a Spruce Link.\n\nNote: for secure endpoints, the `id` returned here is a derived value that will not equal the `endpoint.id` returned for the same Spruce Link by the list internal endpoints API. Use `rawValue` to match a conversation's secure internal endpoint to the corresponding Spruce Link. Endpoint ids for phone, fax, and email channels use the same format across responses and can be compared directly.\n"
          },
          "internalMemberIds": {
            "description": "The ids of the teammates, teams and/or your organization that are members of the conversation.",
            "example": [
              "entity_0D4QABCC06000"
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "isReadOnly": {
            "description": "If the conversation is read-only, messages cannot be sent to it.",
            "example": false,
            "type": "boolean"
          },
          "lastMessageAt": {
            "description": "The time of the conversations latest message",
            "example": "2020-04-01T00:00:00Z",
            "format": "date-time",
            "type": "string"
          },
          "object": {
            "$ref": "#/components/schemas/objectType"
          },
          "subtitle": {
            "description": "The subtitle of the conversation",
            "example": "Billing",
            "type": "string"
          },
          "tags": {
            "$ref": "#/components/schemas/conversation_tags"
          },
          "title": {
            "description": "The title of the conversation",
            "example": "John Doe",
            "type": "string"
          },
          "type": {
            "description": "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.",
            "enum": [
              "email",
              "phone",
              "secure",
              "fax",
              "team",
              "note",
              "other"
            ],
            "type": "string"
          }
        },
        "required": [
          "appURL",
          "apiURL",
          "archived",
          "createdAt",
          "id",
          "isReadOnly",
          "tags",
          "type",
          "title",
          "object"
        ],
        "type": "object"
      },
      "conversation_id": {
        "description": "Spruce's conversation ID",
        "example": "t_0E5QDGJC03000",
        "type": "string"
      },
      "conversation_tag": {
        "properties": {
          "id": {
            "$ref": "#/components/schemas/conversation_tagId"
          },
          "object": {
            "$ref": "#/components/schemas/objectType"
          },
          "value": {
            "$ref": "#/components/schemas/conversation_tagValue"
          }
        },
        "required": [
          "id",
          "value",
          "object"
        ],
        "type": "object"
      },
      "conversation_tagId": {
        "description": "Spruce's conversation tag ID",
        "example": "tag_0E5QDGJC03000",
        "type": "string"
      },
      "conversation_tagIds": {
        "description": "An array of Spruce conversation tag ids",
        "items": {
          "$ref": "#/components/schemas/conversation_tagId"
        },
        "type": "array"
      },
      "conversation_tagValue": {
        "description": "The text value of a conversation tag",
        "example": "Smith",
        "type": "string"
      },
      "conversation_tags": {
        "items": {
          "$ref": "#/components/schemas/conversation_tag"
        },
        "type": "array"
      },
      "endpoint": {
        "properties": {
          "channel": {
            "description": "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.",
            "enum": [
              "email",
              "phone",
              "fax",
              "secure"
            ],
            "type": "string"
          },
          "displayValue": {
            "description": "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.",
            "example": {
              "email": {
                "value": "patient@example.com"
              },
              "phone": {
                "value": "(555) 555-5555"
              },
              "secure": {
                "value": "spruce.care/123456"
              }
            },
            "type": "string"
          },
          "id": {
            "$ref": "#/components/schemas/endpoint_id"
          },
          "isInternal": {
            "description": "Internal endpoints are endpoints that are owned by your organization, such as your organization's Spruce Phone Numbers or Spruce Links.",
            "example": false,
            "type": "boolean"
          },
          "label": {
            "description": "The optional label of the endpoint",
            "example": [
              "Home",
              "Work"
            ],
            "type": "string"
          },
          "object": {
            "$ref": "#/components/schemas/objectType"
          },
          "rawValue": {
            "description": "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.",
            "example": {
              "email": {
                "value": "patient@example.com"
              },
              "phone": {
                "value": 15555555555
              },
              "secure": {
                "value": "https://spruce.care/123456"
              }
            },
            "type": "string"
          }
        },
        "required": [
          "id",
          "channel",
          "displayValue",
          "rawValue",
          "isInternal",
          "object"
        ],
        "type": "object"
      },
      "endpoint_id": {
        "description": "The id of the endpoint.\n\nFor 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.\n",
        "example": 15555555555,
        "type": "string"
      },
      "error": {
        "properties": {
          "message": {
            "example": "Invalid Contact ID",
            "type": "string"
          },
          "statusCode": {
            "example": 400,
            "type": "integer"
          },
          "type": {
            "example": "BAD_PARAMETER",
            "type": "string"
          }
        },
        "required": [
          "message",
          "statusCode",
          "type"
        ],
        "type": "object"
      },
      "objectType": {
        "description": "String representing the object's type",
        "type": "string"
      },
      "updateConversation": {
        "description": "Any omitted or null field will not be updated. To clear a field, pass an empty value such as \"\" or []",
        "properties": {
          "archived": {
            "description": "Whether the conversation should be archived (true) or unarchived (false)",
            "type": "boolean"
          },
          "assignToMemberId": {
            "description": "The id of a team or teammate to assign the conversation to. If the specified teammate or team is not a member of the conversation, they will be added as a member.",
            "example": "entity_0D4QABCC06000",
            "type": "string"
          },
          "associatedContactIds": {
            "description": "The ids of the contacts the conversation is regarding. Associated contacts do not gain access to the conversation. Team conversations cannot have associated contacts.",
            "example": [
              "entity_0D4QABCC06000"
            ],
            "items": {
              "type": "string"
            },
            "type": "array"
          },
          "tagIds": {
            "$ref": "#/components/schemas/conversation_tagIds"
          }
        },
        "type": "object"
      }
    },
    "securitySchemes": {
      "spruceAPIToken": {
        "description": "API token provided by Spruce should be passed in an \"Authorization\" header with the value \"Bearer <token>\"",
        "scheme": "bearer",
        "type": "http"
      }
    }
  },
  "info": {
    "title": "Spruce Health API",
    "version": "1.0.0"
  },
  "openapi": "3.0.0",
  "paths": {
    "/conversations/{conversationId}": {
      "patch": {
        "description": "This operation updates a specific conversation by id.\n\nFields provided in the input object will be updated, omitted fields *(null)* will be unchanged.",
        "operationId": "UpdateConversation",
        "parameters": [
          {
            "$ref": "#/components/parameters/s-idempotency-key"
          },
          {
            "description": "The id of the conversation to update",
            "in": "path",
            "name": "conversationId",
            "required": true,
            "schema": {
              "type": "string"
            }
          }
        ],
        "requestBody": {
          "content": {
            "application/json": {
              "schema": {
                "$ref": "#/components/schemas/updateConversation",
                "description": "Conversation json object. Omitted fields are not updated."
              }
            }
          },
          "required": true
        },
        "responses": {
          "200": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/conversation"
                }
              }
            },
            "description": "ok response",
            "headers": {
              "s-ratelimit-limit": {
                "$ref": "#/components/headers/s-ratelimit-limit"
              },
              "s-ratelimit-remaining": {
                "$ref": "#/components/headers/s-ratelimit-remaining"
              },
              "s-request-id": {
                "$ref": "#/components/headers/s-request-id"
              }
            }
          },
          "400": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/error"
                }
              }
            },
            "description": "bad request"
          },
          "404": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/error"
                }
              }
            },
            "description": "not found"
          },
          "422": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/error"
                }
              }
            },
            "description": "duplicate request"
          },
          "500": {
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/error"
                }
              }
            },
            "description": "unexpected error"
          }
        },
        "summary": "Update a conversation",
        "tags": [
          "Conversations"
        ]
      }
    }
  },
  "security": [
    {
      "spruceAPIToken": []
    }
  ],
  "servers": [
    {
      "url": "https://api.sprucehealth.com/v1",
      "variables": {
        "domain": {
          "default": "api.sprucehealth.com"
        }
      }
    }
  ]
}
```