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

# Quickstart Guide: Building a Custom API Phone Integration

> Learn how to build a custom API phone integration with Siro. Get phone call recordings from your VoIP/Phone System into Siro so they're treated as native recordings with full AI insights and coaching.

This guide walks you through getting completed phone call recordings from your VoIP/Phone System into Siro so they’re treated as *Siro native* recordings. You’ll build a simple 3-step pipeline:

* **Notify:** Detect when a call ends and the recording is ready.
* **Fetch:** Download the audio from your VoIP provider.
* **Forward:** Upload phone recordings into Siro

# Overview

**What you'll build:** A 3-step pipeline enabling:

* Automatic ingestion of completed phone recordings into Siro
* Rep attribution and CRM linking for phone recordings
* Siro’s AI insights and coaching on phone recordings

**Prerequisites:**

* API development capabilities
* Admin access to Siro workspace
* A VoIP/Phone System with recording export/download and API access

***

# Step 1: Get Your Siro API Credentials

### Generate your organization API token

1. Log into your Siro workspace as an admin.
2. Navigate to **Person Icon** → **API Tokens**.
3. Click **Generate New API Token**.
4. Store this securely - you’ll use it to create OAuth apps and access tokens.

### Create an OAuth app and access token

The audio upload endpoints require an **OAuth access token** (user-scoped).

1. **Create an OAuth app** (use your org API token):

```bash theme={null}
curl --request POST \
	--url 'https://functions.siro.ai/api-externalApi/v1/core/oauth/apps' \
	--header 'Authorization: Bearer <org-api-token>' \
	--header 'Content-Type: application/json' \
	--data '{"appName": "My Integration"}'
```

Response includes `clientId` and `clientSecret`. Store the client secret securely. It is only shown once.

Full documentation [HERE](https://docs.siro.ai/api-references/create-an-oauth-app).

1. **Create an OAuth access token** (use your org API token):

```bash theme={null}
curl --request POST \
	--url 'https://functions.siro.ai/api-externalApi/v1/core/oauth/apps/<clientId>/access-token' \
	--header 'Authorization: Bearer <org-api-token>' \
	--header 'Content-Type: application/json' \
	--data '{"clientSecret": "<client-secret>", "userId": "<user-uid>", "scope": "write"}'
```

Response includes `accessToken`. Token expires after 16 hours. Once `accessToken` expires, a new one must be generated by making a new POST to the above endpoint.

Full documentation [HERE](https://docs.siro.ai/api-references/create-an-oauth-access-token).

### API Base URL

The signed-urls endpoint lives in Siro’s API Gateway, with the base URL: `https://api.siro.ai/`

**Authentication:** Use your **OAuth access token** (not the org API token) in the header.

```bash theme={null}
curl --request POST \
	--url 'https://api.siro.ai/v1/core/recordings/signed-urls' \
	--header 'x-siro-auth-token: <oauth-access-token>'
```

***

# Step 2: Understand the Basics of the Data Model

Siro's integration data model to map recordings to reps and CRM objects:

| Your System                                                                 | Siro Equivalent                         | Purpose                                                                                                                               |
| --------------------------------------------------------------------------- | --------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| Sales rep/agent                                                             | `userId`                                | **Siro User** id (UUID)—the rep’s workspace login; not a CRM `externalId`                                                             |
| Rep email                                                                   | `userEmail`                             | Fallback to link the recording to the rep on call                                                                                     |
| Rep phone number                                                            | `userPhone`                             | Fallback to link the recording to the rep on call                                                                                     |
| Recorded audio file                                                         | `fileUrl`                               | Points to the audio file for Siro to ingest and transcribe                                                                            |
| Call start time                                                             | `dateCreated`                           | Sets the actual call timestamp in Siro (not the upload time)                                                                          |
| Your connected CRM account                                                  | `integrationConnectionId`               | Identifies the connected CRM instance (your Salesforce, HubSpot, Dynamics, etc.) so CRM linking is scoped correctly                   |
| CRM record IDs you want to link (Opportunity, Account, Contact, Lead, etc.) | `crmObjects[] = {objectType, objectId}` | Creates definite links to CRM entities Siro already knows for that connection (see [CRM entity IDs](/getting-started#crm-entity-ids)) |
| Contact phone                                                               | `contactPhone`                          | Fallback to link recording to CRM object when CRM object IDs are not shared                                                           |
| Contact name                                                                | `contactName`                           | Fallback to link recording to CRM object when CRM object IDs are not shared                                                           |

## Key Relationships

### **Recording ↔ User**

* **Prerequisite** : Your reps must be set up in Siro as users so recordings can be uploaded and properly attached to the correct rep
* To successfully link a recording to a user, share the **`userId`** (**Siro User** UUID) to create a definite link to the rep.
* If no `userId` is provided, `userEmail` or `userPhone` will be used to look up the rep and link the recording the associated rep.
* Once the recording is linked to a user, it is attributed to the rep in Siro and treated as Siro native recording, which unlocks the same features and insights as any recording captured directly in Siro, including coaching, call analytics, and insights.

### Recording **↔ CRM Object**

* **Prerequisite** : Your CRM must be integrated with Siro to link phone recordings to CRM objects. If you do not have your CRM integrated with Siro yet, reach out to your Customer Success Manager or [support@siro.ai](mailto:support@siro.ai) to get set up. You can also use an API-based CRM integration, follow this guide to get set up [https://docs.siro.ai/Integrations/Available\_Integrations](https://docs.siro.ai/Integrations/Available_Integrations)
* To successfully link a recording to a CRM object you must share `integrationConnectionId` and `crmObjects[] = {objectType, objectId}`.  `integrationConnectionId` can be retrieved via [GET /v1/core/integrations/connections](https://docs.siro.ai/api-references/get-integration-connections). This creates a definite link to those records. ***Note***: the `objectId` must already be present in our database (either from a native CRM integration or an API-based CRM integration) for the link to be created.
* If  no `crmObjects[] = {objectType, objectId}` is provided, `contactPhone` and `contactName` will be used to recommend links that can confirmed in the Siro platform.

***

# Step 3: Send Phone Call Recordings to Siro

## How It Works

1. Your VoIP system/phone carrier notifies your server when a call ends
2. Your server downloads the audio
3. Your server pushes downloaded audio to Siro

## 3.1 Notify — Detect Call End (Recording Ready Signal)

### VoIP → Your Server

Set up a reliable way for your system to detect when a call has ended and its recording is available to fetch from your VoIP. Common approaches include:

* **Webhooks:** Have your VoIP provider notify your server when a call ends or when the recording is ready.
* **Incremental polling:** Periodically check call logs or recording endpoints until the recording URL becomes available.

Use whichever mechanism your VoIP provider supports best (some offer both).

```json theme={null}
{
  "call_id": "call-789",
  "email": "rep@yourcompany.com",
  "number": "+14251234563",
  "recording_url": "https://your-voip.com/recordings/call-789.m4a",
  "started_at": "2026-02-23T14:00:00Z",
  "contact_name": "Jane Smith",
  "contact_phone": "+15551234567"
}
```

> *Exact fields vary by VoIP provider — use whatever fields your provider includes as metadata that will be used to facilitate the matching of the recording to a rep and CRM object in Siro as outlined in the data model.*

### Payload Notes

* `email` and `number` map to `userEmail` or `userNumber` respectively in the data model and are used to resolve the rep when the`userId` is not available.
* Best practice: use the VoIP payload to look up the rep’s Siro `userId`  and match the recording to the correct `userId`. This will enable the most reliable linking of recording to a rep. Use this endpoint to get rep’s Siro `userId` to map recordings to reps [https://docs.siro.ai/api-references/get-users](https://docs.siro.ai/api-references/get-users).

## 3.2 Fetch — Download the Audio from Your VoIP Provider

### VoIP → Your Server

Use the `recording_url` and your VoIP credentials to download the audio file. Follow the instructions of your VoIP provider for guidance on how to download audio files via API.

### Payload Notes

* Supported formats: .mp3, .aac, .wav.
* Max File Size: 100MB

## 3.3 Forward — Upload the Phone Recording to Siro

### Your Server → Siro API

Uploading to Siro is a three-step process: get a signed URL, upload recording via the signed upload URL, then create the recording in Siro.

### 1. Get a Signed Upload URL & Download URL

Post to the signed-urls endpoint to receive an `uploadUrl` to upload your recording to Siro in step 2 and a `downloadUrl` that you pass as `fileUrl` when creating the recording in step 3.

**Endpoint:** `POST /v1/core/recordings/signed-urls` • [Full docs](https://docs.siro.ai/api-references/post-recordings-signed-urls)

**Request**

```http theme={null}
POST /v1/core/recordings/signed-urls
x-siro-auth-token: <oauth-access-token>
Content-Type: application/json
```

```json theme={null}
{
	"fileSizeInBytes": 1048576, // required
	"fileType": "mp3", // required
	"organizationId": "my-org-id" // optional
}
```

**Response** `200 OK`

```json theme={null}
{
  "data": {
    "uploadUrl": "https://...",
    "downloadUrl": "https://...",
    "expiresAt": "2025-02-18T12:00:00.000Z"
  }
}
```

### **Payload notes**

* Use `uploadUrl` to complete upload recording in step 2
* The `downloadUrl` from the response is the value you send as `fileUrl` in step 3 to attach recording metadata to the uploaded recording

### 2. Upload recording to the `uploadUrl`

Make a `PUT` request to the `uploadUrl`

**Request**

```http theme={null}
PUT <uploadUrl>
Content-Type: <mimeType>
x-goog-content-length-range: 0,<fileSize>  
```

**Response** `2xx OK`

* This code means that the recording was uploaded successfully.
* The upload must be completed successfully before moving to the next step — creating recording in Siro.

### 3. Create the Recording

Once the audio file is uploaded, `POST` to the recordings endpoint.

Use the `downloadUrl` from step 1 as the `fileUrl` field in the upload request so Siro can load the uploaded audio and attach the correct metadata: rep attribution, CRM linking, and processing options.

**Endpoint:** `POST /v1/core/recordings/upload` • [Full docs](https://docs.siro.ai/api-references/post-recordings-upload)

**Request**

```http theme={null}
POST /v1/core/recordings/upload
x-siro-auth-token: <oauth-access-token>
Content-Type: application/json
```

```json theme={null}
{
  "fileUrl": "https://...", // required; use the downloadUrl from POST /v1/core/recordings/signed-urls
  "fileType": "string", // required, must be one of 'mp3', 'aac', 'wav'
  "title": "string", // optional
  "userId": "string", // optional, defers to email
  "userEmail": "string", // optional, defers to phone number
  "userPhone": "string", //optional
  "organizationId": "string", // optional, defaults to user's org
  "conversationType": "string", // optional, use default if not provided
  "integrationConnectionId": "string", // optional; if set, crmObjects must be set too (and vice versa)
  "crmObjects": { /* CrmObjectReference */ }[], // optional; if set, integrationConnectionId must be set too
  "contactPhone": "string", // optional
  "contactName": "string", // optional
  "dateCreated": "2025-02-18T12:00:00.000Z" // optional
}
```

**Response** `201 Created`

```json theme={null}
{
  "data": {
    "id": "recording-uuid"
}
```

### **Payload notes:**

* `dateCreated` : Use the actual call time (not the upload time).
* **Recording** **↔ User (rep attribution)** : Provide `userId` when possible. If not, provide `userEmail` or `userPhone` so Siro can attach the recording to the correct rep.
  * At least one of `userId`, `userEmail`, or `userPhone` must be present; otherwise the recording will not be ingested or processed.
* **Recording**  **↔ CRM Objects (CRM linking) :** If your CRM is integrated, include both `integrationConnectionId` and `crmObjects` to create a link between the recording and the CRM object (omit both if you are not linking CRM objects this way).
  * If  `crmObjects` are not available to share, share `contactName` and `contactPhone` for suggested linking in Siro.

***

# Notes

* Recordings should be available in Siro platform within 30 minutes of upload
* **Technical questions:** Email your Customer Success Manager or reach out to [support@siro.ai](mailto:support@siro.ai)
* **API issues:** Include your request details (method, endpoint, payload) and organization ID when reaching out.