Skip to main content
Creates a file upload object and returns an upload URL. This is the first step in the file upload lifecycle.

Method

Parameters

string
How the file is being sent. Use multi_part for files larger than 20MB. Use external_url for files that are temporarily hosted publicly elsewhere. Default is single_part.Options: "single_part" | "multi_part" | "external_url"
string
Name of the file to be created. Required when mode is multi_part. Otherwise optional, and used to override the filename. Must include an extension, or have one inferred from the content_type parameter.
string
MIME type of the file to be created. Recommended when sending the file in multiple parts. Must match the content type of the file that’s sent, and the extension of the filename parameter if any.Examples: "application/pdf", "image/png", "video/mp4"
number
When mode is multi_part, the number of parts you are uploading. This must match the number of parts as well as the final part_number you send.
string
When mode is external_url, provide the HTTPS URL of a publicly accessible file to import into your workspace.

Response

Returns a FileUpload object with:
string
Always "file_upload"
string
Unique identifier for the file upload. Use this in subsequent send and complete calls.
string
Current status of the file upload: "pending", "uploaded", "expired", or "failed"
string
URL to use for sending file data. Present when status is "pending".
string
URL for completing a multi-part upload.
string
ISO 8601 timestamp when the upload URL expires.
object
For multi-part uploads, contains total and sent part counts.

Examples

Single-part upload

For files under 20MB:

Multi-part upload

For files larger than 20MB, split into parts:

External URL import

Import a file from an external URL: