---
title: "Register document upload metadata"
method: POST
path: "/v1/telephony/compliance-cases/{id}/uploads"
tags: ["Telephony"]
---

# Register document upload metadata

`POST /v1/telephony/compliance-cases/{id}/uploads`

## Request

- Base URL: `https://api.pyai.com`
- URL: `https://api.pyai.com/v1/telephony/compliance-cases/{id}/uploads`
- Auth: one of:
  - HTTP bearer
  - API key in header `x-api-key`

Finalizes a previously granted upload. The immutable object generation, ownership path, signed metadata, byte length, SHA-256, and actual file signature are verified before a bounded malware scan runs. Extraction remains blocked unless the terminal scan result is clean.

## Path parameters

- `id` string, required

## Request body

- NumberComplianceUploadCreate
  - `document_request_id` string, required
  - `object_ref` string, required: Opaque object-storage reference. Never a document body or public URL.
  - `file_name` string, required
  - `generation` string: Optional immutable object generation returned by storage.
  - `mime_type` string, required
  - `size_bytes` integer, required
  - `sha256` string, required: Lowercase SHA-256 content hash.

## Response `201`

Upload metadata registered

- NumberComplianceCase
  - `id` string, required
  - `object` 'telephony.compliance_case', required
  - `project_id` string, required
  - `kind` 'new_number' | 'port_in', required
  - `country` 'US' | 'CA' | 'IN' | 'GB' | 'AU', required
  - `number_type` string
  - `capabilities` string[]
  - `use_case` string
  - `network_status` string
  - `state` 'collecting_evidence' | 'extracting' | 'needs_review' | 'ready_for_submission' | 'submitted' | 'cancelled', required
  - `continuation_reason` string, nullable
  - `terminal_reason` 'network_review_submitted' | 'cancelled_by_customer' | 'null', nullable
  - `rules_snapshot` object, required: Immutable rules, source identifiers, thresholds, retry caps, parallelism, wall-clock, cost, and retention configuration frozen when the case started.
    - `available` boolean
    - `registry_version` string
    - `source_ids` string[]
    - `frozen_at` integer
    - `config` object
  - `document_requests` object[], required
    - `id` string
    - `document_type` string
    - `label` string
    - `required` boolean
    - `accepted_mime_types` string[]
    - `max_bytes` integer
  - `attestation_requests` object[]
    - `id` string
    - `text` string
    - `required` boolean
  - `uploads` object[], required
    - `id` string
    - `document_request_id` string
    - `object_ref` string: Opaque object reference.
    - `generation` string, nullable
    - `file_name` string
    - `mime_type` string
    - `size_bytes` integer
    - `sha256` string
    - `malware_status` 'pending' | 'clean' | 'infected' | 'scan_failed'
    - `uploaded_at` integer
    - `retention_delete_at` integer
  - `extractions` object[], required: Terminal processing attempts. Extracted personal values are masked in API views.
    - `id` string
    - `upload_id` string
    - `processing_profile` 'standard'
    - `status` 'succeeded' | 'failed' | 'cancelled'
    - `failure_reason` string, nullable
    - `attempts` integer
    - `fields` object[]
      - `field` string
      - `value` string: Extracted value; personal values are masked.
      - `confidence` number
      - `provenance` object
      - `pii_class` string
      - `redacted` boolean
    - `cost_micros` integer
    - `model_version` string, nullable
    - `latency_ms` integer
    - `started_at` integer
    - `completed_at` integer
  - `corrections` object[]: Correction audit metadata. Corrected PII values are intentionally omitted from API views.
  - `matches` object[]
  - `attestations` object[]
  - `timeline` object[], required
  - `created_at` integer
  - `updated_at` integer
  - `retention_delete_at` integer
  - `version` integer, required

## Other responses

- `400`: Invalid request (bad field, unsupported value)
- `409`: Concurrent case update.

---

[API](https://skmtc.dev/pyai/apis/pyai-api.md) · [All operations](https://skmtc.dev/pyai/apis/pyai-api/llms.txt) · [OpenAPI document](https://skmtc.dev/pyai/apis/pyai-api/revisions/271a1539185b?raw)