> ## 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.

# Create or replace CRM link on a recording

> Links the recording to a CRM Account, Contact, Lead, Opportunity, or Engagement (server clears prior links as needed).

**Path parameter `id`:** Siro’s internal **recording** id (from recording list/detail APIs). It is not a CRM external id.

**Request body — pick one way to point at the CRM row**

1. **Siro internal id:** set **`id`** to the integrations DB id of the Account, Contact, Lead, Opportunity, or Engagement (the synced CRM row’s primary key in Siro—not a **Siro User** id). Do not send `externalId` or `integrationConnectionId`.
2. **CRM-native id:** set **`externalId`** to the id in the source CRM **and** **`integrationConnectionId`** to the Siro integration connection for that tenant. Do not send `id`.

**Always include `dataType`** (`ACCOUNT`, `CONTACT`, `LEAD`, `OPPORTUNITY`, or `ENGAGEMENT`). **`trigger`** is optional; allowed values appear in the request schema below.

**Validation (typical 422)** The API rejects the body if you send both `id` and `externalId`, neither, or `externalId` without a non-empty `integrationConnectionId`.

**Examples**

```json theme={null}
{
  "dataType": "ACCOUNT",
  "id": "01HZX0M4K3N7Q2V8R9T0Y1A2B3C"
}
```

```json theme={null}
{
  "dataType": "OPPORTUNITY",
  "externalId": "006xx0000123456",
  "integrationConnectionId": "01HABCD1234567890EFGHIJKLMN"
}
```


## OpenAPI

````yaml specs/openapi-internalApi.json put /v1/core/recordings/{id}/link
openapi: 3.0.0
info:
  version: 1.0.0
  title: Swagger API
servers:
  - url: https://api.siro.ai/
    description: Siro API Gateway
security: []
externalDocs:
  description: View the raw OpenAPI Specification in JSON format
  url: /swagger.json
paths:
  /v1/core/recordings/{id}/link:
    put:
      summary: Create or replace the CRM link on a recording
      description: >-
        Links the recording to a CRM Account, Contact, Lead, Opportunity, or
        Engagement (server clears prior links as needed).
      parameters:
        - schema:
            type: string
            description: >-
              Siro internal id of the recording (the recording id returned by
              recording APIs). Not a CRM external id.
          required: true
          description: >-
            Siro internal id of the recording (the recording id returned by
            recording APIs). Not a CRM external id.
          name: id
          in: path
      requestBody:
        content:
          application/json:
            schema:
              type: object
              description: >-
                The path parameter identifies the recording. In the JSON body,
                identify the CRM entity using either (1) `id` — Siro's internal
                database id for that Account, Contact, Lead, Opportunity, or
                Engagement, or (2) `externalId` with `integrationConnectionId` —
                the CRM-native id plus the Siro integration connection that owns
                it. Send exactly one of `id` or `externalId` (not both, not
                neither).
              properties:
                id:
                  type: string
                  description: >-
                    Siro internal id of the CRM entity row. Omit when using
                    externalId.
                externalId:
                  type: string
                  description: >-
                    CRM-native external id for the entity. Requires
                    integrationConnectionId. Omit when using id.
                integrationConnectionId:
                  type: string
                  description: >-
                    Siro integration connection id (same resource as integration
                    connection list/detail APIs). Required when externalId is
                    set.
                dataType:
                  type: string
                  enum:
                    - ACCOUNT
                    - LEAD
                    - OPPORTUNITY
                    - ENGAGEMENT
                    - CONTACT
                  description: >-
                    Which CRM object type you are linking (must match the entity
                    identified by id or externalId).
                trigger:
                  type: string
                  enum:
                    - FUZZY_MATCH_RECORDINGS_FOR_ENGAGEMENT
                    - FUZZY_MATCH_ENGAGEMENTS_FOR_RECORDING
                    - FUZZY_MATCH_RECORDINGS_FOR_OPPORTUNITY
                    - FUZZY_MATCH_OPPORTUNITIES_FOR_RECORDING
                    - OPPORTUNITY_DEEPLINK_ADMIN
                    - OPPORTUNITY_DEEPLINK
                    - CRM_DEEPLINK
                    - AUDIO_UPLOAD_DEEPLINK
                    - CONTACT_MATCH_AUDIO_UPLOAD
                    - USER_LINK_WEB
                    - USER_LINK_MOBILE
                    - USER_LINK_POST_RECORDING
                    - USER_UNLINK
                    - USER_APPOINTMENT_LIST
                    - CALENDAR_MATCH
                    - RECORDING_HARD_DELETED
                  description: Recording Link trigger
              required:
                - dataType
      responses:
        '200':
          description: Create or replace the CRM link on a recording
          content:
            application/json:
              schema:
                anyOf:
                  - type: object
                    properties:
                      data:
                        type: object
                        properties:
                          id:
                            type: string
                            description: ID of the linked object
                          externalId:
                            type: string
                            description: External ID of the linked object in the CRM
                          dataType:
                            type: string
                            enum:
                              - ACCOUNT
                              - LEAD
                              - OPPORTUNITY
                              - ENGAGEMENT
                              - CONTACT
                            description: Type of the object that is linked to the response
                          name:
                            type: string
                          lastActivityAt:
                            type: string
                        required:
                          - id
                          - externalId
                          - dataType
                          - name
                          - lastActivityAt
                      cursor:
                        anyOf:
                          - type: string
                          - type: number
                          - nullable: true
                      pageSize:
                        type: number
                      limit:
                        type: number
                      total:
                        type: number
                        nullable: true
                      hasNextPage:
                        type: boolean
                    required:
                      - data
                  - type: object
                    properties:
                      error:
                        type: string
                      details:
                        type: object
                        additionalProperties:
                          nullable: true
                    required:
                      - error
      security:
        - SiroAuthToken: []
components:
  securitySchemes:
    SiroAuthToken:
      type: apiKey
      in: header
      name: x-siro-auth-token
      description: >-
        OAuth access token for user-scoped requests (Authorization Code or
        machine-to-machine). Send header `x-siro-auth-token:
        <oauth-access-token>`. Not an organization API key.
      x-default: <oauth-access-token>

````