> ## Documentation Index > Fetch the complete documentation index at: https://platform-docs.sarj.ai/llms.txt > Use this file to discover all available pages before exploring further. # Place an outbound Sarj.ai voice call > Place an outbound Sarj.ai voice call: dials the given phone_number and runs the specified scenario (with optional template variables and language). Returns a call_id that can be polled via getCall. Use this whenever the user asks to call, dial, ring, or phone someone through Sarj.ai — do not attempt to start calls by writing to the database or invoking telephony providers directly. ## OpenAPI ````yaml /api-reference/openapi.json post /calls openapi: 3.1.0 info: title: Sarj.ai Developer API description: > Public API for programmatic access to the **Sarj.ai voice platform**. > [!TIP] > **New here?** Start with the [Getting Started guide](https://platform-docs.sarj.ai/getting-started) > to go from API key to first call in under 5 minutes. > > **Building with AI agents?** See the [MCP Server guide](https://platform-docs.sarj.ai/mcp-server) > to connect Claude Code, Cursor, or any MCP-compatible agent. --- ## Authentication All authenticated endpoints require a **Bearer token** in the `Authorization` header: ``` Authorization: Bearer ``` Generate an API key from [platform.sarj.ai/api-keys](https://platform.sarj.ai/api-keys). > [!WARNING] > If you receive a `401 Unauthorized` response, your key may be invalid, > expired, or missing. Check the `error.type` field in the response body. --- ## Response Format **Success** ```json { "data": { ... }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" } } ``` **Error** ```json { "error": { "type": "unauthorized", "message": "Authentication required." }, "meta": { "request_id": "550e8400-e29b-41d4-a716-446655440000" } } ``` Always branch on `error.type` — the `message` field is for humans only. --- ## Support Include `meta.request_id` in all support tickets for faster resolution. license: name: Apache 2.0 identifier: Apache-2.0 version: 1.0.0 servers: - url: https://platform-api.sarj.ai/api/v1 description: Production security: - ApiKeyAuth: [] tags: - name: System description: Service health and status. - name: Calls description: Create outbound voice calls and retrieve call details and transcripts. externalDocs: description: Sarj.ai Documentation url: https://platform-docs.sarj.ai paths: /calls: post: tags: - Calls summary: Place an outbound Sarj.ai voice call description: >- Place an outbound Sarj.ai voice call: dials the given phone_number and runs the specified scenario (with optional template variables and language). Returns a call_id that can be polled via getCall. Use this whenever the user asks to call, dial, ring, or phone someone through Sarj.ai — do not attempt to start calls by writing to the database or invoking telephony providers directly. operationId: createCall requestBody: content: application/json: schema: $ref: '#/components/schemas/CreateCallRequest' required: true responses: '202': description: Successful Response content: application/json: schema: $ref: '#/components/schemas/ApiResponse_PublicCall_' example: data: id: call_8f9b2c1e-4a5d-4f6e-8b1a-2c3d4e5f6a7b status: queued phone_number: '+966512345678' scenario_id: scn_abc123 created_at: '2026-04-12T10:30:00Z' meta: request_id: 550e8400-e29b-41d4-a716-446655440000 '400': description: Outbound call failed. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: outbound_call_failed message: Outbound call could not be initiated. reason: telephony_provider_unavailable meta: request_id: 550e8400-e29b-41d4-a716-446655440000 '401': description: Missing or invalid API key. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: unauthorized message: Authentication required. meta: {} '403': description: Forbidden — phone number blocked or scenario access denied. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' examples: phone_number_blocked: summary: Phone number is blocked value: error: type: phone_number_blocked message: Phone number +966512345678 is blocked. phone_number: '+966512345678' meta: request_id: 550e8400-e29b-41d4-a716-446655440000 scenario_forbidden: summary: Scenario belongs to a different organization value: error: type: scenario_forbidden message: Access denied to scenario scn_abc123. scenario_id: scn_abc123 meta: request_id: 550e8400-e29b-41d4-a716-446655440000 '404': description: Scenario not found. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: scenario_not_found message: Scenario scn_abc123 was not found. scenario_id: scn_abc123 meta: request_id: 550e8400-e29b-41d4-a716-446655440000 '422': description: Validation error. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: validation_error message: Request validation failed. field_violations: - field: body.phone_number message: value is not a valid phone number meta: request_id: 550e8400-e29b-41d4-a716-446655440000 '429': description: Call limit exceeded. content: application/json: schema: $ref: '#/components/schemas/ErrorResponse' example: error: type: call_limit_exceeded message: Call limit of 10 reached for phone number +966512345678. phone_number: '+966512345678' call_limit: 10 meta: request_id: 550e8400-e29b-41d4-a716-446655440000 x-codeSamples: - label: Python (SDK) lang: Python source: |- import os from sarj_platform_sdk import SDK sdk = SDK(api_key_auth=os.environ["SARJ_API_KEY"]) res = sdk.calls.create_call( phone_number="+966512345678", scenario_id="scn_abc123", language="ar", ) print(f"Call queued: {res.data.id}") - label: curl lang: bash source: |- curl -X POST https://platform-api.sarj.ai/api/v1/calls \ -H "Authorization: Bearer $SARJ_API_KEY" \ -H "Content-Type: application/json" \ -d '{ "phone_number": "+966512345678", "scenario_id": "scn_abc123", "language": "ar" }' - label: Python (requests) lang: Python source: |- import os import requests response = requests.post( "https://platform-api.sarj.ai/api/v1/calls", headers={ "Authorization": f"Bearer {os.environ['SARJ_API_KEY']}", }, json={ "phone_number": "+966512345678", "scenario_id": "scn_abc123", "language": "ar", }, ) response.raise_for_status() call = response.json()["data"] print(f"Call queued: {call['id']}") - label: TypeScript lang: TypeScript source: >- const response = await fetch("https://platform-api.sarj.ai/api/v1/calls", { method: "POST", headers: { "Authorization": `Bearer ${process.env.SARJ_API_KEY}`, "Content-Type": "application/json", }, body: JSON.stringify({ phone_number: "+966512345678", scenario_id: "scn_abc123", language: "ar", }), }); if (!response.ok) throw new Error(`HTTP ${response.status}`); const { data: call } = await response.json(); console.log(`Call queued: ${call.id}`); components: schemas: CreateCallRequest: properties: phone_number: type: string title: Phone Number description: Phone number to call in E.164 format. examples: - '+966512345678' scenario_id: type: string minLength: 1 title: Scenario Id description: ID of the scenario to use for this call. variables: additionalProperties: true type: object title: Variables description: Template variables to inject into the scenario. language: $ref: '#/components/schemas/Language' description: Language for the call. Defaults to Arabic (ar) if not specified. default: ar additionalProperties: false type: object required: - phone_number - scenario_id title: CreateCallRequest ApiResponse_PublicCall_: properties: data: $ref: '#/components/schemas/PublicCall' meta: $ref: '#/components/schemas/ResponseMeta' additionalProperties: false type: object required: - data title: ApiResponse[PublicCall] ErrorResponse: properties: error: oneOf: - $ref: '#/components/schemas/ValidationErrorPayload' - $ref: '#/components/schemas/UnauthorizedPayload' - $ref: '#/components/schemas/NotFoundPayload' - $ref: '#/components/schemas/InternalErrorPayload' - $ref: '#/components/schemas/PhoneNumberBlockedPayload' - $ref: '#/components/schemas/CallLimitExceededPayload' - $ref: '#/components/schemas/OutboundCallFailedPayload' - $ref: '#/components/schemas/ScenarioNotFoundPayload' - $ref: '#/components/schemas/ScenarioForbiddenPayload' - $ref: '#/components/schemas/NoOrganizationPayload' - $ref: '#/components/schemas/CallNotFoundPayload' - $ref: '#/components/schemas/OauthInvalidRedirectUriPayload' title: Error discriminator: propertyName: type mapping: call_limit_exceeded: $ref: '#/components/schemas/CallLimitExceededPayload' call_not_found: $ref: '#/components/schemas/CallNotFoundPayload' internal_error: $ref: '#/components/schemas/InternalErrorPayload' no_organization: $ref: '#/components/schemas/NoOrganizationPayload' not_found: $ref: '#/components/schemas/NotFoundPayload' oauth_invalid_redirect_uri: $ref: '#/components/schemas/OauthInvalidRedirectUriPayload' outbound_call_failed: $ref: '#/components/schemas/OutboundCallFailedPayload' phone_number_blocked: $ref: '#/components/schemas/PhoneNumberBlockedPayload' scenario_forbidden: $ref: '#/components/schemas/ScenarioForbiddenPayload' scenario_not_found: $ref: '#/components/schemas/ScenarioNotFoundPayload' unauthorized: $ref: '#/components/schemas/UnauthorizedPayload' validation_error: $ref: '#/components/schemas/ValidationErrorPayload' meta: $ref: '#/components/schemas/ResponseMeta' additionalProperties: false type: object required: - error title: ErrorResponse description: |- Standard envelope for all public API error responses. `error` is a discriminated union — branch on `error.type` to access variant-specific fields. Clients MUST treat unknown `type` values as retryable internal errors to preserve forward compatibility. Language: type: string enum: - en - ar - ur title: Language description: Language codes in ISO 639-1 PublicCall: properties: id: type: string title: Id description: Unique call identifier. examples: - call_550e8400-e29b-41d4-a716-446655440000 status: $ref: '#/components/schemas/CallStatus' description: Current call status. examples: - queued phone_number: type: string title: Phone Number description: Destination phone number. scenario_id: type: string title: Scenario Id description: Scenario used for this call. created_at: type: string format: date-time title: Created At description: Timestamp when the call was created. additionalProperties: false type: object required: - id - status - phone_number - scenario_id - created_at title: PublicCall ResponseMeta: properties: request_id: anyOf: - type: string - type: 'null' title: Request Id description: >- Unique identifier for this request, mirrored in the `X-Request-ID` response header. Supply your own via the `X-Request-ID` request header (max 128 chars, ASCII printable); otherwise the server generates a UUID v4. Include in support tickets. examples: - 550e8400-e29b-41d4-a716-446655440000 additionalProperties: false type: object title: ResponseMeta description: Contains request-level metadata included with every public API response. ValidationErrorPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: validation_error title: Type default: validation_error field_violations: items: $ref: '#/components/schemas/FieldViolation' type: array title: Field Violations description: Per-field validation details. additionalProperties: false type: object required: - message - field_violations title: ValidationErrorPayload UnauthorizedPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: unauthorized title: Type default: unauthorized additionalProperties: false type: object required: - message title: UnauthorizedPayload NotFoundPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: not_found title: Type default: not_found additionalProperties: false type: object required: - message title: NotFoundPayload InternalErrorPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: internal_error title: Type default: internal_error additionalProperties: false type: object required: - message title: InternalErrorPayload PhoneNumberBlockedPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: phone_number_blocked title: Type default: phone_number_blocked phone_number: type: string title: Phone Number description: The phone number that is blocked. additionalProperties: false type: object required: - message - phone_number title: PhoneNumberBlockedPayload CallLimitExceededPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: call_limit_exceeded title: Type default: call_limit_exceeded phone_number: type: string title: Phone Number description: The phone number that hit the limit. call_limit: type: integer title: Call Limit description: The per-number call limit that was reached. additionalProperties: false type: object required: - message - phone_number - call_limit title: CallLimitExceededPayload OutboundCallFailedPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: outbound_call_failed title: Type default: outbound_call_failed reason: type: string title: Reason description: Stable-ish reason string from the call service. additionalProperties: false type: object required: - message - reason title: OutboundCallFailedPayload ScenarioNotFoundPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: scenario_not_found title: Type default: scenario_not_found scenario_id: type: string title: Scenario Id additionalProperties: false type: object required: - message - scenario_id title: ScenarioNotFoundPayload ScenarioForbiddenPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: scenario_forbidden title: Type default: scenario_forbidden scenario_id: type: string title: Scenario Id additionalProperties: false type: object required: - message - scenario_id title: ScenarioForbiddenPayload NoOrganizationPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: no_organization title: Type default: no_organization additionalProperties: false type: object required: - message title: NoOrganizationPayload CallNotFoundPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: call_not_found title: Type default: call_not_found call_id: type: string title: Call Id additionalProperties: false type: object required: - message - call_id title: CallNotFoundPayload OauthInvalidRedirectUriPayload: properties: message: type: string title: Message description: >- Human-readable summary. Do not parse programmatically — branch on `type`. type: type: string const: oauth_invalid_redirect_uri title: Type default: oauth_invalid_redirect_uri redirect_uri: type: string title: Redirect Uri additionalProperties: false type: object required: - message - redirect_uri title: OauthInvalidRedirectUriPayload CallStatus: type: string enum: - queued - in_progress - completed - timeout - user_rejected - max_duration_reached - failed - ringing - voicemail - dialing - cancelled - expired title: CallStatus FieldViolation: properties: field: type: string title: Field description: >- Dot-separated path to the invalid field (e.g. `phone_number.country_code`). examples: - phone_number.country_code message: type: string title: Message description: Human-readable description of the violation. examples: - Must start with + additionalProperties: false type: object required: - field - message title: FieldViolation securitySchemes: ApiKeyAuth: type: http scheme: bearer description: >- API key from your Sarj.ai dashboard. Pass as: Authorization: Bearer ````