Create file

Create a new file.

POST /core/files

Create file

cURL

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

201

File Created

{
  "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:39Z"
    }
  }
}

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 our 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:

Node.js

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

201

application/json

File created.

file · object · required

Show child attributes

errors · object

Additional contextual errors that occurred while processing the request.

Show child attributes