--- 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: "Go" sdk_version: "v11.0.1" reader_profile: optional reader_manifest: "https://studio.inttegro.com/machine/go/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: 616 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: 11452 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 Go 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/go/api/files.md). #### Q3. What does “Do not stop at successful request creation” require? **Do not stop at successful request creation.** Read [`UploadRequest.Active`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest)to determine whether the link can still accept a file and wait for a fulfilled state with a resulting[`UploadRequest.FileID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#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/go/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/go/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 [`uploadrequest.StatusPending`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#StatusPending); an accepted file changes the request to [`uploadrequest.StatusFulfilled`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#StatusFulfilled) and sets [`UploadRequest.FileID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest). A request can instead become [`uploadrequest.StatusFailed`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#StatusFailed), [`uploadrequest.StatusExpired`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#StatusExpired), or [`uploadrequest.StatusCanceled`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#StatusCanceled). Use [`UploadRequest.Active`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#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/go/api/files.md#lookup-a-file). ### Properties - [`Active`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `boolean` Whether the request can still accept an upload. - [`Attempt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) Most recent upload attempt. Lookup and upload responses include it after the uploader has tried to send a file. - [`Attempt.AttemptedAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `timestamp` When the upload attempt started. - [`Attempt.ContentType`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Declared content type when present. - [`Attempt.DeclaredSize`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `integer` Declared file size in bytes when present. - [`Attempt.Error`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `object` Why the file was not accepted and whether the uploader may try again. - [`Attempt.FailedAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `timestamp` When a failed attempt completed. - [`Attempt.FileID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Resulting file ID after a successful attempt. - [`Attempt.Filename`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Submitted filename when present. - [`Attempt.ID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Unique attempt identifier. - [`Attempt.Ordinal`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `integer` One-based attempt number for the request. - [`Attempt.Review`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `object` Your approval or rejection of the uploaded file, when reviewed. - [`Attempt.Status`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Attempt status such as `"succeeded"` or `"failed"`. - [`Attempt.SucceededAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `timestamp` When a successful attempt completed. - [`Attempt.UploadRequestID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Upload-request ID that owns the attempt. - [`Attempts`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) Upload-attempt limit and current counts. - [`Attempts.AttemptCount`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `integer` Total upload attempts recorded for this request. - [`Attempts.FailedAttemptCount`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `integer` How many upload attempts have failed validation or fulfillment. - [`Attempts.LastAttemptedAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `timestamp` When the most recent upload attempt happened. - [`Attempts.MaxAttempts`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `integer` Maximum number of allowed failed attempts. - [`CanceledAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `timestamp` When the request was canceled. Returned only after cancellation. - [`CanceledBy`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) Person or system that canceled the request. Present only after cancellation. - [`CanceledBy.Email`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Actor email when available. - [`CanceledBy.ID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Actor ID when available. - [`CanceledBy.Name`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Actor display name when available. - [`CanceledBy.Service`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Service name when the request was canceled by an automated workflow. - [`CanceledBy.Type`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Kind of actor that canceled the request. - [`Constraints`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) Optional file requirements that are stricter than the selected purpose. - [`Constraints.ContentTypes`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `array` Optional narrowed allow-list of MIME types. - [`Constraints.ExactSize`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `integer` Optional exact file size in bytes. - [`Constraints.Extensions`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `array` Optional narrowed allow-list of filename extensions. - [`Constraints.Filename`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Optional exact filename requirement. - [`Constraints.MaxSize`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `integer` Optional maximum file size in bytes. - [`Constraints.MinSize`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `integer` Optional minimum file size in bytes. - [`CreatedAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `timestamp` When the upload request was created. - [`CustomData`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `object` Optional string key-value custom data copied to the resulting file. - [`Display`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) Human-facing copy shown to the uploader. - [`Display.Description`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Optional longer explanation of what should be uploaded. - [`Display.HelpText`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Optional supporting guidance for the uploader. - [`Display.Title`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Short title for the upload prompt. - [`ExpiredAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `timestamp` When the request was marked expired. Returned only after expiry is recorded. - [`ExpiresAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `timestamp` When the public upload URL stops accepting uploads. - [`FileID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Resulting file ID after a successful upload. Omitted until fulfillment succeeds. - [`FulfilledAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `timestamp` When a valid upload produced the file. Returned only after fulfillment succeeds. - [`ID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Unique upload-request identifier. IDs begin with `uplreq_`. - [`LatestError`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) Most recent validation or fulfillment error. - [`LatestError.At`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `timestamp` When the error was recorded. - [`LatestError.Code`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Stable error code for the failure. - [`LatestError.Message`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Human-readable error message. - [`LatestError.Param`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Request field associated with the error when available. - [`LatestError.Retryable`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `boolean` Whether the uploader can try again. - [`Metadata`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `object` Additional read-only details supplied by Inttegro. Use [`UploadRequest.CustomData`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) for your own data. - [`Purpose`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#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://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) Person expected to provide the file, when you want that context on the request. - [`Recipient.Email`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Recipient email when available. - [`Recipient.ID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Recipient ID when available. - [`Recipient.Name`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Recipient display name when available. - [`Recipient.Type`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Recipient type such as `"customer"`, `"email"`, or `"user"`. - [`Requester`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) Person or system that created the request. Inttegro identifies the caller from the API key unless you supply additional details. - [`Requester.Email`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Actor email when available. - [`Requester.ID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Actor ID when available. - [`Requester.Name`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Actor display name when available. - [`Requester.Service`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Service name when the request came from an automated workflow. - [`Requester.Type`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Kind of actor that created the request. - [`Resource`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) Order, product, case, or other resource that needs the file. - [`Resource.ID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Resource ID. - [`Resource.Name`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Resource name when available. - [`Resource.Type`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Resource type. - [`Status`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Upload-request lifecycle status: [`uploadrequest.StatusPending`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#StatusPending), [`uploadrequest.StatusUploading`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#StatusUploading), [`uploadrequest.StatusFulfilled`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#StatusFulfilled), [`uploadrequest.StatusExpired`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#StatusExpired), [`uploadrequest.StatusCanceled`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#StatusCanceled), or [`uploadrequest.StatusFailed`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#StatusFailed). - [`Subject`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) Person or resource that the requested file is about. - [`Subject.Email`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Subject email when available. - [`Subject.ID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Subject ID when available. - [`Subject.Name`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Subject display name when available. - [`Subject.Type`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `string` Subject type such as `"customer"`, `"case"`, or `"user"`. - [`UpdatedAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) — `timestamp` When the upload request was last updated. - [`UploadURL`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#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. - [`UploadingAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#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, [`UploadRequest.Attempt.Review`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#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 [`UploadRequest.UploadURL`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) that you can place behind a button, send in a message, or hand to another trusted system. The [`Purpose`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#CreateParams.Purpose) sets the kinds and maximum size of file Inttegro accepts. Use [`Constraints`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#CreateParams.Constraints) only when this particular request should be stricter—for example, to accept only PDF support documents under 10 MiB. ### Request body - `attempts` — wire-only Optional limit on failed upload attempts. - `attempts.max_attempts` — `integer` — wire-only Maximum number of allowed failed attempts. Defaults to `3`. - [`Constraints`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#CreateParams.Constraints) — `uploadrequest.Constraints` Optional requirements for this upload. These can narrow, but not widen, the selected purpose. - [`Constraints.ContentTypes`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#Constraints.ContentTypes) — `[]string` Optional narrowed allow-list of MIME types. - [`Constraints.ExactSize`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#Constraints.ExactSize) — `int64` Optional exact file size in bytes. - [`Constraints.Extensions`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#Constraints.Extensions) — `[]string` Optional narrowed allow-list of filename extensions. - [`Constraints.Filename`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#Constraints.Filename) — `string` Optional exact filename requirement. - [`Constraints.MaxSize`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#Constraints.MaxSize) — `int64` Optional maximum file size in bytes. - [`Constraints.MinSize`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#Constraints.MinSize) — `int64` Optional minimum file size in bytes. - [`CustomData`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#CreateParams.CustomData) — `*customdata.Data` 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://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#CreateParams.Display) — `uploadrequest.Display` Optional uploader-facing copy. - [`Display.Description`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#Display.Description) — `string` Optional longer description of what to upload. - [`Display.HelpText`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#Display.HelpText) — `string` Optional supporting guidance for the uploader. - [`Display.Title`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#Display.Title) — `string` Short title for the upload prompt. - [`ExpiresAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#CreateParams.ExpiresAt) — `*time.Time` Optional RFC 3339 expiry. The default is 24 hours from creation. - [`Purpose`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#CreateParams.Purpose) — `string` — required File purpose the upload must satisfy. - [`Recipient`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#CreateParams.Recipient) — `uploadrequest.Party` Optional uploader identity details. - [`Recipient.Email`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#Party.Email) — `string` Recipient email when available. - [`Recipient.ID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#Party.ID) — `string` Recipient ID when available. - [`Recipient.Name`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#Party.Name) — `string` Recipient display name when available. - [`Recipient.Type`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#Party.Type) — `string` Recipient type. - [`Requester`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#CreateParams.Requester) — `filelink.Actor` Optional details about the person or system creating the request. Normally, Inttegro identifies the caller from the API key. - [`Requester.Email`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/filelink#Actor.Email) — `string` Actor email when available. - [`Requester.ID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/filelink#Actor.ID) — `string` Actor ID when available. - [`Requester.Name`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/filelink#Actor.Name) — `string` Actor display name when available. - [`Requester.Type`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/filelink#Actor.Type) — `string` Actor type. - [`Resource`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#CreateParams.Resource) — `uploadrequest.FileResource` Optional Inttegro resource or workflow that needs the file. - [`Resource.ID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#FileResource.ID) — `string` Resource ID. - [`Resource.Name`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#FileResource.Name) — `string` Resource name when available. - [`Resource.Type`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#FileResource.Type) — `string` Resource type. - [`Subject`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#CreateParams.Subject) — `uploadrequest.Party` Optional person or Inttegro object the requested file is about. - [`Subject.Email`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#Party.Email) — `string` Subject email when available. - [`Subject.ID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#Party.ID) — `string` Subject ID when available. - [`Subject.Name`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#Party.Name) — `string` Subject display name when available. - [`Subject.Type`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#Party.Type) — `string` Subject type. ### Upload limits - The link expires after 24 hours unless you provide a future [`ExpiresAt`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#CreateParams.ExpiresAt). - The uploader gets three failed attempts unless you set `attempts.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 [`UploadRequest.UploadURL`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#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** ```go package main import ( "context" "log" "os" "time" inttegro "github.com/inttegro/inttegro-sdk-go/v11" "github.com/inttegro/inttegro-sdk-go/v11/customdata" "github.com/inttegro/inttegro-sdk-go/v11/request" "github.com/inttegro/inttegro-sdk-go/v11/uploadrequest" ) func main() { ctx := context.Background() client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY")) params := uploadrequest.CreateParams{ Purpose: "support_document", Constraints: uploadrequest.Constraints{ ContentTypes: []string{ "application/pdf", }, MaxSize: 10485760, }, Display: uploadrequest.Display{ Title: "Upload dispute evidence", HelpText: "Attach a PDF under 10 MB.", }, Recipient: uploadrequest.Party{ Type: "customer", Email: "ama@example.com", }, Resource: uploadrequest.FileResource{ Type: "dispute", ID: "disp_123", }, CustomData: func() *customdata.Data { value, err := customdata.New(map[string]string{ "case_id": "CASE-1001", }); if err != nil { panic(err) }; return value }(), ExpiresAt: mustParseTime("2030-07-06T12:30:00Z"), } result, err := client.UploadRequests.Create(ctx, params, request.WithIdempotencyKey("support-doc-upload-001")) if err != nil { log.Fatal(err) } _ = result } func mustParseTime(value string) *time.Time { parsed, err := time.Parse(time.RFC3339, value) if err != nil { panic(err) } return &parsed } ``` ```json { "upload_request": { "id": "uplreq_1gK9pQ4vL8mN2sT5wX7yZ0", "purpose": "support_document", "status": "pending", "active": true, "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://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#File). Your authenticated backend can pass that ID to [Lookup a file](https://studio.inttegro.com/machine/go/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** ```go package main import ( "context" "log" "os" inttegro "github.com/inttegro/inttegro-sdk-go/v11" "github.com/inttegro/inttegro-sdk-go/v11/uploadrequest" ) func main() { ctx := context.Background() client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY")) uploadRequest, file, err := client.UploadRequests.Fulfill(ctx, uploadrequest.FulfillParams{ UploadURL: "", File: "./evidence.pdf", }) if err != nil { log.Fatal(err) } _ = uploadRequest _ = file } ``` ## 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, [`UploadRequest.FileID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#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 [`UploadRequest.UploadURL`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest); retain that URL only for as long as the intended uploader needs it. **Request — POST /upload\_requests/lookup** ```go package main import ( "context" "log" "os" inttegro "github.com/inttegro/inttegro-sdk-go/v11" ) func main() { ctx := context.Background() client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY")) result, err := client.UploadRequests.Lookup(ctx, "uplreq_1gK9pQ4vL8mN2sT5wX7yZ0") if err != nil { log.Fatal(err) } _ = result } ``` ## 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 - [`AttemptID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#ReviewParams.AttemptID) — `string` Attempt ID to review. Supply exactly one of [`AttemptID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#ReviewParams.AttemptID) or [`AttemptOrdinal`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#ReviewParams.AttemptOrdinal). - [`AttemptOrdinal`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#ReviewParams.AttemptOrdinal) — `int64` One-based attempt number to review. Supply exactly one of [`AttemptID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#ReviewParams.AttemptID) or [`AttemptOrdinal`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#ReviewParams.AttemptOrdinal). - [`Decision`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#ReviewParams.Decision) — `inttegro.string(UploadReviewDecision)` — required Review decision: [`uploadrequest.ReviewDecisionApproved`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#ReviewDecisionApproved) or [`uploadrequest.ReviewDecisionRejected`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#ReviewDecisionRejected). - [`ID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#ReviewParams.ID) — `string` — required Upload-request ID that owns the attempt. - [`PublicMessage`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#ReviewParams.PublicMessage) — `string` Optional explanation suitable for showing to the uploader. - [`Reasons`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#ReviewParams.Reasons) — `[]uploadrequest.ReviewReason` Optional structured reasons for the decision. - [`Reasons.Code`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#ReviewReason.Code) — `string` Required stable reason code. - [`Reasons.Message`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#ReviewReason.Message) — `string` Required customer-safe explanation. - [`Reasons.Param`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#ReviewReason.Param) — `string` 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 [`PublicMessage`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#ReviewParams.PublicMessage) and [`Reasons`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#ReviewParams.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** ```go package main import ( "context" "log" "os" inttegro "github.com/inttegro/inttegro-sdk-go/v11" "github.com/inttegro/inttegro-sdk-go/v11/request" "github.com/inttegro/inttegro-sdk-go/v11/uploadrequest" ) func main() { ctx := context.Background() client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY")) params := uploadrequest.ReviewParams{ ID: "uplreq_1gK9pQ4vL8mN2sT5wX7yZ0", AttemptOrdinal: 1, Decision: string(uploadrequest.ReviewDecisionRejected), Reasons: []uploadrequest.ReviewReason{ { Code: "document_unreadable", Message: "The document is too blurry to read.", }, }, PublicMessage: "Please upload a clearer copy.", } result, err := client.UploadRequests.Review(ctx, params, request.WithIdempotencyKey("review-upload-attempt-001")) if err != nil { log.Fatal(err) } _ = result } ``` ## 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 - [`PageNumber`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#PageParams.PageNumber) — `int` Page number to retrieve. Defaults to `1`. - [`PageSize`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#PageParams.PageSize) — `int` Requested number of upload requests per page. Defaults to `25` and is capped at `256`. - [`Purpose`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#PageParams.Purpose) — `string` Optional purpose filter. - [`Resource`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#PageParams.Resource) — `uploadrequest.FileResource` Optional resource filter. - [`Resource.ID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#FileResource.ID) — `string` Resource ID. - [`Resource.Name`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#FileResource.Name) — `string` Resource name when available. - [`Resource.Type`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#FileResource.Type) — `string` Resource type. - [`Status`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#PageParams.Status) — `string` Optional status filter: [`uploadrequest.StatusPending`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#StatusPending), [`uploadrequest.StatusUploading`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#StatusUploading), [`uploadrequest.StatusFulfilled`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#StatusFulfilled), [`uploadrequest.StatusExpired`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#StatusExpired), [`uploadrequest.StatusCanceled`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#StatusCanceled), or [`uploadrequest.StatusFailed`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#StatusFailed). ### Response Returns a page with [`Page.UploadRequests`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#Page), [`Page.Number`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#Page), and [`Page.Size`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#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.UploadRequests`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#Page) collection and [`Page.Size`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#Page) set to `0`. **Request — POST /upload\_requests/page** ```go package main import ( "context" "log" "os" inttegro "github.com/inttegro/inttegro-sdk-go/v11" "github.com/inttegro/inttegro-sdk-go/v11/uploadrequest" ) func main() { ctx := context.Background() client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY")) params := uploadrequest.PageParams{ Purpose: "support_document", Status: "pending", PageNumber: 1, PageSize: 25, } result, err := client.UploadRequests.Page(ctx, params) if err != nil { log.Fatal(err) } _ = result } ``` ## 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 - [`CanceledBy`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#CancelParams.CanceledBy) — `filelink.Actor` Optional actor canceling the request. - [`CanceledBy.Email`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/filelink#Actor.Email) — `string` Actor email when available. - [`CanceledBy.ID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/filelink#Actor.ID) — `string` Actor ID when available. - [`CanceledBy.Name`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/filelink#Actor.Name) — `string` Actor display name when available. - [`CanceledBy.Type`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/filelink#Actor.Type) — `string` Actor type. - [`ID`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#CancelParams.ID) — `string` — required Upload-request ID to cancel. ### Response Returns the request with [`UploadRequest.Status`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#UploadRequest) set to [`uploadrequest.StatusCanceled`](https://pkg.go.dev/github.com/inttegro/inttegro-sdk-go/v11@v11.0.1/uploadrequest#StatusCanceled). Use a stable idempotency key when retrying the cancellation. **Request — POST /upload\_requests/cancel** ```go package main import ( "context" "log" "os" inttegro "github.com/inttegro/inttegro-sdk-go/v11" "github.com/inttegro/inttegro-sdk-go/v11/filelink" "github.com/inttegro/inttegro-sdk-go/v11/request" "github.com/inttegro/inttegro-sdk-go/v11/uploadrequest" ) func main() { ctx := context.Background() client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY")) params := uploadrequest.CancelParams{ ID: "uplreq_1gK9pQ4vL8mN2sT5wX7yZ0", CanceledBy: filelink.Actor{ Type: "user", ID: "usr_support_123", }, } result, err := client.UploadRequests.Cancel(ctx, params, request.WithIdempotencyKey("cancel-upload-request-001")) if err != nil { log.Fatal(err) } _ = result } ```