Product updates
API Reference

Upcoming changes

Scheduled for October 28th, 2025

ℹī¸

This changes were announced in the changelog of 2025-07-28

The following changes (🆕 New Behaviors) are schedule to take effect on October 28th, 2025. Please review and update your integrations accordingly to ensure continued functionality.

1. Changes to subtype for Document checks

We are standardizing the subtype format for Document checks across all API responses and webhook payloads to improve consistency and simplify integration logic.

Are you impacted ?

You are impacted only if you parse the subtype of Document check to extract the key or the UUID of the document type and have special business logic depending on this key or the UUID.

Current Behavior

The subtype format currently varies based on document type:

  • for "default" document types, it follows the format "document_type:{key}"
  • for "custom" document types, it follows the format"custom_document_type:{uuid}"

🆕 New Behavior

The subtype will use the standardized format for all document types: "document_type:{key}"

The new format will always be of the form "document_type:{key}" for all document types.

If you were relying on the format of the subtype and extracting the key or the UUID to have some conditional business logic, the new property document_type_key or settings.document_type_key (depending on the operations) will allow you to keep the same logic. Additionally, since the document type key can be re-used across Dotfile workspaces, it will be simpler to keep the share the same logic in your integration across workspaces.

🛠ī¸ Migration guide

If your integration parses the subtype field, use the new document_type_key property instead:

Before:

// Parsing subtype to extract key/UUID
const subtype = check.subtype; // "document_type:bank_details" or "custom_document_type:f9a2ae0f-6bd0-4fd7-88eb-737d59034ea6"
const keyOrUuid = subtype.split(':')[1];

After:

// Use the dedicated property
const documentTypeKey = check.document_type_key; // "bank_details" or "my_document_type"
// No need to parse or check format

Affected API Endpoints with Check objects

Migration: Use check.document_type_key instead of parsing check.subtype

Affected Webhook Payloads with Check objects

  • Payload of CaseWebhook, IndividualWebhook, CompanyWebhook, CheckDeletedWebhook

Migration: Use check.document_type_key instead of parsing check.subtype

Affected Document check specific API endpoints and webhooks

Migration: Use data.settings.document_type_key instead of parsing check.subtype

The new property data.settings.document_type_key have been added that will always be set to the key of the document type ("default" or "custom").

2. Changes on data.settings.document_type and removal of data.settings.custom_document_type for Document checks

The property data.settings.document_type_key have been added to replace data.settings.document_type and is always set for all document types.

The property data.settings.document_type will be changed: Instead of containing a string or null, it will always contains the document type object (same as the current value of data.settings.custom_document_type but for all document types).

Are you impacted ?

You are impacted only if you are using the data.settings.document_type or some properties of data.settings.custom_document_type for Document checks.

Current Behavior

  • data.settings.document_type set to the document type key for "default" document types, set to null for "custom" document types
  • data.settings.custom_document_type set to null for "default" document types, set with the object for custom document types

🆕 New Behavior

  • data.settings.document_type will be an object always set with the same shape as the current data.settings.custom_document_type
  • data.settings.custom_document_type will be removed

🛠ī¸ Migration Guide

Replace data.settings.document_type with data.settings.document_type_key, which provides consistent behavior for all document types.

Before:

const { settings } = check.data;

let key; // string
let documentType; // Object or null

if (settings.document_type !== null) {
  // Handle default document type
  key = settings.document_type;
  documentType = null;
}
if (settings.custom_document_type !== null) {
  // Handle custom document type
  key = settings.custom_document_type.key;
  documentType = settings.custom_document_type;
}

// Do something with the key or documentType

After:

const { settings } = check.data;

const key = settings.document_type_key; // String
// Do something with the key

// If you need information on the document type object, also do the following:

let documentType; // Object, always set after the changes take effect

if (settings.document_type) {
  if (typeof settings.document_type === "object") {
    // Be ready for the new document_type
    documentType = settings.document_type;
  }

  // Until the change takes effect, document_type can still be a null or a string and in this case it should be ignored

} else if (settings.custom_document_type) {
  // Until the change takes effect, custom_document_type is still set for "custom" document type
  documentType = settings.custom_document_type;
}

// Do something with the documentType

Affected endpoints and webhooks

3. Removal of List all custom document types (GET /v1/custom_document_types)

The List all custom document types (GET /v1/custom_document_types) endpoint is deprecated and will be removed.

Are you impacted ?

You are impacted only if you are using the List all custom document types (GET /v1/custom_document_types) operation.

Migration Guide

Use List all document types (GET /v1/document_types) instead, which returns all available document types without distinguishing between "default" and "custom" types.

4. Case status Request Body Changes

The status field in case request bodies will no longer accept "approved" and "rejected" values.

Are you impacted

You are impacted only if you are using the Create a case (POST /v1/cases) or Update a case (PATCH /v1/cases) endpoints with "approved" or "rejected" values in request body for the status.

Current Behavior

  • status field in case request bodies accepts the values "draft", "open", "approved" or "rejected".

🆕 New Behavior

  • status field in case request bodies will continue to accept the values "draft"or"open".
  • Values "approved"or"rejected" will returns an HTTP response 400 BAD REQUEST

🛠ī¸ Migration Guide

Create cases without a status, then use Create a case review (POST /v1/cases/{id}/reviews) to set the desired status.

To update the status of an existing case to "approved", "rejected" or "closed", use the Create a case review (POST /v1/cases/{id}/reviews).

Before:

// Creating case with status (deprecated)
const response = await fetch('/v1/cases', {
  method: 'POST',
  body: JSON.stringify({
    status: 'approved',
    // other case data...
  }),
  // headers and other options...
});

After:

// Create case without status, then review
const caseResponse = await fetch('/v1/cases', {
  method: 'POST',
  body: JSON.stringify({
    // case data without status...
  }),
  // headers and other options...
});

const caseId = caseResponse.id;

// Set status via review
await fetch(`/v1/cases/${caseId}/reviews`, {
  method: 'POST',
  body: JSON.stringify({
    status: 'approved',
    // Other review options
  }),
  // headers and other options...
});

Affected endpoints