Shares · API documentation

A run's results shared with a client: the share, the email, what the client answered.

POST/api/v1/runs/{runId}/shares

Shares a complete run's results with a client who has access: the homes you name, in order, else the results as they stand, shown at the depth you choose. 201 for a new share. Sharing again with the same client updates their live share (200) rather than making a second one, so the call is safe to retry.

A run is shared with the client its search is for, so clientId may be left out; a different client is refused with wrong-client. The client must have access (POST /api/v1/clients/{clientId}/access), or the answer is client-has-no-access. A share to a client with no email is refused for Homes for sale runs, which reach clients by email only.

Sharing does not email anyone and does not create a public /s/{token} link. Email the share sends a signed-in portal link.

A share can name only homes in the results; add one first with PUT .../results.

An API key carrying the scope named here, or a signed-in session.

Scope: shares:write
Key kinds: PersonalOrganization

Required and optional fields, allowed values and errors, as the page shows them.

Parameters

Name	In	Type	Required	Description
`runId`	Path	`string (uuid)`	Required	The run's id.

Request body

How to share. Every field is optional but the run's search must have a client.

Fields (4)

Field	Type	Required	Description
`clientId`	`string (uuid)`	Optional	The client to share with. Left out, it is the client the run's search is for. They must have access (`POST /api/v1/clients/{clientId}/access`).
`depth`	`"specs" \| "summary" \| "full"`	Optional	How much of the analysis each home shows the client: `specs` (the facts), `summary` (the facts and the take) or `full` (the reasoning too).default "summary"
`homes`	`string[]`	Optional	The homes to share, in order, as `results[].id` from the run. Left out, the results as they stand are shared (up to twenty).1 to 20 items
`expiresAt`	`string (date-time) \| null`	Optional	When the share ends, as ISO 8601 in the future, or null for no end. Left out, a new share has no end and an existing one keeps its own.

Examples

{
  "depth": "summary",
  "homes": [
    "NSH-2283104",
    "NSH-2279012"
  ]
}

Examples

curl -X POST "https://liviamatch.com/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares" \
  -H "Authorization: Bearer $LIVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "depth": "summary",
  "homes": [
    "NSH-2283104",
    "NSH-2279012"
  ]
}'

Responses

201

A new share was made.

HeadersLocation

A new share

{
  "data": {
    "id": "d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
    "clientId": "9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28",
    "status": "live",
    "depth": "summary",
    "homeCount": 2,
    "homes": [
      "NSH-2283104",
      "NSH-2279012"
    ],
    "expiresAt": null,
    "revokedAt": null,
    "lastEmailedAt": null,
    "createdAt": "2026-10-06T14:20:03.118Z",
    "updatedAt": "2026-10-06T14:20:03.118Z",
    "reactions": [],
    "runId": "1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
    "links": {
      "self": "/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
      "email": "/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41/email",
      "run": "/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
      "client": "/api/v1/clients/9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28"
    }
  }
}

Fields (23)

Field	Type	Description
`data`	`object`
`data.id`	`string (uuid)`
`data.runId`	`string (uuid)`
`data.clientId`	`string (uuid)`
`data.status`	`"live" \| "stopped" \| "ended"`	`live` can be opened now; `stopped` was stopped by you; `ended` is past its `expiresAt`.
`data.depth`	`"specs" \| "summary" \| "full"`	How much of the analysis each home shows the client.
`data.homeCount`	`integer`	How many homes the client sees.
`data.homes`	`string[] \| null`	The curated, ordered package of home ids; null when the client sees the results by score, the first `homeCount`.
`data.expiresAt`	`string (date-time) \| null`
`data.revokedAt`	`string (date-time) \| null`	When you stopped it; null while it has not been stopped.
`data.lastEmailedAt`	`string (date-time) \| null`	When the client was last emailed that it is ready; null if they never were.
`data.createdAt`	`string (date-time)`
`data.updatedAt`	`string (date-time)`
`data.reactions`	`object[]`	What the client answered on each home, newest first. Empty until they open it.
`data.reactions[].homeId`	`string`
`data.reactions[].vote`	`"up" \| "down"`	`up` or `down`.
`data.reactions[].comment`	`string \| null`	What they wrote, or null.
`data.reactions[].updatedAt`	`string (date-time)`
`data.links`	`object`
`data.links.self`	`string`	This share's API URL.
`data.links.email`	`string`	Where to POST to email the client a signed-in portal link.
`data.links.run`	`string`	The run this share belongs to.
`data.links.client`	`string`	The client API URL. They open the homes in the product at `/client` after sign-in, not here.

200

The client's live share was updated.

HeadersLocation

An updated share

{
  "data": {
    "id": "d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
    "clientId": "9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28",
    "status": "live",
    "depth": "summary",
    "homeCount": 2,
    "homes": [
      "NSH-2283104",
      "NSH-2279012"
    ],
    "expiresAt": null,
    "revokedAt": null,
    "lastEmailedAt": null,
    "createdAt": "2026-10-06T14:20:03.118Z",
    "updatedAt": "2026-10-06T14:20:03.118Z",
    "reactions": [],
    "runId": "1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
    "links": {
      "self": "/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
      "email": "/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41/email",
      "run": "/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
      "client": "/api/v1/clients/9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28"
    }
  }
}

Fields (23)

Field	Type	Description
`data`	`object`
`data.id`	`string (uuid)`
`data.runId`	`string (uuid)`
`data.clientId`	`string (uuid)`
`data.status`	`"live" \| "stopped" \| "ended"`	`live` can be opened now; `stopped` was stopped by you; `ended` is past its `expiresAt`.
`data.depth`	`"specs" \| "summary" \| "full"`	How much of the analysis each home shows the client.
`data.homeCount`	`integer`	How many homes the client sees.
`data.homes`	`string[] \| null`	The curated, ordered package of home ids; null when the client sees the results by score, the first `homeCount`.
`data.expiresAt`	`string (date-time) \| null`
`data.revokedAt`	`string (date-time) \| null`	When you stopped it; null while it has not been stopped.
`data.lastEmailedAt`	`string (date-time) \| null`	When the client was last emailed that it is ready; null if they never were.
`data.createdAt`	`string (date-time)`
`data.updatedAt`	`string (date-time)`
`data.reactions`	`object[]`	What the client answered on each home, newest first. Empty until they open it.
`data.reactions[].homeId`	`string`
`data.reactions[].vote`	`"up" \| "down"`	`up` or `down`.
`data.reactions[].comment`	`string \| null`	What they wrote, or null.
`data.reactions[].updatedAt`	`string (date-time)`
`data.links`	`object`
`data.links.self`	`string`	This share's API URL.
`data.links.email`	`string`	Where to POST to email the client a signed-in portal link.
`data.links.run`	`string`	The run this share belongs to.
`data.links.client`	`string`	The client API URL. They open the homes in the product at `/client` after sign-in, not here.

Errors

Status	Code	When
404	not-found	No such run in your workspace.
400	invalid	The body failed validation, a home is named twice, the results are empty, the search has no client and none was sent, or `expiresAt` is not in the future; `issues` names each.
400	invalid-json	The body is empty or not JSON.
413	too-large	The body is over 64 KiB.
409	run-not-ready	The run is still working, or stopped or failed: there are no results to share.
409	client-has-no-access	The client cannot sign in yet.
409	wrong-client	The client is not the one the run's search is for.
409	client-needs-email	A Homes for sale run reaches a client by email, and this client has none.
422	unknown-home	A home is not in the results.

Any call of this kind can also answer401 unauthenticated401 invalid-api-key403 insufficient-scope429 rate-limited429 monthly-cap-reached500 internal

List a run's shares

GET/api/v1/runs/{runId}/shares

Every share of one run, live and stopped, newest first (up to a hundred), each with what its client answered. links.next is always null: a run has one live share per client.

An API key carrying the scope named here, or a signed-in session.

Scope: shares:read
Key kinds: PersonalOrganization

Required and optional fields, allowed values and errors, as the page shows them.

Parameters

Name	In	Type	Required	Description
`runId`	Path	`string (uuid)`	Required	The run's id.

Examples

curl "https://liviamatch.com/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares" \
  -H "Authorization: Bearer $LIVIA_API_KEY"

Responses

200

The run's shares.

One share

{
  "data": [
    {
      "id": "d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
      "clientId": "9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28",
      "status": "live",
      "depth": "summary",
      "homeCount": 2,
      "homes": [
        "NSH-2283104",
        "NSH-2279012"
      ],
      "expiresAt": null,
      "revokedAt": null,
      "lastEmailedAt": null,
      "createdAt": "2026-10-06T14:20:03.118Z",
      "updatedAt": "2026-10-06T14:20:03.118Z",
      "reactions": [
        {
          "homeId": "NSH-2283104",
          "vote": "up",
          "comment": "The porch! Can we see it on Saturday?",
          "updatedAt": "2026-10-06T15:12:44.019Z"
        }
      ],
      "runId": "1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
      "links": {
        "self": "/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
        "email": "/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41/email",
        "run": "/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
        "client": "/api/v1/clients/9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28"
      }
    }
  ],
  "links": {
    "next": null
  }
}

Fields (25)

Field	Type	Description
`data`	`object[]`
`data[].id`	`string (uuid)`
`data[].runId`	`string (uuid)`
`data[].clientId`	`string (uuid)`
`data[].status`	`"live" \| "stopped" \| "ended"`	`live` can be opened now; `stopped` was stopped by you; `ended` is past its `expiresAt`.
`data[].depth`	`"specs" \| "summary" \| "full"`	How much of the analysis each home shows the client.
`data[].homeCount`	`integer`	How many homes the client sees.
`data[].homes`	`string[] \| null`	The curated, ordered package of home ids; null when the client sees the results by score, the first `homeCount`.
`data[].expiresAt`	`string (date-time) \| null`
`data[].revokedAt`	`string (date-time) \| null`	When you stopped it; null while it has not been stopped.
`data[].lastEmailedAt`	`string (date-time) \| null`	When the client was last emailed that it is ready; null if they never were.
`data[].createdAt`	`string (date-time)`
`data[].updatedAt`	`string (date-time)`
`data[].reactions`	`object[]`	What the client answered on each home, newest first. Empty until they open it.
`data[].reactions[].homeId`	`string`
`data[].reactions[].vote`	`"up" \| "down"`	`up` or `down`.
`data[].reactions[].comment`	`string \| null`	What they wrote, or null.
`data[].reactions[].updatedAt`	`string (date-time)`
`data[].links`	`object`
`data[].links.self`	`string`	This share's API URL.
`data[].links.email`	`string`	Where to POST to email the client a signed-in portal link.
`data[].links.run`	`string`	The run this share belongs to.
`data[].links.client`	`string`	The client API URL. They open the homes in the product at `/client` after sign-in, not here.
`links`	`object`
`links.next`	`string \| null`	The URL of the next page, or null when this is the last. Follow it as given.

Errors

Status	Code	When
404	not-found	No such run in your workspace.

Any call of this kind can also answer401 unauthenticated401 invalid-api-key403 insufficient-scope429 rate-limited429 monthly-cap-reached500 internal

GET/api/v1/runs/{runId}/shares/{shareId}

One share of one run, and what the client answered on each home: up or down, with their comment. status says whether the client can open it now.

An API key carrying the scope named here, or a signed-in session.

Scope: shares:read
Key kinds: PersonalOrganization

Required and optional fields, allowed values and errors, as the page shows them.

Parameters

Name	In	Type	Required	Description
`runId`	Path	`string (uuid)`	Required	The run's id.
`shareId`	Path	`string (uuid)`	Required	The share's id: `data.id` from the answer that made it.

Examples

curl "https://liviamatch.com/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41" \
  -H "Authorization: Bearer $LIVIA_API_KEY"

Responses

200

The share.

A share the client answered

{
  "data": {
    "id": "d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
    "clientId": "9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28",
    "status": "live",
    "depth": "summary",
    "homeCount": 2,
    "homes": [
      "NSH-2283104",
      "NSH-2279012"
    ],
    "expiresAt": null,
    "revokedAt": null,
    "lastEmailedAt": null,
    "createdAt": "2026-10-06T14:20:03.118Z",
    "updatedAt": "2026-10-06T14:20:03.118Z",
    "reactions": [
      {
        "homeId": "NSH-2283104",
        "vote": "up",
        "comment": "The porch! Can we see it on Saturday?",
        "updatedAt": "2026-10-06T15:12:44.019Z"
      }
    ],
    "runId": "1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
    "links": {
      "self": "/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
      "email": "/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41/email",
      "run": "/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
      "client": "/api/v1/clients/9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28"
    }
  }
}

Fields (23)

Field	Type	Description
`data`	`object`
`data.id`	`string (uuid)`
`data.runId`	`string (uuid)`
`data.clientId`	`string (uuid)`
`data.status`	`"live" \| "stopped" \| "ended"`	`live` can be opened now; `stopped` was stopped by you; `ended` is past its `expiresAt`.
`data.depth`	`"specs" \| "summary" \| "full"`	How much of the analysis each home shows the client.
`data.homeCount`	`integer`	How many homes the client sees.
`data.homes`	`string[] \| null`	The curated, ordered package of home ids; null when the client sees the results by score, the first `homeCount`.
`data.expiresAt`	`string (date-time) \| null`
`data.revokedAt`	`string (date-time) \| null`	When you stopped it; null while it has not been stopped.
`data.lastEmailedAt`	`string (date-time) \| null`	When the client was last emailed that it is ready; null if they never were.
`data.createdAt`	`string (date-time)`
`data.updatedAt`	`string (date-time)`
`data.reactions`	`object[]`	What the client answered on each home, newest first. Empty until they open it.
`data.reactions[].homeId`	`string`
`data.reactions[].vote`	`"up" \| "down"`	`up` or `down`.
`data.reactions[].comment`	`string \| null`	What they wrote, or null.
`data.reactions[].updatedAt`	`string (date-time)`
`data.links`	`object`
`data.links.self`	`string`	This share's API URL.
`data.links.email`	`string`	Where to POST to email the client a signed-in portal link.
`data.links.run`	`string`	The run this share belongs to.
`data.links.client`	`string`	The client API URL. They open the homes in the product at `/client` after sign-in, not here.

Errors

Status	Code	When
404	not-found	No such share of this run in your workspace.

Any call of this kind can also answer401 unauthenticated401 invalid-api-key403 insufficient-scope429 rate-limited429 monthly-cap-reached500 internal

POST/api/v1/runs/{runId}/shares/{shareId}/email

Emails the client that the share is ready: a note in your brand with a sign-in link to the client portal (/client), which expires in three days. This is not the optional public /s/{token} page.

At most one every ten minutes per share (recently-emailed, with Retry-After); a failed send gives the wait back, so it can be retried at once. Nothing is sent unless you call this, and the client's address is never logged.

An API key carrying the scope named here, or a signed-in session.

Scope: shares:write
Key kinds: PersonalOrganization

Required and optional fields, allowed values and errors, as the page shows them.

Parameters

Name	In	Type	Required	Description
`runId`	Path	`string (uuid)`	Required	The run's id.
`shareId`	Path	`string (uuid)`	Required	The share's id: `data.id` from the answer that made it.

Examples

curl -X POST "https://liviamatch.com/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41/email" \
  -H "Authorization: Bearer $LIVIA_API_KEY"

Responses

200

The email was sent; lastEmailedAt says when.

Emailed

{
  "data": {
    "id": "d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
    "clientId": "9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28",
    "status": "live",
    "depth": "summary",
    "homeCount": 2,
    "homes": [
      "NSH-2283104",
      "NSH-2279012"
    ],
    "expiresAt": null,
    "revokedAt": null,
    "lastEmailedAt": "2026-10-06T14:21:30.447Z",
    "createdAt": "2026-10-06T14:20:03.118Z",
    "updatedAt": "2026-10-06T14:21:30.447Z",
    "reactions": [],
    "runId": "1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
    "links": {
      "self": "/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
      "email": "/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41/email",
      "run": "/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
      "client": "/api/v1/clients/9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28"
    }
  }
}

Fields (23)

Field	Type	Description
`data`	`object`
`data.id`	`string (uuid)`
`data.runId`	`string (uuid)`
`data.clientId`	`string (uuid)`
`data.status`	`"live" \| "stopped" \| "ended"`	`live` can be opened now; `stopped` was stopped by you; `ended` is past its `expiresAt`.
`data.depth`	`"specs" \| "summary" \| "full"`	How much of the analysis each home shows the client.
`data.homeCount`	`integer`	How many homes the client sees.
`data.homes`	`string[] \| null`	The curated, ordered package of home ids; null when the client sees the results by score, the first `homeCount`.
`data.expiresAt`	`string (date-time) \| null`
`data.revokedAt`	`string (date-time) \| null`	When you stopped it; null while it has not been stopped.
`data.lastEmailedAt`	`string (date-time) \| null`	When the client was last emailed that it is ready; null if they never were.
`data.createdAt`	`string (date-time)`
`data.updatedAt`	`string (date-time)`
`data.reactions`	`object[]`	What the client answered on each home, newest first. Empty until they open it.
`data.reactions[].homeId`	`string`
`data.reactions[].vote`	`"up" \| "down"`	`up` or `down`.
`data.reactions[].comment`	`string \| null`	What they wrote, or null.
`data.reactions[].updatedAt`	`string (date-time)`
`data.links`	`object`
`data.links.self`	`string`	This share's API URL.
`data.links.email`	`string`	Where to POST to email the client a signed-in portal link.
`data.links.run`	`string`	The run this share belongs to.
`data.links.client`	`string`	The client API URL. They open the homes in the product at `/client` after sign-in, not here.

Errors

Status	Code	When
404	not-found	No such share of this run in your workspace.
409	client-needs-email	The client has no email to send it to.
429	recently-emailed	The client was emailed less than ten minutes ago; `Retry-After` says when to try again.
502	email-failed	The provider refused the message or did not answer in time.

Any call of this kind can also answer401 unauthenticated401 invalid-api-key403 insufficient-scope429 rate-limited429 monthly-cap-reached500 internal

DELETE/api/v1/runs/{runId}/shares/{shareId}

Stops a share, so its client can no longer open it. The row stays, stamped with revokedAt, and what the client answered is kept. Stopping a share already stopped changes nothing and answers the same.

An API key carrying the scope named here, or a signed-in session.

Scope: shares:write
Key kinds: PersonalOrganization

Required and optional fields, allowed values and errors, as the page shows them.

Parameters

Name	In	Type	Required	Description
`runId`	Path	`string (uuid)`	Required	The run's id.
`shareId`	Path	`string (uuid)`	Required	The share's id: `data.id` from the answer that made it.

Examples

curl -X DELETE "https://liviamatch.com/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41" \
  -H "Authorization: Bearer $LIVIA_API_KEY"

Responses

200

The share, stopped.

Stopped

{
  "data": {
    "id": "d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
    "clientId": "9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28",
    "status": "stopped",
    "depth": "summary",
    "homeCount": 2,
    "homes": [
      "NSH-2283104",
      "NSH-2279012"
    ],
    "expiresAt": null,
    "revokedAt": "2026-10-06T16:00:00.000Z",
    "lastEmailedAt": null,
    "createdAt": "2026-10-06T14:20:03.118Z",
    "updatedAt": "2026-10-06T16:00:00.000Z",
    "reactions": [],
    "runId": "1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
    "links": {
      "self": "/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
      "email": "/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41/email",
      "run": "/api/v1/runs/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
      "client": "/api/v1/clients/9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28"
    }
  }
}

Fields (23)

Field	Type	Description
`data`	`object`
`data.id`	`string (uuid)`
`data.runId`	`string (uuid)`
`data.clientId`	`string (uuid)`
`data.status`	`"live" \| "stopped" \| "ended"`	`live` can be opened now; `stopped` was stopped by you; `ended` is past its `expiresAt`.
`data.depth`	`"specs" \| "summary" \| "full"`	How much of the analysis each home shows the client.
`data.homeCount`	`integer`	How many homes the client sees.
`data.homes`	`string[] \| null`	The curated, ordered package of home ids; null when the client sees the results by score, the first `homeCount`.
`data.expiresAt`	`string (date-time) \| null`
`data.revokedAt`	`string (date-time) \| null`	When you stopped it; null while it has not been stopped.
`data.lastEmailedAt`	`string (date-time) \| null`	When the client was last emailed that it is ready; null if they never were.
`data.createdAt`	`string (date-time)`
`data.updatedAt`	`string (date-time)`
`data.reactions`	`object[]`	What the client answered on each home, newest first. Empty until they open it.
`data.reactions[].homeId`	`string`
`data.reactions[].vote`	`"up" \| "down"`	`up` or `down`.
`data.reactions[].comment`	`string \| null`	What they wrote, or null.
`data.reactions[].updatedAt`	`string (date-time)`
`data.links`	`object`
`data.links.self`	`string`	This share's API URL.
`data.links.email`	`string`	Where to POST to email the client a signed-in portal link.
`data.links.run`	`string`	The run this share belongs to.
`data.links.client`	`string`	The client API URL. They open the homes in the product at `/client` after sign-in, not here.

Errors

Status	Code	When
404	not-found	No such share of this run in your workspace.

Any call of this kind can also answer401 unauthenticated401 invalid-api-key403 insufficient-scope429 rate-limited429 monthly-cap-reached500 internal

POST/api/v1/matches/{matchId}/shares

Shares a complete match's shortlist with a client who has access: the homes you name, in order, else the shortlist as it stands, shown at the depth you choose. 201 for a new share. Sharing again with the same client updates their live share (200) rather than making a second one, so the call is safe to retry.

A match is shared with the client its brief is for, so clientId may be left out; a different client is refused with wrong-client. The client must have access (POST /api/v1/clients/{clientId}/access), or the answer is client-has-no-access. A share to a client with no email is refused for Homes for sale matches, which reach clients by email only.

Sharing does not email anyone and does not create a public /s/{token} link. Email the share sends a signed-in portal link (the client signs in at /client). A public link, when allowed, is turned on in the share studio in the product UI; its PDF is GET /api/v1/shares/{token}/pdf.

A share can name only homes on the shortlist; add one first with PUT .../shortlist.

An API key carrying the scope named here, or a signed-in session.

Scope: shares:write
Key kinds: PersonalOrganization

Required and optional fields, allowed values and errors, as the page shows them.

Parameters

Name	In	Type	Required	Description
`matchId`	Path	`string (uuid)`	Required	The match's id.

Request body

How to share. Every field is optional but the match must have a client.

Fields (4)

Field	Type	Required	Description
`clientId`	`string (uuid)`	Optional	The client to share with. Left out, it is the client the match's brief is for. They must have access (`POST /api/v1/clients/{clientId}/access`).
`depth`	`"specs" \| "summary" \| "full"`	Optional	How much of the analysis each home shows the client: `specs` (the facts), `summary` (the facts and the take) or `full` (the reasoning too).default "summary"
`homes`	`string[]`	Optional	The homes to share, in order, as `homes[].id` from the match. Left out, the shortlist as it stands is shared (up to twenty).1 to 20 items
`expiresAt`	`string (date-time) \| null`	Optional	When the share ends, as ISO 8601 in the future, or null for no end. Left out, a new share has no end and an existing one keeps its own.

Examples

{
  "depth": "summary",
  "homes": [
    "NSH-2283104",
    "NSH-2279012"
  ]
}

Examples

curl -X POST "https://liviamatch.com/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares" \
  -H "Authorization: Bearer $LIVIA_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "depth": "summary",
  "homes": [
    "NSH-2283104",
    "NSH-2279012"
  ]
}'

Responses

201

A new share was made.

HeadersLocation

A new share

{
  "data": {
    "id": "d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
    "matchId": "1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
    "clientId": "9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28",
    "status": "live",
    "depth": "summary",
    "homeCount": 2,
    "homes": [
      "NSH-2283104",
      "NSH-2279012"
    ],
    "expiresAt": null,
    "revokedAt": null,
    "lastEmailedAt": null,
    "createdAt": "2026-10-06T14:20:03.118Z",
    "updatedAt": "2026-10-06T14:20:03.118Z",
    "reactions": [],
    "links": {
      "self": "/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
      "email": "/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41/email",
      "match": "/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
      "client": "/api/v1/clients/9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28"
    }
  }
}

Fields (23)

Field	Type	Description
`data`	`object`
`data.id`	`string (uuid)`
`data.matchId`	`string (uuid)`
`data.clientId`	`string (uuid)`
`data.status`	`"live" \| "stopped" \| "ended"`	`live` can be opened now; `stopped` was stopped by you; `ended` is past its `expiresAt`.
`data.depth`	`"specs" \| "summary" \| "full"`	How much of the analysis each home shows the client.
`data.homeCount`	`integer`	How many homes the client sees.
`data.homes`	`string[] \| null`	The curated, ordered package of home ids; null when the client sees the shortlist by score, the first `homeCount`.
`data.expiresAt`	`string (date-time) \| null`
`data.revokedAt`	`string (date-time) \| null`	When you stopped it; null while it has not been stopped.
`data.lastEmailedAt`	`string (date-time) \| null`	When the client was last emailed that it is ready; null if they never were.
`data.createdAt`	`string (date-time)`
`data.updatedAt`	`string (date-time)`
`data.reactions`	`object[]`	What the client answered on each home, newest first. Empty until they open it.
`data.reactions[].homeId`	`string`
`data.reactions[].vote`	`"up" \| "down"`	`up` or `down`.
`data.reactions[].comment`	`string \| null`	What they wrote, or null.
`data.reactions[].updatedAt`	`string (date-time)`
`data.links`	`object`
`data.links.self`	`string`	This share's API URL.
`data.links.email`	`string`	Where to POST to email the client a signed-in portal link.
`data.links.match`	`string`	The match this share belongs to.
`data.links.client`	`string`	The client API URL. They open the homes in the product at `/client` after sign-in, not here.

200

The client's live share was updated.

HeadersLocation

An updated share

{
  "data": {
    "id": "d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
    "matchId": "1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
    "clientId": "9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28",
    "status": "live",
    "depth": "summary",
    "homeCount": 2,
    "homes": [
      "NSH-2283104",
      "NSH-2279012"
    ],
    "expiresAt": null,
    "revokedAt": null,
    "lastEmailedAt": null,
    "createdAt": "2026-10-06T14:20:03.118Z",
    "updatedAt": "2026-10-06T14:20:03.118Z",
    "reactions": [],
    "links": {
      "self": "/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
      "email": "/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41/email",
      "match": "/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
      "client": "/api/v1/clients/9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28"
    }
  }
}

Fields (23)

Field	Type	Description
`data`	`object`
`data.id`	`string (uuid)`
`data.matchId`	`string (uuid)`
`data.clientId`	`string (uuid)`
`data.status`	`"live" \| "stopped" \| "ended"`	`live` can be opened now; `stopped` was stopped by you; `ended` is past its `expiresAt`.
`data.depth`	`"specs" \| "summary" \| "full"`	How much of the analysis each home shows the client.
`data.homeCount`	`integer`	How many homes the client sees.
`data.homes`	`string[] \| null`	The curated, ordered package of home ids; null when the client sees the shortlist by score, the first `homeCount`.
`data.expiresAt`	`string (date-time) \| null`
`data.revokedAt`	`string (date-time) \| null`	When you stopped it; null while it has not been stopped.
`data.lastEmailedAt`	`string (date-time) \| null`	When the client was last emailed that it is ready; null if they never were.
`data.createdAt`	`string (date-time)`
`data.updatedAt`	`string (date-time)`
`data.reactions`	`object[]`	What the client answered on each home, newest first. Empty until they open it.
`data.reactions[].homeId`	`string`
`data.reactions[].vote`	`"up" \| "down"`	`up` or `down`.
`data.reactions[].comment`	`string \| null`	What they wrote, or null.
`data.reactions[].updatedAt`	`string (date-time)`
`data.links`	`object`
`data.links.self`	`string`	This share's API URL.
`data.links.email`	`string`	Where to POST to email the client a signed-in portal link.
`data.links.match`	`string`	The match this share belongs to.
`data.links.client`	`string`	The client API URL. They open the homes in the product at `/client` after sign-in, not here.

Errors

Status	Code	When
404	not-found	No such match in your workspace.
400	invalid	The body failed validation, a home is named twice, the shortlist is empty, the match has no client and none was sent, or `expiresAt` is not in the future; `issues` names each.
400	invalid-json	The body is empty or not JSON.
413	too-large	The body is over 64 KiB.
409	match-not-ready	The match is still running, or stopped or failed: there is no shortlist to share.
409	client-has-no-access	The client cannot sign in yet.
409	wrong-client	The client is not the one the match's brief is for.
409	client-needs-email	A Homes for sale match reaches a client by email, and this client has none.
422	unknown-home	A home is not on the shortlist.

Any call of this kind can also answer401 unauthenticated401 invalid-api-key403 insufficient-scope429 rate-limited429 monthly-cap-reached500 internal

List a match's shares

GET/api/v1/matches/{matchId}/shares

Every share of one match, live and stopped, newest first (up to a hundred), each with what its client answered. links.next is always null: a match has one live share per client.

An API key carrying the scope named here, or a signed-in session.

Scope: shares:read
Key kinds: PersonalOrganization

Required and optional fields, allowed values and errors, as the page shows them.

Parameters

Name	In	Type	Required	Description
`matchId`	Path	`string (uuid)`	Required	The match's id.

Examples

curl "https://liviamatch.com/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares" \
  -H "Authorization: Bearer $LIVIA_API_KEY"

Responses

200

The match's shares.

One share

{
  "data": [
    {
      "id": "d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
      "matchId": "1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
      "clientId": "9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28",
      "status": "live",
      "depth": "summary",
      "homeCount": 2,
      "homes": [
        "NSH-2283104",
        "NSH-2279012"
      ],
      "expiresAt": null,
      "revokedAt": null,
      "lastEmailedAt": null,
      "createdAt": "2026-10-06T14:20:03.118Z",
      "updatedAt": "2026-10-06T14:20:03.118Z",
      "reactions": [
        {
          "homeId": "NSH-2283104",
          "vote": "up",
          "comment": "The porch! Can we see it on Saturday?",
          "updatedAt": "2026-10-06T15:12:44.019Z"
        }
      ],
      "links": {
        "self": "/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
        "email": "/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41/email",
        "match": "/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
        "client": "/api/v1/clients/9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28"
      }
    }
  ],
  "links": {
    "next": null
  }
}

Fields (25)

Field	Type	Description
`data`	`object[]`
`data[].id`	`string (uuid)`
`data[].matchId`	`string (uuid)`
`data[].clientId`	`string (uuid)`
`data[].status`	`"live" \| "stopped" \| "ended"`	`live` can be opened now; `stopped` was stopped by you; `ended` is past its `expiresAt`.
`data[].depth`	`"specs" \| "summary" \| "full"`	How much of the analysis each home shows the client.
`data[].homeCount`	`integer`	How many homes the client sees.
`data[].homes`	`string[] \| null`	The curated, ordered package of home ids; null when the client sees the shortlist by score, the first `homeCount`.
`data[].expiresAt`	`string (date-time) \| null`
`data[].revokedAt`	`string (date-time) \| null`	When you stopped it; null while it has not been stopped.
`data[].lastEmailedAt`	`string (date-time) \| null`	When the client was last emailed that it is ready; null if they never were.
`data[].createdAt`	`string (date-time)`
`data[].updatedAt`	`string (date-time)`
`data[].reactions`	`object[]`	What the client answered on each home, newest first. Empty until they open it.
`data[].reactions[].homeId`	`string`
`data[].reactions[].vote`	`"up" \| "down"`	`up` or `down`.
`data[].reactions[].comment`	`string \| null`	What they wrote, or null.
`data[].reactions[].updatedAt`	`string (date-time)`
`data[].links`	`object`
`data[].links.self`	`string`	This share's API URL.
`data[].links.email`	`string`	Where to POST to email the client a signed-in portal link.
`data[].links.match`	`string`	The match this share belongs to.
`data[].links.client`	`string`	The client API URL. They open the homes in the product at `/client` after sign-in, not here.
`links`	`object`
`links.next`	`string \| null`	The URL of the next page, or null when this is the last. Follow it as given.

Errors

Status	Code	When
404	not-found	No such match in your workspace.

Any call of this kind can also answer401 unauthenticated401 invalid-api-key403 insufficient-scope429 rate-limited429 monthly-cap-reached500 internal

GET/api/v1/matches/{matchId}/shares/{shareId}

One share of one match, and what the client answered on each home: up or down, with their comment. status says whether the client can open it now.

An API key carrying the scope named here, or a signed-in session.

Scope: shares:read
Key kinds: PersonalOrganization

Required and optional fields, allowed values and errors, as the page shows them.

Parameters

Name	In	Type	Required	Description
`matchId`	Path	`string (uuid)`	Required	The match's id.
`shareId`	Path	`string (uuid)`	Required	The share's id: `data.id` from the answer that made it.

Examples

curl "https://liviamatch.com/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41" \
  -H "Authorization: Bearer $LIVIA_API_KEY"

Responses

200

The share.

A share the client answered

{
  "data": {
    "id": "d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
    "matchId": "1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
    "clientId": "9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28",
    "status": "live",
    "depth": "summary",
    "homeCount": 2,
    "homes": [
      "NSH-2283104",
      "NSH-2279012"
    ],
    "expiresAt": null,
    "revokedAt": null,
    "lastEmailedAt": null,
    "createdAt": "2026-10-06T14:20:03.118Z",
    "updatedAt": "2026-10-06T14:20:03.118Z",
    "reactions": [
      {
        "homeId": "NSH-2283104",
        "vote": "up",
        "comment": "The porch! Can we see it on Saturday?",
        "updatedAt": "2026-10-06T15:12:44.019Z"
      }
    ],
    "links": {
      "self": "/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
      "email": "/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41/email",
      "match": "/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
      "client": "/api/v1/clients/9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28"
    }
  }
}

Fields (23)

Field	Type	Description
`data`	`object`
`data.id`	`string (uuid)`
`data.matchId`	`string (uuid)`
`data.clientId`	`string (uuid)`
`data.status`	`"live" \| "stopped" \| "ended"`	`live` can be opened now; `stopped` was stopped by you; `ended` is past its `expiresAt`.
`data.depth`	`"specs" \| "summary" \| "full"`	How much of the analysis each home shows the client.
`data.homeCount`	`integer`	How many homes the client sees.
`data.homes`	`string[] \| null`	The curated, ordered package of home ids; null when the client sees the shortlist by score, the first `homeCount`.
`data.expiresAt`	`string (date-time) \| null`
`data.revokedAt`	`string (date-time) \| null`	When you stopped it; null while it has not been stopped.
`data.lastEmailedAt`	`string (date-time) \| null`	When the client was last emailed that it is ready; null if they never were.
`data.createdAt`	`string (date-time)`
`data.updatedAt`	`string (date-time)`
`data.reactions`	`object[]`	What the client answered on each home, newest first. Empty until they open it.
`data.reactions[].homeId`	`string`
`data.reactions[].vote`	`"up" \| "down"`	`up` or `down`.
`data.reactions[].comment`	`string \| null`	What they wrote, or null.
`data.reactions[].updatedAt`	`string (date-time)`
`data.links`	`object`
`data.links.self`	`string`	This share's API URL.
`data.links.email`	`string`	Where to POST to email the client a signed-in portal link.
`data.links.match`	`string`	The match this share belongs to.
`data.links.client`	`string`	The client API URL. They open the homes in the product at `/client` after sign-in, not here.

Errors

Status	Code	When
404	not-found	No such share of this match in your workspace.

Any call of this kind can also answer401 unauthenticated401 invalid-api-key403 insufficient-scope429 rate-limited429 monthly-cap-reached500 internal

POST/api/v1/matches/{matchId}/shares/{shareId}/email

Emails the client that the share is ready: a note in your brand with a sign-in link to the client portal (/client), which expires in three days. After sign-in they open the share under /client/homes/…. This is not the optional public /s/{token} page.

An API key carrying the scope named here, or a signed-in session.

Scope: shares:write
Key kinds: PersonalOrganization

Required and optional fields, allowed values and errors, as the page shows them.

Parameters

Name	In	Type	Required	Description
`matchId`	Path	`string (uuid)`	Required	The match's id.
`shareId`	Path	`string (uuid)`	Required	The share's id: `data.id` from the answer that made it.

Examples

curl -X POST "https://liviamatch.com/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41/email" \
  -H "Authorization: Bearer $LIVIA_API_KEY"

Responses

200

The email was sent; lastEmailedAt says when.

Emailed

{
  "data": {
    "id": "d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
    "matchId": "1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
    "clientId": "9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28",
    "status": "live",
    "depth": "summary",
    "homeCount": 2,
    "homes": [
      "NSH-2283104",
      "NSH-2279012"
    ],
    "expiresAt": null,
    "revokedAt": null,
    "lastEmailedAt": "2026-10-06T14:21:30.447Z",
    "createdAt": "2026-10-06T14:20:03.118Z",
    "updatedAt": "2026-10-06T14:21:30.447Z",
    "reactions": [],
    "links": {
      "self": "/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
      "email": "/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41/email",
      "match": "/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
      "client": "/api/v1/clients/9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28"
    }
  }
}

Fields (23)

Field	Type	Description
`data`	`object`
`data.id`	`string (uuid)`
`data.matchId`	`string (uuid)`
`data.clientId`	`string (uuid)`
`data.status`	`"live" \| "stopped" \| "ended"`	`live` can be opened now; `stopped` was stopped by you; `ended` is past its `expiresAt`.
`data.depth`	`"specs" \| "summary" \| "full"`	How much of the analysis each home shows the client.
`data.homeCount`	`integer`	How many homes the client sees.
`data.homes`	`string[] \| null`	The curated, ordered package of home ids; null when the client sees the shortlist by score, the first `homeCount`.
`data.expiresAt`	`string (date-time) \| null`
`data.revokedAt`	`string (date-time) \| null`	When you stopped it; null while it has not been stopped.
`data.lastEmailedAt`	`string (date-time) \| null`	When the client was last emailed that it is ready; null if they never were.
`data.createdAt`	`string (date-time)`
`data.updatedAt`	`string (date-time)`
`data.reactions`	`object[]`	What the client answered on each home, newest first. Empty until they open it.
`data.reactions[].homeId`	`string`
`data.reactions[].vote`	`"up" \| "down"`	`up` or `down`.
`data.reactions[].comment`	`string \| null`	What they wrote, or null.
`data.reactions[].updatedAt`	`string (date-time)`
`data.links`	`object`
`data.links.self`	`string`	This share's API URL.
`data.links.email`	`string`	Where to POST to email the client a signed-in portal link.
`data.links.match`	`string`	The match this share belongs to.
`data.links.client`	`string`	The client API URL. They open the homes in the product at `/client` after sign-in, not here.

Errors

Status	Code	When
404	not-found	No such share of this match in your workspace.
409	client-needs-email	The client has no email to send it to.
429	recently-emailed	The client was emailed less than ten minutes ago; `Retry-After` says when to try again.
502	email-failed	The provider refused the message or did not answer in time.

Any call of this kind can also answer401 unauthenticated401 invalid-api-key403 insufficient-scope429 rate-limited429 monthly-cap-reached500 internal

DELETE/api/v1/matches/{matchId}/shares/{shareId}

An API key carrying the scope named here, or a signed-in session.

Scope: shares:write
Key kinds: PersonalOrganization

Required and optional fields, allowed values and errors, as the page shows them.

Parameters

Name	In	Type	Required	Description
`matchId`	Path	`string (uuid)`	Required	The match's id.
`shareId`	Path	`string (uuid)`	Required	The share's id: `data.id` from the answer that made it.

Examples

curl -X DELETE "https://liviamatch.com/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41" \
  -H "Authorization: Bearer $LIVIA_API_KEY"

Responses

200

The share, stopped.

Stopped

{
  "data": {
    "id": "d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
    "matchId": "1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
    "clientId": "9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28",
    "status": "stopped",
    "depth": "summary",
    "homeCount": 2,
    "homes": [
      "NSH-2283104",
      "NSH-2279012"
    ],
    "expiresAt": null,
    "revokedAt": "2026-10-06T16:00:00.000Z",
    "lastEmailedAt": null,
    "createdAt": "2026-10-06T14:20:03.118Z",
    "updatedAt": "2026-10-06T16:00:00.000Z",
    "reactions": [],
    "links": {
      "self": "/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41",
      "email": "/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15/shares/d5a1f7c3-8e29-4b64-a0d8-3f6c2b9e7a41/email",
      "match": "/api/v1/matches/1e8b4c27-5a93-4d60-b2f7-9c0d3a6e8f15",
      "client": "/api/v1/clients/9c4e1a73-2b85-4d06-8f1a-7d3b5e9c0a28"
    }
  }
}

Fields (23)

Field	Type	Description
`data`	`object`
`data.id`	`string (uuid)`
`data.matchId`	`string (uuid)`
`data.clientId`	`string (uuid)`
`data.status`	`"live" \| "stopped" \| "ended"`	`live` can be opened now; `stopped` was stopped by you; `ended` is past its `expiresAt`.
`data.depth`	`"specs" \| "summary" \| "full"`	How much of the analysis each home shows the client.
`data.homeCount`	`integer`	How many homes the client sees.
`data.homes`	`string[] \| null`	The curated, ordered package of home ids; null when the client sees the shortlist by score, the first `homeCount`.
`data.expiresAt`	`string (date-time) \| null`
`data.revokedAt`	`string (date-time) \| null`	When you stopped it; null while it has not been stopped.
`data.lastEmailedAt`	`string (date-time) \| null`	When the client was last emailed that it is ready; null if they never were.
`data.createdAt`	`string (date-time)`
`data.updatedAt`	`string (date-time)`
`data.reactions`	`object[]`	What the client answered on each home, newest first. Empty until they open it.
`data.reactions[].homeId`	`string`
`data.reactions[].vote`	`"up" \| "down"`	`up` or `down`.
`data.reactions[].comment`	`string \| null`	What they wrote, or null.
`data.reactions[].updatedAt`	`string (date-time)`
`data.links`	`object`
`data.links.self`	`string`	This share's API URL.
`data.links.email`	`string`	Where to POST to email the client a signed-in portal link.
`data.links.match`	`string`	The match this share belongs to.
`data.links.client`	`string`	The client API URL. They open the homes in the product at `/client` after sign-in, not here.

Errors

Status	Code	When
404	not-found	No such share of this match in your workspace.

Any call of this kind can also answer401 unauthenticated401 invalid-api-key403 insufficient-scope429 rate-limited429 monthly-cap-reached500 internal