> ## Documentation Index
> Fetch the complete documentation index at: https://docs.xosum.am/llms.txt
> Use this file to discover all available pages before exploring further.

# Create Transcription

Creates a transcription job and returns a `docId` plus a pre-signed `uploadUrl`. Upload your `.mp3` to that URL via `PUT` (the URL is valid for 1 hour) to begin processing.

The `type` field controls how the resulting transcript is shaped:

* **`single_voice`** — plain transcript with no speaker labels. Use for monologues, dictations, voicemails, or any single-speaker audio.
* **`phone_call`** — diarized transcript with inline `Խոսնակ 1:` / `Խոսնակ 2:` speaker labels, pinned to exactly two speakers. Use for two-party conversations (support, sales, interview calls).

Once processing finishes, the result is available two ways — pick whichever fits your environment:

* **Webhook (push)** — Xosum POSTs the transcript to a URL you host. See [Receive Transcription](/api-reference/webhooks/transcription).
* **Polling (pull)** — call [`GET /api/getTranscription`](/api-reference/endpoint/get-transcription) with the `docId` until `status` is `transcribed`. Recommended when you can't expose a publicly reachable webhook receiver.


## OpenAPI

````yaml POST /api/createTranscription
openapi: 3.0.3
info:
  title: Xosum.am API
  description: >
    The Xosum.am API enables business customers to upload audio for
    transcription and receive results via webhook. All transcription results are
    also accessible via the web interface at
    [https://app.xosum.am](https://app.xosum.am).

    API access is exclusive to Business plan users. Authentication is handled
    via Bearer API keys.
  version: 1.0.0
servers:
  - url: https://app.xosum.am
    description: Production API server
security:
  - BearerAuth: []
paths:
  /api/createTranscription:
    post:
      tags:
        - Transcription
      summary: Create a new transcription job
      operationId: createTranscription
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateTranscriptionRequest'
      responses:
        '200':
          description: Successfully created transcription job and received an upload URL.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/CreateTranscriptionResponse'
        '400':
          description: Invalid request payload.
        '401':
          description: Unauthorized – missing or invalid API key.
        '403':
          description: >-
            Forbidden – The provided `checklistId` is invalid or does not belong
            to the authenticated user.
        '500':
          description: Server error.
      security:
        - BearerAuth: []
components:
  schemas:
    CreateTranscriptionRequest:
      type: object
      required:
        - type
      properties:
        type:
          type: string
          enum:
            - single_voice
            - phone_call
          description: >
            The kind of audio being transcribed. This value also controls
            diarization behavior in the resulting transcript: `single_voice`
            returns a plain transcript with no speaker labels — use this for
            monologues, dictations, voicemails, single-speaker recordings.
            `phone_call` returns a diarized transcript with inline speaker
            labels (`Խոսնակ 1:` / `Խոսնակ 2:`) and is pinned to exactly two
            speakers — use this for two-party conversations such as support or
            sales calls.
        metadata:
          type: object
          description: >-
            Optional metadata to attach to the transcription (e.g., user IDs,
            external info).
          example:
            phonenumber: '+37400000000'
            agent: King Ruzi
        checklistId:
          type: string
          description: >
            Optional. The ID of a QA Checklist to run an automated analysis on
            the transcript. You can find the Checklist ID in the "QA
            Ստուգացուցակներ" (QA Checklists) section of the Xosum.am web app.
            The results of the analysis will be available in the "History" page
            of the web app after the transcription is complete.
          example: a1B2c3D4e5F6g7H8i9J0
    CreateTranscriptionResponse:
      type: object
      properties:
        docId:
          type: string
          description: Unique ID for the created transcription job.
        uploadUrl:
          type: string
          format: uri
          description: >-
            A pre-signed URL for uploading the `.mp3` audio file using a PUT
            request. This URL is valid for 1 hour.
  securitySchemes:
    BearerAuth:
      type: http
      scheme: bearer
      bearerFormat: API Key

````