Changed operations

• Retrieve case's documents (GET /v1/cases/{id}/documents)
  • ✨ [Added] property document_type_key to data[].check in response body

Introducing key property for Template to improve DX and consistency with other support objects (Custom properties, Document type, ...) that uses human-readable key as identifier.

Changed operations

• List all cases (GET /v1/cases)
  • ⚠️ [Added] deprecated status to data[].template_id in response body
  • ✨ [Added] required property template to data[] in response body
• Create a case (POST /v1/cases), Update a case (PATCH /v1/cases/{id})
  • ⚠️ [Added] deprecated status to template_id in request body
  • ✨ [Added] property template_key in request body
  • ⚠️ [Added] deprecated status to template_id in response body
  • ✨ [Added] required property template in response body
• Retrieve a case (GET /v1/cases/{id})
  • ⚠️ [Added] deprecated status to template_id in response body
  • ✨ [Added] required property template in response body
• List all activities (GET /v1/activities)
  • ✨ [Added] required property key to data[].context.template in response body
• List all templates (GET /v1/templates)
  • ✨ [Added] query parameter key
  • ✨ [Added] required property key to data[] in response body
• Retrieve a template (GET /v1/templates/{id})
  • ✨ [Added] required property key in response body
• Run a template (POST /v1/templates/run)
  • ⚠️ [Added] deprecated status to template_id in request body
  • ✨ [Added] property template_key in request body

ℹ️

See below the list of upcoming changes

Changed operations

• Retrieve a case (GET /v1/cases/{id})
  • ✨ [Added] property document_type_key to individuals[].checks[] in response body
  • ✨ [Added] property document_type_key to companies[].checks[] in response body
• Create a company (POST /v1/companies), Retrieve a company (GET /v1/companies/{id}), Update a company (PATCH /v1/companies/{id}), Set company relevance (POST /v1/companies/{id}/set-relevant), Create an individual (POST /v1/individuals), Retrieve an individual (GET /v1/individuals/{id}), Update an individual (PATCH /v1/individuals/{id}), Set individual relevance (POST /v1/individuals/{id}/set-relevant)
  • ✨ [Added] property document_type_key to checks[] in response body
• List all checks (GET /v1/checks)
  • ✨ [Added] property document_type_key to data[] in response body
• Create a Document check (POST /v1/checks/document), Add files (POST /v1/checks/document/{id}/add_files), Retrieve a Document check (GET /v1/checks/document/{id}), Force review (POST /v1/checks/document/{id}/force_review), Review a Document check (PATCH /v1/checks/document/{id}/review)
  • ⚠️ [Added] deprecated status to data.settings.custom_document_type in response body: true
  • ✨ [Added] required property document_type_key to data.settings in response body
• List all custom document types (GET /v1/custom_document_types)
  • ⚠️ [Added] deprecated status, use List all document types (GET /v1/document_types) instead
• List all document types (GET /v1/document_types)
  • ✨ [Added] operation GET /v1/document_types
• Create an ID Verification check (POST /v1/checks/id_verification), Retrieve an ID Verification check (GET /v1/checks/id_verification/{id}), Review an ID Verification check (PATCH /v1/checks/id_verification/{id}/review), Refresh an ID Verification check url (POST /v1/checks/id_verification/{id}/refresh_url)
  • ♻️ Use specific component for each data.vendor depending on the name
  • ✨ [Added] required property data.vendor.sdk_token for onfido

Changed components schemas

• CaseWebhook
  • ✨ [Added] property document_type_key to case.individuals[].checks[]
  • ✨ [Added] property document_type_key to case.companies[].checks[]
• IndividualWebhook
  • ✨ [Added] property document_type_key to individual.checks[]
• CompanyWebhook
  • ✨ [Added] property document_type_key to company.checks[]
• DocumentCheckWebhook
  • ⚠️ [Added] deprecated status to check.data.settings.custom_document_type: true
  • ✨ [Added] required property document_type_key to check.data.settings
• IdVerificationCheckWebhook
  • ♻️ Use specific component for each check.data.vendor depending on the name
  • ✨ [Added] required property check.data.vendor.sdk_token for onfido
• CheckDeletedWebhook
  • ✨ [Added] property document_type_key to check

Upcoming changes

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

• Response body of Retrieve a case (GET /v1/cases/{id})
• Response body of List all checks (GET /v1/checks)
• Response body of Create a company (POST /v1/companies), Retrieve a company (GET /v1/companies/{id}), Update a company (PATCH /v1/companies/{id}), Set company relevance (POST /v1/companies/{id}/set-relevant)
• Response body of Create an individual (POST /v1/individuals), Retrieve an individual (GET /v1/individuals/{id}), Update an individual (PATCH /v1/individuals/{id}), Set individual relevance (POST /v1/individuals/{id}/set-relevant)

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

• Response body of Create a Document check (POST /v1/checks/document), Add files (POST /v1/checks/document/{id}/add_files), Retrieve a Document check (GET /v1/checks/document/{id}), Force review (POST /v1/checks/document/{id}/force_review), Review a Document check (PATCH /v1/checks/document/{id}/review)
• Payload of DocumentCheckWebhook

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

• Create a Document check (POST /v1/checks/document), Add files (POST /v1/checks/document/{id}/add_files), Retrieve a Document check (GET /v1/checks/document/{id}), Force review (POST /v1/checks/document/{id}/force_review), Review a Document check (PATCH /v1/checks/document/{id}/review)
• DocumentCheckWebhook

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

• Request body of Create a case (POST /v1/cases)
• Request body of Update a case (PATCH /v1/cases)

Paths

• Create an AML check (POST /v1/checks/aml)
  • ✨ [Added] property exact_match to settings in request body
  • ✨ [Added] required property exact_match to data.settings in response body
• Retrieve an AML check (GET /v1/checks/aml/{id}), Review AML hits (PATCH /v1/checks/aml/{id}/hits/review), Review an AML check (PATCH /v1/checks/aml/{id}/review), Update an AML check monitoring (PATCH /v1/checks/aml/{id}/monitoring)
  • ✨ [Added] required property exact_match to data.settings in response body

Components schemas

• AmlCheckWebhook
  • ✨ [Added] required property exact_match to check.data.settings

Paths

• List all activities (GET /v1/activities)
  • ✨ [Added] possible values in query parameter type: "user__updated_review__case"
  • ✨ [Added] possible values of data[].type in response body: "user__updated_review__case"

Paths

• Retrieve a case (GET /v1/cases/{id})
  • ✨ [Added] possible values of individuals[].checks[].type in response body: "online_reputation"
  • ✨ [Added] possible values of .checks[].type in response body: "online_reputation"
• Create a company (POST /v1/companies), Retrieve a company (GET /v1/companies/{id}), Update a company (PATCH /v1/companies/{id}), Set company relevance (POST /v1/companies/{id}/set-relevant), Create an individual (POST /v1/individuals), Retrieve an individual (GET /v1/individuals/{id}), Update an individual (PATCH /v1/individuals/{id}), Set individual relevance (POST /v1/individuals/{id}/set-relevant)
  • ✨ [Added] possible values of .checks[].type in response body: "online_reputation"
• List all checks (GET /v1/checks)
  • ✨ [Added] possible values in query parameter type: "online_reputation"
  • ✨ [Added] possible values of .checks[].type in response body: "online_reputation"
• List all activities (GET /v1/activities)
  • ✨ [Added] possible values of data[].context.check.type in response body: "online_reputation"
• Create an Online Reputation check (POST /v1/checks/online_reputation)
  • ✨ [Added] operation POST /v1/checks/online_reputation
• Retrieve an Online Reputation check (GET /v1/checks/online_reputation/{id})
  • ✨ [Added] operation GET /v1/checks/online_reputation/{id}
• Review an Online Reputation check (PATCH /v1/checks/online_reputation/{id}/review)
  • ✨ [Added] operation PATCH /v1/checks/online_reputation/{id}/review

Components schemas

• CaseWebhook
  • ✨ [Added] possible values of case.individuals[].checks[].type: "online_reputation"
  • ✨ [Added] possible values of case.companies[].checks[].type: "online_reputation"
• IndividualWebhook
  • ✨ [Added] possible values of individual.checks[].type: "online_reputation"
• CompanyWebhook
  • ✨ [Added] possible values of company.checks[].type: "online_reputation"
• CheckDeletedWebhook
  • ✨ [Added] possible values of check.type: "online_reputation"
• OnlineReputationCheckDataVendorDTO, OnlineReputationSourceDTO, OnlineReputationCheckDataCompanyDTO, OnlineReputationCheckDataInformationDTO, OnlineReputationCheckDataDTO
  • ✨ [Added]

Paths

• List all checks (GET /v1/checks)
  • ✨ [Added] possible values in query parameter type: "electronic_signature"
  • ✨ [Added] possible values of .checks[].type in response body: "electronic_signature"
• List all activities (GET /v1/activities)
  • ✨ [Added] possible values of data[].context.check.type in response body: "electronic_signature"
• Create an Electronic Signature check (POST /v1/checks/electronic_signature)
  • ✨ [Added] operation POST /v1/checks/electronic_signature
• Retrieve an Electronic Signature check (GET /v1/checks/electronic_signature/{id})
  • ✨ [Added] operation GET /v1/checks/electronic_signature/{id}
• Review an Electronic Signature check (PATCH /v1/checks/electronic_signature/{id}/review)
  • ✨ [Added] operation PATCH /v1/checks/electronic_signature/{id}/review

Components schemas

• CaseWebhook
  • ✨ [Added] possible values of case.individuals[].checks[].type: "electronic_signature"
  • ✨ [Added] possible values of case.companies[].checks[].type: "electronic_signature"
• IndividualWebhook
  • ✨ [Added] possible values of individual.checks[].type: "electronic_signature"
• CompanyWebhook
  • ✨ [Added] possible values of company.checks[].type: "electronic_signature"
• CheckDeletedWebhook
  • ✨ [Added] possible values of check.type: "electronic_signature"
• ElectronicSignatureCheckSettingsCreate, ElectronicSignatureCheckDataSettings, ElectronicSignatureCheckDataVendor, ElectronicSignatureCheckDataInformation, ElectronicSignatureCheckData, ElectronicSignatureCheckWebhook
  • ✨ [Added]

Paths

• List all activities (GET /v1/activities)
  • ✨ [Added] possible values in query parameter type: "system__updated_risk__case"
  • ✨ [Added] possible values in query parameter type: "system__added_tags__case"
  • ✨ [Added] possible values in query parameter type: "system__added__case_control"
  • ✨ [Added] possible values in query parameter type: "system__removed__case_control"
  • ✨ [Added] possible values of data[].type in response body: "system__updated_risk__case"
  • ✨ [Added] possible values of data[].type in response body: "system__added_tags__case"
  • ✨ [Added] possible values of data[].type in response body: "system__added__case_control"
  • ✨ [Added] possible values of data[].type in response body: "system__removed__case_control"

Paths

• List all activities (GET /v1/activities)
  • ✨ [Added] possible values in query parameter type: "template__added__case_control"
  • ✨ [Added] possible values in query parameter type: "template__removed__case_control"
  • ✨ [Added] possible values in query parameter type: "user__mark_as_completed__case_control"
  • ✨ [Added] possible values in query parameter type: "system__mark_as_completed__case_control"
  • ✨ [Added] possible values in query parameter type: "user__mark_as_uncompleted__case_control"
  • ✨ [Added] possible values in query parameter type: "system__mark_as_uncompleted__case_control"
  • ✨ [Added] possible values of data[].type in response body: "template__added__case_control"
  • ✨ [Added] possible values of data[].type in response body: "template__removed__case_control"
  • ✨ [Added] possible values of data[].type in response body: "user__mark_as_completed__case_control"
  • ✨ [Added] possible values of data[].type in response body: "system__mark_as_completed__case_control"
  • ✨ [Added] possible values of data[].type in response body: "user__mark_as_uncompleted__case_control"
  • ✨ [Added] possible values of data[].type in response body: "system__mark_as_uncompleted__case_control"

Paths

• Create a Document check (POST /v1/checks/document)
  • ✨ [Added] property fraud_analysis to settings in request body

Components schemas

• DocumentCheckSettingsCreate
  • ✨ [Added] property fraud_analysis