> ## Documentation Index > Fetch the complete documentation index at: https://docs.helloannie.com/llms.txt > Use this file to discover all available pages before exploring further. # Queue an outbound call > Accept a call request for later processing. Initiated means call initiation was confirmed; use conversationId for the conversation outcome. Acceptance does not guarantee initiation before expiry. Requests expire after one hour. Repeated identical submissions with the same idempotencyKey return the existing request; conflicting reuse returns 409. Status is retained for 30 days after processing. ## OpenAPI ````yaml /openapi/openapi.yaml post /call-requests openapi: 3.0.3 info: title: Annie API description: > ### Overview The Annie API is a (mostly) RESTful API. Typically, both POST bodies and responses are JSON-encoded. Note: The documenation is Work In Progress and is subject to change. ### Base URL The base URL for the Annie API is https://api.helloannie.com/. Examples in this document may abbreviate this to `/`. ### Versioning Routes are prefixed with a version number i.e. `v1`. The version will change when there is a non-backwards compatible or other significant change to the api. ### Authentication The Annie API supports two authentication methods API Keys and OAuth Access Tokens: #### API Keys API Keys are long-lived tokens that can be generated from the Developer Portal on your organization page. API keys are prefixed with `annie-sk-v2-` and can be used directly in the `Authorization` header. ``` curl -H "Authorization: Bearer annie-sk-xxxxx" https://api.helloannie.com/... ``` #### OAuth Tokens OAuth tokens are short-lived access tokens generated using the OAuth 2.0 Client Credentials flow (Machine-to-Machine). OAuth clients provide scoped permissions and are ideal for server-to-server integrations. **Creating an OAuth Client** OAuth clients can be created in the Developer Portal on your organization page. When creating a client, you'll receive: - `client_id`: Your OAuth client identifier - `client_secret`: Your OAuth client secret (store this securely) **Generating an OAuth Token** To generate an OAuth access token, make a POST request to the Annie OAuth token endpoint: **Endpoint:** `https://annie-external-api.us.auth0.com/oauth/token` **Example Request:** ```bash curl -X POST https://annie-external-api.us.auth0.com/oauth/token \ -H "Content-Type: application/json" \ -d '{ "grant_type": "client_credentials", "client_id": "your-client-id", "client_secret": "your-client-secret", "audience": "https://api.helloannie.com" }' ``` The `access_token` from the response should be used in the `Authorization` header when making requests to the Annie API: ``` curl -H "Authorization: Bearer eyJhbGciOiJSUzI..." https://api.helloannie.com/v1/... ``` ### API Response Structure The Annie API returns status codes consistent with standard HTTP conventions. Success and Error responses follow the below structure: ``` { "success": boolean "data": {} "message": string // optional } ``` ### Rate Limiting The Annie API enforces rate limits to ensure stability and fair usage. The default rate limit is **60 requests per minute** per organization. This limit is applied per endpoint pattern (e.g. `GET /v1/bots/:id`). When the rate limit is exceeded, the API responds with HTTP `429 Too Many Requests`. Response headers include: - `X-RateLimit-Limit`: The maximum number of requests allowed in the current window. - `X-RateLimit-Remaining`: The number of requests remaining in the current window. - `X-RateLimit-Reset`: The time at which the current rate limit window resets (in UTC epoch seconds). If you exceed the limit, the response will contain a `Retry-After` header indicating how many seconds to wait before retrying. ### Pagination The Annie API does not currently support pagination. All results are returned at once. version: v1 servers: - url: https://api.helloannie.com/v1 security: [] paths: /call-requests: post: tags: - Calls summary: Queue an outbound call description: >- Accept a call request for later processing. Initiated means call initiation was confirmed; use conversationId for the conversation outcome. Acceptance does not guarantee initiation before expiry. Requests expire after one hour. Repeated identical submissions with the same idempotencyKey return the existing request; conflicting reuse returns 409. Status is retained for 30 days after processing. operationId: postV1CallRequests requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CallRequestBody' application/x-www-form-urlencoded: schema: $ref: '#/components/schemas/CallRequestBody' multipart/form-data: schema: $ref: '#/components/schemas/CallRequestBody' responses: '202': description: Response for status 202 content: application/json: schema: $ref: '#/components/schemas/CallRequestResponse' '400': description: >- Standard error response that includes a message describing what went wrong content: application/json: schema: additionalProperties: false description: >- Standard error response that includes a message describing what went wrong type: object required: - success - data - message properties: success: enum: - false type: boolean data: additionalProperties: false type: object properties: {} message: type: string '403': description: >- Standard error response that includes a message describing what went wrong content: application/json: schema: additionalProperties: false description: >- Standard error response that includes a message describing what went wrong type: object required: - success - data - message properties: success: enum: - false type: boolean data: additionalProperties: false type: object properties: {} message: type: string '404': description: >- Standard error response that includes a message describing what went wrong content: application/json: schema: additionalProperties: false description: >- Standard error response that includes a message describing what went wrong type: object required: - success - data - message properties: success: enum: - false type: boolean data: additionalProperties: false type: object properties: {} message: type: string '409': description: >- Standard error response that includes a message describing what went wrong content: application/json: schema: additionalProperties: false description: >- Standard error response that includes a message describing what went wrong type: object required: - success - data - message properties: success: enum: - false type: boolean data: additionalProperties: false type: object properties: {} message: type: string '429': description: >- Standard error response that includes a message describing what went wrong content: application/json: schema: additionalProperties: false description: >- Standard error response that includes a message describing what went wrong type: object required: - success - data - message properties: success: enum: - false type: boolean data: additionalProperties: false type: object properties: {} message: type: string '503': description: >- Standard error response that includes a message describing what went wrong content: application/json: schema: additionalProperties: false description: >- Standard error response that includes a message describing what went wrong type: object required: - success - data - message properties: success: enum: - false type: boolean data: additionalProperties: false type: object properties: {} message: type: string components: schemas: CallRequestBody: additionalProperties: false type: object required: - fromNumber - toNumber - idempotencyKey properties: fromNumber: description: >- The Annie phone number to call from (must be configured in the system) example: '+15551234567' type: string toNumber: description: The phone number to call (must be in the allowed allowlist) example: '+15559876543' type: string patientInfo: additionalProperties: false description: Patient information for the call example: firstName: Sarah lastName: Johnson dateOfBirth: '1988-03-22T00:00:00.000Z' patientId: PAT-10432 type: object properties: firstName: description: Patient's first name maxLength: 100 example: Sarah type: string lastName: description: Patient's last name maxLength: 100 example: Johnson type: string dateOfBirth: description: Patient's date of birth (YYYY-MM-DD format) pattern: ^\d{4}-\d{2}-\d{2}$ maxLength: 10 example: '1988-03-22T00:00:00.000Z' type: string patientId: description: Patient's external ID from the practice management system maxLength: 255 example: PAT-10432 type: string appointmentInfo: additionalProperties: false description: Appointment information for context during the call example: startTime: '2025-03-10T15:00:00-06:00' endTime: '2025-03-10T15:30:00-06:00' appointmentTypeId: apt-type-cleaning appointmentDescription: 6-month routine cleaning and exam appointmentId: '81260683' type: object properties: startTime: description: >- Appointment start time in ISO 8601 format with timezone offset (e.g., 2025-03-10T15:00:00-06:00) pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?[+-]\d{2}:\d{2}$ example: '2025-03-10T15:00:00-06:00' type: string endTime: description: >- Appointment end time in ISO 8601 format with timezone offset (e.g., 2025-03-10T15:30:00-06:00) pattern: ^\d{4}-\d{2}-\d{2}T\d{2}:\d{2}:\d{2}(\.\d{1,3})?[+-]\d{2}:\d{2}$ example: '2025-03-10T15:30:00-06:00' type: string appointmentTypeId: description: ID of the appointment type maxLength: 255 example: apt-type-cleaning type: string appointmentDescription: description: Description of the appointment maxLength: 255 example: 6-month routine cleaning and exam type: string appointmentId: description: >- Appointment ID from the practice management system (numeric IDs recommended for appointment confirmation support) maxLength: 255 example: '81260683' type: string context: description: >- Context about the call being initiated (e.g., appointment confirmation details) maxLength: 500 example: >- Confirming upcoming cleaning appointment scheduled for March 10th at 3:00 PM type: string voicemailMessage: description: >- If present, Annie will leave this voicemail message when voicemail is detected maxLength: 500 example: Hi, this is Annie from Bright Smile Dental. Please call us back. type: string idempotencyKey: minLength: 1 maxLength: 128 pattern: ^[!-~]+$ description: >- Unique per intended call. Reuse with identical field values on retries; JSON property order is ignored, but string formatting, including phone numbers, must match. Retained for 30 days after processing. type: string CallRequestResponse: additionalProperties: false type: object required: - success - data properties: success: enum: - true type: boolean data: $ref: '#/components/schemas/CallRequestStatus' CallRequestStatus: additionalProperties: false type: object required: - callRequestId - status - createdAt - expiresAt - finishedAt - conversationId - error properties: callRequestId: format: uuid type: string status: type: string enum: - queued - processing - initiated - failed createdAt: type: string format: date-time expiresAt: type: string format: date-time finishedAt: format: date-time type: string nullable: true conversationId: format: uuid type: string nullable: true error: anyOf: - $ref: '#/components/schemas/CallRequestError' - type: object nullable: true enum: - null CallRequestError: additionalProperties: false type: object required: - category - code - message properties: category: type: string enum: - request - compliance - internal code: type: string enum: - target_unavailable - call_restricted - internal_error - call_start_unconfirmed - queue_expired message: type: string ````