> ## Documentation Index > Fetch the complete documentation index at: https://dev.alpharun.com/llms.txt > Use this file to discover all available pages before exploring further. # Upload Recording Asynchronously > Uploads an audio file and creates the recording in the background. Poll `GET /recording-imports/{RECORDING_IMPORT_ID}` until `status` is no longer `pending`. Takes the same fields as `POST /recordings/upload`, returns immediately and retries transient failures, so prefer it for new integrations. ## OpenAPI ````yaml POST /recording-imports openapi: 3.0.1 info: title: Alpharun API description: Alpharun REST API reference license: name: MIT version: 1.0.0 servers: - url: https://api.alpharun.com/api/v1 security: - bearerAuth: [] paths: /recording-imports: post: summary: Upload a recording asynchronously description: >- Uploads an audio file and creates the recording in the background. Poll `GET /recording-imports/{RECORDING_IMPORT_ID}` until `status` is no longer `pending`. Takes the same fields as `POST /recordings/upload`, returns immediately and retries transient failures, so prefer it for new integrations. requestBody: required: true content: multipart/form-data: schema: type: object required: - audio - teammate_email - recorded_at - contacts properties: audio: type: string format: binary playbook_id: type: string format: uuid description: >- The ID of the playbook to use for the assessment. If omitted, the playbook will be determined by the routing rules defined in https://app.alpharun.com/settings/playbooks (based on the teammate group the teammate belongs to). If no matching routing rules is found, the request will be rejected. teammate_email: type: string format: email recorded_at: type: string format: date-time description: >- The date and time when the recording was made. Accepts ISO 8601 format with optional timezone specification (e.g., '2024-01-15T14:30:00Z' or '2024-01-15T14:30:00-05:00'). We encourage you to specify the TZ if available. contacts: type: array minItems: 1 description: >- At least one of email, phone number and ext id must be not null on the contact. Contacts are unique per email, phone number, or ext_id. **No two contacts can have the same email, phone number, or ext_id**. items: $ref: '#/components/schemas/RecordingContactPayload' custom_fields: type: array description: >- Custom fields to set on the customer interaction created for this recording. Each `key` must match the `field_name` of a **Customer interaction** custom field defined in your Alpharun dashboard; entries whose keys don't match a definition are ignored. Like `contacts`, this must be sent as a JSON-encoded string in the multipart form. items: type: object required: - key - value properties: key: type: string description: >- The `field_name` of the customer interaction custom field to set. value: anyOf: - type: string - type: number - type: boolean nullable: true description: Value to set for the custom field. ext_id: type: string maxLength: 255 description: >- Your own reference for this upload, echoed back as `ext_id` on the recording import so you can match results to your records. Not used for deduplication. responses: '202': description: Recording import created content: application/json: schema: type: object properties: data: type: object properties: recording_import: $ref: '#/components/schemas/RecordingImport' example: data: recording_import: id: 9b2f6c1e-3d4a-4f7b-8c2e-1a5d7e9f0b3c ext_id: call-12345 status: pending recording_id: null error: null created_at: '2026-10-02T20:00:00.000Z' imported_at: null '400': description: Invalid or missing field content: application/json: schema: $ref: '#/components/schemas/Error' components: schemas: RecordingContactPayload: type: object anyOf: - required: - email properties: email: type: string format: email description: Email address of the contact first_name: type: string description: First name of the contact last_name: type: string description: Last name of the contact phone_number: anyOf: - type: string - type: number description: Phone number of the contact ext_id: type: string description: External ID of the contact custom_fields: type: array description: Custom fields associated with the contact items: type: object required: - key - value properties: key: type: string value: anyOf: - type: string - type: number - type: boolean nullable: true - required: - phone_number properties: email: type: string format: email description: Email address of the contact first_name: type: string description: First name of the contact last_name: type: string description: Last name of the contact phone_number: anyOf: - type: string - type: number description: Phone number of the contact ext_id: type: string description: External ID of the contact custom_fields: type: array description: Custom fields associated with the contact items: type: object required: - key - value properties: key: type: string value: anyOf: - type: string - type: number - type: boolean nullable: true - required: - ext_id properties: email: type: string format: email description: Email address of the contact first_name: type: string description: First name of the contact last_name: type: string description: Last name of the contact phone_number: anyOf: - type: string - type: number description: Phone number of the contact ext_id: type: string description: External ID of the contact custom_fields: type: array description: Custom fields associated with the contact items: type: object required: - key - value properties: key: type: string value: anyOf: - type: string - type: number - type: boolean nullable: true RecordingImport: type: object required: - id - ext_id - status - recording_id - error - created_at - imported_at properties: id: type: string format: uuid ext_id: type: string nullable: true description: The `ext_id` you passed when creating the import, or `null`. status: type: string enum: - pending - imported - failed - action_required - skipped description: >- - `pending`: waiting to be imported, or being imported. Transient failures (an unreachable URL, a storage error) are retried automatically. - `imported`: the recording was created and `recording_id` is set. - `action_required`: the import stopped on something only you can fix, such as `no_routing_for_teammate`, `teammate_deactivated`, `analyzed_minutes_limit_reached` or `media_url_rejected`. Fix the cause and create a new import. - `failed`: the import could not complete, for example after exhausting its retries (`attempts_exhausted`). Contact support if it persists. - `skipped`: there is nothing to import, for example the uploaded audio expired before it was imported (`file_not_found`). recording_id: type: string format: uuid nullable: true description: >- The created recording's id once `status` is `imported`, otherwise `null`. error: allOf: - $ref: '#/components/schemas/RecordingImportError' nullable: true description: >- Why the import is `failed`, `action_required` or `skipped`. `null` while `pending` and once `imported`. created_at: type: string format: date-time imported_at: type: string format: date-time nullable: true description: When the recording was created, or `null`. Error: required: - error - message type: object properties: error: type: integer format: int32 message: type: string RecordingImportError: type: object required: - code - message properties: code: type: string description: A stable machine-readable code, for example `teammate_deactivated`. message: type: string description: A human-readable explanation. securitySchemes: bearerAuth: type: http scheme: bearer ```` This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.