Documents API

Upload Document

Uploads a document.

POST

https://api.basistheory.com/documents

Permissions

documents:create

Request

cURL

curl --request POST \
  --url https://api.basistheory.com/documents \
  --header 'BT-API-KEY: <PRIVATE_API_KEY>' \
  --header 'Content-Type: multipart/form-data' \
  --form 'request={"metadata": {"name":"value"}}' \
  --form document=@/path/to/file.pdf

Node

C#

Python

Request Parameters

Parameter	Required	Type	Default	Description
request	false	string	null	JSON string containing request metadata. Must be provided as a form field.
document	true	file	null	The document file to upload. Must be provided as a multipart form field with file content.

The request parameter accepts a JSON string with the following properties:

Property	Required	Type	Default	Description
metadata	false	object	{}	Key-value pairs of metadata to associate with the document

Response

Returns a document information if the document was created successfully. Returns an error if there were validation errors, or the document failed to create.

{
  "id": "a05d2a09-b4f4-4ce7-9743-ab18d3aa8a43",
  "tenant_id": "064bbc70-204b-4ef1-a757-ec0878be5945",
  "metadata": {
    "name": "value"
  },
  "content_type": "application/pdf",
  "created_by": "f0f504e5-79c2-40a6-aad3-dbee7a692828",
  "created_at": "2025-07-18T14:41:08.254248+00:00"
}

Get Document Metadata

GET

https://api.basistheory.com/documents/{id}

Permissions

documents:read

Request

cURL

curl --request GET \
  --url https://api.basistheory.com/documents/79602dc6-ac0c-4fe0-9903-62fd88f1303a \
  --header 'BT-API-KEY: <PRIVATE_API_KEY>'

Node

await client.documents.get("c2995d93-600a-44a2-b6f1-2c25e46603a9");

C#

await client.Documents.GetAsync("c2995d93-600a-44a2-b6f1-2c25e46603a9");

Python

client.documents.get(
    id="c2995d93-600a-44a2-b6f1-2c25e46603a9"
)

URI Parameters

Parameter	Required	Type	Default	Description
id	true	uuid	null	The ID of the document

Response

Returns a document with the id provided. Returns an error if the document could not be retrieved.

{
  "id": "79602dc6-ac0c-4fe0-9903-62fd88f1303a",
  "tenant_id": "6f5ea0c2-f1a6-46c2-ba36-8024cecfb2c3",
  "metadata": {
    "name": "value"
  },
  "content_type": "application/pdf",
  "created_by": "0bd433d3-e635-4a81-8263-bb13dcacfc79",
  "created_at": "2025-07-18T14:41:08.254248+00:00"
}

Download Document

GET

https://api.basistheory.com/documents/{id}/data

Permissions

documents:reveal

Request

cURL

curl --request GET \
  --url https://api.basistheory.com/documents/79602dc6-ac0c-4fe0-9903-62fd88f1303a/data \
  --header 'BT-API-KEY: <PRIVATE_API_KEY>'

Node

await client.documents.data.get("c2995d93-600a-44a2-b6f1-2c25e46603a9");

C#

await client.Documents.Data.GetAsync("c2995d93-600a-44a2-b6f1-2c25e46603a9");

Python

client.documents.data.get(
    id="c2995d93-600a-44a2-b6f1-2c25e46603a9"
)

Response

Returns the raw, unencrypted binary content of the document file that was previously uploaded.

Delete Document

Deletes a document.

DELETE

https://api.basistheory.com/documents/{id}

Permissions

documents:delete

Request

cURL

curl --request DELETE \
  --url https://api.basistheory.com/documents/79602dc6-ac0c-4fe0-9903-62fd88f1303a \
  --header 'BT-API-KEY: <PRIVATE_API_KEY>'

Node

await client.documents.delete("c2995d93-600a-44a2-b6f1-2c25e46603a9");

C#

await client.Documents.DeleteAsync("c2995d93-600a-44a2-b6f1-2c25e46603a9");

Python

client.documents.delete(
    id="c2995d93-600a-44a2-b6f1-2c25e46603a9"
)

URI Parameters

Parameter	Required	Type	Default	Description
id	true	uuid	null	The ID of the document

Response

Returns 204 No Content if the document was deleted successfully. Returns an error if the document could not be deleted.