# Asynchronous jobs

<!-- WARNING: THIS FILE WAS AUTOGENERATED! DO NOT EDIT! -->

Use an asynchronous job to submit a recording URL and retrieve the note later by polling the job status.

## Submit a job

**`POST /aiservices/clinical_notes/job`**

Send a JSON request containing one downloadable HTTPS or S3 audio URI in `file`. Authenticate with your [Zoom AI Services credentials](/docs/ai-services/auth/). The examples on this page send a token in the `Authorization: Bearer` header. The recording must stay available at the URI until the job finishes.

| Field          | Type   | Required | Description                                                                                                                                               |
| -------------- | ------ | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `file`         | string | Yes      | Downloadable HTTPS or S3 URI to one recording.                                                                                                            |
| `template`     | string | No       | `SOAP`, `GENERAL_MEDICINE`, or `GENERAL_BEHAVIORAL_HEALTH`. Defaults to `GENERAL_MEDICINE` when omitted or empty. An unknown template returns HTTP `400`. |
| `reference_id` | string | No       | Optional client-supplied reference.                                                                                                                       |

The job endpoint does not accept file uploads, `file_url`, or `zoom_file_id`. Upload a recording through [synchronous generation](/docs/ai-services/clinical-notes/generate/) instead.

```shell
curl -X POST "https://api.zoom.us/v2/aiservices/clinical_notes/job" \
  -H "Authorization: Bearer $TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "file": "https://example.com/consultation.wav",
    "template": "SOAP"
  }'
```

### Submission response

A successful submission returns HTTP `200`. Save `job_id` to retrieve the job's status.

```json
{
    "job_id": "3b344f22-0048-400a-be71-13009c1e96ba",
    "state": "QUEUED",
    "submitted_at": "2026-10-13T11:25:02.173590695Z"
}
```

| Field          | Type   | Description                                                                    |
| -------------- | ------ | ------------------------------------------------------------------------------ |
| `job_id`       | string | Identifier used to retrieve job status.                                        |
| `state`        | string | Current job state. `QUEUED` indicates that the job is waiting to be processed. |
| `submitted_at` | string | Submission timestamp.                                                          |

## Retrieve job status

**`GET /aiservices/clinical_notes/job/{job_id}`**

```shell
curl "https://api.zoom.us/v2/aiservices/clinical_notes/job/$JOB_ID" \
  -H "Authorization: Bearer $TOKEN"
```

The status endpoint returns HTTP `200` for a known job. Inspect `state` to determine its progress rather than treating the HTTP status as successful note generation.

```json
{
    "job_id": "3b344f22-0048-400a-be71-13009c1e96ba",
    "state": "QUEUED",
    "submitted_at": "2026-10-13T11:25:02.173590Z"
}
```

Use the UUID returned in `job_id` when retrieving status. Handle non-success HTTP responses separately from the job's `state`.

| State        | Description                                                                                           | Final |
| ------------ | ----------------------------------------------------------------------------------------------------- | ----- |
| `QUEUED`     | The job is waiting to be processed.                                                                   | No    |
| `PROCESSING` | The job is being processed.                                                                           | No    |
| `SUCCEEDED`  | Transcription and note generation completed. The response includes `transcript` and `clinical_notes`. | Yes   |
| `FAILED`     | Transcription or note generation failed.                                                              | Yes   |

### Failed jobs

A job can return HTTP `200` while its `state` is `FAILED`. Detect failure using `state`. A failed job includes an `error` object only when failure details are available. Other states never include `error`.

```json
{
    "job_id": "3b344f22-0048-400a-be71-13009c1e96ba",
    "state": "FAILED",
    "submitted_at": "2026-10-13T11:25:02.173590Z",
    "completed_at": "2026-10-13T11:26:11.813827Z"
}
```

## Submission errors

| HTTP status | Reason                     | Condition                     |
| ----------- | -------------------------- | ----------------------------- |
| `400`       | `VALIDATION_MISSING_FIELD` | The recording URI is missing. |
| `400`       | `INVALID_INPUT`            | The template name is unknown. |

A request that uses multipart instead of JSON returns HTTP `400` during request decoding. A decoding reason such as `CODEC` is separate from the Clinical Notes application reasons above.

Missing or invalid authentication returns HTTP `401`. See [Get credentials](/docs/ai-services/auth/) for authentication requirements.