Skip to main content
POST
/
core
/
files
Create file
curl --request POST \
  --url https://api.enterprise.sandbox.uphold.com/core/files \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '
{
  "category": "image",
  "contentType": "image/png",
  "metadata": {
    "externalId": 123
  }
}
'
{
  "file": {
    "id": "38cce774-b225-41ed-a9fd-f9c9777a13de",
    "status": "pending",
    "category": "image",
    "contentType": "image/png",
    "upload": {
      "url": "https://example.com/upload",
      "formData": {
        "X-Amz-Algorithm": "AWS4-HMAC-SHA256",
        "X-Amz-Credential": "ASIE4FQORBNQHNQD5CG6/20240801/us-east-1/s3/aws4_request",
        "X-Amz-Date": "20240801T102500Z",
        "X-Amz-Security-Token": "IQoJb3JpZ2luX2VjEIv//////////...JBr6h2HkzH/aFSArQcs=",
        "X-Amz-Signature": "b4da8cf1a59327988a8108c965a4789fc8ba2d20f5bffda076106b2b254def29",
        "Key": "4c13b6f5-987e-43df-bc12-042b58307a80",
        "Policy": "eyJjb25kaXRpb25zIjpbeyJidWN...TA6MjU6MDAuMjAyWiJ9"
      },
      "expiresAt": "2024-03-13T20:20:39.000Z"
    }
  }
}
Uploading a file is a two step process. You start by creating a placeholder for the file and then using the upload details of the response to actually upload the file. Each file has a unique id which is used across the API when you need to reference it. You can optionally include custom entity metadata in the metadata field to store your own business data (e.g., descriptions, related entity IDs, processing metadata). If not provided during creation, you can add it later using Set metadata. Below you will find examples in several programming languages to do the upload:
The following example uses file-type package to determine the content-type of the file.
import { fileTypeFromFile } from 'file-type';
import fs from 'node:fs';

// Function to upload file.
// Takes `file` record from the response and `filePath` which points to the file on disk that needs to be uploaded.
const uploadFile = async (file, filePath) => {
  const { url, formData } =  file.upload;

  // Add form data.
  const form = new FormData();

  for (const [key, value] of Object.entries(formData)) {
    form.append(key, value);
  }

  // Add content type, determined by file-type package.
  // This must match the `contentType` of the file record.
  const { mime } = await fileTypeFromFile(filePath);

  form.append('Content-Type', mime);

  // Add file blob.
  const blob = await fs.openAsBlob(filePath)

  form.append('File', blob);

  const response = await fetch(url, {
    method: 'POST',
    body: form,
  });

  if (!response.ok) {
    throw new Error(`Failed to upload file: ${response.statusText}`);
  }

  console.log('File uploaded!')
};

Authorizations

​
Authorization
string
header
required

OAuth 2.0 authentication.

Body

application/json
​
category
enum<string>
required

The category of the file.

Available options:
document,
image,
video
​
contentType
string
required

The content type of the file.

​
metadata
object

Additional data for the file.

Response

File created.

​
file
object
required
​
errors
object

Additional contextual errors that occurred while processing the request.