Skip to main content

Messages

Messages are notes or updates related to a site visit.

Common operations:

  • GET /messages
  • POST /messages
  • GET /messages/{id}
  • PATCH /messages/{id}
  • POST /messages/{id}/file-attachment
  • GET /messages/{id}/file-attachment

List responses support page[size] and page[after]. When more records are available, use meta.nextCursor as the next page[after] value.

Client-writable fields:

  • type
  • messageThread
  • status
  • urgency
  • buyer
  • clientContacts

The API sets these fields internally:

  • method = Email
  • occurredAt = now
  • ssnPm = true

Create messages against an owned site visit by sending the SSN API site-visit ID. Include a unique Idempotency-Key for every create request.

POST /api/v1/messages
Authorization: Bearer YOUR_ACCESS_TOKEN
Idempotency-Key: import-2026-05-14-messages-row-000123
Content-Type: application/json
{
  "siteVisitId": "visit_0d995b97a85e4c64ad5594c2e74b69e4",
  "type": "Support",
  "messageThread": "Client note: technician should call before arrival.",
  "status": "Open",
  "urgency": "Normal",
  "buyer": true,
  "clientContacts": true
}

Use PATCH /messages/{id} to append to messageThread or update writable message fields. GET /messages/{id} responses include an ETag header. Send that value in If-Match when patching a message.

PATCH /api/v1/messages/msg_123
Authorization: Bearer YOUR_ACCESS_TOKEN
If-Match: "1"
Content-Type: application/json
{
  "messageThread": "Follow-up note: store manager confirmed the revised window.",
  "status": "Open"
}

Message attachments use the file upload workflow documented on File Uploads.

See the API Reference for the full message request and response schemas.