> ## 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 recording
> Get a recording by id
Returns a single recording by its Siro internal id. By default the response contains the recording's core fields; opt into the enrichment blocks below to also pull CRM links, the AI summary, entity extractions, and followups in the same request.
## 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 |
A deleted recording is **still returned** by this endpoint (it does not 404) — it comes back with `deleted: true`. Treat that 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/{id}?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": [
{
"followupId": "abcd-...",
"recordingId": "1234-1234-1234-1234-1234",
"recordingTitle": "Appointment to Win",
"followupType": "REHASH",
"score": 4,
"status": "TO_DO",
"starred": false,
"followupAction": "Call back to address pricing objection",
"repId": "rep-...",
"repName": "Alex Rep",
"teamId": "team-...",
"teamName": "East Region",
"dateCreated": "2026-06-23T15:50:00.000Z",
"updatedAt": "2026-06-23T15:50:00.000Z",
"context": [
{ "header": "MAIN_OBJECTION", "value": "Price too high" }
],
"thinking": "Strong intent with a clear pricing objection."
}
]
}
}
```
## OpenAPI
````yaml specs/openapi-externalApi.json get /v1/core/recordings/{id}
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/{id}:
get:
summary: Get recording
description: Get a recording by id
parameters:
- schema:
type: string
required: true
name: id
in: path
- 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 recording
content:
application/json:
schema:
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:
recordingId:
type: string
description: Followup recording id
recordingTitle:
type: string
nullable: true
description: Followup recording title
repName:
type: string
description: Followup rep name
repId:
type: string
description: Followup rep id
teamName:
type: string
nullable: true
description: Followup team name
teamId:
type: string
description: Followup team id
followupId:
type: string
description: Followup id
dateCreated:
type: string
description: Followup date created. ISO 8601 UTC timestamp.
followupType:
type: string
enum:
- REHASH
- CROSS_SELL
description: Followup type. Can be REHASH or CROSS_SELL.
score:
type: number
description: Followup score. Can be between 1 and 5.
followupAction:
type: string
nullable: true
description: Followup action
context:
type: array
items:
type: object
properties:
header:
type: string
description: >-
Followup context header. Can be
MAIN_OBJECTION, EMOTIONAL_TIE, OVERALL_COST,
SCOPE, FOLLOW_UP_TIME, SECONDARY_OBJECTION,
SCOPE_COST_SUMMARY, OBJECTION_SUMMARY,
FOLLOW_UP_SUMMARY, FIRST_PRICE_QUOTE,
FINAL_PRICE_QUOTE, PRICING_OPTIONS, FINANCING,
COMMITMENT.
value:
type: string
description: Followup context value
required:
- header
- value
description: Followup context
updatedAt:
type: string
description: Followup updated at. ISO 8601 UTC timestamp.
metadata:
type: array
items:
type: object
additionalProperties:
type: string
description: Followup metadata
starred:
type: boolean
description: Followup starred state. Can be true or false.
status:
type: string
enum:
- TO_DO
- IN_PROGRESS
- COMPLETE
description: >-
Followup status. Can be TO_DO, IN_PROGRESS, or
COMPLETE.
thinking:
type: string
description: Followup thinking and score breakdown
history:
type: array
nullable: true
items:
type: object
properties:
id:
type: string
description: Followup history id
updatedBy:
type: string
description: Followup history updated by
updatedByUserId:
type: string
nullable: true
description: >-
Followup history updated by user id. Null if
the updated by is a Siro system action.
createdAt:
type: string
description: >-
Followup history created at. ISO 8601 UTC
timestamp.
note:
type: string
description: Followup history note
status:
type: string
enum:
- TO_DO
- IN_PROGRESS
- COMPLETE
description: Followup history status
required:
- id
- updatedBy
- updatedByUserId
- createdAt
description: >-
Followup history. Returns all status changes and
notes for the followup.
crmUrl:
type: string
nullable: true
description: URL to the customer in the linked CRM (DEPRECATED)
crmCustomer:
type: object
nullable: true
properties:
id:
type: string
description: Customer ID
name:
type: string
nullable: true
description: Customer name
crmUrl:
type: string
description: URL to this customer in the linked CRM
customerType:
type: string
enum:
- ACCOUNT
- LEAD
- OPPORTUNITY
- ENGAGEMENT
- CONTACT
- DMS_OPPORTUNITY
lastActivityAt:
type: string
nullable: true
description: Last activity date
createdAt:
type: string
format: date-time
description: Date the Customer record was created in Siro
updatedAt:
type: string
format: date-time
description: >-
Date the Customer record was last updated in
Siro
closedAt:
type: string
nullable: true
format: date-time
description: >-
Date the Customer was closed (applicable to
Opportunities)
emailAddress:
type: string
nullable: true
description: Customer email addresses
phoneNumber:
type: string
nullable: true
description: Customer phone numbers
externalId:
type: string
nullable: true
description: Customer external ID
opportunityExternalId:
type: string
nullable: true
description: >-
External ID of the linked CRM Opportunity/Lead,
if any
accountExternalId:
type: string
nullable: true
description: >-
External ID of the linked CRM Account/Prospect,
if any
leadExternalId:
type: string
nullable: true
description: External ID of the linked CRM Lead, if any
contactExternalId:
type: string
nullable: true
description: External ID of the linked CRM Contact, if any
amount:
type: number
nullable: true
description: Dollar amount associated with a Customer deal
disposition:
type: string
nullable: true
description: >-
Disposition for the Customer deal: "WON" |
"LOST" | "OPEN"
recordingId:
type: string
nullable: true
description: >-
ID of the most recent recording linked to this
customer
lastRecordingDate:
type: string
nullable: true
format: date-time
description: >-
Datetime of the most recent recording linked to
this customer
numRecordings:
type: number
nullable: true
description: >-
Total number of recordings linked to this
customer
matchingSource:
type: string
nullable: true
enum:
- DIRECT
- FUZZY
- NOT_FOUND
description: Source of matching
accountId:
type: string
nullable: true
description: Account ID
accountOwnerName:
type: string
nullable: true
description: >-
Name of the owning CRM user, for ACCOUNT
customers
opportunityAccountName:
type: string
nullable: true
description: Account Name associated with the Opportunity
contactId:
type: string
nullable: true
description: Contact ID
opportunityContactName:
type: string
nullable: true
description: Contact Name associated with the Opportunity
opportunityId:
type: string
nullable: true
description: Opportunity ID
engagementId:
type: string
nullable: true
description: Engagement ID
opportunity:
type: object
nullable: true
properties:
id:
type: string
externalId:
type: string
description: >-
The ID of the opportunity in the external
system (e.g. Salesforce)
name:
type: string
nullable: true
description: The name of the opportunity
amount:
type: number
description: The dollar amount of the opportunity
closedAt:
type: string
description: The closure date of the opportunity
disposition:
type: string
description: '"WON" | "LOST" | "OPEN"'
stageName:
type: string
nullable: true
description: >-
The opportunity stage name in the external
system
createdAt:
type: string
description: The date the opportunity was created
updatedAt:
type: string
description: The date the opportunity was last updated
deletedAt:
type: string
nullable: true
description: >-
The date the opportunity was soft-deleted,
if any
recordingId:
type: string
description: >-
The ID of the recording associated to the
opportunity
accountId:
type: string
organizationId:
type: string
account:
nullable: true
opportunityUsers:
type: array
items:
nullable: true
required:
- id
- externalId
- createdAt
- updatedAt
- organizationId
description: Opportunity
opportunities:
type: object
nullable: true
properties:
data:
type: array
items:
type: object
properties:
id:
type: string
externalId:
type: string
description: >-
The ID of the opportunity in the
external system (e.g. Salesforce)
name:
type: string
nullable: true
description: The name of the opportunity
amount:
type: number
description: The dollar amount of the opportunity
closedAt:
type: string
description: The closure date of the opportunity
disposition:
type: string
description: '"WON" | "LOST" | "OPEN"'
stageName:
type: string
nullable: true
description: >-
The opportunity stage name in the
external system
createdAt:
type: string
description: The date the opportunity was created
updatedAt:
type: string
description: >-
The date the opportunity was last
updated
deletedAt:
type: string
nullable: true
description: >-
The date the opportunity was
soft-deleted, if any
recordingId:
type: string
description: >-
The ID of the recording associated to
the opportunity
accountId:
type: string
organizationId:
type: string
account:
nullable: true
opportunityUsers:
type: array
items:
nullable: true
required:
- id
- externalId
- createdAt
- updatedAt
- organizationId
cursor:
type: string
nullable: true
required:
- data
description: >-
Optional first page of related opportunities for
Accounts or Contacts
opportunityUsers:
type: array
nullable: true
items:
nullable: true
description: Users associated with the opportunity
contactAccount:
type: object
nullable: true
properties:
id:
type: string
name:
type: string
nullable: true
description: The name of the account
externalId:
type: string
nullable: true
description: >-
The ID of the account in the external system
(e.g. Salesforce)
required:
- id
description: Contact Account
address:
type: string
nullable: true
description: Address
organizationId:
type: string
description: Organization ID
integrationConnectionId:
type: string
nullable: true
description: Integration Connection ID
integrationPlatform:
type: string
nullable: true
enum:
- MERGE
- SIRO_CUSTOM_INPUT
- SERVICE_TITAN
- COMPANY_CAM
- INGAGE
- LEAD_PERFECTION
- SPOTIO
description: Integration Platform
integrationName:
type: string
nullable: true
description: Integration Name
required:
- id
- createdAt
- updatedAt
- organizationId
description: >-
Followup CRM customer. Includes the CRM customer if
the followup is associated with a CRM customer.
hasFollowupComment:
type: boolean
description: >-
Whether the followup has a followup specific comment
on the associated recording.
note:
type: string
nullable: true
description: >-
Followup note. Deprecated in favor of
FollowupHistory.
completed:
type: boolean
description: >-
Followup completed state. Deprecated in favor of
status, which is included in FollowupHistory.
completedBy:
type: string
nullable: true
description: >-
Followup completed by. Deprecated in favor of
FollowupHistory.
completedAt:
type: string
nullable: true
description: >-
Followup completed at. ISO 8601 UTC timestamp.
Deprecated in favor of FollowupHistory.
required:
- recordingId
- recordingTitle
- repName
- repId
- teamName
- teamId
- followupId
- dateCreated
- followupType
- score
- followupAction
- context
- updatedAt
- metadata
- starred
- status
- thinking
- crmCustomer
- hasFollowupComment
- note
- completed
- completedBy
- completedAt
description: >-
Array of follow-up actions and communications generated
from the recording
required:
- id
- organizationId
- userId
- title
- durationInMilliseconds
- latitude
- longitude
- result
- createdAt
- updatedAt
- deleted
- links
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.