Skip to content
FacilydevelopersDashboard
Build with Facily
DocsREST APIsList Lead Communications
Search the full API reference Esc to close

List Lead Communications

Leads · REST API reference

Get support
GET/v1/leads/{lead_id}/communications
The messages sent to one lead, newest first. Needs permission to read the lead and its facility's messages.

Authentication

Bearer API key or Facily session, subject to permissions and facility scope.

Authentication and scope

Request example

Replace bracketed path values with real IDs from your environment. The body, where shown, is generated from the schema and uses illustrative values.

cURL
curl --request GET \
  --url 'https://api.staging.facily.ai/v1/leads/<LEAD_ID>/communications' \
  --header "Authorization: Bearer $FACILY_API_KEY"
An example for building your request, not an executed call. Check required fields, allowed values, and environment configuration before sending.

Try a request

Staging · read-only

Explore your organization with a read-only request to staging.

Kept in this tab only. Sent directly to api.staging.facily.ai.

GET

Replace the {placeholders} in the path with your resource IDs.

Response
Your response will appear here.

Parameters

lead_idpath · stringrequired

Format: uuid

cursorquery · string | null
limitquery · integer

Default: 50 · Minimum: 1 · Maximum: 200

Responses

Expand a status to inspect its schema. Generated examples show structure and synthetic values.

200Successful Response
JSON · generated example
{
  "data": [
    {
      "channel": "string",
      "created_at": "2026-10-29T12:00:00Z",
      "direction": "string",
      "facility_id": "00000000-0000-4000-8000-000000000001",
      "id": "00000000-0000-4000-8000-000000000001",
      "status": "string",
      "updated_at": "2026-10-29T12:00:00Z",
      "attachments": [
        {
          "filename": "string",
          "mime_type": "string",
          "size_bytes": 0,
          "document_id": "00000000-0000-4000-8000-000000000001"
        }
      ],
      "body_preview": "string",
      "contact_address": "string",
      "contact_address_source": "message",
      "delivered_at": "2026-10-29T12:00:00Z"
    }
  ],
  "meta": {
    "request_id": "string"
  },
  "pagination": {
    "has_more": false,
    "limit": 0,
    "cursor": "string",
    "total_count": 0
  },
  "metrics": {
    "cards": {},
    "computed_at": "2026-10-29T12:00:00Z",
    "is_stale": false,
    "scope": "facility"
  }
}

application/json

dataCommunicationResponse[]required
Show data schema
attachmentsCommunicationAttachmentResponse[]

Files attached to the message.

Show attachments schema
document_idstring | null

Format: uuid

Show document_id schema
string | null
Variant 1: string
string
Variant 2: null
null
filenamestringrequired
mime_typestringrequired
size_bytesintegerrequired
body_previewstring | null

Short plain-text extract of an SMS body, so a list row can be read without opening the message. Null for every other channel, and truncated -- the full body is on the detail route.

Show body_preview schema
string | null

Short plain-text extract of an SMS body, so a list row can be read without opening the message. Null for every other channel, and truncated -- the full body is on the detail route.

Variant 1: string
string
Variant 2: null
null
channelstringrequired

How the message travelled, for example email or SMS.

contact_addressstring | null

The other party's email address or phone number: where an outbound message was sent, or where an inbound one came from. Raw, not formatted for display.

Show contact_address schema
string | null

The other party's email address or phone number: where an outbound message was sent, or where an inbound one came from. Raw, not formatted for display.

Variant 1: string
string
Variant 2: null
null
contact_address_sourcestring | null

How `contact_address` is known. `message`: recorded on the message itself. `tenant_record`: the message records no address (an imported inbound message), so this is the tenant's address on file today, which is not necessarily the one they wrote from. Null when there is no address.

Values: "message", "tenant_record"

Show contact_address_source schema
string | null

How `contact_address` is known. `message`: recorded on the message itself. `tenant_record`: the message records no address (an imported inbound message), so this is the tenant's address on file today, which is not necessarily the one they wrote from. Null when there is no address.

Variant 1: string
string

Values: "message", "tenant_record"

Variant 2: null
null
created_atstringrequired

When the message record was created.

Format: date-time

delivered_atstring | null

When the provider confirmed delivery. Null when unconfirmed.

Format: date-time

Show delivered_at schema
string | null

When the provider confirmed delivery. Null when unconfirmed.

Variant 1: string
string
Variant 2: null
null
directionstringrequired

Whether the message was outbound to the tenant or inbound from them.

facility_idstringrequired

The facility the message relates to.

Format: uuid

failed_atstring | null

When delivery failed, if it did.

Format: date-time

Show failed_at schema
string | null

When delivery failed, if it did.

Variant 1: string
string
Variant 2: null
null
failure_reasonstring | null

Why delivery failed.

Show failure_reason schema
string | null

Why delivery failed.

Variant 1: string
string
Variant 2: null
null
idstringrequired

Unique identifier for this message.

Format: uuid

lead_idstring | null

The lead the message was sent to, for a message to a lead.

Format: uuid

Show lead_id schema
string | null

The lead the message was sent to, for a message to a lead.

Variant 1: string
string
Variant 2: null
null
lease_idstring | null

The lease the message concerns, where it is about one specifically.

Format: uuid

Show lease_id schema
string | null

The lease the message concerns, where it is about one specifically.

Variant 1: string
string
Variant 2: null
null
matchstring | null

How a received message found its tenant or lead: `token`, it answered a message sent to them; `last_outbound`, they were the last person the facility wrote to at this address; `record`, the only tenant or open lead with this address; `unmatched`, nobody; `linked`, staff linked it, or the lead-email reader linked it to the lead it entered or found. Null for a message the platform sent.

Values: "token", "last_outbound", "record", "unmatched", "linked"

Show match schema
string | null

How a received message found its tenant or lead: `token`, it answered a message sent to them; `last_outbound`, they were the last person the facility wrote to at this address; `record`, the only tenant or open lead with this address; `unmatched`, nobody; `linked`, staff linked it, or the lead-email reader linked it to the lead it entered or found. Null for a message the platform sent.

Variant 1: string
string

Values: "token", "last_outbound", "record", "unmatched", "linked"

Variant 2: null
null
opened_atstring | null

When the recipient first opened the message, where the channel supports tracking.

Format: date-time

Show opened_at schema
string | null

When the recipient first opened the message, where the channel supports tracking.

Variant 1: string
string
Variant 2: null
null
originstring

Where the record came from. `facily`: sent or received by this platform. The other values are records imported from a previous management system: `storedge_delivery_log` from its delivery log, which records that a message was sent and never what it said, so the record has no body; `storedge_conversation` and `storedge_sms` from its threaded email and SMS history; `imported` from any other import.

Default: "facily" · Values: "facily", "storedge_delivery_log", "storedge_conversation", "storedge_sms", "imported"

provider_message_idstring | null

The delivery provider's own identifier, for tracing a message end to end.

Show provider_message_id schema
string | null

The delivery provider's own identifier, for tracing a message end to end.

Variant 1: string
string
Variant 2: null
null
read_atstring | null

When staff read this received message; null while it is unread. Read state is shared by the facility's staff. Always null for a message the platform sent.

Format: date-time

Show read_at schema
string | null

When staff read this received message; null while it is unread. Read state is shared by the facility's staff. Always null for a message the platform sent.

Variant 1: string
string
Variant 2: null
null
read_bystring | null

The staff member who marked it read.

Format: uuid

Show read_by schema
string | null

The staff member who marked it read.

Variant 1: string
string
Variant 2: null
null
readerstring | null

The lead-email reader that claimed this received email (for example `sparefoot`): it came from a vendor's notification address, not from the person it is about. Only the reader links it on arrival; staff linking it moves this message alone, never the vendor's other mail. Null for every other message.

Show reader schema
string | null

The lead-email reader that claimed this received email (for example `sparefoot`): it came from a vendor's notification address, not from the person it is about. Only the reader links it on arrival; staff linking it moves this message alone, never the vendor's other mail. Null for every other message.

Variant 1: string
string
Variant 2: null
null
recipient_emailstring | null

Address the message was sent to, for an email.

Show recipient_email schema
string | null

Address the message was sent to, for an email.

Variant 1: string
string
Variant 2: null
null
recipient_phonestring | null

The tenant's number for an SMS: where an outbound message was sent, and where an inbound one came from.

Show recipient_phone schema
string | null

The tenant's number for an SMS: where an outbound message was sent, and where an inbound one came from.

Variant 1: string
string
Variant 2: null
null
reviewCommunicationReviewResponse | null

Set when a received email waits for staff to enter it by hand.

Show review schema
CommunicationReviewResponse | null

Set when a received email waits for staff to enter it by hand.

Variant 1: CommunicationReviewResponse
outcomestringrequired

What the reader made of it.

readerstringrequired

The lead-email reader that sent the message to review.

reasonstring | null

Why it needs a person, for example the sender was not verified.

Show reason schema
string | null

Why it needs a person, for example the sender was not verified.

Variant 1: string
Variant 2: null
Variant 2: null
null
sender_emailstring | null

Address the message was sent from.

Show sender_email schema
string | null

Address the message was sent from.

Variant 1: string
string
Variant 2: null
null
sender_namestring | null

The display name a received email came from, as its sender wrote it.

Show sender_name schema
string | null

The display name a received email came from, as its sender wrote it.

Variant 1: string
string
Variant 2: null
null
sent_atstring | null

When the message was handed to the delivery provider.

Format: date-time

Show sent_at schema
string | null

When the message was handed to the delivery provider.

Variant 1: string
string
Variant 2: null
null
statusstringrequired

Delivery state, for example queued, sent, delivered, failed, or suppressed.

subjectstring | null

Subject line. Present for email, absent for SMS.

Show subject schema
string | null

Subject line. Present for email, absent for SMS.

Variant 1: string
string
Variant 2: null
null
template_idstring | null

The template the message was rendered from, where one was used.

Format: uuid

Show template_id schema
string | null

The template the message was rendered from, where one was used.

Variant 1: string
string
Variant 2: null
null
tenant_idstring | null

The tenant the message was sent to or received from.

Format: uuid

Show tenant_id schema
string | null

The tenant the message was sent to or received from.

Variant 1: string
string
Variant 2: null
null
tenant_namestring | null

Display name of the linked tenant, so a row can name them without a second request.

Show tenant_name schema
string | null

Display name of the linked tenant, so a row can name them without a second request.

Variant 1: string
string
Variant 2: null
null
trigger_keystring | null

The automated event that caused the message, for a message the platform sent on its own.

Show trigger_key schema
string | null

The automated event that caused the message, for a message the platform sent on its own.

Variant 1: string
string
Variant 2: null
null
updated_atstringrequired

When the message record was last modified.

Format: date-time

metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
metricsEmbeddedMetrics | null
Show metrics schema
EmbeddedMetrics | null
Variant 1: EmbeddedMetrics
cardsobjectrequired
computed_atstring | nullrequired

Format: date-time

Show computed_at schema
string | null
Variant 1: string
string
Variant 2: null
null
is_stalebooleanrequired
scopestringrequired

Values: "facility", "portfolio"

Variant 2: null
null
paginationPaginationBlockrequired

Pagination metadata for list responses.

Show pagination schema
cursorstring | null
Show cursor schema
string | null
Variant 1: string
string
Variant 2: null
null
has_morebooleanrequired
limitintegerrequired
total_countinteger | null
Show total_count schema
integer | null
Variant 1: integer
integer
Variant 2: null
null
400Validation error
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
401Unauthenticated
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
403Permission denied
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
404Not found
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
409Business logic error
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
503Temporary failure
JSON · generated example
{
  "error": {
    "code": "string",
    "message": "string",
    "details": {}
  },
  "meta": {
    "request_id": "string"
  }
}

application/json

errorErrorBodyrequired

The shape of error.* in an error response.

Show error schema
codestringrequired
detailsobject | null
Show details schema
object | null
Variant 1: object
object
Variant 2: null
null
messagestringrequired
metaMetarequired

Envelope metadata. Every response carries one.

Show meta schema
request_idstringrequired
Continue exploringAll leads operations
Build something that works beautifully.

Facily API · Contract v1.200 · Reviewed October 29, 2026

List Lead Communications | Facily Developers