The Fraud Database Check Object

A fraud_database check screens an entity against a shared industry fraud database to establish
whether it has been filed for fraudulent activity by a member organisation.

It targets an individual or a company, and resolves synchronously: the create response already
carries the result.

Product documentation: Fraud database.

Prerequisites

Workspace enablement. The check is disabled by default. A create request against a workspace
where it has not been enabled returns 400. Contact [email protected] or your customer success
manager to enable it.

Country. address.country on the target entity must be GB. Any other value, or no address,
returns 400.

Entity fields. The target must carry the fields the search is performed on:

Target	Required fields
individual	`first_name`, `last_name`, `birth_date`
company	`name`, `registration_number`

Missing fields are named in the 400. Set them with
Update an individual or Update a company.

Create a fraud database check

POST /v1/checks/fraud-database — the path segment is hyphenated, not fraud_database. See
Create a fraud database check.

curl -X POST https://api.dotfile.com/v1/checks/fraud-database \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"individual_id": "4b36ce30-3d90-421a-b2d9-a046e5e4cfef"}'

curl -X POST https://api.dotfile.com/v1/checks/fraud-database \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"company_id": "5c47df41-4ea1-532b-9157-b159f6e5df00"}'

Field	Type	Required	Description
`individual_id`	`uuid`	one of the two	the individual to screen
`company_id`	`uuid`	one of the two	the company to screen
`settings`	object	no	per-check override of the values below

Exactly one of individual_id and company_id is accepted. The generated schema lists both as
required, which is an artefact of the two request shapes being combined into a single model;
validation enforces one target.

`settings` field	Type	Falls back to	Description
`vendor`	enum	`cifas`	the only accepted value
`automatic_approval`	boolean	`true`	resolves a clean search to `approved` without human review
`automatic_rejection`	boolean	`false`	see below

Omitted settings resolve from the workspace configuration, then from the defaults above. 400 is
also returned when the workspace check limit is reached.

Status

Search outcome	Settings	Resulting `status`
no filing found	`automatic_approval: true`	`approved`
no filing found	`automatic_approval: false`	`need_review`
one or more filings found	any	`need_review`

No code path rejects a fraud_database check automatically, regardless of automatic_rejection.
Every match reaches need_review.

Response

Field	Description
`data.result`	`approved`, `rejected` or `error`
`data.information`	the identity that was searched: `entity_type`, `first_name`, `last_name`, `birth_date`, `email`, `phone_number`, `company_name`, `company_number`, `vat_number`, `address`
`data.vendor.name`	the provider, `cifas`
`data.vendor.search_reference`	the provider's identifier for this search
`data.ai_analysis.interpretation`	plain-language reading of the result, or `null`
`data.settings`	the settings the check ran with
`data.review`	`comment`, `reviewed_at`, `reviewer_type`, `user`

The matched filings are not exposed over the API. The response reports that a review is required
and what the search was performed on; the filings, their types and their reasons are available in
the console.

subtype is always null on a fraud_database check.

Review

PATCH /v1/checks/fraud-database/{id}/review —
Review a fraud database check.

curl -X PATCH https://api.dotfile.com/v1/checks/fraud-database/$CHECK_ID/review \
  -H "X-DOTFILE-API-KEY: $DOTFILE_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "reject", "comment": "Filing confirmed against internal records"}'

Field	Type	Required	Description
`action`	`approve` \| `reject`	yes	the decision
`comment`	string	no	recorded on `data.review`
`override`	boolean	no	permits changing a check already in `approved` or `rejected`

data.review.reviewer_type is set to api.

Retrieval

Retrieve a fraud database check returns the full object, data
included.

Retrieve a case and List checks return the check envelope
only, without data.

The Check.Started, Check.Approved, Check.Rejected and Check.ReviewNeeded
webhook events carry the complete check object.

The Check object — the shared envelope, statuses and review mechanics
AML screening — the other check that screens an entity against external lists
Templates — creating the check from a verification policy rather than per call