---
title: "File upload requests"
description: "Collect a file from a customer or partner through a secure, time-limited upload link."
canonical: "https://studio.inttegro.com/api/file-uploads"
format: inttegro-machine-docs/v1
language: "Python"
sdk_version: "v12.0.0"
reader_profile: optional
reader_manifest: "https://studio.inttegro.com/machine/python/readers/index.json"
reader_identification: "Optional: declare your client only if known and your current-session capabilities; use reader_manifest for supplemental recommendations."
preamble_estimated_tokens: 613
model_token_report: "https://studio.inttegro.com/machine/token-report.json"
preamble_questions: 5
preamble_source: "machine-only-decisions"
recommended_mcp_tools: ["upload_file"]
estimated_tokens: 10520
token_estimate_method: "utf8_bytes_divided_by_4"
---

## Machine preamble

**Summary:** Collect a file from a customer or partner through a secure, time-limited upload link. This Python representation uses the selected SDK's native names wherever Studio has a verified mapping.

### Five questions

#### Q1. Is File upload requests the right source for this task?

Use this reference for collect a file from a customer or partner through a secure, time-limited upload link. Keep the four decision rules below with its exact operations and fields; do not infer a broader workflow from endpoint order.

#### Q2. What does “Use this API for an external uploader, not for a trusted server upload” require?

**Use this API for an external uploader, not for a trusted server upload.**
Your application creates one time-limited request for one file and shares its
upload link without sharing an API credential. For direct server uploads, use
[Files](https://studio.inttegro.com/machine/python/api/files.md).

#### Q3. What does “Do not stop at successful request creation” require?

**Do not stop at successful request creation.** Read [`upload_request.active`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest)to determine whether the link can still accept a file and wait for a fulfilled
state with a resulting[`upload_request.file_id`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest).

#### Q4. What does “Use attempt details to decide whether the same uploader can continue” require?

**Use attempt details to decide whether the same uploader can continue.** A
failed attempt does not necessarily mean the request itself is terminal;
inspect the attempt error, remaining attempt allowance, request status, and
expiry together.

#### Q5. What does “Continue with the file resource” require?

**Continue with the file resource.** Once fulfilled, use [Lookup a
file](https://studio.inttegro.com/machine/python/api/files.md#lookup-a-file) to verify availability and obtain the delivery
details appropriate to its purpose.

### Recommended MCP assistance

Use these through an authenticated Inttegro MCP connection. This document remains the contract source.

- [`upload_file`](https://studio.inttegro.com/machine/python/inttegro-mcp/tools.md#upload_file) — action; exact user confirmation required. Uploads canonical base64 file content up to 5 MiB and returns safe file metadata without echoing bytes or unrestricted custom data.

## Document content

# File upload requests

Upload requests let a customer, supplier, or other partner add a file to your Inttegro account through a secure, time-limited link. Your application creates the request and shares the link; the uploader sends the file directly to Inttegro without gaining access to your API credentials.

Use an upload request when someone outside your application needs to provide a product image, downloadable product, catalog import, video, or support document. Each request collects one file and produces a normal Inttegro file when the upload succeeds.

## Follow the upload-request handoff through to a usable file

The four decision rules are in the machine preamble above.

## The upload request object

An upload request records what file you expect, who should provide it, and whether it has arrived. New requests start as [`inttegro.upload_request.Status.PENDING`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Status.PENDING); an accepted file changes the request to [`inttegro.upload_request.Status.FULFILLED`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Status.FULFILLED) and sets [`upload_request.file_id`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest). A request can instead become [`inttegro.upload_request.Status.FAILED`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Status.FAILED), [`inttegro.upload_request.Status.EXPIRED`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Status.EXPIRED), or [`inttegro.upload_request.Status.CANCELED`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Status.CANCELED).

Use [`upload_request.active`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) to decide whether the link can still accept a file. When a request is fulfilled, retrieve the resulting file through [Lookup a file](https://studio.inttegro.com/machine/python/api/files.md#lookup-a-file).

### Properties

- [`active`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `boolean`

  Whether the request can still accept an upload.

- [`attempt`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest)

  Most recent upload attempt. Lookup and upload responses include it after the uploader has tried to send a file.

  - [`attempt.attempted_at`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `timestamp`

    When the upload attempt started.

  - [`attempt.content_type`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Declared content type when present.

  - [`attempt.declared_size`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `integer`

    Declared file size in bytes when present.

  - [`attempt.error`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `object`

    Why the file was not accepted and whether the uploader may try again.

  - [`attempt.failed_at`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `timestamp`

    When a failed attempt completed.

  - [`attempt.file_id`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Resulting file ID after a successful attempt.

  - [`attempt.filename`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Submitted filename when present.

  - [`attempt.id`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Unique attempt identifier.

  - [`attempt.ordinal`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `integer`

    One-based attempt number for the request.

  - [`attempt.review`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `object`

    Your approval or rejection of the uploaded file, when reviewed.

  - [`attempt.status`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Attempt status such as `'succeeded'` or `'failed'`.

  - [`attempt.succeeded_at`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `timestamp`

    When a successful attempt completed.

  - [`attempt.upload_request_id`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Upload-request ID that owns the attempt.

- [`attempts`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest)

  Upload-attempt limit and current counts.

  - [`attempts.attempt_count`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `integer`

    Total upload attempts recorded for this request.

  - [`attempts.failed_attempt_count`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `integer`

    How many upload attempts have failed validation or fulfillment.

  - [`attempts.last_attempted_at`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `timestamp`

    When the most recent upload attempt happened.

  - [`attempts.max_attempts`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `integer`

    Maximum number of allowed failed attempts.

- [`canceled_at`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `timestamp`

  When the request was canceled. Returned only after cancellation.

- [`canceled_by`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest)

  Person or system that canceled the request. Present only after cancellation.

  - [`canceled_by.email`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Actor email when available.

  - [`canceled_by.id`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Actor ID when available.

  - [`canceled_by.name`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Actor display name when available.

  - [`canceled_by.service`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Service name when the request was canceled by an automated workflow.

  - [`canceled_by.type`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Kind of actor that canceled the request.

- [`constraints`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest)

  Optional file requirements that are stricter than the selected purpose.

  - [`constraints.content_types`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `array`

    Optional narrowed allow-list of MIME types.

  - [`constraints.exact_size`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `integer`

    Optional exact file size in bytes.

  - [`constraints.extensions`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `array`

    Optional narrowed allow-list of filename extensions.

  - [`constraints.filename`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Optional exact filename requirement.

  - [`constraints.max_size`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `integer`

    Optional maximum file size in bytes.

  - [`constraints.min_size`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `integer`

    Optional minimum file size in bytes.

- [`created_at`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `timestamp`

  When the upload request was created.

- [`custom_data`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `object`

  Optional string key-value custom data copied to the resulting file.

- [`display`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest)

  Human-facing copy shown to the uploader.

  - [`display.description`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Optional longer explanation of what should be uploaded.

  - [`display.help_text`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Optional supporting guidance for the uploader.

  - [`display.title`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Short title for the upload prompt.

- [`expired_at`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `timestamp`

  When the request was marked expired. Returned only after expiry is recorded.

- [`expires_at`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `timestamp`

  When the public upload URL stops accepting uploads.

- [`file_id`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

  Resulting file ID after a successful upload. Omitted until fulfillment succeeds.

- [`fulfilled_at`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `timestamp`

  When a valid upload produced the file. Returned only after fulfillment succeeds.

- [`id`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

  Unique upload-request identifier. IDs begin with `uplreq_`.

- [`latest_error`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest)

  Most recent validation or fulfillment error.

  - [`latest_error.at`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `timestamp`

    When the error was recorded.

  - [`latest_error.code`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Stable error code for the failure.

  - [`latest_error.message`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Human-readable error message.

  - [`latest_error.param`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Request field associated with the error when available.

  - [`latest_error.retryable`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `boolean`

    Whether the uploader can try again.

- [`metadata`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `object`

  Additional read-only details supplied by Inttegro. Use [`upload_request.custom_data`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) for your own data.

- [`purpose`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

  File purpose the upload must satisfy:`'product_download'` accepts PDF, ZIP, text, and CSV files up to 100 MiB.
  `'product_image'` accepts JPEG, PNG, and GIF images up to 10 MiB.
  `'product_video'` accepts MP4, WebM, and QuickTime video up to 250 MiB.
  `'products_import'` accepts a CSV catalog import up to 32 MiB and 10,000 product rows.
  `'support_document'` accepts PDF, JPEG, PNG, and text files up to 25 MiB.

- [`recipient`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest)

  Person expected to provide the file, when you want that context on the request.

  - [`recipient.email`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Recipient email when available.

  - [`recipient.id`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Recipient ID when available.

  - [`recipient.name`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Recipient display name when available.

  - [`recipient.type`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Recipient type such as `'customer'`, `'email'`, or `'user'`.

- [`requester`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest)

  Person or system that created the request. Inttegro identifies the caller from the API key unless you supply additional details.

  - [`requester.email`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Actor email when available.

  - [`requester.id`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Actor ID when available.

  - [`requester.name`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Actor display name when available.

  - [`requester.service`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Service name when the request came from an automated workflow.

  - [`requester.type`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Kind of actor that created the request.

- [`resource`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest)

  Order, product, case, or other resource that needs the file.

  - [`resource.id`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Resource ID.

  - [`resource.name`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Resource name when available.

  - [`resource.type`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Resource type.

- [`status`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

  Upload-request lifecycle status: [`inttegro.upload_request.Status.PENDING`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Status.PENDING), [`inttegro.upload_request.Status.UPLOADING`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Status.UPLOADING), [`inttegro.upload_request.Status.FULFILLED`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Status.FULFILLED), [`inttegro.upload_request.Status.EXPIRED`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Status.EXPIRED), [`inttegro.upload_request.Status.CANCELED`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Status.CANCELED), or [`inttegro.upload_request.Status.FAILED`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Status.FAILED).

- [`subject`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest)

  Person or resource that the requested file is about.

  - [`subject.email`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Subject email when available.

  - [`subject.id`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Subject ID when available.

  - [`subject.name`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Subject display name when available.

  - [`subject.type`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

    Subject type such as `'customer'`, `'case'`, or `'user'`.

- [`updated_at`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `timestamp`

  When the upload request was last updated.

- [`upload_url`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `string`

  Secure upload link returned only when you create the request. Share it only with the intended uploader; lookup, page, and cancel responses do not return it again.

- [`uploading_at`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) — `timestamp`

  When an upload attempt moved into active fulfillment. Returned only while or after an upload attempt has started.

When an attempt has been reviewed, [`upload_request.attempt.review`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) records the decision, the review time, an optional message for the uploader, and any structured reasons.

For `'products_import'`, every nonblank data row must contain at least these columns in order: `name`, `type`, `price_currency`, `price_value`, `reference`, `description`, `about`, `category`, `tax_code`, `unit_dimension`, `price_label`, `publish`, and `attributes`. An optional first header row may use those names in the same order. The file must contain between 1 and 10,000 data rows.

## Create an upload request

Create an upload request when another person or system should send the file directly to Inttegro. The response includes a secure [`upload_request.upload_url`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) that you can place behind a button, send in a message, or hand to another trusted system.

The [`purpose`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#CreateRequest.purpose) sets the kinds and maximum size of file Inttegro accepts. Use [`constraints`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#CreateRequest.constraints) only when this particular request should be stricter—for example, to accept only PDF support documents under 10 MiB.

### Request body

- [`attempts`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#CreateRequest.attempts) — `upload_request.AttemptsRequest`

  Optional limit on failed upload attempts.

  - [`attempts.max_attempts`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#AttemptsRequest.max_attempts) — `int`

    Maximum number of allowed failed attempts. Defaults to `3`.

- [`constraints`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#CreateRequest.constraints) — `upload_request.ConstraintsInput`

  Optional requirements for this upload. These can narrow, but not widen, the selected purpose.

  - [`constraints.content_types`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ConstraintsInput.content_types) — `list[str]`

    Optional narrowed allow-list of MIME types.

  - [`constraints.exact_size`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ConstraintsInput.exact_size) — `int`

    Optional exact file size in bytes.

  - [`constraints.extensions`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ConstraintsInput.extensions) — `list[str]`

    Optional narrowed allow-list of filename extensions.

  - [`constraints.filename`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ConstraintsInput.filename) — `str`

    Optional exact filename requirement.

  - [`constraints.max_size`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ConstraintsInput.max_size) — `int`

    Optional maximum file size in bytes.

  - [`constraints.min_size`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ConstraintsInput.min_size) — `int`

    Optional minimum file size in bytes.

- [`custom_data`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#CreateRequest.custom_data) — `CustomData`

  Optional string key-value data for your own reconciliation. Inttegro copies it to the resulting file. The object can be at most 25 KiB and each key at most 256 characters.

- [`display`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#CreateRequest.display) — `upload_request.DisplayInput`

  Optional uploader-facing copy.

  - [`display.description`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#DisplayInput.description) — `str`

    Optional longer description of what to upload.

  - [`display.help_text`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#DisplayInput.help_text) — `str`

    Optional supporting guidance for the uploader.

  - [`display.title`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#DisplayInput.title) — `str`

    Short title for the upload prompt.

- [`expires_at`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#CreateRequest.expires_at) — `datetime`

  Optional RFC 3339 expiry. The default is 24 hours from creation.

- [`purpose`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#CreateRequest.purpose) — `str` — required

  File purpose the upload must satisfy.

- [`recipient`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#CreateRequest.recipient) — `file.PartyInput`

  Optional uploader identity details.

  - [`recipient.email`](https://python.inttegro.dev/v12.0.0/inttegro/file.html#PartyInput.email) — `str`

    Recipient email when available.

  - [`recipient.id`](https://python.inttegro.dev/v12.0.0/inttegro/file.html#PartyInput.id) — `str`

    Recipient ID when available.

  - [`recipient.name`](https://python.inttegro.dev/v12.0.0/inttegro/file.html#PartyInput.name) — `str`

    Recipient display name when available.

  - [`recipient.type`](https://python.inttegro.dev/v12.0.0/inttegro/file.html#PartyInput.type) — `str`

    Recipient type.

- [`requester`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#CreateRequest.requester) — `file.ActorInput`

  Optional details about the person or system creating the request. Normally, Inttegro identifies the caller from the API key.

  - [`requester.email`](https://python.inttegro.dev/v12.0.0/inttegro/file.html#ActorInput.email) — `str`

    Actor email when available.

  - [`requester.id`](https://python.inttegro.dev/v12.0.0/inttegro/file.html#ActorInput.id) — `str`

    Actor ID when available.

  - [`requester.name`](https://python.inttegro.dev/v12.0.0/inttegro/file.html#ActorInput.name) — `str`

    Actor display name when available.

  - [`requester.type`](https://python.inttegro.dev/v12.0.0/inttegro/file.html#ActorInput.type) — `str`

    Actor type.

- [`resource`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#CreateRequest.resource) — `file.ResourceInput`

  Optional Inttegro resource or workflow that needs the file.

  - [`resource.id`](https://python.inttegro.dev/v12.0.0/inttegro/file.html#ResourceInput.id) — `str`

    Resource ID.

  - [`resource.name`](https://python.inttegro.dev/v12.0.0/inttegro/file.html#ResourceInput.name) — `str`

    Resource name when available.

  - [`resource.type`](https://python.inttegro.dev/v12.0.0/inttegro/file.html#ResourceInput.type) — `str`

    Resource type.

- [`subject`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#CreateRequest.subject) — `file.PartyInput`

  Optional person or Inttegro object the requested file is about.

  - [`subject.email`](https://python.inttegro.dev/v12.0.0/inttegro/file.html#PartyInput.email) — `str`

    Subject email when available.

  - [`subject.id`](https://python.inttegro.dev/v12.0.0/inttegro/file.html#PartyInput.id) — `str`

    Subject ID when available.

  - [`subject.name`](https://python.inttegro.dev/v12.0.0/inttegro/file.html#PartyInput.name) — `str`

    Subject display name when available.

  - [`subject.type`](https://python.inttegro.dev/v12.0.0/inttegro/file.html#PartyInput.type) — `str`

    Subject type.

### Upload limits

- The link expires after 24 hours unless you provide a future [`expires_at`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#CreateRequest.expires_at).
- The uploader gets three failed attempts unless you set [`attempts.max_attempts`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#AttemptsRequest.max_attempts).
- File sizes are measured in bytes. Any minimum, maximum, or exact size must fit within the selected purpose's limit.
- Content types, extensions, and an exact filename can make a request more restrictive, but they cannot permit a file that the selected purpose rejects.

### Response

Returns the new upload request and its [`upload_request.upload_url`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest). Save the URL when you create the request because Inttegro does not return it again through lookup, page, or cancel.

Treat the URL like a temporary secret: anyone who has the complete URL can upload against the request. Use a stable idempotency key when retrying this call so that a network failure does not create multiple live links for the same upload.

**Request — POST /upload\_requests/create**

```python
import os
from datetime import datetime

import inttegro
from inttegro import InttegroClient

client = InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])

result = client.upload_requests.create(inttegro.upload_request.CreateRequest(
  purpose="support_document",
  constraints=inttegro.upload_request.ConstraintsInput(
    content_types=[
      "application/pdf",
    ],
    max_size=10485760,
  ),
  display=inttegro.upload_request.DisplayInput(
    title="Upload dispute evidence",
    help_text="Attach a PDF under 10 MB.",
  ),
  recipient=inttegro.file.PartyInput(
    type="customer",
    email="ama@example.com",
  ),
  resource=inttegro.file.ResourceInput(
    type="dispute",
    id="disp_123",
  ),
  custom_data=inttegro.CustomData({
    "case_id": "CASE-1001",
  }),
  expires_at=datetime.fromisoformat("2030-07-06T12:30:00Z".replace("Z", "+00:00")),
),
    idempotency_key="support-doc-upload-001")
```

```json
{
  "upload_request": {
    "id": "uplreq_1gK9pQ4vL8mN2sT5wX7yZ0",
    "purpose": "support_document",
    "status": "pending",
    "active": true,
    "upload_url": "<UPLOAD_URL>",
    "constraints": {
      "content_types": ["application/pdf"],
      "max_size": 10485760
    },
    "display": {
      "help_text": "Attach a PDF under 10 MB.",
      "title": "Upload dispute evidence"
    },
    "subject": {},
    "recipient": { "type": "customer", "email": "ama@example.com" },
    "resource": { "type": "dispute", "id": "disp_123" },
    "requester": { "type": "api_key" },
    "attempts": {
      "max_attempts": 3,
      "attempt_count": 0,
      "failed_attempt_count": 0
    },
    "custom_data": { "case_id": "CASE-1001" },
    "created_at": "2026-06-05T12:30:00Z",
    "updated_at": "2026-06-05T12:30:00Z",
    "expires_at": "2030-07-06T12:30:00Z"
  }
}
```

## Fulfill an upload request

Send the file as `multipart/form-data` to the complete upload link returned when the request was created. This call is made by the uploader and does not use your application's API key; the secure values needed to accept the upload are already part of the URL.

Use the URL exactly as returned. Do not extract, log, or reconstruct its query parameters.

### Included in the upload URL

- `id` — `string` — required — wire-only

  Identifies the upload request. It is already present in the generated upload
  link.

- `token` — `string` — required — wire-only

  Authorizes the upload. It is already present in the generated upload link
  and must remain private.

### Request body

- `file` — `file` — required — wire-only

  File selected by the uploader.

### Response

Returns the fulfilled upload request and a file receipt containing the resulting [`file.id`](https://python.inttegro.dev/v12.0.0/inttegro/shared.html#UploadFulfillment). Your authenticated backend can pass that ID to [Lookup a file](https://studio.inttegro.com/machine/python/api/files.md#lookup-a-file) when it needs the complete file object.

If Inttegro rejects the file, the response includes an error and the failed attempt. Check `error.retryable` before offering another try. A retryable failure leaves the request pending while attempts remain; otherwise, create a new upload request.

Expired, canceled, fulfilled, and exhausted requests no longer accept uploads.

**Request — POST /upload\_requests/upload**

```python
import os

from inttegro import InttegroClient

client = InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])

result = client.upload_requests.fulfill(
    upload_url="<UPLOAD_URL>",
    file="./evidence.pdf",
)
```

## Lookup an upload request

Retrieve an upload request when you need its current status or the result of the uploader's latest attempt. After fulfillment, [`upload_request.file_id`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) identifies the file Inttegro created.

### Request body

- `id` — `string` — required

  Upload-request ID to retrieve.

### Response

Returns the upload request and its latest attempt, when one exists. The response does not include [`upload_request.upload_url`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest); retain that URL only for as long as the intended uploader needs it.

**Request — POST /upload\_requests/lookup**

```python
import os

from inttegro import InttegroClient

client = InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])

result = client.upload_requests.lookup("uplreq_1gK9pQ4vL8mN2sT5wX7yZ0")
```

## Review an upload attempt

Approve or reject the latest upload attempt after your application has checked the file itself—for example, after confirming that a document is readable or contains the requested evidence. Approval keeps a successful request fulfilled. Rejection reopens it for a replacement when another attempt is available.

### Request body

- [`attempt_id`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ReviewAttemptByIDRequest.attempt_id) — `str`

  Attempt ID to review. Supply exactly one of [`attempt_id`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ReviewAttemptByIDRequest.attempt_id)
  or
  [`attempt_ordinal`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ReviewAttemptByIDRequest.attempt_ordinal).

- [`attempt_ordinal`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ReviewAttemptByIDRequest.attempt_ordinal) — `int`

  One-based attempt number to review. Supply exactly one of
  [`attempt_id`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ReviewAttemptByIDRequest.attempt_id) or
  [`attempt_ordinal`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ReviewAttemptByIDRequest.attempt_ordinal).

- [`decision`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ReviewAttemptByIDRequest.decision) — `Literal['approved', 'rejected', UploadReviewDecision.APPROVED, UploadReviewDecision.REJECTED]` — required

  Review decision: [`inttegro.upload_request.ReviewDecision.APPROVED`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ReviewDecision.APPROVED)
  or [`inttegro.upload_request.ReviewDecision.REJECTED`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ReviewDecision.REJECTED).

- [`id`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ReviewAttemptByIDRequest.id) — `str` — required

  Upload-request ID that owns the attempt.

- [`public_message`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ReviewAttemptByIDRequest.public_message) — `str`

  Optional explanation suitable for showing to the uploader.

- [`reasons`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ReviewAttemptByIDRequest.reasons) — `list[upload_request.ReviewReasonInput]`

  Optional structured reasons for the decision.

  - [`reasons.code`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ReviewReasonInput.code) — `str`

    Required stable reason code.

  - [`reasons.message`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ReviewReasonInput.message) — `str`

    Required customer-safe explanation.

  - [`reasons.param`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ReviewReasonInput.param) — `str`

    Optional field associated with the reason.

Only the latest attempt can be reviewed. You can approve only a successful attempt, and you cannot review a canceled or expired request. Use [`public_message`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ReviewAttemptByIDRequest.public_message) and [`reasons`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#ReviewAttemptByIDRequest.reasons) for explanations that are safe to show to the uploader.

### Response

Returns the updated upload request with the reviewed attempt. Use an idempotency key when submitting a review so a retry cannot record the decision twice.

**Request — POST /upload\_requests/review**

```python
import os

import inttegro
from inttegro import InttegroClient

client = InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])

result = client.upload_requests.review(inttegro.upload_request.ReviewAttemptByOrdinalRequest(
  id="uplreq_1gK9pQ4vL8mN2sT5wX7yZ0",
  attempt_ordinal=1,
  decision=inttegro.upload_request.ReviewDecision.REJECTED,
  reasons=[
    inttegro.upload_request.ReviewReasonInput(
      code="document_unreadable",
      message="The document is too blurry to read.",
    ),
  ],
  public_message="Please upload a clearer copy.",
),
    idempotency_key="review-upload-attempt-001")
```

## Page upload requests

List upload requests when you need to find outstanding uploads, recent fulfillments, or requests associated with a particular order, product, case, or other resource.

### Request body

- [`page_number`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#PageRequest.page_number) — `int`

  Page number to retrieve. Defaults to `1`.

- [`page_size`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#PageRequest.page_size) — `int`

  Requested number of upload requests per page. Defaults to `25` and is capped at `256`.

- [`purpose`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#PageRequest.purpose) — `str`

  Optional purpose filter.

- [`resource`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#PageRequest.resource) — `file.ResourceInput`

  Optional resource filter.

  - [`resource.id`](https://python.inttegro.dev/v12.0.0/inttegro/file.html#ResourceInput.id) — `str`

    Resource ID.

  - [`resource.name`](https://python.inttegro.dev/v12.0.0/inttegro/file.html#ResourceInput.name) — `str`

    Resource name when available.

  - [`resource.type`](https://python.inttegro.dev/v12.0.0/inttegro/file.html#ResourceInput.type) — `str`

    Resource type.

- [`status`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#PageRequest.status) — `Literal['pending', 'uploading', 'fulfilled', 'expired', 'canceled', 'failed', UploadRequestStatus.PENDING, UploadRequestStatus.UPLOADING, UploadRequestStatus.FULFILLED, UploadRequestStatus.EXPIRED, UploadRequestStatus.CANCELED, UploadRequestStatus.FAILED]`

  Optional status filter: [`inttegro.upload_request.Status.PENDING`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Status.PENDING), [`inttegro.upload_request.Status.UPLOADING`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Status.UPLOADING), [`inttegro.upload_request.Status.FULFILLED`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Status.FULFILLED), [`inttegro.upload_request.Status.EXPIRED`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Status.EXPIRED), [`inttegro.upload_request.Status.CANCELED`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Status.CANCELED), or [`inttegro.upload_request.Status.FAILED`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Status.FAILED).

### Response

Returns a page with [`page.upload_requests`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Page), [`page.number`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Page), and [`page.size`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Page). Page items omit the latest attempt; use [Lookup an upload request](#lookup-an-upload-request) when you need an attempt or its validation error. An empty page has an empty [`page.upload_requests`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Page) collection and [`page.size`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Page) set to `0`.

**Request — POST /upload\_requests/page**

```python
import os

import inttegro
from inttegro import InttegroClient

client = InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])

result = client.upload_requests.page(inttegro.upload_request.PageRequest(
  purpose="support_document",
  status="pending",
  page_number=1,
  page_size=25,
))
```

## Cancel an upload request

Cancel a request when you no longer need the file or when you have issued a replacement link. Its upload URL stops working immediately.

### Request body

- [`canceled_by`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#CancelRequest.canceled_by) — `file.ActorInput`

  Optional actor canceling the request.

  - [`canceled_by.email`](https://python.inttegro.dev/v12.0.0/inttegro/file.html#ActorInput.email) — `str`

    Actor email when available.

  - [`canceled_by.id`](https://python.inttegro.dev/v12.0.0/inttegro/file.html#ActorInput.id) — `str`

    Actor ID when available.

  - [`canceled_by.name`](https://python.inttegro.dev/v12.0.0/inttegro/file.html#ActorInput.name) — `str`

    Actor display name when available.

  - [`canceled_by.type`](https://python.inttegro.dev/v12.0.0/inttegro/file.html#ActorInput.type) — `str`

    Actor type.

- [`id`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#CancelRequest.id) — `str` — required

  Upload-request ID to cancel.

### Response

Returns the request with [`upload_request.status`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#UploadRequest) set to [`inttegro.upload_request.Status.CANCELED`](https://python.inttegro.dev/v12.0.0/inttegro/upload_request.html#Status.CANCELED). Use a stable idempotency key when retrying the cancellation.

**Request — POST /upload\_requests/cancel**

```python
import os

import inttegro
from inttegro import InttegroClient

client = InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])

result = client.upload_requests.cancel(inttegro.upload_request.CancelRequest(
  id="uplreq_1gK9pQ4vL8mN2sT5wX7yZ0",
  canceled_by=inttegro.file.ActorInput(
    type="user",
    id="usr_support_123",
  ),
),
    idempotency_key="cancel-upload-request-001")
```