> ## Documentation Index > Fetch the complete documentation index at: https://developers.opereit.ai/llms.txt > Use this file to discover all available pages before exploring further. # Initiate document upload > Start uploading a supporting document (e.g. proof of damage, an invoice) for an existing claim. This doesn't upload the file itself — it registers the document and gives you back a URL to upload the file to. See [Uploading a document for an existing claim](/guides/claim-documents). ## OpenAPI ````yaml POST /v1/claims/{id}/documents openapi: 3.1.0 info: title: Opereit API description: >- Public API for Opereit. Create and track carrier claims, upload carrier contracts, run audits against incoming carrier invoices, and retrieve line items and findings. version: 1.0.0 servers: - url: https://api.opereit.ai description: Production security: - apiKey: [] paths: /v1/claims/{id}/documents: post: summary: Initiate a document upload description: >- Start uploading a supporting document (e.g. proof of damage, an invoice) for an existing claim. This doesn't upload the file itself — it registers the document and gives you back a URL to upload the file to. See [Uploading a document for an existing claim](/guides/claim-documents). operationId: initiateClaimDocumentUpload parameters: - $ref: '#/components/parameters/ClaimId' requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/InitiateDocumentUploadRequest' responses: '201': description: >- Document registered. Upload the file to `metadata.upload_url`, then confirm it. content: application/json: schema: $ref: '#/components/schemas/ClaimDocument' '400': $ref: '#/components/responses/ClaimDocumentInvalidBody' '401': $ref: '#/components/responses/ClaimUnauthorized' '404': $ref: '#/components/responses/ClaimNotFound' '500': $ref: '#/components/responses/ClaimInternalError' components: parameters: ClaimId: name: id in: path required: true description: ID of the claim. schema: type: string schemas: InitiateDocumentUploadRequest: type: object required: - content_type - file_name properties: content_type: type: string enum: - application/pdf - image/jpeg - image/png - image/webp description: MIME type of the file you're about to upload. file_name: type: string description: >- Original file name, including its extension. Truncated to 100 characters in the response if longer. ClaimDocument: type: object description: A claim document, as returned right after you initiate its upload. required: - id - claim_id - name - type - status - uploaded_by - created_at - organization_id - metadata properties: id: type: string description: >- Unique document ID. Hold onto this — you need it to confirm the upload. claim_id: type: string name: type: string description: >- The file name you sent, truncated to 100 characters if longer (the extension is preserved). type: type: string description: >- File extension, derived from `content_type` (e.g. `pdf`, `jpeg`, `png`, `webp`). status: $ref: '#/components/schemas/ClaimDocumentStatus' description: >- Always `PENDING_UPLOAD` on this response — it only becomes `CONFIRMED` once you upload the file and confirm it. uploaded_by: type: string description: Always `external` for documents created through this API. created_at: type: string format: date-time organization_id: type: string metadata: type: object required: - upload_url properties: upload_url: type: string description: >- URL to upload the file to. Use an HTTP `PUT` with a `Content-Type` header matching the `content_type` you sent above. See [Uploading a document for an existing claim](/guides/claim-documents). ClaimDocumentStatus: type: string enum: - PENDING_UPLOAD - CONFIRMED description: >- Where a document is in its upload lifecycle. - `PENDING_UPLOAD`: registered, waiting for the file to be uploaded and confirmed. - `CONFIRMED`: the file was uploaded and confirmed. See [Document statuses](/guides/claim-documents#document-statuses). ApiError: type: object description: Error envelope returned by every endpoint. required: - statusCode - statusReasonCode - error properties: statusCode: type: integer description: HTTP status code — same value as the response status. statusReasonCode: type: string enum: - INVALID_REQUEST_BODY - INVALID_QUERY_PARAMETERS - UNSUPPORTED_DOCUMENT_CONTENT_TYPE - CLAIM_NOT_FOUND - CLAIM_ALREADY_EXISTS - CONTRACT_NOT_FOUND - INVOICE_AUDIT_NOT_FOUND - INTERNAL_ERROR - AUTHENTICATION_REQUIRED - INVALID_CREDENTIALS_FORMAT - INVALID_CREDENTIALS_ENCODING - INVALID_CREDENTIALS description: Machine-readable error code. error: type: string description: Human-readable error message. details: type: object description: >- Present on `400` responses. `formErrors` holds errors not tied to a specific field; `fieldErrors` maps a top-level request field to the list of validation messages raised under it. properties: formErrors: type: array items: type: string fieldErrors: type: object additionalProperties: type: array items: type: string responses: ClaimDocumentInvalidBody: description: >- The request body failed validation. Either `content_type`/`file_name` are missing or malformed (`statusReasonCode` `INVALID_REQUEST_BODY`, with `details.fieldErrors`), or `content_type` is well-formed but isn't one of the accepted MIME types (`statusReasonCode` `UNSUPPORTED_DOCUMENT_CONTENT_TYPE`). content: application/json: schema: $ref: '#/components/schemas/ApiError' example: statusCode: 400 statusReasonCode: UNSUPPORTED_DOCUMENT_CONTENT_TYPE error: 'Unsupported content type: text/plain. Expected pdf, jpeg, or png.' ClaimUnauthorized: description: >- Authentication is missing or invalid. Also returned as `WWW-Authenticate: Basic realm="Opereit API"` on the response headers. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: statusCode: 401 statusReasonCode: AUTHENTICATION_REQUIRED error: Authentication required ClaimNotFound: description: The claim does not exist, or belongs to a different organization. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: statusCode: 404 statusReasonCode: CLAIM_NOT_FOUND error: Claim not found ClaimInternalError: description: Unexpected server error. content: application/json: schema: $ref: '#/components/schemas/ApiError' example: statusCode: 500 statusReasonCode: INTERNAL_ERROR error: Internal server error securitySchemes: apiKey: type: http scheme: basic description: >- HTTP Basic Auth using your API key. Send `Authorization: Basic base64(key_id:key_secret)`. ````