Skip to main content

​
Overview

​
What you’ll build

A bidirectional integration enabling:
  • Automatic recording-to-opportunity matching
  • CRM context in Siro (customer names, deal amounts, outcomes)
  • Entity extraction data flowing back to your CRM

​
Time estimate

4-8 hours for a developer familiar with REST APIs

​
Prerequisites

  • API development experience
  • Admin access to your Siro workspace
  • Your system exposes appointment/opportunity data via API or database

​
Step 1: Get Your Siro API Credentials

​
Generate Your API Key

  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 in all API requests

​
API Base URL

Most API calls use: 
https://functions.siro.ai/api-externalApi/v1
Authentication: Include your API key in the header: 
curl --request GET \
  --url 'https://functions.siro.ai/api-externalApi/v1/core/mobile-events?pageSize=100' \
  --header 'Authorization: Bearer <token>'
Documentation: Full API reference at docs.siro.ai

​
Step 2: Understand the Basics of the Data Model

Siro’s integration data model maps to standard CRM concepts:
Your SystemSiro EquivalentPurpose
Sales Rep / User in your CRMUserLink reps in CRM to reps in Siro
Customer / AccountAccountCustomer information
Opportunity / Deal / LeadOpportunitySales outcomes with dollar values
Appointment / MeetingEngagementScheduled interactions that get recorded
RecordingRecordingsSiro recording

​
Key Relationship

The critical link is: Recording ↔ Engagement ↔ Opportunity AND/OR Account When you sync an Engagement to Siro with appointment details (time, location, rep), Siro can automatically match recordings to that engagement and surface the linked Opportunity context.

​
Step 3: Sync Your Data to Siro

User linking happens automatically. When you sync engagements or opportunities, include your CRM’s user identifier with externalId, email, and name. Siro automatically maps to existing workspace users by email or name match. Manual override available in Settings → Integrations → User Mapping.

​
3.2 Sync Appointments (Engagements)

This is the core of the integration. Syncing engagements enables appointment lists for reps, automatic recording linking, and CRM context for AI features. Endpoint: PUT /v1/integrations/sync/engagements • Full docs Example request: 
curl --request PUT \
  --url 'https://functions.siro.ai/api-externalApi/v1/integrations/sync/engagements' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '@-' <<EOF
{
  "externalId": "appt-456",
  "startTime": "2026-02-15T14:00:00Z",
  "endTime": "2026-02-15T15:00:00Z",
  "subject": "Smith Kitchen Remodel Consultation",
  "engagementType": {
    "activityType": "MEETING",
    "name": "meeting"
  },
  "engagementUsers": [
    {
      "externalId": "rep-123-from-your-crm",
      "email": "[email protected]",
      "name": "John Sales"
    }
  ],
  "account": {
    "externalId": "account-789"
  },
  "opportunity": {
    "externalId": "opp-101"
  }
}
EOF
Payload notes:
  • activityType: Valid values are MEETING, CALL, APPOINTMENT, EMAIL, TEXT, EVENT
  • Only MEETING, APPOINTMENT, and EVENT appear in the Appointment List feature

​
3.3 Sync Opportunities

Adds deal context (amount, disposition, customer name) to recordings. Endpoint: PUT /v1/integrations/sync/opportunities • Full docs Example request: 
curl --request PUT \
  --url 'https://functions.siro.ai/api-externalApi/v1/integrations/sync/opportunities' \
  --header 'Authorization: Bearer YOUR_API_TOKEN' \
  --header 'Content-Type: application/json' \
  --data '@-' <<EOF
{
  "externalId": "opp-101",
  "name": "Smith Kitchen Remodel",
  "amount": 45000,
  "closedAt": "2026-03-01T00:00:00Z",
  "disposition": "WON",
  "account": {
    "externalId": "account-789"
  },
  "opportunityUsers": [
    {
      "externalId": "rep-123-from-your-crm",
      "email": "[email protected]",
      "name": "John Sales"
    }
  ]
}
EOF

​
3.4 Sync Accounts

Adds customer context (name, address, contact info) to recordings. Account syncing happens automatically when you include the nested account object with an externalId in engagement or opportunity payloads. See the engagement example in 3.2 for the basic structure, or add optional fields like emailAddresses, phoneNumbers, and addresses as needed.

​
Step 4: Pull Data from Siro Back to Your System

Once recordings are created and linked, retrieve AI-generated insights. Note: Most endpoints use your organization API token. Get Entity Extractions (section 4.2) requires OAuth authentication. Skip OAuth setup if you don’t need entity extractions.

​
OAuth Setup (Required for Entity Extractions Only)

​
1. Create an OAuth App

Endpoint: POST /v1/core/oauth/apps • Full docs Provide appName, owner (user-id), and organizationId. Store the returned clientID and clientSecret securely.

​
2. Generate OAuth Access Tokens

Endpoint: POST /v1/core/oauth/apps/{clientId}/access-token • Full docs Provide clientSecret, userId, and scope: "read". Use the returned accessToken for entity extractions. Tokens expire after 16 hours.

​
4.1 Get Linked Recording for an Engagement

Endpoint: GET /v1/integrations/engagements/{id} • Full docs Response includes: 
{
    "id": "eng-123",
    "externalId": "appt-456",
    "recordingId": "rec-abc-def",
    "engagementType": "appointment",
    "opportunityId": "opp-101",
    "accountId": "account-789"
}
Use the recordingId to fetch detailed data.

​
4.2 Get Entity Extractions (CRM Autofill Data)

Endpoint: GET /v1/core/entities/extractions/{recordingId} • Full docs Base URL: https://siro-gateway-867voja4.uc.gateway.dev Note: This base URL is different from other API endpoints. Authentication: Use OAuth access token (header: x-siro-auth-token) Response example: 
{
    "data": [
        {
            "id": "extraction_001",
            "recordingId": "rec-abc-def",
            "extraction": [
                {
                    "name": "Budget",
                    "value": "$40,000 - $50,000"
                },
                {
                    "name": "Timeline",
                    "value": "Spring 2026"
                },
                {
                    "name": "Decision Maker",
                    "value": "Both homeowners present, wife is primary"
                },
                {
                    "name": "Objections",
                    "value": "Concerned about project timeline due to summer vacation plans"
                }
            ],
            "createdAt": "2026-01-28T00:00:00Z",
            "updatedAt": "2026-01-28T00:00:00Z"
        }
    ]
}
Use case: Write extracted fields back to your CRM to auto-populate data from conversations.

​
4.3 Get Recording Summaries

Endpoint: GET /v1/core/recordings/{recordingId}/summaries Response: 
{
    "data": [
        {
            "id": "summary-001",
            "name": "AI Summary",
            "content": "Summary text here..."
        }
    ]
}
Use case: Write summaries as CRM notes to create an activity trail.

​
Auto Start/Stop via Deep Linking (Optional)

Start Siro recordings directly from your mobile app: URL format: 
siro://record?appointmentId={external-id}&title={customer-name}&opportunityId={opp-external-id}
Example: 
siro://record?appointmentId=appt-456&title=Smith Kitchen Remodel&opportunityId=opp-101
Siro will use the appointmentId to link the recording to the engagement and opportunityId to link the associated opportunity immediately.

​
Next Steps

  • Test it: Sync a test appointment, record a conversation at that time, and verify CRM context appears
  • Automate syncs: Use real-time webhooks (recommended) or batch jobs every 10 minutes
  • Custom fields: Work with your CSM to configure custom entity extraction fields
  • Troubleshoot: If recordings aren’t linking, check Settings → Users to verify email mappings
  • Train your team: Show reps how recordings link to CRM records

​
Getting Help

Technical questions: Email your Customer Success Manager or reach out to [email protected] API issues: Include your request details (method, endpoint, payload) and organization ID when reaching out.