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.
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.UploadRequestStatuses.Pending; an accepted file changes the request to Inttegro.UploadRequestStatuses.Fulfilled and sets fileId. A request can instead become Inttegro.UploadRequestStatuses.Failed, Inttegro.UploadRequestStatuses.Expired, or Inttegro.UploadRequestStatuses.Canceled.
Use active to decide whether the link can still accept a file. When a request is fulfilled, retrieve the resulting file through Lookup a file.
Properties
attemptRecord<string, unknown>Most recent upload attempt. Lookup and upload responses include it after the uploader has tried to send a file.Click or tap to expandView error detailsClick or tap to expand
Why the file was not accepted and whether the uploader may try again.View review detailsClick or tap to expand
Your approval or rejection of the uploaded file, when reviewed.
attemptsUploadRequestAttemptsUpload-attempt limit and current counts.Click or tap to expand- Name
attemptCount- Type
number- Description
- Total upload attempts recorded for this request.
- Name
failedAttemptCount- Type
number- Description
- How many upload attempts have failed validation or fulfillment.
- Name
lastAttemptedAt- Type
Date- Description
- When the most recent upload attempt happened.
- Name
maxAttempts- Type
number- Description
- Maximum number of allowed failed attempts.
- Name
canceledAt- Type
Date | null- Description
When the request was canceled. Returned only after cancellation.
constraintsUploadRequestConstraintsOptional file requirements that are stricter than the selected purpose.Click or tap to expand- Name
contentTypes- Type
string[]- Description
- Optional narrowed allow-list of MIME types.
- Name
exactSize- Type
number- Description
- Optional exact file size in bytes.
- Name
extensions- Type
string[]- Description
- Optional narrowed allow-list of filename extensions.
- Name
filename- Type
string- Description
- Optional exact filename requirement.
- Name
maxSize- Type
number- Description
- Optional maximum file size in bytes.
- Name
minSize- Type
number- Description
- Optional minimum file size in bytes.
- Name
createdAt- Type
Date- Description
When the upload request was created.
customDataCustomDataClick or tap to expandOptional string key-value custom data copied to the resulting file.
displayUploadRequestDisplayHuman-facing copy shown to the uploader.Click or tap to expand- Name
description- Type
string- Description
- Optional longer explanation of what should be uploaded.
- Name
helpText- Type
string- Description
- Optional supporting guidance for the uploader.
- Name
title- Type
string- Description
- Short title for the upload prompt.
- Name
expiresAt- Type
Date | null- Description
When the public upload URL stops accepting uploads.
- Name
id- Type
string- Description
Unique upload-request identifier. IDs begin with
uplreq_.
metadataFileMetadataClick or tap to expandAdditional read-only details supplied by Inttegro. Use
customDatafor your own data.- Name
purpose- Type
string- Description
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.
requesterFileActorPerson or system that created the request. Inttegro identifies the caller from the API key unless you supply additional details.Click or tap to expandresourceFileResourceOrder, product, case, or other resource that needs the file.Click or tap to expand- Name
status- Type
UploadRequestStatus- Description
Upload-request lifecycle status:
Inttegro.UploadRequestStatuses.Pending,Inttegro.UploadRequestStatuses.Uploading,Inttegro.UploadRequestStatuses.Fulfilled,Inttegro.UploadRequestStatuses.Expired,Inttegro.UploadRequestStatuses.Canceled, orInttegro.UploadRequestStatuses.Failed.
- Name
uploadUrl- Type
string- Description
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.
When an attempt has been reviewed, attempt.review 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 uploadUrl that you can place behind a button, send in a message, or hand to another trusted system.
The purpose sets the kinds and maximum size of file Inttegro accepts. Use constraints only when this particular request should be stricter—for example, to accept only PDF support documents under 10 MiB.
Request body
attemptsPick<UploadRequestAttempts, 'maxAttempts'>Optional limit on failed upload attempts.Click or tap to expand- Name
maxAttempts- Type
number- Description
- Maximum number of allowed failed attempts. Defaults to
3.
constraintsUploadRequestConstraintsOptional requirements for this upload. These can narrow, but not widen, the selected purpose.Click or tap to expand- Name
contentTypes- Type
string[]- Description
- Optional narrowed allow-list of MIME types.
- Name
exactSize- Type
number- Description
- Optional exact file size in bytes.
- Name
extensions- Type
string[]- Description
- Optional narrowed allow-list of filename extensions.
- Name
filename- Type
string- Description
- Optional exact filename requirement.
- Name
maxSize- Type
number- Description
- Optional maximum file size in bytes.
- Name
minSize- Type
number- Description
- Optional minimum file size in bytes.
customDataCustomDataClick or tap to expandOptional 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.
displayUploadRequestDisplayOptional uploader-facing copy.Click or tap to expand- Name
description- Type
string- Description
- Optional longer description of what to upload.
- Name
helpText- Type
string- Description
- Optional supporting guidance for the uploader.
- Name
title- Type
string- Description
- Short title for the upload prompt.
- Name
expiresAt- Type
Date- Description
Optional RFC 3339 expiry. The default is 24 hours from creation.
- Name
purpose- Type
string- Required
- required
- Description
File purpose the upload must satisfy.
resourceFileResourceOptional Inttegro resource or workflow that needs the file.Click or tap to expand
Upload limits
- The link expires after 24 hours unless you provide a future
expiresAt. - The uploader gets three failed attempts unless you set
attempts.maxAttempts. - 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 uploadUrl. 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
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.uploadRequests.create({
purpose: "support_document",
constraints: {
contentTypes: [
"application/pdf",
],
maxSize: 10485760,
},
display: {
title: "Upload dispute evidence",
helpText: "Attach a PDF under 10 MB.",
},
recipient: {
type: "customer",
},
resource: {
type: "dispute",
id: "disp_123",
},
customData: {
case_id: "CASE-1001",
},
expiresAt: new Date("2030-07-06T12:30:00Z"),
}, {
idempotencyKey: "support-doc-upload-001",
})
Response
- Object
- JSON
UploadRequestResponse {
uploadRequest: { … },
}
{
"upload_request": {
"id": "uplreq_1gK9pQ4vL8mN2sT5wX7yZ0",
"purpose": "support_document",
"status": "pending",
"active": true,
"upload_url": "<UPLOAD_URL>",
"constraints": { … },
"display": { … },
"subject": {},
"resource": { "type": "dispute", "id": "disp_123" },
"requester": { "type": "api_key" },
"attempts": { … },
"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
Request body
Response
Returns the fulfilled upload request and a file receipt containing the resulting file.id. Your authenticated backend can pass that ID to 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
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.uploadRequests.fulfill({
uploadUrl: '<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, fileId identifies the file Inttegro created.
Request body
Response
Returns the upload request and its latest attempt, when one exists. The response does not include uploadUrl; retain that URL only for as long as the intended uploader needs it.
Request
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.uploadRequests.lookup({
id: "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
- Name
attemptId- Type
string- Description
Attempt ID to review. Supply exactly one of
attemptIdorattemptOrdinal.
- Name
attemptOrdinal- Type
number- Description
One-based attempt number to review. Supply exactly one of
attemptIdorattemptOrdinal.
- Name
decision- Type
UploadReviewDecision- Required
- required
- Description
Review decision:
Inttegro.UploadReviewDecisions.ApprovedorInttegro.UploadReviewDecisions.Rejected.
- Name
id- Type
string- Required
- required
- Description
Upload-request ID that owns the attempt.
- Name
publicMessage- Type
string- Description
Optional explanation suitable for showing to the uploader.
reasonsUploadRequestReviewReason[]Optional structured reasons for the decision.Click or tap to expand
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 and 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
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.uploadRequests.review({
id: "uplreq_1gK9pQ4vL8mN2sT5wX7yZ0",
attemptOrdinal: 1,
decision: Inttegro.UploadReviewDecisions.Rejected,
reasons: [
{
code: "document_unreadable",
message: "The document is too blurry to read.",
},
],
publicMessage: "Please upload a clearer copy.",
}, {
idempotencyKey: "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
- Name
pageNumber- Type
number- Description
Page number to retrieve. Defaults to
1.
- Name
pageSize- Type
number- Description
Requested number of upload requests per page. Defaults to
25and is capped at256.
- Name
purpose- Type
string- Description
Optional purpose filter.
resourceFileResourceOptional resource filter.Click or tap to expand- Name
status- Type
UploadRequestStatus- Description
Optional status filter:
Inttegro.UploadRequestStatuses.Pending,Inttegro.UploadRequestStatuses.Uploading,Inttegro.UploadRequestStatuses.Fulfilled,Inttegro.UploadRequestStatuses.Expired,Inttegro.UploadRequestStatuses.Canceled, orInttegro.UploadRequestStatuses.Failed.
Response
Returns a page with uploadRequests, number, and size. Page items omit the latest attempt; use Lookup an upload request when you need an attempt or its validation error. An empty page has an empty uploadRequests collection and size set to 0.
Request
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.uploadRequests.page({
purpose: "support_document",
status: "pending",
pageNumber: 1,
pageSize: 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
- Name
id- Type
string- Required
- required
- Description
Upload-request ID to cancel.
Response
Returns the request with status set to Inttegro.UploadRequestStatuses.Canceled. Use a stable idempotency key when retrying the cancellation.
Request
import * as Inttegro from '@inttegro/inttegro-sdk'
const inttegro = new Inttegro.InttegroClient({
apiKey: process.env.INTTEGRO_API_KEY!,
})
const result = await inttegro.uploadRequests.cancel({
id: "uplreq_1gK9pQ4vL8mN2sT5wX7yZ0",
canceledBy: {
type: "user",
id: "usr_support_123",
},
}, {
idempotencyKey: "cancel-upload-request-001",
})