/v1/leads/{lead_id}/communicationsAuthentication
Bearer API key or Facily session, subject to permissions and facility scope.
Authentication and scopeRequest 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 --request GET \
--url 'https://api.staging.facily.ai/v1/leads/<LEAD_ID>/communications' \
--header "Authorization: Bearer $FACILY_API_KEY"Try a request
Staging · read-onlyExplore your organization with a read-only request to staging.
Parameters
lead_idpath · stringrequiredFormat: uuid
cursorquery · string | nulllimitquery · integerDefault: 50 · Minimum: 1 · Maximum: 200
Responses
Expand a status to inspect its schema. Generated examples show structure and synthetic values.
200Successful Response
{
"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[]requiredShow data schema
attachmentsCommunicationAttachmentResponse[]Files attached to the message.
Show attachments schema
document_idstring | nullFormat: uuid
Show document_id schema
string | nullVariant 1: string
stringVariant 2: null
nullfilenamestringrequiredmime_typestringrequiredsize_bytesintegerrequiredbody_previewstring | nullShort 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 | nullShort 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
stringVariant 2: null
nullchannelstringrequiredHow the message travelled, for example email or SMS.
contact_addressstring | nullThe 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 | nullThe 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
stringVariant 2: null
nullcontact_address_sourcestring | nullHow `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 | nullHow `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
stringValues: "message", "tenant_record"
Variant 2: null
nullcreated_atstringrequiredWhen the message record was created.
Format: date-time
delivered_atstring | nullWhen the provider confirmed delivery. Null when unconfirmed.
Format: date-time
Show delivered_at schema
string | nullWhen the provider confirmed delivery. Null when unconfirmed.
Variant 1: string
stringVariant 2: null
nulldirectionstringrequiredWhether the message was outbound to the tenant or inbound from them.
facility_idstringrequiredThe facility the message relates to.
Format: uuid
failed_atstring | nullWhen delivery failed, if it did.
Format: date-time
Show failed_at schema
string | nullWhen delivery failed, if it did.
Variant 1: string
stringVariant 2: null
nullfailure_reasonstring | nullWhy delivery failed.
Show failure_reason schema
string | nullWhy delivery failed.
Variant 1: string
stringVariant 2: null
nullidstringrequiredUnique identifier for this message.
Format: uuid
lead_idstring | nullThe lead the message was sent to, for a message to a lead.
Format: uuid
Show lead_id schema
string | nullThe lead the message was sent to, for a message to a lead.
Variant 1: string
stringVariant 2: null
nulllease_idstring | nullThe lease the message concerns, where it is about one specifically.
Format: uuid
Show lease_id schema
string | nullThe lease the message concerns, where it is about one specifically.
Variant 1: string
stringVariant 2: null
nullmatchstring | nullHow 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 | nullHow 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
stringValues: "token", "last_outbound", "record", "unmatched", "linked"
Variant 2: null
nullopened_atstring | nullWhen the recipient first opened the message, where the channel supports tracking.
Format: date-time
Show opened_at schema
string | nullWhen the recipient first opened the message, where the channel supports tracking.
Variant 1: string
stringVariant 2: null
nulloriginstringWhere 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 | nullThe delivery provider's own identifier, for tracing a message end to end.
Show provider_message_id schema
string | nullThe delivery provider's own identifier, for tracing a message end to end.
Variant 1: string
stringVariant 2: null
nullread_atstring | nullWhen 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 | nullWhen 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
stringVariant 2: null
nullread_bystring | nullThe staff member who marked it read.
Format: uuid
Show read_by schema
string | nullThe staff member who marked it read.
Variant 1: string
stringVariant 2: null
nullreaderstring | nullThe 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 | nullThe 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
stringVariant 2: null
nullrecipient_emailstring | nullAddress the message was sent to, for an email.
Show recipient_email schema
string | nullAddress the message was sent to, for an email.
Variant 1: string
stringVariant 2: null
nullrecipient_phonestring | nullThe tenant's number for an SMS: where an outbound message was sent, and where an inbound one came from.
Show recipient_phone schema
string | nullThe tenant's number for an SMS: where an outbound message was sent, and where an inbound one came from.
Variant 1: string
stringVariant 2: null
nullreviewCommunicationReviewResponse | nullSet when a received email waits for staff to enter it by hand.
Show review schema
CommunicationReviewResponse | nullSet when a received email waits for staff to enter it by hand.
Variant 1: CommunicationReviewResponse
outcomestringrequiredWhat the reader made of it.
readerstringrequiredThe lead-email reader that sent the message to review.
reasonstring | nullWhy it needs a person, for example the sender was not verified.
Show reason schema
string | nullWhy it needs a person, for example the sender was not verified.
Variant 1: string
Variant 2: null
Variant 2: null
nullsender_emailstring | nullAddress the message was sent from.
Show sender_email schema
string | nullAddress the message was sent from.
Variant 1: string
stringVariant 2: null
nullsender_namestring | nullThe display name a received email came from, as its sender wrote it.
Show sender_name schema
string | nullThe display name a received email came from, as its sender wrote it.
Variant 1: string
stringVariant 2: null
nullsent_atstring | nullWhen the message was handed to the delivery provider.
Format: date-time
Show sent_at schema
string | nullWhen the message was handed to the delivery provider.
Variant 1: string
stringVariant 2: null
nullstatusstringrequiredDelivery state, for example queued, sent, delivered, failed, or suppressed.
subjectstring | nullSubject line. Present for email, absent for SMS.
Show subject schema
string | nullSubject line. Present for email, absent for SMS.
Variant 1: string
stringVariant 2: null
nulltemplate_idstring | nullThe template the message was rendered from, where one was used.
Format: uuid
Show template_id schema
string | nullThe template the message was rendered from, where one was used.
Variant 1: string
stringVariant 2: null
nulltenant_idstring | nullThe tenant the message was sent to or received from.
Format: uuid
Show tenant_id schema
string | nullThe tenant the message was sent to or received from.
Variant 1: string
stringVariant 2: null
nulltenant_namestring | nullDisplay name of the linked tenant, so a row can name them without a second request.
Show tenant_name schema
string | nullDisplay name of the linked tenant, so a row can name them without a second request.
Variant 1: string
stringVariant 2: null
nulltrigger_keystring | nullThe automated event that caused the message, for a message the platform sent on its own.
Show trigger_key schema
string | nullThe automated event that caused the message, for a message the platform sent on its own.
Variant 1: string
stringVariant 2: null
nullupdated_atstringrequiredWhen the message record was last modified.
Format: date-time
metaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequiredmetricsEmbeddedMetrics | nullShow metrics schema
EmbeddedMetrics | nullVariant 1: EmbeddedMetrics
cardsobjectrequiredcomputed_atstring | nullrequiredFormat: date-time
Show computed_at schema
string | nullVariant 1: string
stringVariant 2: null
nullis_stalebooleanrequiredscopestringrequiredValues: "facility", "portfolio"
Variant 2: null
nullpaginationPaginationBlockrequiredPagination metadata for list responses.
Show pagination schema
cursorstring | nullShow cursor schema
string | nullVariant 1: string
stringVariant 2: null
nullhas_morebooleanrequiredlimitintegerrequiredtotal_countinteger | nullShow total_count schema
integer | nullVariant 1: integer
integerVariant 2: null
null400Validation error
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired401Unauthenticated
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired403Permission denied
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired404Not found
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired409Business logic error
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired503Temporary failure
{
"error": {
"code": "string",
"message": "string",
"details": {}
},
"meta": {
"request_id": "string"
}
}application/json
errorErrorBodyrequiredThe shape of error.* in an error response.
Show error schema
codestringrequireddetailsobject | nullShow details schema
object | nullVariant 1: object
objectVariant 2: null
nullmessagestringrequiredmetaMetarequiredEnvelope metadata. Every response carries one.
Show meta schema
request_idstringrequired