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.

Operations

Create an upload request
Fulfill an upload request
Lookup an upload request
Review an upload attempt
Page upload requests
Cancel an upload request

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 pending; an accepted file changes the request to fulfilled and sets file_id. A request can instead become failed, expired, or 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

Name
active
Type
boolean
Description
Whether the request can still accept an upload.
attemptobjectMost recent upload attempt. Lookup and upload responses include it after the uploader has tried to send a file.Click or tap to expand
- Name
  attempted_at
  Type
  timestamp
  Description
  When the upload attempt started.
- Name
  content_type
  Type
  string
  Description
  Declared content type when present.
- Name
  declared_size
  Type
  integer
  Description
  Declared file size in bytes when present.
- Name
  error
  Type
  object
  View error detailsClick or tap to expand
  Why the file was not accepted and whether the uploader may try again.
- Name
  failed_at
  Type
  timestamp
  Description
  When a failed attempt completed.
- Name
  file_id
  Type
  string
  Description
  Resulting file ID after a successful attempt.
- Name
  filename
  Type
  string
  Description
  Submitted filename when present.
- Name
  id
  Type
  string
  Description
  Unique attempt identifier.
- Name
  ordinal
  Type
  integer
  Description
  One-based attempt number for the request.
- Name
  review
  Type
  object
  View review detailsClick or tap to expand
  Your approval or rejection of the uploaded file, when reviewed.
- Name
  status
  Type
  string
  Description
  Attempt status such as succeeded or failed.
- Name
  succeeded_at
  Type
  timestamp
  Description
  When a successful attempt completed.
- Name
  upload_request_id
  Type
  string
  Description
  Upload-request ID that owns the attempt.
attemptsobjectUpload-attempt limit and current counts.Click or tap to expand
- Name
  attempt_count
  Type
  integer
  Description
  Total upload attempts recorded for this request.
- Name
  failed_attempt_count
  Type
  integer
  Description
  How many upload attempts have failed validation or fulfillment.
- Name
  last_attempted_at
  Type
  timestamp
  Description
  When the most recent upload attempt happened.
- Name
  max_attempts
  Type
  integer
  Description
  Maximum number of allowed failed attempts.
Name
canceled_at
Type
timestamp
Description
When the request was canceled. Returned only after cancellation.
canceled_byobjectPerson or system that canceled the request. Present only after cancellation.Click or tap to expand
- Name
  email
  Type
  string
  Description
  Actor email when available.
- Name
  id
  Type
  string
  Description
  Actor ID when available.
- Name
  name
  Type
  string
  Description
  Actor display name when available.
- Name
  service
  Type
  string
  Description
  Service name when the request was canceled by an automated workflow.
- Name
  type
  Type
  string
  Description
  Kind of actor that canceled the request.
constraintsobjectOptional file requirements that are stricter than the selected purpose.Click or tap to expand
- Name
  content_types
  Type
  array
  Description
  Optional narrowed allow-list of MIME types.
- Name
  exact_size
  Type
  integer
  Description
  Optional exact file size in bytes.
- Name
  extensions
  Type
  array
  Description
  Optional narrowed allow-list of filename extensions.
- Name
  filename
  Type
  string
  Description
  Optional exact filename requirement.
- Name
  max_size
  Type
  integer
  Description
  Optional maximum file size in bytes.
- Name
  min_size
  Type
  integer
  Description
  Optional minimum file size in bytes.
Name
created_at
Type
timestamp
Description
When the upload request was created.
custom_dataobjectClick or tap to expand
Optional string key-value custom data copied to the resulting file.
displayobjectHuman-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
  help_text
  Type
  string
  Description
  Optional supporting guidance for the uploader.
- Name
  title
  Type
  string
  Description
  Short title for the upload prompt.
Name
expired_at
Type
timestamp
Description
When the request was marked expired. Returned only after expiry is recorded.
Name
expires_at
Type
timestamp
Description
When the public upload URL stops accepting uploads.
Name
file_id
Type
string
Description
Resulting file ID after a successful upload. Omitted until fulfillment succeeds.
Name
fulfilled_at
Type
timestamp
Description
When a valid upload produced the file. Returned only after fulfillment succeeds.
Name
id
Type
string
Description
Unique upload-request identifier. IDs begin with uplreq_.
latest_errorobjectMost recent validation or fulfillment error.Click or tap to expand
- Name
  at
  Type
  timestamp
  Description
  When the error was recorded.
- Name
  code
  Type
  string
  Description
  Stable error code for the failure.
- Name
  message
  Type
  string
  Description
  Human-readable error message.
- Name
  param
  Type
  string
  Description
  Request field associated with the error when available.
- Name
  retryable
  Type
  boolean
  Description
  Whether the uploader can try again.
metadataobjectClick or tap to expand
Additional read-only details supplied by Inttegro. Use custom_data for 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.
recipientobjectPerson expected to provide the file, when you want that context on the request.Click or tap to expand
- Name
  email
  Type
  string
  Description
  Recipient email when available.
- Name
  id
  Type
  string
  Description
  Recipient ID when available.
- Name
  name
  Type
  string
  Description
  Recipient display name when available.
- Name
  type
  Type
  string
  Description
  Recipient type such as customer, email, or user.
requesterobjectPerson or system that created the request. Inttegro identifies the caller from the API key unless you supply additional details.Click or tap to expand
- Name
  email
  Type
  string
  Description
  Actor email when available.
- Name
  id
  Type
  string
  Description
  Actor ID when available.
- Name
  name
  Type
  string
  Description
  Actor display name when available.
- Name
  service
  Type
  string
  Description
  Service name when the request came from an automated workflow.
- Name
  type
  Type
  string
  Description
  Kind of actor that created the request.
resourceobjectOrder, product, case, or other resource that needs the file.Click or tap to expand
- Name
  id
  Type
  string
  Description
  Resource ID.
- Name
  name
  Type
  string
  Description
  Resource name when available.
- Name
  type
  Type
  string
  Description
  Resource type.
Name
status
Type
string
Description
Upload-request lifecycle status: pending, uploading, fulfilled, expired, canceled, or failed.
subjectobjectPerson or resource that the requested file is about.Click or tap to expand
- Name
  email
  Type
  string
  Description
  Subject email when available.
- Name
  id
  Type
  string
  Description
  Subject ID when available.
- Name
  name
  Type
  string
  Description
  Subject display name when available.
- Name
  type
  Type
  string
  Description
  Subject type such as customer, case, or user.
Name
updated_at
Type
timestamp
Description
When the upload request was last updated.
Name
upload_url
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.
Name
uploading_at
Type
timestamp
Description
When an upload attempt moved into active fulfillment. Returned only while or after an upload attempt has started.

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.

POST/upload_requests/create

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_url 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

attemptsobjectOptional limit on failed upload attempts.Click or tap to expand
- Name
  max_attempts
  Type
  integer
  Description
  Maximum number of allowed failed attempts. Defaults to 3.
constraintsobjectOptional requirements for this upload. These can narrow, but not widen, the selected purpose.Click or tap to expand
- Name
  content_types
  Type
  array
  Description
  Optional narrowed allow-list of MIME types.
- Name
  exact_size
  Type
  integer
  Description
  Optional exact file size in bytes.
- Name
  extensions
  Type
  array
  Description
  Optional narrowed allow-list of filename extensions.
- Name
  filename
  Type
  string
  Description
  Optional exact filename requirement.
- Name
  max_size
  Type
  integer
  Description
  Optional maximum file size in bytes.
- Name
  min_size
  Type
  integer
  Description
  Optional minimum file size in bytes.
custom_dataobjectClick or tap to expand
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.
displayobjectOptional uploader-facing copy.Click or tap to expand
- Name
  description
  Type
  string
  Description
  Optional longer description of what to upload.
- Name
  help_text
  Type
  string
  Description
  Optional supporting guidance for the uploader.
- Name
  title
  Type
  string
  Description
  Short title for the upload prompt.
Name
expires_at
Type
timestamp
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.
recipientobjectOptional uploader identity details.Click or tap to expand
- Name
  email
  Type
  string
  Description
  Recipient email when available.
- Name
  id
  Type
  string
  Description
  Recipient ID when available.
- Name
  name
  Type
  string
  Description
  Recipient display name when available.
- Name
  type
  Type
  string
  Description
  Recipient type.
requesterobjectOptional details about the person or system creating the request. Normally, Inttegro identifies the caller from the API key.Click or tap to expand
- Name
  email
  Type
  string
  Description
  Actor email when available.
- Name
  id
  Type
  string
  Description
  Actor ID when available.
- Name
  name
  Type
  string
  Description
  Actor display name when available.
- Name
  type
  Type
  string
  Description
  Actor type.
resourceobjectOptional Inttegro resource or workflow that needs the file.Click or tap to expand
- Name
  id
  Type
  string
  Description
  Resource ID.
- Name
  name
  Type
  string
  Description
  Resource name when available.
- Name
  type
  Type
  string
  Description
  Resource type.
subjectobjectOptional person or Inttegro object the requested file is about.Click or tap to expand
- Name
  email
  Type
  string
  Description
  Subject email when available.
- Name
  id
  Type
  string
  Description
  Subject ID when available.
- Name
  name
  Type
  string
  Description
  Subject display name when available.
- Name
  type
  Type
  string
  Description
  Subject type.

Upload limits

The link expires after 24 hours unless you provide a future expires_at.
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 upload_url. 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

curl https://api.inttegro.com/upload_requests/create \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Idempotency-Key: support-doc-upload-001" \
  -H "Content-Type: application/json" \
  -d '{
    "purpose": "support_document",
    "constraints": {
      "content_types": ["application/pdf"],
      "max_size": 10485760
    },
    "display": {
      "title": "Upload dispute evidence",
      "help_text": "Attach a PDF under 10 MB."
    },
    "recipient": { "type": "customer", "email": "[email protected]" },
    "resource": { "type": "dispute", "id": "disp_123" },
    "custom_data": { "case_id": "CASE-1001" },
    "expires_at": "2030-07-06T12:30:00Z"
  }'

SDK versionv8.2.0

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",
    email: "[email protected]",
  },
  resource: {
    type: "dispute",
    id: "disp_123",
  },
  customData: {
    case_id: "CASE-1001",
  },
  expiresAt: "2030-07-06T12:30:00Z",
}, {
  idempotencyKey: "support-doc-upload-001",
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  params := inttegro.UploadRequestCreateParams{
    Purpose: "support_document",
    Constraints: inttegro.UploadRequestConstraints{
      ContentTypes: []string{
        "application/pdf",
      },
      MaxSize: 10485760,
    },
    Display: inttegro.UploadRequestDisplay{
      Title: "Upload dispute evidence",
      HelpText: "Attach a PDF under 10 MB.",
    },
    Recipient: inttegro.FileParty{
      Type: "customer",
      Email: "[email protected]",
    },
    Resource: inttegro.FileResource{
      Type: "dispute",
      ID: "disp_123",
    },
    CustomData: map[string]string{
      "case_id": "CASE-1001",
    },
    ExpiresAt: "2030-07-06T12:30:00Z",
  }
  result, err := client.UploadRequests.Create(ctx, params, inttegro.WithIdempotencyKey("support-doc-upload-001"))
  if err != nil {
    log.Fatal(err)
  }
  _ = result
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.upload_requests.create(inttegro.upload_requests.CreateRequest(
  purpose="support_document",
  constraints=inttegro.upload_requests.Constraints(
    content_types=[
      "application/pdf",
    ],
    max_size=10485760,
  ),
  display=inttegro.upload_requests.Display(
    title="Upload dispute evidence",
    help_text="Attach a PDF under 10 MB.",
  ),
  recipient=inttegro.FilePartyInput(
    type="customer",
    email="[email protected]",
  ),
  resource=inttegro.FileResourceInput(
    type="dispute",
    id="disp_123",
  ),
  custom_data={
    "case_id": "CASE-1001",
  },
  expires_at="2030-07-06T12:30:00Z",
),
    idempotency_key="support-doc-upload-001")

SDK versionv5.3.0

<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->uploadRequests->create([
  'purpose' => 'support_document',
  'constraints' => [
    'content_types' => [
      'application/pdf',
    ],
    'max_size' => 10485760,
  ],
  'display' => [
    'title' => 'Upload dispute evidence',
    'help_text' => 'Attach a PDF under 10 MB.',
  ],
  'recipient' => [
    'type' => 'customer',
    'email' => '[email protected]',
  ],
  'resource' => [
    'type' => 'dispute',
    'id' => 'disp_123',
  ],
  'custom_data' => [
    'case_id' => 'CASE-1001',
  ],
  'expires_at' => '2030-07-06T12:30:00Z',
]);

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.upload_requests.create(
  purpose: "support_document",
  constraints: {
    content_types: [
      "application/pdf",
    ],
    max_size: 10485760,
  },
  display: {
    title: "Upload dispute evidence",
    help_text: "Attach a PDF under 10 MB.",
  },
  recipient: {
    type: "customer",
    email: "[email protected]",
  },
  resource: {
    type: "dispute",
    id: "disp_123",
  },
  custom_data: {
    case_id: "CASE-1001",
  },
  expires_at: "2030-07-06T12:30:00Z",
  idempotency_key: "support-doc-upload-001"
)

SDK versionv5.2.0

import com.inttegro.Client;
import com.inttegro.files.UploadRequestCreateParams;
import com.inttegro.files.UploadConstraints;
import java.util.List;
import com.inttegro.files.UploadDisplay;
import com.inttegro.files.Actor;
import com.inttegro.files.ResourceRef;
import java.util.Map;
import com.inttegro.RequestOptions;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = UploadRequestCreateParams.builder()
      .purpose("support_document")
      .constraints(UploadConstraints.builder()
          .contentTypes(List.of(
              "application/pdf"
            ))
          .maxSize(10485760)
          .build())
      .display(UploadDisplay.builder()
          .title("Upload dispute evidence")
          .helpText("Attach a PDF under 10 MB.")
          .build())
      .recipient(Actor.builder()
          .type("customer")
          .email("[email protected]")
          .build())
      .resource(ResourceRef.builder()
          .type("dispute")
          .id("disp_123")
          .build())
      .customData(Map.<String, String>ofEntries(
          Map.entry("case_id", "CASE-1001")
        ))
      .expiresAt("2030-07-06T12:30:00Z")
      .build();
    var result = client.uploadRequests().create(params, RequestOptions.withIdempotencyKey("support-doc-upload-001"));
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.UploadRequests.CreateAsync(new {
  purpose = "support_document",
  constraints = new {
    content_types = new[] {
      "application/pdf",
    },
    max_size = 10485760,
  },
  display = new {
    title = "Upload dispute evidence",
    help_text = "Attach a PDF under 10 MB.",
  },
  recipient = new {
    type = "customer",
    email = "[email protected]",
  },
  resource = new {
    type = "dispute",
    id = "disp_123",
  },
  custom_data = new {
    case_id = "CASE-1001",
  },
  expires_at = "2030-07-06T12:30:00Z",
}, "support-doc-upload-001");

Response

Object
JSON

SDK versionv8.2.0

UploadRequestResponse {
  uploadRequest: { … },
}

SDK versionv8.2.0

{
  "upload_request": {
    "id": "uplreq_1gK9pQ4vL8mN2sT5wX7yZ0",
    "purpose": "support_document",
    "status": "pending",
    "active": true,
    "upload_url": "<UPLOAD_URL>",
    "constraints": { … },
    "display": { … },
    "subject": {},
    "recipient": { "type": "customer", "email": "[email protected]" },
    "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"
  }
}

POST/upload_requests/upload

Fulfill an upload request

Send the file as multipart/form-data to the complete upload_url 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

Name
id
Type
string
Required
required
Description
Identifies the upload request. It is already present in upload_url.
Name
token
Type
string
Required
required
Description
Authorizes the upload. It is already present in upload_url and must remain private.

Request body

Name
file
Type
file
Required
required
Description
File selected by the uploader.

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

POST/upload_requests/upload

curl "<UPLOAD_URL>" \
  -F "file=@./evidence.pdf;type=application/pdf"

SDK versionv8.2.0

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',
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  uploadRequest, file, err := client.UploadRequests.Fulfill(ctx, inttegro.UploadRequestFulfillParams{
    UploadURL: "<UPLOAD_URL>",
    File:      "./evidence.pdf",
  })
  if err != nil {
    log.Fatal(err)
  }
  _ = uploadRequest
  _ = file
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.upload_requests.fulfill(
    upload_url="<UPLOAD_URL>",
    file="./evidence.pdf",
)

SDK versionv5.3.0

<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->uploadRequests->fulfill([
    'upload_url' => '<UPLOAD_URL>',
    'file' => './evidence.pdf',
]);

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.upload_requests.fulfill(
  upload_url: "<UPLOAD_URL>",
  file: "./evidence.pdf"
)

SDK versionv5.2.0

import com.inttegro.Client;
import com.inttegro.files.UploadRequestFulfillParams;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = UploadRequestFulfillParams.builder()
      .uploadUrl("<UPLOAD_URL>")
      .file("./evidence.pdf")
      .build();
    var result = client.uploadRequests().fulfill(params);
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.UploadRequests.FulfillAsync(new {
    upload_url = "<UPLOAD_URL>",
    file = "./evidence.pdf",
});

POST/upload_requests/lookup

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, file_id identifies the file Inttegro created.

Request body

Name
id
Type
string
Required
required
Description
Upload-request ID to retrieve.

Response

Returns the upload request and its latest attempt, when one exists. The response does not include upload_url; retain that URL only for as long as the intended uploader needs it.

Request

POST/upload_requests/lookup

curl https://api.inttegro.com/upload_requests/lookup \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"id":"uplreq_1gK9pQ4vL8mN2sT5wX7yZ0"}'

SDK versionv8.2.0

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",
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

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
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.upload_requests.lookup("uplreq_1gK9pQ4vL8mN2sT5wX7yZ0")

SDK versionv5.3.0

<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->uploadRequests->lookup("uplreq_1gK9pQ4vL8mN2sT5wX7yZ0");

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.upload_requests.lookup(id: "uplreq_1gK9pQ4vL8mN2sT5wX7yZ0")

SDK versionv5.2.0

import com.inttegro.Client;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var result = client.uploadRequests().lookup("uplreq_1gK9pQ4vL8mN2sT5wX7yZ0");
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.UploadRequests.LookupAsync("uplreq_1gK9pQ4vL8mN2sT5wX7yZ0");

POST/upload_requests/review

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
attempt_id
Type
string
Description
Attempt ID to review. Supply exactly one of attempt_id or attempt_ordinal.
Name
attempt_ordinal
Type
integer
Description
One-based attempt number to review. Supply exactly one of attempt_id or attempt_ordinal.
Name
decision
Type
string
Required
required
Description
Review decision: approved or rejected.
Name
id
Type
string
Required
required
Description
Upload-request ID that owns the attempt.
Name
public_message
Type
string
Description
Optional explanation suitable for showing to the uploader.
reasonsobjectOptional structured reasons for the decision.Click or tap to expand
- Name
  code
  Type
  string
  Description
  Required stable reason code.
- Name
  message
  Type
  string
  Description
  Required customer-safe explanation.
- Name
  param
  Type
  string
  Description
  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 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

POST/upload_requests/review

curl https://api.inttegro.com/upload_requests/review \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Idempotency-Key: review-upload-attempt-001" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "uplreq_1gK9pQ4vL8mN2sT5wX7yZ0",
    "attempt_ordinal": 1,
    "decision": "rejected",
    "reasons": [{
      "code": "document_unreadable",
      "message": "The document is too blurry to read."
    }],
    "public_message": "Please upload a clearer copy."
  }'

SDK versionv8.2.0

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",
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  params := inttegro.UploadRequestReviewParams{
    ID: "uplreq_1gK9pQ4vL8mN2sT5wX7yZ0",
    AttemptOrdinal: 1,
    Decision: string(inttegro.UploadReviewDecisionRejected),
    Reasons: []inttegro.UploadRequestReviewReason{
      {
        Code: "document_unreadable",
        Message: "The document is too blurry to read.",
      },
    },
    PublicMessage: "Please upload a clearer copy.",
  }
  result, err := client.UploadRequests.Review(ctx, params, inttegro.WithIdempotencyKey("review-upload-attempt-001"))
  if err != nil {
    log.Fatal(err)
  }
  _ = result
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.upload_requests.review(inttegro.upload_requests.ReviewByOrdinalRequest(
  id="uplreq_1gK9pQ4vL8mN2sT5wX7yZ0",
  attempt_ordinal=1,
  decision=inttegro.UploadReviewDecision.REJECTED,
  reasons=[
    inttegro.upload_requests.ReviewReason(
      code="document_unreadable",
      message="The document is too blurry to read.",
    ),
  ],
  public_message="Please upload a clearer copy.",
),
    idempotency_key="review-upload-attempt-001")

SDK versionv5.3.0

<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->uploadRequests->review([
  'id' => 'uplreq_1gK9pQ4vL8mN2sT5wX7yZ0',
  'attempt_ordinal' => 1,
  'decision' => \Inttegro\UploadReviewDecision::Rejected,
  'reasons' => [
    [
      'code' => 'document_unreadable',
      'message' => 'The document is too blurry to read.',
    ],
  ],
  'public_message' => 'Please upload a clearer copy.',
], [
    'idempotency_key' => "review-upload-attempt-001",
]);

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.upload_requests.review(
  id: "uplreq_1gK9pQ4vL8mN2sT5wX7yZ0",
  attempt_ordinal: 1,
  decision: Inttegro::UploadReviewDecision::REJECTED,
  reasons: [
    {
      code: "document_unreadable",
      message: "The document is too blurry to read.",
    },
  ],
  public_message: "Please upload a clearer copy.",
  idempotency_key: "review-upload-attempt-001"
)

SDK versionv5.2.0

import com.inttegro.Client;
import com.inttegro.files.ReviewUploadRequestAttemptByOrdinalParams;
import com.inttegro.files.UploadRequestReviewDecision;
import java.util.List;
import com.inttegro.files.UploadRequestReviewReason;
import com.inttegro.RequestOptions;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = ReviewUploadRequestAttemptByOrdinalParams.builder()
      .id("uplreq_1gK9pQ4vL8mN2sT5wX7yZ0")
      .attemptOrdinal(1L)
      .decision(UploadRequestReviewDecision.REJECTED)
      .reasons(List.of(
          UploadRequestReviewReason.builder()
            .code("document_unreadable")
            .message("The document is too blurry to read.")
            .build()
        ))
      .publicMessage("Please upload a clearer copy.")
      .build();
    var result = client.uploadRequests().review(params, RequestOptions.withIdempotencyKey("review-upload-attempt-001"));
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.UploadRequests.ReviewAsync(new Inttegro.ReviewUploadRequestAttemptByOrdinalRequest {
  Id = "uplreq_1gK9pQ4vL8mN2sT5wX7yZ0",
  AttemptOrdinal = 1,
  Decision = "rejected",
  Reasons = new List<Inttegro.UploadRequestReviewReason> {
    new Inttegro.UploadRequestReviewReason {
      Code = "document_unreadable",
      Message = "The document is too blurry to read.",
    },
  },
  PublicMessage = "Please upload a clearer copy.",
}, "review-upload-attempt-001");

POST/upload_requests/page

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
page_number
Type
integer
Description
Page number to retrieve. Defaults to 1.
Name
page_size
Type
integer
Description
Requested number of upload requests per page. Defaults to 25 and is capped at 256.
Name
purpose
Type
string
Description
Optional purpose filter.
resourceobjectOptional resource filter.Click or tap to expand
- Name
  id
  Type
  string
  Description
  Resource ID.
- Name
  name
  Type
  string
  Description
  Resource name when available.
- Name
  type
  Type
  string
  Description
  Resource type.
Name
status
Type
string
Description
Optional status filter: pending, uploading, fulfilled, expired, canceled, or failed.

Response

Returns a page with upload_requests, 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 upload_requests: [] and size: 0.

Request

POST/upload_requests/page

curl https://api.inttegro.com/upload_requests/page \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"purpose":"support_document","status":"pending","page_number":1,"page_size":25}'

SDK versionv8.2.0

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,
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  params := inttegro.UploadRequestPageParams{
    Purpose: "support_document",
    Status: "pending",
    PageNumber: 1,
    PageSize: 25,
  }
  result, err := client.UploadRequests.Page(ctx, params)
  if err != nil {
    log.Fatal(err)
  }
  _ = result
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.upload_requests.page(inttegro.upload_requests.PageRequest(
  purpose="support_document",
  status="pending",
  page_number=1,
  page_size=25,
))

SDK versionv5.3.0

<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->uploadRequests->page([
  'purpose' => 'support_document',
  'status' => 'pending',
  'page_number' => 1,
  'page_size' => 25,
]);

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.upload_requests.page(
  purpose: "support_document",
  status: "pending",
  page_number: 1,
  page_size: 25
)

SDK versionv5.2.0

import com.inttegro.Client;
import com.inttegro.files.UploadRequestPageParams;
import com.inttegro.files.UploadRequestStatus;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = UploadRequestPageParams.builder()
      .purpose("support_document")
      .status(UploadRequestStatus.PENDING)
      .pageNumber(1)
      .pageSize(25)
      .build();
    var result = client.uploadRequests().page(params);
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.UploadRequests.PageAsync(new {
  purpose = "support_document",
  status = "pending",
  page_number = 1,
  page_size = 25,
});

POST/upload_requests/cancel

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_byobjectOptional actor canceling the request.Click or tap to expand
- Name
  email
  Type
  string
  Description
  Actor email when available.
- Name
  id
  Type
  string
  Description
  Actor ID when available.
- Name
  name
  Type
  string
  Description
  Actor display name when available.
- Name
  type
  Type
  string
  Description
  Actor type.
Name
id
Type
string
Required
required
Description
Upload-request ID to cancel.

Response

Returns the request with status set to canceled. Use a stable idempotency key when retrying the cancellation.

Request

POST/upload_requests/cancel

curl https://api.inttegro.com/upload_requests/cancel \
  -H "Authorization: Bearer $INTTEGRO_API_KEY" \
  -H "Idempotency-Key: cancel-upload-request-001" \
  -H "Content-Type: application/json" \
  -d '{
    "id": "uplreq_1gK9pQ4vL8mN2sT5wX7yZ0",
    "canceled_by": { "type": "user", "id": "usr_support_123" }
  }'

SDK versionv8.2.0

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",
})

SDK versionv4.4.0

package main

import (
  "context"
  "log"
  "os"

  inttegro "github.com/zebodotdev/inttegro-sdk-go/v4"
)

func main() {
  ctx := context.Background()
  client := inttegro.NewClient(os.Getenv("INTTEGRO_API_KEY"))

  params := inttegro.UploadRequestCancelParams{
    ID: "uplreq_1gK9pQ4vL8mN2sT5wX7yZ0",
    CanceledBy: inttegro.FileActor{
      Type: "user",
      ID: "usr_support_123",
    },
  }
  result, err := client.UploadRequests.Cancel(ctx, params, inttegro.WithIdempotencyKey("cancel-upload-request-001"))
  if err != nil {
    log.Fatal(err)
  }
  _ = result
}

SDK versionv6.2.0

import os
import inttegro

client = inttegro.InttegroClient(api_key=os.environ["INTTEGRO_API_KEY"])
result = client.upload_requests.cancel(inttegro.upload_requests.CancelRequest(
  id="uplreq_1gK9pQ4vL8mN2sT5wX7yZ0",
  canceled_by=inttegro.FileActorInput(
    type="user",
    id="usr_support_123",
  ),
),
    idempotency_key="cancel-upload-request-001")

SDK versionv5.3.0

<?php

use Inttegro\Client;

$client = new Client($_ENV['INTTEGRO_API_KEY']);
$result = $client->uploadRequests->cancel([
  'id' => 'uplreq_1gK9pQ4vL8mN2sT5wX7yZ0',
  'canceled_by' => [
    'type' => 'user',
    'id' => 'usr_support_123',
  ],
]);

SDK versionv4.3.0

require "inttegro"

client = Inttegro::Client.new(api_key: ENV.fetch("INTTEGRO_API_KEY"))
result = client.upload_requests.cancel(
  id: "uplreq_1gK9pQ4vL8mN2sT5wX7yZ0",
  canceled_by: {
    type: "user",
    id: "usr_support_123",
  },
  idempotency_key: "cancel-upload-request-001"
)

SDK versionv5.2.0

import com.inttegro.Client;
import com.inttegro.files.UploadRequestCancelParams;
import com.inttegro.files.Actor;
import com.inttegro.RequestOptions;

public class Example {
  public static void main(String[] args) throws Exception {
    var client = new Client(System.getenv("INTTEGRO_API_KEY"));
    var params = UploadRequestCancelParams.builder()
      .id("uplreq_1gK9pQ4vL8mN2sT5wX7yZ0")
      .canceledBy(Actor.builder()
          .type("user")
          .id("usr_support_123")
          .build())
      .build();
    var result = client.uploadRequests().cancel(params, RequestOptions.withIdempotencyKey("cancel-upload-request-001"));
  }
}

SDK versionv6.2.0

using Inttegro;

using var inttegro = new InttegroClient(
    Environment.GetEnvironmentVariable("INTTEGRO_API_KEY")!
);
var result = await inttegro.UploadRequests.CancelAsync(new {
  id = "uplreq_1gK9pQ4vL8mN2sT5wX7yZ0",
  canceled_by = new {
    type = "user",
    id = "usr_support_123",
  },
}, "cancel-upload-request-001");

The upload request object

Properties​

Create an upload request

Request body​

Upload limits​

Response​

Request

Response

Fulfill an upload request

Included in the upload URL​

Request body​

Response​

Request

Lookup an upload request

Request body​

Response​

Request

Review an upload attempt

Request body​

Response​

Request

Page upload requests

Request body​

Response​

Request

Cancel an upload request

Request body​

Response​

Request

Properties

Request body

Upload limits

Response

Included in the upload URL

Request body

Response

Request body

Response

Request body

Response

Request body

Response

Request body

Response