> ## Documentation Index
> Fetch the complete documentation index at: https://docs.siro.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Get recordings
> Get recordings
Returns a paginated list of recordings. By default each item contains the recording's core fields; opt into the enrichment blocks below to also pull CRM links, the AI summary, entity extractions, and followup summaries for every recording in the page.
## Deleted recordings
Every recording carries two core fields (always present, no opt-in required) that tell you whether it has been deleted in Siro:
| Field | Shape | Description |
| - | - | - |
| `deleted` | `boolean` | `true` if the recording has been deleted, `false` otherwise |
| `deletedAt` | `string \| null` | ISO 8601 timestamp of when it was deleted, or `null` if it has not been deleted |
Deleted recordings are **still returned** by this endpoint — they are not filtered out. This lets you detect deletions when polling with the `updatedAt` filters and reconcile them in your own system (deleting a recording bumps its `updatedAt`). Treat `deleted: true` as a signal to hide or remove the recording on your side; the Siro app already hides these from its Recordings view.
## Enriching the response
The org-scoped recordings endpoints can optionally hydrate extra blocks of data, each behind an opt-in query flag:
| Flag | Adds | Use it to |
| - | - | - |
| `showCrmLinks` | `crm` — external IDs for the CRM records linked to the recording | Map a recording back to the appointment / account / contact in your CRM |
| `showSummary` | `summary` — the recording's AI summary sections | Pull conversation summaries into your pipeline (e.g. post-call personalization) |
| `showEntityExtractions` | `entityExtractions` — extracted values and their CRM field mappings | Write extracted fields back to your CRM |
| `showFollowups` | `followups` — AI-generated followups for the recording | Surface followup scores and (on the single-recording endpoint) full followup detail |
They are **off by default** and additive — omit them and the response is unchanged. Pass `=true` to enable.
### `crm` — CRM link IDs
When `showCrmLinks=true`, `crm` contains the external IDs of the CRM records the recording is linked to. Every linked object is returned as a pair:
* **`id`** — Siro's internal ID for the object
* **`externalId`** — that object's ID **in your CRM** (use this to join)
| Field | Shape | CRM object |
| - | - | - |
| `integrationConnectionId` | `string` | The Siro integration connection the links came from |
| `users` | array of `{id, externalId}` | CRM user(s) who own the recording (the rep) |
| `engagement` | `{id, externalId}` | The CRM engagement / **appointment** |
| `opportunity` | `{id, externalId}` | The opportunity |
| `contacts` | array of `{id, externalId}` | Contact(s) |
| `account` | `{id, externalId}` | Account |
| `lead` | `{id, externalId}` | Lead |
This is the same shape emitted by the `integrations.recordingProcessed` webhook, so pull-based polling and push-based webhooks give you identical CRM references.
`crm` is `null` when the recording has no confirmed CRM link yet. Because links can be established after a recording is created, poll the [list endpoint](/api-references/get-recordings) with the `updatedAt` filters to pick up recordings as they become linked.
`engagement` (the appointment) is only populated when the recording is linked to a **CRM-sourced** engagement. Recordings linked only to a Siro-side calendar event return `engagement: null` while still returning `account` / `contact`. To map on the appointment ID, ensure your appointments sync to Siro as CRM engagements. Any field with no linked record is `null`.
### `summary`
When `showSummary=true`, `summary` is the recording's AI summary as an ordered array of sections:
| Field | Description |
| - | - |
| `id` | Summary section ID |
| `name` | Section title (the prompt header) |
| `content` | Generated summary text |
Returns `[]` if the recording has no summary yet.
### `entityExtractions`
When `showEntityExtractions=true`, `entityExtractions` is a flat list of the values extracted from the conversation, including the CRM field each maps to:
| Field | Description |
| - | - |
| `name` | The extracted field name |
| `value` | The extracted value |
| `mappings` | CRM target(s): `[{ crmModelName, crmFieldName }]` — which object and field to write `value` to |
Only successfully completed extractions are included; in-progress or failed extractions are omitted. Returns `[]` if there are none. Use `mappings` to write each `value` to the corresponding field on the CRM record from the `crm` block.
### `followups`
When `showFollowups=true`, `followups` is an array of AI-generated followups tied to the recording. The payload differs by endpoint:
**List** (`GET /v1/core/recordings`) returns slim summaries:
| Field | Description |
| - | - |
| `id` | Followup ID |
| `score` | Followup score (1–5) |
Use [Get recording](/api-references/get-recording) with `showFollowups=true` when you need the full followup payload for a specific recording.
**Single recording** (`GET /v1/core/recordings/{id}`) returns the full followup payload, including:
| Field | Description |
| - | - |
| `followupId` | Followup ID |
| `score` | Followup score (1–5) |
| `status` | `TO_DO`, `IN_PROGRESS`, or `COMPLETE` |
| `followupAction` | Suggested action text |
| `context` | Array of `{ header, value }` context items |
| `thinking` | Score breakdown / reasoning |
### Example
```bash theme={null}
curl --request GET \
--url 'https://functions.siro.ai/api-externalApi/v1/core/recordings?updatedAt:gte=2026-06-23T00:00:00.000Z&showCrmLinks=true&showSummary=true&showEntityExtractions=true&showFollowups=true' \
--header 'Authorization: Bearer '
```
```json theme={null}
{
"data": [
{
"id": "1234-1234-1234-1234-1234",
"organizationId": "000000000001234",
"title": "Appointment to Win",
"result": "WON",
"createdAt": "2026-06-23T15:42:30.992Z",
"updatedAt": "2026-06-23T15:47:05.438Z",
"deleted": false,
"deletedAt": null,
"links": { "web": { "self": "https://app.siro.ai/#/recordings/1234-..." } },
"crm": {
"integrationConnectionId": "1234-1234-12345",
"users": [{ "id": "1234-...", "externalId": "22222" }],
"engagement": { "id": "1234-...", "externalId": "1111" },
"contacts": [{ "id": "1234-...", "externalId": "123" }],
"account": { "id": "1234-...", "externalId": "1234" },
"opportunity": null,
"lead": null
},
"summary": [
{ "id": "111111-...", "name": "Meeting Booked", "content": "Yes" }
],
"entityExtractions": [
{
"name": "Tech Systems",
"value": "None",
"mappings": [{ "crmModelName": "Contact", "crmFieldName": "customer_notes" }]
}
],
"followups": [
{ "id": "abcd-...", "score": 4 }
]
}
]
}
```
### Putting it together
A typical pipeline poll:
1. Call `GET /v1/core/recordings?updatedAt:gte=&showCrmLinks=true` to fetch recordings linked since your last poll, with their CRM IDs.
2. Join each recording to your CRM using `crm.engagement.externalId` (appointment) / `crm.account.externalId` / etc.
3. For recordings you want to enrich, request `showSummary` / `showEntityExtractions` (on this list call or the [single-recording endpoint](/api-references/get-recording)) and write `entityExtractions` values back using their `mappings`.
## OpenAPI
````yaml specs/openapi-externalApi.json get /v1/core/recordings
openapi: 3.0.0
info:
version: 1.0.0
title: Swagger API
servers:
- url: https://functions.siro.ai/api-externalApi
description: Siro API external API endpoint
security: []
externalDocs:
description: View the raw OpenAPI Specification in JSON format
url: /swagger.json
paths:
/v1/core/recordings:
get:
summary: Get recordings
description: Get recordings
parameters:
- schema:
type: string
nullable: true
description: >-
Return results created strictly after the given date (exclusive).
Format: ISO 8601 timestamp (YYYY-MM-DDTHH:mm:ss.sssZ). Example:
2024-06-13T04:00:00.592Z
required: false
description: >-
Return results created strictly after the given date (exclusive).
Format: ISO 8601 timestamp (YYYY-MM-DDTHH:mm:ss.sssZ). Example:
2024-06-13T04:00:00.592Z
name: createdAt:gt
in: query
- schema:
type: string
nullable: true
description: >-
Return results created strictly before the given date (exclusive).
Format: ISO 8601 timestamp (YYYY-MM-DDTHH:mm:ss.sssZ). Example:
2024-06-13T04:00:00.592Z
required: false
description: >-
Return results created strictly before the given date (exclusive).
Format: ISO 8601 timestamp (YYYY-MM-DDTHH:mm:ss.sssZ). Example:
2024-06-13T04:00:00.592Z
name: createdAt:lt
in: query
- schema:
type: string
nullable: true
description: >-
Return results updated at or after the given date (inclusive). Use
this for incremental polling. Format: ISO 8601 timestamp
(YYYY-MM-DDTHH:mm:ss.sssZ). Example: 2024-06-13T04:00:00.592Z
required: false
description: >-
Return results updated at or after the given date (inclusive). Use
this for incremental polling. Format: ISO 8601 timestamp
(YYYY-MM-DDTHH:mm:ss.sssZ). Example: 2024-06-13T04:00:00.592Z
name: updatedAt:gte
in: query
- schema:
type: string
nullable: true
description: >-
Return results updated strictly after the given date (exclusive).
Format: ISO 8601 timestamp (YYYY-MM-DDTHH:mm:ss.sssZ). Example:
2024-06-13T04:00:00.592Z
required: false
description: >-
Return results updated strictly after the given date (exclusive).
Format: ISO 8601 timestamp (YYYY-MM-DDTHH:mm:ss.sssZ). Example:
2024-06-13T04:00:00.592Z
name: updatedAt:gt
in: query
- schema:
type: string
nullable: true
description: >-
Return results updated strictly before the given date (exclusive).
Format: ISO 8601 timestamp (YYYY-MM-DDTHH:mm:ss.sssZ). Example:
2024-06-13T04:00:00.592Z
required: false
description: >-
Return results updated strictly before the given date (exclusive).
Format: ISO 8601 timestamp (YYYY-MM-DDTHH:mm:ss.sssZ). Example:
2024-06-13T04:00:00.592Z
name: updatedAt:lt
in: query
- schema:
type: string
nullable: true
description: >-
Return results updated at or before the given date (inclusive).
Format: ISO 8601 timestamp (YYYY-MM-DDTHH:mm:ss.sssZ). Example:
2024-06-13T04:00:00.592Z
required: false
description: >-
Return results updated at or before the given date (inclusive).
Format: ISO 8601 timestamp (YYYY-MM-DDTHH:mm:ss.sssZ). Example:
2024-06-13T04:00:00.592Z
name: updatedAt:lte
in: query
- schema:
type: string
description: Number of results to return per page (default is 25).
required: false
description: Number of results to return per page (default is 25).
name: pageSize
in: query
- schema:
type: string
description: Cursor for pagination.
required: false
description: Cursor for pagination.
name: cursor
in: query
- schema:
type: string
enum:
- 'true'
- 'false'
description: Filter by processing status.
required: false
description: Filter by processing status.
name: isProcessingDone
in: query
- schema:
type: string
enum:
- 'true'
- 'false'
description: Filter by entity extraction status.
required: false
description: Filter by entity extraction status.
name: isEntityExtractionDone
in: query
- schema:
type: string
enum:
- 'true'
- 'false'
description: Filter by summary status.
required: false
description: Filter by summary status.
name: isSummaryDone
in: query
- schema:
type: string
enum:
- 'true'
- 'false'
description: >-
Include CRM link IDs for the recording (integration connection,
users, engagement, opportunity, contacts, account, lead).
required: false
description: >-
Include CRM link IDs for the recording (integration connection,
users, engagement, opportunity, contacts, account, lead).
name: showCrmLinks
in: query
- schema:
type: string
enum:
- 'true'
- 'false'
description: Include the recording summary results.
required: false
description: Include the recording summary results.
name: showSummary
in: query
- schema:
type: string
enum:
- 'true'
- 'false'
description: Include the recording entity extractions.
required: false
description: Include the recording entity extractions.
name: showEntityExtractions
in: query
- schema:
type: string
enum:
- 'true'
- 'false'
description: Include the scorecard evaluation score for the recording.
required: false
description: Include the scorecard evaluation score for the recording.
name: showEvaluationScore
in: query
- schema:
type: string
enum:
- 'true'
- 'false'
description: >-
Include followups for the recording. List returns id/score
summaries; GET by id returns the full followup payload.
required: false
description: >-
Include followups for the recording. List returns id/score
summaries; GET by id returns the full followup payload.
name: showFollowups
in: query
responses:
'200':
description: Get recordings
content:
application/json:
schema:
type: object
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
organizationId:
type: string
userId:
type: string
title:
type: string
durationInMilliseconds:
type: number
latitude:
type: number
longitude:
type: number
result:
type: string
enum:
- OPEN
- WON
- LOST
createdAt:
type: string
updatedAt:
type: string
rootDataPurgedAt:
type: string
nullable: true
deleted:
type: boolean
description: >-
Whether the recording has been deleted. Deleted
recordings are still returned so consumers can
reconcile them; check this flag (and deletedAt) to
handle them.
deletedAt:
type: string
nullable: true
description: >-
When the recording was deleted, if it has been
deleted.
links:
type: object
properties:
web:
type: object
properties:
self:
type: string
required:
- self
required:
- web
isProcessingDone:
type: boolean
isEntityExtractionDone:
type: boolean
isSummaryDone:
type: boolean
crm:
type: object
properties:
integrationConnectionId:
type: string
description: >-
Siro internal IntegrationConnection id for the
CRM connection
users:
type: array
items:
type: object
properties:
id:
type: string
description: Internal Siro ID for the external object
externalId:
type: string
description: >-
External ID for the external object in the
CRM
required:
- id
- externalId
description: CRM Engagement User(s) owning the recording
engagement:
type: object
properties:
id:
type: string
description: Internal Siro ID for the external object
externalId:
type: string
description: >-
External ID for the external object in the
CRM
required:
- id
- externalId
description: CRM Engagement tied to the recording
opportunity:
type: object
properties:
id:
type: string
description: Internal Siro ID for the external object
externalId:
type: string
description: >-
External ID for the external object in the
CRM
required:
- id
- externalId
description: CRM Opportunity tied to the recording
contacts:
type: array
items:
type: object
properties:
id:
type: string
description: Internal Siro ID for the external object
externalId:
type: string
description: >-
External ID for the external object in the
CRM
required:
- id
- externalId
description: CRM Contact(s) tied to the recording
account:
type: object
properties:
id:
type: string
description: Internal Siro ID for the external object
externalId:
type: string
description: >-
External ID for the external object in the
CRM
required:
- id
- externalId
description: CRM Account tied to the recording
lead:
type: object
properties:
id:
type: string
description: Internal Siro ID for the external object
externalId:
type: string
description: >-
External ID for the external object in the
CRM
required:
- id
- externalId
description: CRM Lead tied to the recording
required:
- integrationConnectionId
summary:
type: array
items:
type: object
properties:
id:
type: string
name:
type: string
content:
type: string
required:
- id
- name
- content
entityExtractions:
type: array
items:
type: object
properties:
name:
type: string
value:
anyOf:
- type: string
- type: array
items:
type: string
- type: string
- type: number
- type: boolean
- nullable: true
- type: array
items:
anyOf:
- type: string
- type: number
- type: boolean
- nullable: true
- nullable: true
- nullable: true
mappings:
type: array
nullable: true
items:
type: object
properties:
crmModelName:
type: string
crmFieldName:
type: string
required:
- crmModelName
- crmFieldName
required:
- name
evaluationScore:
type: number
description: Scorecard evaluation score for the recording
followups:
type: array
items:
type: object
properties:
id:
type: string
score:
type: number
description: >-
Slim followup summaries (id and score). Use GET
/recordings/{id}?showFollowups=true for the full
followup payload.
required:
- id
- organizationId
- userId
- title
- durationInMilliseconds
- latitude
- longitude
- result
- createdAt
- updatedAt
- deleted
- links
cursor:
type: string
nullable: true
description: Opaque cursor for pagination
required:
- data
- cursor
security:
- bearerAuth: []
components:
securitySchemes:
bearerAuth:
type: http
scheme: bearer
bearerFormat: Access token
description: >-
Client app access token from POST https://auth.siro.ai/oauth2/token, or
a legacy organization API token (Person icon → API Tokens). Send
`Authorization: Bearer `.
x-default: Bearer
````
This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.