> ## Documentation Index > Fetch the complete documentation index at: https://docs.callrounded.com/llms.txt > Use this file to discover all available pages before exploring further. # Start a new phone call > Start a new phone call with the specified parameters. The response includes headers about rate limiting. ## OpenAPI ````yaml /api-reference-v1/openapi.json post /v1/calls/phone openapi: 3.1.0 info: title: Rounded API description: Rounded API version: 1.0.0 servers: - url: https://api.callrounded.com security: - ApiKeyHeader: [] paths: /v1/calls/phone: post: tags: - calls summary: Start a new phone call description: >- Start a new phone call with the specified parameters. The response includes headers about rate limiting. operationId: start_phone_call_v1_calls_phone_post requestBody: content: application/json: schema: $ref: '#/components/schemas/PhoneCallCreateApiRequest' required: true responses: '201': description: Successfully started phone call headers: ratelimit-limit: description: The number of requests allowed in the current rate limit period schema: type: integer ratelimit-remaining: description: >- The number of requests remaining in the current rate limit period schema: type: integer x-ratelimit-limit-minute: description: >- The number of requests allowed in the current minute window, if rate limit is set to minutes. schema: type: integer x-ratelimit-remaining-minute: description: >- The number of requests remaining in the current minute window, if rate limit is set to minutes. schema: type: integer x-ratelimit-limit-hour: description: >- The number of requests allowed in the current hour window, if rate limit is set to hourly. schema: type: integer x-ratelimit-remaining-hour: description: >- The number of requests remaining in the current hour window, if rate limit is set to hourly. schema: type: integer x-ratelimit-limit-: description: >- The number of requests allowed in the current window, where is the number of seconds, if rate limit is set to seconds. schema: type: integer x-ratelimit-remaining-: description: >- The number of requests remaining in the current window, where is the number of seconds, if rate limit is set to seconds. schema: type: integer content: application/json: schema: $ref: '#/components/schemas/PhoneCallCreateApiResponse' type: object title: Response Start Phone Call V1 Calls Phone Post '400': description: Bad Request content: application/json: schema: $ref: '#/components/schemas/ApiResponseError' example: error: message: Bad request type: api_error status: 400 '401': description: Unauthorized content: application/json: schema: $ref: '#/components/schemas/ApiResponseError' examples: auth_error: summary: Error from the API Service value: message: Unauthorized type: auth_error status: 401 gateway_error: summary: Error from the API Gateway value: message: Unauthorized type: gateway_auth_error status: 401 '403': description: Forbidden content: application/json: schema: $ref: '#/components/schemas/ApiResponseError' example: error: message: Access forbidden type: api_error status: 403 '404': description: Not Found content: application/json: schema: $ref: '#/components/schemas/ApiResponseError' example: error: message: The request endpoint does not exist type: http_error status: 404 '422': description: Validation Error content: application/json: schema: $ref: '#/components/schemas/ApiResponseError' example: error: message: Invalid request body type: validation_error status: 422 details: - field: email message: Invalid email format '429': description: Rate Limit Exceeded content: application/json: schema: $ref: '#/components/schemas/ApiResponseError' example: error: message: API rate limit exceeded type: gateway_rate_limit_error status: 429 '500': description: Internal Server Error content: application/json: schema: $ref: '#/components/schemas/ApiResponseError' example: error: message: An unexpected error occurred type: generic_error status: 500 components: schemas: PhoneCallCreateApiRequest: properties: from_number: type: string minLength: 8 title: From Number description: >- Phone number emitting the call, in E.164 format. It must be a phone number from your Rounded organization. examples: - '+33912345678' to_number: type: string minLength: 8 title: To Number description: Phone number receiving the call, in E.164 format. examples: - '+33612345678' agent_id: type: string format: uuid title: Agent Id description: >- Id of the agent making the call. You can get the id from your agent's config page URL, e.g. https://app.callrounded.com/agents/411b82c8-462a-4e1b-89bc-10ab3ce1ed29. examples: - 411b82c8-462a-4e1b-89bc-10ab3ce1ed29 dynamic_variables_values: anyOf: - additionalProperties: anyOf: - type: string - type: integer - type: number - type: boolean - type: string format: date-time - type: object type: object - type: 'null' title: Dynamic Variables Values description: >- Values for the variables that should be initialized before call starts, provided as a JSON object. Values can be strings, numbers, booleans, or nested JSON objects. examples: - active: true age: 35 appointment_date: '2023-05-15T14:30:00Z' first_name: John last_name: Doe opening_hours: monday: - end: '17:00' start: '07:00' custom_headers: anyOf: - additionalProperties: type: string type: object - type: 'null' title: Custom Headers description: >- If SIP is used, the custom headers will be forwarded to the configured trunk provider when sending the `INVITE` request to start the call. If more control is needed, it's also possible to override default headers like `From`, `To`, `P-Asserted-Identity`, etc. examples: - From: >- Anonymous ;tag=3c90c3cc-0d44-4b50-8888-8dd25736052a X-Custom-Header: value type: object required: - from_number - to_number - agent_id title: PhoneCallCreateApiRequest PhoneCallCreateApiResponse: properties: message: type: string title: Message data: $ref: '#/components/schemas/PhoneCallCreateApiResponseData' error: anyOf: - $ref: '#/components/schemas/ApiResponseError' - type: 'null' status: type: integer title: Status default: 201 type: object required: - message - data title: PhoneCallCreateApiResponse example: data: call_id: 3c90c3cc-0d44-4b50-8888-8dd25736052a message: Phone call started successfully status: 201 ApiResponseError: properties: message: type: string title: Message type: type: string title: Type status: type: integer title: Status details: anyOf: - items: $ref: '#/components/schemas/ApiResponseErrorDetail' type: array - type: 'null' title: Details type: object required: - message - type - status title: ApiResponseError example: details: - field: email message: Invalid email format message: An error occurred while processing your request status: 400 type: generic_error PhoneCallCreateApiResponseData: properties: call_id: type: string title: Call Id description: Unique identifier of the initiated call. examples: - 411b82c8-462a-4e1b-89bc-10ab3ce1ed29 type: object required: - call_id title: PhoneCallCreateApiResponseData ApiResponseErrorDetail: properties: field: anyOf: - type: string - type: 'null' title: Field message: type: string title: Message type: object required: - message title: ApiResponseErrorDetail securitySchemes: ApiKeyHeader: type: apiKey in: header name: X-Api-Key description: >- The API Key created in [Rounded Studio](https://app.callrounded.com). - You can create it by going to the "API Keys" settings of your profile. - Need help? You can email us at [team@callrounded.com](mailto:team@callrounded.com) or join our [Discord community](https://discord.gg/en537j5z75). ````