Siro
Siro Platform API

The Siro Platform API served from the api.siro.ai gateway — 145 operations covering recordings and audio (list, detail, utterances, redacted-audio signed URLs, upload signed URLs, phone-call recording creation, CRM link create/replace/remove), conversation intelligence (summaries, entity extractions, followups, conversation configurations), coaching scorecards (available metrics, metric values, scorecard instances, evaluated instances), folders, org/team/user administration, in-product agents/sessions/jobs, and billing/licenses/invoices/subscription. This is the user-scoped surface Siro's own published Agent Skill documents as the second base URL alongside the External API; it authenticates with an OAuth access token in the x-siro-auth-token header.
Documentation GitHub OpenAPI
OpenAPI Specification

{
  "openapi": "3.0.0",
  "info": {
    "version": "1.0.0",
    "title": "Swagger API"
  },
  "externalDocs": {
    "description": "View the raw OpenAPI Specification in JSON format",
    "url": "/swagger.json"
  },
  "components": {
    "schemas": {
      "CrmCustomer": {
        "type": "object",
        "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"
          },
          "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"
          },
          "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\""
              },
              "createdAt": {
                "type": "string",
                "description": "The date the opportunity was created"
              },
              "updatedAt": {
                "type": "string",
                "description": "The date the opportunity was last updated"
              },
              "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\""
                    },
                    "createdAt": {
                      "type": "string",
                      "description": "The date the opportunity was created"
                    },
                    "updatedAt": {
                      "type": "string",
                      "description": "The date the opportunity was last updated"
                    },
                    "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": "CRM account linked to this recording",
        "example": {
          "id": "acc_12345",
          "name": "Acme Corporation",
          "customerType": "ACCOUNT",
          "externalId": "ext_67890",
          "createdAt": "2024-01-01T00:00:00.000Z",
          "updatedAt": "2024-01-15T08:30:00.000Z",
          "lastActivityAt": "2024-01-15T08:30:00.000Z",
          "matchingSource": "DIRECT",
          "emailAddress": "contact@acme.com",
          "phoneNumber": "+1-555-123-4567",
          "crmUrl": "https://acme.salesforce.com/lightning/r/Account/001XX000004C9Z6YAK/view",
          "organizationId": "12345"
        }
      },
      "DmsOpportunity": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string",
            "description": "Opportunity ID"
          },
          "externalId": {
            "type": "string",
            "description": "Opportunity external ID"
          },
          "name": {
            "type": "string",
            "nullable": true,
            "description": "Opportunity name"
          },
          "description": {
            "type": "string",
            "nullable": true,
            "description": "Opportunity description"
          },
          "status": {
            "type": "string",
            "nullable": true,
            "description": "Opportunity status"
          },
          "disposition": {
            "type": "string",
            "nullable": true,
            "description": "Disposition for the DMS opportunity: \"WON\" | \"LOST\" | \"OPEN"
          },
          "department": {
            "type": "string",
            "nullable": true,
            "description": "Department associated with the opportunity"
          },
          "dealType": {
            "type": "string",
            "nullable": true,
            "description": "Deal type of the opportunity: \"CASH\" | \"FINANCE\" | \"LEASE\" | \"SERVICE\""
          },
          "amount": {
            "type": "number",
            "nullable": true,
            "description": "Dollar amount associated with the opportunity"
          },
          "closedAt": {
            "type": "string",
            "nullable": true,
            "format": "date-time",
            "description": "Date the opportunity was closed"
          },
          "dmsOpportunityType": {
            "type": "string",
            "description": "DMS opportunity type"
          },
          "createdAt": {
            "type": "string",
            "format": "date-time",
            "description": "Date the opportunity record was created in Siro"
          },
          "updatedAt": {
            "type": "string",
            "format": "date-time",
            "description": "Date the opportunity record was last updated in Siro"
          },
          "lastActivityAt": {
            "type": "string",
            "nullable": true,
            "format": "date-time",
            "description": "Last activity date"
          },
          "organizationId": {
            "type": "string",
            "description": "Organization ID"
          },
          "integrationConnectionId": {
            "type": "string",
            "description": "Integration Connection ID"
          },
          "integrationPlatform": {
            "type": "string",
            "nullable": true,
            "description": "DMS Integration Platform"
          },
          "integrationName": {
            "type": "string",
            "nullable": true,
            "description": "Integration Name"
          },
          "primaryCustomer": {
            "type": "object",
            "nullable": true,
            "properties": {
              "id": {
                "type": "string",
                "description": "Customer ID"
              },
              "name": {
                "type": "string",
                "nullable": true,
                "description": "Customer name"
              },
              "customerType": {
                "type": "string",
                "nullable": true,
                "description": "DMS customer type"
              },
              "businessType": {
                "type": "string",
                "nullable": true,
                "description": "DMS customer business type"
              },
              "lastActivityAt": {
                "type": "string",
                "nullable": true,
                "format": "date-time",
                "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"
              },
              "emailAddresses": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Customer email addresses"
              },
              "phoneNumbers": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Customer phone numbers"
              },
              "externalId": {
                "type": "string",
                "description": "Customer external ID"
              },
              "addresses": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "street": {
                      "type": "string"
                    },
                    "city": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string"
                    },
                    "zip": {
                      "type": "string",
                      "nullable": true
                    },
                    "country": {
                      "type": "string",
                      "nullable": true
                    },
                    "addressType": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": [
                    "street",
                    "city",
                    "state",
                    "zip",
                    "country",
                    "addressType"
                  ]
                },
                "description": "Customer addresses"
              },
              "organizationId": {
                "type": "string",
                "description": "Organization ID"
              },
              "integrationConnectionId": {
                "type": "string",
                "description": "Integration Connection ID"
              }
            },
            "required": [
              "id",
              "name",
              "customerType",
              "businessType",
              "lastActivityAt",
              "createdAt",
              "updatedAt",
              "emailAddresses",
              "phoneNumbers",
              "externalId",
              "addresses",
              "organizationId",
              "integrationConnectionId"
            ]
          },
          "secondaryCustomer": {
            "type": "object",
            "nullable": true,
            "properties": {
              "id": {
                "type": "string",
                "description": "Customer ID"
              },
              "name": {
                "type": "string",
                "nullable": true,
                "description": "Customer name"
              },
              "customerType": {
                "type": "string",
                "nullable": true,
                "description": "DMS customer type"
              },
              "businessType": {
                "type": "string",
                "nullable": true,
                "description": "DMS customer business type"
              },
              "lastActivityAt": {
                "type": "string",
                "nullable": true,
                "format": "date-time",
                "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"
              },
              "emailAddresses": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Customer email addresses"
              },
              "phoneNumbers": {
                "type": "array",
                "items": {
                  "type": "string"
                },
                "description": "Customer phone numbers"
              },
              "externalId": {
                "type": "string",
                "description": "Customer external ID"
              },
              "addresses": {
                "type": "array",
                "items": {
                  "type": "object",
                  "properties": {
                    "street": {
                      "type": "string"
                    },
                    "city": {
                      "type": "string"
                    },
                    "state": {
                      "type": "string"
                    },
                    "zip": {
                      "type": "string",
                      "nullable": true
                    },
                    "country": {
                      "type": "string",
                      "nullable": true
                    },
                    "addressType": {
                      "type": "string",
                      "nullable": true
                    }
                  },
                  "required": [
                    "street",
                    "city",
                    "state",
                    "zip",
                    "country",
                    "addressType"
                  ]
                },
                "description": "Customer addresses"
              },
              "organizationId": {
                "type": "string",
                "description": "Organization ID"
              },
              "integrationConnectionId": {
                "type": "string",
                "description": "Integration Connection ID"
              }
            },
            "required": [
              "id",
              "name",
              "customerType",
              "businessType",
              "lastActivityAt",
              "createdAt",
              "updatedAt",
              "emailAddresses",
              "phoneNumbers",
              "externalId",
              "addresses",
              "organizationId",
              "integrationConnectionId"
            ]
          },
          "primaryVehicle": {
            "type": "object",
            "nullable": true,
            "properties": {
              "id": {
                "type": "string"
              },
              "vin": {
                "type": "string"
              },
              "make": {
                "type": "string",
                "nullable": true
              },
              "model": {
                "type": "string",
                "nullable": true
              },
              "trim": {
                "type": "string",
                "nullable": true
              },
              "year": {
                "type": "number",
                "nullable": true
              },
              "stockNumber": {
                "type": "string",
                "nullable": true
              },
              "mileage": {
                "type": "number",
                "nullable": true
              }
            },
            "required": [
              "id",
              "vin",
              "make",
              "model",
              "trim",
              "year",
              "stockNumber",
              "mileage"
            ]
          },
          "lineItems": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "externalId": {
                  "type": "string"
                },
                "name": {
                  "type": "string",
                  "nullable": true
                },
                "description": {
                  "type": "string",
                  "nullable": true
                },
                "price": {
                  "type": "number",
                  "nullable": true
                },
                "type": {
                  "type": "string",
                  "nullable": true
                }
              },
              "required": [
                "id",
                "externalId",
                "name",
                "description",
                "price",
                "type"
              ]
            }
          }
        },
        "required": [
          "id",
          "externalId",
          "name",
          "description",
          "status",
          "disposition",
          "department",
          "dealType",
          "amount",
          "closedAt",
          "dmsOpportunityType",
          "createdAt",
          "updatedAt",
          "lastActivityAt",
          "organizationId",
          "integrationConnectionId",
          "integrationPlatform",
          "integrationName",
          "primaryCustomer",
          "secondaryCustomer",
          "primaryVehicle",
          "lineItems"
        ],
        "description": "DMS opportunity linked to this recording",
        "example": {
          "id": "dms_opp_12345",
          "externalId": "RO-12345",
          "name": "Repair Order 12345",
          "description": "Brake service and inspection",
          "status": "Booked",
          "disposition": "OPEN",
          "department": "Service",
          "dealType": "SERVICE",
          "amount": 39999,
          "closedAt": null,
          "dmsOpportunityType": "REPAIR_ORDER",
          "createdAt": "2024-01-01T00:00:00.000Z",
          "updatedAt": "2024-01-15T08:30:00.000Z",
          "lastActivityAt": "2024-01-15T08:30:00.000Z",
          "organizationId": "12345",
          "integrationConnectionId": "int_conn_12345",
          "integrationPlatform": "AUTHENTICOM",
          "integrationName": "Tekion",
          "primaryCustomer": {
            "id": "dms_cust_12345",
            "name": "Jane Smith",
            "customerType": "Person",
            "businessType": null,
            "lastActivityAt": "2024-01-15T08:30:00.000Z",
            "createdAt": "2024-01-01T00:00:00.000Z",
            "updatedAt": "2024-01-15T08:30:00.000Z",
            "emailAddresses": ["jane@example.com"],
            "phoneNumbers": ["+1-555-123-4567"],
            "externalId": "cust_ext_12345",
            "addresses": [
              {
                "street": "123 Main St",
                "city": "Nashville",
                "state": "TN",
                "zip": "37201",
                "country": "USA",
                "addressType": "home"
              }
            ],
            "organizationId": "12345",
            "integrationConnectionId": "int_conn_12345"
          },
          "secondaryCustomer": null,
          "primaryVehicle": {
            "id": "veh_12345",
            "vin": "1HGCM82633A123456",
            "make": "Honda",
            "model": "Accord",
            "trim": "EX",
            "year": 2022,
            "stockNumber": "A1234",
            "mileage": 24500
          },
          "lineItems": [
            {
              "id": "line_12345",
              "externalId": "line_ext_12345",
              "name": "Balance Tires",
              "description": "Balnce tires",
              "price": 399.99,
              "type": "CS"
            }
          ]
        }
      }
    },
    "parameters": {},
    "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>"
      }
    }
  },
  "paths": {
    "/v1/core/recordings/{id}/viewed": {
      "put": {
        "summary": "Mark a recording as viewed",
        "description": "Marks the authenticated user as having viewed a recording they are allowed to access.",
        "parameters": [
          {
            "schema": {
              "type": "string",
              "minLength": 1,
              "description": "Opaque unique identifier for the recording. Must match a recording the authenticated user is allowed to access."
            },
            "required": true,
            "description": "Opaque unique identifier for the recording. Must match a recording the authenticated user is allowed to access.",
            "name": "id",
            "in": "path"
          }
        ],
        "responses": {
          "200": {
            "description": "Mark a recording as viewed",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "success": {
                          "type": "boolean",
                          "enum": [true]
                        }
                      },
                      "required": ["success"],
                      "description": "Standard success envelope for recording activity writes."
                    },
                    "cursor": {
                      "anyOf": [
                        {
                          "type": "string"
                        },
                        {
                          "type": "number"
                        },
                        {
                          "nullable": true
                        }
                      ]
                    },
                    "pageSize": {
                      "type": "number"
                    },
                    "limit": {
                      "type": "number"
                    },
                    "total": {
                      "type": "number",
                      "nullable": true
                    },
                    "hasNextPage": {
                      "type": "boolean"
                    }
                  },
                  "required": ["data"]
                }
              }
            }
          },
          "400": {
            "description": "Bad Request - Invalid parameters",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Error message"
                    }
                  },
                  "required": ["error"]
                }
              }
            }
          },
          "401": {
            "description": "Unauthorized - User not authenticated",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Authentication error message"
                    }
                  },
                  "required": ["error"]
                }
              }
            }
          },
          "403": {
            "description": "Forbidden - User does not have access",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Authorization error message"
                    }
                  },
                  "required": ["error"]
                }
              }
            }
          },
          "404": {
            "description": "Not Found - Resource not found",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "error": {
                      "type": "string",
                      "description": "Resource not found error message"
                    }
                  },
                  "required": ["error"]
                }
              }
            }
          },
          "422": {
            "description": "Unprocessable Content - The request failed validation checks",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "issues": {

# --- truncated at 32 KB (2507 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/siro/refs/heads/main/openapi/_original/siro-platform-api-openapi.json
Siro Platform API

Documentation

Specifications

Other Resources

OpenAPI Specification
