> ## 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.

# Batch Import Recordings

> Creates up to 50 recording imports from audio or video URLs you host, downloaded in the background. Each item takes the same fields as `POST /recording-imports` plus exactly one of `audio_url` or `video_url`. Poll `GET /recording-imports?ids=...` until every `status` is no longer `pending`.

The batch is all or nothing: if any item fails validation, nothing is created.



## OpenAPI

````yaml POST /recording-imports/batch
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/batch:
    post:
      summary: Batch import recordings
      description: >-
        Creates up to 50 recording imports from audio or video URLs you host,
        downloaded in the background. Each item takes the same fields as `POST
        /recording-imports` plus exactly one of `audio_url` or `video_url`. Poll
        `GET /recording-imports?ids=...` until every `status` is no longer
        `pending`.


        The batch is all or nothing: if any item fails validation, nothing is
        created.
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
              required:
                - recording_imports
              properties:
                recording_imports:
                  type: array
                  minItems: 1
                  maxItems: 50
                  items:
                    type: object
                    required:
                      - teammate_email
                      - recorded_at
                      - contacts
                    properties:
                      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.
                        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.
                      audio_url:
                        type: string
                        format: uri
                        description: >-
                          An https URL of the audio file to import. It is
                          downloaded in the background, so it must stay
                          reachable until the import settles. Provide exactly
                          one of `audio_url` or `video_url`.
                      video_url:
                        type: string
                        format: uri
                        description: >-
                          An https URL of the video file to import. It is
                          downloaded in the background, so it must stay
                          reachable until the import settles. The video is kept
                          for playback and its audio is transcribed. Provide
                          exactly one of `audio_url` or `video_url`.
            example:
              recording_imports:
                - ext_id: call-12345
                  audio_url: https://files.example.com/calls/12345.mp3
                  teammate_email: rep@example.com
                  recorded_at: '2026-10-02T19:30:00Z'
                  contacts:
                    - phone_number: '+14155550123'
                - ext_id: call-12346
                  video_url: https://files.example.com/calls/12346.mp4
                  teammate_email: rep@example.com
                  recorded_at: '2026-10-02T19:45:00Z'
                  contacts:
                    - email: customer@example.com
      responses:
        '202':
          description: Recording imports created, in request order
          content:
            application/json:
              schema:
                type: object
                properties:
                  data:
                    type: object
                    properties:
                      recording_imports:
                        type: array
                        items:
                          $ref: '#/components/schemas/RecordingImport'
              example:
                data:
                  recording_imports:
                    - 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
                    - id: 0c7d2e4f-6a8b-4c1d-9e3f-2b5a7c9d1e4f
                      ext_id: call-12346
                      status: pending
                      recording_id: null
                      error: null
                      created_at: '2026-10-02T20:00:00.000Z'
                      imported_at: null
        '400':
          description: Invalid or missing field on an item, or more than 50 items
          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.