Skip to main content
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):
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.
  1. Create an OAuth access token (use your org API token):
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": "read"}'
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.

​
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. 
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 SystemSiro EquivalentPurpose
Sales rep/agentuserIdLinks the recording to the rep on call
Rep emailuserEmailFallback to link the recording to the rep on call
Rep phone numberuserPhoneFallback to link the recording to the rep on call
Recorded audio filefileUrlPoints to the audio file for Siro to ingest and transcribe
Call start timedateCreatedSets the actual call timestamp in Siro (not the upload time)
Your connected CRM accountintegrationConnectionIdIdentifies 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 between the recording and specific CRM objects
Customer phonecustomerPhoneFallback to link recording to CRM object when CRM object IDs are not shared
Customer namecustomerNameFallback 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 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 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
  • To successfully link a recording to a CRM object you must share integrationConnectionId and crmObjects[] = {objectType, objectId} . 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, customerPhone and customerName 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). 
{
  "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",
  "customer_name": "Jane Smith",
  "customer_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 theuserId 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.

​
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 as a unique identifier for attaching metadata to your uploaded recording in Siro in step 3. Endpoint: POST /v1/core/recordings/signed-urls Request 
POST /v1/core/recordings/signed-urls
x-siro-auth-token: <oauth-access-token>
Content-Type: application/json

{
	"fileSizeInBytes": 1048576, // required
	"fileType": "m4a", // required
	"organizationId": "my-org-id" // optional
}
Response 200 OK 
{
  "data": {
    "uploadUrl": "https://...",
    "downloadUrl": "https://...",
    "expiresAt": "2025-02-18T12:00:00.000Z"
  }
}

​
Payload notes

  • Use uploadUrl to complete upload recording in step 2
  • downloadUrl will be a unique identifier that needs to be passed 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 
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 identifier from step 1 to attach correct metadata to the related audio file to match the audio file to the correct rep, match the audio file to the correct CRM object, and allow the recording to be processed properly in Siro. Endpoint: POST /v2/core/recordings Request 
POST /v2/core/recordings
x-siro-auth-token: <oauth-access-token>
Content-Type: application/json

{
  "downloadUrl": "https://...", // required, Siro needs this to get the file that a client has uploaded
  "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, infer from user context or use default
  "integrationConnectionId": "string", // optional
  "crmObjects": { /* CrmObjectReference */ }[], // optional
  "customerPhone": "string", // optional
  "customerName": "string", // optional
  "dateCreated": "2025-02-18T12:00:00.000Z" // optional
}
Response 201 Created 
{
  "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 userNumber so Siro can attach the recording to the correct rep.
    • If there is no userId , userEmail , or userNumber the recording will not be ingested or processed.
  • Recording ↔ CRM Objects (CRM linking) : If your CRM is integrated, include integrationConnectionId and crmObjects to create a link between the recording and the CRM object.
    • If crmObjects are not available to share, share customerName and customerPhone 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 customersuccess@siro.ai
  • API issues: Include your request details (method, endpoint, payload) and organization ID when reaching out.