# Didit Analytics, Teams and Roles
Source: https://docs.didit.me/academy/analytics-teams-roles

Video transcript: the operator's guide to Didit analytics dashboards, team management, roles and permissions.

<VideoEmbed title="Didit Analytics, Teams and Roles - The Operator's Guide" />

Full transcript of **Didit Analytics, Teams and Roles - The Operator's Guide** - Didit Academy video 9 of 10, 06:37. [Watch on YouTube](https://www.youtube.com/watch?v=sRcOBxjRYag). Each paragraph links to the exact moment in the video.

## What this video covers

[00:04](https://www.youtube.com/watch?v=sRcOBxjRYag\&t=4s) This video covers two things every operator needs once Didit is live. The first is seeing how your account is actually performing and the second is controlling who on your team can do what. So, on the analytic side, if you're running transaction monitoring, Didit turns all the activity into a live dashboard of numbers that you can act on. Then, we'll move over to the team side where you decide who gets to see and change each part of the account. So, let's dive in.

## Where analytics live

[00:36](https://www.youtube.com/watch?v=sRcOBxjRYag\&t=36s) So, the analytics in Didit live in the transactions product. So, we head over to the transactions tab here on the left and we could see at the top we can hit overview, right? So, instead of reading one row at a time, you're reading numbers that you can actually act on. So, if you're only running verifications, you'll spend your time in the sessions list from previous videos, which you can see in the user verifications tab here, or you can see the overview in your dashboard on your home page. You can also add these cards to your home page, but this is

## Date ranges, filters and export

[01:13](https://www.youtube.com/watch?v=sRcOBxjRYag\&t=73s) specifically about your transactions. Now, we can actually change the the date range here. We can filter by tag. We can filter by type, so that's fiat, crypto, KYC, gambling, all of those. And we can actually export the the report here. So, that's just going to give you an Excel export that you can do

## Volume, geography and channel split

[01:31](https://www.youtube.com/watch?v=sRcOBxjRYag\&t=91s) things with. You can put it into Claude. You can create fancy reports to share with your team. So, the first numbers that you can check out here is volume, so how many transactions run over your time window here, and whether that's trending up or down against the period before. So, you can see there's a breakdown here by the country of the user behind each transaction. We've got the split down here between fiat, crypto, and gambling. So, really you could see at a glance where your activity is concentrated and which side

## Rule analytics and the review trend

[02:01](https://www.youtube.com/watch?v=sRcOBxjRYag\&t=121s) of the house it's coming from. Now, we can also see the analytics for our rules. So, you could see which monitoring rules are firing the most and how your approved, declined, and in review mix. So, you see this card right here, this shows your top rules that have been triggered. So, you could see which monitoring rules are firing the most and how your approved, declined, and in review mix is trending over time.

[02:25](https://www.youtube.com/watch?v=sRcOBxjRYag\&t=145s) So, a rising in review line is your early warning that more work is about to

## Customizing your home dashboard

[02:31](https://www.youtube.com/watch?v=sRcOBxjRYag\&t=151s) land on your analysts. So, you can spot risk forming rather than counting it after the fact. So, this is the best place to go to see your analytics on your transactions and for your verifications, we can customize our home page to show the volume of verifications, IP locations, all of this stuff. And if you want to customize that, we can go to edit and we can move around these tabs if we want and we can also add additional tabs from user verifications and business verifications. You can throw in some transaction data as well if you want if you want everything in one dashboard.

[03:08](https://www.youtube.com/watch?v=sRcOBxjRYag\&t=188s) So, let's just switch from measuring to governing and the first thing to

## Organizations

[03:12](https://www.youtube.com/watch?v=sRcOBxjRYag\&t=192s) understand is that everything in Didit lives inside an organization. So, that's the account that holds your billing, your people, and your applications. So, you see this switcher down here, you can jump between organizations here. Now, I only have one organization set up, but you could create a separate organization as well. Now, the account

## Account settings and the audit log

[03:31](https://www.youtube.com/watch?v=sRcOBxjRYag\&t=211s) settings holds the organizational wide settings. So, your plan, your invoices, an audit log of who did what, which is exactly what you want for compliance and incident review. Now, inside each

## Applications, live and sandbox

[03:43](https://www.youtube.com/watch?v=sRcOBxjRYag\&t=223s) organization, you can create multiple applications. So, if I had an additional application here, you know, I can create a new one with this tab, it's going to show up inside of here. We're going to have live and sandbox for each. Now, if you want to switch to sandbox, that's coming soon. It's going to have its own API keys, its own workflows, and its own webhooks for testing. So, let's head over to the

## Team members and roles

[04:04](https://www.youtube.com/watch?v=sRcOBxjRYag\&t=244s) settings tab down in manage. We've got our team members in here as well. And each person carries exactly one role. And this is important, right? It's the role, not the person, that decides what they can see and do. You can see here, this is me. And you can see there's no settings cog here. So, I can't accidentally come in here and change my role and lock myself out of my own account. But, if I do click into here from somebody else, I can change them from owner to developer to compliance to admin, all of the different options here. So,

## Inviting a teammate

[04:38](https://www.youtube.com/watch?v=sRcOBxjRYag\&t=278s) if I want to add a new team member, just click this tab up here. I can add in their email address and select the applications that they're going to have access to and the different kinds of access that we want to give them. Now, until they accept, you'll see a orange pending badge, which means the invite went out, but the person has no access at all yet. So, every organization comes

## The five built-in roles

[05:01](https://www.youtube.com/watch?v=sRcOBxjRYag\&t=301s) with five roles out of the box, and you just match the role to the person. The owner has full access, so including billing, that's usually just you, the owner of the business, or select few people on your team. Admin runs the members, the applications, the workflows, basically everything apart from billing or deleting the organization. We've got compliance officer. This is built for your risk people. So, reviewing verifications, cases, and screening with no developer or billing access at all. Developer covers the APIs, the webhooks, the applications. And the reader down here is read-only on sessions, analytics, and reports, which makes it the safest role for observers and executives who just

## Custom roles

[05:41](https://www.youtube.com/watch?v=sRcOBxjRYag\&t=341s) need to look. Now, if none of those roles suit the needs of someone on your team, we can actually create a custom role and define the permissions that we want to give them. And that can be done here.

## Recap

[05:54](https://www.youtube.com/watch?v=sRcOBxjRYag\&t=354s) Finally, at the bottom here, we can see how many members have access to the specific role. So, that's the operators view of Didit, an analytics side that shows you how your transaction activity is really performing, and a team side that lets you control exactly who can see and change what. So, between the two, you can measure the business and keep it locked down at the same time. And if you'd rather work with the numbers in your own tools, all of it is available over the API and the MCP. So, head over to didit.me, sign up for free, and invite your first teammate today.


# Build a KYC Workflow With No Code
Source: https://docs.didit.me/academy/build-kyc-workflow

Video transcript: building a KYC verification workflow visually - checks, branching logic, risk rules, testing, and publishing to production.

<VideoEmbed title="Build a KYC Verification Workflow With No Code (Full Tutorial)" />

Full transcript of **Build a KYC Verification Workflow With No Code (Full Tutorial)** - Didit Academy video 3 of 10, 18:54. [Watch on YouTube](https://www.youtube.com/watch?v=7-nJ3JE20i4). Each paragraph links to the exact moment in the video.

## What a workflow is

[00:03](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=3s) In this video, we're going to be building a complete verification flow from scratch, and you won't need to write a single line of code. A workflow is really just a recipe for a verification, which checks to run and in what order. Normally, that kind of thing lives with your engineers. But in Didit, you build it yourself visually. You watch the price update as you go, and you push it live whenever you're ready.

[00:28](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=28s) If you want to build one yourself, you can head over to didit.me, sign up for free, and put your first workflow together in just a few minutes. All right, so let's start where every verification flow lives, and that's in

## The workflow list and workflow IDs

[00:39](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=39s) the workflow list underneath the configure tab here. So all of the workflows that we've currently got in this account, you can see the type. We've got KYC and KYB. We've got simple and graph, and we could see all of the different checks and features inside of each workflow. We could see the price spread. So this basically shows the price from somebody who goes through and does one check and doesn't complete versus somebody who completes the entire flow. We have a a link for the workflow.

[01:09](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=69s) We can add a new session manually. We can copy the workflow ID. We can duplicate, rename, archive, all of your usual stuff. And this is your workflow ID here. So multiple versions of the same workflow is just going to run off the same ID. So if you do update the workflow, you don't need to change anything inside of your code or your app. So the simplest way to think about a workflow is that this is just a recipe for a verification. So which checks to run in what order and what rules to follow. So there's two different

## Simple vs graph workflows

[01:40](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=100s) structures like I mentioned. There's simple and there's graph. So a simple flow is just one check or a few checks with no branching at all. No conditional logic. It's quick to set up and it covers most cases. So you pick your modules and you're done. So I mean if we take a look at this example workflow, you can see we can select the modules here over on the left and it's going to sequence them all in order. Now for a

## A graph workflow with branching

[02:05](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=125s) graph-based workflow, if we click into here, we could see there is some branching at the end. So we can get a little bit more granular with where we direct the user through this verification flow. So you can see in this workflow for example there is multiple different branching points. We can include webhook calls as well. Um and in general we can just add a little bit more complexity in here when needed.

[02:30](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=150s) So you just note here as well the KYB workflows look exactly the same but we just have different checks. Okay. So if we want to add a check we can pop in here. We can grab one of the user actions or set up some background checks. These are the ones that the user doesn't see on the front end. So, all

## Creating a new workflow from a template

[02:51](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=171s) you need to do is hit new workflow. Got a couple of options here. KYC, KYB. Let's hit KYC. And we've got simple versus advanced like I showed you earlier. And I'll show you options for both. If we click simple, we have a ton of different templates here for all sorts of different industries. And we can see the cost for each of these templates. We've got age gates. We've got email verification.

[03:19](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=199s) We've got biometric authentication, insurance, healthcare, all of this stuff. Now, for example, if we use a business verification, and we use the advanced version, which is the graph, again, we've got a bunch of different templates or recipes if you want to call them that. So, we could set up high-risk country KYB and boom. You don't even have to click and drag and drop anything in here. It's already built. So every

## Picking a check on each node

[03:48](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=228s) node here has a dropdown. So you can just pick the check that you want. You can change it like here or we can put the registry check. Whatever you want. ID verification, livveness, face match, AML, proof of address. All of the checks that Didit can offer for KYB and KYC are available inside of these nodes right here. So, if I wanted to add an additional check into here, for example, let's say I wanted to do a AML screening, then I can add that into here. We'll get into the rules and these tabs in in just a moment, but you could see in this workflow, I've added that in to this workflow here. So, if you go into a KYC graph workflow here, most of these workflows are going to start with ID verification. It's the most common

## Inside the ID Verification node

[04:33](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=273s) check. And you can see here, this is the ID verification node. We got 500 free checks per month and the same for the livveness and same for the face match. Now, this ID verification does way more than just read text off a card. It proves the document is genuine. checking the security features, looking for tampering, reading the fonts and the layouts, and then it extracts every field, the name, the date of birth, the document number, the expiry, all by OCR in any language across all 14,000 plus supported document types. So, this is never just text. It's an authenticity check first and then data second. So, let's configure one of these modules.

## Liveness modes and what each costs

[05:15](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=315s) Let's I mean, if we head over to the livveness module, you can see we've got a few different livveness modes. We've got passive, which detects livveness using a selfie. We've got flashing, so we confirm the livveness using dynamic light patterns to detect real user faces. Then we've got a 3D action. So, it's going to confirm the lighting with some kind of action, whether it's a blinking of the eyes or a turning of the head. Now you can see for the passive livveness check, we do get 500 free credits a month and then 10 cents per check while the flashing and the 3D action is 15 cents per check. And we don't get any free checks included in our free account. So in the rules tab,

## Rules: thresholds, duplicate faces, multiple faces

[05:56](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=356s) this is how we decide whether the module is required or optional. So if we head over to the rules tab, we can see there's a few different options here. So this allows us to configure the sensitivity of the testing. So we can set a tolerance level. If somebody has a livveness score of less than 70, then it's going to send them to in review. And we can we can change that if we want. And it's the same for decline. We can also have a setting for a duplicated face. So when a user's face matches one from a previously approved session, how do we proceed? So approve, review, or decline. And then we can customize the similarity threshold by ethnicity. So we can set the duplicate detection sensitivity depending on their ethnicity. And then finally we can define the action to take when multiple faces are detected in the livveness image. The the largest face will always be used for livveness scoring. So uh that's an option that we can set here. If we head into the

## Advanced settings and quality thresholds

[06:56](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=416s) advanced tab, we have a few different options here. Here we've got the face privacy mode, maximum livveness attempt, so how many times a user can reattempt the livveness check within a single verification session, the face quality threshold. So, so if you are ever unsure of what these settings actually do, we can hover over this information button here. We can see face quality measures image clarity, resolution, sharpness.

[07:20](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=440s) Low quality images may result from blur, pixelation, or poor lighting conditions. So we can set the threshold here based on the face quality score. We have a luminescence threshold. So we can set the acceptable luminescence range and then if the luminescence is below that range, we can obviously send them to review or decline. And finally, we can set up our own custom rules if none of these match the

## Return data and GDPR

[07:47](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=467s) settings that we want. So in the return data tab we can select the data points that we would like to exclude from the verification results for GDPR etc. Now for each of these modules we can see the price of the check and then at the top

## How workflow pricing adds up

[08:00](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=480s) here we could see a total price. So let me just sort of walk you through this because each node has its own price and each workflow is probably going to be slightly different in terms of the total cost. So you only pay for the steps that actually run. So each step is charged on its own. So if the applicant stops partway through the check, only those first few checks that they've gone through only going to be charged. So that's why you see at the bottom a range from 20 cents to 43 cents. That is the range. If somebody is going to go through the workflow, if they go through the first step and they exit, then it's only going to cost you 20 cents. If they fully complete the verification workflow, it's going to cost 43. And as you can see in the middle, these are all of the modules that are inside of this particular workflow. We can see how many credits we've got per month. Once those free credits are used up, once those 500 checks are done, then you will start getting build for them. So, one of the most powerful modules you can add isn't actually a camera check at all. It's

## Database validation against government registries

[09:05](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=545s) database verification. So, let's just add this in. This is a background check. And we're going to take a look at what this actually does because this database validation check connects to official government registries and databases all over the world. So what it does is cross-check the users data against those official sources and then enrich it with extra fields the registry holds. So you can choose which registries and sources to run as you can see here for each country. And each service lists its own price. So you can see down here we've got different services inside of Canada for example and there's obviously different pricing for different registries. So if you wanted to see a specific country like Germany for example, we could see the checks that are available in Germany and we can select these based on our needs.

[09:59](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=599s) And this database validation is not just something that you can run here in the dashboard is callable directly through the Didit API from your own backend too. And again, like with all of these modules, we've got rules, we've got advanced, and we've got return data. So again, you could set your rules here. And if we click here on partial match, we could see what a full match looks like. Full name and ID number, if that matches in the registry, for example, and a partial match maybe is just an ID number. And then we can decide what that partial match means inside of your workflow. Do we put it to review? Do we decline? Do we approve? So we have some branching inside of this workflow. We

## AML branching and conditional logic

[10:36](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=636s) have AML branching depending on the AML risk score. AML is just anti-moneyaundering. But we can see down at the bottom we already have branching configured for this AML risk score. So we can see if the risk score is over 70, we can just decline and we can click into here. We can see the conditional logic. Right? So this is something that we can set up however we want. So we've got branch one, we've got branch two and then all other cases which means the session is going to be approved. So for example, if somebody is in this group here, they get sent to branch two. We could ask them for uh more information, right? We could ask them for proof of address, for example. So that way if somebody is a little bit risky, we can ask them for for more information that will help us decide whether this person should be approved or declined. So, one of the other nodes that we've got here is we've got status, and we've already been added here, but you can add those at the end of your workflow to determine what the outcome's going to be. So, another one of the

## The webhook node

[11:40](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=700s) nodes that we can include in the workflow is the webhook node. So, the flow can also reach out to your own systems in the middle of a verification, and that's what this node is for. It can call an endpoint and pull data back. And so it's going to wait for that webhook to respond. You can see here we've got a post webhook. We've got a JSON payload which can be changed. Also, we can also send different payloads. So these are the key value pairs that maps your session fields into the request that you send out. And the fields that come back become variables for the next branch to test. So you're combining digits checks with your own risk data all inside a single flow. And one final thing we we can include the headers down here at the bottom. Some more key pairs. We got basic authentication here. All of the stuff that you would expect uh from a webhook call. Didit validates the

## Graph validation and errors

[12:28](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=748s) graph the whole time you're building. So if a node is misconfigured or a path is broken, it's going to tell you exactly where. Right? So we click down here in the bottom. We see flow has two errors. And we can see branch one has incomplete rules. And it's going to tell you what needs fixing inside of your workflow. And we're not going to be able to publish this until these errors are fixed. So if I had a brand new workflow for example and there was an error then I wouldn't be able to publish that workflow. So beyond the individual nodes

## Workflow settings: retries, expiry, callback URL

[12:58](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=778s) in the workflow we have the settings tab in the top here that we could see these settings apply to the whole workflow rather than a single check. We've got a workflow name of course we've got a call back URL which is the address Didit redirects the user to once the flow finishes. We can allow desktop access if you want to allow them to continue on desktop. We've got the retry attempts so you can change that. So, the amount of times a user can reattempt document capture within a single verification session. If a previous attempt fails, we've got the session expiration, so how long an unfinished session stays valid before it automatically expires. And this is going to apply to newly created sessions. And we've got the retry window, so the number of days within which retries are allowed. So from

## White-labelling the flow

[13:43](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=823s) inside of this workflow, we can actually head over to the customizations tab by clicking this button up here. So white labeling is wired straight into the flow itself. So you can jump into this tab here and you could start tweaking how this verification flow looks, the colors, the branding, the email, the domain, all of that good stuff. And in the mockup here, you could see how it's going to look on mobile and also how it's going to look on desktop as well.

[14:13](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=853s) You can also test it out in different languages. So if we put this into French, you could see every check is now written in the French language. And if you want to turn on, you know, you can switch on your branding here. Boom. You could turn it to what we set in the customization tab or we can turn that off. And we can actually see what happens if we choose a different path here and we can see what gets sent to the user. Now, obviously the user is not going to see the the pick a path module, but this is just to help us visualize what's going to happen on the next step, right? So, if they declined, we're going to see verification declined, verification in review, or that they've been verified. We do have the copy link

## The shareable link, and when not to use it

[14:58](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=898s) at the top here. So, if we copy that, open a new tab, we can come through to the the link here, and we're going to be able to see what the user is going to see. And sometimes you just want to hand someone the flow without wiring any code at all. And this copy link does exactly that. It copies a ready to share hosted URL for this workflow. Now, this is handy for a quick test or a manual send, but it's not the recommended way to integrate this. For production, you can create a session per user through the SDK or the API carrying the vendor data and that's how you get real-time results back through webhooks and the SDK. So the copy link is great for tests and events and a proper session is what you're going to ship in production. So

## Version history and rollback

[15:41](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=941s) at the top here we've got the version history. So we could see the different versions and we can restore or we can view the previous versions. And if we were to be editing this workflow, then those edits would sit as a draft um above the published history in here. And the cool thing is that every new version that you publish, it keeps the same workflow ID. So your backend keeps calling that one ID and it's going to get silently forwarded to the newest workflow that you've created cuz that history is tracked and you can iterate with confidence and roll back to previous versions whenever necessary. So for example, in this workflow here, this is a brand new one. You can see it's in draft mode. If we make any changes to the workflow, it's going to be in draft and we'll need to publish it. So, we can

## Publishing your workflow

[16:24](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=984s) hit publish. This workflow is only going to go live when it's published. Uh, it's going to validate the graph to make sure there's no errors. And boom, we can grab the link and now this workflow is live and ready to go. Uh, let's take a look

## Integrating: SDK, API key and the setup prompt

[16:37](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=997s) at the integration. So, there are multiple ways to integrate this. We can grab our target SDK. So whether we want React Native, iOS, React Next.js, we can select the workflow and in this case we got the high-risk country of review. We can select the API key. So we can have different API keys for different workflows or different integrations, whatever you want. Or you can select a webhook. So if you want to get notified of decisions, you can pop that into there. Now the easiest way to integrate this is we just copy a prompt and we can just slap that into claw code or codeex.

[17:12](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=1032s) And that prompt is going to integrate this workflow. So even if you don't have didit integrated into your app yet, this prompt will give you everything that you need to have this workflow up and running into your app. Now you don't even need to do that. You could just

## Building workflows with the MCP server

[17:27](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=1047s) install a Didit MCP server. Just describe the flow in plain language and it will create the workflow for you and automatically integrate it into your app. Tell it what to do and it will go ahead and do it. Now, we are going to get into how to set up the MCP in another video, but MCP is essentially model context protocol that allows you to build. with Didit using natural language in tools like Claude Code, Cursor, Codex, and all the rest. So, we can jump into customization real quick.

[17:57](https://www.youtube.com/watch?v=7-nJ3JE20i4\&t=1077s) We'd add in the public name, privacy policy, URL. We've got the branding where we can change the colors. You can also pull your logos and colors automatically from your website, which could be super useful and easy to do. We can upload your logos down here. And you can see I've already set these colors. And to to test how it would look with those colors, if we just flick this switch here, we could see our white label branding getting implemented here on the verification flow. I'm just going to toggle it off for now. You can set a personalized email. You will need to fill out these details. And then when you continue to verification, you can just get the DNS information and hook that up with your domain. And the same here if you want to put a subdomain. So that this whole workflow is fully hosted using your own branding, your own domain. So this really is a seamless process for your users to go through the verification.


# Integrate Didit: API, SDK and Webhooks
Source: https://docs.didit.me/academy/integrate-api-sdk

Video transcript: the developer integration path - session API, SDKs, webhooks, and going from sandbox to production.

<VideoEmbed title="Integrate Didit in Your App: API, SDK and Webhooks (Developer Guide)" />

Full transcript of **Integrate Didit in Your App: API, SDK and Webhooks (Developer Guide)** - Didit Academy video 8 of 10, 08:13. [Watch on YouTube](https://www.youtube.com/watch?v=fX03-WEu_EI). Each paragraph links to the exact moment in the video.

## What you'll wire up

[00:04](https://www.youtube.com/watch?v=fX03-WEu_EI\&t=4s) In this video, you'll get Dedit wired into your own app. So, your users verify right inside your product, and every result flows back to your system the moment it happens. This is the developers video, so it's a little bit more technical, but it's simpler than you think. And by the end, you'll see you can hand most of it straight to cloud code and have it build it for you. So, we'll go through it in order that

## SDK, API and webhook: the three pieces

[00:28](https://www.youtube.com/watch?v=fX03-WEu_EI\&t=28s) you'd actually build it. Let's dive right in. Integrating Dedit means wiring up three things. The SDK renders the camera, the document capture, the NFC read, and the liveness UI right inside of your app. The API is server-to-server, so your back end creates the session and reads the authoritative decision. And the webhook calls your HTTPS endpoint the instant a session changes state, which is way

## The integrate tab

[00:56](https://www.youtube.com/watch?v=fX03-WEu_EI\&t=56s) faster and richer than polling for it. So, the easiest way to integrate is to go to your manage tab, click on integrate, and we can just grab all the settings from in here, so we can grab our API key. So, we could set up a specific API key for this particular app that we're working on. We can create and choose a workflow that we want to integrate. We can add a webhook. So, this is where the verification results are pushed to.

[01:24](https://www.youtube.com/watch?v=fX03-WEu_EI\&t=84s) And the signing secret, that I'll show you in a second, this is what's going to

## Choosing your platform

[01:28](https://www.youtube.com/watch?v=fX03-WEu_EI\&t=88s) go in your ENV file. You can then connect it to your app. So, we've got a few different options here. We've got web JS, React Native, iOS, Android, Flutter, and a few other surfaces here. So, you can select the one that is relevant for your app. This is the environment secrets that you're going to put in your ENV file over on your

## The AI setup prompt

[01:48](https://www.youtube.com/watch?v=fX03-WEu_EI\&t=108s) server. So, the easy way to set this up would be to use the AI setup prompt. So, we configure all the settings up here, and then we copy the prompt and it's going to copy all of the relevant information that we need from the setup that we've completed here. We copy and paste this, and we can pop that into Cloud Code or Codex or wherever you're

## API keys, one per environment

[02:09](https://www.youtube.com/watch?v=fX03-WEu_EI\&t=129s) building your app. Your API keys live here, and each row has one key, okay? And so, a good habit is a separate key per environment per integration. So, you can rotate or revoke one without breaking the others. So, if you're going to integrate a specific workflow, you

## Creating a key

[02:27](https://www.youtube.com/watch?v=fX03-WEu_EI\&t=147s) might want to just have a separate API key for that workflow, for example. Now, if I click create API key, um I'm just going to put test here, create the API key. Now, I can copy this, right? And I'm not going to see it again. So, it's important that you copy it and maybe note it down somewhere so that you can use it when you're doing the integration. When you come through to the integration section and you grab your API key, and let's say if I grab the test key and I come down, I select, okay, we want to use this uh let's see, KYC workflow. We can add a webhook.

[03:05](https://www.youtube.com/watch?v=fX03-WEu_EI\&t=185s) We can connect our app, okay. And then we can pop in this setup prompt here. You can see here this prompt is going to

## Webhooks overview

[03:13](https://www.youtube.com/watch?v=fX03-WEu_EI\&t=193s) include the API key. So, moving on to webhooks real quick, we can set up a webhook for basically anything that we want. So, say if you want to send a specific event to Slack, right? We can

## The documentation

[03:25](https://www.youtube.com/watch?v=fX03-WEu_EI\&t=205s) add the webhook URL here. Okay, so let's take a look at some of the documentation here cuz you do have access to all the technical documentation. If you just go to docs.didit.me, and we're going to look at a few things

## Create session: the one required field

[03:37](https://www.youtube.com/watch?v=fX03-WEu_EI\&t=217s) in here. Everything revolves around the create session. All right, so this is a post request. This is the start of a verification. So, we could see here in the curl request, we got the workflow ID. This is the only required field, and the really useful bit is that this same endpoint creates both KYC and KYB sessions. The

## Vendor data and callback URL

[04:00](https://www.youtube.com/watch?v=fX03-WEu_EI\&t=240s) workflow is what decides which is which. So, we've got some additional fields down here, including the vendor data, which we've spoken about a lot in these videos. This is the unique identifier for each user, and you can define that as you wish, if it's an email or a unique identifier, and then we have the callback URL here. This is where the user is going to get sent after they've completed the verification workflow. So,

## Trying the endpoint live

[04:24](https://www.youtube.com/watch?v=fX03-WEu_EI\&t=264s) if we scroll down here, we can actually try this out. So, if we click try it, we can actually create a verification session here. So, I'm just going to pop in one of the API keys here. Just going to create a brand new one, test two. I'll copy that. Pop this in here. We want to grab a workflow ID. So, pop over to here. We can grab this workflow ID here. Enter that into there. The vendor data is not required. Let's just do a a random string of numbers.

[05:02](https://www.youtube.com/watch?v=fX03-WEu_EI\&t=302s) The callback, we can keep it the same here. None of this is required, by the way. I think this is because I have a test account here, but if you did want to test this endpoint, this is exactly how you would test it. Now, if you are a developer and you want specific answers here, you can check out the documentation. The MCP also has access to all of this documentation, so you can literally just integrate the MCP and ask Claude a question that you might have about something technical that's probably going to be in these documents

## Webhooks: why not polling

[05:32](https://www.youtube.com/watch?v=fX03-WEu_EI\&t=332s) inside of here. So, let's talk about webhooks. We do have a tab here in the manage section for webhooks, and this is how your results actually reach you. Webhooks are the recommended channel because polling is pretty slow, and it's

## Adding a destination and picking events

[05:44](https://www.youtube.com/watch?v=fX03-WEu_EI\&t=344s) going to cost you more requests, and it's going to skip events. So, we add a new destination in here. We can paste a URL. We can pick the events that we want. So, this is all the data that we want to send to this particular endpoint. And Diddy is going to hand you back a one-time signing secret, which I'll show you in a second. And the URL has to be directly reachable. So, no localhost and no private IPs. So, I'm just going to come out of here and we can scroll over to the right-hand side and we can we've got a few options here.

[06:16](https://www.youtube.com/watch?v=fX03-WEu_EI\&t=376s) So, we can see here the number of events this webhook is listening to and we can

## The signing secret

[06:19](https://www.youtube.com/watch?v=fX03-WEu_EI\&t=379s) copy the signing secret, which is going to be important for your integration. Now, when we do the setup the integration in the integrations tab, and I walked you through that we have a prompt, then the yeah, the signing secret is going to be in here for the webhook that you've selected in the setup. So,

## The webhook handler prompt

[06:34](https://www.youtube.com/watch?v=fX03-WEu_EI\&t=394s) another one of the ways that you can leverage AI, we've got a pre-made prompt here that I found in the webhooks tab here. We could see if you want to set up our webhook handler with AI. We can check out the documentation and we can find an integration prompt here. So, this is going to cover identity verification, entity, and transaction. It's going to build it all out for you. So, it lays everything out. So, what to build, the signature headers of verification, the webhook event types that you just saw when we were setting up a webhook earlier. We've got the webhook envelope and a whole bunch more and we can also select where we want to paste it into, which tool that we're using here.

[07:15](https://www.youtube.com/watch?v=fX03-WEu_EI\&t=435s) So, if you want to use this prompt, that's the easy way to get rolling with this and get your integrations set up. Everything I've just gone through in this video is accessible and queryable inside of your AI tool if you integrate the MCP server. So, you can just explain whatever you want to happen in plain English and Cloud Code will read the documentations and build the integration for you. So, you're just checking the work, making sure it's running and

## Recap

[07:41](https://www.youtube.com/watch?v=fX03-WEu_EI\&t=461s) working rather than coding everything from scratch. So, that's Didit in your app. The SDK, your users see, the API that your back end calls, and the signed webhook that delivers the verdict that you build on. Trust the webhook, use vendor data everywhere, and lean on the setup prompt, so you're not hand-wiring the boring parts. You can head to didit.me, sign up for free, and you can have a verification run in minutes.


# KYB Explained: Registry to UBO
Source: https://docs.didit.me/academy/kyb-explained

Video transcript: business verification end to end - registry data, documents, officers, ownership graphs, and UBO identification.

<VideoEmbed title="KYB Explained - Verify a Business From Registry to UBO, Start to Finish" />

Full transcript of **KYB Explained - Verify a Business From Registry to UBO, Start to Finish** - Didit Academy video 6 of 10, 11:05. [Watch on YouTube](https://www.youtube.com/watch?v=JEnW_sEe35Y). Each paragraph links to the exact moment in the video.

## What this video covers

[00:03](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=3s) In this video, we're going to verify a business from start to finish. Checking a company is more than confirming a name. You've got to look it up in the official registries, work out who really owns it, screen the business and its owners, and collect the right documents. Didit pulls all of that into a single workflow called KYB. We're going to set it up, see what the company representative goes through, and then read the full result in the dashboard.

[00:32](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=32s) So, let's get into it. All right. So,

## The business verifications dashboard

[00:35](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=35s) let's navigate to the business verifications dashboard. So, this is KYB, know your business, and it verifies the company itself, its registry records, its owners, and you can see here, we're going to go into detail on one of these checks. This particular business is under review. And again, this is a demo account with demo data. But you could see the checks that this business has gone through, the checks that have been approved and the warnings right here.

[01:03](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=63s) So, we're going to go through each of these tabs and I'm going to explain the details of each of these checks. Now, if

## Filtering for businesses in review

[01:10](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=70s) you want to filter for all of the businesses that are under review, we can apply the filter in the status column. in review. You can see this particular business has been flagged on a lot of different fronts. Uh we can also check out some other ones here and we can see this business has been flagged on key people. So at the top just like with the user verification results we've got similar tabs and these tabs are related to the checks that this person goes through in a specific workflow. So up

## Warnings first

[01:38](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=98s) top as usual the first place to look is the warnings. Where has this particular business been flagged? So you can see company officers data not available. So that's what we're going to be looking at when we're working through and figuring out if we can approve this business or not. Now we do have the business details

## Business details and vendor data

[01:56](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=116s) here. The country, the session ID, and the vendor data ID. Now, we've gone through this in previous videos. The vendor data is what ties all of the checks and all of the transactions under one profile. We can take a look at the session ID when it was created, the vendor data again, and and the workflow. So the workflow this particular business has gone through. We've got a cost breakdown here of all the checks that have been applied to this business. And that's everything in the overviews tab. All right. So let me find another profile that's got more checks here so can walk you through in a little bit more detail. Again, this is a different company. Again, demo data. Got the cost breakdown, possible match found in the AML screening. So we're going to work through that. Let's take a look at

## The registry check

[02:43](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=163s) the next tab. This is the registry check. This is going to happen with every business that you put through KYB. You can see the registry is active. Got the company name, the registration number, all of the information that we've pulled from the registry. So, there's a lot of stuff in here. I'm not going to walk you through every single field. It's going to be different for different countries, but just know there's a bunch of checks running on this particular registry check. In the background, you can see company country accepted, the ownership data is available, the company is active, and all of these other checks. And if you want a little bit more info on these, you can just hover over and see a further explanation. So, if you're responsible for coming in and reviewing these verifications, you can flick that to approve if you think that check is worth approving. So let's move on to the

## Key people: shareholders, officers and UBOs

[03:34](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=214s) key people because a business is usually not just typically one person. There are many people involved and so we need to run checks on all of those people inside the business. All the shareholders, all the representatives that we can see here. There's plenty of people in this business that we're going to need to run checks on. So we've got a list, but we've al also got a hierarchy. We can see how that looks on this chart here.

[03:56](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=236s) So keep it as a list. We're going to scroll down and again we've got a checks list. And if we hit this drop down, we can see there's only one check happening here on the key people. But if we scroll up, we can see fully verified, all parties clear. So we could flick that to approved. Now, if we keep going, we can

## AML screening and ongoing monitoring

[04:12](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=252s) see the AML screening. So this is the same as the user verification, the KYC. And again, we've got a sanctions list that we're going to be matching against. We can flick on ongoing monitoring if we want to keep monitoring this particular user on an ongoing basis. Instead of just running the check once, we can run that on a weekly, monthly basis. You can see there is a match here, but the match status is inconclusive. We could see the the lists that this particular business has appeared on. If we click the drop down on the checks list, we can see no AML matches found. AML screening performed. So, there was a match found here, but it's it's not a particularly high risk. We can see that there is a

## KYB documents and signature integrity

[04:50](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=290s) match found here, but again, inconclusive. We keep rolling with this. We got the KYB documents. We can see what's been verified, what's in review, and what's declined. The corporate documents that were submitted, and the information that was pulled from these documents. We can also see the document integrity. Was it signed by pen or was it digitally signed? And that's important to know, right? Because digital signatures are not as authentic as real signatures, right? We've got the checks list. Again,

## Device and IP analysis

[05:18](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=318s) these are all the checks that are running on these documents. Like we saw in the KYC, we've got the device and IP analysis looking at where the IP is for the verification device and then where the actual proof of address location is based. Again, if we want to see the checks that are running on the device and IP analysis, we can take a look

## The event log

[05:35](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=335s) here. And down here, we've got an event log. And this is probably going to be a little bit more busier than the KYC because there are going to be different people inside the business that are going to need to submit information. So, we're able to see here when files were uploaded, when the statuses have been changed, when the session was created, including the IP address of each of these actions, and finally, we've got

## Webhooks

[05:58](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=358s) the webhooks at the bottom. So, when these webhooks were pinged, got all the

## Inside a KYB workflow

[06:02](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=362s) information of these webhooks inside of this dropdown. So, what does an actual KYB workflow look like? So, let's just take a quick look inside the configure tab. We go into workflows and we can find a KYB workflow inside of here. Registry and documents. So let's take a look at what a basic KYB workflow looks like. We start off with a registry check. Check the key people. And let me just show you what appears over here on

## The ownership threshold

[06:30](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=390s) the right hand side. So there's a bunch of settings here that we can tweak. So the ownership threshold. So set the ownership threshold used to exempt low ownership owners from verification. you know, if somebody owns 1% of the company, there's really no point in verifying that person. And we can set that threshold here by just using this slider. So, anybody who's below this particular value is exempt from identity verification. So, in the settings tab over on the right, we can set the ownership threshold on UBO ownership and shareholder ownership. We can change that so anyone below the

## Party verification and reusing KYC sessions

[07:04](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=424s) threshold is exempt from identity verification. We can also select the party verification. You can select the ones in here. We can auto decline on UBO rejection. So if any UBO fails verification, we can just auto decline. Also, we want to wait for all of the UBO verifications before making a final decision. Uh we can turn that off if we want. We can reuse verified individuals. So we can reuse approved KYC sessions for the same person across KYB, which is pretty smart. And notify parties by email. We want to notify these people so we can get their verification for the KYB check. There is some more advanced settings here, but it's not the scope of this video. I just want to work through what else we've got here in this workflow. We've got the AML screening.

[07:47](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=467s) So, very similar to KYC. We can set the risk threshold on here. Uh we've got the phone verification, email verification. Again, we've got a bunch of settings for each of these steps, but if you don't really know what to configure, you can just leave everything as default. And the cool thing is you can have a conversation with Claude to set all of this up for you and it can walk you through all of the settings and you can just tell it your preference and it will know which setting to change and tweak.

[08:15](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=495s) So I'm not going to go through all of these individual settings. We will be here forever, but just know you can add additional steps in here. You can add branching based on the outcomes of specific steps in this workflow. Now, if

## What the company representative sees

[08:29](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=509s) you want to see what this workflow actually looks like, we can head over to the customization tab by clicking this icon up here, and we can see what somebody would see on the other end when they're coming in to verify their business. So, we start off with the welcome screen. We find their company using their company name and their country. Then, they select their company because we've done a search on the registry. They're going to edit the company information, list all of the key people. So the UBOS's shareholders representatives phone number verification which they'll then enter in here email for email verification which they'll enter the code in here. And now they're not going to see this. This is the branching that I've put inside the workflow. But we're going to be able to see what that user sees on the other end if they go down branch one or the other branch. But I've not set that in this workflow. So we could you can see at the bottom I I just added this in just to show you as a demo. So we can delete that step. So that's exactly what someone's going to see on the other end.

[09:30](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=570s) So if we want to check in on our data,

## KYB analytics

[09:32](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=572s) we can go through to the homepage. We could check the analytics. We can add some tabs at the bottom here if you want. So we can come in here. We can check the business verifications. We could look at the the volume, IP locations, company locations, warning insights, conversion rate, conversion rate by country, um, automatic verdict breakdown, and we can add all of these to our dashboard.

[09:57](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=597s) So, if you scroll down, you can see that we've added all of these business checks. Down here, we can see the Caribbe registry check, key people, AML screening. So, this is just a warning insights at a glance. So we can see our approved versus rejected, conversion rate from approved, decline, and in review. We can customize this. We can also run reports at the bottom and export any data that we want from that dashboard. So that's a business verified from start to finish. One workflow looked the company up in the official registries, screened the business and its owners against the watch lists and mapped out who really owns it with an identity check on each of them and pulled in the documents. And all of that comes back in the dashboard registry record and the company status, the ownership, the screening results and the documents with the same data available over the API. So if you want to run a KYB of your own, head over to didit.me.

[10:54](https://www.youtube.com/watch?v=JEnW_sEe35Y\&t=654s) me. You can sign up for free and create your own business workflow today.


# What Users See in a KYC Verification
Source: https://docs.didit.me/academy/kyc-user-experience

Video transcript: the end-user KYC flow step by step - branding, document capture, NFC, liveness, face match, and what happens on decline.

<VideoEmbed title="What Your Users Actually See in a KYC Verification (Full Walkthrough)" />

Full transcript of **What Your Users Actually See in a KYC Verification (Full Walkthrough)** - Didit Academy video 2 of 10, 14:36. [Watch on YouTube](https://www.youtube.com/watch?v=LzGe-dMWjUw). Each paragraph links to the exact moment in the video.

## What this video covers

[00:03](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=3s) When you send a customer off to verify with Didit, what do they actually see? Well, that's what this video is about. We're going to walk through the whole flow from their side. The exact screens a real person taps through after they click your link. a flow you fully brand in their own language on whatever device they've got with a stack of invisible checks doing the heavy lifting and the real result landing in your system the moment it's made and the best way to get a feel for it is to run one yourself. So head over to didit.me you can sign up for free and verify on your own phone in

## Opening the flow yourself

[00:38](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=38s) a couple of minutes. Okay, so the easiest way for you to see exactly what your users go through is to open the flow yourself. So that's what we're going to do. Uh we're going to head over to one of our workflows here. We're going to copy the link and we're going to put it in the browser. So let's just take this basic KYC workflow. We're going to copy this link and we're going to pop it in here. So right here is the

## The first screen your user sees

[00:58](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=58s) very first thing that your user sees after they tap one of your links. So the first thing to notice that well this is a demo for it. So we do have the Didit branding on here, but you can fully customize this. This list here is every step this particular user will go through. So we've got ID verification, face verification, and additional documents. So this list is not hardcoded. The workflow that this session is attached to is actually going to decide which steps show up and in what order. So this flow just renders

## Branding, and why it drives completion

[01:28](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=88s) whatever is inside of that workflow when you turn it on. So the logo and the styling are yours, too. So to the user, this still feels like your product. That's pretty important because how much it feels like you and your brand is the single biggest lever on how many people actually finish this verification flow. So there is one small mark down here secured by Didit and even that's removable. Everything above is yours to configure. Did just the engine that's running underneath. So what your user sees is exactly the workflow that you set up wrapped in your brand. So here's

## The checks that never show a screen

[02:00](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=120s) something that surprises most people. Not every check you see here has a screen. The only steps that show up are the ones that genuinely need the user to do something. So document, face, phone, email, and while they're working through those checks, a whole set of other checks is running server side with nobody touching anything. So device and IP intelligence, AML screening, ongoing AML monitoring, database validation, these are all happening in the background. The user never sees a step from any of them and you still get every result back in your dashboard. And that's how the flow stays super short while still doing a ton of work. Some of did its strongest checks at zero friction because they never face the user. So if you go back and look into one of these workflows, we could see here that we've got all these background checks. We got database validation. Uh we've got email verification, phone verification, AML screening, IP and risk analysis. So these are not public facing. These are all the checks that

## Customization: colours, logo, email, domain

[03:00](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=180s) you can add into a workflow. So let's take a look at the customization tab. This is where you're going to be able to add in your branding, your colors, your own email address, your own domain, all of this stuff. As you can see here, we can change the name of the app. We can show the welcome page or turn it off. We could show the progress bar or turn it off. We've got the branding tab where we can add in all of these colors. Can add in the logo, the favicon, and change the typography. We can add a custom email.

[03:25](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=205s) So, if you just pop in a name here, we can put in a an email address and we can continue to verification. This is going to give us the that's not worked out. But if we put in an actual working domain and we click continue to verification, that's going to give us the DNS records uh that we can add and we can set up a custom email address. And this email is where the notifications are going to get sent from and all the updates about the verification status. For the domain, we can also add a custom domain. So, we had a subdomain for example. And again, if you add in your subdomain here, it will give you the the records that you need to update on your domain provider. So you see this globe up here. The

## 54 languages, auto-detected

[04:04](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=244s) interface ships in 54 different languages and that includes left to right scripts like Arabic. And by default, this flow just auto detects whatever language the browser is set to and falls back to English if it doesn't support that particular language. But the user can open this searchable list and switch into any language at any time and have every instruction follow their choice from there. And if you already know someone's language ahead of time, maybe on your own database, you can set this language when you create their session. So it opens in the right language without relying on the browser at all. So the flow meets the user in their own language automatically with 54 to choose from. So, if we take a look at

## Mobile vs desktop, and the QR handoff

[04:49](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=289s) this preview, you see most people end up verifying on their phone. And that kind of makes sense, right? The camera makes capturing a document and a selfie super easy. Someone would just point their phone at this QR code and they'll be able to continue the verification process on their phone. When someone lands on this page on desktop, you could see here we can actually continue on desktop, but that's an option. You can force people to just verify through their mobile, but you can absolutely enable desktop and and let them finish right here on the computer instead. But if you do, just know that the livveness check gets forced to passive on desktop because the active version doesn't really play nicely with computer webcams. And what I mean by active versus passive is where you have to

## The hosted flow vs building your own screens

[05:34](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=334s) blink on the camera. That's an active livveness check. Whereas passive is just a a photo. So the simplest path to get started is the hosted flow. You see when I hit this copy link and I open it up in my my browser. You could send the user a link and Didit handles all the hard parts for you. So the camera permissions, the document capture, the livveness, every fiddly device quirk. So you can drop this into your app through the SDK, an iframe, a redirect, or a pop-up. And if you'd rather build your own screens from scratch, you totally can. But then you're on the hook for all of that. We get into the integration side properly in another video, but for now just know that the link that you're sending that you're getting from this workflow is the hosted flow and it's tuned to get people through to the end.

## Detecting the issuing country

[06:20](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=380s) Okay, so back into the flow. When the document step needs to know which country the ID is from, most of the time the flows already figured that out. It geoloccates the user from their IP the moment the page loads and pre-selects the issuing country. And here you can see that it's worked out. And if your workflow only allows one country anyway, that's just going to get selected automatically and they're never going to see this picker. Uh this example here is a KYC flow, but this is going to be exactly the same for KYB or any other workflow that you build. The engine just runs whatever steps that are configured inside of your workflow. So next, as you can see here on this preview, the user

## Choosing a document type

[07:00](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=420s) is going to pick which government document they're going to show. So didit recognizes seven named types. There's passport, identity card, residence permit, driver's license, health insurance card, tax card, and social security card. But this list is filtered down to only the ones that are actually valid for the country we just detected. So the user can't pick something Didit can't read. And again, if your workflow only allows for a single document type, this whole screen gets skipped and they

## Capturing the document

[07:26](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=446s) go straight to the capture page. So if we continue, we go to the capture page. So, as you can see here in this preview, I am on my desktop and so I can upload a file or I can take a photo. So, forcing a live capture instead. It's going to drive guided real-time photo with no uploads allowed. And that's your strongest setting against tampered or recycled images. So, on the upload side, the accepted formats are your classics, JPEGs, PGs, PDFs, and a few other file types, all under 10 megabytes. And if it's a PDF and it's password protected, it'll prompt for the password. So we can either upload or we can force a live capture and that's all configurable inside of your workflow settings. So as you can see here in this preview as they line up the document ondevice cues are checking the lighting and the sharpness and it captures automatically the moment the shot is good enough so the analysis can start right away. And it's not just reading the text off the card. Didit is running authenticity and tamper checks, a document livveness check that catches things like a photo of a screen or a printed copy. It's also doing security features and checking the MRZ validation across more than 130 document languages.

[08:37](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=517s) And the thing that really sets this apart is it's all happening in real time. So the user finds out instantly if a document didn't work and you get the exact same data at the same moment. So everybody wins on speed. So for the

## The liveness selfie

[08:50](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=530s) livveness check, they can take a selfie. The user just centers their face in the oval that will appear on the screen from this step that you can see here. And behind that simple screen, there's a livveness check proving a real present human is actually in front of the camera. And that's also what lets Didit match the face against the document they just submitted. So you could choose which livveness method runs here. And you can set it per workflow node, which we are going to get into in other

## Passive, 3D flash and 3D action

[09:17](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=557s) videos. And there are three different settings. We've got passive where the user does nothing. We've got 3D flash where colored lights build a depth map and still asks the user to do nothing and a 3D action which adds the lights plus a randomized little action like blinking or turn the head. So it's one selfie step with three livveness strengths that you get to pick from. So

## The liveness video and scores

[09:41](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=581s) let's take a look at what that livveness step gives you. It records a short video of the person and scores it. So, if we go over to the user verifications and maybe we scroll down and take a look at one of the users here, we can look into their profile. And don't worry, we're going to get into everything that's inside of this verification check in another video. But just to show you what the livveness check actually does and what it gives you inside of your profile is a short video that you can see here.

[10:08](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=608s) So, we could play the video. And yes, this is just a video for demo purposes, but this is what will actually show up for each of your users in the verification step. We have a livveness score here in a percentage. I'm going to get into that in another video. So each of the methods, the passive or the active, spits out a livveness score from one to 100. And it runs presentation attack and deep fake detection on top.

[10:30](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=630s) So the video gets saved right alongside the score. And you can come back and replay the video and read every score right here in the verification check. and also in the user's profile. So you walk away with the selfie video plus the livveness and the deep fake scores

## What happens when a step fails

[10:45](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=645s) replayable whenever you need them. So what happens when a step fails? The user doesn't hit a dead end. They get a specific guided retry. And in the settings inside of your workflows, you can set the maximum number of retries, the retry window. Um but we're going to get into more of the settings and how these workflows work in another video. But when they do see a retry message, it's going to be precise. something like the document expired or retake this in a stronger light, not some vague generic error. So they know exactly what to fix and how many attempts that they get is configurable as I've just shown you here in the workflow. By default, the flow just lets them keep trying until they get through because the whole goal is to finish them, not to lock them out. So attempts are tunable and the default is

## The approved screen

[11:30](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=690s) built so the user can always reach the end. So when every required check passes, the user lands here. So, a green check and a plain language. You've been verified. It tells them there's nothing more that they need to do and they can head back to your app. And here's the part that they don't see. Your app has already gotten the verdict in real time before they even tap away. So, approved is this green reassuring end screen and

## The under-review screen

[11:54](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=714s) your back end already has the results. So, sometimes an automated check raises a warning rather than a clean pass or fail. When this happens, the user is going to end up seeing an orange clock instead of this green check mark. With the text underneath, your submission is under review. So on your side, the verification is going to come in to here under review. And it's going to be up to you, somebody on your team, to either pass them, to approve their application, to decline, to ask them to resubmit with more information. And the cool thing is that user is going to get an email the moment the status changes on their

## The declined screen

[12:30](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=750s) verification request. So if a check genuinely fails, they're going to get a clear declined state. So they're going to get a red mark with the words, "We couldn't verify your information at this time," which explains the outcome without giving away any of your fraud logic. So what happens next is entirely up to your workflow. You can let them resubmit within whatever attempt budget that you set or route them into a support flow inside of your own app. So declined is a clear non-technical end

## Redirect vs webhook: which one to trust

[12:58](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=778s) screen and you decide whether that means resubmit or support. So two things happen at the very end of this workflow and it's worth knowing which one to trust. Right? So first the user's browser bounces back to your app. So they land right back where they started but that part is really just a handoff for them. The thing you actually rely on is the result that your server gets at the same moment sent straight to your back end the instant the decision is made and that's the version that you build your logic on. Never what's just sitting in the browser. The nuts and bolts of wiring that up are a whole video on its own. And so we'll save that for later. But the takeaway here is simple. The user returns to your app and your system already has the real trusted

## Finding the session in your dashboard

[13:41](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=821s) results waiting. Every verification is going to show up in the user verifications tab. We got the filters here. We could see approved, in review, approved, declined, and depending on the outcome of the verification and the workflow that they've gone through, then that status is going to update accordingly. Now, the ones that are in review are obviously the ones that you're going to need to pay most attention to. So, we can filter that out and just have all these in here for human review. And with each of these verification checks, we can click in and we can see every piece of evidence behind the results. And this value down here, the vendor data, this is the ID that your own system sent across when it created the session. It's your stable reference for that person.

[14:25](https://www.youtube.com/watch?v=LzGe-dMWjUw\&t=865s) And Didit groups every session that shares the same vendor data ID under one profile?


# Connect Didit to Claude With MCP
Source: https://docs.didit.me/academy/mcp-claude

Video transcript: connecting Didit's MCP server to Claude - running KYC checks, querying sessions, and editing fraud rules from chat.

<VideoEmbed title="Connect Didit to Claude With MCP - Run KYC and Fraud Rules by Chat" />

Full transcript of **Connect Didit to Claude With MCP - Run KYC and Fraud Rules by Chat** - Didit Academy video 4 of 10, 10:50. [Watch on YouTube](https://www.youtube.com/watch?v=I3UkFIhW548). Each paragraph links to the exact moment in the video.

## What you'll build

[00:03](https://www.youtube.com/watch?v=I3UkFIhW548\&t=3s) In this video, you're going to connect Didit straight to Claude and then get real work done just by typing what you want in plain English. So, building a workflow, clearing your review queue, setting up fraud rules. All of it just from the chat. And the thing that makes this possible is the MCP, which lets an AI assistant securely use Didit's own tools. So, let's start with what this connection actually

## The hosted MCP server

[00:31](https://www.youtube.com/watch?v=I3UkFIhW548\&t=31s) gives you and get it set up. So, Didit ships a hosted MCP server, so any MCP client can drive the whole platform. And so, the three products that you should already know by now map straight onto this one connector. So, there's nothing really new to learn about Didit itself. You just type what you want. Claude calls the matching tool and shows you the result. So, anytime it's about to change something, it'll ask you to confirm if you do have permission set inside of Claude. So, one connector turns Claude into a full Didit operator. So, we could see here at the top, we've just got a a link here that we can add straight into Claude. So, I'm going

## What the connector actually gives you

[01:11](https://www.youtube.com/watch?v=I3UkFIhW548\&t=71s) to click that in just a second. But, what do you actually get with this MCP? Cuz this isn't just some wrapper around one endpoint. The connector exposes 108 different tools across 12 tool sets that covers sessions, workflows, KYB, fraud rules, cases, lists, webhooks. Basically, everything that you can do in this dashboard and all the data points, you can access through the MCP. And the cool thing is, you don't actually need to put in any API keys. You can just do an OAuth authentication one click. I'm

## Adding the connector in Claude

[01:42](https://www.youtube.com/watch?v=I3UkFIhW548\&t=102s) going to show you and walk you through that in just a moment. So, let's add the Claude connector. So, we can add this in Claude desktop, right? We can add it in Claude code. We can set it up in CodeX. All sorts of different options for you there. All All so let's just click this link and add the connector straight into Claude, shall we? So we can add a custom connector. This is in the web version.

[02:02](https://www.youtube.com/watch?v=I3UkFIhW548\&t=122s) We can add for now, and you can see it's added the MCP, but we're not connected to Didit yet. So we can click connect. You will sign in here. You'll log in. You'll authenticate. It'll redirect you back to Claude. And so when you come

## OAuth: authorizing without API keys

[02:16](https://www.youtube.com/watch?v=I3UkFIhW548\&t=136s) through to authorize the application, this is the screen that you're going to see. And this is what permissions you're giving it. All right, so I'm just going to hit authorize, and you can see at the top connected to Didit. So I'm just going to see what we've got here. So you can see if we click that plus button, you can see connectors. I can see Didit is connected

## Listing the available tools

[02:38](https://www.youtube.com/watch?v=I3UkFIhW548\&t=158s) here. So if I say "What tools do I have access to?" We'll be able to see the list of tools that we have access to here inside of Claude. So just like I mentioned earlier, we've got 121 tools that we've got access to in here. This is the list of everything. Now, don't worry if this seems like a lot. This is just all of the the data points that we can tap into inside of Didit. So yeah, from here in this chat, you can just describe what you want, and it's going to build it for you through the MCP.

## Claude Code, Codex and ChatGPT

[03:12](https://www.youtube.com/watch?v=I3UkFIhW548\&t=192s) Now, if you are using a different tool like ChatGPT or Claude code, I mean Claude code is the same process. You'd have to just add the MCP URL, and then go through the authentication, signing with your account. It's going to be very similar for ChatGPT. I've got a few prompts here that I've I've developed, so I'm going to throw them in, and we'll see what we can create. Now, of course, you can create workflows. You can check your review

## Querying your review queue

[03:39](https://www.youtube.com/watch?v=I3UkFIhW548\&t=219s) queue, all of this stuff. So So you can see we've got a permissions box show here. It's going to ask us to use this specific tool. Going to click always allow, or you can change to just allow once. I'm going to hit always allow. So, we can see the result set is pretty large. So, perhaps we could have filtered it and said, "How many verification sessions do I have in review in the last 7 days?" Now, because I am using a demo account here, nobody is actually going in and approving any of the verifications that are in review.

[04:11](https://www.youtube.com/watch?v=I3UkFIhW548\&t=251s) So, the situation for you and your business, you'll have somebody doing that daily, depending on the volume that you're running. You're not going to have a huge backlog. So, you can see it's just pulling live data from our account, and let's get into an actual build. So, I'm going to pop this prompt in here, "Build

## Building a KYC workflow from one prompt

[04:26](https://www.youtube.com/watch?v=I3UkFIhW548\&t=266s) me a KYC verification workflow." And then we're going to name the checks that we want. So, I want an ID document check that reads the document, extracts the data, passive liveness, face match, AML screening. Once it's built, set it as my default workflow. So, we do have another permission request that is going to ask you these permissions every time it's using a new tool. Boom, so we're done.

[04:46](https://www.youtube.com/watch?v=I3UkFIhW548\&t=286s) That workflow is built. That was super quick. It was probably like 10, 20 seconds. So, let's go over to Didit and

## Checking the result in the console

[04:54](https://www.youtube.com/watch?v=I3UkFIhW548\&t=294s) go into our workflows tab. Give it a refresh. And we can see KYC, liveness, AML, face match. And you can see last updated 1 minute ago. It's created as a graph workflow.

## Asking for a conversion-lift recommendation

[05:12](https://www.youtube.com/watch?v=I3UkFIhW548\&t=312s) Boom. Pretty cool. So, what else can we build here? Well, I've got another prompt that I think would be really useful if you've been using Didit for some time and you already have some data. "Take a look at my current workflows and my recent conversion data, then suggest one specific change that would lift my pass rate without weakening fraud protection. Please show me the exact update before you apply anything." So, now again, I will say the account that I'm connected to is a demo account, so it doesn't have a ton of actual data, but we'll we'll see what it can come back with. That took a few minutes, but we do have some results back. We could see what's happening over the last 30 days.

[05:52](https://www.youtube.com/watch?v=I3UkFIhW548\&t=352s) 443 sessions started, 84% conversion. But, look at the automated decision before human review. So, auto approved 338, auto routed to in review, so 24% of all sessions, and then 24 declined. So, we could see it's just done an analysis of the approvals and the verifications. So, we could see the mechanism your default workflow ends in a blanket determine. So, I'm not going to read through everything here. It has suggested one change, replace the default workflow as blanket auto decide with the same AML score bands. So, low score AML false positives get auto approved instead of clogging review.

[06:31](https://www.youtube.com/watch?v=I3UkFIhW548\&t=391s) Kind of interesting. And you can run this analysis on your own account with your own data. And you can use AI to to help pull insights instead of having your team spend, you know, hours looking at your numbers and your reports. It's great just to pull reports straight from Claude. You can pull specific numbers. You can even create a nice formatted PDF report straight here from Claude that you can download, that you can present in your meetings. So, this is just a really cool way of accessing all of your data and then using AI to analyze it all in one place. You can see it's made a suggestion of what to change here. It's validated the analysis, and then we can go ahead and ask it to implement these updates. Like you see, if the publish live step is what gave you pause, you can apply it as an unpublished draft.

[07:22](https://www.youtube.com/watch?v=I3UkFIhW548\&t=442s) Yeah.

## Applying the change as an unpublished draft

[07:26](https://www.youtube.com/watch?v=I3UkFIhW548\&t=446s) So, we're going to apply it as a draft. So, if you did want to do this with a live workflow, and you wanted to check everything first before you change something that's live, then we can go ahead and do that, and you can see it's updated. So, we'll check that in a second. We'll just set this other

## Writing transaction monitoring rules

[07:41](https://www.youtube.com/watch?v=I3UkFIhW548\&t=461s) prompt off. to set up two real-time transaction monitoring rules. So a velocity rule that flags too many transactions in a short window and a structuring rule that captures amounts kept just under reporting threshold. Back test both against the last 90 days of my history and show me what they'd have flagged before we turn them on. So this can be super useful if you want to develop new rules that might make your verification process smoother, faster, and easier.

[08:09](https://www.youtube.com/watch?v=I3UkFIhW548\&t=489s) And then you can back test your data. So if we go over to didit, let's just take a look at the workflow that we had created. We can see the version history and we can see boom, we've got a draft here in the version history. Got the V2, we can publish that and boom, it's done that and you can see here at the bottom we do have the branching, which is the update that it was suggesting based off the AML screening. All right, so we've got a few questions here. Cord is asking

## Answering the clarifying questions

[08:35](https://www.youtube.com/watch?v=I3UkFIhW548\&t=515s) us what the velocity rule should be. So how many transactions in what window? Let's do three in an hour. What reporting threshold and just under band? So we're going to flag Yeah, the 10K threshold. Let's do all apps, all categories. Boom. So it's just getting clarification on the specifics of the rules that we want to set up because I noticed that I didn't actually specify that.

[09:00](https://www.youtube.com/watch?v=I3UkFIhW548\&t=540s) So it needs that information to create the rules and to run the back tests.

## Back-testing against 90 days of history

[09:05](https://www.youtube.com/watch?v=I3UkFIhW548\&t=545s) So we can see it's completed the back test. It did take a few minutes to go through all of this data. You know, looking back, I should have specified a specific time period or a specific amount of records to back test on. You know, if you have tens or hundreds of thousands of transactions inside of your account, then that might be something to consider or using a model like Sonnet that would be much quicker. So we can see it's flagged a few users here where the transactions over three in one hour. And we've got the structuring multiple payments underneath that threshold. And you can see extrapolated to the full history, we've got a an analysis here. I'm not I'm not going to read through absolutely everything here, but you can see two things worth noting before you enable.

[09:51](https://www.youtube.com/watch?v=I3UkFIhW548\&t=591s) It's given us some suggestions here. So, refine the rules, extend the back test. Uh we could even send a webhook to your Slack whenever these kinds of transactions come through or whenever somebody meets these specific rules. So, I'm just scratching the surface with what's possible here with these AI tools when you integrate with Didit. You can use it for analysis, intelligence, for flagging specific issues, for crunching

## Recap

[10:15](https://www.youtube.com/watch?v=I3UkFIhW548\&t=615s) data, for building, for editing, the whole works. And that's the Didit MCP from end to end. One hosted connector, an OAuth login with no keys to paste, and 108 tools that let you build workflows, clear reviews, set up fraud rules, and figure out your declines, all just by asking. So, if you want to try it yourself, head over to didit.me, sign up for free, and add the connector just following the steps in this video.


# Didit Academy
Source: https://docs.didit.me/academy/overview

Didit Academy video course with full transcripts: platform tour, KYC, KYB, workflows, transaction monitoring, integration and pricing.

[Didit Academy: Identity Verification & Fraud Prevention](https://www.youtube.com/playlist?list=PLIikxNViJoCY) is the official video course on the [Didit YouTube channel](https://www.youtube.com/channel/UCDnTpf4XOflvmwVdMiPSRIA). Every video has a full, timestamped transcript here - each paragraph deep-links into the exact moment on YouTube.

<Columns>
  <Card title="Platform Tour: KYC, KYB & Transaction Monitoring" href="/academy/platform-tour">
    Video 1 of 10 - 10:59. Full transcript with timestamps.
  </Card>

  <Card title="What Users See in a KYC Verification" href="/academy/kyc-user-experience">
    Video 2 of 10 - 14:36. Full transcript with timestamps.
  </Card>

  <Card title="Build a KYC Workflow With No Code" href="/academy/build-kyc-workflow">
    Video 3 of 10 - 18:54. Full transcript with timestamps.
  </Card>

  <Card title="Connect Didit to Claude With MCP" href="/academy/mcp-claude">
    Video 4 of 10 - 10:50. Full transcript with timestamps.
  </Card>

  <Card title="How to Read a Verification Result" href="/academy/verification-results">
    Video 5 of 10 - 14:26. Full transcript with timestamps.
  </Card>

  <Card title="KYB Explained: Registry to UBO" href="/academy/kyb-explained">
    Video 6 of 10 - 11:05. Full transcript with timestamps.
  </Card>

  <Card title="Real-Time Transaction Monitoring Rules" href="/academy/transaction-monitoring">
    Video 7 of 10 - 13:05. Full transcript with timestamps.
  </Card>

  <Card title="Integrate Didit: API, SDK and Webhooks" href="/academy/integrate-api-sdk">
    Video 8 of 10 - 08:13. Full transcript with timestamps.
  </Card>

  <Card title="Didit Analytics, Teams and Roles" href="/academy/analytics-teams-roles">
    Video 9 of 10 - 06:37. Full transcript with timestamps.
  </Card>

  <Card title="Didit Pricing Explained (Video)" href="/academy/pricing">
    Video 10 of 10 - 09:08. Full transcript with timestamps.
  </Card>
</Columns>


# Platform Tour: KYC, KYB & Transaction Monitoring
Source: https://docs.didit.me/academy/platform-tour

Video transcript: a full tour of the Didit console - dashboard, credits, KYC sessions, KYB, transaction monitoring, directory, API and MCP.

<VideoEmbed title="What Is Didit? Full Platform Tour - KYC, KYB & Transaction Monitoring" />

Full transcript of **What Is Didit? Full Platform Tour - KYC, KYB & Transaction Monitoring** - Didit Academy video 1 of 10, 10:59. [Watch on YouTube](https://www.youtube.com/watch?v=skV9iUR2UhQ). Each paragraph links to the exact moment in the video.

## What this course covers

[00:03](https://www.youtube.com/watch?v=skV9iUR2UhQ\&t=3s) Welcome to Didit. If you're just getting started, this is a quick tour of the whole platform. So, by the end, you'll know your way around and find anything on your own. That's the whole platform in one pass. Three products that follow your customer from the moment they sign up all the way through to ongoing monitoring, every check and every transaction rolling up into one profile, and you can work with all of it here in the dashboard, over on the API, or through an AI tool. If you want to jump in and try it, head to didit.me. You can sign up for free, and you can run your first verification in just a couple of minutes. Okay, so this is the first thing that you see when you log in. This

## The home dashboard

[00:44](https://www.youtube.com/watch?v=skV9iUR2UhQ\&t=44s) is the home dashboard. This is where you're going to do everything in Didit. Build your verification flows, read your results, watch for fraud, handle your billing, and manage your team. So, over here on the left, this is the navigation rail, and that's basically the map of the whole platform. So, we're going to walk through this together. I'm going to take you through each of the tabs, so you know exactly where to go for each of the products and each of the settings inside of Didit.

[01:10](https://www.youtube.com/watch?v=skV9iUR2UhQ\&t=70s) So, in the middle, that you can see here, this is a live overview of your traffic. So, on this side, where we see needs review, this is anything that's waiting on a human to make a decision. Over here, we've got recent activity, which is basically a live feed of everything happening across all of the

## Environments, credits and pay-per-success

[01:26](https://www.youtube.com/watch?v=skV9iUR2UhQ\&t=86s) three products in real time. So, up here, you could see production environment, and this switcher lets you flip between your live app, your sandbox. You can obviously add another application here as well. And down here in the corner, this is where we've got the balance, so you can add your own credits, discounts if you add higher amounts into here. And Didit is pay per success, so you load up your credits and you only get charged when a check actually completes.

[01:56](https://www.youtube.com/watch?v=skV9iUR2UhQ\&t=116s) So, that's the home base. We're going to get into all of these different menus and the analytics and the dashboard uh in this video and later videos, but this is where you're going to be spending most of your time. So, before we go any further, the simplest way to think about Didit it is really three products. They

## The three products, one customer lifecycle

[02:12](https://www.youtube.com/watch?v=skV9iUR2UhQ\&t=132s) follow the life of your customer. So, first you authenticate, so you make sure that they're a real person. Then you verify them, so things like KYC, KYB, biometrics, and AML. Then you monitor them for fraud. Those are the three products we've got. User verification, so KYC. We've got business verification, KYB. And then we've got transaction monitoring, which watches the money flow. Just a quick note, the wallet and crypto screening aren't a separate product. They live inside the transaction monitoring, which we are going to get into in a lot more depth in other videos.

[02:49](https://www.youtube.com/watch?v=skV9iUR2UhQ\&t=169s) So, we've got three products, one customer life cycle. So, let's dig into

## User Verification (KYC): sessions and checks

[02:53](https://www.youtube.com/watch?v=skV9iUR2UhQ\&t=173s) the first product, shall we? User verification or KYC. So, we can just tap into this tab here. And you can see every verification that's been run on a person. Each one's called a session. So, a single KYC check can bundle a few different things together. Government ID check that actually reads the document in any language, not just basic text scanning. We've got the liveness selfie. We've got the face match between the two, the selfie and the ID. And plus got some background checks, proof of address, email verification, device and IP, all of this stuff. So, you could see here that the icons and these represent the checks that happen inside of this workflow that you could see tagged here.

[03:36](https://www.youtube.com/watch?v=skV9iUR2UhQ\&t=216s) So, right now you could see we've got multiple statuses in this window. If we go back to the home page, we could see all of these need review. If we click view all and we go over back to the verifications tab, we can see that it's added the filter, right? So, if you want to add a filter for in review, we want to set a specific date range, we can do all of that in this dashboard. Whenever somebody gets tagged in review, this

## The review queue and webhooks

[03:59](https://www.youtube.com/watch?v=skV9iUR2UhQ\&t=239s) means that the system can't auto decide. This means we need a human on your team, someone in the compliance, someone in your in your review team to actually come along and check out why this person was flagged for in review. And the second a decision is made, it's also pushed straight to your own back end by webhooks. So, your entire system knows instantly when someone has passed or is in review. So, we're going to get into reading a full result in another video, but the short version, KYC

## Business Verification (KYB)

[04:27](https://www.youtube.com/watch?v=skV9iUR2UhQ\&t=267s) confirms a real person. So, let's get into KYB, so business verification. So, this one confirms a company instead of a person. It checks the business against official registries, it maps out who actually owns it, so the beneficial owners and the officers, and it can run an identity check on each of those owners all in one session. So, as you can see here, we've got the registry check, just like we saw in the user verifications, we've got these icons here that represent each of the checks that happen inside of a specific workflow. Don't worry, we're going to get onto workflows in a minute.

[05:02](https://www.youtube.com/watch?v=skV9iUR2UhQ\&t=302s) So, you end up with the company's details, the key people getting verified, and all the supporting documents in one place. We're going to build a full KYB workflow end to end in another video, but for now, KYB verifies

## Transaction Monitoring (fiat and crypto)

[05:14](https://www.youtube.com/watch?v=skV9iUR2UhQ\&t=314s) a company and the real people behind it. Let's take a look at the transaction monitoring tab here. This is the third product, and this is the fraud detection side of Didit. So, verifying someone at sign up only really covers them for the verification on day one. This part runs continuously after a user or business has onboarded and been verified. So, you could see here, we've got some payments declined, some approved, and again, we've got the filter section here at the top, and we can click this button, and it's going to automatically apply the filter to include all of the transactions that are in review. So, you send each payment over to Didit and a real-time rule engine scores it and opens a case if something looks off. So, it works for anything that moves money.

[05:54](https://www.youtube.com/watch?v=skV9iUR2UhQ\&t=354s) So, fiat or crypto. And remember that wallet and crypto screening is built right in here. I'm not going to get into too much detail in this video. I'm just giving you an overview of each of these individual products. So, if you go back to the home page, you can notice the transaction flow in the same activity feed as your verifications. So, you can see here we've got transaction, we've got KYB, KYB. So, everything runs through in this recent activity panel here on your home page. Listen, there's a lot more under the hood here, but the point is simple. Didit watches money movement in real time right next to

## The Directory: one profile per person

[06:27](https://www.youtube.com/watch?v=skV9iUR2UhQ\&t=387s) identity. Let's look at the directory tab at the top here. Let's go into users. So, this where everything ties together. We're going to look into the directory. We're going to check out the users. And everything we just looked at, the verifications and the transactions, all of it rolls up here into one profile per person. So, you can see here we've got a person here. You can see the checks that they've gone through. One session, we've got the country, and we have their user ID. So, each row is one individual. You've got the name, you've got the country, and Didit stacks up everything that person has ever done under this one single profile. You can see these little green icons here like you saw in the verifications and the KYB. These are all the checks that they've passed at a glance. So, you can see we've got ID verification, the liveness, the face match, the device and IP analysis. And this number here is every session stacked up under that one person. You can see just one session for this particular profile. You're also going to see the vendor data value. So, when we open up a profile, you also see a vendor data value. And that's the idea that your system sends across when it creates a session. So, in this case, it is an email address, but it can be a random number that's unique to this person. In this account, it's an email, but it can be any stable ID that your system uses. And below it is Didit's own internal ID for this profile. So, the vendor data is the key that ties everything together. So, every session that comes in with the same vendor data

## The business directory and linked fraud signals

[07:48](https://www.youtube.com/watch?v=skV9iUR2UhQ\&t=468s) lands under this same person. Okay, so let's head over to the business directory. That's where your verified companies roll up in exactly the same way, one profile per company. So, every person in every business carries a single status, active, flagged if something needs a look at, like an AML hit, or blocked. Over in the business directory, when we click on a business, you're going to get their complete profile. So, we've got the overview, profile, the verifications, transactions, payment methods, documents, devices, location, cases, activity. Everything is here under this one business entity, because their verifications and their money all live under the same profile. So, a payment gets judged against who the person actually is. So, this is how Deduct can catch things that disconnected tools just can't, like the same device showing up across accounts, sudden spikes in activity, or whole networks of linked people. So, one profile gives you the full fraud picture. Let's go back to the home dashboard and check out some more of these tabs down here. So, down at the bottom of the rail, there are two

## Configure vs Manage

[08:52](https://www.youtube.com/watch?v=skV9iUR2UhQ\&t=532s) sections where you set Deduct up. So, we've got the configure tab here, and we've got the manage tab. So, configure is everything that your users will see and experience. So, that's workflows, so where you build your verification flows, customization for your branding, questionnaires for any custom questions, and lists for your allow and block lists. And don't worry, we're going to get into these in other videos. But, just a little preview here in the customizations tab, you can actually see how this verification flow looks and how you can customize it. So, the second panel here on the left is manage, and this is how Deduct connects to your own app. So, that's where you integrate it, you grab your API keys, you set up your webhooks. So, results get pushed to you, and it's also where you handle your team and pull your reports. We're going to spend whole videos inside both of these tabs later on, but for now, configure builds the experience and manage connects it to your product. So, the

## Building your own dashboard

[09:46](https://www.youtube.com/watch?v=skV9iUR2UhQ\&t=586s) last thing I want to talk about here is back on the home page, we can actually build our own dashboard. So, the cool thing here is we can actually add cards however we want. So, these widgets, demographics, conversion rate, the locations, we can add them, we can drag and drop, we can move them around. We've got these filters here, we can filter by different date ranges. We can also look at the performance of specific workflows, and we can see all of that in this customizable dashboard below. So, the last thing to note is that everything that I've just walked you through, so creating sessions, building workflows, reading results, changing a

## Doing all of it over the API and MCP

[10:18](https://www.youtube.com/watch?v=skV9iUR2UhQ\&t=618s) status, all of that you can also do in code. So, you can grab an API key under the manage tab here on the left, and the whole platform is yours over a simple API. So, you can build your own dashboards, you can automate anything without ever logging in to this dashboard. You do all of that inside of Codex or Claude Code, also with the MCP server. So, we're going to get into that in another video, but that is the dashboard at a glance. And there's another way to work with Didit on top of that. It has an MCP server with over 100 tools, which lets AI assistants like Claude, Cursor, and Codex work with it directly. So, you can use Didit right here in the dashboard, in your own code, or straight from an AI tool.


# Didit Pricing Explained (Video)
Source: https://docs.didit.me/academy/pricing

Video transcript: how Didit pricing works - pay per successful check, 500 free checks a month, per-feature prices, no contracts or minimums.

<VideoEmbed title="How Much Does Didit Cost? Pricing Explained (500 Free Checks a Month)" />

Full transcript of **How Much Does Didit Cost? Pricing Explained (500 Free Checks a Month)** - Didit Academy video 10 of 10, 09:08. [Watch on YouTube](https://www.youtube.com/watch?v=aTWy1rfChhI). Each paragraph links to the exact moment in the video.

## Why Didit publishes its pricing

[00:04](https://www.youtube.com/watch?v=aTWy1rfChhI\&t=4s) Let's talk about what Didit actually costs. Most verification vendors hide their pricing behind a sales call, but Didit puts everything out into the open so you can work out your own costs

## The pricing page

[00:16](https://www.youtube.com/watch?v=aTWy1rfChhI\&t=16s) before you ever sign up. So, let's head over to the pricing page and break it all down. Okay, so let's start right here on the pricing page. And notice I didn't have to log in to see any of this pricing. Didit publishes every price openly, which most vendors simply won't do. The model is simple. You start free and you pay per successful check for only the modules that you turn on. And you can scale all the way to enterprise on the same account. And every module's price is listed here with no minimums and no contracts to begin. And you're charged only for the checks that you actually run. So you can compare the

## The three plans

[00:52](https://www.youtube.com/watch?v=aTWy1rfChhI\&t=52s) cost of each check before you ever sign up. So as you can see here there's three plans and the thing to understand is that you pick by volume and the terms that you need not by features because the same modules are available on every plan. So there's three tiers. There's free, there's usage based and there is enterprise. Free gives you 500 verifications every month plus blocklist and duplicate detection checks on every session. Usagebased is payer use across dozens of modules with no monthly minimum fee. An enterprise adds a custom master service agreement, an SLA for large volumes and regulated programs. So you're choosing by volume and terms and the same checks. They're on all three.

## What the free plan really includes

[01:38](https://www.youtube.com/watch?v=aTWy1rfChhI\&t=98s) Now, if we take a look at the free plan, this is a real production tier. This is not a sandbox. It cost \$0 a month and needs no credit card. And several anti-fraud checks are already included on every session at no cost. So, every session is screened against your block lists for free. Duplicate detection captures the same person signing up

## 500 free credits, every month

[02:01](https://www.youtube.com/watch?v=aTWy1rfChhI\&t=121s) twice, which is matched on the vendor data ID that you send over. And over 200 device and IP fraud signals get analyzed on every session, again, at no cost. So, it's a free tier that you can genuinely run in production. You get 500 free verification credits every month, and I'm going to show you the features that you can do that on in just a second. So, if we go into Didit and we check out the workflows and let's say if we So, let's say we open up a new workflow, we do user verification, uh we do simple workflow, start from scratch, you're going to see the pricing of each of the modules. So you can see ID verification

## The usage-based plan

[02:41](https://www.youtube.com/watch?v=aTWy1rfChhI\&t=161s) 500 free per month, livveness 500 free and face match 500 free. And also I mentioned earlier the device and IP analysis again you get 500 free verifications. So the allowance resets on the first of each month. And while unused checks don't roll over, you always get a fresh 500 and it's permanent, not a timelimited trial. So that's 500 free identity checks a month forever. Now, if we take a look at the usagebased plan here in the middle. So, when you outgrow your free tier, you move to usagebased, the pay-per-use plan. It's the same account, no migration. You just start paying for what you run beyond the free allowance.

[03:21](https://www.youtube.com/watch?v=aTWy1rfChhI\&t=201s) It's essentially pay as you go across dozens of modules. So, again, if we go back into the workflow, we could see what modules that we're going to need to pay for straight out the gate and which modules we're going to have to pay for after we've used up our 500 free credits. So you can turn whatever modules on or off that you want to use in your verification flows and you'll only pay for the successful checks that a user goes through. So that's why we see at the top here we've got a price from \$0 to 15. And if we click on the

## How a workflow's price is assembled

[03:52](https://www.youtube.com/watch?v=aTWy1rfChhI\&t=232s) pricing, we can see how this workflow is priced. So you see you only pay for the steps that actually run. So if somebody enters the workflow and leaves immediately or after that first check, you're not going to pay anything because the first check is ID verification which is free. You're not going to pay anything because the ID verification you get 500 free. Okay? And after that it's

## KYB pricing

[04:15](https://www.youtube.com/watch?v=aTWy1rfChhI\&t=255s) only going to be 15 cents. So that's going to be the maximum cost of this workflow. And it's the same for KYB. So the business verification. So, if we go into a KYB workflow, we can take a look at some of the modules inside of there. If we zoom in here, we could see the registry check \$2. The KYB is variable because it's going to depend on how many people we need to verify on that step.

[04:39](https://www.youtube.com/watch?v=aTWy1rfChhI\&t=279s) Got the AML screening. If we want to add in any additional checks, we can do that here. And just know this AML screening is 20 cents per check, but that runs people against over 10,000 data sets covering sanctions, PEPS, adverse media.

## Database validation pricing

[04:55](https://www.youtube.com/watch?v=aTWy1rfChhI\&t=295s) So the only other module that is variable on cost is the database validation. So if we add that node into here, we click database validation and you see the panel that opens up here on the right. You can see we can select whichever database validation we want to run. And this is country specific and database specific. You can see if we want to run a credit check, it's going to cost us more than checking the consumer data, for example. But the cool thing is you can see the cost of absolutely every check in here. So you're not going to be surprised when somebody runs through this workflow and you're you're wondering why is this costing so much? The price is going to appear up at the top here. And you can see it is variable. It just depends on how far somebody gets through this step.

[05:40](https://www.youtube.com/watch?v=aTWy1rfChhI\&t=340s) So if I select a database in here, you can see it's going to give us a a price

## White-label pricing

[05:44](https://www.youtube.com/watch?v=aTWy1rfChhI\&t=344s) down here. So the only other thing that I haven't mentioned here is the white labeling. So if you want to set up the white labeling, we can turn that on. It's going to cost 20 cents per verification. And you can see when we toggle this on, the price at the top, it's going to change. So this is going to consider the

## No minimums, no contracts

[06:03](https://www.youtube.com/watch?v=aTWy1rfChhI\&t=363s) cost of absolutely everything inside of this workflow. You can see custom branding extra 20 cents. So with Didit there are no minimums. There's no contract on the self-s served plans and there's nothing to commit upfront. So if you spend nothing in a quiet month your account stays open and with the free 500 a month still available. So if you spend nothing in a quiet month your account stays open with the free 500 a month credits still available. Uh the usage plan has no monthly floor, no platform fee, no seat fee. So your bill is

## Why the prices are this low

[06:34](https://www.youtube.com/watch?v=aTWy1rfChhI\&t=394s) exactly your usage and nothing more. You might be wondering how the prices come in this low. You see, Didit runs its own optimized verification infrastructure with sub 2C inference? And that's why a complete identity check from about 30 cents is typically 70 to 80% cheaper than comparable providers for the same checks. And because it's all published openly, you can compare line by line instead of negotiating a

## Enterprise

[07:01](https://www.youtube.com/watch?v=aTWy1rfChhI\&t=421s) hidden quote. So for large volumes and regulated programs, there's enterprise. It gives you custom pricing with volume discounts on top of the public per module rates. You also get access to a dedicated Slack channel, the WhatsApp channels with manual reviewers on demand and reseller and white label terms with four deployed engineers who build alongside you. at high volume, the team genuinely recommends it because they like working closely with customers to fit into their flows and improve their KPIs. So, if you're running serious volume here, that's the conversation to have. So, let's head over to the billing

## Billing, top-ups and auto-recharge

[07:40](https://www.youtube.com/watch?v=aTWy1rfChhI\&t=460s) section inside of our dashboard here. The bottom here, we have our current balance. This is where you're going to get build from. So, you're going to need a prepaid balance to use Didit. Now, as you can see here, there are discounts depending on how much you decide to top up. You can also set the auto recharge function as well, so you can keep running your checks without your balance going to zero. So, if we head over to the settings tab here, we can head over to billing. And again, we've got options to top up. We've got previous deposit history in here as well. And the amount that you top up in here, your credits, they never expire. So, if you need your invoices for your accounting team, you can just come in here and download them.

## The usage tab

[08:18](https://www.youtube.com/watch?v=aTWy1rfChhI\&t=498s) So if we head over to the usage tab, this is where you're going to see exactly where your credits go. So you can see the spend breakdown module by module and you can filter by date range at the top here and by application. So if you have multiple applications, you can see which application is spending on which checks. So the whole thing is

## Recap

[08:38](https://www.youtube.com/watch?v=aTWy1rfChhI\&t=518s) refreshingly simple. You start free every month and you only pay for the checks that you actually use. And the credits that you buy, they don't expire. So, there's no contracts, no hidden fees, and you can see every price for yourself before you commit a penny. Honestly, the best way to know your real number is to just start using it. So, head over to diddit.mme, sign up for free, and run your first verification in a couple of minutes today.


# Real-Time Transaction Monitoring Rules
Source: https://docs.didit.me/academy/transaction-monitoring

Video transcript: setting up real-time transaction monitoring - fraud rules for fiat and crypto, alerts, cases, and wallet screening.

<VideoEmbed title="Real-Time Transaction Monitoring: Fraud Rules for Fiat and Crypto" />

Full transcript of **Real-Time Transaction Monitoring: Fraud Rules for Fiat and Crypto** - Didit Academy video 7 of 10, 13:05. [Watch on YouTube](https://www.youtube.com/watch?v=Yhm63_n7HuU). Each paragraph links to the exact moment in the video.

## What this video covers

[00:04](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=4s) In this video, you'll see how Didit watches the money moving through your app and catches the transactions that should worry you. Checking who someone is when they sign up is one thing, but it doesn't tell you what they'll do once they start moving money around. That's the job of transaction monitoring. It scores every payment the moment it lands, ties it back to the person who made it, and flags the things that actually matter. So, a sudden spike in activity, a payment that's far too big, or a match against a sanction list. It works for regular money and for crypto, all against rules that you set yourself.

[00:40](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=40s) So, let's open it up and walk through it. All right, so we can head over to the

## The live transaction feed

[00:45](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=45s) transactions tab here on the left. And this is a live feed of every payment Didit is watching. So, it's ranked by date, so the newest first, and each row is one economic event. So, we're talking a deposit, a withdrawal, a transfer, a payment, a payout, or a bet. And every one of them gets scored and decisioned in real time as it arrives. So, the place that you'll probably want

## The review queue and filters

[01:12](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=72s) to head to first is this tab here, 100 transactions to be reviewed. We'll click on that, and it's going to automatically filter out the transactions that need to be reviewed by your team. And if you want to see everything, we can add the filter all statuses. We can refine this if we want, if we want to select a specific day in the last 7 days, for example. If you want to search for a specific transaction ID or a Didit ID. If we want to look in specific currencies, etc.

[01:42](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=102s) But for today, we're just going to flip the status to in review, and these are the ones we're going to walk through because these are going to be most important for you and for your own use cases. So, we

## Every transaction tied to an identity

[01:52](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=112s) can see this transaction here is connected to a specific identity because nobody in your platform is going to be able to complete transactions without going through the KYC or KYB. We can see the type. This is crypto in this scenario. The amount, any tags that are involved, and the date that it was created. Now, one thing to note here is that we actually have the counterparty

## Counterparty screening

[02:15](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=135s) here. They also get screened against sanctions and watch lists. The same AML engine that your identity checks already use. You can see we've got the score here. I'm going to jump into the transaction. I'm going to show you exactly what's going on here. So, if we click on one of these, again, I will preface this by saying this is this is demo data. This is not a real transaction, but to show you how this works, I want to walk you through each of these tabs. So, if we scroll down, each of these tabs corresponds to a tab up top here. Just like in the KYC and KYB, we can change the status here, download as a PDF, we can add to a block

## The overview tab and risk score

[02:49](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=169s) list. So, let's take a look, right? So, in the overview section, we've got the risk score. So, this is medium. Uh it's been flagged as in review. We can see all of the warnings here. So, in the crypto monitoring, cuz this is a crypto

## Wallet risk and what the score bands mean

[03:01](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=181s) transaction, we see there's a high wallet risk score. And we can read what this actually means. So, if the risk score sits between 70 and 89, it's going to escalate it for review. So, wallets at this score have a meaningful exposure to illicit clusters, like mixers, darknet markets, and scams. So, these are all the things that we want to be looking out for when we're reviewing this particular transaction. We could see it's been flagged for a large single

## Vendor data

[03:28](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=208s) transaction. Now, just like with the KYC and KYB, we've got the vendor data here. So, all of these transactions for this particular vendor data, so in this case we're using an email, and it can be a unique identifier. So, this person will have gone through KYC. And all of the transactions that correspond to this vendor data will be

## How the risk score is calculated

[03:52](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=232s) flagged underneath this particular user. So, you might be thinking, well, where does this score come from? You could see the risk score is 284, there's three rules matched, eight rules evaluated, and one open alert. Like, what's going on here? Well, every transaction is decisioned the moment it arrives, and each rule that matches adds to a cumulative risk score. And so, your thresholds decide when that

## The four transaction statuses

[04:17](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=257s) score is high enough to send it to review or to decline it outright. So, in transactions, there are actually four statuses. We've got approved, meaning the transaction is clean, in review, like this particular example here, we've got declined, and then we also have awaiting user. So, when a rule needs a bit more assurance before it lets a payment through, the status flips to awaiting user. So, Didit quietly spins up a linked verification session, hands back a URL, and the user re-verifies themselves, and the transaction picks up where it left off.

## Getting transactions into Didit

[04:51](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=291s) So, before we start digging through all of this information here, how do we actually get transactions into Didit? Well, we can import them from a CSV or a list. We can integrate, which is going to be the obvious option for for most of you watching this. You integrate with the SDK. And we can also create a manual transaction, and this really is only going to be for testing purposes.

[05:15](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=315s) It's going to be a massive hassle to create a manual transaction every time a transaction runs through your company. So, if you click integrate, you can see we can just literally copy the prompt, select an API key, and then we can paste that into our cloud code or code X, and it will automatically set up the installation, so that your transaction monitoring is completely set up. Okay, so let's work through some of these checks and tabs here, and let me explain what each of them mean. Now, there is a lot of information in in but the reason why this account was flagged is because of the rules, and we'll get into the rules

## Transaction details

[05:49](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=349s) section uh a little bit later on. But, we can see here this this is all of the transaction details that we've got here, crypto outbound, uh the country from Argentina to Netherlands, the transaction ID, the payment ID, payment details, and the vendor data, and the the currency amount. We've got the AML risk score. This just means the score that we get from the anti-money laundering module.

[06:13](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=373s) We can look at all of the specifics of the transaction, the chain, the wallet risk, in this case potential scam wallet risk, the beneficiary wallet, and the wallet score risk. We've got some alerts here, the simulated crypto exposure. This is demo crypto transaction flagged by synthetic monitoring metadata, and

## The crypto exposure visualization

[06:30](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=390s) medium. We've got the crypto monitoring. This is really cool. Let's click visualization, and you're going to be able to see the visualization of the wallets, how they're connected, the transactions. So, this can be really useful if you're trying to spot scams, and mixers, things like this. So, we've got the whole transaction overview here. You can see we've got an analysis here from Merkle Science. This is a third-party tool that you can integrate here into Didit for crypto screening and transaction analysis. If we keep going down here, this is all part of the crypto

## Counterparties

[07:03](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=423s) monitoring from Merkle Science, transaction summary, exposure table, and then we get to the counterparties. So, this is the person who is receiving the the funds in this particular transaction. We can see this person is not verified inside of the current system, so it's going to check if this particular wallet is already inside your platform, and then this is the important part down here at the bottom. These are

## Triggered rules

[07:27](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=447s) the triggered rules. So, we're going to look at these rules in a moment and see how we can set these up for our transaction monitoring, but if you click on each one of these, you could see what each rule is all about. So, we've got the rule identity, the trigger, the conditions, the actions, deploy settings. I'm going to run you through these in just a moment. You see there's related transactions down here.

[07:48](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=468s) Yeah, it's a lot of information, but the the thing to focus on is the rules. So, let's go ahead and create some rules,

## Creating a rule

[07:55](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=475s) shall we? Now, there is a library of rules. These are defaults that you can set up when you start a brand new account. We've got the installed rules that you can set up manually. We can create the rules here, so rules are essentially filters. So, if this happens, then do this. That's essentially what a rule is doing. So, we can give it a name. We'll call it test. We can add a description if we want. We can add a specific category.

## Triggers

[08:18](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=498s) So, let's say we select geography and we move over to the trigger. Triggers on all transactions. We could specify by the channel, so crypto or fiat. Let's do crypto.

## Conditions

[08:29](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=509s) The entity type, we can specify by individual or company. I'm going to do individual. We go through to the conditions. We can look for, I don't know, travel rule. Uh we can look for subjects. We can look for the country equals maybe if we put a high-risk country on there, somewhere in Africa, for example. We can add an additional condition here as well. So, if someone's putting multiple transactions through in a short space of time from this country, then that's what this rule is going to flag. And then we

## Actions and scoring

[09:01](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=541s) can decide whether that's going to decline the transaction or put them into review. So, you can see here, choose what happens on a match. We change the status, right? We could add points. Okay, so that's what I was mentioning earlier. That's how the score is calculated. So, we can say add maybe 50 points in here, for example. And then

## Back-testing and deploy settings

[09:24](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=564s) we've got the deploy settings. We can back test the rule to see how many hits this rule is going to get. Now, this is important because if you have a very restrictive rule, that's going to mean a lot more work for your team. So, you've got to evaluate the the risk versus reward of setting up these kinds of rules and how strict you want to be with this. Now, you can see on here, each rule shows you how often it fired and how much of that was sent to review or declined. For example, you got this percentage just here, and this is the data that you're going to lean on to tune the rule. So, if setting up your own rules seems like a lot of work, you could just actually have a conversation with Claude and say, "We want to filter out these kinds of people or these kinds of transactions.

## The rule library

[10:07](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=607s) We want to detect this kind of behavior from these countries." You can also look in the library and we've got different categories here. We've got AML, nominee detection, crypto monitoring, device intelligence, finance for protection, responsible gaming, travel rules, and so there's a library of different rules that you can pull from inside of there. So, there's one condition in this rule

## Velocity conditions

[10:33](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=633s) that I was working on earlier is the velocity condition. And this is pretty clever. So, instead of judging one payment in isolation, a rule can add up or average activity over a specific window of time. So, anywhere from an hour to 90 days, grouped by the user, the device, the IP, the payment method, or the counterparty. So, that's how you're going to catch structuring and sudden bursts that no single transaction would ever reveal.

[10:59](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=659s) So, we could hit velocity condition. So, we can do the count of transactions in the last 24 hours for the same user, and we can specify is greater than, let's say, five, for example. So, that's the velocity condition. I think that's pretty clever. I've not seen this in any other platform. The idea being that AI can surface hidden patterns from your own history. Now, you could do this with Claude right now. You could hook up the MCP, ask Claude to analyze your data, and create rules

## Turning on crypto monitoring

[11:26](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=686s) based on the patterns that it's seeing. So, if you were wondering where to turn on crypto compliance and the crypto monitoring integration. You can see here in the transactions tab, we can go to settings. We can adjust the risk threshold and then we can select the crypto monitoring Merkle Science. We can turn that on 15 cents per check. You can bring your own key, that's going to be happening sometime soon in the future. So, we can flip that on or off to your own needs.

[11:54](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=714s) So, one final thing on the dashboard,

## Transaction analytics

[11:56](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=716s) again, we can adjust our analytics here to include transaction monitoring as well. So, if you click on add, we can come through to transactions. We can take a look at the volume, for example, the action breakdown, approved versus rejected, and then we can add that to our analytics dashboard. And you can see that's going to appear down at the bottom here. And to move these tabs around, we just click edit, and we can let say we remove this one, and yeah, we can move these around like this. We can change whatever order we want them in.

## Recap

[12:34](https://www.youtube.com/watch?v=Yhm63_n7HuU\&t=754s) So, that's transaction monitoring end-to-end. Every payment scored the moment it lands. So, regular money and crypto, all through one engine, each one tied back to a verified person or business. And anything suspicious flagged for your team to review and act on. If you want to try it for yourself, you can head over to didit.me, sign up for free, and send your first transaction today.


# How to Read a Verification Result
Source: https://docs.didit.me/academy/verification-results

Video transcript: every check in a Didit verification result explained - document authenticity, liveness, face match, IP analysis, warnings.

<VideoEmbed title="How to Read a Didit Verification Result - Every Check Explained" />

Full transcript of **How to Read a Didit Verification Result - Every Check Explained** - Didit Academy video 5 of 10, 14:26. [Watch on YouTube](https://www.youtube.com/watch?v=7htTWCWsl60). Each paragraph links to the exact moment in the video.

## What this video covers

[00:03](https://www.youtube.com/watch?v=7htTWCWsl60\&t=3s) Every verification you run in Didit comes back as a detailed result and that result is laid out as a row of tabs across the top of a session. In this video, we're going to go walk through those tabs in order left to right so you know exactly what each check does and what it looks like when one of them fails. And by the end, you'll be able to open any session and read it with confidence from the headline verdict right down to the evidence behind it.

[00:30](https://www.youtube.com/watch?v=7htTWCWsl60\&t=30s) So, let's open one up and get stuck in.

## Finding a session

[00:33](https://www.youtube.com/watch?v=7htTWCWsl60\&t=33s) Okay, so let's navigate to the user verifications. This is where every session is going to appear from all of your workflows. It's going to be one row per person. And normally you'd filter by status, workflow, or date to find whatever you need, but today we're just going to go straight into a single result. So, I'm just going to click on one of these and open it. So, right here we can see this

## The overview tab

[00:55](https://www.youtube.com/watch?v=7htTWCWsl60\&t=55s) is the overview tab. These are collapsible so we can collapse these. We can collapse all the checks if we want if we want to see everything, but honestly they're all up here as well. So, you could see this particular user has passed all of these specific checks. So, if we just head over to overview, we

## Warnings: where to look first

[01:13](https://www.youtube.com/watch?v=7htTWCWsl60\&t=73s) can pull that out and you can see we've got a few different tabs here. Now, the most important thing to check out here is the warnings. So, you could see this user is in review and you can see they've been flagged for a duplicate phone number. Okay, so if we check out other people that are in review, we could see the warnings in the overview section might look a little bit different. Based on the flags from the workflow, this particular user has gone through. You could see the database validation and the name mismatch. So, this is where we need to look if we're reviewing a verification and we need to figure out what the issue is and then we can go to the specific section and we can see where these checks actually are and we can look at the data that's been submitted to see if there is indeed a mismatch and what's really going on there. Now, if we remove all of these filters, so I can just come out of here,

## An approved session

[02:04](https://www.youtube.com/watch?v=7htTWCWsl60\&t=124s) we can remove these filters. So, I'm going to select all of these and let's see if we go into someone who has been approved, we can see there's there's no major warnings that have been flagged. We can see this has been listed under the warnings, but it's not triggered the in review or the decline. This has actually been approved. We can see this little pill up here and we can actually change these as needed. We'll get into

## A declined session

[02:26](https://www.youtube.com/watch?v=7htTWCWsl60\&t=146s) that in a little moment. And what does it look like when someone has been declined? We can see here the warnings, again, the name mismatch. And then up here at the top, we can see proof of address is the one that caused some issues. So, we can come in and take a look at this as well. So, we're going to go through each section one by one so you could see exactly what's happening underneath the hood. So, I'm just clicking into this profile here and you can see the liveness and the face match is where this particular user has been flagged for checking. So, we'll get to that in a moment. But the rest of the

## Session details, vendor data and cost breakdown

[03:01](https://www.youtube.com/watch?v=7htTWCWsl60\&t=181s) tabs in the overview section, we've got session details, so you've got the session ID, when it was created, the vendor data. So, we spoke about this in previous videos. The vendor data is a unique identifier for this particular user. This is where all of the \[snorts] checks, all of the verifications and transactions are going to be collected under the specific vendor data. We can see the workflows that this user has gone through for the verification. We've got the contact details here and any tags. I mean, we can we can add a tag here if you want.

[03:31](https://www.youtube.com/watch?v=7htTWCWsl60\&t=211s) We can tag people in workflows as well. Now, the total cost breakdown, I believe this this user was imported. You can see here on the left, it was imported, so he hasn't actually gone through a workflow. Let's click this other user here and you can see the workflow that they've gone through and you can see the cost

## ID Verification: authenticity before data

[03:48](https://www.youtube.com/watch?v=7htTWCWsl60\&t=228s) breakdown of all the checks this user has completed. So, let's take a look at the ID verification. Now, the main job is not just reading text off the card. It's It's proving the document itself is genuine before anyone trusts a single field on it. So, under the hood, we're running tamper detection, document liveness to catch a screen replay or a printed copy, security feature validation for holograms and watermarks, and a a cross-check between the printed fields and the machine-readable zone, the MRZ, the block of chevron characters at the back that you could see here on this particular ID. Now, once the document is proven authentic, Dedit will read the fields with OCR and lay them out. Here, you can see the personal data. Got the document type, the document number, personal number, issuing state, all of the information that you would find on the ID, including the address data and any additional data in here. And remember, Dedit can read more than 130 languages across 14,000 document types. So, you're going to get clean fields

## The checks list

[04:47](https://www.youtube.com/watch?v=7htTWCWsl60\&t=287s) wherever someone presents their ID. So, there is a tab here called checks list. And these are the checks that are running in the background on this specific ID. So, I'm not going to read through all of these. There is a lot here, but this is essentially how Dedit is verifying that this is an authentic ID. So, you don't have to configure any

## Liveness: score, video and quality

[05:07](https://www.youtube.com/watch?v=7htTWCWsl60\&t=307s) of this. This is all running in the background. So, the next check is the liveness check. You can see that this particular check is in review. This is what's been flagged. You can see liveness and face match. Now, I will say this is a demo account, so some of this data is not matching. Um you can see the liveness score is it's not 100%, and if we play the liveness video, you could see it's it's not actually the person.

[05:30](https://www.youtube.com/watch?v=7htTWCWsl60\&t=330s) This is just a random example. Now, if you were to see this on a on a real user, you would see the the person doing the liveness check, the video, whether it's passive or active. We've got the face quality score and the face luminance score. And the cool thing about Dedit is if you're confused about any of these scores, you can just click this button here and it'll give you an explanation of what this does. We can change the status of any of these checks if we believe that this has been flagged inappropriately, and obviously we can change the overall status of this verification. Again, just like the ID verification, we've got a checks list and there's a bunch of checks here that are all happening in the background, right? And we can hover over these and we can see a little bit more information about each of these checks. And if somebody fails any of these tests, instead of the green

## Face Match

[06:16](https://www.youtube.com/watch?v=7htTWCWsl60\&t=376s) tick, there's going to be a red X. So, if we keep going, we've got the face match tab. This is going to match the face on the ID with the face in the liveness check. And you can see here, obviously the similarity score is pretty low because they're not really the same person. And again, we've got a checks list of what's happening in the background there and what this particular check is doing. So, the similarity score is based on the original ID and the liveness image that we've captured. And this is to figure out if the person holding the ID is a genuine owner. Now, we're not going to see this in the dashboard, but there is a face

## Face Search and block lists

[06:54](https://www.youtube.com/watch?v=7htTWCWsl60\&t=414s) search. So, beyond matching against the document, Didit searches the same face across all of your other sessions. So, this part only shows when it finds a match. So, if the same face turns up in another session, a grid of matches is going to appear here. And if one of those matched faces is on a block list that you maintain, it's going to be flagged and the session will be declined, which is how a known fraudster gets stopped on site. But on a clean session with no matches, this area stays

## Proof of Address

[07:21](https://www.youtube.com/watch?v=7htTWCWsl60\&t=441s) empty, so we're not going to see anything here. Let's move on to proof of address. We can see the document that was submitted and the data that was extracted from this particular document with all of the metadata. So, we've got a checks list here and we can see one of the checks does not have a green tick, meaning that this check was being flagged. And we can see one is in review. Now, that's not enough for this proof of address module to be flicked over to declined, but this is again something that your human reviewer is going to be looking at when they come to a profile that is in review. And a pass here means the code was entered correctly and a failure means the number couldn't be confirmed, and you'll see that reflected in this module here. So, you remember at the top, one of the flags here was duplicate phone number, and now that's probably due to this being a demo

## Phone verification and duplicates

[08:08](https://www.youtube.com/watch?v=7htTWCWsl60\&t=488s) account, but you could see when we scroll down under the phone verification, we could see phone matches. Now, this is going to search the phone number on your database, and if it matches anything from a previous user, then this is going to be flagged in this tab here. We can also hover over here. We can see other verification sessions that use the same phone number. This is just an explanation of what this module does.

## Email verification

[08:35](https://www.youtube.com/watch?v=7htTWCWsl60\&t=515s) Same for email verification, the user is going to receive a code and put the

## AML screening: sanctions, PEPs and adverse media

[08:40](https://www.youtube.com/watch?v=7htTWCWsl60\&t=520s) code, and if everything's good, then this module is also approved. Now, the anti-money laundering, the AML screening, there's quite a lot going on here. This checks the verified person against sanction lists, politically exposed persons, adverse media, and then reports how many matches were found. So, you could see the data that it's using to screen, and we can actually see the list. So, if I open this up, we could see all of the sanction lists here that we can run the checks against. So, narcotics, terrorism, financial crime, everything. And we can see if this user has matched on any of the lists, we could see here the match score, the risk score, and the lists that this user has appeared on and whether it's a false positive or not. Now, a false positive can occur if the name matches somebody on one of those lists. So, this is where we have other information like the date of birth to to cross-reference. We do have a checks list here again. Uh it's pretty short for this particular one, but the the checks against all these lists is doing the heavy lifting here.

[09:41](https://www.youtube.com/watch?v=7htTWCWsl60\&t=581s) And if you want to have this person monitored ongoing, where we can check the lists against this user on an ongoing basis, we can actually turn that on. If we keep moving down, we can see

## Device and IP analysis

[09:50](https://www.youtube.com/watch?v=7htTWCWsl60\&t=590s) the device IP analysis. So, we have the ID verification document location. So, the actual address from the document. We have the address details here for the proof of address. And then we have the device information. So, the IP address and where that person is actually completing the verification from. And we could see at the bottom the document location versus the proof of address, how far away those distances and those locations are from the verification IP. And we can see all of that on this map. So, we see if we hover over here, we've got the ID verification document location.

[10:28](https://www.youtube.com/watch?v=7htTWCWsl60\&t=628s) Got device number one, so they're pretty close. And then we have the proof of address in the US here. Again, this is a demo account, so these details are not particularly accurate, but this just gives you a good understanding of is that person close to where the proof of address and their ID actually is. And here we have the checks list again, and these are all the checks that ID it is doing in the background to decide whether to flag \[snorts] this particular check or not. If we keep going down, we've got database validation. So, if you remember in previous videos, we spoke about database validation. It's a node that you can add in a workflow. And what we can do here is we can run a check. And for this example, we can run

## Database validation: full, partial and no match

[11:06](https://www.youtube.com/watch?v=7htTWCWsl60\&t=666s) a check in Argentina, and we can check against a government registry, civil registry, the tax authority, the electoral roll, all of these different directories that we do have access to. You could see we have a match found here. And you could see the source data, the fields that match on the results. So, we've got a full name match and a date of birth match. And if we open up the checks list, we can see one of these checks was flagged.

[11:29](https://www.youtube.com/watch?v=7htTWCWsl60\&t=689s) And we can see here the match type. Now, if a full match has been found, it means the identity exists in the registry. Partial match means some fields matched and you should review the rest. And a no match is a strong synthetic identity signal because a fabricated ID number simply isn't in any registry. And this is one of the strongest defenses you have against made-up identities. And again, it runs in the background with no

## Document AI and questionnaires

[11:54](https://www.youtube.com/watch?v=7htTWCWsl60\&t=714s) extra steps for the user. Now, moving on, we do have a few other tabs here and these can vary depending on the checks that this particular user has gone through. We can see document AI. This check hasn't run. You can see not started. There are other checks that we do have for questionnaires. If somebody ends up filling out a questionnaire, we could see the answers to those questions in

## The event log

[12:15](https://www.youtube.com/watch?v=7htTWCWsl60\&t=735s) the questionnaire tab. And then if we keep on moving down, we've got the events. So, this is a audit trail, a log of all of the events that happened. So, when the session was created, when the session status changed, and each entry carries the device, the IP, the timing, who did it, so you can reconstruct

## Webhook deliveries

[12:31](https://www.youtube.com/watch?v=7htTWCWsl60\&t=751s) exactly how a session unfolded. And then finally, at the bottom, we have webhooks. So, webhooks list every delivery Didit attempt to your own endpoint with the response status. We can see 200 here. And we could see the request header, the body, the webhook URL, the status of this particular verification. And we've also got the date here this webhook was sent. So, one thing to note here is that this dashboard can be accessed through the API through the MCP. You can ask Claude to pull all of this data, to pull all of your verifications that are in review that you can analyze inside of

## Resubmission, PDF export and block lists

[13:08](https://www.youtube.com/watch?v=7htTWCWsl60\&t=788s) Claude as well. Now, if you take a look at the top here, we've got some breadcrumbs and we can see we can request resubmission. We can download the PDF, which is excellent if you want to have an audit trail or you need to present something in a meeting. Um you can also access this download through the API and you can add this person to a block list. So, that is how you read a verification

## Session chat for your review team

[13:30](https://www.youtube.com/watch?v=7htTWCWsl60\&t=810s) result. There's one last thing at the bottom here. We've got a session chat. So, we can actually tag team members, and we can talk about a specific verification result with somebody on our team. So, if we opened up this chat and we put in a message and we tagged someone on our team, that's going to be specific for this particular verification. So, if we do have a question or there's multiple people working on this case, this chat is going to be incredibly useful.

[13:55](https://www.youtube.com/watch?v=7htTWCWsl60\&t=835s) So, that's a verification result read the way you'll actually read it, tab by tab, top to bottom. The verdict and the warnings on overview, then each check in turn, and the full audit trail at the end. So, once you've done it on one session, every other session reads the same way. And if you want to try it on your own data, head to didit.me, sign up for free, and open your first result.


# Argentina Citizens (AFIP)
Source: https://docs.didit.me/api-reference/database-validation/argentina/citizens

POST /v3/database-validation/
Verifies input data to the AFIP (Administracion Federal de Ingresos Publicos). Authoritative real-time identity lookup for Argentina. Real-time lookup, pay-per-call.

<div />

Verifies input data to the AFIP (Administracion Federal de Ingresos Publicos). Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 90%
* **Country:** Argentina
* **Service ID:** `arg_citizens`
* **Data domain:** Identity
* **Category:** Citizenship

## Inputs

| Field             | Required | Example      |
| ----------------- | -------: | ------------ |
| `first_name`      |      Yes | `John`       |
| `last_name`       |      Yes | `Doe`        |
| `date_of_birth`   |      Yes | `1990-01-01` |
| `document_number` |      Yes | `1111111`    |
| `vendor_data`     |       No | `user-1234`  |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `document_number`
* **Optional inputs:** `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 90%
* **Price:** \$1.90 per successful query

## Body parameters

<ParamField type="string" placeholder="ARG">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `ARG`
</ParamField>

<ParamField type="string" placeholder="arg_citizens">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `arg_citizens`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="1111111">
  Document number extracted from or provided by the user.

  Example: `1111111`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Argentine DNI (7-8 digits)
* `document_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `document_number` must be 7-8 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=ARG" \
    -F "services=arg_citizens" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "document_number=1111111"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "ARG",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "arg_citizens",
        "service_name": "Argentina Citizens (AFIP)",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": true,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "ARG",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "arg_citizens",
        "service_name": "Argentina Citizens (AFIP)",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": false,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ARG",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "arg_citizens",
        "service_name": "Argentina Citizens (AFIP)",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `arg_citizens` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `full_name`
* `identification_number`
* `last_name`
* `name_match_score`

## Pricing & SLAs

Argentina Citizens (AFIP) queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$1.90 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Argentina Database Validation overview](/api-reference/database-validation/argentina)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Argentina Credit Bureau
Source: https://docs.didit.me/api-reference/database-validation/argentina/credit-bureau

POST /v3/database-validation/
Verifies input data against Credit Header data obtained from a Credit Bureau in Argentina. Authoritative real-time identity lookup for Argentina. Real-time lookup, pay-per-call.

<div />

Verifies input data against Credit Header data obtained from a Credit Bureau in Argentina. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 90%
* **Country:** Argentina
* **Service ID:** `arg_credit_bureau`
* **Data domain:** Financial
* **Category:** CreditBureau

## Inputs

| Field             | Required | Example      |
| ----------------- | -------: | ------------ |
| `first_name`      |      Yes | `John`       |
| `last_name`       |      Yes | `Doe`        |
| `date_of_birth`   |      Yes | `1990-01-01` |
| `document_number` |      Yes | `1111111`    |
| `vendor_data`     |       No | `user-1234`  |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `document_number`
* **Optional inputs:** `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 90%
* **Price:** \$2.15 per successful query

## Body parameters

<ParamField type="string" placeholder="ARG">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `ARG`
</ParamField>

<ParamField type="string" placeholder="arg_credit_bureau">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `arg_credit_bureau`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="1111111">
  Document number extracted from or provided by the user.

  Example: `1111111`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Argentine DNI (7-8 digits)
* `document_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `document_number` must be 7-8 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=ARG" \
    -F "services=arg_credit_bureau" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "document_number=1111111"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "ARG",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "arg_credit_bureau",
        "service_name": "Argentina Credit Bureau",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": true,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "ARG",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "arg_credit_bureau",
        "service_name": "Argentina Credit Bureau",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": false,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ARG",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "arg_credit_bureau",
        "service_name": "Argentina Credit Bureau",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `arg_credit_bureau` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `full_name`
* `identification_number`
* `last_name`
* `name_match_score`

## Pricing & SLAs

Argentina Credit Bureau queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$2.15 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Argentina Database Validation overview](/api-reference/database-validation/argentina)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Argentina - DNI verification (RENAPER)
Source: https://docs.didit.me/api-reference/database-validation/argentina/renaper

POST /v3/database-validation/
Verifies Argentine DNI against the official RENAPER civil registry, with biometric face-match against the photo on file. 100% population coverage. Authoritative real-time identity lookup for Argentina. Real-time lookup, pay-per-call.

<div />

Verifies Argentine DNI against the official RENAPER civil registry, with biometric face-match against the photo on file. 100% population coverage. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** Argentina
* **Service ID:** `arg_renaper`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field             | Required | Example         |
| ----------------- | -------: | --------------- |
| `document_number` |      Yes | `1111111`       |
| `selfie`          |      Yes | `@./selfie.jpg` |
| `gender`          |      Yes | `M`             |
| `first_name`      |       No | `John`          |
| `last_name`       |       No | `Doe`           |
| `vendor_data`     |       No | `user-1234`     |

* **Required inputs:** `document_number`, `selfie`, `gender`
* **Optional inputs:** `first_name`, `last_name`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** —
* **Price:** \$0.20 per successful query

## Body parameters

<ParamField type="string" placeholder="ARG">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `ARG`
</ParamField>

<ParamField type="string" placeholder="arg_renaper">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `arg_renaper`
</ParamField>

<ParamField type="string" placeholder="1111111">
  Document number extracted from or provided by the user.

  Example: `1111111`
</ParamField>

<ParamField type="file" placeholder="@./selfie.jpg">
  Selfie image file to upload for biometric database validation. Accepted formats: JPEG, PNG, or WebP.

  Example: `@./selfie.jpg`
</ParamField>

<ParamField type="string" placeholder="M">
  Gender value, when required by the database.

  Allowed values: `M` (male), `F` (female), `X` (other or unknown).

  Example: `M`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Argentine DNI (7-8 digits)
* `document_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `document_number` must be 7-8 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=ARG" \
    -F "services=arg_renaper" \
    -F "vendor_data=user-1234" \
    -F "document_number=1111111" \
    -F "selfie=@./selfie.jpg" \
    -F "gender=M"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "ARG",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "arg_renaper",
        "service_name": "Argentina - DNI verification (RENAPER)",
        "source_data": {
          "banks": "sample_value",
          "date_of_birth": "1990-01-01",
          "face_match_score": "0.990",
          "first_name": "John",
          "full_name": "John Doe",
          "highest_position": "sample_value",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "last_position": "sample_value",
          "rejected_checks": "sample_value",
          "sit_1_since": "sample_value",
          "tax_id": "SAMPLE-12345",
          "tax_id_type": "SAMPLE-12345"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ARG",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "arg_renaper",
        "service_name": "Argentina - DNI verification (RENAPER)",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```

  **`BIOMETRIC_NO_MATCH`** — The face-match score was below the acceptance threshold - the selfie is not the same person as the registry photo.

  ```json 200 OK — BIOMETRIC_NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ARG",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "BIOMETRIC_NO_MATCH",
        "service_id": "arg_renaper",
        "service_name": "Argentina - DNI verification (RENAPER)",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```

  **`BIOMETRIC_IMAGE_UNUSABLE`** — The selfie could not be processed (empty, no face, low quality, or the registry could not read it). Prompt the user to retake the selfie.

  ```json 200 OK — BIOMETRIC_IMAGE_UNUSABLE theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "ARG",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "BIOMETRIC_IMAGE_UNUSABLE",
        "service_id": "arg_renaper",
        "service_name": "Argentina - DNI verification (RENAPER)",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `arg_renaper` currently documents this normalized shape:

* `banks`
* `date_of_birth`
* `face_match_score`
* `first_name`
* `full_name`
* `highest_position`
* `identification_number`
* `last_name`
* `last_position`
* `rejected_checks`
* `sit_1_since`
* `tax_id`
* `tax_id_type`

## Pricing & SLAs

Argentina - DNI verification (RENAPER) queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.20 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Argentina Database Validation overview](/api-reference/database-validation/argentina)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Australia - DVS - Birth Certificate
Source: https://docs.didit.me/api-reference/database-validation/australia/birth-certificate

POST /v3/database-validation/
Verifies input data against the Document Verification Service (DVS). Authoritative real-time identity lookup for Australia. Real-time lookup, pay-per-call.

<div />

Verifies input data against the Document Verification Service (DVS). Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 100%\*
* **Country:** Australia
* **Service ID:** `aus_birth_certificate`
* **Data domain:** Identity
* **Category:** BirthRecord

## Inputs

| Field                       | Required | Example              |
| --------------------------- | -------: | -------------------- |
| `first_name`                |      Yes | `John`               |
| `last_name`                 |      Yes | `Doe`                |
| `date_of_birth`             |      Yes | `1990-01-01`         |
| `birth_registration_number` |      Yes | `SAMPLE-BIRTH-12345` |
| `birth_registration_date`   |      Yes | `1990-01-01`         |
| `birth_registration_state`  |      Yes | `Sample State`       |
| `middle_name`               |       No | `Demo`               |
| `vendor_data`               |       No | `user-1234`          |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `birth_registration_number`, `birth_registration_date`, `birth_registration_state`
* **Optional inputs:** `middle_name`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow with field mapping
* **Coverage:** 100%\*
* **Price:** \$0.45 per successful query

In a workflow, `birth_registration_date` and `birth_registration_state` are not printed on an identity document, so no step produces them on their own. Collect them from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map each one on the Database Validation step. Until they are mapped the workflow editor shows this service disabled and names the missing input; at run time a missing input means the check is skipped before any query, so you are never billed for a database that could not be asked.

## Body parameters

<ParamField type="string" placeholder="AUS">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `AUS`
</ParamField>

<ParamField type="string" placeholder="aus_birth_certificate">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `aus_birth_certificate`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-BIRTH-12345">
  `birth_registration_number` value required by this database service.

  Example: `SAMPLE-BIRTH-12345`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  `birth_registration_date` value required by this database service.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="Sample State">
  `birth_registration_state` value required by this database service.

  Example: `Sample State`
</ParamField>

<ParamField type="string" placeholder="Demo">
  Middle name, when available.

  Example: `Demo`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=AUS" \
    -F "services=aus_birth_certificate" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "birth_registration_number=SAMPLE-BIRTH-12345" \
    -F "birth_registration_date=1990-01-01" \
    -F "birth_registration_state=Sample State"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "AUS",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "aus_birth_certificate",
        "service_name": "Australia - DVS - Birth Certificate",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "middle_name": "Demo"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "AUS",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "aus_birth_certificate",
        "service_name": "Australia - DVS - Birth Certificate",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "middle_name": "Demo"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "AUS",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "aus_birth_certificate",
        "service_name": "Australia - DVS - Birth Certificate",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `aus_birth_certificate` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `identification_number`
* `last_name`
* `middle_name`

## Pricing & SLAs

Australia - DVS - Birth Certificate queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.45 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Australia Database Validation overview](/api-reference/database-validation/australia)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Australia - DVS - Centrelink Card
Source: https://docs.didit.me/api-reference/database-validation/australia/centrelink-card

POST /v3/database-validation/
Verifies input data against the Document Verification Service (DVS). Authoritative real-time identity lookup for Australia. Real-time lookup, pay-per-call.

<div />

Verifies input data against the Document Verification Service (DVS). Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 100%\*
* **Country:** Australia
* **Service ID:** `aus_centrelink_card`
* **Data domain:** Government
* **Category:** Government

## Inputs

| Field                  | Required | Example      |
| ---------------------- | -------: | ------------ |
| `first_name`           |      Yes | `John`       |
| `last_name`            |      Yes | `Doe`        |
| `date_of_birth`        |      Yes | `1990-01-01` |
| `medicare_card_number` |      Yes | `1111111111` |
| `middle_name`          |       No | `Demo`       |
| `vendor_data`          |       No | `user-1234`  |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `medicare_card_number`
* **Optional inputs:** `middle_name`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** 100%\*
* **Price:** \$0.45 per successful query

## Body parameters

<ParamField type="string" placeholder="AUS">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `AUS`
</ParamField>

<ParamField type="string" placeholder="aus_centrelink_card">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `aus_centrelink_card`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="1111111111">
  Medicare card number.

  Example: `1111111111`
</ParamField>

<ParamField type="string" placeholder="Demo">
  Middle name, when available.

  Example: `Demo`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Australian Medicare card number (exactly 10 digits)
* `medicare_card_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `medicare_card_number` must be exactly 10 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=AUS" \
    -F "services=aus_centrelink_card" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "medicare_card_number=1111111111"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "AUS",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "aus_centrelink_card",
        "service_name": "Australia - DVS - Centrelink Card",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "middle_name": "Demo"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "AUS",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "aus_centrelink_card",
        "service_name": "Australia - DVS - Centrelink Card",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "middle_name": "Demo"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "AUS",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "aus_centrelink_card",
        "service_name": "Australia - DVS - Centrelink Card",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `aus_centrelink_card` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `identification_number`
* `last_name`
* `middle_name`

## Pricing & SLAs

Australia - DVS - Centrelink Card queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.45 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Australia Database Validation overview](/api-reference/database-validation/australia)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Australia - DVS – Change of Name Certificate
Source: https://docs.didit.me/api-reference/database-validation/australia/change-of-name-certificate

POST /v3/database-validation/
Verifies input data against the Document Verification Service (DVS). Authoritative real-time identity lookup for Australia. Real-time lookup, pay-per-call.

<div />

Verifies input data against the Document Verification Service (DVS). Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 100%\*
* **Country:** Australia
* **Service ID:** `aus_change_of_name_certificate`
* **Data domain:** Identity
* **Category:** CivilRegistry

## Inputs

| Field                               | Required | Example            |
| ----------------------------------- | -------: | ------------------ |
| `first_name`                        |      Yes | `John`             |
| `last_name`                         |      Yes | `Doe`              |
| `date_of_birth`                     |      Yes | `1990-01-01`       |
| `change_of_name_certificate_number` |      Yes | `SAMPLE-CON-12345` |
| `vendor_data`                       |       No | `user-1234`        |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `change_of_name_certificate_number`
* **Optional inputs:** `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow with field mapping
* **Coverage:** 100%\*
* **Price:** \$0.45 per successful query

In a workflow, `change_of_name_certificate_number` is not printed on an identity document, so no step produces it on its own. Collect it from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step. Until it is mapped the workflow editor shows this service disabled and names the missing input; at run time a missing input means the check is skipped before any query, so you are never billed for a database that could not be asked.

## Body parameters

<ParamField type="string" placeholder="AUS">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `AUS`
</ParamField>

<ParamField type="string" placeholder="aus_change_of_name_certificate">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `aus_change_of_name_certificate`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-CON-12345">
  `change_of_name_certificate_number` value required by this database service.

  Example: `SAMPLE-CON-12345`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=AUS" \
    -F "services=aus_change_of_name_certificate" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "change_of_name_certificate_number=SAMPLE-CON-12345"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "AUS",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "aus_change_of_name_certificate",
        "service_name": "Australia - DVS – Change of Name Certificate",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "AUS",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "aus_change_of_name_certificate",
        "service_name": "Australia - DVS – Change of Name Certificate",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "AUS",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "aus_change_of_name_certificate",
        "service_name": "Australia - DVS – Change of Name Certificate",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `aus_change_of_name_certificate` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `identification_number`
* `last_name`

## Pricing & SLAs

Australia - DVS – Change of Name Certificate queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.45 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Australia Database Validation overview](/api-reference/database-validation/australia)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Australia - DVS – Citizenship Certificate
Source: https://docs.didit.me/api-reference/database-validation/australia/citizenship-certificate

POST /v3/database-validation/
Verifies input data against the Document Verification Service (DVS). Authoritative real-time identity lookup for Australia. Real-time lookup, pay-per-call.

<div />

Verifies input data against the Document Verification Service (DVS). Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 100%\*
* **Country:** Australia
* **Service ID:** `aus_citizenship_certificate`
* **Data domain:** Identity
* **Category:** Citizenship

## Inputs

| Field                            | Required | Example             |
| -------------------------------- | -------: | ------------------- |
| `first_name`                     |      Yes | `John`              |
| `last_name`                      |      Yes | `Doe`               |
| `date_of_birth`                  |      Yes | `1990-01-01`        |
| `citizenship_certificate_number` |      Yes | `SAMPLE-CERT-12345` |
| `middle_name`                    |       No | `Demo`              |
| `vendor_data`                    |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `citizenship_certificate_number`
* **Optional inputs:** `middle_name`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow with field mapping
* **Coverage:** 100%\*
* **Price:** \$0.45 per successful query

In a workflow, `citizenship_certificate_number` is not printed on an identity document, so no step produces it on its own. Collect it from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step. Until it is mapped the workflow editor shows this service disabled and names the missing input; at run time a missing input means the check is skipped before any query, so you are never billed for a database that could not be asked.

## Body parameters

<ParamField type="string" placeholder="AUS">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `AUS`
</ParamField>

<ParamField type="string" placeholder="aus_citizenship_certificate">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `aus_citizenship_certificate`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-CERT-12345">
  `citizenship_certificate_number` value required by this database service.

  Example: `SAMPLE-CERT-12345`
</ParamField>

<ParamField type="string" placeholder="Demo">
  Middle name, when available.

  Example: `Demo`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=AUS" \
    -F "services=aus_citizenship_certificate" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "citizenship_certificate_number=SAMPLE-CERT-12345"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "AUS",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "aus_citizenship_certificate",
        "service_name": "Australia - DVS – Citizenship Certificate",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "middle_name": "Demo"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "AUS",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "aus_citizenship_certificate",
        "service_name": "Australia - DVS – Citizenship Certificate",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "middle_name": "Demo"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "AUS",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "aus_citizenship_certificate",
        "service_name": "Australia - DVS – Citizenship Certificate",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `aus_citizenship_certificate` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `identification_number`
* `last_name`
* `middle_name`

## Pricing & SLAs

Australia - DVS – Citizenship Certificate queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.45 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Australia Database Validation overview](/api-reference/database-validation/australia)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Australia Credit Bureau
Source: https://docs.didit.me/api-reference/database-validation/australia/credit-bureau

POST /v3/database-validation/
Verifies input data against Credit Header data obtained from the largest Credit Bureau in Australia. Authoritative real-time identity lookup for Australia. Real-time lookup, pay-per-call.

<div />

Verifies input data against Credit Header data obtained from the largest Credit Bureau in Australia. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 75%
* **Country:** Australia
* **Service ID:** `aus_credit_bureau`
* **Data domain:** Financial
* **Category:** CreditBureau

## Inputs

| Field                 | Required | Example                |
| --------------------- | -------: | ---------------------- |
| `first_name`          |      Yes | `John`                 |
| `last_name`           |      Yes | `Doe`                  |
| `date_of_birth`       |      Yes | `1990-01-01`           |
| `address.street_1`    |      Yes | `123 Sample Street`    |
| `address.postal_code` |      Yes | `10001`                |
| `address.street_2`    |       No | `Unit 4`               |
| `address.city`        |       No | `Sample City`          |
| `address.region`      |       No | `Sample State`         |
| `phone`               |       No | `+15550101000`         |
| `email`               |       No | `john.doe@example.com` |
| `vendor_data`         |       No | `user-1234`            |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `address.street_1`, `address.postal_code`
* **Optional inputs:** `address.street_2`, `address.city`, `address.region`, `phone`, `email`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 75%
* **Price:** \$0.70 per successful query

## Body parameters

<ParamField type="string" placeholder="AUS">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `AUS`
</ParamField>

<ParamField type="string" placeholder="aus_credit_bureau">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `aus_credit_bureau`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  Phone number in international format.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="john.doe@example.com">
  Email address.

  Example: `john.doe@example.com`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=AUS" \
    -F "services=aus_credit_bureau" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}'
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "AUS",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "aus_credit_bureau",
        "service_name": "Australia Credit Bureau",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "postal_code": "10001",
          "state": "Sample State",
          "street": "sample_value"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "AUS",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "aus_credit_bureau",
        "service_name": "Australia Credit Bureau",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "postal_code": "10001",
          "state": "Sample State",
          "street": "sample_value"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "AUS",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "aus_credit_bureau",
        "service_name": "Australia Credit Bureau",
        "source_data": {
          "address": "NO_MATCH",
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `aus_credit_bureau` currently documents this normalized shape:

* `address`
* `address_match_score`
* `city`
* `date_of_birth`
* `first_name`
* `full_name`
* `last_name`
* `name_match_score`
* `postal_code`
* `state`
* `street`

## Pricing & SLAs

Australia Credit Bureau queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.70 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Australia Database Validation overview](/api-reference/database-validation/australia)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Australia Death Check (BDM)
Source: https://docs.didit.me/api-reference/database-validation/australia/death-check

POST /v3/database-validation/
The official Australian Birth, Deaths, Marriages Register. Authoritative real-time identity lookup for Australia. Real-time lookup, pay-per-call.

<div />

The official Australian Birth, Deaths, Marriages Register. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 100%\*
* **Country:** Australia
* **Service ID:** `aus_death_check`
* **Data domain:** Other
* **Category:** DeathRecord

## Inputs

| Field           | Required | Example      |
| --------------- | -------: | ------------ |
| `first_name`    |      Yes | `John`       |
| `last_name`     |      Yes | `Doe`        |
| `date_of_birth` |      Yes | `1990-01-01` |
| `vendor_data`   |       No | `user-1234`  |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`
* **Optional inputs:** `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** 100%\*
* **Price:** \$0.05 per successful query

## Body parameters

<ParamField type="string" placeholder="AUS">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `AUS`
</ParamField>

<ParamField type="string" placeholder="aus_death_check">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `aus_death_check`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=AUS" \
    -F "services=aus_death_check" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "AUS",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "aus_death_check",
        "service_name": "Australia Death Check (BDM)",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "AUS",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "aus_death_check",
        "service_name": "Australia Death Check (BDM)",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": false
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "AUS",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "aus_death_check",
        "service_name": "Australia Death Check (BDM)",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `aus_death_check` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `full_name`
* `last_name`
* `name_match_score`

## Pricing & SLAs

Australia Death Check (BDM) queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.05 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Australia Database Validation overview](/api-reference/database-validation/australia)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# DVS - Australia Driver Licence
Source: https://docs.didit.me/api-reference/database-validation/australia/driver-licence

POST /v3/database-validation/
Verifies input data against the Document Verification Service (DVS). Authoritative real-time identity lookup for Australia. Real-time lookup, pay-per-call.

<div />

Verifies input data against the Document Verification Service (DVS). Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 100%\*
* **Country:** Australia
* **Service ID:** `aus_australia_driver_licence`
* **Data domain:** Document
* **Category:** DriverLicence

## Inputs

| Field                        | Required | Example           |
| ---------------------------- | -------: | ----------------- |
| `first_name`                 |      Yes | `John`            |
| `last_name`                  |      Yes | `Doe`             |
| `date_of_birth`              |      Yes | `1990-01-01`      |
| `driver_license_number`      |      Yes | `SAMPLE-DL-12345` |
| `driver_license_card_number` |      Yes | `87654321`        |
| `driver_license_state`       |      Yes | `Sample State`    |
| `middle_name`                |       No | `Demo`            |
| `vendor_data`                |       No | `user-1234`       |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `driver_license_number`, `driver_license_card_number`, `driver_license_state`
* **Optional inputs:** `middle_name`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** 100%\*
* **Price:** \$0.45 per successful query

## Body parameters

<ParamField type="string" placeholder="AUS">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `AUS`
</ParamField>

<ParamField type="string" placeholder="aus_australia_driver_licence">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `aus_australia_driver_licence`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-DL-12345">
  Driver licence number.

  Example: `SAMPLE-DL-12345`
</ParamField>

<ParamField type="string" placeholder="87654321">
  `driver_license_card_number` value required by this database service.

  Example: `87654321`
</ParamField>

<ParamField type="string" placeholder="Sample State">
  State or region that issued the driver licence.

  Example: `Sample State`
</ParamField>

<ParamField type="string" placeholder="Demo">
  Middle name, when available.

  Example: `Demo`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=AUS" \
    -F "services=aus_australia_driver_licence" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "driver_license_number=SAMPLE-DL-12345" \
    -F "driver_license_card_number=87654321" \
    -F "driver_license_state=Sample State"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "AUS",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "aus_australia_driver_licence",
        "service_name": "DVS - Australia Driver Licence",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": true,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "AUS",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "aus_australia_driver_licence",
        "service_name": "DVS - Australia Driver Licence",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": false,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "AUS",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "aus_australia_driver_licence",
        "service_name": "DVS - Australia Driver Licence",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `aus_australia_driver_licence` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `full_name`
* `identification_number`
* `last_name`
* `name_match_score`

## Pricing & SLAs

DVS - Australia Driver Licence queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.45 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Australia Database Validation overview](/api-reference/database-validation/australia)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Australia Electoral Roll
Source: https://docs.didit.me/api-reference/database-validation/australia/electoral-roll

POST /v3/database-validation/
The official Government Electoral Roll service. Authoritative real-time identity lookup for Australia. Real-time lookup, pay-per-call.

<div />

The official Government Electoral Roll service. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 100%\*
* **Country:** Australia
* **Service ID:** `aus_electoral_roll`
* **Data domain:** Government
* **Category:** ElectoralRoll

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `address.street_1`, `address.postal_code`
* **Optional inputs:** `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** 100%\*
* **Price:** \$0.45 per successful query

## Body parameters

<ParamField type="string" placeholder="AUS">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `AUS`
</ParamField>

<ParamField type="string" placeholder="aus_electoral_roll">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `aus_electoral_roll`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=AUS" \
    -F "services=aus_electoral_roll" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}'
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "AUS",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "aus_electoral_roll",
        "service_name": "Australia Electoral Roll",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "postal_code": "10001",
          "state": "Sample State",
          "street": "sample_value"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "AUS",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "aus_electoral_roll",
        "service_name": "Australia Electoral Roll",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "postal_code": "10001",
          "state": "Sample State",
          "street": "sample_value"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "AUS",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "aus_electoral_roll",
        "service_name": "Australia Electoral Roll",
        "source_data": {
          "address": "NO_MATCH",
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `aus_electoral_roll` currently documents this normalized shape:

* `address`
* `address_match_score`
* `city`
* `date_of_birth`
* `first_name`
* `full_name`
* `last_name`
* `name_match_score`
* `postal_code`
* `state`
* `street`

## Pricing & SLAs

Australia Electoral Roll queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.45 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Australia Database Validation overview](/api-reference/database-validation/australia)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Australia - DVS - ImmiCard
Source: https://docs.didit.me/api-reference/database-validation/australia/immicard

POST /v3/database-validation/
Verifies input data against the Document Verification Service (DVS). Authoritative real-time identity lookup for Australia. Real-time lookup, pay-per-call.

<div />

Verifies input data against the Document Verification Service (DVS). Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 100%\*
* **Country:** Australia
* **Service ID:** `aus_immicard`
* **Data domain:** Document
* **Category:** Visa

## Inputs

| Field                   | Required | Example             |
| ----------------------- | -------: | ------------------- |
| `first_name`            |      Yes | `John`              |
| `last_name`             |      Yes | `Doe`               |
| `date_of_birth`         |      Yes | `1990-01-01`        |
| `immi_card_number`      |      Yes | `SAMPLE-IMMI-12345` |
| `immi_card_expiry_date` |      Yes | `2030-01-01`        |
| `vendor_data`           |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `immi_card_number`, `immi_card_expiry_date`
* **Optional inputs:** `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** 100%\*
* **Price:** \$0.45 per successful query

## Body parameters

<ParamField type="string" placeholder="AUS">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `AUS`
</ParamField>

<ParamField type="string" placeholder="aus_immicard">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `aus_immicard`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-IMMI-12345">
  `immi_card_number` value required by this database service.

  Example: `SAMPLE-IMMI-12345`
</ParamField>

<ParamField type="string" placeholder="2030-01-01">
  `immi_card_expiry_date` value required by this database service.

  Example: `2030-01-01`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=AUS" \
    -F "services=aus_immicard" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "immi_card_number=SAMPLE-IMMI-12345" \
    -F "immi_card_expiry_date=2030-01-01"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "AUS",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "aus_immicard",
        "service_name": "Australia - DVS - ImmiCard",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "AUS",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "aus_immicard",
        "service_name": "Australia - DVS - ImmiCard",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "AUS",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "aus_immicard",
        "service_name": "Australia - DVS - ImmiCard",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `aus_immicard` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `identification_number`
* `last_name`

## Pricing & SLAs

Australia - DVS - ImmiCard queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.45 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Australia Database Validation overview](/api-reference/database-validation/australia)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Australia - DVS – Marriage Certificate
Source: https://docs.didit.me/api-reference/database-validation/australia/marriage-certificate

POST /v3/database-validation/
Verifies input data against the Document Verification Service (DVS). Authoritative real-time identity lookup for Australia. Real-time lookup, pay-per-call.

<div />

Verifies input data against the Document Verification Service (DVS). Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 100%\*
* **Country:** Australia
* **Service ID:** `aus_marriage_certificate`
* **Data domain:** Identity
* **Category:** CivilRegistry

## Inputs

| Field                         | Required | Example                 |
| ----------------------------- | -------: | ----------------------- |
| `first_name`                  |      Yes | `John`                  |
| `last_name`                   |      Yes | `Doe`                   |
| `first_partner_name`          |      Yes | `Jamie`                 |
| `last_partner_name`           |      Yes | `Example`               |
| `marriage_certificate_number` |      Yes | `SAMPLE-MARRIAGE-12345` |
| `birth_registration_number`   |      Yes | `SAMPLE-BIRTH-12345`    |
| `birth_registration_state`    |      Yes | `Sample State`          |
| `birth_registration_date`     |      Yes | `1990-01-01`            |
| `vendor_data`                 |       No | `user-1234`             |

* **Required inputs:** `first_name`, `last_name`, `first_partner_name`, `last_partner_name`, `marriage_certificate_number`, `birth_registration_number`, `birth_registration_state`, `birth_registration_date`
* **Optional inputs:** `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow with field mapping
* **Coverage:** 100%\*
* **Price:** \$0.45 per successful query

In a workflow, `first_partner_name`, `last_partner_name`, `birth_registration_state` and `birth_registration_date` are not printed on an identity document, so no step produces them on their own. Collect them from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map each one on the Database Validation step. Until they are mapped the workflow editor shows this service disabled and names the missing input; at run time a missing input means the check is skipped before any query, so you are never billed for a database that could not be asked.

## Body parameters

<ParamField type="string" placeholder="AUS">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `AUS`
</ParamField>

<ParamField type="string" placeholder="aus_marriage_certificate">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `aus_marriage_certificate`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="Jamie">
  `first_partner_name` value required by this database service.

  Example: `Jamie`
</ParamField>

<ParamField type="string" placeholder="Example">
  `last_partner_name` value required by this database service.

  Example: `Example`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-MARRIAGE-12345">
  `marriage_certificate_number` value required by this database service.

  Example: `SAMPLE-MARRIAGE-12345`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-BIRTH-12345">
  `birth_registration_number` value required by this database service.

  Example: `SAMPLE-BIRTH-12345`
</ParamField>

<ParamField type="string" placeholder="Sample State">
  `birth_registration_state` value required by this database service.

  Example: `Sample State`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  `birth_registration_date` value required by this database service.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=AUS" \
    -F "services=aus_marriage_certificate" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "first_partner_name=Jamie" \
    -F "last_partner_name=Example" \
    -F "marriage_certificate_number=SAMPLE-MARRIAGE-12345" \
    -F "birth_registration_number=SAMPLE-BIRTH-12345" \
    -F "birth_registration_state=Sample State" \
    -F "birth_registration_date=1990-01-01"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "AUS",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "aus_marriage_certificate",
        "service_name": "Australia - DVS – Marriage Certificate",
        "source_data": {
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "AUS",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "aus_marriage_certificate",
        "service_name": "Australia - DVS – Marriage Certificate",
        "source_data": {
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "AUS",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "aus_marriage_certificate",
        "service_name": "Australia - DVS – Marriage Certificate",
        "source_data": {
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `aus_marriage_certificate` currently documents this normalized shape:

* `first_name`
* `identification_number`
* `last_name`

## Pricing & SLAs

Australia - DVS – Marriage Certificate queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.45 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Australia Database Validation overview](/api-reference/database-validation/australia)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# DVS - Australia Medicare Card
Source: https://docs.didit.me/api-reference/database-validation/australia/medicare-card

POST /v3/database-validation/
Verifies input data against the Document Verification Service (DVS). Authoritative real-time identity lookup for Australia. Real-time lookup, pay-per-call.

<div />

Verifies input data against the Document Verification Service (DVS). Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 100%\*
* **Country:** Australia
* **Service ID:** `aus_australia_medicare_card`
* **Data domain:** Health
* **Category:** Healthcare

## Inputs

| Field                  | Required | Example      |
| ---------------------- | -------: | ------------ |
| `first_name`           |      Yes | `John`       |
| `last_name`            |      Yes | `Doe`        |
| `date_of_birth`        |      Yes | `1990-01-01` |
| `medicare_card_number` |      Yes | `1111111111` |
| `middle_name`          |       No | `Demo`       |
| `vendor_data`          |       No | `user-1234`  |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `medicare_card_number`
* **Optional inputs:** `middle_name`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** 100%\*
* **Price:** \$0.45 per successful query

Not every document this service accepts carries the identifier it queries by. When the identifier is not extracted from the document the check is recorded as **not applicable** - no database is queried and you are not charged - which for some countries is a large share of real users. To cover them, also collect the identifier from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step.

## Body parameters

<ParamField type="string" placeholder="AUS">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `AUS`
</ParamField>

<ParamField type="string" placeholder="aus_australia_medicare_card">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `aus_australia_medicare_card`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="1111111111">
  Medicare card number.

  Example: `1111111111`
</ParamField>

<ParamField type="string" placeholder="Demo">
  Middle name, when available.

  Example: `Demo`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Australian Medicare card number (exactly 10 digits)
* `medicare_card_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `medicare_card_number` must be exactly 10 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=AUS" \
    -F "services=aus_australia_medicare_card" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "medicare_card_number=1111111111"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "AUS",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "aus_australia_medicare_card",
        "service_name": "DVS - Australia Medicare Card",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "middle_name": "Demo"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "AUS",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "aus_australia_medicare_card",
        "service_name": "DVS - Australia Medicare Card",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "middle_name": "Demo"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "AUS",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "aus_australia_medicare_card",
        "service_name": "DVS - Australia Medicare Card",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `aus_australia_medicare_card` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `identification_number`
* `last_name`
* `middle_name`

## Pricing & SLAs

DVS - Australia Medicare Card queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.45 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Australia Database Validation overview](/api-reference/database-validation/australia)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# DVS - Australia Passport
Source: https://docs.didit.me/api-reference/database-validation/australia/passport

POST /v3/database-validation/
Verifies input data against the Document Verification Service (DVS). Authoritative real-time identity lookup for Australia. Real-time lookup, pay-per-call.

<div />

Verifies input data against the Document Verification Service (DVS). Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 100%\*
* **Country:** Australia
* **Service ID:** `aus_australia_passport`
* **Data domain:** Document
* **Category:** Passport

## Inputs

| Field             | Required | Example             |
| ----------------- | -------: | ------------------- |
| `first_name`      |      Yes | `John`              |
| `last_name`       |      Yes | `Doe`               |
| `date_of_birth`   |      Yes | `1990-01-01`        |
| `passport_number` |      Yes | `SAMPLE-PASS-12345` |
| `middle_name`     |       No | `Demo`              |
| `vendor_data`     |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `passport_number`
* **Optional inputs:** `middle_name`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** 100%\*
* **Price:** \$0.45 per successful query

## Body parameters

<ParamField type="string" placeholder="AUS">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `AUS`
</ParamField>

<ParamField type="string" placeholder="aus_australia_passport">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `aus_australia_passport`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-PASS-12345">
  Passport number.

  Example: `SAMPLE-PASS-12345`
</ParamField>

<ParamField type="string" placeholder="Demo">
  Middle name, when available.

  Example: `Demo`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=AUS" \
    -F "services=aus_australia_passport" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "passport_number=SAMPLE-PASS-12345"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "AUS",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "aus_australia_passport",
        "service_name": "DVS - Australia Passport",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "middle_name": "Demo"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "AUS",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "aus_australia_passport",
        "service_name": "DVS - Australia Passport",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "middle_name": "Demo"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "AUS",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "aus_australia_passport",
        "service_name": "DVS - Australia Passport",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `aus_australia_passport` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `identification_number`
* `last_name`
* `middle_name`

## Pricing & SLAs

DVS - Australia Passport queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.45 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Australia Database Validation overview](/api-reference/database-validation/australia)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Australia Superannuation & Payroll
Source: https://docs.didit.me/api-reference/database-validation/australia/superannuation-payroll

POST /v3/database-validation/
Verifies input data to an authorised Superannuation and Payroll administrator and services provider. Authoritative real-time identity lookup for Australia. Real-time lookup, pay-per-call.

<div />

Verifies input data to an authorised Superannuation and Payroll administrator and services provider. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 50%
* **Country:** Australia
* **Service ID:** `aus_superannuation_payroll`
* **Data domain:** Financial
* **Category:** Superannuation

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `address.street_1`    |       No | `123 Sample Street` |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `address.postal_code` |       No | `10001`             |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`
* **Optional inputs:** `address.street_1`, `address.street_2`, `address.city`, `address.region`, `address.postal_code`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 50%
* **Price:** \$0.67 per successful query

## Body parameters

<ParamField type="string" placeholder="AUS">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `AUS`
</ParamField>

<ParamField type="string" placeholder="aus_superannuation_payroll">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `aus_superannuation_payroll`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* `address` is optional for this service. You can send one complete `address` string and Didit will split it into structured address elements when possible, or you can send the structured fields explicitly.
* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=AUS" \
    -F "services=aus_superannuation_payroll" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "AUS",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "aus_superannuation_payroll",
        "service_name": "Australia Superannuation & Payroll",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "AUS",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "aus_superannuation_payroll",
        "service_name": "Australia Superannuation & Payroll",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "AUS",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "aus_superannuation_payroll",
        "service_name": "Australia Superannuation & Payroll",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `aus_superannuation_payroll` currently documents this normalized shape:

* `address`
* `date_of_birth`
* `first_name`
* `last_name`

## Pricing & SLAs

Australia Superannuation & Payroll queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.67 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Australia Database Validation overview](/api-reference/database-validation/australia)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Australia - DVS - Travel Document
Source: https://docs.didit.me/api-reference/database-validation/australia/travel-document

POST /v3/database-validation/
Verifies input data against the Document Verification Service (DVS). Authoritative real-time identity lookup for Australia. Real-time lookup, pay-per-call.

<div />

Verifies input data against the Document Verification Service (DVS). Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 100%\*
* **Country:** Australia
* **Service ID:** `aus_travel_document`
* **Data domain:** Document
* **Category:** Passport

## Inputs

| Field                    | Required | Example             |
| ------------------------ | -------: | ------------------- |
| `first_name`             |      Yes | `John`              |
| `last_name`              |      Yes | `Doe`               |
| `passport_number`        |      Yes | `SAMPLE-PASS-12345` |
| `passport_issue_country` |      Yes | `USA`               |
| `vendor_data`            |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `passport_number`, `passport_issue_country`
* **Optional inputs:** `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** 100%\*
* **Price:** \$0.45 per successful query

## Body parameters

<ParamField type="string" placeholder="AUS">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `AUS`
</ParamField>

<ParamField type="string" placeholder="aus_travel_document">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `aus_travel_document`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-PASS-12345">
  Passport number.

  Example: `SAMPLE-PASS-12345`
</ParamField>

<ParamField type="string" placeholder="USA">
  ISO 3166-1 alpha-3 country that issued the passport.

  Example: `USA`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* ISO 3166-1 alpha-3 country code
* `passport_issue_country` must use uppercase letters.
* `passport_issue_country` must match `[A-Za-z]{3}`.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=AUS" \
    -F "services=aus_travel_document" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "passport_number=SAMPLE-PASS-12345" \
    -F "passport_issue_country=USA"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "AUS",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "aus_travel_document",
        "service_name": "Australia - DVS - Travel Document",
        "source_data": {
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "AUS",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "aus_travel_document",
        "service_name": "Australia - DVS - Travel Document",
        "source_data": {
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "AUS",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "aus_travel_document",
        "service_name": "Australia - DVS - Travel Document",
        "source_data": {
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `aus_travel_document` currently documents this normalized shape:

* `first_name`
* `identification_number`
* `last_name`

## Pricing & SLAs

Australia - DVS - Travel Document queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.45 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Australia Database Validation overview](/api-reference/database-validation/australia)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Australia VEVO
Source: https://docs.didit.me/api-reference/database-validation/australia/vevo

POST /v3/database-validation/
Verifies input data against the Department of Home Affairs Visa database. Authoritative real-time identity lookup for Australia. Real-time lookup, pay-per-call.

<div />

Verifies input data against the Department of Home Affairs Visa database. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 100%\*
* **Country:** Australia
* **Service ID:** `aus_vevo`
* **Data domain:** Document
* **Category:** Visa

## Inputs

| Field                    | Required | Example             |
| ------------------------ | -------: | ------------------- |
| `first_name`             |      Yes | `John`              |
| `last_name`              |      Yes | `Doe`               |
| `date_of_birth`          |      Yes | `1990-01-01`        |
| `passport_number`        |      Yes | `SAMPLE-PASS-12345` |
| `passport_issue_country` |      Yes | `USA`               |
| `vendor_data`            |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `passport_number`, `passport_issue_country`
* **Optional inputs:** `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** 100%\*
* **Price:** \$0.32 per successful query

## Body parameters

<ParamField type="string" placeholder="AUS">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `AUS`
</ParamField>

<ParamField type="string" placeholder="aus_vevo">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `aus_vevo`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-PASS-12345">
  Passport number.

  Example: `SAMPLE-PASS-12345`
</ParamField>

<ParamField type="string" placeholder="USA">
  ISO 3166-1 alpha-3 country that issued the passport.

  Example: `USA`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* ISO 3166-1 alpha-3 country code
* `passport_issue_country` must use uppercase letters.
* `passport_issue_country` must match `[A-Za-z]{3}`.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=AUS" \
    -F "services=aus_vevo" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "passport_number=SAMPLE-PASS-12345" \
    -F "passport_issue_country=USA"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "AUS",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "aus_vevo",
        "service_name": "Australia VEVO",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "identification_number": "SAMPLE-ID-12345",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": true,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "AUS",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "aus_vevo",
        "service_name": "Australia VEVO",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "identification_number": "SAMPLE-ID-12345",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": false,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "AUS",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "aus_vevo",
        "service_name": "Australia VEVO",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `aus_vevo` currently documents this normalized shape:

* `date_of_birth`
* `identification_number`
* `name_match_score`

## Pricing & SLAs

Australia VEVO queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.32 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Australia Database Validation overview](/api-reference/database-validation/australia)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# DVS - Australia Visa
Source: https://docs.didit.me/api-reference/database-validation/australia/visa

POST /v3/database-validation/
Verifies input data against the Document Verification Service (DVS). Authoritative real-time identity lookup for Australia. Real-time lookup, pay-per-call.

<div />

Verifies input data against the Document Verification Service (DVS). Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 100%\*
* **Country:** Australia
* **Service ID:** `aus_australia_visa`
* **Data domain:** Document
* **Category:** Visa

## Inputs

| Field             | Required | Example             |
| ----------------- | -------: | ------------------- |
| `first_name`      |      Yes | `John`              |
| `last_name`       |      Yes | `Doe`               |
| `date_of_birth`   |      Yes | `1990-01-01`        |
| `passport_number` |      Yes | `SAMPLE-PASS-12345` |
| `vendor_data`     |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `passport_number`
* **Optional inputs:** `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** 100%\*
* **Price:** \$0.45 per successful query

## Body parameters

<ParamField type="string" placeholder="AUS">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `AUS`
</ParamField>

<ParamField type="string" placeholder="aus_australia_visa">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `aus_australia_visa`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-PASS-12345">
  Passport number.

  Example: `SAMPLE-PASS-12345`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=AUS" \
    -F "services=aus_australia_visa" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "passport_number=SAMPLE-PASS-12345"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "AUS",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "aus_australia_visa",
        "service_name": "DVS - Australia Visa",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "AUS",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "aus_australia_visa",
        "service_name": "DVS - Australia Visa",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "AUS",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "aus_australia_visa",
        "service_name": "DVS - Australia Visa",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `aus_australia_visa` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `identification_number`
* `last_name`

## Pricing & SLAs

DVS - Australia Visa queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.45 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Australia Database Validation overview](/api-reference/database-validation/australia)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Austria Credit Bureau
Source: https://docs.didit.me/api-reference/database-validation/austria/credit-bureau

POST /v3/database-validation/
Verifies input data against Credit Header data obtained from a Credit Bureau in Austria. Authoritative real-time identity lookup for Austria. Real-time lookup, pay-per-call.

<div />

Verifies input data against Credit Header data obtained from a Credit Bureau in Austria. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 80%
* **Country:** Austria
* **Service ID:** `aut_credit_bureau`
* **Data domain:** Financial
* **Category:** CreditBureau

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `address.street_1`, `address.postal_code`
* **Optional inputs:** `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 80%
* **Price:** \$1.60 per successful query

## Body parameters

<ParamField type="string" placeholder="AUT">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `AUT`
</ParamField>

<ParamField type="string" placeholder="aut_credit_bureau">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `aut_credit_bureau`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=AUT" \
    -F "services=aut_credit_bureau" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}'
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "AUT",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "aut_credit_bureau",
        "service_name": "Austria Credit Bureau",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "AUT",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "aut_credit_bureau",
        "service_name": "Austria Credit Bureau",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "AUT",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "aut_credit_bureau",
        "service_name": "Austria Credit Bureau",
        "source_data": {
          "address": "NO_MATCH",
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `aut_credit_bureau` currently documents this normalized shape:

* `address`
* `date_of_birth`
* `first_name`
* `last_name`

## Pricing & SLAs

Austria Credit Bureau queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$1.60 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Austria Database Validation overview](/api-reference/database-validation/austria)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Bolivia - CI verification
Source: https://docs.didit.me/api-reference/database-validation/bolivia/cedula

POST /v3/database-validation/
Verifies Bolivian Carnet de Identidad data against SEGIP government records. Authoritative real-time identity lookup for Bolivia. Real-time lookup, pay-per-call.

<div />

Verifies Bolivian Carnet de Identidad data against SEGIP government records. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 90-95%
* **Country:** Bolivia
* **Service ID:** `bol_cedula`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field             | Required | Example      |
| ----------------- | -------: | ------------ |
| `document_number` |      Yes | `111111`     |
| `date_of_birth`   |      Yes | `1990-01-01` |
| `first_name`      |       No | `John`       |
| `last_name`       |       No | `Doe`        |
| `vendor_data`     |       No | `user-1234`  |

* **Required inputs:** `document_number`, `date_of_birth`
* **Optional inputs:** `first_name`, `last_name`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** 90-95%
* **Price:** \$0.20 per successful query

## Body parameters

<ParamField type="string" placeholder="BOL">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `BOL`
</ParamField>

<ParamField type="string" placeholder="bol_cedula">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `bol_cedula`
</ParamField>

<ParamField type="string" placeholder="111111">
  Document number extracted from or provided by the user.

  Example: `111111`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Bolivian CI (6-10 digits)
* `document_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `document_number` must be 6-10 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=BOL" \
    -F "services=bol_cedula" \
    -F "vendor_data=user-1234" \
    -F "document_number=111111" \
    -F "date_of_birth=1990-01-01"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "BOL",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "bol_cedula",
        "service_name": "Bolivia - CI verification",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "BOL",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "bol_cedula",
        "service_name": "Bolivia - CI verification",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "BOL",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "bol_cedula",
        "service_name": "Bolivia - CI verification",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `bol_cedula` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `full_name`
* `identification_number`
* `last_name`

## Pricing & SLAs

Bolivia - CI verification queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.20 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Bolivia Database Validation overview](/api-reference/database-validation/bolivia)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Brazil - CNH QR code + face match (Datavalid)
Source: https://docs.didit.me/api-reference/database-validation/brazil/cnh-facial-qrcode

POST /v3/database-validation/
SERPRO Datavalid v4 pf-facial-qrcode — decodes the QR code printed on Brazilian CNH driver licences (physical or digital, issued since May 2017), validates CPF + name + date of birth against Receita Federal, and matches the live selfie against the CNH portrait stored at Senatran. Authoritative real-time identity lookup for Brazil. Real-time lookup, pay-per-call.

<div />

SERPRO Datavalid v4 pf-facial-qrcode — decodes the QR code printed on Brazilian CNH driver licences (physical or digital, issued since May 2017), validates CPF + name + date of birth against Receita Federal, and matches the live selfie against the CNH portrait stored at Senatran. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** Brazil
* **Service ID:** `bra_cnh_facial_qrcode`
* **Data domain:** Biometric
* **Category:** DriverLicence

## Inputs

| Field               | Required | Example                                                  |
| ------------------- | -------: | -------------------------------------------------------- |
| `tax_number`        |      Yes | `11111111111`                                            |
| `selfie`            |      Yes | `@./selfie.jpg`                                          |
| `cnh_qr_code_image` |      Yes | `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB` |
| `first_name`        |       No | `John`                                                   |
| `last_name`         |       No | `Doe`                                                    |
| `date_of_birth`     |       No | `1990-01-01`                                             |
| `vendor_data`       |       No | `user-1234`                                              |

* **Required inputs:** `tax_number`, `selfie`, `cnh_qr_code_image`
* **Optional inputs:** `first_name`, `last_name`, `date_of_birth`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** —
* **Price:** \$0.50 per successful query

## Body parameters

<ParamField type="string" placeholder="BRA">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `BRA`
</ParamField>

<ParamField type="string" placeholder="bra_cnh_facial_qrcode">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `bra_cnh_facial_qrcode`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="11111111111">
  Tax or fiscal identification number.

  Example: `11111111111`
</ParamField>

<ParamField type="file" placeholder="@./selfie.jpg">
  Selfie image file to upload for biometric database validation. Accepted formats: JPEG, PNG, or WebP.

  Example: `@./selfie.jpg`
</ParamField>

<ParamField type="string" placeholder="data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB">
  `cnh_qr_code_image` value required by this database service.

  Example: `data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Brazilian CPF (exactly 11 digits)
* `tax_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `tax_number` must be exactly 11 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=BRA" \
    -F "services=bra_cnh_facial_qrcode" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "tax_number=11111111111" \
    -F "selfie=@./selfie.jpg" \
    -F "cnh_qr_code_image=data:image/png;base64,iVBORw0KGgoAAAANSUhEUgAAAAEAAAAB"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "BRA",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "bra_cnh_facial_qrcode",
        "service_name": "Brazil - CNH QR code + face match (Datavalid)",
        "source_data": {
          "cnh_qrcode": "sample_value",
          "date_of_birth": "1990-01-01",
          "face_match_probability": "Altíssima probabilidade",
          "face_match_score": "0.990",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "identification_number": true
          }
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "BRA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "bra_cnh_facial_qrcode",
        "service_name": "Brazil - CNH QR code + face match (Datavalid)",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```

  **`BIOMETRIC_NO_MATCH`** — The face-match score was below the acceptance threshold - the selfie is not the same person as the registry photo.

  ```json 200 OK — BIOMETRIC_NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "BRA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "BIOMETRIC_NO_MATCH",
        "service_id": "bra_cnh_facial_qrcode",
        "service_name": "Brazil - CNH QR code + face match (Datavalid)",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```

  **`BIOMETRIC_IMAGE_UNUSABLE`** — The selfie could not be processed (empty, no face, low quality, or the registry could not read it). Prompt the user to retake the selfie.

  ```json 200 OK — BIOMETRIC_IMAGE_UNUSABLE theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "BRA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "BIOMETRIC_IMAGE_UNUSABLE",
        "service_id": "bra_cnh_facial_qrcode",
        "service_name": "Brazil - CNH QR code + face match (Datavalid)",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `bra_cnh_facial_qrcode` currently documents this normalized shape:

* `cnh_qrcode`
* `date_of_birth`
* `face_match_probability`
* `face_match_score`
* `first_name`
* `identification_number`
* `last_name`
* `name_match_score`

## Pricing & SLAs

Brazil - CNH QR code + face match (Datavalid) queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.50 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Brazil Database Validation overview](/api-reference/database-validation/brazil)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Brazil - CPF status check
Source: https://docs.didit.me/api-reference/database-validation/brazil/cpf

POST /v3/database-validation/
Returns CPF status (regular, suspended, cancelled), name, social name and registration date from Receita Federal via SERPRO. The lookup is keyed by CPF and date of birth. Authoritative real-time identity lookup for Brazil. Real-time lookup, pay-per-call.

<div />

Returns CPF status (regular, suspended, cancelled), name, social name and registration date from Receita Federal via SERPRO. The lookup is keyed by CPF and date of birth. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 100%
* **Country:** Brazil
* **Service ID:** `bra_cpf`
* **Data domain:** Identity
* **Category:** TaxRegistry

## Inputs

| Field           | Required | Example       |
| --------------- | -------: | ------------- |
| `tax_number`    |      Yes | `11111111111` |
| `date_of_birth` |      Yes | `1990-01-01`  |
| `first_name`    |       No | `John`        |
| `last_name`     |       No | `Doe`         |
| `vendor_data`   |       No | `user-1234`   |

* **Required inputs:** `tax_number`, `date_of_birth`
* **Optional inputs:** `first_name`, `last_name`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 100%
* **Price:** \$0.20 per successful query

Not every document this service accepts carries the identifier it queries by. When the identifier is not extracted from the document the check is recorded as **not applicable** - no database is queried and you are not charged - which for some countries is a large share of real users. To cover them, also collect the identifier from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step.

## Body parameters

<ParamField type="string" placeholder="BRA">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `BRA`
</ParamField>

<ParamField type="string" placeholder="bra_cpf">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `bra_cpf`
</ParamField>

<ParamField type="string" placeholder="11111111111">
  Tax or fiscal identification number.

  Example: `11111111111`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Brazilian CPF (exactly 11 digits)
* `tax_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `tax_number` must be exactly 11 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=BRA" \
    -F "services=bra_cpf" \
    -F "vendor_data=user-1234" \
    -F "tax_number=11111111111" \
    -F "date_of_birth=1990-01-01"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "BRA",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "bra_cpf",
        "service_name": "Brazil - CPF status check",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "lgpd_minor": "sample_value",
          "minor_under_16": "sample_value",
          "minor_under_18": "sample_value",
          "registration_date": "1990-01-01"
        },
        "validation": {
          "date_of_birth": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "BRA",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "bra_cpf",
        "service_name": "Brazil - CPF status check",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "lgpd_minor": "sample_value",
          "minor_under_16": "sample_value",
          "minor_under_18": "sample_value",
          "registration_date": "1990-01-01"
        },
        "validation": {
          "date_of_birth": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "BRA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "bra_cpf",
        "service_name": "Brazil - CPF status check",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `bra_cpf` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `identification_number`
* `last_name`
* `lgpd_minor`
* `minor_under_16`
* `minor_under_18`
* `registration_date`

## Pricing & SLAs

Brazil - CPF status check queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.20 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Brazil Database Validation overview](/api-reference/database-validation/brazil)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Brazil - CPF + face match (Datavalid)
Source: https://docs.didit.me/api-reference/database-validation/brazil/cpf-facial

POST /v3/database-validation/
SERPRO Datavalid v4 pf-facial — validates CPF (mandatory) against Receita Federal and matches the live selfie (mandatory) against the CNH portrait stored at Senatran. Optionally screens name and date of birth. Authoritative real-time identity lookup for Brazil. Real-time lookup, pay-per-call.

<div />

SERPRO Datavalid v4 pf-facial — validates CPF (mandatory) against Receita Federal and matches the live selfie (mandatory) against the CNH portrait stored at Senatran. Optionally screens name and date of birth. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~50%
* **Country:** Brazil
* **Service ID:** `bra_cpf_facial`
* **Data domain:** Biometric
* **Category:** NationalIDRegistry

Roughly 50% of Brazilian adults — the face-match step relies on the CNH portrait held at Senatran, so only driver-licence holders can be matched.

## Inputs

| Field           | Required | Example         |
| --------------- | -------: | --------------- |
| `tax_number`    |      Yes | `11111111111`   |
| `selfie`        |      Yes | `@./selfie.jpg` |
| `first_name`    |       No | `John`          |
| `last_name`     |       No | `Doe`           |
| `date_of_birth` |       No | `1990-01-01`    |
| `vendor_data`   |       No | `user-1234`     |

* **Required inputs:** `tax_number`, `selfie`
* **Optional inputs:** `first_name`, `last_name`, `date_of_birth`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** \~50%
* **Price:** \$0.45 per successful query

## Body parameters

<ParamField type="string" placeholder="BRA">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `BRA`
</ParamField>

<ParamField type="string" placeholder="bra_cpf_facial">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `bra_cpf_facial`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="11111111111">
  Tax or fiscal identification number.

  Example: `11111111111`
</ParamField>

<ParamField type="file" placeholder="@./selfie.jpg">
  Selfie image file to upload for biometric database validation. Accepted formats: JPEG, PNG, or WebP.

  Example: `@./selfie.jpg`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Brazilian CPF (exactly 11 digits)
* `tax_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `tax_number` must be exactly 11 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=BRA" \
    -F "services=bra_cpf_facial" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "tax_number=11111111111" \
    -F "selfie=@./selfie.jpg"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "BRA",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "bra_cpf_facial",
        "service_name": "Brazil - CPF + face match (Datavalid)",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "face_match_probability": "Altíssima probabilidade",
          "face_match_score": "0.990",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "identification_number": true
          }
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "BRA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "bra_cpf_facial",
        "service_name": "Brazil - CPF + face match (Datavalid)",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```

  **`BIOMETRIC_NO_MATCH`** — The face-match score was below the acceptance threshold - the selfie is not the same person as the registry photo.

  ```json 200 OK — BIOMETRIC_NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "BRA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "BIOMETRIC_NO_MATCH",
        "service_id": "bra_cpf_facial",
        "service_name": "Brazil - CPF + face match (Datavalid)",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```

  **`BIOMETRIC_IMAGE_UNUSABLE`** — The selfie could not be processed (empty, no face, low quality, or the registry could not read it). Prompt the user to retake the selfie.

  ```json 200 OK — BIOMETRIC_IMAGE_UNUSABLE theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "BRA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "BIOMETRIC_IMAGE_UNUSABLE",
        "service_id": "bra_cpf_facial",
        "service_name": "Brazil - CPF + face match (Datavalid)",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `bra_cpf_facial` currently documents this normalized shape:

* `date_of_birth`
* `face_match_probability`
* `face_match_score`
* `first_name`
* `identification_number`
* `last_name`
* `name_match_score`

## Pricing & SLAs

Brazil - CPF + face match (Datavalid) queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.45 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## About this source

This is the official government source: [SERPRO](https://www.serpro.gov.br) Datavalid, operated by the Brazilian federal data-processing service. The CPF is checked against Receita Federal, and the selfie is matched against the portrait held for that person at Senatran — the national driver-licensing registry.

Because the portrait comes from the CNH (driver's licence) record, only people who hold a CNH have a face on file. That is what caps coverage at roughly 50% of the adult population: the data is authoritative, but it is missing for every Brazilian who has never held a driver's licence.

**Need broader coverage?** Use [BRA - Unico IDCloud (CPF + selfie)](/api-reference/database-validation/brazil/unico-idcloud) instead. It reaches about 96% of Brazilian adults through Unico's private biometric registry, and costs \$0.20 against \$0.45 here. Choose Datavalid when you specifically need the government registry as your source of truth; choose IDCloud when you need to verify everyone.

## Continue reading

* [Brazil Database Validation overview](/api-reference/database-validation/brazil)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Brazil Residential
Source: https://docs.didit.me/api-reference/database-validation/brazil/residential

POST /v3/database-validation/
Verifies against a combined database of electoral registrations. Authoritative real-time identity lookup for Brazil. Real-time lookup, pay-per-call.

<div />

Verifies against a combined database of electoral registrations. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 95%
* **Country:** Brazil
* **Service ID:** `bra_residential`
* **Data domain:** Address
* **Category:** Residential

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `tax_number`          |      Yes | `11111111111`       |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `address.street_1`, `address.postal_code`, `tax_number`
* **Optional inputs:** `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 95%
* **Price:** \$0.35 per successful query

Not every document this service accepts carries the identifier it queries by. When the identifier is not extracted from the document the check is recorded as **not applicable** - no database is queried and you are not charged - which for some countries is a large share of real users. To cover them, also collect the identifier from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step.

## Body parameters

<ParamField type="string" placeholder="BRA">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `BRA`
</ParamField>

<ParamField type="string" placeholder="bra_residential">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `bra_residential`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="11111111111">
  Tax or fiscal identification number.

  Example: `11111111111`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Brazilian CPF (exactly 11 digits)
* `tax_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `tax_number` must be exactly 11 characters long.
* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=BRA" \
    -F "services=bra_residential" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}' \
    -F "tax_number=11111111111"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "BRA",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "bra_residential",
        "service_name": "Brazil Residential",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "BRA",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "bra_residential",
        "service_name": "Brazil Residential",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "BRA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "bra_residential",
        "service_name": "Brazil Residential",
        "source_data": {
          "address": "NO_MATCH",
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `bra_residential` currently documents this normalized shape:

* `address`
* `date_of_birth`
* `first_name`
* `identification_number`
* `last_name`

## Pricing & SLAs

Brazil Residential queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.35 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Brazil Database Validation overview](/api-reference/database-validation/brazil)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Brazil Tax Registration (CPF/CNPJ)
Source: https://docs.didit.me/api-reference/database-validation/brazil/tax-registration

POST /v3/database-validation/
Verifies against the CPF/CNPJ database. Authoritative real-time identity lookup for Brazil. Real-time lookup, pay-per-call.

<div />

Verifies against the CPF/CNPJ database. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 100%
* **Country:** Brazil
* **Service ID:** `bra_tax_registration`
* **Data domain:** Financial
* **Category:** TaxRegistry

## Inputs

| Field           | Required | Example       |
| --------------- | -------: | ------------- |
| `first_name`    |      Yes | `John`        |
| `last_name`     |      Yes | `Doe`         |
| `date_of_birth` |      Yes | `1990-01-01`  |
| `tax_number`    |      Yes | `11111111111` |
| `vendor_data`   |       No | `user-1234`   |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `tax_number`
* **Optional inputs:** `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 100%
* **Price:** \$0.15 per successful query

Not every document this service accepts carries the identifier it queries by. When the identifier is not extracted from the document the check is recorded as **not applicable** - no database is queried and you are not charged - which for some countries is a large share of real users. To cover them, also collect the identifier from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step.

## Body parameters

<ParamField type="string" placeholder="BRA">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `BRA`
</ParamField>

<ParamField type="string" placeholder="bra_tax_registration">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `bra_tax_registration`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="11111111111">
  Tax or fiscal identification number.

  Example: `11111111111`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Brazilian CPF (exactly 11 digits)
* `tax_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `tax_number` must be exactly 11 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=BRA" \
    -F "services=bra_tax_registration" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "tax_number=11111111111"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "BRA",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "bra_tax_registration",
        "service_name": "Brazil Tax Registration (CPF/CNPJ)",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "identification_number": "SAMPLE-ID-12345",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": true,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "BRA",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "bra_tax_registration",
        "service_name": "Brazil Tax Registration (CPF/CNPJ)",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "identification_number": "SAMPLE-ID-12345",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": false,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "BRA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "bra_tax_registration",
        "service_name": "Brazil Tax Registration (CPF/CNPJ)",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `bra_tax_registration` currently documents this normalized shape:

* `date_of_birth`
* `identification_number`
* `name_match_score`

## Pricing & SLAs

Brazil Tax Registration (CPF/CNPJ) queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.15 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Brazil Database Validation overview](/api-reference/database-validation/brazil)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# BRA - Unico IDCloud (CPF + selfie)
Source: https://docs.didit.me/api-reference/database-validation/brazil/unico-idcloud

POST /v3/database-validation/
Unico IDCloud biometric validation: matches the user's selfie against the face on record for their CPF and returns whether it is the same person, not the same person, or inconclusive. Authoritative real-time identity lookup for Brazil. Real-time lookup, pay-per-call.

<div />

Unico IDCloud biometric validation: matches the user's selfie against the face on record for their CPF and returns whether it is the same person, not the same person, or inconclusive. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 96%
* **Country:** Brazil
* **Service ID:** `bra_unico_idcloud`
* **Data domain:** Identity
* **Category:** BiometricRiskScore

About 96% of Brazilian CPF holders resolve to a biometric record in Unico's registry — roughly double the reach of the government face-match source, [Datavalid](/api-reference/database-validation/brazil/cpf-facial), at about 50%.

## Inputs

| Field           | Required | Example         |
| --------------- | -------: | --------------- |
| `tax_number`    |      Yes | `11111111111`   |
| `selfie`        |      Yes | `@./selfie.jpg` |
| `first_name`    |       No | `John`          |
| `last_name`     |       No | `Doe`           |
| `full_name`     |       No | `John Doe`      |
| `date_of_birth` |       No | `1990-01-01`    |
| `vendor_data`   |       No | `user-1234`     |

* **Required inputs:** `tax_number`, `selfie`
* **Optional inputs:** `first_name`, `last_name`, `full_name`, `date_of_birth`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** 96%
* **Price:** \$0.20 per successful query

## Body parameters

<ParamField type="string" placeholder="BRA">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `BRA`
</ParamField>

<ParamField type="string" placeholder="bra_unico_idcloud">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `bra_unico_idcloud`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="11111111111">
  Tax or fiscal identification number.

  Example: `11111111111`
</ParamField>

<ParamField type="file" placeholder="@./selfie.jpg">
  Selfie image file to upload for biometric database validation. Accepted formats: JPEG, PNG, or WebP.

  Example: `@./selfie.jpg`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="John Doe">
  Full legal name to validate.

  Example: `John Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Brazilian CPF (exactly 11 digits)
* `tax_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `tax_number` must be exactly 11 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=BRA" \
    -F "services=bra_unico_idcloud" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "tax_number=11111111111" \
    -F "selfie=@./selfie.jpg"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "BRA",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "bra_unico_idcloud",
        "service_name": "BRA - Unico IDCloud (CPF + selfie)",
        "source_data": {
          "unico_face_match": "yes"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`BIOMETRIC_NO_MATCH`** — The face-match score was below the acceptance threshold - the selfie is not the same person as the registry photo.

  ```json 200 OK — BIOMETRIC_NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "BRA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "BIOMETRIC_NO_MATCH",
        "service_id": "bra_unico_idcloud",
        "service_name": "BRA - Unico IDCloud (CPF + selfie)",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```

  **`INCONCLUSIVE`** — The registry could not determine whether the person matches - the result is genuinely uncertain (they may or may not be in the registry). This is NOT a no-match and NOT a technical image problem; no field is asserted, so match\_type is null and the check is sent to review.

  ```json 200 OK — INCONCLUSIVE theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "BRA",
    "match_type": null,
    "validations": [
      {
        "outcome_code": "INCONCLUSIVE",
        "service_id": "bra_unico_idcloud",
        "service_name": "BRA - Unico IDCloud (CPF + selfie)",
        "source_data": {},
        "validation": {}
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `bra_unico_idcloud` currently documents this normalized shape:

* `unico_face_match`

## Pricing & SLAs

BRA - Unico IDCloud (CPF + selfie) queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.20 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## About this source

[Unico](https://unico.io) is a Brazilian IDtech that runs the country's largest private facial-biometric registry. Its IDCloud platform holds more than a billion facial embeddings and adds roughly 35 million new faces every month, fed by the onboarding and re-authentication flows of over 800 Brazilian companies — including four of the five largest banks. That scale is what produces the coverage figure above: a CPF lookup resolves to a biometric record for about 96% of Brazilian adults.

Didit has a direct partnership with Unico, so you can query IDCloud through the standard Database Validation API — pay-per-call, with no separate Unico contract, no minimum volume, and no onboarding process.

**How this differs from the government registry.** Didit also offers [Brazil - CPF + face match (Datavalid)](/api-reference/database-validation/brazil/cpf-facial), which is the official SERPRO source and the right choice when you specifically need the government registry as your source of truth. IDCloud is the stronger choice for everything else, on two axes you can check: it reaches about 96% of adults against Datavalid's roughly 50%, and it matches against a biometric record the registry maintains itself rather than a portrait taken from a document the user hands you — so it resists both document forgery and stolen-CPF fraud. It is also less than half the price per query.

## Recommended flow for Brazil

For most Brazilian use cases you do not need document capture at all. The user gives you a CPF, and a liveness-checked selfie confirms they are the person behind it.

<Steps>
  <Step title="Collect the CPF">
    Your only text input is the 11-digit CPF — no document photo, and no manually typed name or date of birth.

    Because no document is read in this flow, Didit has nothing to take the CPF from unless you say where it comes from. Send it in the session's `metadata` when you create the session, and map it as the `tax_number` input of the Database Validation step. In the Business Console that is the step's input mapping; through the workflows API it is the node's `database_validation_field_sources`:

    ```json theme={null}
    {
      "database_validation_countries": {"BRA": {"services": ["bra_unico_idcloud"]}},
      "database_validation_field_sources": {
        "tax_number": {"source": "expected_data", "key": "metadata.cpf"}
      }
    }
    ```

    Then create each session with the value under that key:

    ```json theme={null}
    {"workflow_id": "<workflow_id>", "metadata": {"cpf": "12345678909"}}
    ```

    Without the mapping the step still runs, but it reports `tax_number` as missing and never queries the registry — nothing is billed, and the session's `database_validations` entry carries the reason.
  </Step>

  <Step title="Capture the selfie with a liveness check">
    Add a [liveness](/core-technology/liveness/overview) step to the same workflow and pick the method that matches your risk appetite — **Passive Liveness** (no user action at all), **3D Flash**, or **3D Action & Flash** (active methods that project light patterns, the last one adding a randomized action). Set it with `face_liveness_method` (`PASSIVE`, `FLASHING`, or `ACTIVE_3D`) in the Business Console or through the workflows API. Whichever you pick, Didit renders the capture step and confirms a real, present person — this is what stops a stored photo or a screen replay from being submitted.
  </Step>

  <Step title="Validate the CPF and selfie against Unico IDCloud">
    Inside a session flow Didit re-uses the liveness selfie automatically — you never handle the image — and reads the CPF from the mapping above. IDCloud then confirms whether that face belongs to the person the CPF belongs to. The step needs only these two inputs; if you also send `full_name` or `date_of_birth` in `metadata` and map them, they are passed to Unico as cross-checks, but they are not required.
  </Step>
</Steps>

<Note>
  This CPF-only flow applies to **session and workflow** integrations, where Didit performs the capture and passes the liveness selfie to this service for you. If you call `POST /v3/database-validation/` **directly**, `selfie` is a required file input and you supply the image yourself — see [Database Validation overview](/core-technology/database-validation/overview) for both modes.
</Note>

**Cost:** about \$0.30 per verified user with Passive Liveness — \$0.20 for the IDCloud query plus \$0.10 for the liveness check — or about \$0.35 with an active method, where the liveness check costs \$0.15. Liveness includes a free monthly tier, so early volume costs less; see [pricing](/getting-started/pricing).

**Fallback for the roughly 4% without coverage.** When IDCloud returns `INCONCLUSIVE`, the registry could not resolve that CPF to a usable biometric record — typically because the person is not in it. Treat this as "no answer" rather than a failed check, and fall back to full [ID Verification](/core-technology/id-verification/overview): document capture plus face match against the document portrait. Everyone stays verifiable, and you pay for document verification only on the small remainder.

**Handling declines.** `BIOMETRIC_NO_MATCH` means the registry actively disagreed — the face does not belong to that CPF. Treat it as a strong negative rather than a prompt to retry: sending the user straight to document capture is exactly the path an impostor wants, since the document is the artefact they control. Genuine false negatives do happen, though — a changed appearance, an old registry photo, or a poor capture — so route these to manual review instead of either auto-approving or dead-ending the user. `BIOMETRIC_IMAGE_UNUSABLE` is different: the selfie simply could not be read, so ask for a fresh one. Decide what each result does to the session with [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings), and see [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes) for the full list.

**Returning users.** You only need to pay for a registry lookup once. After a user passes this flow, the liveness selfie is stored against their `vendor_data`, so you can re-verify them later with [Biometric Authentication](/core-technology/biometric-auth/overview) — a liveness check plus a face match against that stored face — for \$0.10, with the same choice of liveness methods. Note that this is for **returning** users specifically: a biometric-authentication session needs a stored face (or a `portrait_image` you supply) and fails at creation if the user has neither, so first-time users still go through the flow above.

## Continue reading

* [Brazil Database Validation overview](/api-reference/database-validation/brazil)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Cambodia National ID
Source: https://docs.didit.me/api-reference/database-validation/cambodia/national-id

POST /v3/database-validation/
Verifies input data against a Government agency database consisting of national identity data of citizens. Authoritative real-time identity lookup for Cambodia. Real-time lookup, pay-per-call.

<div />

Verifies input data against a Government agency database consisting of national identity data of citizens. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 80%
* **Country:** Cambodia
* **Service ID:** `khm_national_id`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field                 | Required | Example              |
| --------------------- | -------: | -------------------- |
| `first_name`          |      Yes | `John`               |
| `last_name`           |      Yes | `Doe`                |
| `date_of_birth`       |      Yes | `1990-01-01`         |
| `voter_id`            |      Yes | `SAMPLE-VOTER-12345` |
| `gender`              |       No | `M`                  |
| `address.street_1`    |       No | `123 Sample Street`  |
| `address.street_2`    |       No | `Unit 4`             |
| `address.city`        |       No | `Sample City`        |
| `address.region`      |       No | `Sample State`       |
| `address.postal_code` |       No | `10001`              |
| `vendor_data`         |       No | `user-1234`          |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `voter_id`
* **Optional inputs:** `gender`, `address.street_1`, `address.street_2`, `address.city`, `address.region`, `address.postal_code`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 80%
* **Price:** \$0.35 per successful query

Not every document this service accepts carries the identifier it queries by. When the identifier is not extracted from the document the check is recorded as **not applicable** - no database is queried and you are not charged - which for some countries is a large share of real users. To cover them, also collect the identifier from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step.

## Body parameters

<ParamField type="string" placeholder="KHM">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `KHM`
</ParamField>

<ParamField type="string" placeholder="khm_national_id">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `khm_national_id`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-VOTER-12345">
  Voter identifier.

  Example: `SAMPLE-VOTER-12345`
</ParamField>

<ParamField type="string" placeholder="M">
  Gender value, when required by the database.

  Allowed values: `M` (male), `F` (female), `X` (other or unknown).

  Example: `M`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* `address` is optional for this service. You can send one complete `address` string and Didit will split it into structured address elements when possible, or you can send the structured fields explicitly.
* `voter_id` must match `(?:\d{8,9}|\d{2}-\d{3}-\d{3})`.
* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=KHM" \
    -F "services=khm_national_id" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "voter_id=SAMPLE-VOTER-12345"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "KHM",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "khm_national_id",
        "service_name": "Cambodia National ID",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "building_number": "SAMPLE-12345",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "state": "Sample State",
          "street": "sample_value",
          "verifications": {
            "date_of_birth": true,
            "full_name": true,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "KHM",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "khm_national_id",
        "service_name": "Cambodia National ID",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "building_number": "SAMPLE-12345",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "state": "Sample State",
          "street": "sample_value",
          "verifications": {
            "date_of_birth": true,
            "full_name": false,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "KHM",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "khm_national_id",
        "service_name": "Cambodia National ID",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `khm_national_id` currently documents this normalized shape:

* `address`
* `address_match_score`
* `building_number`
* `city`
* `date_of_birth`
* `first_name`
* `full_name`
* `identification_number`
* `last_name`
* `name_match_score`
* `state`
* `street`

## Pricing & SLAs

Cambodia National ID queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.35 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Cambodia Database Validation overview](/api-reference/database-validation/cambodia)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Canada Credit Bureau 2 (Non-FINTRAC)
Source: https://docs.didit.me/api-reference/database-validation/canada/credit-bureau-2-non-fintrac

POST /v3/database-validation/
Verifies input data against Credit Header data obtained from a Credit Bureau in Canada. This service does not provide FINTRAC required data but can provide additional fraud detection flags. An agency application is required. Authoritative real-time identity lookup for Canada. Real-time lookup, pay-per-call.

<div />

Verifies input data against Credit Header data obtained from a Credit Bureau in Canada. This service does not provide FINTRAC required data but can provide additional fraud detection flags. An agency application is required. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 85%
* **Country:** Canada
* **Service ID:** `can_credit_bureau_2_non_fintrac`
* **Data domain:** Financial
* **Category:** CreditBureau

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `address.street_1`, `address.postal_code`
* **Optional inputs:** `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 85%
* **Price:** \$1.05 per successful query

## Body parameters

<ParamField type="string" placeholder="CAN">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `CAN`
</ParamField>

<ParamField type="string" placeholder="can_credit_bureau_2_non_fintrac">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `can_credit_bureau_2_non_fintrac`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=CAN" \
    -F "services=can_credit_bureau_2_non_fintrac" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}'
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "CAN",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "can_credit_bureau_2_non_fintrac",
        "service_name": "Canada Credit Bureau 2 (Non-FINTRAC)",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "CAN",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "can_credit_bureau_2_non_fintrac",
        "service_name": "Canada Credit Bureau 2 (Non-FINTRAC)",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "CAN",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "can_credit_bureau_2_non_fintrac",
        "service_name": "Canada Credit Bureau 2 (Non-FINTRAC)",
        "source_data": {
          "address": "NO_MATCH",
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `can_credit_bureau_2_non_fintrac` currently documents this normalized shape:

* `address`
* `date_of_birth`
* `first_name`
* `last_name`

## Pricing & SLAs

Canada Credit Bureau 2 (Non-FINTRAC) queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$1.05 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Canada Database Validation overview](/api-reference/database-validation/canada)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Canada Credit Bureau (FINTRAC)
Source: https://docs.didit.me/api-reference/database-validation/canada/credit-bureau-fintrac

POST /v3/database-validation/
Verifies input data against Credit Header data obtained from a Credit Bureau in Canada and responds with data sufficient to meet FINTRAC requirements. An agency application is required. This service cannot currently be included in a Sequence Package. Authoritative real-time identity lookup for Canada. Real-time lookup, pay-per-call.

<div />

Verifies input data against Credit Header data obtained from a Credit Bureau in Canada and responds with data sufficient to meet FINTRAC requirements. An agency application is required. This service cannot currently be included in a Sequence Package. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 85%
* **Country:** Canada
* **Service ID:** `can_credit_bureau_fintrac`
* **Data domain:** Financial
* **Category:** CreditBureau

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `address.street_1`, `address.postal_code`, `date_of_birth`
* **Optional inputs:** `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 85%
* **Price:** \$2.90 per successful query

## Body parameters

<ParamField type="string" placeholder="CAN">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `CAN`
</ParamField>

<ParamField type="string" placeholder="can_credit_bureau_fintrac">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `can_credit_bureau_fintrac`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=CAN" \
    -F "services=can_credit_bureau_fintrac" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}' \
    -F "date_of_birth=1990-01-01"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "CAN",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "can_credit_bureau_fintrac",
        "service_name": "Canada Credit Bureau (FINTRAC)",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "CAN",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "can_credit_bureau_fintrac",
        "service_name": "Canada Credit Bureau (FINTRAC)",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "CAN",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "can_credit_bureau_fintrac",
        "service_name": "Canada Credit Bureau (FINTRAC)",
        "source_data": {
          "address": "NO_MATCH",
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `can_credit_bureau_fintrac` currently documents this normalized shape:

* `address`
* `date_of_birth`
* `first_name`
* `last_name`

## Pricing & SLAs

Canada Credit Bureau (FINTRAC) queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$2.90 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Canada Database Validation overview](/api-reference/database-validation/canada)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Canada Residential
Source: https://docs.didit.me/api-reference/database-validation/canada/residential

POST /v3/database-validation/
Verifies input data to mobile network operators phone data. An agency application is required. Authoritative real-time identity lookup for Canada. Real-time lookup, pay-per-call.

<div />

Verifies input data to mobile network operators phone data. An agency application is required. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 90%
* **Country:** Canada
* **Service ID:** `can_residential`
* **Data domain:** Address
* **Category:** Residential

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `phone`               |      Yes | `+15550101000`      |
| `date_of_birth`       |       No | `1990-01-01`        |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `address.street_1`, `address.postal_code`, `phone`
* **Optional inputs:** `date_of_birth`, `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 90%
* **Price:** \$0.25 per successful query

## Body parameters

<ParamField type="string" placeholder="CAN">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `CAN`
</ParamField>

<ParamField type="string" placeholder="can_residential">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `can_residential`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  Phone number in international format.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=CAN" \
    -F "services=can_residential" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}' \
    -F "phone=+15550101000"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "CAN",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "can_residential",
        "service_name": "Canada Residential",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "CAN",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "can_residential",
        "service_name": "Canada Residential",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "CAN",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "can_residential",
        "service_name": "Canada Residential",
        "source_data": {
          "address": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `can_residential` currently documents this normalized shape:

* `address`
* `date_of_birth`
* `first_name`
* `last_name`

## Pricing & SLAs

Canada Residential queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.25 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Canada Database Validation overview](/api-reference/database-validation/canada)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Chile - RUT verification
Source: https://docs.didit.me/api-reference/database-validation/chile/rut

POST /v3/database-validation/
Verifies Chilean RUT against the Servicio de Registro Civil records. Authoritative real-time identity lookup for Chile. Real-time lookup, pay-per-call.

<div />

Verifies Chilean RUT against the Servicio de Registro Civil records. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** Chile
* **Service ID:** `chl_rut`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field             | Required | Example            |
| ----------------- | -------: | ------------------ |
| `personal_number` |      Yes | `SAMPLE-PER-12345` |
| `first_name`      |       No | `John`             |
| `last_name`       |       No | `Doe`              |
| `date_of_birth`   |       No | `1990-01-01`       |
| `vendor_data`     |       No | `user-1234`        |

* **Required inputs:** `personal_number`
* **Optional inputs:** `first_name`, `last_name`, `date_of_birth`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** —
* **Price:** \$0.20 per successful query

## Body parameters

<ParamField type="string" placeholder="CHL">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `CHL`
</ParamField>

<ParamField type="string" placeholder="chl_rut">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `chl_rut`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-PER-12345">
  Country-specific personal identity number.

  Example: `SAMPLE-PER-12345`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Chilean RUT (e.g. 12345678-9)
* `personal_number` must be 8-12 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=CHL" \
    -F "services=chl_rut" \
    -F "vendor_data=user-1234" \
    -F "personal_number=SAMPLE-PER-12345"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "CHL",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "chl_rut",
        "service_name": "Chile - RUT verification",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "gender": "M",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "CHL",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "chl_rut",
        "service_name": "Chile - RUT verification",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `chl_rut` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `gender`
* `identification_number`
* `last_name`

## Pricing & SLAs

Chile - RUT verification queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.20 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Chile Database Validation overview](/api-reference/database-validation/chile)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# China Bank Card
Source: https://docs.didit.me/api-reference/database-validation/china/bank-card

POST /v3/database-validation/
Verifies input data against the official data service in China. Authoritative real-time identity lookup for China. Real-time lookup, pay-per-call.

<div />

Verifies input data against the official data service in China. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 100%
* **Country:** China
* **Service ID:** `chn_bank_card`
* **Data domain:** Financial
* **Category:** Banking

## Inputs

| Field              | Required | Example              |
| ------------------ | -------: | -------------------- |
| `full_name`        |      Yes | `王新伟`                |
| `date_of_birth`    |      Yes | `1990-01-01`         |
| `national_id`      |      Yes | `11010519900101003X` |
| `bank_card_number` |      Yes | `4111111111111111`   |
| `vendor_data`      |       No | `user-1234`          |

* **Required inputs:** `full_name`, `date_of_birth`, `national_id`, `bank_card_number`
* **Optional inputs:** `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow with field mapping
* **Coverage:** \~ 100%
* **Price:** \$0.40 per successful query

In a workflow, `bank_card_number` is not printed on an identity document, so no step produces it on its own. Collect it from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step. Until it is mapped the workflow editor shows this service disabled and names the missing input; at run time a missing input means the check is skipped before any query, so you are never billed for a database that could not be asked.

## Body parameters

<ParamField type="string" placeholder="CHN">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `CHN`
</ParamField>

<ParamField type="string" placeholder="chn_bank_card">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `chn_bank_card`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="王新伟">
  Full legal name to validate.

  Example: `王新伟`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="11010519900101003X">
  National identity number for this service.

  Example: `11010519900101003X`
</ParamField>

<ParamField type="string" placeholder="4111111111111111">
  Bank card number.

  Example: `4111111111111111`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Date of birth must match the birth date encoded in the Chinese national ID (digits 7-14 of an 18-character number, 7-12 of a legacy 15-digit one)
* `date_of_birth` must match the birth date encoded in `national_id`; the source rejects the request outright when the two disagree, so a mismatch is refused before the lookup and is not charged.
* Chinese resident identity card number (15 digits or 18 characters with checksum)
* `national_id` must match `(?:\d{15}|\d{17}[\dXx])`.
* The final Chinese Resident Identity Card check character is validated.
* `full_name` must be the original Chinese-script name as it appears in the registry or on the document. Do not send the Latin transliteration for China database checks.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=CHN" \
    -F "services=chn_bank_card" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "full_name=王新伟" \
    -F "date_of_birth=1990-01-01" \
    -F "national_id=11010519900101003X" \
    -F "bank_card_number=4111111111111111"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "CHN",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "chn_bank_card",
        "service_name": "China Bank Card",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "full_name": "王新伟",
          "identification_number": "11010519900101003X"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "CHN",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "chn_bank_card",
        "service_name": "China Bank Card",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "full_name": "王新伟",
          "identification_number": "11010519900101003X"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "CHN",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "chn_bank_card",
        "service_name": "China Bank Card",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `chn_bank_card` currently documents this normalized shape:

* `date_of_birth`
* `full_name`
* `identification_number`

## Pricing & SLAs

China Bank Card queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.40 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [China Database Validation overview](/api-reference/database-validation/china)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# China National ID
Source: https://docs.didit.me/api-reference/database-validation/china/national-id

POST /v3/database-validation/
Verifies input data against the official data service in China. Authoritative real-time identity lookup for China. Real-time lookup, pay-per-call.

<div />

Verifies input data against the official data service in China. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 100%
* **Country:** China
* **Service ID:** `chn_national_id`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field           | Required | Example              |
| --------------- | -------: | -------------------- |
| `full_name`     |      Yes | `王新伟`                |
| `date_of_birth` |      Yes | `1990-01-01`         |
| `national_id`   |      Yes | `11010519900101003X` |
| `vendor_data`   |       No | `user-1234`          |

* **Required inputs:** `full_name`, `date_of_birth`, `national_id`
* **Optional inputs:** `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 100%
* **Price:** \$0.30 per successful query

Not every document this service accepts carries the identifier it queries by. When the identifier is not extracted from the document the check is recorded as **not applicable** - no database is queried and you are not charged - which for some countries is a large share of real users. To cover them, also collect the identifier from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step.

## Body parameters

<ParamField type="string" placeholder="CHN">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `CHN`
</ParamField>

<ParamField type="string" placeholder="chn_national_id">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `chn_national_id`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="王新伟">
  Full legal name to validate.

  Example: `王新伟`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="11010519900101003X">
  National identity number for this service.

  Example: `11010519900101003X`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Date of birth must match the birth date encoded in the Chinese national ID (digits 7-14 of an 18-character number, 7-12 of a legacy 15-digit one)
* `date_of_birth` must match the birth date encoded in `national_id`; the source rejects the request outright when the two disagree, so a mismatch is refused before the lookup and is not charged.
* `national_id` must match `(\d{15}|\d{17}[\dXx])`.
* The final Chinese Resident Identity Card check character is validated.
* `full_name` must be the original Chinese-script name as it appears in the registry or on the document. Do not send the Latin transliteration for China database checks.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=CHN" \
    -F "services=chn_national_id" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "full_name=王新伟" \
    -F "date_of_birth=1990-01-01" \
    -F "national_id=11010519900101003X"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "CHN",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "chn_national_id",
        "service_name": "China National ID",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "identification_number": "11010519900101003X",
          "verifications": {
            "date_of_birth": true,
            "full_name": true,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "CHN",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "chn_national_id",
        "service_name": "China National ID",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "identification_number": "11010519900101003X",
          "verifications": {
            "date_of_birth": true,
            "full_name": false,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "CHN",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "chn_national_id",
        "service_name": "China National ID",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `chn_national_id` currently documents this normalized shape:

* `date_of_birth`
* `identification_number`

## Pricing & SLAs

China National ID queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.30 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [China Database Validation overview](/api-reference/database-validation/china)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# China Passport Verification
Source: https://docs.didit.me/api-reference/database-validation/china/passport-verification

POST /v3/database-validation/
Verifies input data against the official data service in China. Authoritative real-time identity lookup for China. Real-time lookup, pay-per-call.

<div />

Verifies input data against the official data service in China. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 100%
* **Country:** China
* **Service ID:** `chn_passport_verification`
* **Data domain:** Document
* **Category:** Passport

## Inputs

| Field             | Required | Example              |
| ----------------- | -------: | -------------------- |
| `full_name`       |      Yes | `王新伟`                |
| `date_of_birth`   |      Yes | `1990-01-01`         |
| `national_id`     |      Yes | `11010519900101003X` |
| `passport_number` |      Yes | `SAMPLE-PASS-12345`  |
| `vendor_data`     |       No | `user-1234`          |

* **Required inputs:** `full_name`, `date_of_birth`, `national_id`, `passport_number`
* **Optional inputs:** `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 100%
* **Price:** \$1.00 per successful query

Not every document this service accepts carries the identifier it queries by. When the identifier is not extracted from the document the check is recorded as **not applicable** - no database is queried and you are not charged - which for some countries is a large share of real users. To cover them, also collect the identifier from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step.

## Body parameters

<ParamField type="string" placeholder="CHN">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `CHN`
</ParamField>

<ParamField type="string" placeholder="chn_passport_verification">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `chn_passport_verification`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="王新伟">
  Full legal name to validate.

  Example: `王新伟`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="11010519900101003X">
  National identity number for this service.

  Example: `11010519900101003X`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-PASS-12345">
  Passport number.

  Example: `SAMPLE-PASS-12345`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Date of birth must match the birth date encoded in the Chinese national ID (digits 7-14 of an 18-character number, 7-12 of a legacy 15-digit one)
* `date_of_birth` must match the birth date encoded in `national_id`; the source rejects the request outright when the two disagree, so a mismatch is refused before the lookup and is not charged.
* `national_id` must match `(?:\d{15}|\d{17}[\dXx])`.
* The final Chinese Resident Identity Card check character is validated.
* `full_name` must be the original Chinese-script name as it appears in the registry or on the document. Do not send the Latin transliteration for China database checks.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=CHN" \
    -F "services=chn_passport_verification" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "full_name=王新伟" \
    -F "date_of_birth=1990-01-01" \
    -F "national_id=11010519900101003X" \
    -F "passport_number=SAMPLE-PASS-12345"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "CHN",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "chn_passport_verification",
        "service_name": "China Passport Verification",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "identification_number": "11010519900101003X",
          "verifications": {
            "date_of_birth": true,
            "full_name": true,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "CHN",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "chn_passport_verification",
        "service_name": "China Passport Verification",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "identification_number": "11010519900101003X",
          "verifications": {
            "date_of_birth": true,
            "full_name": false,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "CHN",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "chn_passport_verification",
        "service_name": "China Passport Verification",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `chn_passport_verification` currently documents this normalized shape:

* `date_of_birth`
* `identification_number`

## Pricing & SLAs

China Passport Verification queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$1.00 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [China Database Validation overview](/api-reference/database-validation/china)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# China Phone
Source: https://docs.didit.me/api-reference/database-validation/china/phone

POST /v3/database-validation/
Verifies input data against the official data service in China. Authoritative real-time identity lookup for China. Real-time lookup, pay-per-call.

<div />

Verifies input data against the official data service in China. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 100%
* **Country:** China
* **Service ID:** `chn_phone`
* **Data domain:** Telecom
* **Category:** Telecom

## Inputs

| Field           | Required | Example              |
| --------------- | -------: | -------------------- |
| `full_name`     |      Yes | `王新伟`                |
| `date_of_birth` |      Yes | `1990-01-01`         |
| `national_id`   |      Yes | `11010519900101003X` |
| `phone`         |      Yes | `+15550101000`       |
| `vendor_data`   |       No | `user-1234`          |

* **Required inputs:** `full_name`, `date_of_birth`, `national_id`, `phone`
* **Optional inputs:** `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 100%
* **Price:** \$0.30 per successful query

## Body parameters

<ParamField type="string" placeholder="CHN">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `CHN`
</ParamField>

<ParamField type="string" placeholder="chn_phone">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `chn_phone`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="王新伟">
  Full legal name to validate.

  Example: `王新伟`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="11010519900101003X">
  National identity number for this service.

  Example: `11010519900101003X`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  Phone number in international format.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Date of birth must match the birth date encoded in the Chinese national ID (digits 7-14 of an 18-character number, 7-12 of a legacy 15-digit one)
* `date_of_birth` must match the birth date encoded in `national_id`; the source rejects the request outright when the two disagree, so a mismatch is refused before the lookup and is not charged.
* Chinese resident identity card number (15 digits or 18 characters with checksum)
* `national_id` must match `(?:\d{15}|\d{17}[\dXx])`.
* The final Chinese Resident Identity Card check character is validated.
* `full_name` must be the original Chinese-script name as it appears in the registry or on the document. Do not send the Latin transliteration for China database checks.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=CHN" \
    -F "services=chn_phone" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "full_name=王新伟" \
    -F "date_of_birth=1990-01-01" \
    -F "national_id=11010519900101003X" \
    -F "phone=+15550101000"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "CHN",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "chn_phone",
        "service_name": "China Phone",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "full_name": "王新伟",
          "identification_number": "11010519900101003X"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "CHN",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "chn_phone",
        "service_name": "China Phone",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "full_name": "王新伟",
          "identification_number": "11010519900101003X"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "CHN",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "chn_phone",
        "service_name": "China Phone",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `chn_phone` currently documents this normalized shape:

* `date_of_birth`
* `full_name`
* `identification_number`

## Pricing & SLAs

China Phone queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.30 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [China Database Validation overview](/api-reference/database-validation/china)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Colombia - Cédula verification
Source: https://docs.didit.me/api-reference/database-validation/colombia/cedula

POST /v3/database-validation/
Verifies Colombian citizen identity data against Registraduría General de la Nación / ANI government records. Authoritative real-time identity lookup for Colombia. Real-time lookup, pay-per-call.

<div />

Verifies Colombian citizen identity data against Registraduría General de la Nación / ANI government records. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 90-95%
* **Country:** Colombia
* **Service ID:** `col_cedula`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field             | Required | Example      |
| ----------------- | -------: | ------------ |
| `personal_number` |      Yes | `111111`     |
| `date_of_issue`   |      Yes | `1990-01-01` |
| `first_name`      |       No | `John`       |
| `last_name`       |       No | `Doe`        |
| `vendor_data`     |       No | `user-1234`  |

* **Required inputs:** `personal_number`, `date_of_issue`
* **Optional inputs:** `first_name`, `last_name`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** 90-95%
* **Price:** \$0.20 per successful query

## Body parameters

<ParamField type="string" placeholder="COL">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `COL`
</ParamField>

<ParamField type="string" placeholder="col_cedula">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `col_cedula`
</ParamField>

<ParamField type="string" placeholder="111111">
  Country-specific personal identity number.

  Example: `111111`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  `date_of_issue` value required by this database service.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Colombian Cédula (6-10 digits)
* `personal_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `personal_number` must be 6-10 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=COL" \
    -F "services=col_cedula" \
    -F "vendor_data=user-1234" \
    -F "personal_number=111111" \
    -F "date_of_issue=1990-01-01"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "COL",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "col_cedula",
        "service_name": "Colombia - Cédula verification",
        "source_data": {
          "cedula_status": "sample_value",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "verifications": {
            "identification_number": true
          }
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "COL",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "col_cedula",
        "service_name": "Colombia - Cédula verification",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `col_cedula` currently documents this normalized shape:

* `cedula_status`
* `first_name`
* `identification_number`
* `last_name`

## Pricing & SLAs

Colombia - Cédula verification queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.20 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Colombia Database Validation overview](/api-reference/database-validation/colombia)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Colombia - Migración Colombia foreigner status
Source: https://docs.didit.me/api-reference/database-validation/colombia/migracion

POST /v3/database-validation/
Verifies a foreigner's migratory status and identity against Migración Colombia government records (cédula de extranjería). Authoritative real-time identity lookup for Colombia. Real-time lookup, pay-per-call.

<div />

Verifies a foreigner's migratory status and identity against Migración Colombia government records (cédula de extranjería). Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** Colombia
* **Service ID:** `col_migracion`
* **Data domain:** Identity
* **Category:** ResidencePermit

## Inputs

| Field             | Required | Example      |
| ----------------- | -------: | ------------ |
| `personal_number` |      Yes | `111111`     |
| `date_of_birth`   |      Yes | `1990-01-01` |
| `nationality`     |      Yes | `MEX`        |
| `first_name`      |       No | `John`       |
| `last_name`       |       No | `Doe`        |
| `vendor_data`     |       No | `user-1234`  |

* **Required inputs:** `personal_number`, `date_of_birth`, `nationality`
* **Optional inputs:** `first_name`, `last_name`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** —
* **Price:** \$1.20 per successful query

## Body parameters

<ParamField type="string" placeholder="COL">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `COL`
</ParamField>

<ParamField type="string" placeholder="col_migracion">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `col_migracion`
</ParamField>

<ParamField type="string" placeholder="111111">
  Country-specific personal identity number.

  Example: `111111`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="MEX">
  `nationality` value required by this database service.

  Example: `MEX`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Colombian Cédula (6-10 digits)
* `personal_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `personal_number` must be 6-10 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=COL" \
    -F "services=col_migracion" \
    -F "vendor_data=user-1234" \
    -F "personal_number=111111" \
    -F "date_of_birth=1990-01-01" \
    -F "nationality=MEX"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "COL",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "col_migracion",
        "service_name": "Colombia - Migración Colombia foreigner status",
        "source_data": {
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "COL",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "col_migracion",
        "service_name": "Colombia - Migración Colombia foreigner status",
        "source_data": {
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "COL",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "col_migracion",
        "service_name": "Colombia - Migración Colombia foreigner status",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `col_migracion` currently documents this normalized shape:

* `first_name`
* `identification_number`
* `last_name`

## Pricing & SLAs

Colombia - Migración Colombia foreigner status queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$1.20 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Colombia Database Validation overview](/api-reference/database-validation/colombia)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Costa Rica - Cédula verification
Source: https://docs.didit.me/api-reference/database-validation/costa-rica/cedula

POST /v3/database-validation/
Verifies Costa Rican national identity card data against Tribunal Supremo de Elecciones government records. Authoritative real-time identity lookup for Costa Rica. Real-time lookup, pay-per-call.

<div />

Verifies Costa Rican national identity card data against Tribunal Supremo de Elecciones government records. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 90-95%
* **Country:** Costa Rica
* **Service ID:** `cri_cedula`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field             | Required | Example     |
| ----------------- | -------: | ----------- |
| `personal_number` |      Yes | `111111111` |
| `first_name`      |       No | `John`      |
| `last_name`       |       No | `Doe`       |
| `vendor_data`     |       No | `user-1234` |

* **Required inputs:** `personal_number`
* **Optional inputs:** `first_name`, `last_name`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** 90-95%
* **Price:** \$0.20 per successful query

## Body parameters

<ParamField type="string" placeholder="CRI">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `CRI`
</ParamField>

<ParamField type="string" placeholder="cri_cedula">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `cri_cedula`
</ParamField>

<ParamField type="string" placeholder="111111111">
  Country-specific personal identity number.

  Example: `111111111`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Costa Rican Cédula (9-12 digits)
* `personal_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `personal_number` must be 9-12 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=CRI" \
    -F "services=cri_cedula" \
    -F "vendor_data=user-1234" \
    -F "personal_number=111111111"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "CRI",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "cri_cedula",
        "service_name": "Costa Rica - Cédula verification",
        "source_data": {
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "CRI",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "cri_cedula",
        "service_name": "Costa Rica - Cédula verification",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```

  **`DOCUMENT_NOT_FOUND`** — The submitted document number does not correspond to any record in the registry.

  ```json 200 OK — DOCUMENT_NOT_FOUND theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "CRI",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "DOCUMENT_NOT_FOUND",
        "service_id": "cri_cedula",
        "service_name": "Costa Rica - Cédula verification",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `cri_cedula` currently documents this normalized shape:

* `first_name`
* `full_name`
* `identification_number`
* `last_name`

## Pricing & SLAs

Costa Rica - Cédula verification queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.20 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Costa Rica Database Validation overview](/api-reference/database-validation/costa-rica)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Denmark Consumer 2
Source: https://docs.didit.me/api-reference/database-validation/denmark/consumer-2

POST /v3/database-validation/
Input is verified against a source comprising multiple datasets from consumer, telephone and utility records. Authoritative real-time identity lookup for Denmark. Real-time lookup, pay-per-call.

<div />

Input is verified against a source comprising multiple datasets from consumer, telephone and utility records. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 50%
* **Country:** Denmark
* **Service ID:** `dnk_consumer_2`
* **Data domain:** Address
* **Category:** Residential

## Inputs

| Field                 | Required | Example                |
| --------------------- | -------: | ---------------------- |
| `first_name`          |      Yes | `John`                 |
| `last_name`           |      Yes | `Doe`                  |
| `date_of_birth`       |      Yes | `1990-01-01`           |
| `address.street_1`    |       No | `123 Sample Street`    |
| `address.street_2`    |       No | `Unit 4`               |
| `address.city`        |       No | `Sample City`          |
| `address.region`      |       No | `Sample State`         |
| `address.postal_code` |       No | `10001`                |
| `phone`               |       No | `+15550101000`         |
| `email`               |       No | `john.doe@example.com` |
| `vendor_data`         |       No | `user-1234`            |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`
* **Optional inputs:** `address.street_1`, `address.street_2`, `address.city`, `address.region`, `address.postal_code`, `phone`, `email`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 50%
* **Price:** \$0.97 per successful query

## Body parameters

<ParamField type="string" placeholder="DNK">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `DNK`
</ParamField>

<ParamField type="string" placeholder="dnk_consumer_2">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `dnk_consumer_2`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  Phone number in international format.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="john.doe@example.com">
  Email address.

  Example: `john.doe@example.com`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* `address` is optional for this service. You can send one complete `address` string and Didit will split it into structured address elements when possible, or you can send the structured fields explicitly.
* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=DNK" \
    -F "services=dnk_consumer_2" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "DNK",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "dnk_consumer_2",
        "service_name": "Denmark Consumer 2",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "DNK",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "dnk_consumer_2",
        "service_name": "Denmark Consumer 2",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "DNK",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "dnk_consumer_2",
        "service_name": "Denmark Consumer 2",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `dnk_consumer_2` currently documents this normalized shape:

* `address`
* `date_of_birth`
* `first_name`
* `last_name`

## Pricing & SLAs

Denmark Consumer 2 queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.97 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Denmark Database Validation overview](/api-reference/database-validation/denmark)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Denmark National ID
Source: https://docs.didit.me/api-reference/database-validation/denmark/national-id

POST /v3/database-validation/
Verifies input data against the Civil Registration service. Authoritative real-time identity lookup for Denmark. Real-time lookup, pay-per-call.

<div />

Verifies input data against the Civil Registration service. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 100%
* **Country:** Denmark
* **Service ID:** `dnk_national_id`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `national_id`         |      Yes | `SAMPLE-NID-12345`  |
| `address.street_1`    |       No | `123 Sample Street` |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `address.postal_code` |       No | `10001`             |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `national_id`
* **Optional inputs:** `address.street_1`, `address.street_2`, `address.city`, `address.region`, `address.postal_code`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 100%
* **Price:** \$1.39 per successful query

Not every document this service accepts carries the identifier it queries by. When the identifier is not extracted from the document the check is recorded as **not applicable** - no database is queried and you are not charged - which for some countries is a large share of real users. To cover them, also collect the identifier from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step.

## Body parameters

<ParamField type="string" placeholder="DNK">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `DNK`
</ParamField>

<ParamField type="string" placeholder="dnk_national_id">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `dnk_national_id`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-NID-12345">
  National identity number for this service.

  Example: `SAMPLE-NID-12345`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* `address` is optional for this service. You can send one complete `address` string and Didit will split it into structured address elements when possible, or you can send the structured fields explicitly.
* `national_id` must match `\d{6}-?\d{4}`.
* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=DNK" \
    -F "services=dnk_national_id" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "national_id=SAMPLE-NID-12345"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "DNK",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "dnk_national_id",
        "service_name": "Denmark National ID",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": true,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "DNK",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "dnk_national_id",
        "service_name": "Denmark National ID",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": false,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "DNK",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "dnk_national_id",
        "service_name": "Denmark National ID",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `dnk_national_id` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `full_name`
* `identification_number`
* `last_name`
* `name_match_score`

## Pricing & SLAs

Denmark National ID queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$1.39 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Denmark Database Validation overview](/api-reference/database-validation/denmark)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Dominican Republic - Cédula verification
Source: https://docs.didit.me/api-reference/database-validation/dominican-republic/cedula

POST /v3/database-validation/
Verifies Dominican Cédula directly against the Junta Central Electoral civil registry. Authoritative real-time identity lookup for Dominican Republic. Real-time lookup, pay-per-call.

<div />

Verifies Dominican Cédula directly against the Junta Central Electoral civil registry. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** Dominican Republic
* **Service ID:** `dom_cedula`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field             | Required | Example       |
| ----------------- | -------: | ------------- |
| `personal_number` |      Yes | `11111111111` |
| `vendor_data`     |       No | `user-1234`   |

* **Required inputs:** `personal_number`
* **Optional inputs:** `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** —
* **Price:** \$0.05 per successful query

## Body parameters

<ParamField type="string" placeholder="DOM">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `DOM`
</ParamField>

<ParamField type="string" placeholder="dom_cedula">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `dom_cedula`
</ParamField>

<ParamField type="string" placeholder="11111111111">
  Country-specific personal identity number.

  Example: `11111111111`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Dominican Cédula (exactly 11 digits)
* `personal_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `personal_number` must be exactly 11 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=DOM" \
    -F "services=dom_cedula" \
    -F "vendor_data=user-1234" \
    -F "personal_number=11111111111"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "DOM",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "dom_cedula",
        "service_name": "Dominican Republic - Cédula verification",
        "source_data": {
          "identification_number": "SAMPLE-ID-12345"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "DOM",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "dom_cedula",
        "service_name": "Dominican Republic - Cédula verification",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `dom_cedula` currently documents this normalized shape:

* `identification_number`

## Pricing & SLAs

Dominican Republic - Cédula verification queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.05 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Dominican Republic Database Validation overview](/api-reference/database-validation/dominican-republic)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Ecuador - Cédula verification
Source: https://docs.didit.me/api-reference/database-validation/ecuador/cedula

POST /v3/database-validation/
Verifies Ecuadorian Cédula against the Registro Civil records. Authoritative real-time identity lookup for Ecuador. Real-time lookup, pay-per-call.

<div />

Verifies Ecuadorian Cédula against the Registro Civil records. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** Ecuador
* **Service ID:** `ecu_cedula`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field             | Required | Example      |
| ----------------- | -------: | ------------ |
| `personal_number` |      Yes | `1111111111` |
| `first_name`      |       No | `John`       |
| `last_name`       |       No | `Doe`        |
| `vendor_data`     |       No | `user-1234`  |

* **Required inputs:** `personal_number`
* **Optional inputs:** `first_name`, `last_name`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** —
* **Price:** \$0.20 per successful query

## Body parameters

<ParamField type="string" placeholder="ECU">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `ECU`
</ParamField>

<ParamField type="string" placeholder="ecu_cedula">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `ecu_cedula`
</ParamField>

<ParamField type="string" placeholder="1111111111">
  Country-specific personal identity number.

  Example: `1111111111`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Ecuadorian Cédula (exactly 10 digits)
* `personal_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `personal_number` must be exactly 10 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=ECU" \
    -F "services=ecu_cedula" \
    -F "vendor_data=user-1234" \
    -F "personal_number=1111111111"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "ECU",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "ecu_cedula",
        "service_name": "Ecuador - Cédula verification",
        "source_data": {
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ECU",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "ecu_cedula",
        "service_name": "Ecuador - Cédula verification",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `ecu_cedula` currently documents this normalized shape:

* `first_name`
* `identification_number`
* `last_name`

## Pricing & SLAs

Ecuador - Cédula verification queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.20 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Ecuador Database Validation overview](/api-reference/database-validation/ecuador)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# El Salvador - DUI verification
Source: https://docs.didit.me/api-reference/database-validation/el-salvador/dui

POST /v3/database-validation/
Verifies Salvadoran DUI data against RNPN government records. Authoritative real-time identity lookup for El Salvador. Real-time lookup, pay-per-call.

<div />

Verifies Salvadoran DUI data against RNPN government records. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 90-95%
* **Country:** El Salvador
* **Service ID:** `slv_dui`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field             | Required | Example      |
| ----------------- | -------: | ------------ |
| `document_number` |      Yes | `111111111`  |
| `date_of_birth`   |      Yes | `1990-01-01` |
| `first_name`      |       No | `John`       |
| `last_name`       |       No | `Doe`        |
| `vendor_data`     |       No | `user-1234`  |

* **Required inputs:** `document_number`, `date_of_birth`
* **Optional inputs:** `first_name`, `last_name`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** 90-95%
* **Price:** \$0.20 per successful query

## Body parameters

<ParamField type="string" placeholder="SLV">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `SLV`
</ParamField>

<ParamField type="string" placeholder="slv_dui">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `slv_dui`
</ParamField>

<ParamField type="string" placeholder="111111111">
  Document number extracted from or provided by the user.

  Example: `111111111`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Salvadoran DUI (exactly 9 digits)
* `document_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `document_number` must be exactly 9 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=SLV" \
    -F "services=slv_dui" \
    -F "vendor_data=user-1234" \
    -F "document_number=111111111" \
    -F "date_of_birth=1990-01-01"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "SLV",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "slv_dui",
        "service_name": "El Salvador - DUI verification",
        "source_data": {
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345"
        },
        "validation": {
          "date_of_birth": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "SLV",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "slv_dui",
        "service_name": "El Salvador - DUI verification",
        "source_data": {
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345"
        },
        "validation": {
          "date_of_birth": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "SLV",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "slv_dui",
        "service_name": "El Salvador - DUI verification",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `slv_dui` currently documents this normalized shape:

* `full_name`
* `identification_number`

## Pricing & SLAs

El Salvador - DUI verification queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.20 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [El Salvador Database Validation overview](/api-reference/database-validation/el-salvador)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Finland Consumer 2
Source: https://docs.didit.me/api-reference/database-validation/finland/consumer-2

POST /v3/database-validation/
Verifies Finland Consumer 2. Authoritative real-time identity lookup for Finland. Real-time lookup, pay-per-call.

<div />

Verifies Finland Consumer 2. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** Finland
* **Service ID:** `fin_consumer_2`
* **Data domain:** Address
* **Category:** Residential

## Inputs

| Field                 | Required | Example                |
| --------------------- | -------: | ---------------------- |
| `first_name`          |      Yes | `John`                 |
| `last_name`           |      Yes | `Doe`                  |
| `date_of_birth`       |      Yes | `1990-01-01`           |
| `address.street_1`    |       No | `123 Sample Street`    |
| `address.street_2`    |       No | `Unit 4`               |
| `address.city`        |       No | `Sample City`          |
| `address.region`      |       No | `Sample State`         |
| `address.postal_code` |       No | `10001`                |
| `phone`               |       No | `+15550101000`         |
| `email`               |       No | `john.doe@example.com` |
| `vendor_data`         |       No | `user-1234`            |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`
* **Optional inputs:** `address.street_1`, `address.street_2`, `address.city`, `address.region`, `address.postal_code`, `phone`, `email`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** —
* **Price:** \$0.97 per successful query

## Body parameters

<ParamField type="string" placeholder="FIN">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `FIN`
</ParamField>

<ParamField type="string" placeholder="fin_consumer_2">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `fin_consumer_2`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  Phone number in international format.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="john.doe@example.com">
  Email address.

  Example: `john.doe@example.com`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* `address` is optional for this service. You can send one complete `address` string and Didit will split it into structured address elements when possible, or you can send the structured fields explicitly.
* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=FIN" \
    -F "services=fin_consumer_2" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "FIN",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "fin_consumer_2",
        "service_name": "Finland Consumer 2",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "FIN",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "fin_consumer_2",
        "service_name": "Finland Consumer 2",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "FIN",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "fin_consumer_2",
        "service_name": "Finland Consumer 2",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `fin_consumer_2` currently documents this normalized shape:

* `address`
* `date_of_birth`
* `first_name`
* `last_name`

## Pricing & SLAs

Finland Consumer 2 queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.97 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Finland Database Validation overview](/api-reference/database-validation/finland)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Finland National ID
Source: https://docs.didit.me/api-reference/database-validation/finland/national-id

POST /v3/database-validation/
Verifies input data against the official issuing agency of the Finnish Identity Card. Authoritative real-time identity lookup for Finland. Real-time lookup, pay-per-call.

<div />

Verifies input data against the official issuing agency of the Finnish Identity Card. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 100%
* **Country:** Finland
* **Service ID:** `fin_national_id`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `national_id`         |      Yes | `SAMPLE-NID-12345`  |
| `address.street_1`    |       No | `123 Sample Street` |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `address.postal_code` |       No | `10001`             |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `national_id`
* **Optional inputs:** `address.street_1`, `address.street_2`, `address.city`, `address.region`, `address.postal_code`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 100%
* **Price:** \$2.10 per successful query

Not every document this service accepts carries the identifier it queries by. When the identifier is not extracted from the document the check is recorded as **not applicable** - no database is queried and you are not charged - which for some countries is a large share of real users. To cover them, also collect the identifier from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step.

## Body parameters

<ParamField type="string" placeholder="FIN">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `FIN`
</ParamField>

<ParamField type="string" placeholder="fin_national_id">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `fin_national_id`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-NID-12345">
  National identity number for this service.

  Example: `SAMPLE-NID-12345`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* `address` is optional for this service. You can send one complete `address` string and Didit will split it into structured address elements when possible, or you can send the structured fields explicitly.
* `national_id` must match `(?:\d{6}[-+A]\d{3}[0-9A-Z]|\d{6}\d{3}[0-9A-Z])`.
* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=FIN" \
    -F "services=fin_national_id" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "national_id=SAMPLE-NID-12345"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "FIN",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "fin_national_id",
        "service_name": "Finland National ID",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "FIN",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "fin_national_id",
        "service_name": "Finland National ID",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "FIN",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "fin_national_id",
        "service_name": "Finland National ID",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `fin_national_id` currently documents this normalized shape:

* `address`
* `date_of_birth`
* `first_name`
* `identification_number`
* `last_name`

## Pricing & SLAs

Finland National ID queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$2.10 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Finland Database Validation overview](/api-reference/database-validation/finland)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# France Phone
Source: https://docs.didit.me/api-reference/database-validation/france/phone

POST /v3/database-validation/
Verifies input data to mobile network operators phone data. Authoritative real-time identity lookup for France. Real-time lookup, pay-per-call.

<div />

Verifies input data to mobile network operators phone data. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 90%
* **Country:** France
* **Service ID:** `fra_phone`
* **Data domain:** Telecom
* **Category:** Telecom

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `phone`               |      Yes | `+15550101000`      |
| `date_of_birth`       |       No | `1990-01-01`        |
| `address.street_1`    |       No | `123 Sample Street` |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `address.postal_code` |       No | `10001`             |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `phone`
* **Optional inputs:** `date_of_birth`, `address.street_1`, `address.street_2`, `address.city`, `address.region`, `address.postal_code`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 90%
* **Price:** \$0.67 per successful query

## Body parameters

<ParamField type="string" placeholder="FRA">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `FRA`
</ParamField>

<ParamField type="string" placeholder="fra_phone">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `fra_phone`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  Phone number in international format.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* `address` is optional for this service. You can send one complete `address` string and Didit will split it into structured address elements when possible, or you can send the structured fields explicitly.
* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=FRA" \
    -F "services=fra_phone" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "phone=+15550101000"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "FRA",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "fra_phone",
        "service_name": "France Phone",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "FRA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "fra_phone",
        "service_name": "France Phone",
        "source_data": {
          "full_name": "NO_MATCH"
        },
        "validation": {
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `fra_phone` currently documents this normalized shape:

* `address`
* `date_of_birth`
* `first_name`
* `last_name`

## Pricing & SLAs

France Phone queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.67 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [France Database Validation overview](/api-reference/database-validation/france)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# France Residential
Source: https://docs.didit.me/api-reference/database-validation/france/residential

POST /v3/database-validation/
Verifies data against government agency sourced census data. Authoritative real-time identity lookup for France. Real-time lookup, pay-per-call.

<div />

Verifies data against government agency sourced census data. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 85%
* **Country:** France
* **Service ID:** `fra_residential`
* **Data domain:** Address
* **Category:** Residential

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `address.street_1`, `address.postal_code`
* **Optional inputs:** `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 85%
* **Price:** \$0.89 per successful query

## Body parameters

<ParamField type="string" placeholder="FRA">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `FRA`
</ParamField>

<ParamField type="string" placeholder="fra_residential">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `fra_residential`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=FRA" \
    -F "services=fra_residential" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}'
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "FRA",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "fra_residential",
        "service_name": "France Residential",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "postal_code": "10001",
          "street": "sample_value"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "FRA",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "fra_residential",
        "service_name": "France Residential",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "postal_code": "10001",
          "street": "sample_value"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "FRA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "fra_residential",
        "service_name": "France Residential",
        "source_data": {
          "address": "NO_MATCH",
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `fra_residential` currently documents this normalized shape:

* `address`
* `address_match_score`
* `city`
* `date_of_birth`
* `first_name`
* `full_name`
* `last_name`
* `name_match_score`
* `postal_code`
* `street`

## Pricing & SLAs

France Residential queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.89 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [France Database Validation overview](/api-reference/database-validation/france)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# France Utility
Source: https://docs.didit.me/api-reference/database-validation/france/utility

POST /v3/database-validation/
Aggregated service of public records, background records, and public professional profiles. Authoritative real-time identity lookup for France. Real-time lookup, pay-per-call.

<div />

Aggregated service of public records, background records, and public professional profiles. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** > 75%
* **Country:** France
* **Service ID:** `fra_utility`
* **Data domain:** Address
* **Category:** Utility

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `address.street_1`, `address.postal_code`
* **Optional inputs:** `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** > 75%
* **Price:** \$0.65 per successful query

## Body parameters

<ParamField type="string" placeholder="FRA">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `FRA`
</ParamField>

<ParamField type="string" placeholder="fra_utility">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `fra_utility`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=FRA" \
    -F "services=fra_utility" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}'
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "FRA",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "fra_utility",
        "service_name": "France Utility",
        "source_data": {
          "address_match_score": "1.000",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "address": true,
            "date_of_birth": true,
            "full_name": true
          }
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "FRA",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "fra_utility",
        "service_name": "France Utility",
        "source_data": {
          "address_match_score": "1.000",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "address": true,
            "date_of_birth": true,
            "full_name": false
          }
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "FRA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "fra_utility",
        "service_name": "France Utility",
        "source_data": {
          "address": "NO_MATCH",
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `fra_utility` currently documents this normalized shape:

* `address_match_score`
* `date_of_birth`
* `first_name`
* `full_name`
* `last_name`
* `name_match_score`

## Pricing & SLAs

France Utility queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.65 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [France Database Validation overview](/api-reference/database-validation/france)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Germany Credit Bureau
Source: https://docs.didit.me/api-reference/database-validation/germany/credit-bureau

POST /v3/database-validation/
Verifies input data against Credit Header data obtained from a Credit Bureau in Germany. Authoritative real-time identity lookup for Germany. Real-time lookup, pay-per-call.

<div />

Verifies input data against Credit Header data obtained from a Credit Bureau in Germany. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 80%
* **Country:** Germany
* **Service ID:** `deu_credit_bureau`
* **Data domain:** Financial
* **Category:** CreditBureau

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `address.street_1`, `address.postal_code`
* **Optional inputs:** `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 80%
* **Price:** \$0.84 per successful query

## Body parameters

<ParamField type="string" placeholder="DEU">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `DEU`
</ParamField>

<ParamField type="string" placeholder="deu_credit_bureau">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `deu_credit_bureau`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=DEU" \
    -F "services=deu_credit_bureau" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}'
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "DEU",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "deu_credit_bureau",
        "service_name": "Germany Credit Bureau",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "postal_code": "10001",
          "street": "sample_value",
          "verifications": {
            "address": true,
            "date_of_birth": true,
            "full_name": true
          }
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "DEU",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "deu_credit_bureau",
        "service_name": "Germany Credit Bureau",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "postal_code": "10001",
          "street": "sample_value",
          "verifications": {
            "address": true,
            "date_of_birth": true,
            "full_name": false
          }
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "DEU",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "deu_credit_bureau",
        "service_name": "Germany Credit Bureau",
        "source_data": {
          "address": "NO_MATCH",
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `deu_credit_bureau` currently documents this normalized shape:

* `address`
* `address_match_score`
* `city`
* `date_of_birth`
* `first_name`
* `full_name`
* `last_name`
* `name_match_score`
* `postal_code`
* `street`

## Pricing & SLAs

Germany Credit Bureau queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.84 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Germany Database Validation overview](/api-reference/database-validation/germany)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Germany Phone 2
Source: https://docs.didit.me/api-reference/database-validation/germany/phone-2

POST /v3/database-validation/
Verifies input data to mobile network operators phone data. Authoritative real-time identity lookup for Germany. Real-time lookup, pay-per-call.

<div />

Verifies input data to mobile network operators phone data. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** > 75%
* **Country:** Germany
* **Service ID:** `deu_phone_2`
* **Data domain:** Telecom
* **Category:** Telecom

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `phone`               |      Yes | `+15550101000`      |
| `date_of_birth`       |       No | `1990-01-01`        |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `address.street_1`, `address.postal_code`, `phone`
* **Optional inputs:** `date_of_birth`, `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** > 75%
* **Price:** \$0.59 per successful query

## Body parameters

<ParamField type="string" placeholder="DEU">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `DEU`
</ParamField>

<ParamField type="string" placeholder="deu_phone_2">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `deu_phone_2`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  Phone number in international format.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=DEU" \
    -F "services=deu_phone_2" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}' \
    -F "phone=+15550101000"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "DEU",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "deu_phone_2",
        "service_name": "Germany Phone 2",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "DEU",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "deu_phone_2",
        "service_name": "Germany Phone 2",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "DEU",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "deu_phone_2",
        "service_name": "Germany Phone 2",
        "source_data": {
          "address": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `deu_phone_2` currently documents this normalized shape:

* `address`
* `date_of_birth`
* `first_name`
* `last_name`

## Pricing & SLAs

Germany Phone 2 queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.59 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Germany Database Validation overview](/api-reference/database-validation/germany)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Global - Identity Enrichment
Source: https://docs.didit.me/api-reference/database-validation/global/identity-enrichment

POST /v3/database-validation/
Resolves persons (names, DOB, addresses, phones, emails, national IDs) and a name-match score from an email and/or phone number via a global risk-insights network. Charged per request. Third-party identity-network lookup for Global. Real-time lookup, pay-per-call.

<div />

Resolves persons (names, DOB, addresses, phones, emails, national IDs) and a name-match score from an email and/or phone number via a global risk-insights network. Charged per request. Didit exposes this service through `POST /v3/database-validation/` so you can screen the submitted data against the connected identity network and receive normalized match results. This is a third-party enrichment network, not an authoritative government registry — do not present its results as primary-source verification.

## Coverage

* **Coverage:** 50+ markets
* **Country:** Global
* **Service ID:** `glb_identity_enrichment`
* **Data domain:** Identity
* **Category:** IdentityEnrichment

## Inputs

| Field                  | Required | Example                |
| ---------------------- | -------: | ---------------------- |
| `email`                |       No | `john.doe@example.com` |
| `phone`                |       No | `+15550101000`         |
| `first_name`           |       No | `John`                 |
| `last_name`            |       No | `Doe`                  |
| `full_name`            |       No | `John Doe`             |
| `country_of_residence` |       No | `US`                   |
| `vendor_data`          |       No | `user-1234`            |

* **Required inputs:** —
* **Optional inputs:** `email`, `phone`, `first_name`, `last_name`, `full_name`, `country_of_residence`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Standalone API only
* **Coverage:** 50+ markets
* **Price:** \$0.20 per successful query

This service needs an input no workflow step can produce (a biometric capture, a signed artifact, a live one-time code), so it is available only on the standalone API, where you supply the values directly.

## Body parameters

<ParamField type="string" placeholder="GLB">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `GLB`
</ParamField>

<ParamField type="string" placeholder="glb_identity_enrichment">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `glb_identity_enrichment`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="john.doe@example.com">
  Email address.

  Example: `john.doe@example.com`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  Phone number in international format.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="John Doe">
  Full legal name to validate.

  Example: `John Doe`
</ParamField>

<ParamField type="string" placeholder="US">
  Optional ISO 3166-1 alpha-2 country of residence. Only used to focus the identity lookup.

  Example: `US`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Provide at least one of `email` or `phone` - they are the lookup keys. A request with neither cannot perform an enrichment lookup and is rejected before source lookup (not charged).
* Add `full_name` (or `first_name` + `last_name`) whenever you have it - the name is what the returned match score is computed against.
* `country_of_residence` is an ISO 3166-1 alpha-2 code used to focus the lookup.
* Every completed lookup is charged, including one that resolves no person at all (`persons_found: 0`). Only a request rejected before the lookup - neither `email` nor `phone` supplied - is free.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=GLB" \
    -F "services=glb_identity_enrichment" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "email=john.doe@example.com" \
    -F "phone=+15550101000" \
    -F "full_name=John Doe" \
    -F "country_of_residence=US"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "GLB",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "glb_identity_enrichment",
        "service_name": "Global - Identity Enrichment",
        "source_data": {
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "GLB",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "glb_identity_enrichment",
        "service_name": "Global - Identity Enrichment",
        "source_data": {
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "GLB",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "glb_identity_enrichment",
        "service_name": "Global - Identity Enrichment",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```

  **`INCONCLUSIVE`** — The registry could not determine whether the person matches - the result is genuinely uncertain (they may or may not be in the registry). This is NOT a no-match and NOT a technical image problem; no field is asserted, so match\_type is null and the check is sent to review.

  ```json 200 OK — INCONCLUSIVE theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "GLB",
    "match_type": null,
    "validations": [
      {
        "outcome_code": "INCONCLUSIVE",
        "service_id": "glb_identity_enrichment",
        "service_name": "Global - Identity Enrichment",
        "source_data": {},
        "validation": {}
      }
    ]
  }
  ```

  **`DOCUMENT_NOT_FOUND`** — The submitted document number does not correspond to any record in the registry.

  ```json 200 OK — DOCUMENT_NOT_FOUND theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "GLB",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "DOCUMENT_NOT_FOUND",
        "service_id": "glb_identity_enrichment",
        "service_name": "Global - Identity Enrichment",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `glb_identity_enrichment` currently documents this normalized shape:

* `first_name`
* `full_name`
* `last_name`

## Pricing & SLAs

Global - Identity Enrichment queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.20 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Global Database Validation overview](/getting-started/database-validation-pricing)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Global - Core Intelligence Service
Source: https://docs.didit.me/api-reference/database-validation/global/intelligence-service

POST /v3/database-validation/
Performs a series of checks across multiple data partners and returns risks associated with each data point. Authoritative real-time identity lookup for Global. Real-time lookup, pay-per-call.

<div />

Performs a series of checks across multiple data partners and returns risks associated with each data point. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** Global
* **Service ID:** `glb_intelligence_service`
* **Data domain:** Telecom
* **Category:** Telecom

## Inputs

| Field         | Required | Example        |
| ------------- | -------: | -------------- |
| `phone`       |      Yes | `+15550101000` |
| `vendor_data` |       No | `user-1234`    |

* **Required inputs:** `phone`
* **Optional inputs:** `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** —
* **Price:** \$0.41 per successful query

## Body parameters

<ParamField type="string" placeholder="GLB">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `GLB`
</ParamField>

<ParamField type="string" placeholder="glb_intelligence_service">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `glb_intelligence_service`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  Phone number in international format.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=GLB" \
    -F "services=glb_intelligence_service" \
    -F "vendor_data=user-1234" \
    -F "phone=+15550101000"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "GLB",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "glb_intelligence_service",
        "service_name": "Global - Core Intelligence Service",
        "source_data": {},
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "GLB",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "glb_intelligence_service",
        "service_name": "Global - Core Intelligence Service",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `glb_intelligence_service` currently documents this normalized shape:

* Varies by registry response.

## Pricing & SLAs

Global - Core Intelligence Service queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.41 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Global Database Validation overview](/getting-started/database-validation-pricing)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Global - Sim Swap
Source: https://docs.didit.me/api-reference/database-validation/global/swap

POST /v3/database-validation/
Returns data points associated with any Sim Swap activity on the input phone number. Authoritative real-time identity lookup for Global. Real-time lookup, pay-per-call.

<div />

Returns data points associated with any Sim Swap activity on the input phone number. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** Global
* **Service ID:** `glb_swap`
* **Data domain:** Telecom
* **Category:** Telecom

## Inputs

| Field         | Required | Example        |
| ------------- | -------: | -------------- |
| `phone`       |      Yes | `+15550101000` |
| `vendor_data` |       No | `user-1234`    |

* **Required inputs:** `phone`
* **Optional inputs:** `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** —
* **Price:** \$0.18 per successful query

## Body parameters

<ParamField type="string" placeholder="GLB">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `GLB`
</ParamField>

<ParamField type="string" placeholder="glb_swap">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `glb_swap`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  Phone number in international format.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=GLB" \
    -F "services=glb_swap" \
    -F "vendor_data=user-1234" \
    -F "phone=+15550101000"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "GLB",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "glb_swap",
        "service_name": "Global - Sim Swap",
        "source_data": {},
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "GLB",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "glb_swap",
        "service_name": "Global - Sim Swap",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `glb_swap` currently documents this normalized shape:

* Varies by registry response.

## Pricing & SLAs

Global - Sim Swap queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.18 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Global Database Validation overview](/getting-started/database-validation-pricing)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Guatemala - DPI verification
Source: https://docs.didit.me/api-reference/database-validation/guatemala/dpi

POST /v3/database-validation/
Verifies Guatemalan unique identification code data against SAT government records. Authoritative real-time identity lookup for Guatemala. Real-time lookup, pay-per-call.

<div />

Verifies Guatemalan unique identification code data against SAT government records. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 90-95%
* **Country:** Guatemala
* **Service ID:** `gtm_dpi`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field             | Required | Example         |
| ----------------- | -------: | --------------- |
| `document_number` |      Yes | `1111111111111` |
| `date_of_birth`   |      Yes | `1990-01-01`    |
| `first_name`      |       No | `John`          |
| `last_name`       |       No | `Doe`           |
| `vendor_data`     |       No | `user-1234`     |

* **Required inputs:** `document_number`, `date_of_birth`
* **Optional inputs:** `first_name`, `last_name`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** 90-95%
* **Price:** \$0.20 per successful query

## Body parameters

<ParamField type="string" placeholder="GTM">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `GTM`
</ParamField>

<ParamField type="string" placeholder="gtm_dpi">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `gtm_dpi`
</ParamField>

<ParamField type="string" placeholder="1111111111111">
  Document number extracted from or provided by the user.

  Example: `1111111111111`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Guatemalan DPI (exactly 13 digits)
* `document_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `document_number` must be exactly 13 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=GTM" \
    -F "services=gtm_dpi" \
    -F "vendor_data=user-1234" \
    -F "document_number=1111111111111" \
    -F "date_of_birth=1990-01-01"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "GTM",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "gtm_dpi",
        "service_name": "Guatemala - DPI verification",
        "source_data": {
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "GTM",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "gtm_dpi",
        "service_name": "Guatemala - DPI verification",
        "source_data": {
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "GTM",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "gtm_dpi",
        "service_name": "Guatemala - DPI verification",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `gtm_dpi` currently documents this normalized shape:

* `first_name`
* `full_name`
* `identification_number`
* `last_name`

## Pricing & SLAs

Guatemala - DPI verification queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.20 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Guatemala Database Validation overview](/api-reference/database-validation/guatemala)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Honduras - DNI verification
Source: https://docs.didit.me/api-reference/database-validation/honduras/dni

POST /v3/database-validation/
Verifies Honduran DNI data against CNE electoral registry records. Authoritative real-time identity lookup for Honduras. Real-time lookup, pay-per-call.

<div />

Verifies Honduran DNI data against CNE electoral registry records. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 90-95%
* **Country:** Honduras
* **Service ID:** `hnd_dni`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field             | Required | Example         |
| ----------------- | -------: | --------------- |
| `document_number` |      Yes | `1111111111111` |
| `first_name`      |       No | `John`          |
| `last_name`       |       No | `Doe`           |
| `vendor_data`     |       No | `user-1234`     |

* **Required inputs:** `document_number`
* **Optional inputs:** `first_name`, `last_name`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** 90-95%
* **Price:** \$0.20 per successful query

## Body parameters

<ParamField type="string" placeholder="HND">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `HND`
</ParamField>

<ParamField type="string" placeholder="hnd_dni">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `hnd_dni`
</ParamField>

<ParamField type="string" placeholder="1111111111111">
  Document number extracted from or provided by the user.

  Example: `1111111111111`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Honduran DNI (exactly 13 digits)
* `document_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `document_number` must be exactly 13 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=HND" \
    -F "services=hnd_dni" \
    -F "vendor_data=user-1234" \
    -F "document_number=1111111111111"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "HND",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "hnd_dni",
        "service_name": "Honduras - DNI verification",
        "source_data": {
          "document_type": "sample_value",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "HND",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "hnd_dni",
        "service_name": "Honduras - DNI verification",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `hnd_dni` currently documents this normalized shape:

* `document_type`
* `first_name`
* `full_name`
* `identification_number`
* `last_name`

## Pricing & SLAs

Honduras - DNI verification queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.20 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Honduras Database Validation overview](/api-reference/database-validation/honduras)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# India Aadhaar (UIDAI)
Source: https://docs.didit.me/api-reference/database-validation/india/aadhaar

POST /v3/database-validation/
Verifies the input Aadhaar number against UIDAI identity records. Authoritative real-time identity lookup for India. Real-time lookup, pay-per-call.

<div />

Verifies the input Aadhaar number against UIDAI identity records. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 100%
* **Country:** India
* **Service ID:** `ind_aadhaar`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field             | Required | Example        |
| ----------------- | -------: | -------------- |
| `full_name`       |      Yes | `John Doe`     |
| `date_of_birth`   |      Yes | `1990-01-01`   |
| `personal_number` |      Yes | `111111111111` |
| `pan`             |      Yes | `ABCDE1234F`   |
| `vendor_data`     |       No | `user-1234`    |

* **Required inputs:** `full_name`, `date_of_birth`, `personal_number`, `pan`
* **Optional inputs:** `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 100%
* **Price:** \$0.25 per successful query

Not every document this service accepts carries the identifier it queries by. When the identifier is not extracted from the document the check is recorded as **not applicable** - no database is queried and you are not charged - which for some countries is a large share of real users. To cover them, also collect the identifier from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step.

## Body parameters

<ParamField type="string" placeholder="IND">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `IND`
</ParamField>

<ParamField type="string" placeholder="ind_aadhaar">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `ind_aadhaar`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John Doe">
  Full legal name to validate.

  Example: `John Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="111111111111">
  Country-specific personal identity number.

  Example: `111111111111`
</ParamField>

<ParamField type="string" placeholder="ABCDE1234F">
  Permanent Account Number.

  Example: `ABCDE1234F`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* `pan` must use uppercase letters.
* `pan` must match `[A-Z]{5}\d{4}[A-Z]`.
* `personal_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `personal_number` must be exactly 12 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=IND" \
    -F "services=ind_aadhaar" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "full_name=John Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "personal_number=111111111111" \
    -F "pan=ABCDE1234F"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "IND",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "ind_aadhaar",
        "service_name": "India Aadhaar (UIDAI)",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "IND",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "ind_aadhaar",
        "service_name": "India Aadhaar (UIDAI)",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "IND",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "ind_aadhaar",
        "service_name": "India Aadhaar (UIDAI)",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `ind_aadhaar` currently documents this normalized shape:

* `date_of_birth`
* `full_name`
* `identification_number`

## Pricing & SLAs

India Aadhaar (UIDAI) queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.25 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [India Database Validation overview](/api-reference/database-validation/india)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# India Drivers Licence (RTO)
Source: https://docs.didit.me/api-reference/database-validation/india/drivers-licence

POST /v3/database-validation/
Verifies input data against the databases of the Road Transport Offices of the States of India. Authoritative real-time identity lookup for India. Real-time lookup, pay-per-call.

<div />

Verifies input data against the databases of the Road Transport Offices of the States of India. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** > 75%
* **Country:** India
* **Service ID:** `ind_drivers_licence`
* **Data domain:** Document
* **Category:** DriverLicence

## Inputs

| Field                   | Required | Example             |
| ----------------------- | -------: | ------------------- |
| `full_name`             |      Yes | `John Doe`          |
| `date_of_birth`         |      Yes | `1990-01-01`        |
| `driver_license_number` |      Yes | `SAMPLE-DL-12345`   |
| `address.street_1`      |       No | `123 Sample Street` |
| `address.street_2`      |       No | `Unit 4`            |
| `address.city`          |       No | `Sample City`       |
| `address.region`        |       No | `Sample State`      |
| `address.postal_code`   |       No | `10001`             |
| `vendor_data`           |       No | `user-1234`         |

* **Required inputs:** `full_name`, `date_of_birth`, `driver_license_number`
* **Optional inputs:** `address.street_1`, `address.street_2`, `address.city`, `address.region`, `address.postal_code`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** > 75%
* **Price:** \$0.15 per successful query

## Body parameters

<ParamField type="string" placeholder="IND">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `IND`
</ParamField>

<ParamField type="string" placeholder="ind_drivers_licence">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `ind_drivers_licence`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John Doe">
  Full legal name to validate.

  Example: `John Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-DL-12345">
  Driver licence number.

  Example: `SAMPLE-DL-12345`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* `address` is optional for this service. You can send one complete `address` string and Didit will split it into structured address elements when possible, or you can send the structured fields explicitly.
* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=IND" \
    -F "services=ind_drivers_licence" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "full_name=John Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "driver_license_number=SAMPLE-DL-12345"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "IND",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "ind_drivers_licence",
        "service_name": "India Drivers Licence (RTO)",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "date_of_birth": "1990-01-01",
          "identification_number": "SAMPLE-ID-12345",
          "verifications": {
            "date_of_birth": true,
            "full_name": true,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "IND",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "ind_drivers_licence",
        "service_name": "India Drivers Licence (RTO)",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "date_of_birth": "1990-01-01",
          "identification_number": "SAMPLE-ID-12345",
          "verifications": {
            "date_of_birth": true,
            "full_name": false,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "IND",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "ind_drivers_licence",
        "service_name": "India Drivers Licence (RTO)",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `ind_drivers_licence` currently documents this normalized shape:

* `address`
* `address_match_score`
* `date_of_birth`
* `identification_number`

## Pricing & SLAs

India Drivers Licence (RTO) queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.15 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [India Database Validation overview](/api-reference/database-validation/india)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# India EPIC (Voter's Registration) (ECI)
Source: https://docs.didit.me/api-reference/database-validation/india/epic-voter-s-registration

POST /v3/database-validation/
Verifies input data against the Election Commission of India database. Authoritative real-time identity lookup for India. Real-time lookup, pay-per-call.

<div />

Verifies input data against the Election Commission of India database. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** > 75%
* **Country:** India
* **Service ID:** `ind_epic_voter_s_registration`
* **Data domain:** Government
* **Category:** ElectoralRoll

## Inputs

| Field           | Required | Example      |
| --------------- | -------: | ------------ |
| `full_name`     |      Yes | `John Doe`   |
| `date_of_birth` |      Yes | `1990-01-01` |
| `epic_card`     |      Yes | `ABC1234567` |
| `vendor_data`   |       No | `user-1234`  |

* **Required inputs:** `full_name`, `date_of_birth`, `epic_card`
* **Optional inputs:** `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow with field mapping
* **Coverage:** > 75%
* **Price:** \$0.15 per successful query

In a workflow, `epic_card` is not printed on an identity document, so no step produces it on its own. Collect it from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step. Until it is mapped the workflow editor shows this service disabled and names the missing input; at run time a missing input means the check is skipped before any query, so you are never billed for a database that could not be asked.

Not every document this service accepts carries the identifier it queries by. When the identifier is not extracted from the document the check is recorded as **not applicable** - no database is queried and you are not charged - which for some countries is a large share of real users. To cover them, also collect the identifier from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step.

## Body parameters

<ParamField type="string" placeholder="IND">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `IND`
</ParamField>

<ParamField type="string" placeholder="ind_epic_voter_s_registration">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `ind_epic_voter_s_registration`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John Doe">
  Full legal name to validate.

  Example: `John Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="ABC1234567">
  EPIC voter card number.

  Example: `ABC1234567`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* `epic_card` must match `[A-Za-z]{3}\d{7,14}`.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=IND" \
    -F "services=ind_epic_voter_s_registration" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "full_name=John Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "epic_card=ABC1234567"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "IND",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "ind_epic_voter_s_registration",
        "service_name": "India EPIC (Voter's Registration) (ECI)",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "IND",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "ind_epic_voter_s_registration",
        "service_name": "India EPIC (Voter's Registration) (ECI)",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "IND",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "ind_epic_voter_s_registration",
        "service_name": "India EPIC (Voter's Registration) (ECI)",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `ind_epic_voter_s_registration` currently documents this normalized shape:

* `date_of_birth`
* `full_name`
* `identification_number`

## Pricing & SLAs

India EPIC (Voter's Registration) (ECI) queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.15 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [India Database Validation overview](/api-reference/database-validation/india)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# India PAN (Permanent Account Number) (ITD)
Source: https://docs.didit.me/api-reference/database-validation/india/pan-permanent-account-number

POST /v3/database-validation/
Verifies input data against the database of the Income Tax Department of India. Authoritative real-time identity lookup for India. Real-time lookup, pay-per-call.

<div />

Verifies input data against the database of the Income Tax Department of India. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 100%
* **Country:** India
* **Service ID:** `ind_pan_permanent_account_number`
* **Data domain:** Financial
* **Category:** TaxRegistry

## Inputs

| Field           | Required | Example      |
| --------------- | -------: | ------------ |
| `full_name`     |      Yes | `John Doe`   |
| `date_of_birth` |      Yes | `1990-01-01` |
| `pan`           |      Yes | `ABCDE1234F` |
| `vendor_data`   |       No | `user-1234`  |

* **Required inputs:** `full_name`, `date_of_birth`, `pan`
* **Optional inputs:** `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 100%
* **Price:** \$0.25 per successful query

Not every document this service accepts carries the identifier it queries by. When the identifier is not extracted from the document the check is recorded as **not applicable** - no database is queried and you are not charged - which for some countries is a large share of real users. To cover them, also collect the identifier from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step.

## Body parameters

<ParamField type="string" placeholder="IND">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `IND`
</ParamField>

<ParamField type="string" placeholder="ind_pan_permanent_account_number">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `ind_pan_permanent_account_number`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John Doe">
  Full legal name to validate.

  Example: `John Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="ABCDE1234F">
  Permanent Account Number.

  Example: `ABCDE1234F`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* `pan` must use uppercase letters.
* `pan` must match `[A-Z]{5}\d{4}[A-Z]`.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=IND" \
    -F "services=ind_pan_permanent_account_number" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "full_name=John Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "pan=ABCDE1234F"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "IND",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "ind_pan_permanent_account_number",
        "service_name": "India PAN (Permanent Account Number) (ITD)",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "identification_number": "SAMPLE-ID-12345",
          "verifications": {
            "date_of_birth": true,
            "full_name": true,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "IND",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "ind_pan_permanent_account_number",
        "service_name": "India PAN (Permanent Account Number) (ITD)",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "identification_number": "SAMPLE-ID-12345",
          "verifications": {
            "date_of_birth": true,
            "full_name": false,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "IND",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "ind_pan_permanent_account_number",
        "service_name": "India PAN (Permanent Account Number) (ITD)",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `ind_pan_permanent_account_number` currently documents this normalized shape:

* `date_of_birth`
* `identification_number`

## Pricing & SLAs

India PAN (Permanent Account Number) (ITD) queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.25 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [India Database Validation overview](/api-reference/database-validation/india)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Indonesia Residential Identity Card
Source: https://docs.didit.me/api-reference/database-validation/indonesia/residential-identity-card

POST /v3/database-validation/
Verifies input data against a Government agency. Authoritative real-time identity lookup for Indonesia. Real-time lookup, pay-per-call.

<div />

Verifies input data against a Government agency. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 90%
* **Country:** Indonesia
* **Service ID:** `idn_residential_identity_card`
* **Data domain:** Address
* **Category:** Residential

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `full_name`           |      Yes | `John Doe`          |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `national_id`         |      Yes | `1111111111111111`  |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `gender`              |       No | `M`                 |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `full_name`, `date_of_birth`, `national_id`, `address.street_1`, `address.postal_code`
* **Optional inputs:** `address.street_2`, `address.city`, `address.region`, `gender`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 90%
* **Price:** \$0.35 per successful query

Not every document this service accepts carries the identifier it queries by. When the identifier is not extracted from the document the check is recorded as **not applicable** - no database is queried and you are not charged - which for some countries is a large share of real users. To cover them, also collect the identifier from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step.

## Body parameters

<ParamField type="string" placeholder="IDN">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `IDN`
</ParamField>

<ParamField type="string" placeholder="idn_residential_identity_card">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `idn_residential_identity_card`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John Doe">
  Full legal name to validate.

  Example: `John Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="1111111111111111">
  National identity number for this service.

  Example: `1111111111111111`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="M">
  Gender value, when required by the database.

  Allowed values: `M` (male), `F` (female), `X` (other or unknown).

  Example: `M`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* `national_id` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `national_id` must be exactly 16 characters long.
* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=IDN" \
    -F "services=idn_residential_identity_card" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "full_name=John Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "national_id=1111111111111111" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}'
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "IDN",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "idn_residential_identity_card",
        "service_name": "Indonesia Residential Identity Card",
        "source_data": {
          "address_match_score": "1.000",
          "date_of_birth": "1990-01-01",
          "identification_number": "SAMPLE-ID-12345",
          "verifications": {
            "address": true,
            "date_of_birth": true,
            "full_name": true,
            "identification_number": true
          }
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "IDN",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "idn_residential_identity_card",
        "service_name": "Indonesia Residential Identity Card",
        "source_data": {
          "address_match_score": "1.000",
          "date_of_birth": "1990-01-01",
          "identification_number": "SAMPLE-ID-12345",
          "verifications": {
            "address": true,
            "date_of_birth": true,
            "full_name": false,
            "identification_number": true
          }
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "IDN",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "idn_residential_identity_card",
        "service_name": "Indonesia Residential Identity Card",
        "source_data": {
          "address": "NO_MATCH",
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `idn_residential_identity_card` currently documents this normalized shape:

* `address_match_score`
* `date_of_birth`
* `identification_number`

## Pricing & SLAs

Indonesia Residential Identity Card queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.35 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Indonesia Database Validation overview](/api-reference/database-validation/indonesia)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Italy Credit Bureau
Source: https://docs.didit.me/api-reference/database-validation/italy/credit-bureau

POST /v3/database-validation/
Verifies input data against Credit Header data obtained from a Credit Bureau in Italy. Authoritative real-time identity lookup for Italy. Real-time lookup, pay-per-call.

<div />

Verifies input data against Credit Header data obtained from a Credit Bureau in Italy. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 80%
* **Country:** Italy
* **Service ID:** `ita_credit_bureau`
* **Data domain:** Financial
* **Category:** CreditBureau

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `tax_number`          |      Yes | `SAMPLE-TAX-12345`  |
| `date_of_birth`       |       No | `1990-01-01`        |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `address.street_1`, `address.postal_code`, `tax_number`
* **Optional inputs:** `date_of_birth`, `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 80%
* **Price:** \$1.95 per successful query

Not every document this service accepts carries the identifier it queries by. When the identifier is not extracted from the document the check is recorded as **not applicable** - no database is queried and you are not charged - which for some countries is a large share of real users. To cover them, also collect the identifier from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step.

## Body parameters

<ParamField type="string" placeholder="ITA">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `ITA`
</ParamField>

<ParamField type="string" placeholder="ita_credit_bureau">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `ita_credit_bureau`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-TAX-12345">
  Tax or fiscal identification number.

  Example: `SAMPLE-TAX-12345`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* `tax_number` must be exactly 16 characters long.
* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=ITA" \
    -F "services=ita_credit_bureau" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}' \
    -F "tax_number=SAMPLE-TAX-12345"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "ITA",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "ita_credit_bureau",
        "service_name": "Italy Credit Bureau",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "ITA",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "ita_credit_bureau",
        "service_name": "Italy Credit Bureau",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ITA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "ita_credit_bureau",
        "service_name": "Italy Credit Bureau",
        "source_data": {
          "address": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `ita_credit_bureau` currently documents this normalized shape:

* `address`
* `date_of_birth`
* `first_name`
* `identification_number`
* `last_name`

## Pricing & SLAs

Italy Credit Bureau queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$1.95 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Italy Database Validation overview](/api-reference/database-validation/italy)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Italy Residential
Source: https://docs.didit.me/api-reference/database-validation/italy/residential

POST /v3/database-validation/
Input is verified against a source comprising multiple datasets from consumer, telephone and postal records. Authoritative real-time identity lookup for Italy. Real-time lookup, pay-per-call.

<div />

Input is verified against a source comprising multiple datasets from consumer, telephone and postal records. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** > 75%
* **Country:** Italy
* **Service ID:** `ita_residential`
* **Data domain:** Address
* **Category:** Residential

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `address.street_1`, `address.postal_code`
* **Optional inputs:** `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** > 75%
* **Price:** \$0.45 per successful query

## Body parameters

<ParamField type="string" placeholder="ITA">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `ITA`
</ParamField>

<ParamField type="string" placeholder="ita_residential">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `ita_residential`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=ITA" \
    -F "services=ita_residential" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}'
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "ITA",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "ita_residential",
        "service_name": "Italy Residential",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "postal_code": "10001",
          "street": "sample_value",
          "verifications": {
            "address": true,
            "date_of_birth": true,
            "full_name": true
          }
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "ITA",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "ita_residential",
        "service_name": "Italy Residential",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "postal_code": "10001",
          "street": "sample_value",
          "verifications": {
            "address": true,
            "date_of_birth": true,
            "full_name": false
          }
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ITA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "ita_residential",
        "service_name": "Italy Residential",
        "source_data": {
          "address": "NO_MATCH",
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `ita_residential` currently documents this normalized shape:

* `address`
* `address_match_score`
* `city`
* `date_of_birth`
* `first_name`
* `full_name`
* `last_name`
* `name_match_score`
* `postal_code`
* `street`

## Pricing & SLAs

Italy Residential queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.45 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Italy Database Validation overview](/api-reference/database-validation/italy)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Kenya National ID
Source: https://docs.didit.me/api-reference/database-validation/kenya/national-id

POST /v3/database-validation/
Verifies data against the National Registration Bureau. Authoritative real-time identity lookup for Kenya. Real-time lookup, pay-per-call.

<div />

Verifies data against the National Registration Bureau. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 90%
* **Country:** Kenya
* **Service ID:** `ken_national_id`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field           | Required | Example            |
| --------------- | -------: | ------------------ |
| `first_name`    |      Yes | `John`             |
| `last_name`     |      Yes | `Doe`              |
| `date_of_birth` |      Yes | `1990-01-01`       |
| `national_id`   |      Yes | `SAMPLE-NID-12345` |
| `vendor_data`   |       No | `user-1234`        |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `national_id`
* **Optional inputs:** `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 90%
* **Price:** \$3.15 per successful query

Not every document this service accepts carries the identifier it queries by. When the identifier is not extracted from the document the check is recorded as **not applicable** - no database is queried and you are not charged - which for some countries is a large share of real users. To cover them, also collect the identifier from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step.

## Body parameters

<ParamField type="string" placeholder="KEN">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `KEN`
</ParamField>

<ParamField type="string" placeholder="ken_national_id">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `ken_national_id`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-NID-12345">
  National identity number for this service.

  Example: `SAMPLE-NID-12345`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* `national_id` must match `\d{8,9}`.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=KEN" \
    -F "services=ken_national_id" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "national_id=SAMPLE-NID-12345"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "KEN",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "ken_national_id",
        "service_name": "Kenya National ID",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": true,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "KEN",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "ken_national_id",
        "service_name": "Kenya National ID",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": false,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "KEN",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "ken_national_id",
        "service_name": "Kenya National ID",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `ken_national_id` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `full_name`
* `identification_number`
* `last_name`
* `name_match_score`

## Pricing & SLAs

Kenya National ID queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$3.15 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Kenya Database Validation overview](/api-reference/database-validation/kenya)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Malaysia National ID
Source: https://docs.didit.me/api-reference/database-validation/malaysia/national-id

POST /v3/database-validation/
Verifies input data against a Government agency database consisting of Malaysian citizens data. Authoritative real-time identity lookup for Malaysia. Real-time lookup, pay-per-call.

<div />

Verifies input data against a Government agency database consisting of Malaysian citizens data. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** > 75%
* **Country:** Malaysia
* **Service ID:** `mys_national_id`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `full_name`           |      Yes | `John Doe`          |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `national_id`         |      Yes | `111111111111`      |
| `address.street_1`    |       No | `123 Sample Street` |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `address.postal_code` |       No | `10001`             |
| `phone`               |       No | `+15550101000`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `full_name`, `date_of_birth`, `national_id`
* **Optional inputs:** `address.street_1`, `address.street_2`, `address.city`, `address.region`, `address.postal_code`, `phone`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** > 75%
* **Price:** \$0.35 per successful query

Not every document this service accepts carries the identifier it queries by. When the identifier is not extracted from the document the check is recorded as **not applicable** - no database is queried and you are not charged - which for some countries is a large share of real users. To cover them, also collect the identifier from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step.

## Body parameters

<ParamField type="string" placeholder="MYS">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `MYS`
</ParamField>

<ParamField type="string" placeholder="mys_national_id">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `mys_national_id`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John Doe">
  Full legal name to validate.

  Example: `John Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="111111111111">
  National identity number for this service.

  Example: `111111111111`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  Phone number in international format.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* `address` is optional for this service. You can send one complete `address` string and Didit will split it into structured address elements when possible, or you can send the structured fields explicitly.
* `national_id` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `national_id` must be exactly 12 characters long.
* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=MYS" \
    -F "services=mys_national_id" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "full_name=John Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "national_id=111111111111"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "MYS",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "mys_national_id",
        "service_name": "Malaysia National ID",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "identification_number": "SAMPLE-ID-12345",
          "postal_code": "10001",
          "state": "Sample State",
          "street": "sample_value"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "MYS",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "mys_national_id",
        "service_name": "Malaysia National ID",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "identification_number": "SAMPLE-ID-12345",
          "postal_code": "10001",
          "state": "Sample State",
          "street": "sample_value"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "MYS",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "mys_national_id",
        "service_name": "Malaysia National ID",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `mys_national_id` currently documents this normalized shape:

* `address`
* `address_match_score`
* `city`
* `date_of_birth`
* `identification_number`
* `postal_code`
* `state`
* `street`

## Pricing & SLAs

Malaysia National ID queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.35 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Malaysia Database Validation overview](/api-reference/database-validation/malaysia)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Mexico - CURP verification
Source: https://docs.didit.me/api-reference/database-validation/mexico/curp

POST /v3/database-validation/
Verifies Mexican CURP against the RENAPO national identifier registry. Authoritative real-time identity lookup for Mexico. Real-time lookup, pay-per-call.

<div />

Verifies Mexican CURP against the RENAPO national identifier registry. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 100%
* **Country:** Mexico
* **Service ID:** `mex_curp`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field             | Required | Example              |
| ----------------- | -------: | -------------------- |
| `personal_number` |      Yes | `ABCD900101HDFABC09` |
| `first_name`      |       No | `John`               |
| `last_name`       |       No | `Doe`                |
| `vendor_data`     |       No | `user-1234`          |

* **Required inputs:** `personal_number`
* **Optional inputs:** `first_name`, `last_name`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 100%
* **Price:** \$0.20 per successful query

## Body parameters

<ParamField type="string" placeholder="MEX">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `MEX`
</ParamField>

<ParamField type="string" placeholder="mex_curp">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `mex_curp`
</ParamField>

<ParamField type="string" placeholder="ABCD900101HDFABC09">
  Country-specific personal identity number.

  Example: `ABCD900101HDFABC09`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Mexican CURP (exactly 18 alphanumeric characters)
* `personal_number` must be exactly 18 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=MEX" \
    -F "services=mex_curp" \
    -F "vendor_data=user-1234" \
    -F "personal_number=ABCD900101HDFABC09"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "MEX",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "mex_curp",
        "service_name": "Mexico - CURP verification",
        "source_data": {
          "curp_status": "sample_value",
          "date_of_birth": "1990-01-01",
          "doc_probatorio": "sample_value",
          "first_name": "John",
          "full_name": "John Doe",
          "gender": "M",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "nationality": "USA",
          "num_acta": "sample_value",
          "registration_municipality": "sample_value",
          "registration_state": "sample_value",
          "registration_year": "sample_value",
          "state_of_birth": "sample_value"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "MEX",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "mex_curp",
        "service_name": "Mexico - CURP verification",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `mex_curp` currently documents this normalized shape:

* `curp_status`
* `date_of_birth`
* `doc_probatorio`
* `first_name`
* `full_name`
* `gender`
* `identification_number`
* `last_name`
* `nationality`
* `num_acta`
* `registration_municipality`
* `registration_state`
* `registration_year`
* `state_of_birth`

## Pricing & SLAs

Mexico - CURP verification queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.20 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Mexico Database Validation overview](/api-reference/database-validation/mexico)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Mexico - INE credential validity verification
Source: https://docs.didit.me/api-reference/database-validation/mexico/ine-vigencia

POST /v3/database-validation/
Verifies a Mexican INE / IFE voter ID credential against the INE registry (modelo, vigencia, válida-como-identificación, derecho-a-votar). Authoritative real-time identity lookup for Mexico. Real-time lookup, pay-per-call.

<div />

Verifies a Mexican INE / IFE voter ID credential against the INE registry (modelo, vigencia, válida-como-identificación, derecho-a-votar). Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** Mexico
* **Service ID:** `mex_ine_vigencia`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field                     | Required | Example         |
| ------------------------- | -------: | --------------- |
| `cic`                     |       No | `123456789`     |
| `identificador_ciudadano` |       No | `123456789`     |
| `ocr`                     |       No | `1234567890123` |
| `voter_number`            |       No | `ABCDEF123456`  |
| `emission_number`         |       No | `01`            |
| `first_name`              |       No | `John`          |
| `last_name`               |       No | `Doe`           |
| `date_of_birth`           |       No | `1990-01-01`    |
| `vendor_data`             |       No | `user-1234`     |

* **Required inputs:** —
* **Optional inputs:** `cic`, `identificador_ciudadano`, `ocr`, `voter_number`, `emission_number`, `first_name`, `last_name`, `date_of_birth`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** —
* **Price:** \$0.20 per successful query

## Body parameters

<ParamField type="string" placeholder="MEX">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `MEX`
</ParamField>

<ParamField type="string" placeholder="mex_ine_vigencia">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `mex_ine_vigencia`
</ParamField>

<ParamField type="string" placeholder="123456789">
  `cic` value required by this database service.

  Example: `123456789`
</ParamField>

<ParamField type="string" placeholder="123456789">
  `identificador_ciudadano` value required by this database service.

  Example: `123456789`
</ParamField>

<ParamField type="string" placeholder="1234567890123">
  `ocr` value required by this database service.

  Example: `1234567890123`
</ParamField>

<ParamField type="string" placeholder="ABCDEF123456">
  `voter_number` value required by this database service.

  Example: `ABCDEF123456`
</ParamField>

<ParamField type="string" placeholder="01">
  `emission_number` value required by this database service.

  Example: `01`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Provide at least one credential identifier: `cic`, `identificador_ciudadano`, `ocr`, or `voter_number`. If all are absent, Didit returns HTTP `400` with the accepted fields instead of calling the provider. Requests rejected before source lookup are not charged.
* For a legacy credential identified by `voter_number`, include `emission_number`.
* A provider rejection remains a completed HTTP `200` validation and carries the real normalized result. For example, provider code `4` is returned as `outcome_code: "INVALID_DOCUMENT_FORMAT"`, `outcome_detail: "4"`, and `source_data.message: "Error de datos"`. Use these fields rather than treating every rejection as a generic availability error.
* Provider code `0` means the submitted credential was not found. It is returned as `outcome_code: "DOCUMENT_NOT_FOUND"`, with `outcome_detail: "0"` and the original explanation in `source_data.message`.
* Provider codes `1` and `10` mean the submitted credential data did not match the INE record. They are returned as `outcome_code: "NO_MATCH"`, with the provider code in `outcome_detail` and the original explanation in `source_data.message`.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=MEX" \
    -F "services=mex_ine_vigencia" \
    -F "vendor_data=user-1234"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "MEX",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "mex_ine_vigencia",
        "service_name": "Mexico - INE credential validity verification",
        "source_data": {
          "emission_number": "SAMPLE-12345",
          "emission_year": "sample_value",
          "expiration_date": "1990-01-01",
          "federal_district": "sample_value",
          "identification_number": "SAMPLE-ID-12345",
          "message": "sample_value",
          "message_code": "sample_value",
          "ocr": "sample_value",
          "registration_year": "sample_value",
          "validation_code": "SAMPLE-12345",
          "voter_number": "SAMPLE-12345"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "MEX",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "mex_ine_vigencia",
        "service_name": "Mexico - INE credential validity verification",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `mex_ine_vigencia` currently documents this normalized shape:

* `emission_number`
* `emission_year`
* `expiration_date`
* `federal_district`
* `identification_number`
* `message`
* `message_code`
* `ocr`
* `registration_year`
* `validation_code`
* `voter_number`

## Pricing & SLAs

Mexico - INE credential validity verification queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.20 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Mexico Database Validation overview](/api-reference/database-validation/mexico)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Netherlands Residential
Source: https://docs.didit.me/api-reference/database-validation/netherlands/residential

POST /v3/database-validation/
Verifies input data to a data source containing Government records, postal, and public records. Authoritative real-time identity lookup for Netherlands. Real-time lookup, pay-per-call.

<div />

Verifies input data to a data source containing Government records, postal, and public records. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** > 80%
* **Country:** Netherlands
* **Service ID:** `nld_residential`
* **Data domain:** Address
* **Category:** Residential

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `national_id`         |       No | `SAMPLE-NID-12345`  |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `address.street_1`, `address.postal_code`
* **Optional inputs:** `national_id`, `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** > 80%
* **Price:** \$0.90 per successful query

## Body parameters

<ParamField type="string" placeholder="NLD">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `NLD`
</ParamField>

<ParamField type="string" placeholder="nld_residential">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `nld_residential`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-NID-12345">
  National identity number for this service.

  Example: `SAMPLE-NID-12345`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=NLD" \
    -F "services=nld_residential" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}'
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "NLD",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "nld_residential",
        "service_name": "Netherlands Residential",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "NLD",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "nld_residential",
        "service_name": "Netherlands Residential",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "NLD",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "nld_residential",
        "service_name": "Netherlands Residential",
        "source_data": {
          "address": "NO_MATCH",
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `nld_residential` currently documents this normalized shape:

* `address`
* `date_of_birth`
* `first_name`
* `identification_number`
* `last_name`

## Pricing & SLAs

Netherlands Residential queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.90 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Netherlands Database Validation overview](/api-reference/database-validation/netherlands)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# DIA - New Zealand Births
Source: https://docs.didit.me/api-reference/database-validation/new-zealand/births

POST /v3/database-validation/
DIA Birth Certificate verification service. Authoritative real-time identity lookup for New Zealand. Real-time lookup, pay-per-call.

<div />

DIA Birth Certificate verification service. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 85%
* **Country:** New Zealand
* **Service ID:** `nzl_new_zealand_births`
* **Data domain:** Identity
* **Category:** BirthRecord

## Inputs

| Field           | Required | Example      |
| --------------- | -------: | ------------ |
| `first_name`    |      Yes | `John`       |
| `last_name`     |      Yes | `Doe`        |
| `date_of_birth` |      Yes | `1990-01-01` |
| `vendor_data`   |       No | `user-1234`  |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`
* **Optional inputs:** `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 85%
* **Price:** \$1.00 per successful query

## Body parameters

<ParamField type="string" placeholder="NZL">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `NZL`
</ParamField>

<ParamField type="string" placeholder="nzl_new_zealand_births">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `nzl_new_zealand_births`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=NZL" \
    -F "services=nzl_new_zealand_births" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "NZL",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "nzl_new_zealand_births",
        "service_name": "DIA - New Zealand Births",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "NZL",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "nzl_new_zealand_births",
        "service_name": "DIA - New Zealand Births",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "NZL",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "nzl_new_zealand_births",
        "service_name": "DIA - New Zealand Births",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `nzl_new_zealand_births` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `last_name`

## Pricing & SLAs

DIA - New Zealand Births queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$1.00 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [New Zealand Database Validation overview](/api-reference/database-validation/new-zealand)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# DIA - New Zealand Citizenship
Source: https://docs.didit.me/api-reference/database-validation/new-zealand/citizenship

POST /v3/database-validation/
DIA Citizenship verification service. Authoritative real-time identity lookup for New Zealand. Real-time lookup, pay-per-call.

<div />

DIA Citizenship verification service. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** > 10%
* **Country:** New Zealand
* **Service ID:** `nzl_new_zealand_citizenship`
* **Data domain:** Identity
* **Category:** Citizenship

## Inputs

| Field           | Required | Example      |
| --------------- | -------: | ------------ |
| `first_name`    |      Yes | `John`       |
| `last_name`     |      Yes | `Doe`        |
| `date_of_birth` |      Yes | `1990-01-01` |
| `vendor_data`   |       No | `user-1234`  |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`
* **Optional inputs:** `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** > 10%
* **Price:** \$1.00 per successful query

## Body parameters

<ParamField type="string" placeholder="NZL">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `NZL`
</ParamField>

<ParamField type="string" placeholder="nzl_new_zealand_citizenship">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `nzl_new_zealand_citizenship`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=NZL" \
    -F "services=nzl_new_zealand_citizenship" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "NZL",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "nzl_new_zealand_citizenship",
        "service_name": "DIA - New Zealand Citizenship",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "NZL",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "nzl_new_zealand_citizenship",
        "service_name": "DIA - New Zealand Citizenship",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "NZL",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "nzl_new_zealand_citizenship",
        "service_name": "DIA - New Zealand Citizenship",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `nzl_new_zealand_citizenship` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `last_name`

## Pricing & SLAs

DIA - New Zealand Citizenship queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$1.00 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [New Zealand Database Validation overview](/api-reference/database-validation/new-zealand)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# New Zealand Death Check (BDM)
Source: https://docs.didit.me/api-reference/database-validation/new-zealand/death-check

POST /v3/database-validation/
The official New Zealand Birth, Deaths, Marriages Register. Authoritative real-time identity lookup for New Zealand. Real-time lookup, pay-per-call.

<div />

The official New Zealand Birth, Deaths, Marriages Register. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 100%\*
* **Country:** New Zealand
* **Service ID:** `nzl_zealand_death_check`
* **Data domain:** Other
* **Category:** DeathRecord

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `address.street_1`, `address.postal_code`
* **Optional inputs:** `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** 100%\*
* **Price:** \$0.16 per successful query

## Body parameters

<ParamField type="string" placeholder="NZL">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `NZL`
</ParamField>

<ParamField type="string" placeholder="nzl_zealand_death_check">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `nzl_zealand_death_check`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=NZL" \
    -F "services=nzl_zealand_death_check" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}'
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "NZL",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "nzl_zealand_death_check",
        "service_name": "New Zealand Death Check (BDM)",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "postal_code": "10001",
          "state": "Sample State",
          "street": "sample_value"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "NZL",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "nzl_zealand_death_check",
        "service_name": "New Zealand Death Check (BDM)",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "postal_code": "10001",
          "state": "Sample State",
          "street": "sample_value"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "NZL",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "nzl_zealand_death_check",
        "service_name": "New Zealand Death Check (BDM)",
        "source_data": {
          "address": "NO_MATCH",
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `nzl_zealand_death_check` currently documents this normalized shape:

* `address`
* `address_match_score`
* `city`
* `date_of_birth`
* `first_name`
* `full_name`
* `last_name`
* `name_match_score`
* `postal_code`
* `state`
* `street`

## Pricing & SLAs

New Zealand Death Check (BDM) queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.16 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [New Zealand Database Validation overview](/api-reference/database-validation/new-zealand)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# New Zealand Drivers Licence (NZTA)
Source: https://docs.didit.me/api-reference/database-validation/new-zealand/drivers-licence

POST /v3/database-validation/
Verifies input data to the NZTA verification service. Authoritative real-time identity lookup for New Zealand. Real-time lookup, pay-per-call.

<div />

Verifies input data to the NZTA verification service. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 100%\*
* **Country:** New Zealand
* **Service ID:** `nzl_zealand_drivers_licence`
* **Data domain:** Document
* **Category:** DriverLicence

## Inputs

| Field                    | Required | Example           |
| ------------------------ | -------: | ----------------- |
| `first_name`             |      Yes | `John`            |
| `last_name`              |      Yes | `Doe`             |
| `date_of_birth`          |      Yes | `1990-01-01`      |
| `driver_license_number`  |      Yes | `SAMPLE-DL-12345` |
| `driver_license_version` |      Yes | `1`               |
| `vendor_data`            |       No | `user-1234`       |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `driver_license_number`, `driver_license_version`
* **Optional inputs:** `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** 100%\*
* **Price:** \$0.35 per successful query

## Body parameters

<ParamField type="string" placeholder="NZL">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `NZL`
</ParamField>

<ParamField type="string" placeholder="nzl_zealand_drivers_licence">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `nzl_zealand_drivers_licence`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-DL-12345">
  Driver licence number.

  Example: `SAMPLE-DL-12345`
</ParamField>

<ParamField type="string" placeholder="1">
  `driver_license_version` value required by this database service.

  Example: `1`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=NZL" \
    -F "services=nzl_zealand_drivers_licence" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "driver_license_number=SAMPLE-DL-12345" \
    -F "driver_license_version=1"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "NZL",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "nzl_zealand_drivers_licence",
        "service_name": "New Zealand Drivers Licence (NZTA)",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": true,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "NZL",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "nzl_zealand_drivers_licence",
        "service_name": "New Zealand Drivers Licence (NZTA)",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": false,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "NZL",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "nzl_zealand_drivers_licence",
        "service_name": "New Zealand Drivers Licence (NZTA)",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `nzl_zealand_drivers_licence` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `full_name`
* `identification_number`
* `last_name`
* `name_match_score`

## Pricing & SLAs

New Zealand Drivers Licence (NZTA) queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.35 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [New Zealand Database Validation overview](/api-reference/database-validation/new-zealand)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# DIA - New Zealand Passport
Source: https://docs.didit.me/api-reference/database-validation/new-zealand/passport

POST /v3/database-validation/
DIA Passport verification service. Authoritative real-time identity lookup for New Zealand. Real-time lookup, pay-per-call.

<div />

DIA Passport verification service. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 100%\*
* **Country:** New Zealand
* **Service ID:** `nzl_new_zealand_passport`
* **Data domain:** Document
* **Category:** Passport

## Inputs

| Field                      | Required | Example             |
| -------------------------- | -------: | ------------------- |
| `first_name`               |      Yes | `John`              |
| `last_name`                |      Yes | `Doe`               |
| `date_of_birth`            |      Yes | `1990-01-01`        |
| `passport_number`          |      Yes | `SAMPLE-PASS-12345` |
| `passport_expiration_date` |      Yes | `1990-01-01`        |
| `vendor_data`              |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `passport_number`, `passport_expiration_date`
* **Optional inputs:** `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** 100%\*
* **Price:** \$1.00 per successful query

## Body parameters

<ParamField type="string" placeholder="NZL">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `NZL`
</ParamField>

<ParamField type="string" placeholder="nzl_new_zealand_passport">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `nzl_new_zealand_passport`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-PASS-12345">
  Passport number.

  Example: `SAMPLE-PASS-12345`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Passport expiration date in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=NZL" \
    -F "services=nzl_new_zealand_passport" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "passport_number=SAMPLE-PASS-12345" \
    -F "passport_expiration_date=1990-01-01"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "NZL",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "nzl_new_zealand_passport",
        "service_name": "DIA - New Zealand Passport",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "NZL",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "nzl_new_zealand_passport",
        "service_name": "DIA - New Zealand Passport",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "NZL",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "nzl_new_zealand_passport",
        "service_name": "DIA - New Zealand Passport",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `nzl_new_zealand_passport` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `identification_number`
* `last_name`

## Pricing & SLAs

DIA - New Zealand Passport queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$1.00 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [New Zealand Database Validation overview](/api-reference/database-validation/new-zealand)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Nigeria Bank Verification Number (BVN)
Source: https://docs.didit.me/api-reference/database-validation/nigeria/bank-verification-number

POST /v3/database-validation/
Verifies input data against the Nigerian Banking Industry database. Requires a selfie: the enrolment portrait held against the BVN is face-matched with it, and the record is only returned when the two are the same person. Authoritative real-time identity lookup for Nigeria. Real-time lookup, pay-per-call.

<div />

Verifies input data against the Nigerian Banking Industry database. Requires a selfie: the enrolment portrait held against the BVN is face-matched with it, and the record is only returned when the two are the same person. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 100%
* **Country:** Nigeria
* **Service ID:** `nga_bank_verification_number`
* **Data domain:** Financial
* **Category:** Banking

## Inputs

| Field           | Required | Example         |
| --------------- | -------: | --------------- |
| `bvn`           |      Yes | `11111111111`   |
| `selfie`        |      Yes | `@./selfie.jpg` |
| `first_name`    |       No | `John`          |
| `last_name`     |       No | `Doe`           |
| `date_of_birth` |       No | `1990-01-01`    |
| `vendor_data`   |       No | `user-1234`     |

* **Required inputs:** `bvn`, `selfie`
* **Optional inputs:** `first_name`, `last_name`, `date_of_birth`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow with field mapping
* **Coverage:** \~ 100%
* **Price:** \$0.35 per successful query

In a workflow, `bvn` is not printed on an identity document, so no step produces it on its own. Collect it from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step. Until it is mapped the workflow editor shows this service disabled and names the missing input; at run time a missing input means the check is skipped before any query, so you are never billed for a database that could not be asked.

## Body parameters

<ParamField type="string" placeholder="NGA">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `NGA`
</ParamField>

<ParamField type="string" placeholder="nga_bank_verification_number">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `nga_bank_verification_number`
</ParamField>

<ParamField type="string" placeholder="11111111111">
  Bank Verification Number.

  Example: `11111111111`
</ParamField>

<ParamField type="file" placeholder="@./selfie.jpg">
  Selfie image file to upload for biometric database validation. Accepted formats: JPEG, PNG, or WebP.

  Example: `@./selfie.jpg`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Nigerian Bank Verification Number (exactly 11 digits)
* `bvn` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `bvn` must be exactly 11 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=NGA" \
    -F "services=nga_bank_verification_number" \
    -F "vendor_data=user-1234" \
    -F "bvn=11111111111" \
    -F "selfie=@./selfie.jpg"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "NGA",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "nga_bank_verification_number",
        "service_name": "Nigeria Bank Verification Number (BVN)",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`BIOMETRIC_NO_MATCH`** — The face-match score was below the acceptance threshold - the selfie is not the same person as the registry photo.

  ```json 200 OK — BIOMETRIC_NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "NGA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "BIOMETRIC_NO_MATCH",
        "service_id": "nga_bank_verification_number",
        "service_name": "Nigeria Bank Verification Number (BVN)",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```

  **`INCONCLUSIVE`** — The registry could not determine whether the person matches - the result is genuinely uncertain (they may or may not be in the registry). This is NOT a no-match and NOT a technical image problem; no field is asserted, so match\_type is null and the check is sent to review.

  ```json 200 OK — INCONCLUSIVE theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "NGA",
    "match_type": null,
    "validations": [
      {
        "outcome_code": "INCONCLUSIVE",
        "service_id": "nga_bank_verification_number",
        "service_name": "Nigeria Bank Verification Number (BVN)",
        "source_data": {},
        "validation": {}
      }
    ]
  }
  ```

  **`DOCUMENT_NOT_FOUND`** — The submitted document number does not correspond to any record in the registry.

  ```json 200 OK — DOCUMENT_NOT_FOUND theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "NGA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "DOCUMENT_NOT_FOUND",
        "service_id": "nga_bank_verification_number",
        "service_name": "Nigeria Bank Verification Number (BVN)",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `nga_bank_verification_number` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `last_name`

## Pricing & SLAs

Nigeria Bank Verification Number (BVN) queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.35 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Nigeria Database Validation overview](/api-reference/database-validation/nigeria)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Nigeria National ID (NIMC)
Source: https://docs.didit.me/api-reference/database-validation/nigeria/national-id

POST /v3/database-validation/
Verifies data against the National Identity database. Authoritative real-time identity lookup for Nigeria. Real-time lookup, pay-per-call.

<div />

Verifies data against the National Identity database. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 100%
* **Country:** Nigeria
* **Service ID:** `nga_national_id`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field           | Required | Example       |
| --------------- | -------: | ------------- |
| `first_name`    |      Yes | `John`        |
| `last_name`     |      Yes | `Doe`         |
| `national_id`   |      Yes | `11111111111` |
| `date_of_birth` |       No | `1990-01-01`  |
| `vendor_data`   |       No | `user-1234`   |

* **Required inputs:** `first_name`, `last_name`, `national_id`
* **Optional inputs:** `date_of_birth`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 100%
* **Price:** \$0.20 per successful query

Not every document this service accepts carries the identifier it queries by. When the identifier is not extracted from the document the check is recorded as **not applicable** - no database is queried and you are not charged - which for some countries is a large share of real users. To cover them, also collect the identifier from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step.

## Body parameters

<ParamField type="string" placeholder="NGA">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `NGA`
</ParamField>

<ParamField type="string" placeholder="nga_national_id">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `nga_national_id`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="11111111111">
  National identity number for this service.

  Example: `11111111111`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* `first_name` must match `[A-Za-zÀ-ÖØ-öø-ÿ .'-]+`.
* `national_id` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `national_id` must be exactly 11 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=NGA" \
    -F "services=nga_national_id" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "national_id=11111111111"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "NGA",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "nga_national_id",
        "service_name": "Nigeria National ID (NIMC)",
        "source_data": {
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000"
        },
        "validation": {
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "NGA",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "nga_national_id",
        "service_name": "Nigeria National ID (NIMC)",
        "source_data": {
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000"
        },
        "validation": {
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "NGA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "nga_national_id",
        "service_name": "Nigeria National ID (NIMC)",
        "source_data": {
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `nga_national_id` currently documents this normalized shape:

* `first_name`
* `full_name`
* `identification_number`
* `last_name`
* `name_match_score`

## Pricing & SLAs

Nigeria National ID (NIMC) queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.20 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Nigeria Database Validation overview](/api-reference/database-validation/nigeria)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Norway Residential
Source: https://docs.didit.me/api-reference/database-validation/norway/residential

POST /v3/database-validation/
Verifies input data against the Norwegian Register service. Authoritative real-time identity lookup for Norway. Real-time lookup, pay-per-call.

<div />

Verifies input data against the Norwegian Register service. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 100%
* **Country:** Norway
* **Service ID:** `nor_residential`
* **Data domain:** Address
* **Category:** Residential

## Inputs

| Field                 | Required | Example                |
| --------------------- | -------: | ---------------------- |
| `first_name`          |      Yes | `John`                 |
| `last_name`           |      Yes | `Doe`                  |
| `date_of_birth`       |      Yes | `1990-01-01`           |
| `address.street_1`    |      Yes | `123 Sample Street`    |
| `address.postal_code` |      Yes | `10001`                |
| `email`               |       No | `john.doe@example.com` |
| `address.street_2`    |       No | `Unit 4`               |
| `address.city`        |       No | `Sample City`          |
| `address.region`      |       No | `Sample State`         |
| `vendor_data`         |       No | `user-1234`            |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `address.street_1`, `address.postal_code`
* **Optional inputs:** `email`, `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 100%
* **Price:** \$2.42 per successful query

## Body parameters

<ParamField type="string" placeholder="NOR">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `NOR`
</ParamField>

<ParamField type="string" placeholder="nor_residential">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `nor_residential`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="john.doe@example.com">
  Email address.

  Example: `john.doe@example.com`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=NOR" \
    -F "services=nor_residential" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}'
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "NOR",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "nor_residential",
        "service_name": "Norway Residential",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "NOR",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "nor_residential",
        "service_name": "Norway Residential",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "NOR",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "nor_residential",
        "service_name": "Norway Residential",
        "source_data": {
          "address": "NO_MATCH",
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `nor_residential` currently documents this normalized shape:

* `address`
* `date_of_birth`
* `first_name`
* `last_name`

## Pricing & SLAs

Norway Residential queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$2.42 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Norway Database Validation overview](/api-reference/database-validation/norway)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Panama - Cédula with biometric face-match (SIB)
Source: https://docs.didit.me/api-reference/database-validation/panama/sib

POST /v3/database-validation/
Verifies Panamanian Cédula with biometric face-match against the Tribunal Electoral SIB biometric service. Standard tier. Authoritative real-time identity lookup for Panama. Real-time lookup, pay-per-call.

<div />

Verifies Panamanian Cédula with biometric face-match against the Tribunal Electoral SIB biometric service. Standard tier. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** Panama
* **Service ID:** `pan_cedula_sib`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field             | Required | Example            |
| ----------------- | -------: | ------------------ |
| `personal_number` |      Yes | `SAMPLE-PER-12345` |
| `selfie`          |      Yes | `@./selfie.jpg`    |
| `vendor_data`     |       No | `user-1234`        |

* **Required inputs:** `personal_number`, `selfie`
* **Optional inputs:** `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** —
* **Price:** \$0.75 per successful query

## Body parameters

<ParamField type="string" placeholder="PAN">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `PAN`
</ParamField>

<ParamField type="string" placeholder="pan_cedula_sib">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `pan_cedula_sib`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-PER-12345">
  Country-specific personal identity number.

  Example: `SAMPLE-PER-12345`
</ParamField>

<ParamField type="file" placeholder="@./selfie.jpg">
  Selfie image file to upload for biometric database validation. Accepted formats: JPEG, PNG, or WebP.

  Example: `@./selfie.jpg`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Panamanian Cédula (min 5 characters)
* `personal_number` must be 5-20 characters long.
* `personal_number` must use uppercase letters.
* `personal_number` must match `(?:\d{1,2}(?:-?(?:AV|PI))?|PE|E|N)[\d-]*`.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=PAN" \
    -F "services=pan_cedula_sib" \
    -F "vendor_data=user-1234" \
    -F "personal_number=SAMPLE-PER-12345" \
    -F "selfie=@./selfie.jpg"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "PAN",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "pan_cedula_sib",
        "service_name": "Panama - Cédula with biometric face-match (SIB)",
        "source_data": {
          "identification_number": "SAMPLE-ID-12345"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "PAN",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "pan_cedula_sib",
        "service_name": "Panama - Cédula with biometric face-match (SIB)",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```

  **`BIOMETRIC_NO_MATCH`** — The face-match score was below the acceptance threshold - the selfie is not the same person as the registry photo.

  ```json 200 OK — BIOMETRIC_NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "PAN",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "BIOMETRIC_NO_MATCH",
        "service_id": "pan_cedula_sib",
        "service_name": "Panama - Cédula with biometric face-match (SIB)",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```

  **`BIOMETRIC_IMAGE_UNUSABLE`** — The selfie could not be processed (empty, no face, low quality, or the registry could not read it). Prompt the user to retake the selfie.

  ```json 200 OK — BIOMETRIC_IMAGE_UNUSABLE theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "PAN",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "BIOMETRIC_IMAGE_UNUSABLE",
        "service_id": "pan_cedula_sib",
        "service_name": "Panama - Cédula with biometric face-match (SIB)",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```

  **`DECEASED`** — The identity matched, but the registry flags the person as deceased.

  ```json 200 OK — DECEASED theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "PAN",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "DECEASED",
        "service_id": "pan_cedula_sib",
        "service_name": "Panama - Cédula with biometric face-match (SIB)",
        "source_data": {
          "identification_number": "SAMPLE-ID-12345"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `pan_cedula_sib` currently documents this normalized shape:

* `identification_number`

## Pricing & SLAs

Panama - Cédula with biometric face-match (SIB) queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.75 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Panama Database Validation overview](/api-reference/database-validation/panama)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Panama - Cédula with biometric face-match (SIB Plus, elevated tier)
Source: https://docs.didit.me/api-reference/database-validation/panama/sib-plus

POST /v3/database-validation/
Verifies Panamanian Cédula with biometric face-match — elevated-tier SIB Plus. Same data source as the standard SIB tier with stronger biometric thresholds and richer match metadata. Authoritative real-time identity lookup for Panama. Real-time lookup, pay-per-call.

<div />

Verifies Panamanian Cédula with biometric face-match — elevated-tier SIB Plus. Same data source as the standard SIB tier with stronger biometric thresholds and richer match metadata. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** Panama
* **Service ID:** `pan_cedula_sib_plus`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field             | Required | Example            |
| ----------------- | -------: | ------------------ |
| `personal_number` |      Yes | `SAMPLE-PER-12345` |
| `selfie`          |      Yes | `@./selfie.jpg`    |
| `vendor_data`     |       No | `user-1234`        |

* **Required inputs:** `personal_number`, `selfie`
* **Optional inputs:** `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** —
* **Price:** \$1.50 per successful query

## Body parameters

<ParamField type="string" placeholder="PAN">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `PAN`
</ParamField>

<ParamField type="string" placeholder="pan_cedula_sib_plus">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `pan_cedula_sib_plus`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-PER-12345">
  Country-specific personal identity number.

  Example: `SAMPLE-PER-12345`
</ParamField>

<ParamField type="file" placeholder="@./selfie.jpg">
  Selfie image file to upload for biometric database validation. Accepted formats: JPEG, PNG, or WebP.

  Example: `@./selfie.jpg`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Panamanian Cédula (min 5 characters)
* `personal_number` must be 5-20 characters long.
* `personal_number` must use uppercase letters.
* `personal_number` must match `(?:\d{1,2}(?:-?(?:AV|PI))?|PE|E|N)[\d-]*`.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=PAN" \
    -F "services=pan_cedula_sib_plus" \
    -F "vendor_data=user-1234" \
    -F "personal_number=SAMPLE-PER-12345" \
    -F "selfie=@./selfie.jpg"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "PAN",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "pan_cedula_sib_plus",
        "service_name": "Panama - Cédula with biometric face-match (SIB Plus, elevated tier)",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "expiration_date": "1990-01-01",
          "full_name": "John Doe",
          "gender": "M",
          "identification_number": "SAMPLE-ID-12345",
          "issue_date": "1990-01-01",
          "last_name": "Doe",
          "place_of_birth": "sample_value",
          "signature": "sample_value"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "PAN",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "pan_cedula_sib_plus",
        "service_name": "Panama - Cédula with biometric face-match (SIB Plus, elevated tier)",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```

  **`BIOMETRIC_NO_MATCH`** — The face-match score was below the acceptance threshold - the selfie is not the same person as the registry photo.

  ```json 200 OK — BIOMETRIC_NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "PAN",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "BIOMETRIC_NO_MATCH",
        "service_id": "pan_cedula_sib_plus",
        "service_name": "Panama - Cédula with biometric face-match (SIB Plus, elevated tier)",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```

  **`BIOMETRIC_IMAGE_UNUSABLE`** — The selfie could not be processed (empty, no face, low quality, or the registry could not read it). Prompt the user to retake the selfie.

  ```json 200 OK — BIOMETRIC_IMAGE_UNUSABLE theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "PAN",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "BIOMETRIC_IMAGE_UNUSABLE",
        "service_id": "pan_cedula_sib_plus",
        "service_name": "Panama - Cédula with biometric face-match (SIB Plus, elevated tier)",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```

  **`DECEASED`** — The identity matched, but the registry flags the person as deceased.

  ```json 200 OK — DECEASED theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "PAN",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "DECEASED",
        "service_id": "pan_cedula_sib_plus",
        "service_name": "Panama - Cédula with biometric face-match (SIB Plus, elevated tier)",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "expiration_date": "1990-01-01",
          "full_name": "John Doe",
          "gender": "M",
          "identification_number": "SAMPLE-ID-12345",
          "issue_date": "1990-01-01",
          "last_name": "Doe",
          "place_of_birth": "sample_value",
          "signature": "sample_value"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `pan_cedula_sib_plus` currently documents this normalized shape:

* `date_of_birth`
* `expiration_date`
* `full_name`
* `gender`
* `identification_number`
* `issue_date`
* `last_name`
* `place_of_birth`
* `signature`

## Pricing & SLAs

Panama - Cédula with biometric face-match (SIB Plus, elevated tier) queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$1.50 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Panama Database Validation overview](/api-reference/database-validation/panama)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Paraguay - CI verification
Source: https://docs.didit.me/api-reference/database-validation/paraguay/cedula

POST /v3/database-validation/
Verifies Paraguayan Cédula data against Registro del Estado Civil government records. Authoritative real-time identity lookup for Paraguay. Real-time lookup, pay-per-call.

<div />

Verifies Paraguayan Cédula data against Registro del Estado Civil government records. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 90-95%
* **Country:** Paraguay
* **Service ID:** `pry_cedula`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field             | Required | Example     |
| ----------------- | -------: | ----------- |
| `document_number` |      Yes | `111111`    |
| `first_name`      |       No | `John`      |
| `last_name`       |       No | `Doe`       |
| `vendor_data`     |       No | `user-1234` |

* **Required inputs:** `document_number`
* **Optional inputs:** `first_name`, `last_name`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** 90-95%
* **Price:** \$0.20 per successful query

## Body parameters

<ParamField type="string" placeholder="PRY">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `PRY`
</ParamField>

<ParamField type="string" placeholder="pry_cedula">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `pry_cedula`
</ParamField>

<ParamField type="string" placeholder="111111">
  Document number extracted from or provided by the user.

  Example: `111111`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Paraguayan CI (6-10 digits)
* `document_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `document_number` must be 6-10 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=PRY" \
    -F "services=pry_cedula" \
    -F "vendor_data=user-1234" \
    -F "document_number=111111"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "PRY",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "pry_cedula",
        "service_name": "Paraguay - CI verification",
        "source_data": {
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "PRY",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "pry_cedula",
        "service_name": "Paraguay - CI verification",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `pry_cedula` currently documents this normalized shape:

* `first_name`
* `full_name`
* `identification_number`
* `last_name`

## Pricing & SLAs

Paraguay - CI verification queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.20 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Paraguay Database Validation overview](/api-reference/database-validation/paraguay)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Peru - DNI verification
Source: https://docs.didit.me/api-reference/database-validation/peru/dni

POST /v3/database-validation/
Verifies Peruvian DNI against the RENIEC civil registry. Authoritative real-time identity lookup for Peru. Real-time lookup, pay-per-call.

<div />

Verifies Peruvian DNI against the RENIEC civil registry. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** Peru
* **Service ID:** `per_dni`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field             | Required | Example     |
| ----------------- | -------: | ----------- |
| `personal_number` |      Yes | `11111111`  |
| `first_name`      |       No | `John`      |
| `last_name`       |       No | `Doe`       |
| `vendor_data`     |       No | `user-1234` |

* **Required inputs:** `personal_number`
* **Optional inputs:** `first_name`, `last_name`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** —
* **Price:** \$0.20 per successful query

## Body parameters

<ParamField type="string" placeholder="PER">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `PER`
</ParamField>

<ParamField type="string" placeholder="per_dni">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `per_dni`
</ParamField>

<ParamField type="string" placeholder="11111111">
  Country-specific personal identity number.

  Example: `11111111`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Peruvian DNI (exactly 8 digits)
* `personal_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `personal_number` must be exactly 8 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=PER" \
    -F "services=per_dni" \
    -F "vendor_data=user-1234" \
    -F "personal_number=11111111"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "PER",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "per_dni",
        "service_name": "Peru - DNI verification",
        "source_data": {
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "maternal_name": "Doe Maternal",
          "paternal_name": "Doe Paternal",
          "verification_letter": "G",
          "verification_number": 2
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "PER",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "per_dni",
        "service_name": "Peru - DNI verification",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```

  **`DOCUMENT_NOT_FOUND`** — The submitted document number does not correspond to any record in the registry.

  ```json 200 OK — DOCUMENT_NOT_FOUND theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "PER",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "DOCUMENT_NOT_FOUND",
        "service_id": "per_dni",
        "service_name": "Peru - DNI verification",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `per_dni` currently documents this normalized shape:

* `first_name`
* `identification_number`
* `last_name`
* `maternal_name`
* `paternal_name`
* `verification_letter`
* `verification_number`

## Pricing & SLAs

Peru - DNI verification queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.20 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Peru Database Validation overview](/api-reference/database-validation/peru)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Peru Tax Registration (SUNAT)
Source: https://docs.didit.me/api-reference/database-validation/peru/tax-registration

POST /v3/database-validation/
Verifies input data against SUNAT. Authoritative real-time identity lookup for Peru. Real-time lookup, pay-per-call.

<div />

Verifies input data against SUNAT. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** > 90%
* **Country:** Peru
* **Service ID:** `per_tax_registration`
* **Data domain:** Financial
* **Category:** TaxRegistry

## Inputs

| Field             | Required | Example      |
| ----------------- | -------: | ------------ |
| `first_name`      |      Yes | `John`       |
| `last_name`       |      Yes | `Doe`        |
| `date_of_birth`   |      Yes | `1990-01-01` |
| `personal_number` |      Yes | `11111111`   |
| `vendor_data`     |       No | `user-1234`  |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `personal_number`
* **Optional inputs:** `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** > 90%
* **Price:** \$1.75 per successful query

Not every document this service accepts carries the identifier it queries by. When the identifier is not extracted from the document the check is recorded as **not applicable** - no database is queried and you are not charged - which for some countries is a large share of real users. To cover them, also collect the identifier from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step.

## Body parameters

<ParamField type="string" placeholder="PER">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `PER`
</ParamField>

<ParamField type="string" placeholder="per_tax_registration">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `per_tax_registration`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="11111111">
  Country-specific personal identity number.

  Example: `11111111`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Peruvian DNI (exactly 8 digits)
* `personal_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `personal_number` must be exactly 8 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=PER" \
    -F "services=per_tax_registration" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "personal_number=11111111"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "PER",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "per_tax_registration",
        "service_name": "Peru Tax Registration (SUNAT)",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": true,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "PER",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "per_tax_registration",
        "service_name": "Peru Tax Registration (SUNAT)",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": false,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "PER",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "per_tax_registration",
        "service_name": "Peru Tax Registration (SUNAT)",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `per_tax_registration` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `full_name`
* `identification_number`
* `last_name`
* `name_match_score`

## Pricing & SLAs

Peru Tax Registration (SUNAT) queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$1.75 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Peru Database Validation overview](/api-reference/database-validation/peru)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Philippines Residential
Source: https://docs.didit.me/api-reference/database-validation/philippines/residential

POST /v3/database-validation/
Verifies input data against a Government agency database consisting of Filipino citizens data. Authoritative real-time identity lookup for Philippines. Real-time lookup, pay-per-call.

<div />

Verifies input data against a Government agency database consisting of Filipino citizens data. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** > 80%
* **Country:** Philippines
* **Service ID:** `phl_residential`
* **Data domain:** Address
* **Category:** Residential

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `address.street_1`    |       No | `123 Sample Street` |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `address.postal_code` |       No | `10001`             |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`
* **Optional inputs:** `address.street_1`, `address.street_2`, `address.city`, `address.region`, `address.postal_code`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** > 80%
* **Price:** \$0.35 per successful query

## Body parameters

<ParamField type="string" placeholder="PHL">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `PHL`
</ParamField>

<ParamField type="string" placeholder="phl_residential">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `phl_residential`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* `address` is optional for this service. You can send one complete `address` string and Didit will split it into structured address elements when possible, or you can send the structured fields explicitly.
* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=PHL" \
    -F "services=phl_residential" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "PHL",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "phl_residential",
        "service_name": "Philippines Residential",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "PHL",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "phl_residential",
        "service_name": "Philippines Residential",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": false
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "PHL",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "phl_residential",
        "service_name": "Philippines Residential",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `phl_residential` currently documents this normalized shape:

* `date_of_birth`
* `name_match_score`

## Pricing & SLAs

Philippines Residential queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.35 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Philippines Database Validation overview](/api-reference/database-validation/philippines)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Singapore Credit Bureau
Source: https://docs.didit.me/api-reference/database-validation/singapore/credit-bureau

POST /v3/database-validation/
Verifies input data against Credit Header data obtained from a Credit Bureau in Singapore. Authoritative real-time identity lookup for Singapore. Real-time lookup, pay-per-call.

<div />

Verifies input data against Credit Header data obtained from a Credit Bureau in Singapore. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** undisclosed
* **Country:** Singapore
* **Service ID:** `sgp_credit_bureau`
* **Data domain:** Financial
* **Category:** CreditBureau

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `full_name`           |      Yes | `John Doe`          |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `national_id`         |      Yes | `SAMPLE-NID-12345`  |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `full_name`, `date_of_birth`, `address.street_1`, `address.postal_code`, `national_id`
* **Optional inputs:** `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** undisclosed
* **Price:** \$2.61 per successful query

## Body parameters

<ParamField type="string" placeholder="SGP">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `SGP`
</ParamField>

<ParamField type="string" placeholder="sgp_credit_bureau">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `sgp_credit_bureau`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John Doe">
  Full legal name to validate.

  Example: `John Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-NID-12345">
  National identity number for this service.

  Example: `SAMPLE-NID-12345`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=SGP" \
    -F "services=sgp_credit_bureau" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "full_name=John Doe" \
    -F "date_of_birth=1990-01-01" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}' \
    -F "national_id=SAMPLE-NID-12345"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "SGP",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "sgp_credit_bureau",
        "service_name": "Singapore Credit Bureau",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "identification_number": "SAMPLE-ID-12345",
          "postal_code": "10001",
          "street": "sample_value",
          "verifications": {
            "address": true,
            "date_of_birth": true,
            "full_name": true,
            "identification_number": true
          }
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "SGP",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "sgp_credit_bureau",
        "service_name": "Singapore Credit Bureau",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "identification_number": "SAMPLE-ID-12345",
          "postal_code": "10001",
          "street": "sample_value",
          "verifications": {
            "address": true,
            "date_of_birth": true,
            "full_name": false,
            "identification_number": true
          }
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "SGP",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "sgp_credit_bureau",
        "service_name": "Singapore Credit Bureau",
        "source_data": {
          "address": "NO_MATCH",
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `sgp_credit_bureau` currently documents this normalized shape:

* `address`
* `address_match_score`
* `city`
* `date_of_birth`
* `identification_number`
* `postal_code`
* `street`

## Pricing & SLAs

Singapore Credit Bureau queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$2.61 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Singapore Database Validation overview](/api-reference/database-validation/singapore)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Singapore Utility
Source: https://docs.didit.me/api-reference/database-validation/singapore/utility

POST /v3/database-validation/
Verifies input data to telco billing records and phone data. Authoritative real-time identity lookup for Singapore. Real-time lookup, pay-per-call.

<div />

Verifies input data to telco billing records and phone data. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** > 80%
* **Country:** Singapore
* **Service ID:** `sgp_utility`
* **Data domain:** Address
* **Category:** Utility

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `date_of_birth`       |       No | `1990-01-01`        |
| `phone`               |       No | `+15550101000`      |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `address.street_1`, `address.postal_code`
* **Optional inputs:** `date_of_birth`, `phone`, `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** > 80%
* **Price:** \$1.69 per successful query

## Body parameters

<ParamField type="string" placeholder="SGP">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `SGP`
</ParamField>

<ParamField type="string" placeholder="sgp_utility">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `sgp_utility`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  Phone number in international format.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=SGP" \
    -F "services=sgp_utility" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}'
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "SGP",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "sgp_utility",
        "service_name": "Singapore Utility",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "postal_code": "10001",
          "street": "sample_value",
          "verifications": {
            "address": true,
            "full_name": true
          }
        },
        "validation": {
          "address": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "SGP",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "sgp_utility",
        "service_name": "Singapore Utility",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "postal_code": "10001",
          "street": "sample_value",
          "verifications": {
            "address": true,
            "full_name": false
          }
        },
        "validation": {
          "address": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "SGP",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "sgp_utility",
        "service_name": "Singapore Utility",
        "source_data": {
          "address": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `sgp_utility` currently documents this normalized shape:

* `address`
* `address_match_score`
* `city`
* `date_of_birth`
* `first_name`
* `full_name`
* `last_name`
* `name_match_score`
* `postal_code`
* `street`

## Pricing & SLAs

Singapore Utility queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$1.69 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Singapore Database Validation overview](/api-reference/database-validation/singapore)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# South Africa - Bank Account Holder Verification
Source: https://docs.didit.me/api-reference/database-validation/south-africa/bank-account-holder

POST /v3/database-validation/
Confirms a South African bank account belongs to the named holder via the inter-bank Account Holder Verification service. Authoritative real-time identity lookup for South Africa. Real-time lookup, pay-per-call.

<div />

Confirms a South African bank account belongs to the named holder via the inter-bank Account Holder Verification service. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** South Africa
* **Service ID:** `zaf_bank_account_holder`
* **Data domain:** Financial
* **Category:** Banking

## Inputs

| Field                 | Required | Example                |
| --------------------- | -------: | ---------------------- |
| `national_id`         |      Yes | `8708150847085`        |
| `bank_account_number` |      Yes | `1234567890`           |
| `bank_name`           |      Yes | `ABSA`                 |
| `account_type`        |       No | `current`              |
| `first_name`          |       No | `John`                 |
| `last_name`           |       No | `Doe`                  |
| `initials`            |       No | `JD`                   |
| `email`               |       No | `john.doe@example.com` |
| `phone_number`        |       No | `+15550101000`         |
| `vendor_data`         |       No | `user-1234`            |

* **Required inputs:** `national_id`, `bank_account_number`, `bank_name`
* **Optional inputs:** `account_type`, `first_name`, `last_name`, `initials`, `email`, `phone_number`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow with field mapping
* **Coverage:** —
* **Price:** \$0.40 per successful query

In a workflow, `bank_account_number` and `bank_name` are not printed on an identity document, so no step produces them on their own. Collect them from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map each one on the Database Validation step. Until they are mapped the workflow editor shows this service disabled and names the missing input; at run time a missing input means the check is skipped before any query, so you are never billed for a database that could not be asked.

## Body parameters

<ParamField type="string" placeholder="ZAF">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `ZAF`
</ParamField>

<ParamField type="string" placeholder="zaf_bank_account_holder">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `zaf_bank_account_holder`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="8708150847085">
  National identity number for this service.

  Example: `8708150847085`
</ParamField>

<ParamField type="string" placeholder="1234567890">
  `bank_account_number` value required by this database service.

  Example: `1234567890`
</ParamField>

<ParamField type="string" placeholder="ABSA">
  `bank_name` value required by this database service.

  Example: `ABSA`
</ParamField>

<ParamField type="string" placeholder="current">
  `account_type` value required by this database service.

  Example: `current`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="JD">
  `initials` value required by this database service.

  Example: `JD`
</ParamField>

<ParamField type="string" placeholder="john.doe@example.com">
  Email address.

  Example: `john.doe@example.com`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  `phone_number` value required by this database service.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* `account_type` must be one of the South African AVS account types: `current`, `savings`, `transmission`, `subscriptionShare`, `notKnown`. Matching is case-insensitive. Omit the field when you do not know the account type - Didit then sends `notKnown` and the account-type cross-check is reported as not confirmed instead of failing the request.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=ZAF" \
    -F "services=zaf_bank_account_holder" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "national_id=8708150847085" \
    -F "bank_account_number=1234567890" \
    -F "bank_name=ABSA" \
    -F "account_type=current" \
    -F "last_name=Doe" \
    -F "initials=JD"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "ZAF",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "zaf_bank_account_holder",
        "service_name": "South Africa - Bank Account Holder Verification",
        "source_data": {
          "accepts_credits": true,
          "accepts_debits": true,
          "account_found": true,
          "account_number_length_valid": true,
          "account_open": true,
          "account_type_match": true,
          "id_match": true,
          "identification_number": "SAMPLE-ID-12345",
          "initials_match": true,
          "surname_match": true
        },
        "validation": {
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "ZAF",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "zaf_bank_account_holder",
        "service_name": "South Africa - Bank Account Holder Verification",
        "source_data": {
          "accepts_credits": true,
          "accepts_debits": true,
          "account_found": true,
          "account_number_length_valid": false,
          "account_open": true,
          "account_type_match": true,
          "id_match": true,
          "identification_number": "SAMPLE-ID-12345",
          "initials_match": true,
          "surname_match": false
        },
        "validation": {
          "full_name": "partial_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ZAF",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "zaf_bank_account_holder",
        "service_name": "South Africa - Bank Account Holder Verification",
        "source_data": {
          "accepts_credits": false,
          "accepts_debits": false,
          "account_found": false,
          "account_number_length_valid": false,
          "account_open": false,
          "account_type_match": false,
          "id_match": false,
          "identification_number": "NO_MATCH",
          "initials_match": false,
          "surname_match": false
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `zaf_bank_account_holder` currently documents this normalized shape:

* `accepts_credits`
* `accepts_debits`
* `account_found`
* `account_number_length_valid`
* `account_open`
* `account_type_match`
* `id_match`
* `identification_number`
* `initials_match`
* `surname_match`

## Pricing & SLAs

South Africa - Bank Account Holder Verification queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.40 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## What a MATCH confirms

Account Holder Verification (AVS) is a set of yes/no cross-checks, not a record lookup. The source never returns a name, an ID number or an account balance - it takes the details you send, compares them against what the bank holds for that account, and answers each comparison with a flag. `source_data` carries those flags:

* **`account_found`** - the bank holds an account with this number. Everything else is meaningless when this is `false`.
* **`account_open`** - the account is open. An account can be found but closed.
* **`id_match`** - the account is held by the national id you submitted. This is the check the service exists for.
* **`initials_match`**, **`surname_match`** - the submitted `initials` and `last_name` match the account holder on file.
* **`account_type_match`** - the submitted `account_type` matches the account's real type.
* **`email_match`**, **`phone_match`** - the submitted `email` and `phone_number` match the contact details the bank holds.
* **`accepts_debits`**, **`accepts_credits`** - the account can receive debit orders and credits.
* **`account_number_length_valid`** - the account number is the length the bank expects.

The outcome code summarises them:

* **`MATCH`** - the account exists and every field you submitted matched, `id_match` included.
* **`PARTIAL_MATCH`** - the account is held by the submitted national id, but at least one other field you sent did not match (a surname spelled differently on the bank's records, for example). `outcome_detail` names the fields that failed.
* **`NO_MATCH`** - either the bank holds no such account, or the account exists but belongs to someone else. Both are conclusive answers about the person.

A cross-check you did not ask for is neither counted nor reported. AVS answers `N` for every field that was not supplied, so `surname_match`, `initials_match`, `email_match`, `phone_match` and `account_type_match` appear in `source_data` only when you sent the matching input. Sending only `national_id`, `bank_account_number` and `bank_name` therefore still produces a full `MATCH`.

## Accepted bank\_name and account\_type values

`bank_name` and `account_type` are enumerations. A value outside either list is refused before the query runs, so a typo costs you a round-trip rather than a charge.

`account_type` is optional and accepts, case-insensitively:

`current` · `savings` · `transmission` · `subscriptionShare` · `notKnown`

Omit it when you do not know the account type. Didit then sends `notKnown`, the request succeeds, and `account_type_match` comes back `false` because there was nothing to compare. Any other value - `checking`, `cheque`, `bond` - is rejected with a `400` that lists the accepted set.

`bank_name` is required, and these values are confirmed accepted (case-insensitive):

`ABSA` · `Capitec` · `FNB` · `Nedbank` · `Standard Bank` · `Investec` · `African Bank` · `Discovery Bank` · `Old Mutual` · `Bank Zero` · `Tyme` · `Grindrod`

Consumer accounts at all of these are in scope, Capitec included. Send the short form exactly as listed - `Capitec`, not `Capitec Bank`; `Tyme`, not `TymeBank`. An unrecognised bank comes back as an outcome of `REGISTRY_ERROR` whose `outcome_detail` names the field the source refused.

## Telling a missing account apart from an unavailable source

These are different HTTP outcomes, so no parsing of error strings is needed:

* **The account does not exist** - `200 OK`, `match_type: "no_match"`, `outcome_code: "NO_MATCH"`, `source_data.account_found: false`. A real answer from the bank. Billed, and your no-match action applies.
* **The source did not answer** - `502 Bad Gateway` with `validation_errors[].code` = `empty_provider_response` and `retryable: true`. Nothing was established about the person, nothing is billed, and the request is safe to retry.
* **The source refused to run the query** - `400 Bad Request` with `validation_errors[].code` = `provider_rejected_input` and `retryable: false`. The source never searched, because it would not accept what it was sent. Correct the data; retrying the same values cannot succeed. Nothing is billed.
* **The source answered and rejected your input** - `502 Bad Gateway` with `validation_errors[].code` = `provider_invalid_input` (for example an account number that fails the bank's own format check). Retrying is pointless until the input is corrected; nothing is billed.
* **Your request never left Didit** - `400 Bad Request`, listing the field to fix. Nothing is billed.

Only the first of these is an answer about the person. Treat a `502` as transient - AVS relays to the account holder's bank rather than reading a registry, so it is the slowest of the South African services - and retry with backoff.

## Continue reading

* [South Africa Database Validation overview](/api-reference/database-validation/south-africa)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# South Africa - Company Directors Lookup
Source: https://docs.didit.me/api-reference/database-validation/south-africa/company-directors

POST /v3/database-validation/
Returns the current directors of a South African company from the CIPC commercial register. Authoritative real-time identity lookup for South Africa. Real-time lookup, pay-per-call.

<div />

Returns the current directors of a South African company from the CIPC commercial register. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** South Africa
* **Service ID:** `zaf_company_directors`
* **Data domain:** Government
* **Category:** CompanyRegister

## Inputs

| Field                         | Required | Example      |
| ----------------------------- | -------: | ------------ |
| `company_registration_number` |      Yes | `REG-123456` |
| `vendor_data`                 |       No | `user-1234`  |

* **Required inputs:** `company_registration_number`
* **Optional inputs:** `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow with field mapping
* **Coverage:** —
* **Price:** \$0.65 per successful query

In a workflow, `company_registration_number` is not printed on an identity document, so no step produces it on its own. Collect it from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step. Until it is mapped the workflow editor shows this service disabled and names the missing input; at run time a missing input means the check is skipped before any query, so you are never billed for a database that could not be asked.

## Body parameters

<ParamField type="string" placeholder="ZAF">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `ZAF`
</ParamField>

<ParamField type="string" placeholder="zaf_company_directors">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `zaf_company_directors`
</ParamField>

<ParamField type="string" placeholder="REG-123456">
  `company_registration_number` value required by this database service.

  Example: `REG-123456`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=ZAF" \
    -F "services=zaf_company_directors" \
    -F "vendor_data=user-1234" \
    -F "company_registration_number=REG-123456"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "ZAF",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "zaf_company_directors",
        "service_name": "South Africa - Company Directors Lookup",
        "source_data": {},
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ZAF",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "zaf_company_directors",
        "service_name": "South Africa - Company Directors Lookup",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `zaf_company_directors` currently documents this normalized shape:

* Varies by registry response.

## Pricing & SLAs

South Africa - Company Directors Lookup queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.65 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [South Africa Database Validation overview](/api-reference/database-validation/south-africa)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# South Africa - Company Registry Lookup
Source: https://docs.didit.me/api-reference/database-validation/south-africa/company-registry

POST /v3/database-validation/
Looks up a South African company by registration number against the CIPC commercial register. Authoritative real-time identity lookup for South Africa. Real-time lookup, pay-per-call.

<div />

Looks up a South African company by registration number against the CIPC commercial register. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** South Africa
* **Service ID:** `zaf_company_registry`
* **Data domain:** Government
* **Category:** CompanyRegister

## Inputs

| Field                         | Required | Example              |
| ----------------------------- | -------: | -------------------- |
| `company_registration_number` |      Yes | `REG-123456`         |
| `company_name`                |       No | `Sample Company LLC` |
| `vendor_data`                 |       No | `user-1234`          |

* **Required inputs:** `company_registration_number`
* **Optional inputs:** `company_name`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow with field mapping
* **Coverage:** —
* **Price:** \$0.65 per successful query

In a workflow, `company_registration_number` is not printed on an identity document, so no step produces it on its own. Collect it from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step. Until it is mapped the workflow editor shows this service disabled and names the missing input; at run time a missing input means the check is skipped before any query, so you are never billed for a database that could not be asked.

## Body parameters

<ParamField type="string" placeholder="ZAF">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `ZAF`
</ParamField>

<ParamField type="string" placeholder="zaf_company_registry">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `zaf_company_registry`
</ParamField>

<ParamField type="string" placeholder="REG-123456">
  `company_registration_number` value required by this database service.

  Example: `REG-123456`
</ParamField>

<ParamField type="string" placeholder="Sample Company LLC">
  `company_name` value required by this database service.

  Example: `Sample Company LLC`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=ZAF" \
    -F "services=zaf_company_registry" \
    -F "vendor_data=user-1234" \
    -F "company_registration_number=REG-123456"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "ZAF",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "zaf_company_registry",
        "service_name": "South Africa - Company Registry Lookup",
        "source_data": {},
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ZAF",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "zaf_company_registry",
        "service_name": "South Africa - Company Registry Lookup",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `zaf_company_registry` currently documents this normalized shape:

* Varies by registry response.

## Pricing & SLAs

South Africa - Company Registry Lookup queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.65 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [South Africa Database Validation overview](/api-reference/database-validation/south-africa)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# South Africa - Contactability Lookup
Source: https://docs.didit.me/api-reference/database-validation/south-africa/contactability

POST /v3/database-validation/
Returns known phone numbers, emails, and addresses tied to a South African individual. Authoritative real-time identity lookup for South Africa. Real-time lookup, pay-per-call.

<div />

Returns known phone numbers, emails, and addresses tied to a South African individual. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** South Africa
* **Service ID:** `zaf_contactability`
* **Data domain:** Telecom
* **Category:** Telecom

## Inputs

| Field         | Required | Example            |
| ------------- | -------: | ------------------ |
| `national_id` |      Yes | `SAMPLE-NID-12345` |
| `vendor_data` |       No | `user-1234`        |

* **Required inputs:** `national_id`
* **Optional inputs:** `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** —
* **Price:** \$0.35 per successful query

## Body parameters

<ParamField type="string" placeholder="ZAF">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `ZAF`
</ParamField>

<ParamField type="string" placeholder="zaf_contactability">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `zaf_contactability`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-NID-12345">
  National identity number for this service.

  Example: `SAMPLE-NID-12345`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=ZAF" \
    -F "services=zaf_contactability" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "national_id=SAMPLE-NID-12345"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "ZAF",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "zaf_contactability",
        "service_name": "South Africa - Contactability Lookup",
        "source_data": {
          "contact_email": "alex.sample@example.com",
          "contact_phone_numbers": "+15550101000",
          "date_of_birth": "1990-01-01",
          "deceased": "sample_value",
          "first_name": "John",
          "gender": "M",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "phone_history_count": "+15550101000"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ZAF",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "zaf_contactability",
        "service_name": "South Africa - Contactability Lookup",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `zaf_contactability` currently documents this normalized shape:

* `contact_email`
* `contact_phone_numbers`
* `date_of_birth`
* `deceased`
* `first_name`
* `gender`
* `identification_number`
* `last_name`
* `phone_history_count`

## Pricing & SLAs

South Africa - Contactability Lookup queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.35 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [South Africa Database Validation overview](/api-reference/database-validation/south-africa)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# South Africa - Criminal Screening by Face
Source: https://docs.didit.me/api-reference/database-validation/south-africa/criminal-face-screening

POST /v3/database-validation/
Screens a facial image against published criminal-record datasets to surface potential matches. Authoritative real-time identity lookup for South Africa. Real-time lookup, pay-per-call.

<div />

Screens a facial image against published criminal-record datasets to surface potential matches. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** South Africa
* **Service ID:** `zaf_criminal_face_screening`
* **Data domain:** Criminal
* **Category:** Criminal

## Inputs

| Field         | Required | Example         |
| ------------- | -------: | --------------- |
| `selfie`      |      Yes | `@./selfie.jpg` |
| `score_level` |       No | `standard`      |
| `max_matches` |       No | `10`            |
| `vendor_data` |       No | `user-1234`     |

* **Required inputs:** `selfie`
* **Optional inputs:** `score_level`, `max_matches`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** —
* **Price:** \$7.00 per successful query

## Body parameters

<ParamField type="string" placeholder="ZAF">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `ZAF`
</ParamField>

<ParamField type="string" placeholder="zaf_criminal_face_screening">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `zaf_criminal_face_screening`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="file" placeholder="@./selfie.jpg">
  Selfie image file to upload for biometric database validation. Accepted formats: JPEG, PNG, or WebP.

  Example: `@./selfie.jpg`
</ParamField>

<ParamField type="string" placeholder="standard">
  `score_level` value required by this database service.

  Example: `standard`
</ParamField>

<ParamField type="string" placeholder="10">
  `max_matches` value required by this database service.

  Example: `10`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=ZAF" \
    -F "services=zaf_criminal_face_screening" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "selfie=@./selfie.jpg"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "ZAF",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "zaf_criminal_face_screening",
        "service_name": "South Africa - Criminal Screening by Face",
        "source_data": {
          "criminal_matches": "sample_value",
          "face_quality": "sample_value",
          "request_id": "SAMPLE-12345"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ZAF",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "zaf_criminal_face_screening",
        "service_name": "South Africa - Criminal Screening by Face",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```

  **`BIOMETRIC_NO_MATCH`** — The face-match score was below the acceptance threshold - the selfie is not the same person as the registry photo.

  ```json 200 OK — BIOMETRIC_NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ZAF",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "BIOMETRIC_NO_MATCH",
        "service_id": "zaf_criminal_face_screening",
        "service_name": "South Africa - Criminal Screening by Face",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```

  **`BIOMETRIC_IMAGE_UNUSABLE`** — The selfie could not be processed (empty, no face, low quality, or the registry could not read it). Prompt the user to retake the selfie.

  ```json 200 OK — BIOMETRIC_IMAGE_UNUSABLE theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "ZAF",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "BIOMETRIC_IMAGE_UNUSABLE",
        "service_id": "zaf_criminal_face_screening",
        "service_name": "South Africa - Criminal Screening by Face",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `zaf_criminal_face_screening` currently documents this normalized shape:

* `criminal_matches`
* `face_quality`
* `request_id`

## Pricing & SLAs

South Africa - Criminal Screening by Face queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$7.00 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [South Africa Database Validation overview](/api-reference/database-validation/south-africa)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# South Africa - DHA Fingerprint Match
Source: https://docs.didit.me/api-reference/database-validation/south-africa/dha-fingerprint-match

POST /v3/database-validation/
Verifies provided fingerprint images against the Department of Home Affairs fingerprint register. Authoritative real-time identity lookup for South Africa. Real-time lookup, pay-per-call.

<div />

Verifies provided fingerprint images against the Department of Home Affairs fingerprint register. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** South Africa
* **Service ID:** `zaf_dha_fingerprint_match`
* **Data domain:** Biometric
* **Category:** Government

## Inputs

| Field         | Required | Example                |
| ------------- | -------: | ---------------------- |
| `national_id` |      Yes | `SAMPLE-NID-12345`     |
| `right_thumb` |      Yes | `RIGHT_THUMB_TEMPLATE` |
| `left_thumb`  |      Yes | `LEFT_THUMB_TEMPLATE`  |
| `vendor_data` |       No | `user-1234`            |

* **Required inputs:** `national_id`, `right_thumb`, `left_thumb`
* **Optional inputs:** `vendor_data`
* **Consent:** Required
* **Workflow availability:** Standalone API only
* **Coverage:** —
* **Price:** \$1.10 per successful query

This service needs an input no workflow step can produce (a biometric capture, a signed artifact, a live one-time code), so it is available only on the standalone API, where you supply the values directly.

## Body parameters

<ParamField type="string" placeholder="ZAF">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `ZAF`
</ParamField>

<ParamField type="string" placeholder="zaf_dha_fingerprint_match">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `zaf_dha_fingerprint_match`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-NID-12345">
  National identity number for this service.

  Example: `SAMPLE-NID-12345`
</ParamField>

<ParamField type="string" placeholder="RIGHT_THUMB_TEMPLATE">
  `right_thumb` value required by this database service.

  Example: `RIGHT_THUMB_TEMPLATE`
</ParamField>

<ParamField type="string" placeholder="LEFT_THUMB_TEMPLATE">
  `left_thumb` value required by this database service.

  Example: `LEFT_THUMB_TEMPLATE`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=ZAF" \
    -F "services=zaf_dha_fingerprint_match" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "national_id=SAMPLE-NID-12345" \
    -F "right_thumb=RIGHT_THUMB_TEMPLATE" \
    -F "left_thumb=LEFT_THUMB_TEMPLATE"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "ZAF",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "zaf_dha_fingerprint_match",
        "service_name": "South Africa - DHA Fingerprint Match",
        "source_data": {
          "identification_number": "SAMPLE-ID-12345"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ZAF",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "zaf_dha_fingerprint_match",
        "service_name": "South Africa - DHA Fingerprint Match",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `zaf_dha_fingerprint_match` currently documents this normalized shape:

* `identification_number`

## Pricing & SLAs

South Africa - DHA Fingerprint Match queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$1.10 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [South Africa Database Validation overview](/api-reference/database-validation/south-africa)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# South Africa - DHA Photo Retrieval
Source: https://docs.didit.me/api-reference/database-validation/south-africa/dha-photo

POST /v3/database-validation/
Retrieves the registered Department of Home Affairs photograph for a South African ID number. Authoritative real-time identity lookup for South Africa. Real-time lookup, pay-per-call.

<div />

Retrieves the registered Department of Home Affairs photograph for a South African ID number. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** South Africa
* **Service ID:** `zaf_dha_photo`
* **Data domain:** Biometric
* **Category:** Government

## Inputs

| Field         | Required | Example            |
| ------------- | -------: | ------------------ |
| `national_id` |      Yes | `SAMPLE-NID-12345` |
| `vendor_data` |       No | `user-1234`        |

* **Required inputs:** `national_id`
* **Optional inputs:** `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** —
* **Price:** \$1.10 per successful query

## Body parameters

<ParamField type="string" placeholder="ZAF">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `ZAF`
</ParamField>

<ParamField type="string" placeholder="zaf_dha_photo">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `zaf_dha_photo`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-NID-12345">
  National identity number for this service.

  Example: `SAMPLE-NID-12345`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=ZAF" \
    -F "services=zaf_dha_photo" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "national_id=SAMPLE-NID-12345"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "ZAF",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "zaf_dha_photo",
        "service_name": "South Africa - DHA Photo Retrieval",
        "source_data": {
          "birth_place_country_code": "sample_value",
          "deceased": "sample_value",
          "first_name": "John",
          "id_blocked": false,
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "marital_status": "sample_value",
          "on_hanis_biometric_register": "sample_value",
          "on_national_population_register": "sample_value",
          "photo_base64": "sample_value",
          "smart_card_issued": "sample_value",
          "transaction_number": "SAMPLE-12345"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ZAF",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "zaf_dha_photo",
        "service_name": "South Africa - DHA Photo Retrieval",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `zaf_dha_photo` currently documents this normalized shape:

* `birth_place_country_code`
* `deceased`
* `first_name`
* `id_blocked`
* `identification_number`
* `last_name`
* `marital_status`
* `on_hanis_biometric_register`
* `on_national_population_register`
* `photo_base64`
* `smart_card_issued`
* `transaction_number`

## Pricing & SLAs

South Africa - DHA Photo Retrieval queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$1.10 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [South Africa Database Validation overview](/api-reference/database-validation/south-africa)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# South Africa - Driving License Verification
Source: https://docs.didit.me/api-reference/database-validation/south-africa/drivers-license

POST /v3/database-validation/
Verifies a South African driving license against the NATIS / Department of Transport register. Authoritative real-time identity lookup for South Africa. Real-time lookup, pay-per-call.

<div />

Verifies a South African driving license against the NATIS / Department of Transport register. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** South Africa
* **Service ID:** `zaf_drivers_license`
* **Data domain:** Identity
* **Category:** DriverLicence

## Inputs

| Field            | Required | Example            |
| ---------------- | -------: | ------------------ |
| `national_id`    |      Yes | `SAMPLE-NID-12345` |
| `last_name`      |      Yes | `Doe`              |
| `initials`       |      Yes | `JD`               |
| `licence_number` |      Yes | `LIC123456`        |
| `first_name`     |       No | `John`             |
| `date_of_birth`  |       No | `1990-01-01`       |
| `vendor_data`    |       No | `user-1234`        |

* **Required inputs:** `national_id`, `last_name`, `initials`, `licence_number`
* **Optional inputs:** `first_name`, `date_of_birth`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow with field mapping
* **Coverage:** —
* **Price:** \$0.70 per successful query

In a workflow, `initials` and `licence_number` are not printed on an identity document, so no step produces them on their own. Collect them from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map each one on the Database Validation step. Until they are mapped the workflow editor shows this service disabled and names the missing input; at run time a missing input means the check is skipped before any query, so you are never billed for a database that could not be asked.

## Body parameters

<ParamField type="string" placeholder="ZAF">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `ZAF`
</ParamField>

<ParamField type="string" placeholder="zaf_drivers_license">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `zaf_drivers_license`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-NID-12345">
  National identity number for this service.

  Example: `SAMPLE-NID-12345`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="JD">
  `initials` value required by this database service.

  Example: `JD`
</ParamField>

<ParamField type="string" placeholder="LIC123456">
  `licence_number` value required by this database service.

  Example: `LIC123456`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=ZAF" \
    -F "services=zaf_drivers_license" \
    -F "vendor_data=user-1234" \
    -F "national_id=SAMPLE-NID-12345" \
    -F "last_name=Doe" \
    -F "initials=JD" \
    -F "licence_number=LIC123456"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "ZAF",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "zaf_drivers_license",
        "service_name": "South Africa - Driving License Verification",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "ZAF",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "zaf_drivers_license",
        "service_name": "South Africa - Driving License Verification",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ZAF",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "zaf_drivers_license",
        "service_name": "South Africa - Driving License Verification",
        "source_data": {
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `zaf_drivers_license` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `identification_number`
* `last_name`

## Pricing & SLAs

South Africa - Driving License Verification queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.70 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## What a MATCH confirms

This is a **record match against the driving-licence register**, not a licence-standing check. You send a South African ID number and a licence number (plus surname and initials as cross-checks); the register is asked whether it holds that licence for that person, and `validation` reports how each submitted field compared with the record.

A `MATCH` therefore means *this licence number belongs to this person on the register*. It does not assert that the licence is currently valid to drive on.

`source_data` carries the record the register returned:

* **`identification_number`** - the licence number held on the record.
* **`first_name`**, **`last_name`** - the forenames and surname on the record.
* **`vehicle_codes`** - the vehicle codes (licence classes) the record carries, e.g. `EB`, `C1`.
* **`expiration_date`** - the expiry date of the licence card on the record.

**What is not returned.** There is no suspension, cancellation, withdrawal, endorsement or demerit-point field: the register does not answer those through this service, so a `MATCH` must never be worded to your users as "the licence is valid and in good standing". `expiration_date` is the one standing-adjacent fact you get - compare it with the session date to decide whether the licence has expired, and treat that as a rule of your own rather than as part of the match outcome.

If you need to state this in terms and conditions, word it as: Didit confirms the licence details against the national register and returns the licence's classes and expiry date - not that Didit confirms the holder is licensed to drive today.

## Continue reading

* [South Africa Database Validation overview](/api-reference/database-validation/south-africa)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# South Africa - Fraud Prevention Screening
Source: https://docs.didit.me/api-reference/database-validation/south-africa/fraud-prevention

POST /v3/database-validation/
Screens an individual against the South African Fraud Prevention Service (SAFPS) watch-list. Authoritative real-time identity lookup for South Africa. Real-time lookup, pay-per-call.

<div />

Screens an individual against the South African Fraud Prevention Service (SAFPS) watch-list. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** South Africa
* **Service ID:** `zaf_fraud_prevention`
* **Data domain:** Background
* **Category:** Background

## Inputs

| Field                 | Required | Example                |
| --------------------- | -------: | ---------------------- |
| `national_id`         |       No | `SAMPLE-NID-12345`     |
| `bank_account_number` |       No | `1234567890`           |
| `phone_number`        |       No | `+15550101000`         |
| `email`               |       No | `john.doe@example.com` |
| `vendor_data`         |       No | `user-1234`            |

* **Required inputs:** —
* **Optional inputs:** `national_id`, `bank_account_number`, `phone_number`, `email`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** —
* **Price:** \$0.30 per successful query

## Body parameters

<ParamField type="string" placeholder="ZAF">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `ZAF`
</ParamField>

<ParamField type="string" placeholder="zaf_fraud_prevention">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `zaf_fraud_prevention`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-NID-12345">
  National identity number for this service.

  Example: `SAMPLE-NID-12345`
</ParamField>

<ParamField type="string" placeholder="1234567890">
  `bank_account_number` value required by this database service.

  Example: `1234567890`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  `phone_number` value required by this database service.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="john.doe@example.com">
  Email address.

  Example: `john.doe@example.com`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=ZAF" \
    -F "services=zaf_fraud_prevention" \
    -F "vendor_data=user-1234" \
    -F "consent=true"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "ZAF",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "zaf_fraud_prevention",
        "service_name": "South Africa - Fraud Prevention Screening",
        "source_data": {
          "fraud_listings": "sample_value",
          "identification_number": "SAMPLE-ID-12345"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ZAF",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "zaf_fraud_prevention",
        "service_name": "South Africa - Fraud Prevention Screening",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `zaf_fraud_prevention` currently documents this normalized shape:

* `fraud_listings`
* `identification_number`

## Pricing & SLAs

South Africa - Fraud Prevention Screening queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.30 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [South Africa Database Validation overview](/api-reference/database-validation/south-africa)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# South Africa National ID (DHA)
Source: https://docs.didit.me/api-reference/database-validation/south-africa/national-id

POST /v3/database-validation/
Verifies input data against the Department of Home Affairs (DHA) registry in South Africa. Authoritative real-time identity lookup for South Africa. Real-time lookup, pay-per-call.

<div />

Verifies input data against the Department of Home Affairs (DHA) registry in South Africa. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 100%
* **Country:** South Africa
* **Service ID:** `zaf_africa_national_id`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field           | Required | Example            |
| --------------- | -------: | ------------------ |
| `first_name`    |      Yes | `John`             |
| `last_name`     |      Yes | `Doe`              |
| `date_of_birth` |      Yes | `1990-01-01`       |
| `national_id`   |      Yes | `SAMPLE-NID-12345` |
| `vendor_data`   |       No | `user-1234`        |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `national_id`
* **Optional inputs:** `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 100%
* **Price:** \$1.10 per successful query

## Body parameters

<ParamField type="string" placeholder="ZAF">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `ZAF`
</ParamField>

<ParamField type="string" placeholder="zaf_africa_national_id">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `zaf_africa_national_id`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-NID-12345">
  National identity number for this service.

  Example: `SAMPLE-NID-12345`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=ZAF" \
    -F "services=zaf_africa_national_id" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "national_id=SAMPLE-NID-12345"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "ZAF",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "zaf_africa_national_id",
        "service_name": "South Africa National ID (DHA)",
        "source_data": {
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "marital_status": "sample_value"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "ZAF",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "zaf_africa_national_id",
        "service_name": "South Africa National ID (DHA)",
        "source_data": {
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "marital_status": "sample_value"
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ZAF",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "zaf_africa_national_id",
        "service_name": "South Africa National ID (DHA)",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```

  **`DOCUMENT_NOT_FOUND`** — The submitted document number does not correspond to any record in the registry.

  ```json 200 OK — DOCUMENT_NOT_FOUND theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ZAF",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "DOCUMENT_NOT_FOUND",
        "service_id": "zaf_africa_national_id",
        "service_name": "South Africa National ID (DHA)",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `zaf_africa_national_id` currently documents this normalized shape:

* `first_name`
* `identification_number`
* `last_name`
* `marital_status`

## Pricing & SLAs

South Africa National ID (DHA) queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$1.10 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [South Africa Database Validation overview](/api-reference/database-validation/south-africa)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# South Africa - Person Directorships Lookup
Source: https://docs.didit.me/api-reference/database-validation/south-africa/person-directorships

POST /v3/database-validation/
Returns all CIPC-registered directorships held by a South African individual. Authoritative real-time identity lookup for South Africa. Real-time lookup, pay-per-call.

<div />

Returns all CIPC-registered directorships held by a South African individual. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** South Africa
* **Service ID:** `zaf_person_directorships`
* **Data domain:** Government
* **Category:** CompanyRegister

## Inputs

| Field         | Required | Example            |
| ------------- | -------: | ------------------ |
| `national_id` |      Yes | `SAMPLE-NID-12345` |
| `vendor_data` |       No | `user-1234`        |

* **Required inputs:** `national_id`
* **Optional inputs:** `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** —
* **Price:** \$1.20 per successful query

## Body parameters

<ParamField type="string" placeholder="ZAF">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `ZAF`
</ParamField>

<ParamField type="string" placeholder="zaf_person_directorships">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `zaf_person_directorships`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-NID-12345">
  National identity number for this service.

  Example: `SAMPLE-NID-12345`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=ZAF" \
    -F "services=zaf_person_directorships" \
    -F "vendor_data=user-1234" \
    -F "national_id=SAMPLE-NID-12345"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "ZAF",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "zaf_person_directorships",
        "service_name": "South Africa - Person Directorships Lookup",
        "source_data": {
          "directorships": "sample_value",
          "identification_number": "SAMPLE-ID-12345"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ZAF",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "zaf_person_directorships",
        "service_name": "South Africa - Person Directorships Lookup",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `zaf_person_directorships` currently documents this normalized shape:

* `directorships`
* `identification_number`

## Pricing & SLAs

South Africa - Person Directorships Lookup queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$1.20 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [South Africa Database Validation overview](/api-reference/database-validation/south-africa)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# South Africa - Refugee File Verification
Source: https://docs.didit.me/api-reference/database-validation/south-africa/refugee

POST /v3/database-validation/
Verifies a refugee file number against the South African Department of Home Affairs refugee register. Authoritative real-time identity lookup for South Africa. Real-time lookup, pay-per-call.

<div />

Verifies a refugee file number against the South African Department of Home Affairs refugee register. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** South Africa
* **Service ID:** `zaf_refugee`
* **Data domain:** Identity
* **Category:** Government

## Inputs

| Field                 | Required | Example                |
| --------------------- | -------: | ---------------------- |
| `refugee_file_number` |      Yes | `RF123456`             |
| `phone_number`        |       No | `+15550101000`         |
| `email`               |       No | `john.doe@example.com` |
| `vendor_data`         |       No | `user-1234`            |

* **Required inputs:** `refugee_file_number`
* **Optional inputs:** `phone_number`, `email`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow with field mapping
* **Coverage:** —
* **Price:** \$1.10 per successful query

In a workflow, `refugee_file_number` is not printed on an identity document, so no step produces it on its own. Collect it from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step. Until it is mapped the workflow editor shows this service disabled and names the missing input; at run time a missing input means the check is skipped before any query, so you are never billed for a database that could not be asked.

## Body parameters

<ParamField type="string" placeholder="ZAF">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `ZAF`
</ParamField>

<ParamField type="string" placeholder="zaf_refugee">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `zaf_refugee`
</ParamField>

<ParamField type="string" placeholder="RF123456">
  `refugee_file_number` value required by this database service.

  Example: `RF123456`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  `phone_number` value required by this database service.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="john.doe@example.com">
  Email address.

  Example: `john.doe@example.com`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=ZAF" \
    -F "services=zaf_refugee" \
    -F "vendor_data=user-1234" \
    -F "refugee_file_number=RF123456"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "ZAF",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "zaf_refugee",
        "service_name": "South Africa - Refugee File Verification",
        "source_data": {},
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ZAF",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "zaf_refugee",
        "service_name": "South Africa - Refugee File Verification",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `zaf_refugee` currently documents this normalized shape:

* Varies by registry response.

## Pricing & SLAs

South Africa - Refugee File Verification queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$1.10 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [South Africa Database Validation overview](/api-reference/database-validation/south-africa)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# South Africa - Vehicle Ownership Verification
Source: https://docs.didit.me/api-reference/database-validation/south-africa/vehicle-ownership

POST /v3/database-validation/
Confirms that a South African individual is the registered owner of a given vehicle via the NATIS vehicle register. Authoritative real-time identity lookup for South Africa. Real-time lookup, pay-per-call.

<div />

Confirms that a South African individual is the registered owner of a given vehicle via the NATIS vehicle register. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** —
* **Country:** South Africa
* **Service ID:** `zaf_vehicle_ownership`
* **Data domain:** Government
* **Category:** Other

## Inputs

| Field                     | Required | Example             |
| ------------------------- | -------: | ------------------- |
| `national_id`             |      Yes | `SAMPLE-NID-12345`  |
| `vehicle_register_number` |      Yes | `VRN123456`         |
| `vehicle_licence_plate`   |      Yes | `ABC123GP`          |
| `vin`                     |      Yes | `1HGCM82633A004352` |
| `vendor_data`             |       No | `user-1234`         |

* **Required inputs:** `national_id`, `vehicle_register_number`, `vehicle_licence_plate`, `vin`
* **Optional inputs:** `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow with field mapping
* **Coverage:** —
* **Price:** \$2.80 per successful query

In a workflow, `vehicle_register_number`, `vehicle_licence_plate` and `vin` are not printed on an identity document, so no step produces them on their own. Collect them from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map each one on the Database Validation step. Until they are mapped the workflow editor shows this service disabled and names the missing input; at run time a missing input means the check is skipped before any query, so you are never billed for a database that could not be asked.

## Body parameters

<ParamField type="string" placeholder="ZAF">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `ZAF`
</ParamField>

<ParamField type="string" placeholder="zaf_vehicle_ownership">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `zaf_vehicle_ownership`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-NID-12345">
  National identity number for this service.

  Example: `SAMPLE-NID-12345`
</ParamField>

<ParamField type="string" placeholder="VRN123456">
  `vehicle_register_number` value required by this database service.

  Example: `VRN123456`
</ParamField>

<ParamField type="string" placeholder="ABC123GP">
  `vehicle_licence_plate` value required by this database service.

  Example: `ABC123GP`
</ParamField>

<ParamField type="string" placeholder="1HGCM82633A004352">
  `vin` value required by this database service.

  Example: `1HGCM82633A004352`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Send the fields listed above exactly as captured from the user or document.
* Didit validates required fields before calling the database. Requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=ZAF" \
    -F "services=zaf_vehicle_ownership" \
    -F "vendor_data=user-1234" \
    -F "national_id=SAMPLE-NID-12345" \
    -F "vehicle_register_number=VRN123456" \
    -F "vehicle_licence_plate=ABC123GP" \
    -F "vin=1HGCM82633A004352"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "ZAF",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "zaf_vehicle_ownership",
        "service_name": "South Africa - Vehicle Ownership Verification",
        "source_data": {
          "identification_number": "SAMPLE-ID-12345"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ZAF",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "zaf_vehicle_ownership",
        "service_name": "South Africa - Vehicle Ownership Verification",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `zaf_vehicle_ownership` currently documents this normalized shape:

* `identification_number`

## Pricing & SLAs

South Africa - Vehicle Ownership Verification queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$2.80 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [South Africa Database Validation overview](/api-reference/database-validation/south-africa)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Spain - DNI/NIE verification
Source: https://docs.didit.me/api-reference/database-validation/spain/dni

POST /v3/database-validation/
Verifies a Spanish DNI / NIE holder's name, date of birth and address against national identity records. Authoritative real-time identity lookup for Spain. Real-time lookup, pay-per-call.

<div />

Verifies a Spanish DNI / NIE holder's name, date of birth and address against national identity records. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 75%
* **Country:** Spain
* **Service ID:** `esp_dni`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `national_id`         |       No | `SAMPLE-NID-12345`  |
| `phone`               |       No | `+15550101000`      |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `address.street_1`, `address.postal_code`
* **Optional inputs:** `national_id`, `phone`, `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 75%
* **Price:** \$1.26 per successful query

## Body parameters

<ParamField type="string" placeholder="ESP">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `ESP`
</ParamField>

<ParamField type="string" placeholder="esp_dni">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `esp_dni`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-NID-12345">
  National identity number for this service.

  Example: `SAMPLE-NID-12345`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  Phone number in international format.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=ESP" \
    -F "services=esp_dni" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}'
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "ESP",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "esp_dni",
        "service_name": "Spain - DNI/NIE verification",
        "source_data": {
          "address_match_score": "1.000",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "address": true,
            "date_of_birth": true,
            "full_name": true
          }
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "ESP",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "esp_dni",
        "service_name": "Spain - DNI/NIE verification",
        "source_data": {
          "address_match_score": "1.000",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "address": true,
            "date_of_birth": true,
            "full_name": false
          }
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "ESP",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "esp_dni",
        "service_name": "Spain - DNI/NIE verification",
        "source_data": {
          "address": "NO_MATCH",
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `esp_dni` currently documents this normalized shape:

* `address_match_score`
* `date_of_birth`
* `first_name`
* `full_name`
* `identification_number`
* `last_name`
* `name_match_score`

## Pricing & SLAs

Spain - DNI/NIE verification queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$1.26 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Spain Database Validation overview](/api-reference/database-validation/spain)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Sweden National ID
Source: https://docs.didit.me/api-reference/database-validation/sweden/national-id

POST /v3/database-validation/
Verifies input data against the Swedish Police Authority service. Authoritative real-time identity lookup for Sweden. Real-time lookup, pay-per-call.

<div />

Verifies input data against the Swedish Police Authority service. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 100%
* **Country:** Sweden
* **Service ID:** `swe_national_id`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `national_id`         |      Yes | `11111111`          |
| `address.street_1`    |       No | `123 Sample Street` |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `address.postal_code` |       No | `10001`             |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `national_id`
* **Optional inputs:** `address.street_1`, `address.street_2`, `address.city`, `address.region`, `address.postal_code`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 100%
* **Price:** \$0.35 per successful query

Not every document this service accepts carries the identifier it queries by. When the identifier is not extracted from the document the check is recorded as **not applicable** - no database is queried and you are not charged - which for some countries is a large share of real users. To cover them, also collect the identifier from a Questionnaire answer, a Document AI extraction field, or a value you send when you create the session, and map it on the Database Validation step.

## Body parameters

<ParamField type="string" placeholder="SWE">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `SWE`
</ParamField>

<ParamField type="string" placeholder="swe_national_id">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `swe_national_id`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="11111111">
  National identity number for this service.

  Example: `11111111`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* `address` is optional for this service. You can send one complete `address` string and Didit will split it into structured address elements when possible, or you can send the structured fields explicitly.
* `national_id` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `national_id` must match `(\d{10}|\d{12})`.
* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=SWE" \
    -F "services=swe_national_id" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "national_id=11111111"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "SWE",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "swe_national_id",
        "service_name": "Sweden National ID",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": true,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "SWE",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "swe_national_id",
        "service_name": "Sweden National ID",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": false,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "SWE",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "swe_national_id",
        "service_name": "Sweden National ID",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `swe_national_id` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `full_name`
* `identification_number`
* `last_name`
* `name_match_score`

## Pricing & SLAs

Sweden National ID queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.35 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Sweden Database Validation overview](/api-reference/database-validation/sweden)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Sweden Phone
Source: https://docs.didit.me/api-reference/database-validation/sweden/phone

POST /v3/database-validation/
Verifies input data to mobile network operators phone data. Authoritative real-time identity lookup for Sweden. Real-time lookup, pay-per-call.

<div />

Verifies input data to mobile network operators phone data. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 100%
* **Country:** Sweden
* **Service ID:** `swe_phone`
* **Data domain:** Telecom
* **Category:** Telecom

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `phone`               |      Yes | `+15550101000`      |
| `date_of_birth`       |       No | `1990-01-01`        |
| `national_id`         |       No | `SAMPLE-NID-12345`  |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `address.street_1`, `address.postal_code`, `phone`
* **Optional inputs:** `date_of_birth`, `national_id`, `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 100%
* **Price:** \$0.35 per successful query

## Body parameters

<ParamField type="string" placeholder="SWE">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `SWE`
</ParamField>

<ParamField type="string" placeholder="swe_phone">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `swe_phone`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  Phone number in international format.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-NID-12345">
  National identity number for this service.

  Example: `SAMPLE-NID-12345`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=SWE" \
    -F "services=swe_phone" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}' \
    -F "phone=+15550101000"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "SWE",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "swe_phone",
        "service_name": "Sweden Phone",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "SWE",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "swe_phone",
        "service_name": "Sweden Phone",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "SWE",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "swe_phone",
        "service_name": "Sweden Phone",
        "source_data": {
          "address": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `swe_phone` currently documents this normalized shape:

* `address`
* `date_of_birth`
* `first_name`
* `identification_number`
* `last_name`

## Pricing & SLAs

Sweden Phone queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.35 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Sweden Database Validation overview](/api-reference/database-validation/sweden)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Switzerland Credit Bureau
Source: https://docs.didit.me/api-reference/database-validation/switzerland/credit-bureau

POST /v3/database-validation/
Credit Header data obtained from the Credit Bureau in Switzerland. Authoritative real-time identity lookup for Switzerland. Real-time lookup, pay-per-call.

<div />

Credit Header data obtained from the Credit Bureau in Switzerland. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 85%
* **Country:** Switzerland
* **Service ID:** `che_credit_bureau`
* **Data domain:** Financial
* **Category:** CreditBureau

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `address.street_1`, `address.postal_code`
* **Optional inputs:** `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 85%
* **Price:** \$2.00 per successful query

## Body parameters

<ParamField type="string" placeholder="CHE">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `CHE`
</ParamField>

<ParamField type="string" placeholder="che_credit_bureau">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `che_credit_bureau`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=CHE" \
    -F "services=che_credit_bureau" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}'
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "CHE",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "che_credit_bureau",
        "service_name": "Switzerland Credit Bureau",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "CHE",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "che_credit_bureau",
        "service_name": "Switzerland Credit Bureau",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "CHE",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "che_credit_bureau",
        "service_name": "Switzerland Credit Bureau",
        "source_data": {
          "address": "NO_MATCH",
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `che_credit_bureau` currently documents this normalized shape:

* `address`
* `date_of_birth`
* `first_name`
* `last_name`

## Pricing & SLAs

Switzerland Credit Bureau queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$2.00 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Switzerland Database Validation overview](/api-reference/database-validation/switzerland)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Thailand National ID
Source: https://docs.didit.me/api-reference/database-validation/thailand/national-id

POST /v3/database-validation/
Verifies input data against government agency sourced National ID. Authoritative real-time identity lookup for Thailand. Real-time lookup, pay-per-call.

<div />

Verifies input data against government agency sourced National ID. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 90%
* **Country:** Thailand
* **Service ID:** `tha_national_id`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `national_id`         |      Yes | `1111111111111`     |
| `address.street_1`    |       No | `123 Sample Street` |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `address.postal_code` |       No | `10001`             |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `national_id`
* **Optional inputs:** `address.street_1`, `address.street_2`, `address.city`, `address.region`, `address.postal_code`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 90%
* **Price:** \$0.35 per successful query

## Body parameters

<ParamField type="string" placeholder="THA">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `THA`
</ParamField>

<ParamField type="string" placeholder="tha_national_id">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `tha_national_id`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="1111111111111">
  National identity number for this service.

  Example: `1111111111111`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* `address` is optional for this service. You can send one complete `address` string and Didit will split it into structured address elements when possible, or you can send the structured fields explicitly.
* Thai national ID number: 13 digits whose last digit is the mod-11 check digit (weights 13 to 2 over the first twelve digits).
* `national_id` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `national_id` must be exactly 13 characters long.
* The final Thai national ID check digit (mod 11) is validated; a number that fails the check is refused before the lookup and is not charged.
* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=THA" \
    -F "services=tha_national_id" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F "national_id=1111111111111"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "THA",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "tha_national_id",
        "service_name": "Thailand National ID",
        "source_data": {
          "address_match_score": "1.000",
          "date_of_birth": "1990-01-01",
          "identification_number": "SAMPLE-ID-12345",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": true,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "THA",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "tha_national_id",
        "service_name": "Thailand National ID",
        "source_data": {
          "address_match_score": "1.000",
          "date_of_birth": "1990-01-01",
          "identification_number": "SAMPLE-ID-12345",
          "name_match_score": "1.000",
          "verifications": {
            "date_of_birth": true,
            "full_name": false,
            "identification_number": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "THA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "tha_national_id",
        "service_name": "Thailand National ID",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `tha_national_id` currently documents this normalized shape:

* `address_match_score`
* `date_of_birth`
* `identification_number`
* `name_match_score`

## Pricing & SLAs

Thailand National ID queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.35 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Thailand Database Validation overview](/api-reference/database-validation/thailand)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# United Kingdom Credit Bureau
Source: https://docs.didit.me/api-reference/database-validation/united-kingdom/credit-bureau

POST /v3/database-validation/
Verifies input data against Credit Header data obtained from a Credit Bureau in the United Kingdom. Authoritative real-time identity lookup for United Kingdom. Real-time lookup, pay-per-call.

<div />

Verifies input data against Credit Header data obtained from a Credit Bureau in the United Kingdom. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 85%
* **Country:** United Kingdom
* **Service ID:** `gbr_kingdom_credit_bureau`
* **Data domain:** Financial
* **Category:** CreditBureau

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `address.street_1`, `address.postal_code`
* **Optional inputs:** `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 85%
* **Price:** \$0.90 per successful query

## Body parameters

<ParamField type="string" placeholder="GBR">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `GBR`
</ParamField>

<ParamField type="string" placeholder="gbr_kingdom_credit_bureau">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `gbr_kingdom_credit_bureau`
</ParamField>

<ParamField type="boolean" placeholder="true">
  Explicit end-user consent for this service.

  Example: `true`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=GBR" \
    -F "services=gbr_kingdom_credit_bureau" \
    -F "vendor_data=user-1234" \
    -F "consent=true" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}'
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "GBR",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "gbr_kingdom_credit_bureau",
        "service_name": "United Kingdom Credit Bureau",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "GBR",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "gbr_kingdom_credit_bureau",
        "service_name": "United Kingdom Credit Bureau",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "GBR",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "gbr_kingdom_credit_bureau",
        "service_name": "United Kingdom Credit Bureau",
        "source_data": {
          "address": "NO_MATCH",
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `gbr_kingdom_credit_bureau` currently documents this normalized shape:

* `address`
* `date_of_birth`
* `first_name`
* `last_name`

## Pricing & SLAs

United Kingdom Credit Bureau queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.90 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [United Kingdom Database Validation overview](/api-reference/database-validation/united-kingdom)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# United Kingdom Financial Services
Source: https://docs.didit.me/api-reference/database-validation/united-kingdom/financial-services

POST /v3/database-validation/
Aggregated service of government and public records, background records, and other services. Authoritative real-time identity lookup for United Kingdom. Real-time lookup, pay-per-call.

<div />

Aggregated service of government and public records, background records, and other services. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 85%
* **Country:** United Kingdom
* **Service ID:** `gbr_kingdom_financial_services`
* **Data domain:** Financial
* **Category:** FinancialServices

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `date_of_birth`       |      Yes | `1990-01-01`        |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `phone`               |       No | `+15550101000`      |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `address.street_1`, `address.postal_code`
* **Optional inputs:** `phone`, `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 85%
* **Price:** \$0.95 per successful query

## Body parameters

<ParamField type="string" placeholder="GBR">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `GBR`
</ParamField>

<ParamField type="string" placeholder="gbr_kingdom_financial_services">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `gbr_kingdom_financial_services`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  Phone number in international format.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=GBR" \
    -F "services=gbr_kingdom_financial_services" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}'
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "GBR",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "gbr_kingdom_financial_services",
        "service_name": "United Kingdom Financial Services",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "GBR",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "gbr_kingdom_financial_services",
        "service_name": "United Kingdom Financial Services",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "GBR",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "gbr_kingdom_financial_services",
        "service_name": "United Kingdom Financial Services",
        "source_data": {
          "address": "NO_MATCH",
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `gbr_kingdom_financial_services` currently documents this normalized shape:

* `address`
* `date_of_birth`
* `first_name`
* `last_name`

## Pricing & SLAs

United Kingdom Financial Services queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.95 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [United Kingdom Database Validation overview](/api-reference/database-validation/united-kingdom)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# United Kingdom Phone 2
Source: https://docs.didit.me/api-reference/database-validation/united-kingdom/phone-2

POST /v3/database-validation/
Verifies input data to mobile network operators phone data. Authoritative real-time identity lookup for United Kingdom. Real-time lookup, pay-per-call.

<div />

Verifies input data to mobile network operators phone data. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** > 75%
* **Country:** United Kingdom
* **Service ID:** `gbr_kingdom_phone_2`
* **Data domain:** Telecom
* **Category:** Telecom

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `phone`               |      Yes | `+15550101000`      |
| `date_of_birth`       |       No | `1990-01-01`        |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `address.street_1`, `address.postal_code`, `phone`
* **Optional inputs:** `date_of_birth`, `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** > 75%
* **Price:** \$0.96 per successful query

## Body parameters

<ParamField type="string" placeholder="GBR">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `GBR`
</ParamField>

<ParamField type="string" placeholder="gbr_kingdom_phone_2">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `gbr_kingdom_phone_2`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  Phone number in international format.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=GBR" \
    -F "services=gbr_kingdom_phone_2" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}' \
    -F "phone=+15550101000"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "GBR",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "gbr_kingdom_phone_2",
        "service_name": "United Kingdom Phone 2",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "GBR",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "gbr_kingdom_phone_2",
        "service_name": "United Kingdom Phone 2",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "GBR",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "gbr_kingdom_phone_2",
        "service_name": "United Kingdom Phone 2",
        "source_data": {
          "address": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `gbr_kingdom_phone_2` currently documents this normalized shape:

* `address`
* `date_of_birth`
* `first_name`
* `last_name`

## Pricing & SLAs

United Kingdom Phone 2 queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.96 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [United Kingdom Database Validation overview](/api-reference/database-validation/united-kingdom)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# United Kingdom Residential
Source: https://docs.didit.me/api-reference/database-validation/united-kingdom/residential

POST /v3/database-validation/
Aggregated service of government and public records, background records, and public professional profiles. Authoritative real-time identity lookup for United Kingdom. Real-time lookup, pay-per-call.

<div />

Aggregated service of government and public records, background records, and public professional profiles. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 90%
* **Country:** United Kingdom
* **Service ID:** `gbr_kingdom_residential`
* **Data domain:** Address
* **Category:** Residential

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `date_of_birth`       |       No | `1990-01-01`        |
| `phone`               |       No | `+15550101000`      |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `address.street_1`, `address.postal_code`
* **Optional inputs:** `date_of_birth`, `phone`, `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 90%
* **Price:** \$0.25 per successful query

## Body parameters

<ParamField type="string" placeholder="GBR">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `GBR`
</ParamField>

<ParamField type="string" placeholder="gbr_kingdom_residential">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `gbr_kingdom_residential`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  Phone number in international format.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=GBR" \
    -F "services=gbr_kingdom_residential" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}'
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "GBR",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "gbr_kingdom_residential",
        "service_name": "United Kingdom Residential",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "GBR",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "gbr_kingdom_residential",
        "service_name": "United Kingdom Residential",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "GBR",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "gbr_kingdom_residential",
        "service_name": "United Kingdom Residential",
        "source_data": {
          "address": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `gbr_kingdom_residential` currently documents this normalized shape:

* `address`
* `date_of_birth`
* `first_name`
* `last_name`

## Pricing & SLAs

United Kingdom Residential queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.25 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [United Kingdom Database Validation overview](/api-reference/database-validation/united-kingdom)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# United States of America - United States Credit Bureau
Source: https://docs.didit.me/api-reference/database-validation/united-states/credit-bureau

POST /v3/database-validation/
Aggregated service of credit header data and other services. Authoritative real-time identity lookup for United States. Real-time lookup, pay-per-call.

<div />

Aggregated service of credit header data and other services. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 90%
* **Country:** United States
* **Service ID:** `usa_states_credit_bureau`
* **Data domain:** Financial
* **Category:** CreditBureau

## Inputs

| Field                 | Required | Example                |
| --------------------- | -------: | ---------------------- |
| `first_name`          |      Yes | `John`                 |
| `last_name`           |      Yes | `Doe`                  |
| `date_of_birth`       |       No | `1990-01-01`           |
| `address.street_1`    |       No | `123 Sample Street`    |
| `address.street_2`    |       No | `Unit 4`               |
| `address.city`        |       No | `Sample City`          |
| `address.region`      |       No | `Sample State`         |
| `address.postal_code` |       No | `10001`                |
| `phone`               |       No | `+15550101000`         |
| `ssn`                 |       No | `123456789`            |
| `email`               |       No | `john.doe@example.com` |
| `vendor_data`         |       No | `user-1234`            |

* **Required inputs:** `first_name`, `last_name`
* **Optional inputs:** `date_of_birth`, `address.street_1`, `address.street_2`, `address.city`, `address.region`, `address.postal_code`, `phone`, `ssn`, `email`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 90%
* **Price:** \$0.15 per successful query

## Body parameters

<ParamField type="string" placeholder="USA">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `USA`
</ParamField>

<ParamField type="string" placeholder="usa_states_credit_bureau">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `usa_states_credit_bureau`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  Phone number in international format.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="123456789">
  `ssn` value required by this database service.

  Example: `123456789`
</ParamField>

<ParamField type="string" placeholder="john.doe@example.com">
  Email address.

  Example: `john.doe@example.com`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* `address` is optional for this service. You can send one complete `address` string and Didit will split it into structured address elements when possible, or you can send the structured fields explicitly.
* US Social Security Number or ITIN - full 9 digits (dashes optional) or only the last 4 digits
* `ssn` must match `(?:\d{9}|\d{3}-\d{2}-\d{4}|\d{4})`.
* For `ssn`, send either the full 9-digit SSN/ITIN (dashes optional) or only its last 4 digits.
* Beyond the required `first_name` and `last_name`, include at least one more field from `date_of_birth`, `address`, `phone`, `ssn`, or `email`. A name-only request is rejected before the provider lookup (and not charged); `date_of_birth` gives the most reliable match.
* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=USA" \
    -F "services=usa_states_credit_bureau" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "USA",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "usa_states_credit_bureau",
        "service_name": "United States of America - United States Credit Bureau",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "postal_code": "10001",
          "state": "Sample State",
          "street": "sample_value",
          "verifications": {
            "full_name": true
          }
        },
        "validation": {
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "USA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "usa_states_credit_bureau",
        "service_name": "United States of America - United States Credit Bureau",
        "source_data": {
          "full_name": "NO_MATCH"
        },
        "validation": {
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `usa_states_credit_bureau` currently documents this normalized shape:

* `address`
* `address_match_score`
* `city`
* `date_of_birth`
* `first_name`
* `full_name`
* `last_name`
* `name_match_score`
* `postal_code`
* `state`
* `street`

## Pricing & SLAs

United States of America - United States Credit Bureau queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.15 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [United States Database Validation overview](/api-reference/database-validation/united-states)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# United States of America - United States Death Check (SSDMF)
Source: https://docs.didit.me/api-reference/database-validation/united-states/death-check

POST /v3/database-validation/
The official Social Security Death Master File. Authoritative real-time identity lookup for United States. Real-time lookup, pay-per-call.

<div />

The official Social Security Death Master File. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 100%\*
* **Country:** United States
* **Service ID:** `usa_states_death_check`
* **Data domain:** Other
* **Category:** DeathRecord

## Inputs

| Field           | Required | Example      |
| --------------- | -------: | ------------ |
| `first_name`    |      Yes | `John`       |
| `last_name`     |      Yes | `Doe`        |
| `middle_name`   |       No | `Demo`       |
| `date_of_birth` |       No | `1990-01-01` |
| `ssn`           |       No | `123456789`  |
| `vendor_data`   |       No | `user-1234`  |

* **Required inputs:** `first_name`, `last_name`
* **Optional inputs:** `middle_name`, `date_of_birth`, `ssn`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** 100%\*
* **Price:** \$0.06 per successful query

## Body parameters

<ParamField type="string" placeholder="USA">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `USA`
</ParamField>

<ParamField type="string" placeholder="usa_states_death_check">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `usa_states_death_check`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="Demo">
  Middle name, when available.

  Example: `Demo`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="123456789">
  `ssn` value required by this database service.

  Example: `123456789`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* US Social Security Number or ITIN - full 9 digits (dashes optional) or only the last 4 digits
* `ssn` must match `(?:\d{9}|\d{3}-\d{2}-\d{4}|\d{4})`.
* For `ssn`, send either the full 9-digit SSN/ITIN (dashes optional) or only its last 4 digits.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=USA" \
    -F "services=usa_states_death_check" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "USA",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "usa_states_death_check",
        "service_name": "United States of America - United States Death Check (SSDMF)",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "verifications": {
            "full_name": true
          }
        },
        "validation": {
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "USA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "usa_states_death_check",
        "service_name": "United States of America - United States Death Check (SSDMF)",
        "source_data": {
          "full_name": "NO_MATCH"
        },
        "validation": {
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `usa_states_death_check` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `full_name`
* `last_name`
* `name_match_score`

## Pricing & SLAs

United States of America - United States Death Check (SSDMF) queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.06 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [United States Database Validation overview](/api-reference/database-validation/united-states)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# United States of America - United States Financial Services
Source: https://docs.didit.me/api-reference/database-validation/united-states/financial-services

POST /v3/database-validation/
Aggregated service of government and public records, background records, and other services. Authoritative real-time identity lookup for United States. Real-time lookup, pay-per-call.

<div />

Aggregated service of government and public records, background records, and other services. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 85%
* **Country:** United States
* **Service ID:** `usa_states_financial_services`
* **Data domain:** Financial
* **Category:** FinancialServices

## Inputs

| Field                 | Required | Example                |
| --------------------- | -------: | ---------------------- |
| `first_name`          |      Yes | `John`                 |
| `last_name`           |      Yes | `Doe`                  |
| `date_of_birth`       |      Yes | `1990-01-01`           |
| `address.street_1`    |       No | `123 Sample Street`    |
| `address.street_2`    |       No | `Unit 4`               |
| `address.city`        |       No | `Sample City`          |
| `address.region`      |       No | `Sample State`         |
| `address.postal_code` |       No | `10001`                |
| `phone`               |       No | `+15550101000`         |
| `ssn`                 |       No | `123456789`            |
| `email`               |       No | `john.doe@example.com` |
| `vendor_data`         |       No | `user-1234`            |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`
* **Optional inputs:** `address.street_1`, `address.street_2`, `address.city`, `address.region`, `address.postal_code`, `phone`, `ssn`, `email`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 85%
* **Price:** \$0.12 per successful query

## Body parameters

<ParamField type="string" placeholder="USA">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `USA`
</ParamField>

<ParamField type="string" placeholder="usa_states_financial_services">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `usa_states_financial_services`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  Phone number in international format.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="123456789">
  `ssn` value required by this database service.

  Example: `123456789`
</ParamField>

<ParamField type="string" placeholder="john.doe@example.com">
  Email address.

  Example: `john.doe@example.com`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* `address` is optional for this service. You can send one complete `address` string and Didit will split it into structured address elements when possible, or you can send the structured fields explicitly.
* US Social Security Number or ITIN - full 9 digits (dashes optional) or only the last 4 digits
* `ssn` must match `(?:\d{9}|\d{3}-\d{2}-\d{4}|\d{4})`.
* For `ssn`, send either the full 9-digit SSN/ITIN (dashes optional) or only its last 4 digits.
* This service requires `first_name`, `last_name`, and `date_of_birth`, which already meets the source's minimum of a name plus one more identity field. Optional fields (`ssn`, `address`, `phone`, `email`) further strengthen the match.
* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=USA" \
    -F "services=usa_states_financial_services" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "USA",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "usa_states_financial_services",
        "service_name": "United States of America - United States Financial Services",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "postal_code": "10001",
          "state": "Sample State",
          "street": "sample_value",
          "verifications": {
            "date_of_birth": true,
            "full_name": true
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "USA",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "usa_states_financial_services",
        "service_name": "United States of America - United States Financial Services",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "postal_code": "10001",
          "state": "Sample State",
          "street": "sample_value",
          "verifications": {
            "date_of_birth": true,
            "full_name": false
          }
        },
        "validation": {
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "USA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "usa_states_financial_services",
        "service_name": "United States of America - United States Financial Services",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `usa_states_financial_services` currently documents this normalized shape:

* `address`
* `address_match_score`
* `city`
* `date_of_birth`
* `first_name`
* `full_name`
* `last_name`
* `name_match_score`
* `postal_code`
* `state`
* `street`

## Pricing & SLAs

United States of America - United States Financial Services queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.12 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [United States Database Validation overview](/api-reference/database-validation/united-states)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# United States of America - United States Phone 2
Source: https://docs.didit.me/api-reference/database-validation/united-states/phone-2

POST /v3/database-validation/
Verifies input data to mobile network operators phone data. Authoritative real-time identity lookup for United States. Real-time lookup, pay-per-call.

<div />

Verifies input data to mobile network operators phone data. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** > 90%
* **Country:** United States
* **Service ID:** `usa_states_phone_2`
* **Data domain:** Telecom
* **Category:** Telecom

## Inputs

| Field                 | Required | Example             |
| --------------------- | -------: | ------------------- |
| `first_name`          |      Yes | `John`              |
| `last_name`           |      Yes | `Doe`               |
| `address.street_1`    |      Yes | `123 Sample Street` |
| `address.postal_code` |      Yes | `10001`             |
| `phone`               |      Yes | `+15550101000`      |
| `date_of_birth`       |       No | `1990-01-01`        |
| `ssn`                 |       No | `123456789`         |
| `address.street_2`    |       No | `Unit 4`            |
| `address.city`        |       No | `Sample City`       |
| `address.region`      |       No | `Sample State`      |
| `vendor_data`         |       No | `user-1234`         |

* **Required inputs:** `first_name`, `last_name`, `address.street_1`, `address.postal_code`, `phone`
* **Optional inputs:** `date_of_birth`, `ssn`, `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** > 90%
* **Price:** \$0.15 per successful query

## Body parameters

<ParamField type="string" placeholder="USA">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `USA`
</ParamField>

<ParamField type="string" placeholder="usa_states_phone_2">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `usa_states_phone_2`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  Phone number in international format.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="123456789">
  `ssn` value required by this database service.

  Example: `123456789`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* US Social Security Number (9 digits, with optional dashes)
* `ssn` must match `(?:\d{9}|\d{3}-\d{2}-\d{4})`.
* For `ssn`, send the full 9-digit SSN/ITIN (dashes optional). Unlike the US Credit Bureau and Financial Services checks, this service does not accept the last-4-digits form.
* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=USA" \
    -F "services=usa_states_phone_2" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}' \
    -F "phone=+15550101000"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "USA",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "usa_states_phone_2",
        "service_name": "United States of America - United States Phone 2",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "USA",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "usa_states_phone_2",
        "service_name": "United States of America - United States Phone 2",
        "source_data": {
          "address": "123 Sample Street",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "last_name": "Doe"
        },
        "validation": {
          "address": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "USA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "usa_states_phone_2",
        "service_name": "United States of America - United States Phone 2",
        "source_data": {
          "address": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `usa_states_phone_2` currently documents this normalized shape:

* `address`
* `date_of_birth`
* `first_name`
* `last_name`

## Pricing & SLAs

United States of America - United States Phone 2 queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.15 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [United States Database Validation overview](/api-reference/database-validation/united-states)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# United States of America - United States Residential
Source: https://docs.didit.me/api-reference/database-validation/united-states/residential

POST /v3/database-validation/
Aggregated service of government and public records, background records, and public professional profiles. Authoritative real-time identity lookup for United States. Real-time lookup, pay-per-call.

<div />

Aggregated service of government and public records, background records, and public professional profiles. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** \~ 90%
* **Country:** United States
* **Service ID:** `usa_states_residential`
* **Data domain:** Address
* **Category:** Residential

## Inputs

| Field                 | Required | Example                |
| --------------------- | -------: | ---------------------- |
| `first_name`          |      Yes | `John`                 |
| `last_name`           |      Yes | `Doe`                  |
| `date_of_birth`       |      Yes | `1990-01-01`           |
| `address.street_1`    |      Yes | `123 Sample Street`    |
| `address.postal_code` |      Yes | `10001`                |
| `phone`               |       No | `+15550101000`         |
| `ssn`                 |       No | `123456789`            |
| `email`               |       No | `john.doe@example.com` |
| `address.street_2`    |       No | `Unit 4`               |
| `address.city`        |       No | `Sample City`          |
| `address.region`      |       No | `Sample State`         |
| `vendor_data`         |       No | `user-1234`            |

* **Required inputs:** `first_name`, `last_name`, `date_of_birth`, `address.street_1`, `address.postal_code`
* **Optional inputs:** `phone`, `ssn`, `email`, `address.street_2`, `address.city`, `address.region`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** \~ 90%
* **Price:** \$0.60 per successful query

## Body parameters

<ParamField type="string" placeholder="USA">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `USA`
</ParamField>

<ParamField type="string" placeholder="usa_states_residential">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `usa_states_residential`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="object" placeholder="{&#x22;street_1&#x22;:&#x22;123 Sample Street&#x22;,&#x22;street_2&#x22;:&#x22;Unit 4&#x22;,&#x22;city&#x22;:&#x22;Sample City&#x22;,&#x22;region&#x22;:&#x22;Sample State&#x22;,&#x22;postal_code&#x22;:&#x22;10001&#x22;,&#x22;country&#x22;:&#x22;US&#x22;}">
  Structured residential address object. Use `street_1`, `street_2`, `city`, `region`, `postal_code`, and `country`. A complete legacy address string is still accepted but not recommended.

  Example: `{"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}`
</ParamField>

<ParamField type="string" placeholder="+15550101000">
  Phone number in international format.

  Example: `+15550101000`
</ParamField>

<ParamField type="string" placeholder="123456789">
  `ssn` value required by this database service.

  Example: `123456789`
</ParamField>

<ParamField type="string" placeholder="john.doe@example.com">
  Email address.

  Example: `john.doe@example.com`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* must be at least 2 characters long
* US Social Security Number (9 digits, with optional dashes)
* `ssn` must match `(?:\d{9}|\d{3}-\d{2}-\d{4})`.
* For `ssn`, send the full 9-digit SSN/ITIN (dashes optional). Unlike the US Credit Bureau and Financial Services checks, this service does not accept the last-4-digits form.
* For address services, send structured address fields instead of a single `address` string when possible.
* `address.street_1` is the street address, including street number and street type.
* `address.street_2` is apartment, unit, building, floor, or extra address line. Send it only when you have it.
* `address.city` is city, suburb, district, locality, or neighborhood.
* `address.region` is state, province, region, or town.
* `address.postal_code` is postcode or postal code.
* Address-based database services require at least street address and postal code; requests rejected before source lookup are not charged.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=USA" \
    -F "services=usa_states_residential" \
    -F "vendor_data=user-1234" \
    -F "first_name=John" \
    -F "last_name=Doe" \
    -F "date_of_birth=1990-01-01" \
    -F 'address={"street_1":"123 Sample Street","street_2":"Unit 4","city":"Sample City","region":"Sample State","postal_code":"10001","country":"US"}'
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "USA",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "usa_states_residential",
        "service_name": "United States of America - United States Residential",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "postal_code": "10001",
          "state": "Sample State",
          "street": "sample_value",
          "verifications": {
            "address": true,
            "date_of_birth": true,
            "full_name": true
          }
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "USA",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "usa_states_residential",
        "service_name": "United States of America - United States Residential",
        "source_data": {
          "address": "123 Sample Street",
          "address_match_score": "1.000",
          "city": "Sample City",
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "last_name": "Doe",
          "name_match_score": "1.000",
          "postal_code": "10001",
          "state": "Sample State",
          "street": "sample_value",
          "verifications": {
            "address": true,
            "date_of_birth": true,
            "full_name": false
          }
        },
        "validation": {
          "address": "full_match",
          "date_of_birth": "full_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "USA",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "usa_states_residential",
        "service_name": "United States of America - United States Residential",
        "source_data": {
          "address": "NO_MATCH",
          "date_of_birth": "NO_MATCH",
          "full_name": "NO_MATCH"
        },
        "validation": {
          "address": "no_match",
          "date_of_birth": "no_match",
          "full_name": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `usa_states_residential` currently documents this normalized shape:

* `address`
* `address_match_score`
* `city`
* `date_of_birth`
* `first_name`
* `full_name`
* `last_name`
* `name_match_score`
* `postal_code`
* `state`
* `street`

## Pricing & SLAs

United States of America - United States Residential queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.60 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [United States Database Validation overview](/api-reference/database-validation/united-states)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Uruguay - CI verification
Source: https://docs.didit.me/api-reference/database-validation/uruguay/cedula

POST /v3/database-validation/
Verifies Uruguayan Cédula data against Dirección Nacional del Registro de Estado Civil government records. Authoritative real-time identity lookup for Uruguay. Real-time lookup, pay-per-call.

<div />

Verifies Uruguayan Cédula data against Dirección Nacional del Registro de Estado Civil government records. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 90-95%
* **Country:** Uruguay
* **Service ID:** `ury_cedula`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field             | Required | Example      |
| ----------------- | -------: | ------------ |
| `personal_number` |      Yes | `1111111`    |
| `date_of_birth`   |      Yes | `1990-01-01` |
| `first_name`      |       No | `John`       |
| `last_name`       |       No | `Doe`        |
| `vendor_data`     |       No | `user-1234`  |

* **Required inputs:** `personal_number`, `date_of_birth`
* **Optional inputs:** `first_name`, `last_name`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** 90-95%
* **Price:** \$0.20 per successful query

## Body parameters

<ParamField type="string" placeholder="URY">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `URY`
</ParamField>

<ParamField type="string" placeholder="ury_cedula">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `ury_cedula`
</ParamField>

<ParamField type="string" placeholder="1111111">
  Country-specific personal identity number.

  Example: `1111111`
</ParamField>

<ParamField type="string" placeholder="1990-01-01">
  Date of birth in `YYYY-MM-DD` format.

  Example: `1990-01-01`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Uruguayan CI (7-9 digits)
* `personal_number` must contain digits only; remove spaces, hyphens, and punctuation before sending the request.
* `personal_number` must be 7-9 characters long.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=URY" \
    -F "services=ury_cedula" \
    -F "vendor_data=user-1234" \
    -F "personal_number=1111111" \
    -F "date_of_birth=1990-01-01"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "URY",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "ury_cedula",
        "service_name": "Uruguay - CI verification",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "full_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`PARTIAL_MATCH`** — The identification number was found but one or more personal fields (usually name or date of birth) did not fully match.

  ```json 200 OK — PARTIAL_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "In Review",
    "issuing_state": "URY",
    "match_type": "partial_match",
    "validations": [
      {
        "outcome_code": "PARTIAL_MATCH",
        "service_id": "ury_cedula",
        "service_name": "Uruguay - CI verification",
        "source_data": {
          "date_of_birth": "1990-01-01",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "date_of_birth": "no_match",
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "URY",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "ury_cedula",
        "service_name": "Uruguay - CI verification",
        "source_data": {
          "date_of_birth": "NO_MATCH",
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "date_of_birth": "no_match",
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `ury_cedula` currently documents this normalized shape:

* `date_of_birth`
* `first_name`
* `full_name`
* `identification_number`
* `last_name`

## Pricing & SLAs

Uruguay - CI verification queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.20 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Uruguay Database Validation overview](/api-reference/database-validation/uruguay)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Venezuela - Cédula verification
Source: https://docs.didit.me/api-reference/database-validation/venezuela/cedula

POST /v3/database-validation/
Verifies Venezuelan Cédula data against CNE electoral registry records. Authoritative real-time identity lookup for Venezuela. Real-time lookup, pay-per-call.

<div />

Verifies Venezuelan Cédula data against CNE electoral registry records. Didit exposes this service through `POST /v3/database-validation/` so you can verify the submitted data against the authoritative source and receive normalized match results.

## Coverage

* **Coverage:** 90-95%
* **Country:** Venezuela
* **Service ID:** `ven_cedula`
* **Data domain:** Identity
* **Category:** NationalIDRegistry

## Inputs

| Field             | Required | Example            |
| ----------------- | -------: | ------------------ |
| `document_number` |      Yes | `SAMPLE-DOC-12345` |
| `first_name`      |       No | `John`             |
| `last_name`       |       No | `Doe`              |
| `vendor_data`     |       No | `user-1234`        |

* **Required inputs:** `document_number`
* **Optional inputs:** `first_name`, `last_name`, `vendor_data`
* **Consent:** Not required
* **Workflow availability:** Available in workflow
* **Coverage:** 90-95%
* **Price:** \$0.20 per successful query

## Body parameters

<ParamField type="string" placeholder="VEN">
  ISO 3166-1 alpha-3 country code for this database service.

  Example: `VEN`
</ParamField>

<ParamField type="string" placeholder="ven_cedula">
  Array containing this service ID. Pinning the service keeps the request scoped to this exact database.

  Example: `ven_cedula`
</ParamField>

<ParamField type="string" placeholder="SAMPLE-DOC-12345">
  Document number extracted from or provided by the user.

  Example: `SAMPLE-DOC-12345`
</ParamField>

<ParamField type="string" placeholder="John">
  Given name to validate.

  Example: `John`
</ParamField>

<ParamField type="string" placeholder="Doe">
  Family name to validate.

  Example: `Doe`
</ParamField>

<ParamField type="string" placeholder="user-1234">
  Your stable user reference for this person, such as your internal user ID. Didit uses it to link standalone checks to the same end user and reduce duplicate-detection noise.

  Example: `user-1234`
</ParamField>

## Input rules & validation notes

* Venezuelan Cédula (7-10 digits, optional V/E prefix)
* `document_number` must be 7-12 characters long.
* `document_number` must match `[VvEe]?-?\d{7,10}`.

## How to call it

<RequestExample>
  ```bash cURL theme={null}
  curl -X POST "https://verification.didit.me/v3/database-validation/" \
    -H "x-api-key: YOUR_API_KEY" \
    -F "issuing_state=VEN" \
    -F "services=ven_cedula" \
    -F "vendor_data=user-1234" \
    -F "document_number=SAMPLE-DOC-12345"
  ```
</RequestExample>

<ResponseExample>
  Every successful call returns HTTP `200`. The **`outcome_code`** field tells you what actually happened — distinguishing, for example, a real biometric mismatch (`BIOMETRIC_NO_MATCH`) from a selfie that could not be read (`BIOMETRIC_IMAGE_UNUSABLE`). The `status` shown is the default feature status; your configured [Partial Match / No Match actions](/core-technology/database-validation/database-validation-warnings) can override it.

  **`MATCH`** — The registry confirmed the identity and every checked field matched.

  ```json 200 OK — MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Approved",
    "issuing_state": "VEN",
    "match_type": "full_match",
    "validations": [
      {
        "outcome_code": "MATCH",
        "service_id": "ven_cedula",
        "service_name": "Venezuela - Cédula verification",
        "source_data": {
          "document_type": "sample_value",
          "first_name": "John",
          "full_name": "John Doe",
          "identification_number": "SAMPLE-ID-12345",
          "last_name": "Doe"
        },
        "validation": {
          "identification_number": "full_match"
        }
      }
    ]
  }
  ```

  **`NO_MATCH`** — The registry returned no match for the submitted data.

  ```json 200 OK — NO_MATCH theme={null}
  {
    "request_id": "req_01H…",
    "status": "Declined",
    "issuing_state": "VEN",
    "match_type": "no_match",
    "validations": [
      {
        "outcome_code": "NO_MATCH",
        "service_id": "ven_cedula",
        "service_name": "Venezuela - Cédula verification",
        "source_data": {
          "identification_number": "NO_MATCH"
        },
        "validation": {
          "identification_number": "no_match"
        }
      }
    ]
  }
  ```
</ResponseExample>

## Returned data

The exact fields surfaced in `source_data` depend on what the registry returns. The generated example for `ven_cedula` currently documents this normalized shape:

* `document_type`
* `first_name`
* `full_name`
* `identification_number`
* `last_name`

## Pricing & SLAs

Venezuela - Cédula verification queries are billed only when Didit receives a conclusive result from the validation source.

* **Per-call price:** \$0.20 USD.
* **Billing:** per successful query. You are not charged when the registry is unreachable, when required fields are missing, or when the request is rejected before reaching the source.
* **Latency:** typical p95 \< 2 s.
* **Availability:** 99.9% per quarter on Didit's side; downstream source availability varies by country and dataset.

## Continue reading

* [Venezuela Database Validation overview](/api-reference/database-validation/venezuela)
* [Database Validation overview](/core-technology/database-validation/overview)
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes)


# Healthcheck
Source: https://docs.didit.me/api-reference/healthcheck

openapi-healthcheck.json GET /system/healthcheck
Public unauthenticated liveness probe. Returns `HTTP 200` with `{status: "ok", timestamp}` when service, DB, cache, and broker are healthy.

<AgentPromptAccordion title="Healthcheck Prompt" />


# API Reference
Source: https://docs.didit.me/api-reference/overview

Complete REST API reference for Didit identity verification. Sessions, standalone endpoints, management API, and OpenAPI spec. Pay-per-use pricing.

<AgentPromptAccordion title="Standalone API Integration Prompt" />

Didit offers **two complementary approaches** to identity verification. Understanding the difference is essential for choosing the right integration for your use case.

<FeatureGrid>
  <FeatureCard icon="browser" title="Hosted Sessions" description="Full verification flows with a pre-built, optimized UI. Users interact with Didit's hosted interface via redirect, iframe, or native SDK." href="/sessions-api/create-session" />

  <FeatureCard icon="server" title="Standalone APIs" description="Direct server-to-server API calls. You send data (images, documents, names) and receive structured verification results — no end-user UI involved." href="/standalone-apis/id-verification" />
</FeatureGrid>

***

## Hosted Sessions (Recommended for User-Facing Flows)

Hosted sessions are the **recommended approach** for most integrations. When you create a session, Didit generates a `verification_url` that you present to your user. The user completes the entire verification flow in Didit's optimized interface, and you receive the results via webhook or API.

### How It Works

<Steps>
  <Step title="Create Session">
    Your server calls `POST /v3/session/` with a workflow ID. Didit returns a `verification_url` and `session_token`.
  </Step>

  <Step title="Present to User">
    Redirect the user, embed via iframe, or initialize a native SDK using the session token.
  </Step>

  <Step title="User Completes Verification">
    The user follows the guided flow in Didit's optimized UI — ID capture, liveness, and any additional steps.
  </Step>

  <Step title="Receive Results">
    Didit sends a webhook to your server with the verification decision, or you poll via the retrieve API.
  </Step>
</Steps>

### Why Sessions Are Recommended

| Advantage                   | Details                                                                                         |
| --------------------------- | ----------------------------------------------------------------------------------------------- |
| **Optimized UX**            | The verification interface is continuously A/B tested globally for the highest completion rates |
| **Camera handling**         | Smart camera selection, auto-capture, quality checks, and device compatibility built in         |
| **Guided flow**             | Step-by-step instructions, real-time feedback, and error recovery for the user                  |
| **Multi-feature workflows** | Chain multiple features (ID + Liveness + AML + Phone + Email) in a single flow                  |
| **Security**                | Anti-spoofing, active liveness detection, and device fingerprinting embedded in the flow        |
| **Compliance**              | Session-level audit trails, consent capture, and data retention policies handled automatically  |
| **Localization**            | 49 languages with automatic browser detection                                                   |
| **Mobile-native**           | Native SDKs for iOS, Android, React Native, and Flutter                                         |
| **No maintenance**          | Didit handles all UI updates, browser/device bugs, and camera edge cases                        |

### When to Use Sessions

* **User onboarding / KYC** — New users sign up and need to verify their identity
* **Age verification** — Confirm users meet minimum age requirements
* **Re-verification** — Periodically re-verify existing users
* **Biometric authentication** — Users authenticate with their face for sensitive actions
* **Multi-step compliance** — Flows requiring ID + Liveness + AML + Phone in one go
* **Any scenario where the end user is present** and interacts directly

### Session Endpoints

| Endpoint                                            | Purpose                                                |
| --------------------------------------------------- | ------------------------------------------------------ |
| [Create Session](/sessions-api/create-session)      | Generate a verification URL for a user                 |
| [Retrieve Session](/sessions-api/retrieve-session)  | Get the full results and decision for a session        |
| [List Sessions](/sessions-api/list-sessions)        | Query and filter all sessions                          |
| [Delete Session](/sessions-api/delete-session)      | Remove a session and all associated data               |
| [Generate PDF](/sessions-api/generate-pdf)          | Export a verification report as PDF                    |
| [Share Session](/sessions-api/share-session/share)  | Generate a share token for Reusable KYC with a partner |
| [Import Shared](/sessions-api/share-session/import) | Import a session shared by a partner (Reusable KYC)    |

***

## Standalone APIs (For Server-to-Server Processing)

Standalone APIs let you call individual verification features **directly from your server** without any end-user UI. You send the data (images, documents, names) and receive structured results.

### How It Works

<Steps>
  <Step title="Send Data">
    Your server calls a standalone endpoint (e.g., `POST /v3/id-verification/`) with the required data — images, documents, or JSON fields.
  </Step>

  <Step title="Receive Results">
    Didit processes the request synchronously and returns structured verification results in the response.
  </Step>
</Steps>

### When to Use Standalone APIs

| Use Case                              | Example                                                                           |
| ------------------------------------- | --------------------------------------------------------------------------------- |
| **Backend processing**                | You already have document images from your own capture UI and need to verify them |
| **Batch verification**                | Processing bulk identity documents uploaded by an operations team                 |
| **Custom UX**                         | You've built your own capture flow and want to use Didit only for the analysis    |
| **Server-to-server checks**           | AML screening a list of customers, without any user interaction                   |
| **Automated pipelines**               | CI/CD or cron-based compliance re-checks (e.g., daily AML monitoring)             |
| **Integration with existing systems** | Connecting Didit's verification to your existing document management system       |
| **Single-feature calls**              | You only need one feature (e.g., just AML screening or just face matching)        |

### Available Standalone APIs

**Identity & Documents**

| API                                                                  | What It Does                                                               |
| -------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| [ID Verification](/standalone-apis/id-verification)                  | Extract and validate data from ID documents (front + back images)          |
| [Proof of Address](/standalone-apis/proof-of-address)                | Verify address documents (utility bills, bank statements, government docs) |
| [Database Validation](/core-technology/database-validation/overview) | Cross-check user data against government databases                         |

**Document AI**

| API                                         | What It Does                                                                                            |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
| [Document AI](/standalone-apis/document-ai) | Extract the fields you define from any document (PDF or image), with name matching and tampering checks |

**Biometrics & Face**

| API                                                   | What It Does                                                        |
| ----------------------------------------------------- | ------------------------------------------------------------------- |
| [Passive Liveness](/standalone-apis/passive-liveness) | Verify a real person is present (anti-spoofing) from a single image |
| [Face Match](/standalone-apis/face-match)             | Compare two faces to determine if they are the same person          |
| [Face Search](/standalone-apis/face-search)           | Search for a face across all previously verified sessions (1:N)     |
| [Age Estimation](/standalone-apis/age-estimation)     | Estimate a person's age from a facial image                         |

**Compliance & Risk**

| API                                             | What It Does                                                       |
| ----------------------------------------------- | ------------------------------------------------------------------ |
| [AML Screening](/standalone-apis/aml-screening) | Screen persons or companies against sanctions, PEP, and watchlists |

**Business Verification (KYB)**

| API                                                         | What It Does                                                                                             |
| ----------------------------------------------------------- | -------------------------------------------------------------------------------------------------------- |
| [KYB Registry Search](/standalone-apis/kyb-registry-search) | Search company registries by name, registration number, and country; up to \$0.50 per successful request |
| [KYB Registry Select](/standalone-apis/kyb-registry-select) | Retrieve the full registry profile (officers, beneficial owners, addresses) for a selected company       |

***

## Side-by-Side Comparison

|                         | Hosted Sessions                       | Standalone APIs                                 |
| ----------------------- | ------------------------------------- | ----------------------------------------------- |
| **Integration effort**  | Low — redirect, iframe, or SDK        | Medium — you handle data capture and submission |
| **User interaction**    | Yes — user completes flow in Didit UI | No — server-to-server only                      |
| **Camera/capture**      | Handled by Didit (optimized)          | You provide the images/data                     |
| **Multi-feature flows** | Yes — chain features in a workflow    | One feature per API call                        |
| **UX optimization**     | Continuously A/B tested               | You control the UX                              |
| **Localization**        | 49 languages, auto-detected           | N/A (no UI)                                     |
| **Webhooks**            | Automatic status notifications        | N/A (synchronous response)                      |
| **Response time**       | Async (user completes at their pace)  | Synchronous (seconds)                           |
| **Best for**            | User-facing onboarding & verification | Backend processing & automation                 |
| **Console visibility**  | Full session lifecycle in dashboard   | Appears in Manual Checks section                |

***

## Can I Use Both?

**Yes.** Many teams combine both approaches:

1. **Sessions for onboarding** — New users go through the full hosted verification flow during sign-up
2. **Standalone AML for ongoing monitoring** — A cron job re-screens all approved users nightly against updated watchlists
3. **Standalone Face Search for duplicate detection** — When a new session is approved, your server calls Face Search to check for duplicates
4. **Standalone ID Verification for operations** — Your compliance team uploads documents manually for edge-case reviews

### Example: Combined Architecture

| Your Application             | Didit API                      | Type             |
| ---------------------------- | ------------------------------ | ---------------- |
| **User sign-up flow**        | Sessions API (hosted UI)       | User-facing      |
| **Nightly AML re-screening** | Standalone AML API             | Server-to-server |
| **Ops team document review** | Standalone ID Verification API | Server-to-server |
| **Duplicate face detection** | Standalone Face Search API     | Server-to-server |

***

## Getting Started

<FeatureGrid>
  <FeatureCard icon="rocket" title="Quick Start with Sessions" description="Create your first hosted verification session in 5 minutes." href="/integration/api-full-flow" />

  <FeatureCard icon="key" title="API Authentication" description="Get your API key and start making authenticated requests." href="/getting-started/api-authentication" />

  <FeatureCard icon="webhook" title="Set Up Webhooks" description="Receive real-time notifications when verification status changes." href="/integration/webhooks" />

  <FeatureCard icon="diagram-project" title="Create a Workflow" description="Build custom verification flows in the Business Console." href="/console/workflows" />
</FeatureGrid>

***


# Create Application
Source: https://docs.didit.me/auth-api/create-application

POST /organizations/me/{org_id}/applications/
Create an application inside an organization. The response includes `api_key`; persist it now (recoverable via GET). Requires owner/admin JWT.

<AgentPromptAccordion title="Create Application Prompt" />

Use this endpoint when you need to separate verification traffic, credentials, branding, or reporting inside the same organization.

This is especially useful for **resellers** that create one application per customer. It also works well when your own company has multiple products, brands, regions, staging/production environments, or use cases that should not share the same API key and application-level settings.

<Note>
  All Auth API endpoints use `https://apx.didit.me/auth/v2`. Use the returned `api_key` as `x-api-key` when calling `https://verification.didit.me/v3/...` endpoints such as sessions and workflows.
</Note>


# Get Application Credentials
Source: https://docs.didit.me/auth-api/get-credentials

GET /organizations/me/{org_id}/applications/{app_id}/
Read one application's full record including `client_id` and `api_key`. Use this to recover a lost `api_key`.

<AgentPromptAccordion title="Get Application Credentials Prompt" />


# Programmatic Login
Source: https://docs.didit.me/auth-api/login

POST /programmatic/login/
Authenticate any verified email/password Didit account and receive an RS256 JWT pair (default lifetime 86400s). Console-created email/password accounts can use this endpoint; OAuth-only console accounts must set a password first.

<AgentPromptAccordion title="Programmatic Login Prompt" />


# Register Account
Source: https://docs.didit.me/auth-api/register

POST /programmatic/register/
Step 1 of programmatic onboarding. Creates a pending account and emails a 6-char code (10 min TTL). Rate limit: 5/IP/hour.

<AgentPromptAccordion title="Programmatic Register Prompt" />


# Update Application
Source: https://docs.didit.me/auth-api/update-application

PATCH /organizations/me/{org_id}/applications/{app_id}/
Update application metadata (name, URLs, redirect URIs). `api_key` and `client_id` are never rotated. Requires owner/admin JWT.

<AgentPromptAccordion title="Update Application Prompt" />

Use this endpoint to keep each application aligned with the customer, brand, environment, or internal use case it represents.

For resellers, this lets you rename or update each customer application without sharing credentials across customers. For direct customers, it helps separate products, regions, or environments while keeping everything under one organization.

<Note>
  This endpoint updates application metadata. The `api_key` stays the same unless you rotate credentials separately.
</Note>


# Verify Email & Get Credentials
Source: https://docs.didit.me/auth-api/verify-email

POST /programmatic/verify-email/
Step 2 of onboarding. Exchanges the 6-char code for a verified account, a default org+app, and a JWT pair. Persist the returned `api_key`.

<AgentPromptAccordion title="Verify Email & Get Credentials Prompt" />


# Business AML Screening
Source: https://docs.didit.me/business-verification/aml

Screen companies, UBOs, and officers against global sanctions, PEP, and watchlist databases. Entity AML included; $0.20 per person. No contracts.

Business verification includes AML screening at two levels: the **company entity** and all **identified individuals** (beneficial owners and officers). This ensures comprehensive compliance coverage.

The same two-score system used in user verification applies — see [AML screening overview](/core-technology/aml-screening/overview), [risk score](/core-technology/aml-screening/aml-risk-score), and [match score](/core-technology/aml-screening/aml-match-score) for the underlying model.

## Company-level AML

The company itself is screened against global watchlists as a legal entity:

| Check                      | Description                                                                       |
| -------------------------- | --------------------------------------------------------------------------------- |
| **Sanctions**              | International and national sanctions lists (OFAC, EU, UN, etc.)                   |
| **Regulatory enforcement** | Regulatory warnings, fines, and enforcement actions                               |
| **Adverse media**          | News articles about financial crime, fraud, or legal issues involving the company |

Company AML uses the same [two-score risk system](/core-technology/aml-screening/overview) as user verification:

* **Match score** — how confident the system is that the match refers to the same entity
* **Risk score** — how risky the matched entity is based on the category, country, and severity

Company-level screening produces:

| Field                     | Description                                    |
| ------------------------- | ---------------------------------------------- |
| `company_aml_score`       | Overall AML risk score for the company (0–100) |
| `company_aml_total_hits`  | Total number of watchlist matches found        |
| `company_aml_screened_at` | Timestamp of the most recent screening         |

## Person-level AML

Every identified beneficial owner and officer is individually screened against:

| Check                 | Description                                                                            |
| --------------------- | -------------------------------------------------------------------------------------- |
| **Sanctions**         | Individual sanctions across all major lists                                            |
| **PEP**               | Politically Exposed Persons at all levels (heads of state through to close associates) |
| **Criminal records**  | Global and local criminal databases                                                    |
| **Adverse media**     | News articles mentioning the individual in connection with financial crime             |
| **Fitness & probity** | Financial regulator fitness and probity registers                                      |

## Screening flow

<Steps>
  <Step title="Data extraction" icon="file-lines">
    Company name, registration number, country, and all identified persons are extracted from the registry lookup.
  </Step>

  <Step title="Company screening" icon="building">
    The company entity is screened against corporate sanctions, regulatory enforcement, and adverse media databases.
  </Step>

  <Step title="Person screening" icon="users">
    Each beneficial owner and officer is screened individually against PEP, sanctions, criminal, and adverse media databases.
  </Step>

  <Step title="Score and classify" icon="calculator">
    Each match receives a match score and risk score. Matches below the match score threshold are classified as false positives. Remaining matches determine the AML status.
  </Step>

  <Step title="Aggregate results" icon="chart-simple">
    The business session's overall AML status reflects the highest-risk result across the company and all screened individuals.
  </Step>
</Steps>

## Configuration

AML screening for business verification uses the same configurable thresholds as user verification:

| Setting                   | Description                                                                                   |
| ------------------------- | --------------------------------------------------------------------------------------------- |
| **Match score threshold** | Below this threshold, matches are auto-classified as false positives                          |
| **Approve threshold**     | Risk scores below this value result in an Approved AML status                                 |
| **Review threshold**      | Risk scores above this value result in a Declined AML status; between thresholds is In Review |

These thresholds can be set per workflow in the Business Console.

## Ongoing monitoring

If ongoing AML monitoring is enabled, all screened entities (company and individuals) are re-screened daily against updated watchlists. Any new matches trigger a webhook notification so your compliance team can take action.

### Enabling ongoing monitoring

Toggle ongoing monitoring per business session from the [Business Console](/business-verification/console) or via the API:

| Setting                         | Description                                            |
| ------------------------------- | ------------------------------------------------------ |
| `is_ongoing_monitoring_enabled` | Enable or disable daily re-screening for this business |
| `last_aml_bill_date`            | Timestamp of the most recent billed screening cycle    |

When enabled, Didit re-screens the company entity and all identified individuals against updated watchlists. New or changed matches generate a `data.updated` webhook event with `session_kind: "business"` (or `business.data.updated` when the entity profile changes).

<Note>
  Ongoing monitoring incurs a per-screening fee for each monitoring cycle. Review your billing settings to understand the cost impact before enabling monitoring across all business sessions.
</Note>

## Next steps

<CardGroup>
  <Card title="AML overview" icon="shield-check" href="/core-technology/aml-screening/overview">
    Two-score system, watchlists, thresholds.
  </Card>

  <Card title="Business AML coverage" icon="database" href="/business-verification/aml-coverage">
    Sanctions, watchlists, and insolvency sources used at the company level.
  </Card>

  <Card title="Continuous monitoring" icon="arrows-rotate" href="/core-technology/aml-screening/continuous-monitoring-aml-screening">
    Ongoing rescans and webhook events.
  </Card>
</CardGroup>


# AML Coverage
Source: https://docs.didit.me/business-verification/aml-coverage

Global sanctions, regulatory watchlists, and insolvency registers powering Didit's KYB AML screening across 220+ countries. Pay-per-call, no contracts.

Didit's business AML screening leverages a curated set of global publishers tailored to **legal entities**: international sanctions regimes, national regulatory watchlists, and insolvency / bankruptcy registers. Company-level matches surface alongside person-level matches for beneficial owners and officers — see the [AML screening page](/business-verification/aml) for how the two layers combine.

### 1. **Sanctions Screening**

We maintain up‑to‑date coverage of all major **multilateral sanctions, debarment, and exclusion lists** published by international organizations and development banks, including:

* **United Nations Security Council** consolidated list
* **European Union** consolidated financial sanctions and travel-ban lists
* **Multilateral development banks** (World Bank, ADB, AIIB, IDB, AfDB, EBRD, EIB, CDB) debarment / ineligibility registers
* **Specialized international watchlists** (IOSCO investor alerts, EU Air Safety List, Uyghur Human Rights Project)

### 2. **Regulatory & Enforcement Watchlists**

We screen against **government and regulatory watchlists** published by national authorities responsible for financial markets, trade, transport, energy, and consumer protection. Coverage spans agencies in the United States, Canada, Colombia, and Brazil — including securities regulators, central banks, antitrust authorities, customs and trade bodies, and procurement registries.

### 3. **Insolvency & Bankruptcy Registers**

We flag companies listed in **official insolvency, bankruptcy, and liquidation registers** across multiple jurisdictions, including India (IBBI), China's National Enterprise Bankruptcy Information Disclosure Platform, U.S. federal and state insurance guaranty associations, the FDIC, German insolvency announcements, the Polish court-business monitor, and similar registers in Australia, Chile, Indonesia, Brazil, and Belgium.

***

### Granular Taxonomy & Structured Metadata

Every match is enriched with structured metadata to aid remediation and risk prioritization:

* **Categorization**: primary categories (Sanctions, Watchlists, Insolvency) and publisher-level subcategories
* **Identifiers**: company name, registration number, jurisdiction
* **Other fields**: aliases, addresses, listing date, source URL

This ensures easy filtering and supports detailed differential risk workflows.

***

## Summary Table

| **Risk Category**         | **Key Coverage**                                                                                  |
| ------------------------- | ------------------------------------------------------------------------------------------------- |
| **Sanctions**             | UN, EU, OFAC, World Bank, ADB, AIIB, IDB, AfDB, EBRD, EIB, IOSCO, EU Air Safety List              |
| **Regulatory Watchlists** | Securities regulators, central banks, trade authorities, antitrust bodies, procurement registries |
| **Insolvency Registers**  | National bankruptcy boards, deposit insurance corporations, court insolvency monitors             |

***

### Sanctions

Below is a table of the international sanctions lists included in our business AML screening process:

| Publisher                                                                       | Country          | Category  |
| ------------------------------------------------------------------------------- | ---------------- | --------- |
| Anti-Corruption Foundation (ACF International) — Sanctions Tracker              | 🌐 International | Sanctions |
| Solomon Islands Government-Ministry of Commerce, Industry, Labour & Immigration | 🌐 International | Sanctions |
| European Investment Bank - Exclusions                                           | 🌐 International | Sanctions |
| Caribbean Development Bank - Sanctions                                          | 🌐 International | Sanctions |
| European National Bank - Supervisory Sanctions                                  | 🌐 International | Sanctions |
| Uyghur Human Rights Project - Sanctions                                         | 🌐 International | Sanctions |
| EU Sanctions - Consolidated List of Travel Bans                                 | 🌐 International | Sanctions |
| EU Consolidated Sanctions                                                       | 🌐 International | Sanctions |
| Inter-American Development Bank (IDB) - Sanctioned Firms                        | 🌐 International | Sanctions |
| Asian Infrastructure Investment Bank - Debarment List                           | 🌐 International | Sanctions |
| United Nations Security Council - Consolidated List                             | 🌐 International | Sanctions |
| European Commission - The EU Air Safety List                                    | 🌐 International | Sanctions |
| Asian Development bank - Sanction List                                          | 🌐 International | Sanctions |
| European Bank for Reconstruction and Development - Ineligible Entities          | 🌐 International | Sanctions |
| African Development Bank - Debarred Entities                                    | 🌐 International | Sanctions |
| European Union - Consolidated List of EU Financial Sanctions                    | 🌐 International | Sanctions |
| International Organization of Securities Commission - Investor Alerts Portal    | 🌐 International | Sanctions |
| The World Bank - Debarred Firms and Individuals                                 | 🌐 International | Sanctions |

<p>
  18 sources across 1 jurisdiction
</p>

### Regulatory Watchlists

Below is a table of the regulatory and enforcement watchlists included in our business AML screening process:

| Publisher                                                          | Country            | Category   |
| ------------------------------------------------------------------ | ------------------ | ---------- |
| Office of Foreign Assets Control                                   | 🇺🇸 United States | Watchlists |
| Federal Trade Commission                                           | 🇺🇸 United States | Watchlists |
| International Trade Administration, U.S. Department of Commerce    | 🇺🇸 United States | Watchlists |
| U.S Securities and Exchange Commission                             | 🇺🇸 United States | Watchlists |
| Federal Reserve Bank                                               | 🇺🇸 United States | Watchlists |
| Food and Drug Administration                                       | 🇺🇸 United States | Watchlists |
| Federal Energy Regulatory Commission                               | 🇺🇸 United States | Watchlists |
| Transport Canada                                                   | 🇨🇦 Canada        | Watchlists |
| Ontario Securities Commission                                      | 🇨🇦 Canada        | Watchlists |
| BC Securities Commission                                           | 🇨🇦 Canada        | Watchlists |
| Government of Canada                                               | 🇨🇦 Canada        | Watchlists |
| Canadian Transportation Agency                                     | 🇨🇦 Canada        | Watchlists |
| Canada Energy Regulator                                            | 🇨🇦 Canada        | Watchlists |
| Superintendency of Industry and Commerce                           | 🇨🇴 Colombia      | Watchlists |
| National Directorate of Taxes and Customs                          | 🇨🇴 Colombia      | Watchlists |
| Office of the Attorney General; Republic of Colombia               | 🇨🇴 Colombia      | Watchlists |
| Superintendency of the Solidarity Economy                          | 🇨🇴 Colombia      | Watchlists |
| Superintendence of Ports and Transport                             | 🇨🇴 Colombia      | Watchlists |
| Judicial Branch; Superior Council of the Judiciary                 | 🇨🇴 Colombia      | Watchlists |
| Comptroller General of Santander                                   | 🇨🇴 Colombia      | Watchlists |
| Secop Electronic Public Procurement System                         | 🇨🇴 Colombia      | Watchlists |
| Ministry of Justice and Public Security                            | 🇧🇷 Brazil        | Watchlists |
| National Electric Energy Agency                                    | 🇧🇷 Brazil        | Watchlists |
| National Civil Aviation Agency                                     | 🇧🇷 Brazil        | Watchlists |
| Administrative Council for Economic Defense                        | 🇧🇷 Brazil        | Watchlists |
| Brazilian Institute of Environment and Renewable Natural Resources | 🇧🇷 Brazil        | Watchlists |
| Securities and Exchange Commission of Brazil                       | 🇧🇷 Brazil        | Watchlists |
| Federal Government of Brazil                                       | 🇧🇷 Brazil        | Watchlists |
| Public Ministry of the State of Minas Gerais                       | 🇧🇷 Brazil        | Watchlists |
| Labor Public Ministry                                              | 🇧🇷 Brazil        | Watchlists |

<p>
  30 sources across 4 countries
</p>

### Insolvency Registers

Below is a table of the insolvency, bankruptcy, and liquidation registers included in our business AML screening process:

| Publisher                                                                | Country            | Category   |
| ------------------------------------------------------------------------ | ------------------ | ---------- |
| Insolvency and Bankruptcy Board of India (IBBI)                          | 🇮🇳 India         | Insolvency |
| China National Enterprise Bankruptcy Information Disclosure Platform     | 🇨🇳 China         | Insolvency |
| U.S Securities and Exchange Commission                                   | 🇺🇸 United States | Insolvency |
| Bankrupt Companies in the United States                                  | 🇺🇸 United States | Insolvency |
| National Organization of Life and Health Insurance Guaranty Associations | 🇺🇸 United States | Insolvency |
| Arkansas Life and Health Insurance Guaranty Association                  | 🇺🇸 United States | Insolvency |
| Florida Office of Insurance Regulation                                   | 🇺🇸 United States | Insolvency |
| Florida Insurance Guaranty Association                                   | 🇺🇸 United States | Insolvency |
| Des Moines Register                                                      | 🇺🇸 United States | Insolvency |
| New York Liquidation Bureau (NYLB)                                       | 🇺🇸 United States | Insolvency |
| North Carolina Insurance Guaranty Association                            | 🇺🇸 United States | Insolvency |
| Federal Deposit Insurance Corporation (FDIC)                             | 🇺🇸 United States | Insolvency |
| Indonesia Deposit Insurance Corporation - Bank Liquidation               | 🇮🇩 Indonesia     | Insolvency |
| Central Bank - Liquidated Companies                                      | 🇧🇷 Brazil        | Insolvency |
| German Insolvency Register - insolvenzbekanntmachungen                   | 🇩🇪 Germany       | Insolvency |
| BORSE-Frankfurt                                                          | 🇩🇪 Germany       | Insolvency |
| Insolvenz Radar                                                          | 🇩🇪 Germany       | Insolvency |
| Internetowy Monitor Sądowy Gospodarczy                                   | 🇵🇱 Poland        | Insolvency |
| Australian Financial Security Authority - Bankruptcy Register            | 🇦🇺 Australia     | Insolvency |
| Chile The Superintendency of Insolvency and Re-entrepreneurship          | 🇨🇱 Chile         | Insolvency |
| American Bankruptcy Institute Global Insolvency                          | 🇧🇪 Belgium       | Insolvency |

<p>
  21 sources across 9 countries
</p>

***

## Next steps

<CardGroup>
  <Card title="Business AML screening" icon="shield-check" href="/business-verification/aml">
    How company and person-level AML are combined.
  </Card>

  <Card title="User AML coverage" icon="database" href="/core-technology/aml-screening/watchlist-database-aml-screening">
    Full person-level watchlist coverage reference.
  </Card>

  <Card title="Continuous monitoring" icon="arrows-rotate" href="/core-technology/aml-screening/continuous-monitoring-aml-screening">
    Ongoing rescans and webhook events.
  </Card>
</CardGroup>


# Business Profiles
Source: https://docs.didit.me/business-verification/business-profiles

Track verified companies across sessions with auto-created profiles, status management, tags, bulk ops, and CSV import/export. From $2.00 per check, priced per country and tier.

Didit automatically creates a business profile for each company you verify, aggregating verification data and session history into a single entity. Business profiles provide a unified view of each company across all their verification sessions.

<Note>
  Business profiles are the KYB-specific surface of the more general **Business entity** model. For the full entity model — operations, key-people linking to Users, blocklist mechanics, import/export — see [Businesses overview](/entities/businesses/overview).
</Note>

## What is a business profile

A business profile is created automatically when a [business session](/business-verification/overview) is submitted with a `vendor_data` identifier. If a profile with that identifier already exists, the new session is linked to it.

| Field                   | Description                                                    |
| ----------------------- | -------------------------------------------------------------- |
| **Vendor data**         | Your unique identifier for this business (e.g., `company-123`) |
| **Display name**        | Display name shown in the console                              |
| **Legal name**          | Official legal name from registry or manual entry              |
| **Registration number** | Company registration or incorporation number                   |
| **Country**             | Country of incorporation (ISO 3166-1 alpha-2)                  |

## Profile statuses

| Status    | Description                                                    |
| --------- | -------------------------------------------------------------- |
| `ACTIVE`  | Business is in good standing — no issues detected              |
| `FLAGGED` | Business requires attention — review results or pending checks |
| `BLOCKED` | Business has been blocked from further activity                |

Statuses can be changed manually from the console, in bulk, or automatically based on verification results.

## Session metrics

Each profile tracks verification metrics across all linked sessions:

| Metric             | Description                                                            |
| ------------------ | ---------------------------------------------------------------------- |
| **Total sessions** | Number of verification sessions for this business                      |
| **Approved**       | Sessions that passed all checks                                        |
| **Declined**       | Sessions that failed one or more critical checks                       |
| **In review**      | Sessions awaiting analyst review                                       |
| **Last session**   | Timestamp of the most recent verification                              |
| **First session**  | Timestamp of the earliest verification                                 |
| **Last activity**  | Timestamp of any recent activity (status change, session update, etc.) |

## Tags

Apply tags to business profiles for categorisation and filtering. Tags are application-defined — create custom tags that fit your workflow (e.g., `high-risk`, `vip-client`, `re-verification-needed`).

## Bulk operations

Manage multiple business profiles at once:

| Operation              | Description                                                                         |
| ---------------------- | ----------------------------------------------------------------------------------- |
| **Bulk status update** | Change the status of selected profiles (or all profiles matching current filters)   |
| **CSV export**         | Export profile data to CSV with configurable column selection                       |
| **CSV import**         | Import business profiles from a CSV file to pre-create profiles before verification |
| **Bulk delete**        | Remove selected profiles and their associated data                                  |

### CSV import

To import business profiles in bulk:

1. Download the **import template** from the console to see the expected column format
2. Populate the template with your business data
3. Upload the file — Didit creates an import job and processes rows asynchronously

After completion, review the import summary for created, updated, and failed row counts. Failed rows include specific error details.

## Reviews and comments

Add internal review notes to any business profile. Comments are visible to all team members with access and form part of the audit trail:

* Add notes with free-text content
* Mention team members by email to notify them
* View the full comment history with author and timestamp

## Next steps

<CardGroup>
  <Card title="Business verification overview" icon="building" href="/business-verification/overview">
    How business verification sessions work end to end.
  </Card>

  <Card title="Console guide" icon="gauge" href="/business-verification/console">
    Managing business profiles and sessions in the Business Console.
  </Card>

  <Card title="API reference" icon="code" href="/management-api/businesses/list">
    Business management API endpoints.
  </Card>
</CardGroup>


# Company Data
Source: https://docs.didit.me/business-verification/company-data

Automated registry lookups, company status validation, and data extraction across 220+ countries. From $2.00 per check, priced per country and tier, no contracts.

When a business verification session starts, Didit queries official company registries to retrieve and validate company information. This automated lookup provides the foundation for the entire business verification process.

## Registry lookup

Didit connects to company registries in supported countries to retrieve official data. In the hosted flow the user selects the country of incorporation and fills in the company name, the registration number, or both — at least one is required. Registration numbers are normalized where registries require it (for example, UK company numbers are zero-padded to eight digits), and when both identifiers are provided the registry lookup combines them.

### Pre-filling the search with `expected_details`

If you already know the company, pass `expected_details` (`company_name`, `registry_country`, `registration_number`) when [creating the session](/sessions-api/create-session). The hosted flow pre-selects and locks the country (and the state for state-level registries like `US-CA`), pre-fills the matching search fields, and runs the asserted search automatically — the user lands directly on their company's result. Both fields stay editable so the user can correct a wrong assertion. Prefill only: selecting a different company than asserted does not produce a warning.

### Search types

Registry searches support two modes:

| Mode         | Description                                                                                         |
| ------------ | --------------------------------------------------------------------------------------------------- |
| **Exact**    | Matches the company name or registration number precisely                                           |
| **Contains** | Matches companies whose name contains the search term — useful when the exact legal name is unknown |

### Search workflow

The registry lookup follows an asynchronous workflow:

<Steps>
  <Step title="Search" icon="magnifying-glass">
    Didit queries the registry with the selected country and the identifiers provided — company name, registration number, or both combined. The response's `searched_by` field reports how results were matched (`name`, `registration_number`, or `registration_number_and_name`), and the hosted UI offers a one-tap "Search as company name instead" override on registration-number results. The search runs asynchronously.
  </Step>

  <Step title="Poll results" icon="clock">
    Poll the search status until results are resolved. Large registries may take a few seconds to return results.
  </Step>

  <Step title="Select company" icon="check">
    Review the returned companies and select the correct match. Didit links the selected company to the KYB check and populates all available data.
  </Step>

  <Step title="Manual submission" icon="pen">
    If the company is not found in the registry, submit company data manually. The session continues with the provided data, and `is_from_registry` is set to `false`.
  </Step>
</Steps>

### Retrieved data

| Field                       | Description                                                                                                                                            |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `company_name`              | Legal name as registered with the authority                                                                                                            |
| `registration_number`       | Official company registration or incorporation number                                                                                                  |
| `country_code`              | Country of incorporation (ISO 3166-1 alpha-3)                                                                                                          |
| `company_type`              | Legal entity type (Ltd, LLC, PLC, SA, GmbH, SL, etc.)                                                                                                  |
| `registry_status`           | Current company status from the registry (`active`, `dissolved`, `struck_off`, etc.)                                                                   |
| `incorporation_date`        | Date the company was originally registered                                                                                                             |
| `registered_address`        | Official registered office address                                                                                                                     |
| `tax_number`                | Tax identification number where available                                                                                                              |
| `alternative_names`         | Trade names, dbas, former legal names, or original-language names as a text value                                                                      |
| `legal_entity_identifier`   | LEI — for financial institutions and listed entities                                                                                                   |
| `nature_of_business`        | Short description of the business (in the registry's language)                                                                                         |
| `registered_capital`        | Authorized / issued capital as an `{amount, currency}` object                                                                                          |
| `location_of_registration`  | City / subdivision of the registry of record                                                                                                           |
| `control_scheme`            | Control / governance scheme where the registry exposes it                                                                                              |
| `website`, `email`, `phone` | Contact details on file with the registry                                                                                                              |
| `addresses[]`               | Additional registered or trading addresses                                                                                                             |
| `industries[]`              | Industry classification codes (SIC, NACE, or local equivalents)                                                                                        |
| `accounts`                  | Filing dates when reported, including `last_annual_return_date` and `last_agm_date`. Annual returns and meetings are distinct from financial accounts. |
| `financial_summary`         | Summary financial data where the registry publishes it (revenue, employees, filing status)                                                             |
| `confirmed_by_user_at`      | Timestamp when the end user confirmed or edited the registry data                                                                                      |
| `last_console_edit_at`      | Timestamp of the last console-side edit by an analyst                                                                                                  |
| `is_editable`               | `true` while registry-sourced data can still be edited by the end user in the hosted flow                                                              |
| `is_from_registry`          | `true` for registry-sourced companies, `false` for manual entry                                                                                        |
| `fetch_status`              | `pending`, `resolved`, or `failed` — registry lookup state                                                                                             |
| `verification_status`       | `verified`, `failed`, or `unknown`                                                                                                                     |

### Company statuses

| Status             | Description                                          |
| ------------------ | ---------------------------------------------------- |
| **Active**         | Company is currently active and in good standing     |
| **Dissolved**      | Company has been formally dissolved                  |
| **Struck off**     | Removed from the register (e.g., for non-compliance) |
| **In liquidation** | Company is in the process of being wound up          |
| **Dormant**        | Registered but not currently trading                 |

<Warning>
  Companies with a status other than **Active** may be automatically flagged or declined depending on your workflow configuration.
</Warning>

### Data source indicator

Each company record includes an `is_from_registry` flag:

* **`true`** — data was retrieved from an official company registry
* **`false`** — data was manually submitted because the company was not found in the registry

The `fetch_status` field tracks whether the registry lookup has completed, failed, or is still in progress.

## Data tiers and pricing

The registry check is billed once per selected company, at the price of the tier delivered for that company's country. Hosted workflow searches have no separate search fee.
Standalone API searches can incur a \$0.50 fee per successful request; see [search billing](/standalone-apis/kyb-registry-search). See [KYB registry pricing](/getting-started/kyb-registry-pricing) for the full per-country table.

| Tier             | What you get                                                                                          |
| ---------------- | ----------------------------------------------------------------------------------------------------- |
| **Lite**         | The fields above: company profile, identifiers, status, registered address, activity, and officers    |
| **Shareholders** | Lite plus the direct shareholders (natural persons and corporate entities) with their ownership bands |
| **UBOs**         | Shareholders plus the ultimate beneficial owners resolved through the ownership chain                 |

A hosted workflow picks the tier per country from *Workflows → KYB Registry Check → Countries*. Where the registry holds no ownership record for a company, a Shareholders or UBO request is delivered and billed at the highest tier the country's registries can serve — usually Lite.

A company that is not found and is entered manually (`is_from_registry: false`) is billed a flat **\$0.75** — the search still ran, even though no registry record was returned.

<Accordion title="Example: Lite tier response">
  Lite returns the company profile only — no shareholders, UBOs, or ownership structure:

  ```json theme={null}
  {
    "company_name": "ACME HOLDINGS PTY LTD",
    "registration_number": "094447122",
    "country_code": "AU",
    "registry_status": "active",
    "incorporation_date": "2000-09-12",
    "company_type": "Proprietary Limited",
    "registered_address": "Sydney, NSW, 2000",
    "tax_number": null,
    "vat_number": null,
    "website": null,
    "is_from_registry": true
  }
  ```

  The Shareholders tier adds `ownership_structure` and shareholder entries plus directors/officers. The UBOs tier additionally resolves beneficial owners with ownership percentages. See [Ownership](/business-verification/ownership) and [Officers & directors](/business-verification/officers).
</Accordion>

## Registry data vs user-provided data

Didit keeps registry-returned data and user-confirmed data as **separate audit records**, with a merged canonical view used by downstream checks. Every company carries three related blocks:

| Field                                                                                                          | Description                                                                                                                                                                                    |
| -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `registry_data`                                                                                                | Raw payload returned by the registry. Immutable — kept as an audit record of exactly what the registry said, unchanged.                                                                        |
| `user_provided_data`                                                                                           | What the end user confirmed or edited during the registry-confirmation step in the hosted flow.                                                                                                |
| Top-level canonical fields (`company_name`, `registration_number`, `country_code`, `incorporation_date`, etc.) | The merged truth — user-confirmed data when present, registry data as fallback. Downstream features (document OCR cross-check, AML screening, risk assessment) run against the canonical view. |

The `confirmed_by_user_at` timestamp marks when the end user confirmed or edited the registry data. While that timestamp is still null and `is_editable` is `true`, the end user can continue to modify fields inside the hosted flow.

For **manual-entry companies** (`is_from_registry: false`), `user_provided_data` is the only source and `is_editable` becomes `false` after the user submits.

Analysts can see the two sources side-by-side in the [Business Console](/business-verification/console) session review and diff what the registry said vs what the user confirmed.

## Configurable registry form fields

You control which company-data fields the hosted verification flow asks for during the registry-confirmation step. Configure them in the Business Console: open the workflow editor, select the **KYB Registry check** node, and switch to the **Fields** tab.

Each field has one of three states:

| State        | Behavior                                                          |
| ------------ | ----------------------------------------------------------------- |
| **Hidden**   | The field is not shown in the hosted flow and is not collected.   |
| **Optional** | The field is shown; the user can leave it empty.                  |
| **Required** | The field is shown and must be filled before the user can submit. |

Three fields are always shown and always required — they identify the company and cannot be configured: `company_name`, `country_code`, and `region` (state/region, where the registry is regional).

The 16 configurable fields:

`registration_number`, `incorporation_date`, `legal_address`, `vat_number`, `alternative_names`, `tax_number`, `company_type`, `legal_entity_identifier`, `location_of_registration`, `nature_of_business`, `registered_capital_amount`, `registered_capital_currency`, `website`, `email`, `phone`, `control_scheme`

By default — and for all existing workflows — only `incorporation_date` is **Required**; every other configurable field is **Optional**, so the form behaves exactly as it did before this setting existed.

Requiredness is enforced server-side: submitting the registry form with a required field empty returns `400` with per-field error messages, and the hosted UI renders only the enabled fields. In the workflow API, the setting is the `kyb_registry_fields_config` object on the KYB Registry node — see [feature configs](/management-api/workflows/feature-configs#kyb-registry) for the shape.

<Note>
  `vat_number` marked **Required** is only enforced for companies incorporated in an EU VAT country (see below) — for all other countries the field is treated as optional even when required, since there is no EU VAT number to collect.
</Note>

## VAT validation (VIES)

When the end user (or the registry) provides a `vat_number` for a company incorporated in the EU, Didit validates it against the European Commission's [VIES](https://ec.europa.eu/taxation_customs/vies/) service when the registry step is submitted.

* **Coverage** — the 27 EU member states plus Northern Ireland (`XI`). Greek VAT numbers are checked under the `EL` prefix automatically. Companies from any other country skip validation entirely and get `vat_validation_status: "not_applicable"`.
* **Prefix handling** — the number is normalized before the check, so it can be submitted with or without the country prefix (`DE123456789` and `123456789` are equivalent for a German company).

The result is stored on the company and exposed in the [KYB decision payload](/business-verification/response-schema#company-block):

| Field                   | Description                                                             |
| ----------------------- | ----------------------------------------------------------------------- |
| `vat_number`            | The VAT number as submitted                                             |
| `vat_validation_status` | `valid`, `invalid`, `could_not_validate`, or `not_applicable`           |
| `vat_validated_name`    | Trader name registered with VIES, when the member state discloses it    |
| `vat_validated_address` | Trader address registered with VIES, when the member state discloses it |
| `vat_checked_at`        | Timestamp of the VIES check                                             |

| Status               | Meaning                                                                    |
| -------------------- | -------------------------------------------------------------------------- |
| `valid`              | VIES confirmed the VAT number is registered                                |
| `invalid`            | VIES rejected the number (not registered or malformed)                     |
| `could_not_validate` | VIES or the member state was unavailable — the number could not be checked |
| `not_applicable`     | No VAT number was provided, or the company is outside the EU VAT area      |

**Name cross-check.** When the number is `valid` and VIES discloses the registered trader name, Didit fuzzy-compares it against the submitted company name. A meaningful divergence raises the `KYB_COMPANY_VAT_NAME_MISMATCH` warning (with `vies_name` and `submitted_name` in `additional_data`) without changing the session status — it is a soft signal for reviewers. Some member states do not disclose the name or address; the fields come back empty and no comparison runs.

**Configurable actions.** Two settings on the KYB Registry check node control what an unsuccessful check does to the session (values `REVIEW`, `DECLINE`, `NO_ACTION`):

| Setting                     | Fires when                                      | Default                                |
| --------------------------- | ----------------------------------------------- | -------------------------------------- |
| `kyb_vat_invalid_action`    | `vat_validation_status` is `invalid`            | `REVIEW` — session goes to In Review   |
| `kyb_vat_unverified_action` | `vat_validation_status` is `could_not_validate` | `NO_ACTION` — no effect on the session |

Each outcome also raises the matching warning (`KYB_COMPANY_VAT_INVALID`, `KYB_COMPANY_VAT_COULD_NOT_VALIDATE`) on the registry check — see [Business Verification warnings](/business-verification/warnings#kyb-registry-warnings).

## Data cross-referencing

Didit automatically compares the user-provided / canonical data with what the registry returned, and with OCR data extracted from uploaded documents:

* **Company name** — fuzzy matching to account for abbreviations and formatting differences
* **Registration number** — exact match validation
* **Country** — consistency check between provided and registry country
* **Address** — geocoding and normalization for comparison

Any inconsistencies are flagged as warnings in the session and visible to analysts in the console.

## Financial summary

Where available, Didit retrieves summary financial data from the registry:

* Revenue or turnover
* Number of employees
* SIC/NACE industry codes
* Filing dates and compliance status

## Additional registry fields

Depending on jurisdiction coverage, the registry response may also include:

* `alternative_names` - trade names, dbas, former legal names
* `legal_entity_identifier` (LEI) — for financial institutions and listed entities
* `website`, `email`, `phone` — contact information on file with the registry
* `nature_of_business` — short description (in the language of the registry)
* `registered_capital` — authorized / issued capital as an `{amount, currency}` object

All fields land in the [`business`](/business-verification/response-schema) block of the KYB decision.

## Confidence and verification status

Each registry response carries a `verification_status`:

| Value      | Meaning                                                                      |
| ---------- | ---------------------------------------------------------------------------- |
| `VERIFIED` | Registry returned a match and data was retrieved.                            |
| `FAILED`   | Registry returned a match but data retrieval failed (e.g. partial response). |
| `UNKNOWN`  | Company could not be located in any registry.                                |

Combine with `is_from_registry` to drive your own downstream logic:

| `is_from_registry` | `verification_status` | Meaning                                       |
| ------------------ | --------------------- | --------------------------------------------- |
| true               | VERIFIED              | Fully verified against official registry      |
| true               | FAILED                | Partial — some fields may be stale or missing |
| false              | UNKNOWN               | User-provided data only; no registry match    |

## Cross-referencing outputs

Each cross-reference runs per field and returns one of:

* `MATCH` — provided data agrees with registry.
* `MISMATCH` — meaningful divergence. Flagged as a warning.
* `NO_DATA` — one side was empty; no comparison possible.

Mismatches are visible per-field in the console session review.

## Risk assessment

The company's overall risk level is calculated based on:

| Factor                   | Impact                                                          |
| ------------------------ | --------------------------------------------------------------- |
| **Company status**       | Non-active companies increase risk                              |
| **Country risk**         | Incorporation in high-risk jurisdictions increases risk         |
| **Age**                  | Recently incorporated companies may receive additional scrutiny |
| **AML results**          | Company-level AML screening results                             |
| **Ownership complexity** | Multi-layered or opaque ownership structures                    |

See [risk assessment](/business-verification/risk-assessment) for the full computation.

## Supported countries

Coverage varies by country — see [supported countries](/business-verification/supported-countries) for the per-region tier breakdown.

## Next steps

<CardGroup>
  <Card title="Ownership" icon="sitemap" href="/business-verification/ownership">
    UBO identification and ownership chains.
  </Card>

  <Card title="Response schema" icon="file-lines" href="/business-verification/response-schema">
    Where each field appears in the payload.
  </Card>

  <Card title="Supported countries" icon="globe" href="/business-verification/supported-countries">
    Coverage by region.
  </Card>
</CardGroup>


# Business Verification Console
Source: https://docs.didit.me/business-verification/console

Review KYB sessions in the Business Console: company data, ownership, AML results, documents, key people. From $2.00 per check, priced per country and tier, no contracts.

Business verification sessions are managed in the Business Console alongside user verifications, with KYB-specific sections for registry data, documents, and key people. This page walks through the session detail view.

## Navigating to a business session

From the Business Console, open *Businesses → \[business]* to see all sessions for that business, or open the session directly from the Sessions list. Business sessions show a **business** badge next to the session number so they're easy to spot in a mixed list.

## Session detail — sections

A KYB session detail page shows these sections. Which sections appear depends on the features your workflow enabled.

### Overview

Session summary: status, workflow used, `vendor_data`, session number, creation/expiry timestamps, per-feature status chips (KYB Registry, KYB Company AML, KYB Documents, KYB Key People, and any shared features like AML, Phone, Email, Questionnaires, Device & IP Analysis).

### KYB Registry

The company block extracted from the registry (or submitted manually when not found):

* **Registry data** — registry-returned fields: legal name, registration number, incorporation date, company type, registered address, tax number, industries, accounts / filing dates.
* **User-provided / confirmed data** — what the end user confirmed or edited in the hosted flow, shown side-by-side with the registry data.
* **Data source indicator** — `is_from_registry`, `fetch_status`, `verification_status`, `confirmed_by_user_at`.
* **Financial summary** — where the registry publishes it.
* **Risk level** — composite signal (`LOW`, `MEDIUM`, `HIGH`).

Actions: confirm / edit canonical fields, view the raw registry payload for audit, request the end user to re-confirm.

### KYB Documents

Documents grouped by document type group — Legal presence, Company details, Ownership structure, Representatives authorization.

* **Per-group progress** — approved / pending / missing counts per group, and which groups are required.
* **Document items** — each uploaded document with signed preview URL, OCR extract, cross-check result against the user-provided data.
* **Cross-check diff** — per-field comparison between the OCR data and the canonical company data.

Actions: approve or decline individual documents, request a resubmission, request an additional document, download.

### KYB Key People

The key-people list — UBOs, shareholders, directors, representatives, and other officer roles — shown **side-by-side** in two buckets:

* **Registry** — parties extracted from the registry check, grouped by role category.
* **Submitted** — parties the business admin added during the Key People flow (source = USER).

Each person shows: name, entity type (person or company), role(s) with ownership / voting percentages where relevant, KYC status of the linked child session (`Approved` / `Declined` / `Pending`), AML status, and a link to open the child KYC or KYB sub-session.

The `ubo_kyc_summary` card rolls up UBO KYC progress — total / approved / flagged / pending — at the top of the section.

Actions: open a child session, skip a party's verification (or require it again), request resubmission of a specific child session, view the child AML hits.

**Skipping a party** exempts it from the Key People check so a KYB that cannot progress can still be settled - the usual case is a party whose individual KYC session was deleted, which leaves it with a dead link and a status that can never change. The control needs the `write:businesses` permission and, unlike the applicant-facing skip in the hosted flow, is not limited to roles with `allow_skip`. The same override is available over the API: [`PATCH /v3/session/{id}/kyb/parties/{party_uuid}/`](/sessions-api/update-data#skip-a-key-people-party).

### AML

Company-level AML screening. For each hit: match score, risk score, category (sanctions, PEP, adverse media, criminal, enforcement), watchlist source, screened name. Per-hit actions: mark false positive, confirm, add note.

Person-level AML hits for key people also surface here, each linked back to the relevant key person.

### Device & IP Analysis

Submitter IP, country, ASN, data-center / VPN flags, device fingerprint when collected.

### Phone / Email / Questionnaires

Appear only when the workflow collects them. Same feature-detail surface as on a KYC session.

### Events

Chronological log of everything that happened on the session — status changes, feature completions, analyst actions, webhook deliveries. Filter by event type and date.

### Webhooks

History of webhook deliveries for this session with response codes, retry counts, and raw payloads. You can resend any delivery.

### Chat

Internal analyst notes with `@`-mentions. Not visible to the end user.

## Tag management

Tag any business session for categorisation and later filtering. Tags appear as chips on the Overview and on the Sessions list — useful for tracking risk tiers, review stages, partner source, or any custom axis.

## Reviewer actions

From any section, an analyst with the right role can:

* **Approve** the session when all checks pass.
* **Decline** the session if a critical issue stands.
* **Request more information** — force a resubmission on specific documents or child KYC sessions.
* **Override a feature status** — manually set a feature to `APPROVED` / `DECLINED` / `IN_REVIEW` with a note.
* **Add a chat note** — visible to teammates, not to the user.
* **Tag** the session for downstream filtering.
* **View the full audit trail** of every action on the Events tab.

See [Roles & permissions](/console/roles-permissions) for the matrix of who can do what.

## Business profiles

Business profiles give you the durable cross-session view of each company. From *Businesses* you can search, filter, tag, bulk-update status, export CSV, and import in bulk. See [Business profiles](/business-verification/business-profiles) for details.

## Next steps

<CardGroup>
  <Card title="Business entities" icon="building" href="/entities/businesses/overview">
    The broader Business entity model across sessions.
  </Card>

  <Card title="Manual review" icon="gavel" href="/console/manual-review">
    Deep reviewer walkthroughs across KYB and KYC.
  </Card>

  <Card title="Workflows" icon="diagram-project" href="/console/workflows">
    Configuring KYB workflows.
  </Card>
</CardGroup>


# Documents
Source: https://docs.didit.me/business-verification/documents

Collect and verify corporate documents — incorporation certificates, articles, financials — with OCR and registry cross-referencing. Document collection is billed separately from registry retrieval.

Business verification includes structured document collection to validate company information beyond what's available in registries.

## Pricing

In the current staging release, KYB document collection costs **USD 0.20 per workflow step**, independent of how many documents are uploaded in that step. Re-uploading a document in the same step does not add another fee; a separate document-collection step has its own charge. Production rollout of this billing change is pending. Registry retrieval, company and person AML, and linked KYC are separate charges. The 500 free document-capture ID checks do not cover KYB document collection.

## Document groups

Documents are organized into four structured groups, each representing a category of evidence needed for business verification:

| Group                             | Description                                                 | Examples                                                    |
| --------------------------------- | ----------------------------------------------------------- | ----------------------------------------------------------- |
| **Legal presence**                | Documents proving the company legally exists                | Certificate of incorporation, business registration         |
| **Company details**               | Documents describing the company's operations               | Articles of association, memorandum of association          |
| **Ownership structure**           | Documents proving the ownership chain                       | Shareholder register, share certificates, UBO declarations  |
| **Representatives authorization** | Documents proving authority to act on behalf of the company | Power of attorney, board resolutions, authorization letters |

Each group tracks its own progress with per-group summaries: total documents expected, approved, pending review, and missing. The business session's overall documents status aggregates across all groups.

## Document types

| Category                 | Examples                                                                         |
| ------------------------ | -------------------------------------------------------------------------------- |
| **Formation documents**  | Certificate of incorporation, articles of association, memorandum of association |
| **Ownership documents**  | Shareholder register, share certificates, UBO declarations                       |
| **Address documents**    | Utility bills, bank statements, or lease agreements for the registered address   |
| **Financial documents**  | Annual accounts, audit reports, financial statements                             |
| **Tax documents**        | Tax registration certificates, tax compliance certificates                       |
| **Regulatory documents** | Licenses, permits, regulatory approvals                                          |
| **Custom documents**     | Any additional documents required by your compliance process                     |

## Document workflow

<Steps>
  <Step title="Automatic requests" icon="file-circle-plus">
    Based on your workflow configuration, Didit automatically identifies which documents are needed for the business verification. Required document types are presented to the business for upload.
  </Step>

  <Step title="Upload" icon="upload">
    Documents are uploaded through the hosted verification flow or via the Business Console. Supported formats include PDF, JPG, PNG, and WebP.
  </Step>

  <Step title="OCR extraction" icon="microchip-ai">
    Didit extracts structured data from uploaded documents using OCR:

    * Company name and registration number from certificates
    * Address data from utility bills
    * Financial figures from statements
    * Names and roles from shareholder registers
  </Step>

  <Step title="Cross-referencing" icon="code-compare">
    Extracted data is cross-referenced against:

    * Registry data from the company lookup
    * Information provided at session creation
    * Data from other uploaded documents

    Inconsistencies are flagged for analyst review.
  </Step>

  <Step title="Review" icon="magnifying-glass">
    Analysts review uploaded documents in the console, verify their authenticity, and approve or reject each document individually.
  </Step>
</Steps>

## Analyst document requests

During the review process, analysts can request additional documents:

1. Navigate to the business session in the console
2. Click **Request document** and specify the document type and description
3. The business is notified and can upload the requested document
4. The document appears in the session with a **Requested** status until uploaded

This allows analysts to gather additional evidence without rejecting the entire business session.

## Document statuses

Each document and the aggregate `document_verifications[]` check use the standard KYB feature status set:

| Status            | Description                                                                                                   |
| ----------------- | ------------------------------------------------------------------------------------------------------------- |
| `NOT_FINISHED`    | Document is still being processed (upload in progress, OCR running, or cross-check pending).                  |
| `APPROVED`        | Document was reviewed and accepted.                                                                           |
| `DECLINED`        | Document was reviewed and rejected.                                                                           |
| `IN_REVIEW`       | Document requires manual analyst attention.                                                                   |
| `RESUB_REQUESTED` | Analyst requested a resubmission — the business must re-upload this document before the session can progress. |

## Cross-check results

When a document is processed, Didit cross-references the OCR-extracted data against the **user-provided data** submitted in the Key People flow (and any data confirmed during registry review) plus other uploaded documents. The cross-check produces structured results:

| Category                | Description                                                                                                                                                                                  |
| ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Critical fields**     | Fields where the document data and the user-provided data do not match — these require analyst review. Each field shows the document value, the user-provided value, and a confidence score. |
| **Non-critical fields** | Fields with minor discrepancies or formatting differences that may not require action (e.g. abbreviation differences in company name).                                                       |
| **People overlap**      | Analysis of people mentioned in the document vs. people submitted by the user — highlights missing or additional individuals.                                                                |

Cross-check results are displayed in the [Business Console](/business-verification/console) alongside the document preview, giving analysts a clear view of what matches and what needs attention.

## Retrieving documents via API

Documents are attached to the Business Verification (KYB) session. Fetch them via the session decision:

```bash theme={null}
curl https://verification.didit.me/v3/session/{session_id}/decision/ \
  -H "x-api-key: YOUR_API_KEY"
```

The response includes a `document_verifications[]` array — each item has a `status`, `node_id`, `items[]` (each with a signed `file_url` and OCR extract), `groups`, and `required_groups`. See [response schema](/business-verification/response-schema#document_verifications) for the full structure.

## Next steps

<CardGroup>
  <Card title="Response schema" icon="file-lines" href="/business-verification/response-schema">
    Where documents appear in the payload.
  </Card>

  <Card title="Business console" icon="desktop" href="/business-verification/console">
    Reviewing documents as an analyst.
  </Card>
</CardGroup>


# KYB Integration Guide
Source: https://docs.didit.me/business-verification/integration-guide

Production-ready KYB integration: architecture, sessions, hosted flows, webhooks, polling, and decisions. From $2.00 per check, priced per country and tier.

<AgentPromptAccordion title="KYB Integration Prompt" />

This guide is the companion to the [quickstart](/business-verification/quickstart). It covers the architecture, every integration decision, and the operational patterns that make KYB reliable in production.

## Architecture

```mermaid theme={null}
sequenceDiagram
    participant You as Your platform
    participant Didit as Didit API
    participant Biz as Business contact
    participant Webhook as Your webhook endpoint

    You->>Didit: POST /v3/session/ (workflow_id, vendor_data)
    Didit-->>You: session_id, url, token
    You->>Biz: Deliver hosted verification URL (your email/flow)
    Biz->>Didit: Completes KYB hosted flow
    Didit->>Didit: Registry lookup, AML screening, OCR
    Didit->>Webhook: status.updated (session_kind: business)
    You->>Didit: GET /v3/session/{id}/decision/
    Didit-->>You: Full KYB decision payload
    You->>You: Onboard / reject / escalate based on status
```

## Authentication

All requests require the `x-api-key` header with your application's API key. See [API authentication](/getting-started/api-authentication) for key rotation, environment separation, and scopes.

## Session creation

Single endpoint: `POST /v3/session/`. The workflow's type determines whether the session is KYC or KYB — no explicit "business" flag is needed.

**Recommended fields on creation:**

| Field              | Purpose                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workflow_id`      | Required — references your KYB workflow.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `vendor_data`      | Your identifier for the business. Binds the session to a [Business entity](/entities/businesses/overview).                                                                                                                                                                                                                                                                                                                                                                |
| `callback_url`     | Optional — where to redirect the user after completion.                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `expected_details` | Optional — `{ company_name, registry_country, registration_number }`. Pre-fills the company registry search: the country of incorporation is pre-selected and locked (`registry_country` as `XX`, or `XX-YY` for state-level registries, e.g. `US-CA`), the company-name and registration-number fields are pre-filled, and the asserted search runs automatically — combining both identifiers when both are present. Prefill only — mismatches do not produce warnings. |
| `metadata`         | Optional JSON attached to the session.                                                                                                                                                                                                                                                                                                                                                                                                                                    |

Full schema: [create session](/sessions-api/create-session).

## Delivering the hosted link

The response `url` is a hosted verification link. Options for delivery:

* Email it from your own platform.
* Embed it in your onboarding UI as a link.
* Open it in an in-app webview (iOS / Android / React Native).

You can **customize** the hosted experience — logo, color, domain, email templates — via [White-label](/console/white-label).

## Polling vs webhooks

Webhooks are the recommended pattern. Didit POSTs completion events to your subscribed endpoint as soon as processing finishes.

Polling is supported for development or when your webhook endpoint is unreachable:

* Poll `GET /v3/session/{id}/decision/` with exponential backoff (every 10s initially, up to 60s).
* Stop polling when `status` is one of `APPROVED`, `DECLINED`, `IN_REVIEW`.

<Warning>
  Polling at high frequency may hit [rate limits](/integration/rate-limiting). Always prefer webhooks in production.
</Warning>

## Webhook handling

Subscribe to the events you care about — the same events cover both KYC and KYB, with `session_kind: "business"` inside the payload to identify business-session events:

* `status.updated` — session status changed. Filter on `data.session_kind === "business"` for KYB sessions.
* `data.updated` — session data changed (registry refresh, key-people submission, documents, ongoing AML). Same `session_kind` filter applies.
* `business.status.updated` / `business.data.updated` — the linked [Business entity](/entities/businesses/overview) changed.

Full event catalog: [KYB webhooks](/business-verification/webhooks). Signature verification and retry semantics: [webhooks reference](/integration/webhooks).

## Handling decisions

```typescript theme={null}
switch (decision.status) {
  case 'APPROVED':
    await onboardBusiness(decision);
    break;
  case 'DECLINED':
    await logRejection(decision.decision_reason_code, decision);
    break;
  case 'IN_REVIEW':
    // Wait for analyst decision — another webhook will fire
    await markPending(decision);
    break;
  case 'RESUBMITTED':
    // The business was asked to re-upload a document
    await notifyBusiness(decision);
    break;
}
```

See [KYB statuses](/business-verification/statuses) for the full state machine and reason codes.

## Resubmission flow

When a Business Verification (KYB) session transitions to `RESUB_REQUESTED` (or a feature is marked for resubmission), the business needs to upload corrected or additional data.

You can:

* **Re-deliver** the same `url` — the hosted flow picks up where resubmission is needed.
* **Open a [case](/transaction-monitoring/cases)** in the Business Console to track the back-and-forth internally.

## Business profile aggregation

If you pass `vendor_data` on session creation, Didit aggregates all sessions for that business into a single [Business entity](/entities/businesses/overview). Use the entity's `features` map to answer "is this business fully verified right now?" without iterating sessions.

Benefits:

* Periodic re-KYB flows append to the same profile.
* Transactions monitored against the same `vendor_data` carry the business's risk context.
* UBOs and officers linked to User entities populate cross-entity relationships.

## Best practices

| Practice                            | Why                                                               |
| ----------------------------------- | ----------------------------------------------------------------- |
| Always pass `vendor_data`           | Without it, the session is orphaned and can't be aggregated.      |
| Use webhooks, not polling           | Lower latency, no rate limit pressure.                            |
| Verify webhook signatures           | Prevents spoofed events.                                          |
| Store the `session_id` on your side | Needed to retrieve the decision and generate PDFs.                |
| Tag sessions with `metadata`        | Simplifies reporting and debugging.                               |
| Set up a test workflow              | Use a sandbox workflow for integration testing before production. |

## Error handling

| Scenario                                       | Response                                                                                                                                                                                                                                                                                                                                                      |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Invalid `workflow_id`                          | `400 Bad Request`                                                                                                                                                                                                                                                                                                                                             |
| Duplicate session with same `vendor_data`      | Creates a new session — that's by design, since re-verification is expected.                                                                                                                                                                                                                                                                                  |
| Dangerous country                              | Session is created but immediately `DECLINED` with reason `blocked_country`.                                                                                                                                                                                                                                                                                  |
| Blocklisted `vendor_data`                      | Session auto-declined with reason `blocked_business`.                                                                                                                                                                                                                                                                                                         |
| Registry provider outage during company search | `POST /v3/kyb/search/` returns `502` with `code: "kyb_registry_provider_unavailable"`. Not billed - retry, or branch on `code` to offer manual company entry. In Didit's hosted flow, the business is routed into manual entry automatically instead of a retry-only error. See [KYB Registry Search](/standalone-apis/kyb-registry-search#provider-outages). |
| Rate limit                                     | `429 Too Many Requests` with `Retry-After` header.                                                                                                                                                                                                                                                                                                            |

Full [rate limiting](/integration/rate-limiting) reference.

## Next steps

<CardGroup>
  <Card title="Webhooks" icon="bolt" href="/business-verification/webhooks">
    Every KYB event and payload.
  </Card>

  <Card title="Statuses" icon="list-check" href="/business-verification/statuses">
    State machine reference.
  </Card>

  <Card title="Response schema" icon="file-lines" href="/business-verification/response-schema">
    Decoding the KYB decision.
  </Card>
</CardGroup>


# Key People
Source: https://docs.didit.me/business-verification/key-people

Verify UBOs, shareholders, directors, and officers in one unified KYB flow with role-aware checks and linked KYC sessions. From $2.00 per check, priced per country and tier, no contracts.

**Key people** is Didit's unified model for every natural person and corporate entity tied to the business you're verifying: UBOs, shareholders (individual and corporate), directors, representatives, and other officer roles. A single Key People flow covers the lot — with role-aware verification dispatch and full side-by-side comparison between registry-sourced and user-submitted parties.

<Note>
  For the Business-entity view of key people — how officers and UBOs aggregate across sessions — see [Businesses → Key people](/entities/businesses/key-people).
</Note>

## How it works

<Steps>
  <Step title="Registry prefill (optional)">
    If the workflow enables registry prefill, the Key People screen is pre-populated with UBOs, shareholders and officers extracted from the registry check. The end user can edit, add, or remove parties before submitting.
  </Step>

  <Step title="Submission from the hosted flow">
    The end user submits the final list of key people through the hosted verification flow. You don't call this step yourself — it happens inside the KYB flow whose URL you delivered from [Create Session](/sessions-api/create-session).
  </Step>

  <Step title="Role-aware verification routing">
    For each submitted party, Didit checks the role's configured verification settings:

    * Applies the workflow's ownership threshold — UBOs and shareholders below the configured percentage don't require individual verification.
    * Honours the "skip verification" flag the end user set, if the role allows skipping.
    * Spawns a child User Verification (KYC) session for person parties that require KYC.
    * Spawns a child KYB sub-session for corporate UBOs when nested KYB is enabled on the workflow.
  </Step>

  <Step title="Status progression">
    The Key People feature status becomes `Awaiting User` while any required child session is still in progress. When every child session finishes, the status aggregates to `Approved`, `Declined`, or `In Review` based on the outcomes.
  </Step>
</Steps>

## Roles collected

Key people can carry one or more of the following roles — a single person can hold several at once (for example, director **and** shareholder). The full taxonomy:

| Category                        | Roles                                                                                                                                                                      |
| ------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Ownership**                   | `ubo`, `shareholder`, `beneficiary`, `settlor`, `protector`, `investor`                                                                                                    |
| **Governance / representation** | `director`, `non_executive_director`, `chairman`, `secretary`, `representative`, `authorized_signatory`, `trustee`, `company_officer`, `founder`, `legal_advisor`, `other` |

Every role can be individually configured in the workflow — enabled or disabled, required or optional for KYC, mapped to a specific KYC workflow, and optionally skippable. See [Ownership](/business-verification/ownership) for the verification dispatch details.

## Data collected per key person

The hosted flow asks for a default set of fields and additional workflow-configured custom fields. See [Ownership → Fields collected](/business-verification/ownership#data-collected-for-each-key-person) for the full list.

## Registry confirmation

Before the Key People step, the end user reviews the company data extracted from the registry check and optionally edits any fields. The hosted flow then stores:

* The **raw registry payload** as an immutable audit record (`registry_data`).
* The **user-confirmed data** (`user_provided_data`) with a timestamp that marks when the user confirmed.
* A merged canonical view on the top-level company fields — user-confirmed when present, registry fallback otherwise.

See [Company data → Registry vs user-provided data](/business-verification/company-data#registry-data-vs-user-provided-data) for the full model.

## Shape in the decision response

After submission, the collected key people surface in the KYB decision under `key_people_checks[]`, split into two buckets — **registry** (what the provider disclosed) and **submitted** (what the business admin confirmed through the flow) — plus a `ubo_kyc_summary` that rolls up UBO KYC progress. See the full [key\_people\_checks reference](/business-verification/response-schema#key_people_checks).

## Resubmit behaviour

* **Key People** and **Registry Check** cannot be resubmitted directly. To re-verify a specific person, resubmit their individual child KYC session.
* When a child KYC session is resubmitted, the parent Key People feature status automatically returns to `Awaiting User`.
* When the resubmitted child finishes, the parent re-aggregates based on all child statuses.

## Configuration options

All Key People behaviour is configured per workflow from the Business Console:

| Setting                             | What it controls                                                                                            |
| ----------------------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Registry prefill**                | Pre-populate the Key People form from registry data                                                         |
| **Extra fields — persons**          | Custom fields to collect for each person party                                                              |
| **Extra fields — companies**        | Custom fields to collect for each corporate party                                                           |
| **UBO ownership threshold**         | Minimum ownership percentage to classify someone as a UBO                                                   |
| **Shareholder ownership threshold** | Minimum ownership percentage to classify someone as a shareholder                                           |
| **Per-role settings**               | For each role: enabled/disabled, require KYC, KYC workflow to use, skippable                                |
| **Corporate UBO nested KYB**        | When enabled, corporate UBOs trigger their own child KYB session                                            |
| **Reuse verified individuals**      | See [Reusing verified individuals across KYB checks](#reusing-verified-individuals-across-kyb-checks) below |
| **Notify parties by email**         | Automatically email each key person with their verification link                                            |

Configure at *Workflows → \[KYB workflow] → Key People* in the console.

## Reusing verified individuals across KYB checks

When **Reuse verified individuals** is enabled on a workflow (the default), a key person doesn't have to redo KYC every time they show up on a new KYB check. Didit looks for an existing approved KYC from a previous KYB check and links it to the new party instead of spawning a fresh child KYC session.

<Note>
  This is a distinct mechanism from [Reusable KYC](/core-technology/reusable-kyc/overview), which lets an *end user* voluntarily carry one finished session across separate Didit-integrated applications via a share/import token. The KYB reuse setting on this page is automatic, workflow-configured, and scoped to key people within a single application - no share token, and no action from the end user.
</Note>

**Matching.** A candidate match is found by comparing the submitted person's full name (case-insensitive, whitespace-trimmed) against key people from the application's other KYB checks. There's no additional matching signal - a document number, email, or phone match is not required or checked. A name entered with different spelling, a middle name, or a transliteration won't match, and in rare cases two different people who share a name could match; review your Key People results with this in mind.

**Scope.** Matching looks across every other KYB check that belongs to the *same application*, not just the current KYB check and not other applications in your organization. A person verified as a UBO on Company A can be matched when they later appear as a director on Company B, as long as both checks run under the same application.

**Eligible statuses.** Only a party's most recent **Approved** KYC is eligible for reuse. A **Declined** KYC for that name blocks reuse entirely - the party is flagged and a fresh KYC is requested instead of falling back to the declined one. A KYC that's still **In Review** is never considered a candidate.

**Retention.** Matching only considers KYC sessions created in roughly the last year that haven't been deleted. If the only matching session falls outside that window, or the person or org has deleted it, the check finds no eligible match and silently requests a new KYC - it never fails or blocks Key People submission.

**Billing.** A reused KYC is not billed again. Linking an already-approved session to the new party carries no additional charge; you're only billed once, on the original KYC.

```txt Example theme={null}
Company A: Jane Doe submitted as UBO, KYC approved.
Company B (same application): Jane Doe submitted as a director.
"Reuse verified individuals" is enabled, so Company B's Key People
check links Jane's existing approved KYC instead of requesting a
new one - free, and instantly Approved for that party.
```

## Next steps

<CardGroup>
  <Card title="Ownership" icon="sitemap" href="/business-verification/ownership">
    Fields collected, custom data, and registry vs submitted reconciliation.
  </Card>

  <Card title="Officers & representatives" icon="user-tie" href="/business-verification/officers">
    Governance roles within the key-people model.
  </Card>

  <Card title="Response schema" icon="file-lines" href="/business-verification/response-schema#key_people_checks">
    `key_people_checks[]` field-by-field reference.
  </Card>
</CardGroup>


# Officers & Representatives
Source: https://docs.didit.me/business-verification/officers

Verify directors, officers, and authorized representatives via Didit's unified Key People model with multi-role tagging and AML screening. From $2.00 per check, priced per country and tier.

Officers, directors, and representatives are **not a separate concept in Didit's KYB model** — they live inside [Key People](/business-verification/key-people) alongside UBOs and shareholders, tagged with one or more roles per person. A single person can be a director **and** a shareholder, or a representative **and** an authorized signatory — the party carries the full role list, not just one role.

## Full role taxonomy

Every key person can hold one or more of these roles:

### Governance / representation

| Role                     | Description                                                     |
| ------------------------ | --------------------------------------------------------------- |
| `director`               | Board member with governance responsibilities                   |
| `non_executive_director` | Board member without day-to-day management duties               |
| `chairman`               | Chair of the board                                              |
| `secretary`              | Company secretary handling administrative and compliance duties |
| `representative`         | Legal or appointed representative of the company                |
| `authorized_signatory`   | Person empowered to sign on behalf of the company               |
| `trustee`                | Trustee of a structure holding company interests                |
| `company_officer`        | General officer role                                            |
| `founder`                | Founding member of the company                                  |
| `legal_advisor`          | Retained legal counsel for the company                          |
| `other`                  | Any role outside the standard taxonomy                          |

### Ownership / beneficiary

| Role          | Description                                                                        |
| ------------- | ---------------------------------------------------------------------------------- |
| `ubo`         | Ultimate Beneficial Owner — individual who ultimately owns or controls the company |
| `shareholder` | Registered shareholder (individual or corporate)                                   |
| `beneficiary` | Beneficiary of a trust or similar structure                                        |
| `settlor`     | Settlor of a trust                                                                 |
| `protector`   | Protector of a trust                                                               |
| `investor`    | Investor role (outside formal share ownership structures)                          |

A single person can carry both categories — for example, a founder who is also a director and a UBO holds three roles on the same key-people record.

## Multi-role records

Each key person record includes a list of roles, each with its own ownership/voting percentages where relevant. This is how a director-plus-shareholder looks in the response:

```json theme={null}
{
  "uuid": "...",
  "name": "Jane Doe",
  "first_name": "John",
  "last_name": "Doe",
  "entity_type": "person",
  "roles": [
    { "role": "director", "ownership_percent": null, "voting_percent": null },
    { "role": "shareholder", "ownership_percent": 15.0, "voting_percent": 15.0 }
  ],
  "kyc_status": "Approved",
  "kyc_session_url": "https://verify.didit.me/..."
}
```

## KYC linking

Every key person can be linked to an individual User Verification (KYC) session. The linking happens automatically when the role's workflow settings require KYC — the system spawns the child KYC session, emails the person their verification link (if that option is enabled), and tracks status back on the party.

See [Ownership → How role settings drive verification](/business-verification/ownership#how-role-settings-drive-verification) for the full routing logic. For the B2C-safe KYC status values surfaced on each party (`Approved`, `Declined`, `Pending`), see the [response schema](/business-verification/response-schema#company-block).

## AML screening

Every identified key person is automatically screened against global AML watchlists as part of the business verification process. PEP matches are especially relevant for governance roles — directors and signatories of regulated companies often surface on PEP lists. See [Business AML screening](/business-verification/aml).

## Requires-verification flag

Each party carries a `requires_verification` flag that tells you whether the workflow demands KYC for that person:

| Value   | Meaning                                                                 |
| ------- | ----------------------------------------------------------------------- |
| `true`  | KYC must complete for this person before the session can approve.       |
| `false` | Person is identified and AML-screened but does not need individual KYC. |

Configure which roles require verification from *Workflows → \[KYB workflow] → Key People → per-role settings*. Typical defaults:

* Directors and UBOs above the workflow's threshold → `requires_verification: true`.
* Authorized signatories and secretaries → optional.
* Non-executive board members → optional.

## Skipping a key person

If a person cannot be verified (deceased, unreachable, historical), they can be marked with `is_skipped: true` — either by the end user in the hosted flow (if the role's settings allow skipping) or by an analyst from the console. Skipped parties are excluded from the verification gate but still surface in the response for audit.

## Cross-referencing across sources

Data about each key person can come from three places, and the console shows all three side-by-side:

* **Registry records** — what the official registry disclosed.
* **User-submitted** — what the business admin confirmed or added in the Key People flow.
* **Uploaded documents** — names extracted via OCR from articles of association, shareholder registers, or power-of-attorney documents.

Inconsistencies surface as warnings on the session decision.

## Effect on the Business entity

Linking a key person to a User entity via KYC creates a lasting relationship on the [Business entity](/entities/businesses/overview). You can then:

* See every business each person serves in a governance or ownership role.
* Propagate a User's status changes (flagged, blocked) into businesses where they serve as a key person.
* Run ongoing AML monitoring on each linked person independent of any specific KYB session.

## Next steps

<CardGroup>
  <Card title="Key people" icon="users" href="/business-verification/key-people">
    The full Key People flow.
  </Card>

  <Card title="Ownership" icon="sitemap" href="/business-verification/ownership">
    UBO identification and ownership chains.
  </Card>

  <Card title="AML" icon="shield-check" href="/business-verification/aml">
    Company and person AML screening.
  </Card>
</CardGroup>


# Business Verification
Source: https://docs.didit.me/business-verification/overview

Verify companies and legal entities with automated registry lookups, UBO identification, officer screening, and AML — from $2.00 per check, priced per country and tier, no contracts.

This Didit Academy lesson follows a business verification from start to finish: the KYB dashboard, the registry check, shareholders and UBOs, AML screening, and what the company representative sees on their side.

<VideoEmbed title="Verify a business (KYB), start to finish — Didit Academy" />

Didit's Business Verification (KYB) lets you verify companies and legal entities before onboarding them to your platform. The system automates company registry lookups, identifies beneficial owners and officers, screens all parties against AML watchlists, and collects supporting documents — all within a single workflow. Each verified company is tracked as a [business profile](/business-verification/business-profiles), aggregating results across sessions.

New to Didit KYB? Start with the [quickstart](/business-verification/quickstart) for a 10-minute end-to-end walkthrough, then read the [integration guide](/business-verification/integration-guide) for production patterns. For the underlying Business entity model (linking to Users, blocklists, import/export), see [Businesses](/entities/businesses/overview).

## How it works

<Steps>
  <Step title="Create a business session" icon="building">
    Start a business verification by creating a session with a **KYB workflow**. When the workflow type is KYB, Didit automatically creates a business session:

    ```bash theme={null}
    curl -X POST https://verification.didit.me/v3/session/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "workflow_id": "your-kyb-workflow-id",
        "vendor_data": "company-123"
      }'
    ```

    The session type is determined by the workflow — no extra fields needed. KYB workflows automatically create business sessions with business-specific features enabled.
  </Step>

  <Step title="Company registry lookup" icon="magnifying-glass">
    Didit queries official company registries at the **Lite**, **Shareholders**, or **UBOs** tier — each priced per country, see [registry pricing](/getting-started/kyb-registry-pricing). Lite retrieves:

    | Data                    | Description                                 |
    | ----------------------- | ------------------------------------------- |
    | **Company name**        | Legal name as registered                    |
    | **Registration number** | Official company registration number        |
    | **Country**             | Country of incorporation                    |
    | **Status**              | Active, dissolved, struck off, etc.         |
    | **Company type**        | Ltd, LLC, PLC, SA, GmbH, etc.               |
    | **Incorporation date**  | Date the company was registered             |
    | **Registered address**  | Official registered office address          |
    | **Tax number**          | Tax identification number (where available) |

    Registry data is cross-referenced with the information provided to detect inconsistencies.
  </Step>

  <Step title="Key people — UBOs, shareholders, directors & representatives" icon="users">
    The system identifies every person and corporate entity tied to the business under the unified **Key People** model:

    * **UBOs** — individuals who ultimately own or control the company, with ownership and voting percentages
    * **Shareholders** (individual and corporate) — each with their ownership percentage
    * **Directors, representatives, secretaries, authorized signatories, and other officer roles** — with their specific role tag
    * **Corporate ownership layers** — parent companies in the ownership chain, with optional nested KYB

    A single person can carry multiple role tags (for example, director **and** shareholder). Each role is individually configured in the workflow — which roles require KYC, which KYC workflow to use, and whether the end user can skip verification. Learn more in [Key People](/business-verification/key-people) and [Ownership](/business-verification/ownership).
  </Step>

  <Step title="AML screening" icon="shield-check">
    All identified parties are automatically screened against global AML watchlists:

    * **Company AML** — screens the company entity against sanctions, adverse media, and regulatory enforcement lists
    * **Person AML** — screens each key person (UBO, shareholder, director, representative, etc.) individually
    * Uses the same [two-score risk system](/core-technology/aml-screening/overview) (match score + risk score) as user verification
  </Step>

  <Step title="Document collection" icon="file-lines">
    Collect and verify supporting documents:

    | Document type                    | Examples                                                     |
    | -------------------------------- | ------------------------------------------------------------ |
    | **Certificate of incorporation** | Company formation certificate                                |
    | **Articles of association**      | Bylaws, memorandum of association                            |
    | **Proof of address**             | Utility bills, bank statements for the registered address    |
    | **Shareholder register**         | Official register of shareholders                            |
    | **Financial statements**         | Annual accounts, audit reports                               |
    | **Tax certificates**             | Tax registration or compliance certificates                  |
    | **Custom documents**             | Any additional documents required by your compliance process |

    Analysts can request additional documents from the business during the review process.
  </Step>

  <Step title="Review and decide" icon="gavel">
    The business session receives an overall status based on all checks:

    | Status        | Meaning                                                              |
    | ------------- | -------------------------------------------------------------------- |
    | **Approved**  | All checks passed — company is verified                              |
    | **In Review** | One or more checks require manual review                             |
    | **Declined**  | A critical check failed (e.g., dissolved company, sanctioned entity) |

    Analysts can review all collected data in the Business Console, add comments, request additional documents, and make a final decision.
  </Step>
</Steps>

## Business session lifecycle

Each business verification runs within a **business session** that tracks progress through the following statuses:

| Status        | Description                                                                                    |
| ------------- | ---------------------------------------------------------------------------------------------- |
| `NOT_STARTED` | Session created but verification has not begun                                                 |
| `IN_PROGRESS` | Verification is underway — registry lookups, AML screening, or document collection in progress |
| `APPROVED`    | All checks passed — company is verified                                                        |
| `DECLINED`    | A critical check failed (e.g., dissolved company, sanctioned entity)                           |
| `IN_REVIEW`   | One or more checks require manual analyst review                                               |
| `RESUBMITTED` | Previously declined session resubmitted with updated data                                      |

Each session has a unique `session_id`, a sequential `session_number`, and a `session_token` for the hosted verification link. When a session is created with a `vendor_data` identifier, Didit automatically links it to the corresponding [business profile](/business-verification/business-profiles).

## Feature statuses

Business verification tracks the status of each component independently:

| Feature            | Description                                                  |
| ------------------ | ------------------------------------------------------------ |
| **Registry check** | Company registry lookup and data extraction                  |
| **Company AML**    | Company-level AML screening against sanctions and watchlists |
| **Documents**      | Document collection, OCR, and cross-referencing              |
| **Key people**     | Beneficial owner and officer identification, AML, and KYC    |

Each feature can be: `NOT_FINISHED`, `APPROVED`, `DECLINED`, `IN_REVIEW`, or `RESUB_REQUESTED`. The overall session status aggregates the individual feature statuses — the session is only `APPROVED` when all required features pass.

## Webhook events

Business sessions generate the following webhook events:

| Event                     | Trigger                                                                                                          |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `status.updated`          | Session status changed. Payload carries `session_kind: "business"` for KYB sessions.                             |
| `data.updated`            | Session data changed (registry, key people, documents, AML). Payload carries `session_kind: "business"`.         |
| `business.status.updated` | The linked [Business entity](/entities/businesses/overview)'s status changed (`ACTIVE` / `FLAGGED` / `BLOCKED`). |
| `business.data.updated`   | The linked Business entity's profile fields or aggregate counters changed.                                       |

Webhook payloads include `session_kind: "business"` and the `business_session_id` to distinguish them from user verification events. See [Webhooks](/integration/webhooks) for signature verification and delivery details.

## Key capabilities

| Capability                     | Description                                                                                                                                                   |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Automated registry lookups** | Query official company registries in supported countries at the Lite, Shareholders, or UBOs tier, [priced per country](/getting-started/kyb-registry-pricing) |
| **UBO identification**         | Automatically extract beneficial ownership structures with percentages                                                                                        |
| **Officer screening**          | Identify and verify directors, secretaries, and other officers                                                                                                |
| **Company AML**                | Screen the company entity against sanctions and watchlists                                                                                                    |
| **Person AML**                 | Screen all identified UBOs and officers individually                                                                                                          |
| **KYC linking**                | Link each identified person to a User Verification (KYC) session for identity verification                                                                    |
| **Document collection**        | Structured document requests with upload tracking                                                                                                             |
| **OCR cross-checking**         | Extract data from uploaded documents and cross-reference with registry data                                                                                   |
| **Business profiles**          | Automatic profile creation and session aggregation for each verified company                                                                                  |
| **Feature-level statuses**     | Independent status tracking for registry, AML, documents, and key people                                                                                      |
| **Risk assessment**            | Overall risk level based on company status, AML results, and ownership complexity                                                                             |
| **Webhooks**                   | Receive session lifecycle and data update events in real time via [webhooks](/integration/webhooks)                                                           |

## Business sessions vs. user sessions

| Feature               | User session                        | Business session                                             |
| --------------------- | ----------------------------------- | ------------------------------------------------------------ |
| **Target**            | Individual person                   | Company or legal entity                                      |
| **Session kind**      | `user` (default)                    | `business`                                                   |
| **Core checks**       | ID, liveness, face match, AML       | Registry lookup, UBO, officers, company AML                  |
| **Additional checks** | Phone, email, proof of address, NFC | Document collection, person AML, KYC linking                 |
| **Webhook payloads**  | Standard session events             | Include `session_kind: "business"` and `business_session_id` |

## Next steps

<CardGroup>
  <Card title="Business profiles" icon="address-card" href="/business-verification/business-profiles">
    Track companies across sessions with profiles, tags, and bulk operations.
  </Card>

  <Card title="Company data" icon="building" href="/business-verification/company-data">
    Registry lookups, company status, and data cross-referencing.
  </Card>

  <Card title="Ownership structure" icon="sitemap" href="/business-verification/ownership">
    UBO identification, corporate shareholders, and ownership chains.
  </Card>

  <Card title="Officers & directors" icon="user-tie" href="/business-verification/officers">
    Director identification, roles, and KYC linking.
  </Card>

  <Card title="AML screening" icon="shield-check" href="/business-verification/aml">
    Company and person-level AML checks.
  </Card>

  <Card title="Documents" icon="file-lines" href="/business-verification/documents">
    Document collection, requests, and OCR verification.
  </Card>
</CardGroup>


# Ownership & UBO
Source: https://docs.didit.me/business-verification/ownership

Extract Ultimate Beneficial Owners (UBOs) from company registries with ownership chains, percentages, and automated AML screening. From $2.00 per check, priced per country and tier.

Identifying who ultimately owns and controls a company is the heart of KYB. Didit pulls the ownership structure from the registry where available, lets the business admin confirm and extend it in the hosted flow, and then runs role-aware verification on each key person.

## Beneficial owners (UBOs)

An **Ultimate Beneficial Owner (UBO)** is a natural person who ultimately owns or controls a legal entity. UBOs surface in the session decision under `key_people_checks[].registry.beneficial_owners[]` (registry-derived) and `key_people_checks[].submitted.parties[]` (user-submitted), with any other role such as shareholder or director in the same list.

## Data collected for each key person

The hosted flow collects a default set of fields plus any workflow-configured custom fields. The defaults:

| Field                                             |   Person   |           Company           |
| ------------------------------------------------- | :--------: | :-------------------------: |
| `name` or `first_name` + `last_name`              | ✅ required | ✅ required (`company_name`) |
| `email`                                           | ✅ required |          ✅ required         |
| `nationality` / country                           | ✅ required |          ✅ required         |
| `role` (one or more per party)                    | ✅ required |          ✅ required         |
| `ownership_percent` / `voting_percent` (per role) |  optional  |           optional          |
| `date_of_birth`                                   |  optional  |              —              |
| `phone_number`                                    |  optional  |              —              |
| `position` (free-text job title)                  |  optional  |              —              |
| `registration_number`                             |      —     |           optional          |
| `entity_type`                                     |  `person`  |          `company`          |

`entity_type` is set automatically based on whether the party is a natural person or a corporate entity.

### Custom fields

Workflows can require additional fields per person or per company — any number of them. They're configured in the Business Console on the KYB workflow and end up in the `custom_fields` object on each party in the decision response. Use custom fields for things like source-of-wealth declarations, tax residency, internal client IDs, or industry-specific disclosures.

## Corporate shareholders and nested ownership

When a shareholder is itself a company (not a natural person), Didit records:

* Company name and registration number.
* Ownership percentage held by that corporate shareholder.
* Country of incorporation.

This lets you trace the chain through multiple layers to the ultimate natural persons.

### Nested KYB for corporate UBOs

When the workflow enables nested KYB for corporate UBOs, each corporate party triggers its own child KYB sub-session — the company verifies under the same process you run at the top level, and its result feeds back into the parent. Off by default; opt in per workflow.

## Ownership thresholds

Most jurisdictions classify UBOs at **25% or more**. The threshold is configurable per workflow:

| Jurisdiction | Typical UBO threshold                |
| ------------ | ------------------------------------ |
| EU (AMLD)    | 25% ownership or control             |
| UK           | 25% shares or voting rights          |
| USA (CTA)    | 25% ownership or substantial control |
| Singapore    | 25% shares or voting power           |

Set it from *Workflows → \[KYB workflow] → Risk → UBO threshold*. Your workflow can also flag or route for review when no UBO meets the threshold (common with widely-held public companies).

## Voting vs economic rights

Ownership disclosures distinguish two kinds of control:

| Right                      | What it means                                           |
| -------------------------- | ------------------------------------------------------- |
| **Economic (ownership) %** | Share of the company's economic value / dividend rights |
| **Voting %**               | Share of voting power on shareholder resolutions        |

These are usually equal but can diverge when a company issues dual-class shares or preferred equity. Didit records both. Rules and thresholds can check either — most jurisdictions require UBO disclosure when *either* crosses 25%.

## Effective ownership through a chain

When ownership runs through a corporate shareholder, effective ownership of a downstream natural person is computed by multiplying percentages along the chain.

### Example — 3-layer chain

```
Acme Corp (target)
  └─ 60% → Acme Holdings Ltd
              └─ 75% → Jane Doe (natural person)
  └─ 40% → John Smith (natural person)
```

Computed UBOs:

* **Jane Doe** — effective ownership of Acme Corp = 60% × 75% = **45%** (UBO).
* **John Smith** — effective ownership of Acme Corp = **40%** (UBO).

With a 25% UBO threshold, both Jane and John are disclosed. With a 50% threshold, no UBO meets the cut — Didit flags this as a transparency concern.

## How role settings drive verification

Each role is individually configured per KYB workflow: enabled or disabled, whether it requires KYC, which KYC workflow to use for that role, and whether the end user can choose to skip it. When a key person is submitted:

1. Didit checks the submitted party's roles against the workflow's role settings.
2. For roles marked as requiring verification, a child verification session is started:
   * **Person parties** → child User Verification (KYC) session, using either the role-specific KYC workflow or the default.
   * **Corporate UBOs** (when nested KYB is enabled) → child Business Verification (KYB) sub-session.
3. For roles marked as skippable, the end user sees a "skip verification" option and can opt out; skipped parties are recorded but don't block the parent session.
4. Parties below the workflow's ownership threshold don't trigger individual verification even if the role would otherwise require it.

Configure everything from *Workflows → \[KYB workflow] → Key People* in the Business Console.

## Monitoring shareholders and UBOs

<Note>
  Registry monitoring is **coming soon**. No country in the staging retail catalog checked on September 7, 2026 has monitoring enabled. The configured rate is USD 2.00 per company per year; a price does not mean the feature is available. The behavior below describes the planned service after rollout.
</Note>

A company verified at the **Shareholders** or **UBO** tier can be kept under **continuous registry monitoring**. The registry pushes changes of company status, officers, ownership and registered address; on each change Didit:

* moves the business session from *Approved* back to *In Review*, with the change recorded on the session;
* fires the `kyb_registry_change` [business webhook](/business-verification/webhooks) with the fields that changed;
* keeps the company's registry record current.

Monitoring is **only available where the country allows it**: the registry provider must offer a watch for that jurisdiction. The full list is the [continuous monitoring countries table](/business-verification/supported-countries#continuous-registry-monitoring); a company verified at the Lite tier, or in a country outside that list, is not enrolled and the business page shows why.

Enable it per workflow from *Workflows → KYB Registry Check → Advanced → Continuous registry monitoring*. It costs **\$2.00 per company per year**, billed on enrolment and on each yearly renewal; when the wallet cannot cover a renewal, monitoring stops for that company instead of running unpaid. Cancel it at any time from the business page (*KYB Registry Check → Registry monitoring*).

## Registry vs user-submitted reconciliation

The response surfaces both sources side-by-side under `key_people_checks[]`:

* `registry.officers[]` and `registry.beneficial_owners[]` — what the provider disclosed.
* `submitted.parties[]` — what the business admin explicitly submitted through the flow, with `source: "USER"`.

Analysts compare the two buckets visually in the console to spot missing UBOs, extra undisclosed parties, or ownership percentages that don't line up. There's no automated diff endpoint — you can reconcile on your side by matching on name, role, and ownership where applicable.

## AML screening

Every identified key person is automatically screened against global AML watchlists, both from the registry side and the submitted side. See [Business AML screening](/business-verification/aml) for how company-level and person-level AML checks combine.

## Next steps

<CardGroup>
  <Card title="Key people" icon="users" href="/business-verification/key-people">
    The Key People flow end-to-end.
  </Card>

  <Card title="Officers & representatives" icon="user-tie" href="/business-verification/officers">
    Governance roles inside the key-people model.
  </Card>

  <Card title="Risk assessment" icon="gauge" href="/business-verification/risk-assessment">
    How ownership complexity rolls into risk level.
  </Card>
</CardGroup>


# KYB quickstart: business verification in 10 minutes
Source: https://docs.didit.me/business-verification/quickstart

Verify a business end-to-end in under 10 minutes — registry lookup, UBO, officers, AML, and webhooks. From $2.00 per check, priced per country and tier, no contracts.

This guide walks you through a complete KYB verification in under 10 minutes. You'll create a workflow, start a session, deliver the hosted verification link to your business contact, wait for the webhook, and fetch the final decision.

## Prerequisites

* A Didit application with KYB enabled. Create one at [business.didit.me](https://business.didit.me) if needed.
* An API key from *Developer Settings → API Keys*.
* A webhook endpoint reachable from the internet (for the decision webhook).

## Steps

<Steps>
  <Step title="Create a KYB workflow in the console">
    Navigate to *Workflows → Create workflow*. Choose **Business Verification** as the workflow type.

    Enable the features you need:

    * **Company registry lookup** (required)
    * **Company AML** (recommended)
    * **Key People** (required for most regulated industries)
    * **Documents** (optional — pick document types you'll require)

    Save and copy the `workflow_id` — you'll use it in the next step.
  </Step>

  <Step title="Create a Business Verification (KYB) session via the API">
    ```bash theme={null}
    curl -X POST https://verification.didit.me/v3/session/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "workflow_id": "YOUR_KYB_WORKFLOW_ID",
        "vendor_data": "biz-acme-001"
      }'
    ```

    The response contains the `session_id`, `session_number`, and `url` — the hosted verification link you deliver to the business contact. The workflow's type (KYB) automatically flags the session as a business session.
  </Step>

  <Step title="Send the link to your business contact">
    Deliver the `url` to the company admin via your own email or chat. They open it, fill in the registry data, add key people and UBOs, and upload documents.

    You can customize the hosted experience with branding, logo, and domain — see [White-label](/console/white-label).
  </Step>

  <Step title="Receive the status webhook">
    When the business finishes the flow and KYB processing reaches a terminal status, Didit POSTs a `status.updated` event to your webhook endpoint. Business-session events carry `session_kind: "business"` inside `data` — filter on that to route the event to your KYB handler.

    Verify the `X-Signature-V2` HMAC signature before trusting the event (see [webhooks](/integration/webhooks)), then trigger your downstream logic. Store the destination's `secret_shared_key` (returned when you register the webhook) as `DIDIT_WEBHOOK_SECRET` in your `.env`.

    Example payload:

    ```json theme={null}
    {
      "event": "status.updated",
      "application_id": "app_abc123",
      "timestamp": "2026-04-18T12:30:00Z",
      "data": {
        "session_id": "bs_01H...",
        "session_kind": "business",
        "vendor_data": "biz-acme-001",
        "status": "APPROVED",
        "previous_status": "IN_PROGRESS"
      }
    }
    ```
  </Step>

  <Step title="Retrieve the decision (optional)">
    <Note>
      The `status.updated` webhook payload already contains the full decision. You only need to call this endpoint if you didn't subscribe to webhooks, or you want to fetch the decision on demand later.
    </Note>

    ```bash theme={null}
    curl https://verification.didit.me/v3/session/bs_01H.../decision/ \
      -H "x-api-key: YOUR_API_KEY"
    ```

    The decision includes registry data, key people (UBOs, shareholders, directors and representatives), AML hits, documents, and per-feature results. See [response schema](/business-verification/response-schema) for the full payload reference.
  </Step>

  <Step title="Act on the decision">
    Based on `status`:

    * `APPROVED` — onboard the business.
    * `DECLINED` — reject and log the reason code.
    * `IN_REVIEW` — wait for the analyst decision; you'll receive another webhook when it resolves.
  </Step>
</Steps>

## Node.js example

```typescript theme={null}
import fetch from 'node-fetch';

const API_KEY = process.env.DIDIT_API_KEY!;
const WORKFLOW_ID = process.env.DIDIT_KYB_WORKFLOW_ID!;
const BASE_URL = 'https://verification.didit.me';

async function startKybVerification(vendorData: string) {
  const res = await fetch(`${BASE_URL}/v3/session/`, {
    method: 'POST',
    headers: {
      'x-api-key': API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({ workflow_id: WORKFLOW_ID, vendor_data: vendorData }),
  });
  if (!res.ok) throw new Error(`Session create failed: ${res.status}`);
  return res.json();
}

async function getDecision(sessionId: string) {
  const res = await fetch(`${BASE_URL}/v3/session/${sessionId}/decision/`, {
    headers: { 'x-api-key': API_KEY },
  });
  return res.json();
}

// Kick off the flow
const { session_id, url } = await startKybVerification('biz-acme-001');
console.log('Deliver this URL to your contact:', url);

// ... later, after the webhook confirms completion:
const decision = await getDecision(session_id);
console.log('KYB status:', decision.status);
```

## What happens automatically

* Company registry lookup against 190+ jurisdictions.
* UBO and officer extraction from registry data.
* Company-level AML screening (sanctions, PEP, adverse media).
* Person-level AML for each identified party.
* Document OCR and cross-referencing.
* [Business profile](/business-verification/business-profiles) creation and aggregation keyed by `vendor_data`.

## Next steps

<CardGroup>
  <Card title="Integration guide" icon="book" href="/business-verification/integration-guide">
    End-to-end architecture, polling vs webhooks, retry logic.
  </Card>

  <Card title="KYB webhooks" icon="bolt" href="/business-verification/webhooks">
    Every KYB event and payload shape.
  </Card>

  <Card title="Statuses" icon="list-check" href="/business-verification/statuses">
    Session, feature, and registry status reference.
  </Card>

  <Card title="Response schema" icon="file-lines" href="/business-verification/response-schema">
    The full KYB decision payload.
  </Card>

  <Card title="Business entities" icon="building" href="/entities/businesses/overview">
    How profiles aggregate across sessions.
  </Card>
</CardGroup>


# KYB Response Schema
Source: https://docs.didit.me/business-verification/response-schema

Annotated KYB decision payload: registry checks, key people, UBO KYC summaries, documents, AML screenings, and shared fields. From $2.00 per check, priced per country and tier.

This page documents the full payload returned by [`GET /v3/session/{id}/decision/`](/sessions-api/retrieve-session) for a Business Verification (KYB) session. The endpoint is unified — when you pass a business `session_id`, the response carries `session_kind: "business"` and the business-specific feature arrays below.

## Top-level structure

```json theme={null}
{
  "session_id": "bs_01H...",
  "session_kind": "business",
  "session_number": 89,
  "session_url": "https://verify.didit.me/...",
  "status": "APPROVED",
  "workflow_id": "wf_kyb_standard",
  "features": ["KYB_REGISTRY", "KYB_COMPANY_AML", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE"],
  "vendor_data": "biz-acme-001",
  "metadata": { },
  "callback": null,

  "registry_checks": [ ... ],
  "aml_screenings": [ ... ],
  "document_verifications": [ ... ],
  "key_people_checks": [ ... ],

  "phone_verifications": null,
  "email_verifications": null,
  "questionnaire_responses": null,
  "ip_analyses": null,

  "reviews": [ ],
  "contact_details": { ... },
  "expected_details": null,
  "created_at": "...",
  "expires_at": "..."
}
```

All feature arrays are multi-instance — each item represents one node in a graph workflow. Null means the feature was not present in this session's workflow.

## Shared top-level fields

| Field                      | Type             | Description                                                                                                                                                                                |
| -------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `session_id`               | UUID             | Unique session identifier                                                                                                                                                                  |
| `session_kind`             | enum             | Always `"business"` for KYB sessions                                                                                                                                                       |
| `session_number`           | int              | Sequential number within the application                                                                                                                                                   |
| `session_url`              | URL              | Hosted verification link                                                                                                                                                                   |
| `status`                   | enum             | Overall session status (see [statuses](/business-verification/statuses))                                                                                                                   |
| `workflow_id`              | UUID             | Workflow that drove this session                                                                                                                                                           |
| `features`                 | array of strings | Feature identifiers the workflow ran (e.g. `KYB_REGISTRY`, `AML`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE`, `PHONE`, `EMAIL`)                                                                     |
| `vendor_data`              | string           | Your identifier for the business                                                                                                                                                           |
| `metadata`                 | object           | Free-form JSON you attached at session creation                                                                                                                                            |
| `callback`                 | URL or null      | Optional post-verification redirect URL                                                                                                                                                    |
| `contact_details`          | object or null   | `{ email, email_lang, send_notification_emails, phone }` — set when the flow includes email/phone notifications                                                                            |
| `expected_details`         | object or null   | Business expected-data payload you passed on creation: `company_name`, `registry_country` (`XX` or `XX-YY` with the state for state-level registries, e.g. `US-CA`), `registration_number` |
| `reviews`                  | array            | Latest reviewer notes on the session                                                                                                                                                       |
| `created_at`, `expires_at` | ISO timestamps   | —                                                                                                                                                                                          |

## `registry_checks[]`

Each item is one company registry check (typically one per session; multiple in graph workflows with recursive corporate UBO KYB).

```json theme={null}
{
  "status": "Approved",
  "node_id": "feature_kyb_registry",
  "data_resolved": true,
  "company": { ...see below... },
  "ownership_structure": { },
  "warnings": []
}
```

| Field                 | Description                                                                                                                             |
| --------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `status`              | Feature lifecycle status (`Approved`, `Declined`, `In Review`, `Not Finished`, `Resub Requested`)                                       |
| `node_id`             | Graph node identifier for this check                                                                                                    |
| `data_resolved`       | `true` when registry data has finished loading or the user provided the data manually                                                   |
| `company`             | Full registry payload — see **`company` block** below                                                                                   |
| `ownership_structure` | Raw ownership-chain JSON as returned by the registry provider                                                                           |
| `warnings`            | Structured warnings / log entries scoped to this registry check. See [Business Verification warnings](/business-verification/warnings). |

### `company` block

The nested company object is the full view of the legal entity as derived from the registry (and optionally user-edited):

```json theme={null}
{
  "uuid": "...",
  "node_id": "feature_kyb_registry",
  "status": "Approved",
  "registry_status": "active",
  "data_resolved": true,
  "company_name": "Acme Corporation Limited",
  "registration_number": "12345678",
  "country_code": "GBR",
  "company_type": "Private Limited",
  "incorporation_date": "2010-05-14",
  "registered_address": "1 Main Street, London EC1A 1AA, United Kingdom",
  "tax_number": "SAMPLE-TAX-12345",
  "risk_level": "LOW",
  "verification_status": "verified",
  "is_from_registry": true,
  "fetch_status": "resolved",
  "alternative_names": "Acme Ltd",
  "nature_of_business": "Software publishing",
  "registered_capital": "100000 GBP",
  "website": "https://acme.example",
  "email": "alex.sample@example.com",
  "phone": "+15550101000",
  "legal_entity_identifier": "529900XXXXXXXXXXXXX",
  "location_of_registration": "London",
  "vat_number": "GB123456789",
  "vat_validation_status": "not_applicable",
  "vat_validated_name": null,
  "vat_validated_address": null,
  "vat_checked_at": null,
  "financial_summary": { },
  "officers": [ ... ],
  "beneficial_owners": [ ... ],
  "addresses": [ ... ],
  "industries": [ ... ],
  "accounts": { ... },
  "registry_data": { },
  "user_provided_data": { },
  "confirmed_by_user_at": "2026-04-16T10:10:00Z",
  "last_console_edit_at": null,
  "is_editable": false
}
```

| Field                                          | Description                                                                                                                                                                                                             |
| ---------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `registry_status`                              | Provider-reported status (`active`, `dissolved`, `struck_off`, `inactive`, etc.). See [statuses](/business-verification/statuses#registry-status-from-the-provider)                                                     |
| `is_from_registry`                             | `true` when data came from an official registry; `false` for manual entry                                                                                                                                               |
| `fetch_status`                                 | `pending`, `resolved`, or `failed` — registry lookup state                                                                                                                                                              |
| `verification_status`                          | `verified`, `failed`, or `unknown`                                                                                                                                                                                      |
| `is_editable`                                  | `true` while registry-sourced data can still be edited by the end user                                                                                                                                                  |
| `registry_data` / `user_provided_data`         | Raw JSON for registry-returned vs user-entered fields (useful for audit diffing)                                                                                                                                        |
| `confirmed_by_user_at`                         | Timestamp when the end user confirmed / edited the registry data                                                                                                                                                        |
| `vat_number`                                   | VAT number as submitted, when collected                                                                                                                                                                                 |
| `vat_validation_status`                        | Result of the EU VIES check: `valid`, `invalid`, `could_not_validate`, or `not_applicable` (non-EU companies, or no VAT number provided). See [VAT validation](/business-verification/company-data#vat-validation-vies) |
| `vat_validated_name` / `vat_validated_address` | Trader name and address registered with VIES, when the member state discloses them                                                                                                                                      |
| `vat_checked_at`                               | Timestamp of the VIES check; `null` when no check ran                                                                                                                                                                   |
| `officers[]`                                   | Officers with embedded KYC enrichment (see below)                                                                                                                                                                       |
| `beneficial_owners[]`                          | UBOs with embedded KYC enrichment (see below)                                                                                                                                                                           |
| `addresses`, `industries`, `accounts`          | Extracted from `registry_data` when available                                                                                                                                                                           |

When reported, `industries` includes classification entries with `code` and `description`, and `addresses` includes entries with `address`, `type`, and `description`.
`accounts` can include `last_annual_return_date` and `last_agm_date`; these describe corporate filings and meetings, not financial statements.
Industry descriptions or a registry business scope populate `nature_of_business`.
Contact details and alternative names are populated when available, while explicit user or reviewer edits take precedence.

### Officer item shape (inside `company.officers`)

```json theme={null}
{
  "uuid": "...",
  "name": "Jane Doe",
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": null,
  "date_of_birth_year": 1983,
  "date_of_birth_month": 2,
  "address": "1 Example Street, London",
  "appointment_date": "2024-07-01",
  "termination_date": null,
  "designation": "Director",
  "role": "director",
  "nationality": "USA",
  "is_active": true,
  "kyc_status": "Approved",
  "kyc_session_url": "https://verify.didit.me/..."
}
```

`date_of_birth` is populated only when the registry supplies a complete date.
If the registry reports only a year or month and year, use `date_of_birth_year` and `date_of_birth_month`; the missing day is never inferred.
Names, birth details, address, and appointment dates remain available in both the company officer list and the Key People registry list.

### Beneficial owner item shape (inside `company.beneficial_owners`)

```json theme={null}
{
  "uuid": "...",
  "name": "John Doe",
  "first_name": "John",
  "last_name": "Doe",
  "entity_type": "person",
  "date_of_birth": null,
  "country_of_birth": null,
  "email": null,
  "company_name": null,
  "registration_number": null,
  "nationality": null,
  "designation": null,
  "appointment_date": null,
  "voting_min_shares": null,
  "voting_max_shares": null,
  "roles": ["ubo"],
  "ownership_min_shares": "40",
  "ownership_max_shares": "40",
  "is_active": true,
  "kyc_status": "Pending",
  "kyc_session_url": "https://verify.didit.me/...",
  "effective_ownership_percent": 40.0
}
```

`kyc_status` uses a B2C-safe projection: `Approved`, `Declined`, or `Pending` (full session states collapse to `Pending` until the KYC finishes).

## `key_people_checks[]`

This is the **aggregate check** over all officers and UBOs for the session. It exposes two buckets so the console can render "extracted from the registry" side-by-side with "submitted by the business", plus a high-level UBO KYC summary.

```json theme={null}
{
  "status": "Approved",
  "node_id": "feature_kyb_key_people",
  "registry": {
    "officers": [ ...registry-derived officers... ],
    "beneficial_owners": [ ...registry-derived UBOs... ]
  },
  "submitted": {
    "parties": [ ...user-submitted key-people records... ]
  },
  "ubo_kyc_summary": {
    "total": 2,
    "approved": 1,
    "flagged": 0,
    "pending": 1
  },
  "warnings": []
}
```

* **`registry.officers` / `registry.beneficial_owners`** — parties extracted from the registry check.
* **`submitted.parties`** — parties the business admin explicitly added during the Key People flow (records with `source = "USER"`).

### `registry.officers[]` / `registry.beneficial_owners[]`

The registry facts match `company.officers` / `company.beneficial_owners` above.
Key People additionally includes AML status and detailed verification linkage, such as `kyc_session_id` and verification workflow fields.
The company lists retain their existing simplified KYC status and verification URL.

### `submitted.parties[]`

User-submitted parties carry their KYC or child-KYB linkage:

```json theme={null}
{
  "uuid": "...",
  "entity_type": "person",
  "name": "Alice Chen",
  "first_name": "John",
  "last_name": "Doe",
  "email": "alex.sample@example.com",
  "role": "ubo",
  "ownership_percent": 35.0,
  "nationality": "USA",
  "position": "CEO",
  "date_of_birth": "1990-01-01",
  "phone_number": "+34612345678",
  "source": "USER",
  "requires_verification": true,
  "is_skipped": false,
  "kyc_session_id": "sess-xyz...",
  "kyc_session_status": "Not Started",
  "kyc_session_url": "https://verify.didit.me/...",
  "kyc_session_deleted": false,
  "custom_fields": { }
}
```

Corporate parties (`entity_type: "company"`) additionally carry `company_name`, `registration_number`, and `kyb_sub_session_id` / `kyb_sub_session_status` / `kyb_sub_session_deleted` when nested KYB is enabled for corporate UBOs.

`kyc_session_deleted` (and its corporate counterpart `kyb_sub_session_deleted`) is `true` when the party's child session was deleted. A deleted child keeps whatever status it had at deletion time and can never settle, so read this flag rather than the status: the matching `*_session_url` is returned as `null` because the link no longer resolves, and the Key People check drops to `In Review` instead of waiting forever. Deleting a child session never counts as a pass. Exempt the party with [`PATCH /v3/session/{id}/kyb/parties/{party_uuid}/`](/sessions-api/update-data#skip-a-key-people-party) to let the KYB settle.

### `ubo_kyc_summary`

Aggregate UBO KYC progress — useful for a single dashboard card:

| Field      | Meaning                                              |
| ---------- | ---------------------------------------------------- |
| `total`    | Number of active UBOs that have a linked KYC session |
| `approved` | UBOs whose KYC session is `APPROVED`                 |
| `flagged`  | UBOs whose KYC session is `DECLINED` or `IN_REVIEW`  |
| `pending`  | Everyone else (not yet finished)                     |

Returns `null` when no UBOs have linked KYC sessions.

## `document_verifications[]`

Documents grouped by node:

```json theme={null}
{
  "status": "Approved",
  "node_id": "feature_kyb_documents",
  "items": [
    {
      "uuid": "...",
      "document_type": "certificate_of_incorporation",
      "status": "Approved",
      "file_url": "https://didit-storage.s3...",
      "document_metadata": {
        "file_size": 246810,
        "content_type": "application/pdf",
        "creation_date": "2024-05-15",
        "modified_date": "2024-05-15",
        "overlay_manipulation": null
      },
      "ocr_data": {
        "company_name": "Acme Corporation Limited",
        "registration_number": "12345678",
        "incorporation_date": "2010-05-14"
      }
    }
  ],
  "groups": {
    "legal_presence": { "approved": 1, "pending": 0, "missing": 0 },
    "ownership_structure": { "approved": 1, "pending": 0, "missing": 0 }
  },
  "required_groups": ["legal_presence", "ownership_structure"],
  "warnings": []
}
```

| Field             | Description                                                                                                            |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------- |
| `items[]`         | Individual document rows — each has its own `status`, `file_url` (signed), `document_metadata`, and OCR extract        |
| `groups`          | Per-group progress counters — matches the [four KYB document groups](/business-verification/documents#document-groups) |
| `required_groups` | Groups your workflow marked as required; gate session approval on all being satisfied                                  |

### Corporate document metadata

For PDF corporate documents, `items[].document_metadata.overlay_manipulation` can include forensic evidence for suspected overlay-text editing. When present, it includes:

| Field                 | Description                                                                                                                   |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `detected`            | Whether overlay-text manipulation evidence was detected                                                                       |
| `analyzed`            | Whether the PDF could be analyzed                                                                                             |
| `signals`             | Forensic signals that fired, such as `duplicate_font_subset` or `glyph_fragmentation`                                         |
| `manipulated_regions` | PDF page-coordinate rectangles around suspected edited text: `page`, `x`, `y`, `width`, `height`, `page_width`, `page_height` |

The field is `null` when no overlay evidence was found, when the document is not a PDF, or when the PDF could not be analyzed.

## `aml_screenings[]`

Company-level and (when the workflow wires them) person-level AML screenings.

```json theme={null}
{
  "node_id": "feature_kyb_company_aml",
  "status": "Approved",
  "total_hits": 0,
  "score": 0,
  "entity_type": "COMPANY",
  "screened_data": {
    "company_name": "Acme Corporation Limited",
    "country_code": "GBR"
  },
  "is_ongoing_monitoring_enabled": true,
  "next_ongoing_monitoring_bill_date": "2027-04-16",
  "hits": [],
  "warnings": []
}
```

When `total_hits > 0`, each hit includes match score, risk score, watchlist sources, and a per-hit `review_status` you can update via the update-aml-hit-status endpoint. See [AML Screening report](/core-technology/aml-screening/report-aml-screening) for the hit structure.

## Shared feature arrays

`phone_verifications`, `email_verifications`, `questionnaire_responses`, `ip_analyses` use the same per-item shapes as user (KYC) sessions. They're `null` when the workflow doesn't include them. See the [KYC response](/sessions-api/retrieve-session) for item schemas.

## Warning feature groups

Business Verification warnings are grouped by the feature that produced them:

* `KYB_REGISTRY` for registry availability, ownership, company activity, and country-restriction issues.
* `KYB_DOCUMENTS` for corporate document extraction, cross-check, metadata, manipulation, subtype, age, and attempt-limit issues.
* `AML` for company AML screening matches or missing screening data.
* `KYB_KEY_PEOPLE` for person-level issues tied to directors, officers, UBOs, or representatives.
* `PHONE` for phone-number risk, duplication, blocklist, and verification-code attempt issues.
* `EMAIL` for email risk, deliverability, duplication, blocklist, and verification-code attempt issues.
* `QUESTIONNAIRE` for custom status rules driven by questionnaire answers.
* `LOCATION` for Device & IP Analysis, private-network, IP blocklist, device blocklist, and duplicate device/IP issues.

See [Business Verification warnings](/business-verification/warnings) for the full list of warning codes.

## Workflow-driven field filtering

Workflows can limit which nested fields appear on each feature item via `response_attributes`. Fields always included regardless: `status`, `warnings`, `node_id`. All other fields are nullified when not in the allow-list — the key stays in the response for schema stability.

## Next steps

<CardGroup>
  <Card title="Statuses" icon="list-check" href="/business-verification/statuses">
    What each status value means.
  </Card>

  <Card title="Risk assessment" icon="gauge" href="/business-verification/risk-assessment">
    How `risk_level` is computed.
  </Card>

  <Card title="AML report" icon="shield-check" href="/core-technology/aml-screening/report-aml-screening">
    Full AML hit payload reference.
  </Card>

  <Card title="Key people" icon="users" href="/business-verification/key-people">
    How parties flow from registry vs user submission into `registry` / `submitted` buckets.
  </Card>

  <Card title="Documents" icon="file-lines" href="/business-verification/documents">
    Document groups, OCR, and cross-reference.
  </Card>

  <Card title="Retrieve session" icon="arrow-down" href="/sessions-api/retrieve-session">
    Full endpoint reference including example responses.
  </Card>
</CardGroup>


# Risk Assessment
Source: https://docs.didit.me/business-verification/risk-assessment

Composite KYB risk level (LOW/MEDIUM/HIGH) and ownership complexity scoring across registry, AML, key people, documents, and country risk. From $2.00 per check, priced per country and tier.

Every KYB decision includes two composite risk signals on the registry check: `risk_level` (`LOW`, `MEDIUM`, `HIGH`) and `ownership_complexity` (`SIMPLE`, `COMPLEX`). They give your compliance team a quick directional read of the business without having to re-score each sub-check on your side.

## Inputs to `risk_level`

`risk_level` is a composite Didit computes from the checks that actually ran on the session. The main signals:

| Signal                           | Contribution                                                                                                                                                                                           |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Registry status**              | An `ACTIVE` / `AUTHORISED` company sits at the low end. `DISSOLVED`, `STRUCK_OFF`, `CLOSED`, `UNAUTHORISED` push toward high. `INACTIVE` or statuses that require manual inspection sit in the middle. |
| **Company AML screening**        | The company's AML score and hits count. Clean screens sit low; confirmed sanction or adverse-media matches push high.                                                                                  |
| **Person AML across key people** | The worst AML result across UBOs, directors, and other key people. Any confirmed sanction / PEP match pushes high.                                                                                     |
| **Document completeness**        | Whether every required document group is approved, vs missing or failed documents.                                                                                                                     |
| **Country of incorporation**     | Country risk tier, based on FATF and OFAC guidance and your dangerous-country policy.                                                                                                                  |

When `risk_level` is `HIGH`, the workflow typically routes the session to `IN_REVIEW` or `DECLINED` depending on your configuration.

<Note>
  Exact weighting evolves over time as we tune the model. Treat `risk_level` as a directional signal and combine it with your own policy before making onboarding decisions.
</Note>

## Inputs to `ownership_complexity`

`ownership_complexity` reflects how hard the ownership structure is to unpack. Simple structures have direct natural-person ownership with few UBOs and no opaque intermediaries; complex structures run through multiple corporate layers, cross-border holdings, or trust / foundation / nominee entities.

| Value     | Typical shape                                                                                    |
| --------- | ------------------------------------------------------------------------------------------------ |
| `SIMPLE`  | Direct natural-person ownership, few UBOs above threshold, no opaque corporate intermediaries    |
| `COMPLEX` | Multi-layer corporate chains, cross-border ownership, or trust / foundation / nominee structures |

`COMPLEX` doesn't automatically imply high risk — but it usually warrants enhanced due diligence.

## Configuration

Risk thresholds and related defaults are configurable per workflow in the Business Console:

* *Workflows → \[KYB workflow] → Risk → AML thresholds* — set the match-score and risk-score thresholds for approve/review/decline. See [AML risk score](/core-technology/aml-screening/aml-risk-score) and [AML match score](/core-technology/aml-screening/aml-match-score).
* *Workflows → \[KYB workflow] → Risk → UBO threshold* — ownership percentage at which someone is classified as a UBO (typically 10%, 25% or 50%).
* *Workflows → \[KYB workflow] → Risk → Document policy* — which documents are required vs optional.
* *Settings → Blocklist → Countries* — the dangerous-country list used in the country input.

## Illustrative examples

The examples below are illustrative of how different signals land — not an exact formula.

### Simple UK Ltd, clean AML

* Registry `ACTIVE`
* Company AML clean
* All key people AML clean
* Documents complete
* Country `GBR`

→ `risk_level = LOW`, `ownership_complexity = SIMPLE`. Approved.

### Multi-layer holding with a PEP UBO

* Registry `ACTIVE`
* Company AML clean
* One UBO has an `IN_REVIEW` PEP hit
* Documents complete
* Country `LUX`

→ `risk_level = MEDIUM`, `ownership_complexity = COMPLEX` (multi-layer chain). Session routes to `IN_REVIEW`.

### Sanctioned subsidiary detected

* Registry `ACTIVE`
* Company AML: confirmed sanctions match
* One director on a sanctions list

→ `risk_level = HIGH`. Session auto-declined with reason `aml_confirmed_sanction`.

## Risk color coding in the console

* 🟢 `LOW` — green badge.
* 🟡 `MEDIUM` — yellow badge.
* 🔴 `HIGH` — red badge.

`COMPLEX` ownership is shown alongside the risk badge with a small chain icon.

## Using the risk fields on your side

```typescript theme={null}
if (decision.status === 'APPROVED' && decision.risk_level === 'HIGH') {
  // Approved by the engine but still worth a manual reviewer glance
  await routeToEnhancedDueDiligence(decision);
}

if (decision.ownership_complexity === 'COMPLEX') {
  await requireExtraDocumentation(decision);
}
```

## Next steps

<CardGroup>
  <Card title="Statuses" icon="list-check" href="/business-verification/statuses">
    Status taxonomy.
  </Card>

  <Card title="AML scoring" icon="gauge" href="/core-technology/aml-screening/overview">
    Two-score system used throughout Didit.
  </Card>

  <Card title="Response schema" icon="file-lines" href="/business-verification/response-schema">
    Where risk fields appear.
  </Card>
</CardGroup>


# KYB Statuses
Source: https://docs.didit.me/business-verification/statuses

Full reference for KYB session, feature, registry lookup, AML statuses, and decision reason codes. From $2.00 per check, priced per country and tier.

Business Verification tracks status at multiple levels: the **session**, individual **features**, the **registry lookup**, and the **AML result**. This page is the reference for every state.

## Session status

The overall status of a Business Verification (KYB) session — the single field you'll most often switch on.

| Status          | Meaning                                                                                                                                                                               |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NOT_STARTED`   | Session created but business has not opened the hosted link.                                                                                                                          |
| `IN_PROGRESS`   | Hosted flow is active — registry lookups, document uploads, or AML screening in progress.                                                                                             |
| `AWAITING_USER` | Waiting for the end user to take an action (typically submit Key People, or respond to a resubmission request). Transitions automatically once the user completes the pending action. |
| `APPROVED`      | All required features passed. Business is verified.                                                                                                                                   |
| `DECLINED`      | A critical check failed (dissolved company, sanctioned entity, blocklisted) or workflow rule rejected.                                                                                |
| `IN_REVIEW`     | One or more features require manual analyst review.                                                                                                                                   |
| `RESUBMITTED`   | Previously declined/resub-requested session has been resubmitted with updated data.                                                                                                   |
| `ABANDONED`     | Business never completed the flow (timeout).                                                                                                                                          |
| `EXPIRED`       | Session expired before the business completed it.                                                                                                                                     |

<Note>
  `AWAITING_USER` is transient — you don't need to manually move sessions out of it. As soon as the end user completes the pending action (for example, submits the Key People list or re-uploads a requested document), Didit re-evaluates the session and transitions it automatically to `IN_REVIEW`, `APPROVED`, or `DECLINED` based on the outcome.
</Note>

## Feature status

Each KYB feature has its own status, which rolls up into the session status.

| Status            | Meaning                                                                                                                                                   |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NOT_FINISHED`    | Feature has not yet been started or is mid-run.                                                                                                           |
| `APPROVED`        | Feature passed.                                                                                                                                           |
| `DECLINED`        | Feature failed (critical).                                                                                                                                |
| `IN_REVIEW`       | Feature requires analyst attention.                                                                                                                       |
| `RESUB_REQUESTED` | Business must resubmit for this feature (e.g. re-upload a document).                                                                                      |
| `AWAITING_USER`   | Feature is waiting for an end-user action. Applies to the Key People feature while the user must submit parties. Automatically transitions on submission. |

### KYB feature names

* `kyb_registry` — company registry lookup.
* `kyb_company_aml` — company-level AML screening.
* `kyb_documents` — document collection and OCR.
* `kyb_key_people` — key people: UBOs, shareholders, directors, representatives and other officers.

## Registry status (from the provider)

The official status of the company as obtained from authoritative registry sources. Reflects the legal or regulatory standing of the entity as reported by the jurisdiction-specific registry, so exact values vary by source. Surfaced inside the KYB decision under `company.registry_status`.

| Status                     | Meaning                                              |
| -------------------------- | ---------------------------------------------------- |
| `ACTIVE`                   | Company is active and in good standing.              |
| `DISSOLVED`                | Company has been dissolved.                          |
| `DEREGISTERED`             | Company has been deregistered.                       |
| `STRUCK_OFF`               | Company has been struck from the registry.           |
| `CLOSED`                   | Company has been closed.                             |
| `INACTIVE`                 | Company is inactive (non-trading).                   |
| `AUTHORISED`               | Authorised (typically for regulated entities).       |
| `APPOINTED_REPRESENTATIVE` | Appointed representative of another authorised firm. |
| `UNAUTHORISED`             | Previously authorised, now unauthorised.             |
| `NO_LONGER_AUTHORISED`     | Authorisation revoked.                               |
| `SEE_FULL_DETAILS`         | Status requires manual inspection.                   |

<Note>
  Because `registry_status` reflects raw registry values, use `verification_status` below when you need a consistent, cross-jurisdiction indicator to drive product logic.
</Note>

## Company verification status

A standardized, business-facing status per company result. Normalizes the varying registry and company statuses across different countries and sources into a single consistent indicator that can be interpreted directly within your product. Surfaced inside the KYB decision under `company.verification_status`.

| Status     | Meaning                                                            |
| ---------- | ------------------------------------------------------------------ |
| `verified` | The company appears active and valid.                              |
| `failed`   | The company appears inactive, dissolved, or has issues identified. |
| `unknown`  | There is insufficient information or the status is ambiguous.      |

## Company fetch status

Indicates the data retrieval progress for a specific company record from external or official registries. Use it to determine how complete the fetched information is for a given company. Surfaced inside the KYB decision under `company.fetch_status`.

| Status     | Meaning                                                                               |
| ---------- | ------------------------------------------------------------------------------------- |
| `pending`  | Only partial or basic company information has been retrieved at this stage.           |
| `resolved` | Full and complete company data has been successfully retrieved from official sources. |

## AML verification status

Returned per screening (company or person).

| Status         | Meaning                                              |
| -------------- | ---------------------------------------------------- |
| `APPROVED`     | No hits above threshold.                             |
| `DECLINED`     | High-severity hit (confirmed sanction or PEP match). |
| `IN_REVIEW`    | Hit found that requires analyst review.              |
| `NOT_FINISHED` | Screening has not completed.                         |

## Decision reason codes

When a session is `DECLINED`, the decision includes a machine-readable `decision_reason_code`. Common codes:

| Code                         | Meaning                                                        |
| ---------------------------- | -------------------------------------------------------------- |
| `blocked_country`            | Country of incorporation is in the dangerous countries list.   |
| `blocked_business`           | The `vendor_data` matches a Business blocklist entry.          |
| `registry_company_not_found` | Company could not be located in any supported registry.        |
| `registry_company_dissolved` | Registry reports company is dissolved.                         |
| `registry_mismatch`          | Registry data contradicts the customer-provided data.          |
| `aml_confirmed_sanction`     | Confirmed sanctions match on the company or a key person.      |
| `aml_confirmed_pep`          | Confirmed PEP match on a key person.                           |
| `documents_failed_ocr`       | Uploaded documents could not be OCR'd or fail cross-reference. |
| `documents_incomplete`       | Required documents missing.                                    |
| `key_people_incomplete`      | UBOs or officers below threshold could not be identified.      |
| `analyst_rejected`           | An analyst manually declined after review.                     |
| `timeout_abandoned`          | Business did not complete the flow within the SLA.             |

Additional workflow-specific reason codes may appear — see your workflow configuration for the full list.

## Ownership and complexity signals

Returned in the decision alongside status, for informational use:

| Field                  | Description                                                                     |
| ---------------------- | ------------------------------------------------------------------------------- |
| `risk_level`           | `LOW`, `MEDIUM`, `HIGH` — composite of registry, AML, and ownership complexity. |
| `ownership_complexity` | `SIMPLE`, `COMPLEX` — based on number of ownership layers and entity types.     |

See [risk assessment](/business-verification/risk-assessment) for how these fields are computed.

## Next steps

<CardGroup>
  <Card title="Response schema" icon="file-lines" href="/business-verification/response-schema">
    Where each status appears in the payload.
  </Card>

  <Card title="Risk assessment" icon="gauge" href="/business-verification/risk-assessment">
    How statuses combine into a risk level.
  </Card>

  <Card title="Webhooks" icon="bolt" href="/business-verification/webhooks">
    Events that fire on status changes.
  </Card>
</CardGroup>


# Supported Countries
Source: https://docs.didit.me/business-verification/supported-countries

KYB registry coverage across 220+ countries, with the Lite, Shareholders and UBO data tiers available per jurisdiction. From $2.00 per check, priced per country and tier.

Didit's Business Verification (KYB) provides broad global coverage for company registry lookups, sold in three data tiers — see [KYB registry pricing](/getting-started/kyb-registry-pricing) for what each tier returns and what it costs. Tier availability varies by country — the table below shows which tiers are available for each jurisdiction.

<Note>
  Customize which countries your workflows collect, and the tier per country, via the console [workflows](/console/workflows) — align coverage to your compliance footprint without paying for a tier you don't need.
</Note>

### Tier columns

| Column           | What it means                                                                                         |
| ---------------- | ----------------------------------------------------------------------------------------------------- |
| **Lite**         | Company profile, identifiers, status, registered address, activity, and officers                      |
| **Shareholders** | Lite plus the direct shareholders (natural persons and corporate entities) with their ownership bands |
| **UBOs**         | Shareholders plus the ultimate beneficial owners resolved through the ownership chain                 |

Cells marked ✅ indicate the tier is available for that jurisdiction; — means the registry holds no data at that tier there. A Shareholders or UBO request in a country whose registry holds no ownership record is delivered and billed at the highest tier the country's registries can serve — usually Lite. A country with no ✅ at any tier is not offered for registry checks: the applicant enters the company manually, billed at the flat manual-entry price.

***

## Supported countries and subdivisions

The table below shows all supported countries and subdivisions. The **Code** column contains the [ISO 3166-1 alpha-2](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-2) country code used across Didit KYB APIs (e.g. in `country_code` on the registry check, session creation, and business entity fields). US states use the extended `US_<state>` format (e.g. `US_CA`, `US_NY`, `US_DE`) to select the correct Secretary of State registry.

<SupportedKYBCountriesTable />

***

## Manual entry

A country with no tier available above, or a company the registry cannot find, is not blocked — the applicant enters the company by hand and the step continues with `is_from_registry: false`, billed at the flat manual-entry price (see [KYB registry pricing](/getting-started/kyb-registry-pricing)). Some jurisdictions route these sessions to `IN_REVIEW` automatically with reason `registry_manual_required`, depending on your workflow configuration.

## US state coverage

US registries are organized per state. To run a KYB check on a US company, pass the `US_<state>` code (e.g. `US_DE` for Delaware, `US_CA` for California, `US_NY` for New York) — every US state and DC is supported. Using just `US` falls back to a federal-only search (company name + status). Per-state coverage of officers, shareholders, and UBOs varies — Delaware, California, Texas, and New York expose the richest officer and filing data, while smaller states often return only company name, status, and registered agent.

## Dangerous / sanctioned countries

By default, companies incorporated in any country on your application's [dangerous countries](/entities/businesses/blocklist#dangerous-countries) list are auto-declined at session creation regardless of whether the registry is supported. Default list follows FATF and OFAC guidance:

* `AF` Afghanistan
* `IR` Iran
* `KP` Korea, Dem. Republic of
* `SY` Syria
* `RU` Russian Federation — sectoral sanctions
* `MM` Burma (Myanmar)

Configure the list from *Settings → Blocklist → Countries*.

## Ongoing monitoring

Company AML screening can be configured for **ongoing monitoring** — periodic rescans against sanctions and adverse media lists. See [continuous AML monitoring](/core-technology/aml-screening/continuous-monitoring-aml-screening).

## Continuous registry monitoring

<Note>
  Registry monitoring is **coming soon**. No country in the staging retail catalog checked on September 7, 2026 has monitoring enabled. The configured rate is USD 2.00 per company per year; a price does not mean the feature is available. The behavior below describes the planned service after rollout.
</Note>

Companies verified at the **Shareholders** or **UBO** tier can be kept under continuous registry monitoring for **\$2.00 per company per year**: the registry pushes changes of status, officers, ownership and address, the session goes back to review and a `kyb_registry_change` webhook fires. It is only available where the country allows it: the countries below. See [monitoring shareholders and UBOs](/business-verification/ownership#monitoring-shareholders-and-ubos) and the [per-country prices](/getting-started/kyb-registry-pricing).

<KybRegistryMonitoringCountriesTable />

## Registry data sources

Didit routes each query to the appropriate official government registry or an authoritative aggregator based on the jurisdiction and subdivision you specify. Data is refreshed on every session — results reflect the latest registry state at query time.

<Tip>
  Need a country or subdivision that isn't listed here? [Contact us](mailto:support@didit.me) — registry coverage expands regularly based on customer demand.
</Tip>

## Next steps

<CardGroup>
  <Card title="Overview" icon="building" href="/business-verification/overview">
    How KYB uses registry data.
  </Card>

  <Card title="Company data" icon="database" href="/business-verification/company-data">
    What registry fields get extracted.
  </Card>
</CardGroup>


# Business Verification Warnings
Source: https://docs.didit.me/business-verification/warnings

Business Verification warning codes grouped by feature: KYB registry, KYB documents, KYB key people, AML, phone, email, questionnaire, and Device & IP Analysis.

Business Verification surfaces warnings on the feature item that produced them. Each warning carries the standard structured shape used across the platform — `feature`, `risk`, `log_type`, `short_description`, `long_description`, optional `additional_data`, and `node_id` — so you can route review work to the right operational team.

## Overview

KYB sessions emit warnings under three core feature tags that map to dedicated feature arrays in the V3 decision response:

| Feature tag      | Decision response key                 | What it covers                                                                                                                                                   |
| ---------------- | ------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `KYB_REGISTRY`   | `registry_checks[].warnings[]`        | Official company-registry lookups. Active status, country restrictions, derivable ownership, missing officer/UBO records.                                        |
| `KYB_DOCUMENTS`  | `document_verifications[].warnings[]` | Incorporation, ownership, address, and shareholder documents the user uploads. Cross-document consistency, OCR, metadata, manipulation, age, and subtype rules.  |
| `KYB_KEY_PEOPLE` | `key_people_checks[].warnings[]`      | Person-level signals on directors, officers, UBOs, or user-submitted parties — including PEP/sanctions findings that propagate from AML and prior-decline reuse. |

The same KYB workflow can also include the shared features below — they emit warnings on their own arrays:

| Feature tag     | Decision response key                                        |
| --------------- | ------------------------------------------------------------ |
| `AML`           | `aml_screenings[].warnings[]`                                |
| `PHONE`         | `phone_verifications[].warnings[]`                           |
| `EMAIL`         | `email_verifications[].warnings[]`                           |
| `QUESTIONNAIRE` | `questionnaire_responses` (warnings live on the session log) |
| `LOCATION`      | `ip_analyses[].warnings[]`                                   |

## KYB Registry warnings

Registry warnings use `feature: "KYB_REGISTRY"` and appear on `registry_checks[].warnings[]`.

| Tag                                      | Description                                                                                                                                                                                      |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `KYB_COUNTRY_RESTRICTED`                 | The company's country is outside the allowed countries configured for the workflow.                                                                                                              |
| `KYB_OFFICERS_DATA_NOT_FOUND`            | Officer data is not available from the registry.                                                                                                                                                 |
| `KYB_OWNERSHIP_DATA_NOT_FOUND`           | Ownership data is not available from the registry.                                                                                                                                               |
| `KYB_BENEFICIAL_OWNERSHIP_NOT_DERIVABLE` | Ultimate beneficial ownership could not be established from the registry data.                                                                                                                   |
| `KYB_COMPANY_NOT_ACTIVE`                 | The company is not active according to the registry.                                                                                                                                             |
| `KYB_COMPANY_NOT_FROM_REGISTRY`          | The company was entered manually and could not be verified against a corporate registry.                                                                                                         |
| `KYB_COMPANY_VAT_INVALID`                | The company's VAT number was checked against the EU VIES service and is not valid. The configured `kyb_vat_invalid_action` is applied (default: In Review).                                      |
| `KYB_COMPANY_VAT_COULD_NOT_VALIDATE`     | The VAT number could not be validated because the EU VIES service (or the member state) was temporarily unavailable. The configured `kyb_vat_unverified_action` is applied (default: no effect). |
| `KYB_COMPANY_VAT_NAME_MISMATCH`          | The trader name registered with VIES for this VAT number differs from the submitted company name. Informational — includes `vies_name` and `submitted_name` in `additional_data`.                |

VAT warnings only apply to companies in the EU VAT area (EU-27 plus Northern Ireland) — see [VAT validation](/business-verification/company-data#vat-validation-vies).

## KYB Document warnings

Document warnings use `feature: "KYB_DOCUMENTS"` and appear on `document_verifications[].warnings[]`.

| Tag                                        | Description                                                                                             |
| ------------------------------------------ | ------------------------------------------------------------------------------------------------------- |
| `KYB_DOCUMENT_MISSING_REQUIRED_FIELD`      | A required company field — such as company name or registration number — was not found in the document. |
| `KYB_DOCUMENT_NAME_MISMATCH`               | The company name in the document does not match the registry.                                           |
| `KYB_DOCUMENT_REG_NUMBER_MISMATCH`         | The registration number in the document does not match the registry.                                    |
| `KYB_DOCUMENT_INCORPORATION_DATE_MISMATCH` | The incorporation date in the document does not match the registry.                                     |
| `KYB_DOCUMENT_ADDRESS_MISMATCH`            | The registered address in the document does not match the registry.                                     |
| `KYB_CROSS_DOCUMENT_MISMATCH`              | Company data differs across uploaded corporate documents.                                               |
| `KYB_DOCUMENT_METADATA_MISMATCH`           | The document signature, metadata, or file structure indicates a possible issue.                         |
| `KYB_ASSOCIATED_PARTY_MISMATCH`            | Directors or shareholders in the document do not match the registry.                                    |
| `KYB_DOCUMENT_GRAPHIC_EDITOR`              | The document appears to have been processed by graphic editing software.                                |
| `KYB_DOCUMENT_SUSPECTED_MANIPULATION`      | The system detected signs of possible corporate-document manipulation.                                  |
| `KYB_ADDITIONAL_DATA_NOT_FOUND`            | A document field could not be verified because the corresponding registry data is unavailable.          |
| `KYB_DOCUMENT_EXPIRED`                     | The corporate document exceeds the configured maximum age.                                              |
| `KYB_DOCUMENT_UNSUPPORTED_SUBTYPE`         | The uploaded document subtype is disabled for the workflow.                                             |
| `KYB_DOCUMENT_MAX_ATTEMPTS_EXCEEDED`       | The maximum number of corporate-document upload attempts was exceeded.                                  |

For PDF overlay-text manipulation, `KYB_DOCUMENT_SUSPECTED_MANIPULATION` can include `additional_data.manipulated_regions`. These are page-coordinate rectangles that identify the suspected edited areas and match the rectangles returned in `document_verifications[].items[].document_metadata.overlay_manipulation.manipulated_regions`.

## KYB Key People warnings

Key People warnings use `feature: "KYB_KEY_PEOPLE"` and appear on `key_people_checks[].warnings[]`. They surface person-level issues on directors, officers, UBOs, and user-submitted parties.

| Tag                                  | Description                                                                                                             |
| ------------------------------------ | ----------------------------------------------------------------------------------------------------------------------- |
| `KYB_PREVIOUSLY_DECLINED_INDIVIDUAL` | A person associated with the company was previously declined in another business verification for the same application. |

<Note>
  **PEP / sanctions hits on key people** are reported as standard AML hits on the matching `aml_screenings[]` item, not as a KYB-key-people warning. The Key People check propagates the resulting `Declined` or `In Review` status onto each affected party so the overall key-people verdict reflects the AML outcome.
</Note>

## Shared feature warnings

The features below can run inside a KYB workflow. They use the same warning catalog as User Verification — full reference on each feature's own warnings page.

### AML

`feature: "AML"` on `aml_screenings[].warnings[]`.

| Tag                               | Description                                                                                           |
| --------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `POSSIBLE_MATCH_FOUND`            | The AML screening found a possible match requiring review.                                            |
| `COULD_NOT_PERFORM_AML_SCREENING` | Didit could not perform the AML screening because required screening data was missing or unavailable. |

### Phone

`feature: "PHONE"` on `phone_verifications[].warnings[]`.

| Tag                                   | Description                                                    |
| ------------------------------------- | -------------------------------------------------------------- |
| `DISPOSABLE_NUMBER_DETECTED`          | The phone number is disposable.                                |
| `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` | The maximum number of verification-code attempts was exceeded. |
| `VOIP_NUMBER_DETECTED`                | The phone number is a VoIP number.                             |
| `DUPLICATED_PHONE_NUMBER`             | The phone number was used in another verification process.     |
| `HIGH_RISK_PHONE_NUMBER`              | The phone number is high risk.                                 |
| `PHONE_NUMBER_IN_BLOCKLIST`           | The phone number matches an entry in your blocklist.           |

### Email

`feature: "EMAIL"` on `email_verifications[].warnings[]`.

| Tag                            | Description                                                          |
| ------------------------------ | -------------------------------------------------------------------- |
| `BREACHED_EMAIL_DETECTED`      | The email address appears in known data breaches.                    |
| `DISPOSABLE_EMAIL_DETECTED`    | The email address is disposable.                                     |
| `UNDELIVERABLE_EMAIL_DETECTED` | The email address is undeliverable.                                  |
| `DUPLICATED_EMAIL`             | The email address was used in another verification process.          |
| `EMAIL_IN_BLOCKLIST`           | The email address matches an entry in your blocklist.                |
| `EMAIL_CODE_ATTEMPTS_EXCEEDED` | The maximum number of email verification-code attempts was exceeded. |

### Questionnaire

`feature: "QUESTIONNAIRE"`.

| Tag                            | Description                                                                             |
| ------------------------------ | --------------------------------------------------------------------------------------- |
| `CUSTOM_STATUS_RULE_TRIGGERED` | A workflow status rule evaluated a questionnaire answer and changed the feature status. |

### Device & IP Analysis

`feature: "LOCATION"` on `ip_analyses[].warnings[]`.

| Tag                                                    | Description                                                                                |
| ------------------------------------------------------ | ------------------------------------------------------------------------------------------ |
| `COUNTRY_FROM_DOCUMENT_DOES_NOT_MATCH_COUNTRY_FROM_IP` | The document country does not match the IP country.                                        |
| `PRIVATE_NETWORK_DETECTED`                             | A private network, VPN, proxy, or Tor signal was detected.                                 |
| `EXPECTED_IP_ADDRESS_MISMATCH`                         | The IP address does not match the expected IP address provided for the session.            |
| `IP_ADDRESS_IN_BLOCKLIST`                              | The IP address matches an entry in your blocklist.                                         |
| `DEVICE_FINGERPRINT_IN_BLOCKLIST`                      | The device fingerprint matches an entry in your blocklist.                                 |
| `DUPLICATED_IP_ADDRESS`                                | The same IP address was used in another verification with different `vendor_data`.         |
| `DUPLICATED_DEVICE_FINGERPRINT`                        | The same device fingerprint was used in another verification with different `vendor_data`. |

## Examples

### Registry — company not active

```json theme={null}
{
  "registry_checks": [
    {
      "node_id": "feature_kyb_registry",
      "status": "Declined",
      "warnings": [
        {
          "feature": "KYB_REGISTRY",
          "risk": "KYB_COMPANY_NOT_ACTIVE",
          "log_type": "error",
          "short_description": "Company is not active",
          "long_description": "The company is not active according to the registry.",
          "additional_data": null,
          "node_id": "feature_kyb_registry"
        }
      ]
    }
  ]
}
```

### Documents — suspected overlay manipulation

```json theme={null}
{
  "document_verifications": [
    {
      "node_id": "feature_kyb_documents",
      "status": "In Review",
      "warnings": [
        {
          "feature": "KYB_DOCUMENTS",
          "risk": "KYB_DOCUMENT_SUSPECTED_MANIPULATION",
          "log_type": "warning",
          "short_description": "Possible document manipulation",
          "long_description": "The system detected signs of possible corporate-document manipulation.",
          "additional_data": {
            "manipulated_regions": [
              { "page": 1, "x": 120, "y": 240, "width": 180, "height": 22, "page_width": 612, "page_height": 792 }
            ]
          },
          "node_id": "feature_kyb_documents"
        }
      ]
    }
  ]
}
```

### Key people — previously declined individual

```json theme={null}
{
  "key_people_checks": [
    {
      "node_id": "feature_kyb_key_people",
      "status": "In Review",
      "warnings": [
        {
          "feature": "KYB_KEY_PEOPLE",
          "risk": "KYB_PREVIOUSLY_DECLINED_INDIVIDUAL",
          "log_type": "warning",
          "short_description": "Previously declined individual",
          "long_description": "A person associated with the company was previously declined in another business verification for the same application.",
          "additional_data": null,
          "node_id": "feature_kyb_key_people"
        }
      ]
    }
  ]
}
```

## Related

<CardGroup>
  <Card title="Response schema" icon="code" href="/business-verification/response-schema">
    See where warnings appear in each KYB feature array.
  </Card>

  <Card title="Statuses" icon="list-check" href="/business-verification/statuses">
    Understand how warning severity maps to verification status.
  </Card>

  <Card title="Documents" icon="file-lines" href="/business-verification/documents">
    Review document groups, OCR, and cross-check behavior.
  </Card>

  <Card title="Key people" icon="users" href="/business-verification/key-people">
    Officer, UBO, and submitted-party verification flow.
  </Card>

  <Card title="AML report" icon="shield-check" href="/core-technology/aml-screening/report-aml-screening">
    Hit-level structure for company and person AML screenings.
  </Card>

  <Card title="Reference data models" icon="brackets-curly" href="/reference/data-models">
    Canonical shapes for warnings and feature arrays.
  </Card>
</CardGroup>


# KYB Webhooks
Source: https://docs.didit.me/business-verification/webhooks

Webhook events for KYB sessions and Business entities — triggers, payload schemas, and HMAC signature verification. From $2.00 per check, priced per country and tier, no contracts.

Business Verification and Business entities emit webhook events on every meaningful state change. Subscribe to the events you care about via the [webhook destinations API](/management-api/webhook/list-destinations) or the Business Console.

## Event catalog

Webhook events are shared between User and Business sessions — the `session_kind` field on the payload tells you which kind the event refers to. Entity-level events are separate from session-level events.

### Session-level events

| Event            | When it fires                                                                                                                                                      |
| ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `status.updated` | A session's status changed. For Business Verification (KYB) sessions the payload carries `session_kind: "business"`.                                               |
| `data.updated`   | A session's data was updated (registry refresh, key-people submission, document upload, AML rescan). Payload includes `session_kind: "business"` for KYB sessions. |

### Business entity events

| Event                     | When it fires                                                                                                    |
| ------------------------- | ---------------------------------------------------------------------------------------------------------------- |
| `business.status.updated` | The linked [Business entity](/entities/businesses/overview)'s status changed (`ACTIVE` / `FLAGGED` / `BLOCKED`). |
| `business.data.updated`   | The Business entity's profile fields or aggregate counters changed.                                              |

Subscribe to any combination on your webhook destination. See [entity webhooks](/entities/webhooks) for the full Business / User entity event reference.

## Envelope

Every webhook uses the same top-level envelope. The `session_kind` field inside `data` discriminates between User Verification (KYC) and Business Verification (KYB) for session-level events.

```json theme={null}
{
  "event": "status.updated",
  "event_id": "evt_01H8X...",
  "application_id": "app_abc123",
  "timestamp": "2026-04-18T12:30:00Z",
  "data": { ... }
}
```

## Payload shapes

### `status.updated` — Business Verification (KYB) session

Fires when a KYB session's status transitions.

```json theme={null}
{
  "event": "status.updated",
  "data": {
    "session_id": "bs_01H...",
    "session_kind": "business",
    "previous_status": "IN_PROGRESS",
    "status": "APPROVED",
    "vendor_data": "biz-acme-001",
    "workflow_id": "wf_kyb_standard",
    "features": ["KYB_REGISTRY", "KYB_COMPANY_AML", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE"],
    "decision": { ...abbreviated KYB decision payload... },
    "changed_at": "2026-04-18T12:30:00Z"
  }
}
```

The `decision` block contains the same shape as [`GET /v3/session/{id}/decision/`](/sessions-api/retrieve-session) — `registry_checks[]`, `key_people_checks[]`, `document_verifications[]`, `aml_screenings[]`, etc.

### `data.updated` — Business Verification (KYB) session

Fires when session data (registry, key people, documents, AML) changed without a status transition.

```json theme={null}
{
  "event": "data.updated",
  "data": {
    "session_id": "bs_01H...",
    "session_kind": "business",
    "vendor_data": "biz-acme-001",
    "changed_fields": ["registry_checks", "key_people_checks"],
    "updated_at": "2026-04-18T14:00:00Z"
  }
}
```

Use `changed_fields` to efficiently decide what to re-fetch.

### `business.status.updated`

Fires when the [Business entity](/entities/businesses/overview) moves between `ACTIVE`, `FLAGGED`, or `BLOCKED`.

```json theme={null}
{
  "event": "business.status.updated",
  "data": {
    "vendor_data": "biz-acme-001",
    "uuid": "f7a9c1b2-4e6d-4f8a-9c5d-2a1b3c4d5e6f",
    "status": "FLAGGED",
    "previous_status": "ACTIVE",
    "reason": "manual",
    "actor": "compliance@yourcorp.com"
  }
}
```

### `business.data.updated`

Fires when the Business entity's profile fields or aggregate counters change.

```json theme={null}
{
  "event": "business.data.updated",
  "data": {
    "vendor_data": "biz-acme-001",
    "uuid": "...",
    "legal_name": "Acme Corporation Limited",
    "registration_number": "12345678",
    "country_code": "GBR",
    "session_count": 2,
    "approved_count": 1,
    "declined_count": 0,
    "in_review_count": 1,
    "changed_fields": ["session_count", "approved_count", "features"]
  }
}
```

## Signature verification

All webhooks are signed HMAC-SHA256 with your destination's shared secret, sent in the `X-Didit-Signature` header. Verify the raw request body before acting.

Example (Node.js):

```typescript theme={null}
import { createHmac, timingSafeEqual } from 'crypto';

function verifyWebhook(rawBody: string, signature: string, secret: string): boolean {
  const expected = createHmac('sha256', secret).update(rawBody).digest('hex');
  const provided = Buffer.from(signature);
  const computed = Buffer.from(expected);
  return provided.length === computed.length && timingSafeEqual(provided, computed);
}
```

Full details in the [webhooks reference](/integration/webhooks).

## Retry policy

* Non-2xx responses trigger retries with exponential backoff.
* Up to 5 retries over \~24 hours.
* Each retry gets a new `X-Didit-Delivery` header but the same `event_id` — de-duplicate on your side.
* Repeated failures flip the destination to `disabled`.

## Subscribing

Subscribe to the events you care about on a [webhook destination](/management-api/webhook/create-destination):

```bash theme={null}
curl -X POST https://verification.didit.me/v3/webhook/destinations/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "KYB events",
    "url": "https://yourapp.com/webhooks/didit-kyb",
    "subscribed_events": [
      "status.updated",
      "data.updated",
      "business.status.updated",
      "business.data.updated",
      "activity.created"
    ]
  }'
```

Filter for business sessions on your side by checking `data.session_kind === "business"` inside `status.updated` and `data.updated` events.

## Next steps

<CardGroup>
  <Card title="Webhooks reference" icon="bolt" href="/integration/webhooks">
    Destinations, signing, retries, common patterns.
  </Card>

  <Card title="Statuses" icon="list-check" href="/business-verification/statuses">
    Session and feature status reference.
  </Card>

  <Card title="Response schema" icon="file-lines" href="/business-verification/response-schema">
    Decoding the KYB decision payload.
  </Card>
</CardGroup>


# April 2026
Source: https://docs.didit.me/changelog/april-2026

April 2026 release: KYB business verification revamp, transaction monitoring upgrades, streaming exports, new documents, and native SDK updates.

### KYB Business Verification — Major Revamp

Business verification received its biggest update yet. The end-to-end flow — from creating a session to reviewing the final report — was rebuilt around the same patterns you already know from KYC.

* **New Business List View** — Filters, column visibility, tags, bulk actions, and create-session shortcuts make managing business onboarding far easier
* **Redesigned Business Detail Page** — Scrollable feature tabs (registry, key people, documents, AML, questionnaires), PDF download, file preview, resubmit, and delete — matching the session detail experience
* **Key People Graph** — Split view between registry-provided and submitted parties, clickable detail modal, and a workflow-style hierarchy graph (Cmd/Ctrl + scroll to zoom)
* **Expanded Registry Check** — More fields, richer inline editing, country flags with localized names, and translated labels for addresses, financials, and industries
* **AML for KYB** — Configure AML screening for businesses and their key people with the same controls as KYC
* **Required Document Validation** — Workflows can now require at least one verified business document (incorporation, POA, etc.) before approval
* **Tags, Cases, and Decision Endpoints** — Tag businesses, attach cases, and apply manual decisions through the same APIs used for individuals

<Frame>
  <img alt="KYB key people hierarchy graph in the Didit Business Console" />
</Frame>

### Customer-Facing KYB Flow

The end-user side of KYB also saw heavy work for a smoother onboarding experience.

* **Smart Prefill** — Phone numbers and key people are prefilled when the data is already known, so applicants only confirm
* **POA Improvements** — Better proof-of-address screen, document subtype detection, and a new action when the address can't be parsed
* **KYB Document Compression** — Uploaded business documents are now compressed automatically for faster submission and smaller payloads
* **Region Picker Polish** — Redesigned country and state pickers shared across every step for a more consistent feel

<Frame>
  <img alt="Customer-facing KYB flow — company search step" />
</Frame>

### Transaction Monitoring (KYT)

Transaction monitoring grew from a beta feature into a full surface area inside the Console.

* **Transaction PDF Reports** — Download a complete PDF for any transaction, matching the format already available for verification sessions
* **Lists & Blocklists Expanded** — System lists now cover IPs, devices, and duplicated identifiers, with translations and richer match details
* **Rules Summary** — Each transaction shows only the rules that actually matched, with a count summary at the top
* **Cases on User Details** — User profiles now surface their associated cases, transactions, and screening history in one place
* **Improved Screening Performance** — AML screening responses are cached, transaction screening is faster, and rule responses are more compact
* **Subject Country Fix** — Cross-border transactions resolve the correct subject country
* **Webhooks for Transactions** — Get notified when transaction state changes via the same webhook system as sessions
* **Payment Methods** — Payment-method data is now captured and surfaced on the transaction record

<Frame>
  <img alt="Transaction monitoring list view in the Didit Business Console" />
</Frame>

### Database Validation

* **New Service Format** — Database validation services moved to a richer format that returns more structured data for downstream use
* **Outcome Codes** — Standardized outcome codes make it easier to map vendor responses across countries

### Streaming CSV Exports

Large exports no longer time out. Sessions, transactions, analytics, and usage exports stream results as they're generated.

* **Sessions & Businesses Export** — Streamed CSV with no row cap and far lower memory usage
* **Analytics Export** — Download analytics data as a CSV directly from the dashboard
* **Usage Export** — Per-feature usage breakdown is now exportable
* **Faster Generation** — Exports complete several times faster on large organizations

<Frame>
  <img alt="Exporting sessions to CSV from the Didit Business Console" />
</Frame>

### Multi-Account Abuse Prevention

New protection against organization farming — when a single actor creates multiple sub-accounts to bypass limits.

* **Multi-Account Detection** — Suspicious patterns of organization creation are now flagged automatically
* **New Roles & Permissions** — Additional granular permissions, plus updates to SAML for enterprise customers

### Workflow & API Improvements

* **More Flexible Workflow API** — Create and patch workflows with a wider range of configurations, including KYB settings and node deduplication
* **Workflow Editor Polish** — Template fixes, blur/scroll improvements in the node editor, redesigned modals, and clearer node-based UI
* **Custom Verification Email** — Send the verification link from a dedicated email channel
* **Update-Data Endpoints for API Clients** — The endpoints used to update session data are now first-class, available to all API clients
* **Workflow Templates** — More templates and better preview screens

<Frame>
  <img alt="Didit workflow and API improvements" />
</Frame>

### Console Performance & UX

* **Faster Console** — Reduced initial load time and smoother navigation across the dashboard
* **Phone Lifecycle** — Cleaner state transitions for phone-verification features
* **User Details Pages** — All tabs (sessions, businesses, transactions, cases) now visible on a single user-detail surface
* **Permissions Fixes** — Several Console buttons that were incorrectly disabled (e.g., the "+" create button) now reflect the user's real permissions

### New Document & Country Support

* **Kyrgyzstan** — Added support for the national ID
* **India** — PAN ID card now correctly classified, separate from passports
* **Mexico** — New ID document added; Switzerland and Czech Republic recognition improved
* **Algeria** — CSCA chip validation now works correctly
* **Income Tax Cards** — New document type for tax-residency verification across multiple regions

### Kazakh Language

The verification flow, Console, and SDKs now support Kazakh (kk), bringing total language coverage to 53.

### Native SDKs

A wave of releases across all native SDKs this month, focused on stability and reliability.

* **Android SDK 3.4.4 – 3.5.3** — Improved document and face overflow detection, better photo quality, refined face-intro styling, fixed close buttons and verification screen styling, and updated languages including Kazakh
* **iOS SDK 3.2.10 – 3.3.3** — Multiple stability releases with active liveness improvements, language updates, and miscellaneous fixes
* **React Native SDK 3.2.8 – 3.2.9** — Resolved Swift 6 main-actor isolation error on Xcode 26.0.x, surfaced the new `RetryBlocked` error variant, added an Expo example app, and improved the CI pod-install fallback
* **Flutter SDK 3.4.4 – 3.4.5** — Fixed Swift 6 exhaustive switch, updated native iOS/Android SDKs underneath, and surfaced `RetryBlocked` from the native Android layer

### MCP Server

The Didit MCP server (used by AI agents) was upgraded.

* **Lists API** — Legacy blocklist tools were replaced with the unified Lists API, giving agents the same blocklist/allowlist capabilities the Console exposes
* **Version 3.0.3** — Latest release published

### Improvements

* IP enrichment now handles private IP addresses gracefully
* KYB sub-sessions (KYC for UBOs, officers, etc.) correctly inherit the whitelabel branding of their parent
* WebSocket responses include the user's locale for client-side display
* Active liveness uses the latest verification SDK with faster capture validation on iOS
* Camera permission handling distinguishes between permission timeouts and scan timeouts for clearer error messages
* Arabic transliteration improved
* Country detection from IP fixed for several edge-case ranges
* Fraud reports include richer detail and a clearer summary


# April and May 2025
Source: https://docs.didit.me/changelog/april-may-2025

Didit V2 launch with modular architecture, age estimation, biometric authentication, proof of address, prepaid credits, and open APIs.

### Didit V2 Is Here

We've rebuilt Didit from the ground up. This is not just an update — it's a reimagining of how identity verification should work.

**Modular Architecture** — Choose only the tools you need. Use our web widget or go deep with our open APIs.

**New Features:**

* **Age Estimation** — Facial analysis to verify user age, with optional document check
* **Biometric Authentication** — Use biometrics to unlock sensitive flows like payments or restricted access
* **Proof of Address** — Accept bills, bank statements, or cross-reference data to verify residency
* **Face Search 1:N** — Match a user's face against your database to detect duplicates, enforce blocklists, or manage biometric access
* **Phone Verification** — OTP-based phone number checks built-in

**More Control** — Fully customize your verification flow based on your risk and product needs.

**Prepaid Credit Model** — Buy only what you use. Save more on premium features like AML, Biometrics, and Age Estimation.

**Open & Modular APIs** — Core features exposed via API so you can integrate directly without the hosted verification flow.


# August 2025
Source: https://docs.didit.me/changelog/august-2025

Database validation API launch, phone verification, proof of address by country, and RTL language support across Didit's identity verification platform.

* **Database Validation** — New API for verifying identity against government databases. Launched coverage for Brazil and Dominican Republic
* **Phone Verification** — New phone verification API integrated into biometric authentication flows
* **Proof of Address by Country** — POA documents can now be configured per country for flexible integrations
* **Unparsed Address Warning** — Notifications when document addresses cannot be parsed or geolocated
* **Enhanced Document Handling** — Additional personal number fields, improved non-standard MRZ handling (Peru, Bolivia, Romania, Iraq, Kazakhstan, Kuwait)
* **Language & RTL Support** — Full right-to-left interface improvements for Arabic, Hebrew, and Persian
* **Improved iOS Capture Quality** — Optimized image and video quality on iOS while keeping file sizes lightweight
* **Shorter Session URLs** — Smaller QR codes and more readable URLs
* **Automatic Language Routing** — Language auto-detection when scanning QR codes and during redirections
* **Bug Fixes** — Fixed face match edge cases, improved video compression, fixed Samsung Internet compatibility issues


# August 2026
Source: https://docs.didit.me/changelog/august-2026

Biometric-template retention with a breaking session-deletion change, new fraud signals, ISO/IEC 27566-1 age assurance, and standalone risk APIs.

### Stronger fraud detection

Fraudsters increasingly submit documents and selfies that never came from a real capture. Five new signals catch those submissions before they reach a reviewer.

* **Catch recycled document images** — every upload is scored against a corpus of ID document images already circulating publicly, and a match raises its own warning
* **Liveness video forensics** — frame count, duplicate-frame ratio, and effective frame rate are analyzed server side, so replayed or synthetic video is flagged rather than trusted
* **Covered documents are detected** — a partially obscured document is caught at pixel level and returns `DOCUMENT_OCCLUSION_DETECTED`, translated into every supported language
* **Live capture confirmed** — Face Match confirms the person in front of the camera, distinguishing a live capture from the portrait printed on the document
* **Capture quality gate** — every upload is scored for quality before extraction runs, so a poor capture is caught while the user is still in the flow

<Frame>
  <img alt="Didit card titled Five new fraud signals" />
</Frame>

### Age assurance built to ISO/IEC 27566-1

Age-assurance workflows can now return the age decision and nothing else, in line with the international age-assurance standard.

* **Returned data is locked** — a workflow that declares the age-assurance standard cannot return identity attributes alongside the age decision, and only an age-capable workflow may declare it
* **Branch on a borderline age** — the Age Estimation borderline band is visible to the workflow graph, so an uncertain result can route to a document check instead of a flat pass or fail
* **Ready-made templates** — start from an age-assurance template in the workflow builder with returned data already restricted

<Frame>
  <img alt="Didit card titled Age assurance, ISO/IEC 27566-1" />
</Frame>

### New standalone APIs

Four capabilities that previously required a full verification session are now callable on their own, each priced per call on the [pricing page](https://didit.me/pricing).

* **Document AI** — `POST /v3/document-ai/` extracts structured data from any uploaded document, not just identity documents. See [Document AI](/standalone-apis/document-ai)
* **Contact and network risk** — `POST /v3/email/risk/`, `POST /v3/phone/risk/`, and `POST /v3/ip/risk/` return risk signals for an email address, phone number, or IP address. See [Email risk](/standalone-apis/email-risk), [Phone risk](/standalone-apis/phone-risk), and [IP risk](/standalone-apis/ip-risk)
* **Run them as a single check** — each is also available from the single-check dialog in the **Business Console**, without building a workflow

<Frame>
  <img alt="Didit card titled Document AI and risk APIs" />
</Frame>

### Didit Copilot

The in-console assistant became a floating copilot that cites its sources and can build a working workflow from a description.

* **Available on every page** — a resizable floating panel replaces the docked one, with starting prompts for the page you are on and a fullscreen layout on mobile
* **Answers cite their sources** — inline citations open the underlying documentation without leaving the panel
* **Build a workflow by describing it** — the copilot creates the draft, adds and configures steps, adds branches, sets final-status rules, and validates before publishing
* **Configure Database Validation by conversation** — the copilot creates a configured **Database Validation** step for any supported country
* **Build a questionnaire from a spreadsheet** — attach a CSV or Excel file and the copilot turns it into a questionnaire, including very long answer lists
* **Works in your language** — the console language travels with every turn, voice and typed input are both supported, and you can download the transcript

<Frame>
  <video />
</Frame>

### Support in the Business Console

Support moved into the product, so you can raise and follow an issue without leaving the **Business Console**.

* **A Support section** — organization-scoped tickets with live status and a standard tickets table
* **Report an issue in place** — a dialog with category, severity, and session ID, attachments on any message, and the ticket number shown everywhere
* **Escalate to a human in the same thread** — the assistant hands off to a support agent without losing context, and you get an email when a human replies
* **Follow a ticket by link** — every ticket has a permalink

<Frame>
  <img alt="The Support section of the Business Console listing three tickets with All, Open, In Progress, Resolved and Canceled filters and a New ticket button" />
</Frame>

### Marketplace and per-check engines

The Marketplace is now available in the **Business Console**, and you can choose which engine runs each individual check.

* **Browse and enable partner modules** from the Marketplace section. See [Marketplace](/console/marketplace)
* **Pick an engine per feature** — a full-width engine selector sits in the first tab of a feature, in both the graph and simple workflow editors
* **Your choice persists** on simple workflows as well as graph workflows

<Frame>
  <img alt="The Marketplace in the Business Console with Browse, Connected, Requests and Activity tabs and a grid of connectable verification providers" />
</Frame>

### Transaction Monitoring

Monitoring rules are now fully programmable, from the API and from an AI agent.

* **Manage rules through the API** — create, update, delete, and backtest transaction-monitoring rules with the `/v3/transactions/rules/` Management API endpoints, in addition to the **Business Console**. Browse, install, and remove preset rules from the library with the matching `library` and `install` endpoints
* **Manage rules from the Didit MCP** — nine `didit_transaction_rule_*` MCP tools bring the same list, create, update, delete, backtest, and library workflows to any MCP-connected AI agent
* **AI-assisted rule migration** — ask the Didit assistant (or any MCP-connected agent) to map a rule set exported from another provider (CSV or Excel) onto Didit's rule schema, backtest it against your own transaction history, and create the rules in test mode for you to review before activating
* **Every manual status change is attributed** — a transaction moved by hand records the console user who moved it

<Frame>
  <img alt="Didit MCP terminal creating a transaction-monitoring rule with didit_transaction_rule_create and returning Rule created in test mode" />
</Frame>

### Biometric templates and data retention

Applications can keep one image-free face template after a session is deleted, so duplicate detection keeps working once session data is purged.

* **Biometric-template retention after session deletion (opt-in)** — keep one image-free face biometric template anchored to the User when a session is deleted, so duplicate detection, Face Search, and biometric authentication keep working after you purge session data. Enable it in **App Settings → Data** (**Retain biometric template**, with a required finite retention period) or with `face_retention_policy` and `face_retention_days` on `PATCH /v3/webhook/`. Override it per call with `retain_face_embeddings` on `DELETE /v3/session/{sessionId}/delete/` and `POST /v3/sessions/delete/`. Retained templates never contain images, session data, or identity fields, carry a finite `expires_at`, and are purged on User deletion, privacy erasure, expiry, or explicit purge. See [Biometric templates](/management-api/biometric-templates/overview)
* **Privacy-erasure instructions** — send `deletion_instruction: "privacy_erasure"` (and your own `instruction_id`) on session deletion to purge every retained template for that person regardless of the application policy
* **New Biometric Templates API** — `GET /v3/biometric-templates/`, `GET /v3/biometric-templates/count/`, `GET`/`DELETE /v3/biometric-templates/{template_uuid}/`, and `POST /v3/biometric-templates/delete/` list, count, inspect, and purge retained templates. Every retain and purge is audited
* **Face Search matches** now report `source: "retained_template"` with `vendor_user_id` and `biometric_template_id` for hits on retained templates, and `vendor_user_id` on session and imported matches
* **Breaking: session deletion responses** — `DELETE /v3/session/{sessionId}/delete/` and `POST /v3/sessions/delete/` now return `200 OK` with a JSON body (`face_retention_outcome`, `biometric_template_uuid`; per-session `results[]` for batch) instead of `204 No Content`. Update clients that assert on `204`. Default deletion behavior is unchanged: existing applications stay on `delete_with_session` until you explicitly enable retention
* **`POST /v3/users/delete/`** purges the user's retained biometric templates before deleting the user, and returns `503` (retryable, nothing deleted) if a template cannot be purged
* **A retention policy you can see** — set the policy in settings and review stored templates in **Lists → Biometric templates**

<Frame>
  <img alt="Didit card titled Biometric templates API" />
</Frame>

### Session API

Retrieve-session responses carry more of the signals your integration needs, so you can decide without extra calls.

* **Barcode data in responses** — retrieve-session responses include `id_verifications[].barcodes`. Each barcode entry preserves `type`, `position`, `data`, `data_raw`, and `side`; documents without barcode output return an empty array
* **Explicit liveness method** — face-step payloads always include `face_liveness_method`. When a workflow does not set it explicitly, the API returns `PASSIVE`
* **Marital status in rules** — use `kyc.marital_status` in workflow branches and custom status rules
* **Order by last update** — list sessions by `updated_at`, and see at a glance which sessions were imported

<Frame>
  <img alt="Didit card titled Richer session payloads" />
</Frame>

### New documents and countries

New document types across ten countries, and firearm licenses as a new document category.

* **New identity documents** — Moldova ID card (2025), Pakistan ID card (2025), Uruguay ID card (2026), Greece asylum seeker card (2025), and a third Belgium driving license variant
* **Digital driving licenses** — Argentina (Mi Argentina and Jujuy) and Australia (New South Wales including provisional, South Australia including learner, and Victoria including heavy vehicle)
* **Firearm licenses are a new category** — Victoria firearms license in Australia, and Illinois, Massachusetts, and two New Jersey permits in the United States, selectable as their own document type
* **Mexico City driving license (2025)**, including the permanent-license catalog, and **Paraguay driving license (2026)**. Separately, **Malaysia MyKad** is now selectable as its own subtype rather than a generic ID card
* **Extraction upgraded for ten more countries** — Belgium, Germany, India, Israel, Madagascar, New Zealand, Norway, Sierra Leone, South Africa, and the United States
* **French 2D-Doc validation** — French 2021 ID cards read and validate the ANTS 2D-Doc Data Matrix on the back of the document
* **See exactly which fields a barcode signs** — the barcode on North American driving licenses reports its signed fields, and each signature is validated against its certificate's validity window

<Frame>
  <img alt="The verification flow on mobile with country set to United States of America and document type set to Firearm License" />
</Frame>

### Chip reading

The ePassport trust store was refreshed, so more chips authenticate cleanly and an unreadable chip explains itself.

* **136 issuing countries** in the ePassport trust store, with new signing-certificate generations imported for 32 of them
* **A missing trust anchor is named** — when the trust anchor for a chip is missing, the result says so directly
* **Branch on why a chip was skipped** — workflows can route on the specific NFC skip reason
* **Wider chip compatibility** — passports whose signatures use a non-standard encoding now read successfully, and chip portraits in every color mode convert correctly

<Frame>
  <img alt="Didit card titled 136 countries for chip reading" />
</Frame>

### Database Validation

A new authoritative source, and Database Validation now runs on its own inputs.

* **Nigeria Bank Verification Number** — a direct BVN lookup, gated on a selfie face match so the number is only resolved for the person actually present. Names are optional inputs
* **No document step required** — each field can draw from its own input source, so a workflow can run Database Validation from a selfie and a national ID number with no document capture at all
* **Explicit approval semantics** — an approval means the source positively confirmed the data, and billing follows a successful source call
* **Clearer outcomes** — when Database Validation does not run, the response says why

### Business verification

Declared owners and officers are checked against the documents you upload, and a registry outage keeps the flow moving.

* **Key people are confirmed against corporate documents** — a declared party is matched on document evidence, and a shareholder named in a document must carry an owner role
* **Registry roles are preserved** — UBO roles come from registry ownership data, and officer roles from the full registry designation
* **Registry outages return a clear code** — registry-search outages return `502` with `code: "kyb_registry_provider_unavailable"`, so your integration can react instead of guessing
* **Manual company entry** — web, iOS, and Android verification flows let the applicant enter company details by hand when the registry provider is unavailable
* **French overseas departments** are now searchable in the French company registry
* **Registry coverage analytics** — see registry search coverage and success by country and workflow version in **Reports**
* **Per-group document progress** on the documents step, with documents awaiting replacement counted separately

<Frame>
  <img alt="KYB Key People hierarchy showing a verified company with two ultimate beneficial owners, each party marked AML clear and approved" />
</Frame>

### AML screening and Wallet Screening

Reviewers get the reasoning behind a score, and wallet screening gains a shareable report.

* **The risk score is explained** — the result shows the factors behind the score, with readable hit tooltips and spelled-out dataset names
* **Signed PDF report for wallet screening** — a standalone report endpoint whose results are signed, so the PDF cannot be altered after the fact
* **Idempotency keys** on the AML API, so a retried screening request is never charged or screened twice
* **Sharper matching** — nationality is normalized to exact country codes before search, and re-screening survives a manual country correction

<Frame>
  <video />
</Frame>

### Verification flow

Capture is where users most often fail, so most of this month went into finishing the first attempt.

* **The alignment frame stays on screen through a retake**, and sits correctly above the camera preview on the newest mobile browsers
* **Camera recovery** — the flow detects a camera that has stopped producing images and restarts it, so capture continues
* **Photo fallback for capture** — web and Android capture flows continue with a photo when video recording is unavailable, and Android retries a failed document-detection model download
* **Honest liveness messaging** — timeout-specific wording, stronger guidance after a second consecutive timeout, and a device with no camera is told so rather than asked for permission
* **Larger uploads** — documents up to 50 MB on Proof of Address, business documents, and Document AI, with automatic compression
* **Vatican City and Saint Vincent and the Grenadines** added to the country list
* **Phone provider outages return a clear code** — `502` with `code: "phone_provider_unavailable"`
* **Retry and rescan stay available** after a document or face upload error on Android (SDK 4.7.3)
* **A clear message when credits run out**, so the user knows exactly what happened

<Frame>
  <video />
</Frame>

### Branding and copy

You can now rewrite the words your users read and match the flow to your palette.

* **A Texts tab in Customization** — override the wording of each step and the completion screen, with a preview showing the real default text
* **Per-application copy overrides** — the same override can differ between two applications in one organization, and applies per step rather than only to the first
* **The "Secured by" footer** takes your configured support-text color

<Frame>
  <img alt="The Texts tab in Customization, showing the language selector, a Translate to all languages action, and per-step wording groups such as Welcome 0 of 6 and Select Document 0 of 7" />
</Frame>

### Billing and usage

Spend is easier to read, and a failed payment explains itself.

* **Prepaid volume discounts** — prepaid credits use charge discounts instead of bonus credits: save 4% at $250, 7% at $1,000, and 10% at \$2,000
* **Pay once per document step, not once per upload** — a step with ten business documents costs the same as one with two
* **Monthly invoices for contract billing** — contract-billed organizations receive a monthly usage invoice settled in the payer's currency
* **Auto-recharge explains itself** — a failed attempt records and shows the decline reason, and auto-recharge resumes automatically once the payment method is replaced
* **A rebuilt Usage page** — sortable tables, search inside the breakdown dialog, a promoted total-cost figure, and a free-tier counter
* **A machine-readable code on insufficient credits**, so your integration can react to it programmatically

<Frame>
  <img alt="The Top up prepaid balance dialog showing $50, $250, $1,000 and $2,000 tiers with Save 4%, Save 7% and Save 10% badges" />
</Frame>

### Native SDKs

Native SDKs shipped steadily all month, landing every platform on 4.7.x with materially smaller binaries.

* **React Native 4.5.4 to 4.7.5**, **Android 4.5.4 to 4.7.4**, **iOS 4.5.4 to 4.7.2**, **Flutter 4.6.0 to 4.7.2**
* **Smaller apps** — iOS variants are materially smaller, and a lighter on-device engine now powers auto-capture on both platforms
* **Wallet support is optional on Android** — wallet connection ships as a separate dependency, so your app carries it only when you use it
* **Per-step welcome copy** — welcome text resolves against its own workflow step, and title overrides apply on fully white-labeled apps
* **Framework support** — the React Native TurboModule specification supports React Native 0.77 code generation, Kotlin 2.2 is supported, and Flutter passes the device locale into the session so the flow opens in the user's language
* **Android 16** — Active Liveness camera previews render correctly on Android 16 devices; React Native 4.7.5 carries the Android 4.7.4 build that fixes it
* **iOS still-photo capture** — the iOS SDK falls back to still-photo capture on iOS 15 when the live video frame is unavailable
* **Crash symbolication** — the React Native SDK publishes iOS dSYM artifacts from 4.5.4, and Expo Android dependency collisions are resolved across all variants

<Frame>
  <img alt="Didit card titled Native SDKs 4.5.4 to 4.7.5" />
</Frame>

### Didit Academy

Ten video lessons take you from your first workflow to reading a verification result, each with a full timestamped transcript in these docs.

* **Ten lessons on YouTube** — [platform tour](https://www.youtube.com/watch?v=skV9iUR2UhQ), [what your users see](https://www.youtube.com/watch?v=LzGe-dMWjUw), [build a KYC workflow with no code](https://www.youtube.com/watch?v=7-nJ3JE20i4), [connect Didit to Claude with MCP](https://www.youtube.com/watch?v=I3UkFIhW548), [read a verification result](https://www.youtube.com/watch?v=7htTWCWsl60), [KYB from registry to UBO](https://www.youtube.com/watch?v=JEnW_sEe35Y), [real-time transaction monitoring rules](https://www.youtube.com/watch?v=Yhm63_n7HuU), [integrate the API, SDKs, and webhooks](https://www.youtube.com/watch?v=fX03-WEu_EI), [analytics, teams, and roles](https://www.youtube.com/watch?v=sRcOBxjRYag), and [pricing explained](https://www.youtube.com/watch?v=aTWy1rfChhI)
* **Watch the full course** in the [Didit Academy playlist](https://www.youtube.com/playlist?list=PLIikxNViJoCY)
* **Searchable transcripts** — every lesson has a timestamped transcript in the docs, and each paragraph deep-links to that exact moment in the video. Start at [Didit Academy](/academy/overview)

<Frame>
  <iframe title="What Is Didit? Full Platform Tour — KYC, KYB and Transaction Monitoring" />
</Frame>

### Trust and compliance

Where the age-assurance work above sits in Didit's credentials.

* **Age verification is certified in Germany** — FSM, Germany's youth-protection self-regulator, certified that Didit's age-verification system reliably establishes a closed user group under Section 4(2) JMStV. See [Certifications](/getting-started/certifications)
* **Biometric anti-spoofing** — iBeta Level 1 presentation-attack detection under ISO/IEC 30107-3, tested by a NIST-accredited laboratory
* **FIDO Alliance** — Didit joined the FIDO Alliance as an Associate Member on August 13, 2026

### Improvements

Smaller changes across the Business Console, the API, and the verification flow.

* Download a user's PDF report directly from user details, and get one report covering every session a returning user has completed
* Start a workflow with a branch, and route branches on the session metadata you set at session creation
* Workflows keep running unchanged as new document subtypes are added or renamed
* A resubmission replays the full workflow graph, including webhooks
* Proof of Address keeps the address exactly as printed on the document, and reads a utility bill's payment deadline as a payment date
* Compliance country questions group countries by continent, with select-or-clear for a whole continent
* Merchants using the Shopify app can see their verification results in the Shopify admin
* Pending invitations are listed before accepted members, and your organization ID is shown in Organization Settings


# December 2025
Source: https://docs.didit.me/changelog/december-2025

Advanced questionnaires, real-time collaboration, AML for businesses, database validation expansion, and platform performance gains across Didit.

* **Advanced Questionnaires** — Dynamic questionnaires that adapt in real time: show/hide questions based on previous answers, split flows into sections, and preview full branching logic before publishing
* **Questionnaires Analytics** — Visual summaries and graphs for questionnaire results (including source-of-funds charts) for easier pattern spotting
* **Encrypted PDF Support** — Now supporting encrypted PDFs with password handling and improved browser compatibility
* **New Users Section** — The Console now includes a Users area with user detail pages (documents, verifications, metadata) so teams can investigate across sessions
* **Real-time Session Collaboration** — Session chat, tags, notifications, and reviews are now real-time, improving coordination for ops/compliance teams
* **AML: Business Entities** — Added support for company/business AML checks, expanding coverage beyond individuals
* **Database Validation Expanded** — Extended to Chile, Panama, Paraguay with UI improvements and lower pricing in certain cases
* **Precise Billing** — Clearer cost reporting with total cost + cost breakdown in session details
* **Whitelabel & Domain Safety** — Safer whitelabel setup with subdomain-only rules and updated app configuration
* **Extra Fields** — Added middle name, improved address handling (parsed + raw), and more country-aware name rules (e.g., Brazil edge cases)
* **Platform Performance** — Multiple backend optimizations for faster queries and fewer incidents


# February 2025
Source: https://docs.didit.me/changelog/february-2025

AML ongoing monitoring, streamlined verification, age and gender estimation, and CSV exports across Didit's identity verification platform.

* **AML Ongoing Monitoring** — Daily automated checks against 230+ databases for PEP, sanctions, warnings, and adverse media (Pro Plan)
* **18 Supported Languages** — Added new languages to the verification process
* **Streamlined Verification Flow** — Auto-skip single-option screens; auto-preselect country based on user IP
* **Demo Repos** — New demo repositories for integrating verification in Expo (React Native) and Flutter via WebView
* **Age and Gender Estimation** — Now included in the KYC flow for more comprehensive verification
* **Export Sessions as CSV** — Export verification sessions from the Business Console (Dashboard → Verifications)
* **Delete Sessions** — One-click session deletion from the Verifications section


# February 2026
Source: https://docs.didit.me/changelog/february-2026

Spanish financial sandbox results, e-commerce integrations, native SDK updates, AI agent integration, and social login on the Didit platform.

### Spanish Financial Sandbox Conclusions

After more than a year of testing inside Spain's financial sandbox, the official conclusions report from the Spanish Treasury, CNMV, and SEPBLAC has been published. The results confirm that Didit's NFC + active biometrics technology blocks the most advanced fraud scenarios — including deepfakes and document manipulation — delivering security equivalent to or superior to in-person verification.

* **Fraud reduced to residual levels** — Even sophisticated deepfake and impersonation attacks were blocked
* **EBA-compliant** — Full alignment with European Banking Authority guidelines on digital onboarding
* **Positive regulatory evaluation** — Both CNMV and SEPBLAC validated Didit's approach for financial services
* **ICAO-standard NFC verification** — Chip-based document reading valid in 150+ countries

[Read the full success story →](https://didit.me/blog/success-story-spanish-financial-sandbox-confirms-didit-new-standard-digital-onboarding)

<Frame>
  <img alt="Didit — conclusions published from Spain's financial sandbox with formal supervisory attestation" />
</Frame>

### E-Commerce Integrations

New plugins to add identity verification directly into your Shopify or WordPress store. Merchants can configure verification preferences, pass custom data, and verify customers without leaving the platform.

* **Shopify Plugin** — Install the Didit app from the Shopify App Store and start verifying customers in minutes
* **WordPress Plugin** — Drop-in plugin for WordPress and WooCommerce sites with flexible configuration options

<Frame>
  <img alt="Didit e-commerce integrations for Shopify and WordPress stores" />
</Frame>

### Native SDKs

We shipped major SDK updates across all platforms this month.

* **Native Android SDK** — Full-featured Android SDK with document detection, camera capture, video recording, NFC chip reading, phone and email verification, resubmit support, and privacy mode
* **Native iOS SDK** — Expanded iOS 13+ support, Swift 6 compatibility, and NFC settings navigation when NFC is disabled
* **Flutter SDK** — New Flutter SDK for cross-platform mobile integration
* **React Native SDK** — New React Native SDK for cross-platform mobile integration
* **SDK v3.2.0** — Translation fixes across 47 languages and improved UI components on all platforms

<Frame>
  <img alt="Didit native SDKs for Android, iOS, Flutter, and React Native" />
</Frame>

### AI Agent Integration

New MCP server and programmatic APIs that let AI agents run identity verification workflows end to end — create sessions, trigger checks, and read results without a UI. Perfect for building automated onboarding pipelines or integrating verification into your own AI-powered tools.

<Frame>
  <img alt="Didit AI Agent Integration — MCP server connecting coding agents to identity verification" />
</Frame>

### Social Login & Passkeys

Sign in to the Console with GitHub, Google, Apple, or Microsoft. We also added passkey support for passwordless login and SSO enforcement for organizations that require it.

### Face Search Performance

Major improvements to the face search algorithm — significantly faster and more accurate duplicate detection and blocklist matching, even at scale.

### Resubmission Flow

Users who fail verification can now resubmit their documents and selfies directly. The Console shows the resubmission status and lets your team review corrected submissions without starting over.

### Age Verification by Country

Set different age rules per country or state. Configure minimum and maximum age thresholds, and choose what happens when a user falls outside the range — decline automatically or send to manual review.

### New Document Support

* **Mongolia ID** — National identity card
* **Ontario Photo Card** — Canadian provincial photo ID
* **Mexico Driver's Licenses** — Multiple states supported
* **Germany Driver's License** — Added to supported documents
* **Date of Issue** — Now available as a workflow branching condition, so you can route sessions based on how recently a document was issued

### Improvements

* AML reports now include richer metadata for deeper compliance insights
* Image quality checks run before processing to catch blurry or dark photos early
* Low-balance email notifications so you never run out of credits unexpectedly
* Alphanumeric email verification codes for better security
* Public API endpoints for managing blocklists
* Better image compression for faster uploads on slow connections
* Improved country selector in the Console
* Proof of Address now supports months-since-issue validation

### Fixes

* Fixed document side mismatch between front and back captures
* Fixed OCR accuracy for Brazilian documents
* Fixed translation issues across all SDKs
* Fixed various authentication and SSO edge cases


# January 2025
Source: https://docs.didit.me/changelog/january-2025

New frontend design, step-by-step video, QR and barcode detection, OCR improvements, and white-label across Didit's identity verification platform.

* **New Frontend Design** — Revamped design for a more intuitive verification process with optimized AI models and reduced loading times
* **Step-by-Step Video** — Added video guide walking users through the KYC process, accessible via `kyc.front_video` / `kyc.back_video` in the session model
* **QR & Barcode Detection** — Enhanced accuracy for barcodes and QR codes
* **OCR Improvement** — Faster and more accurate document processing, with significant improvements for Arabic and other languages
* **Generate PDF API** — New API to generate PDF reports for verifications
* **White-Label** — Fully customize verification flows with your branding from the Business Console


# January 2026
Source: https://docs.didit.me/changelog/january-2026

Node-based workflows, native iOS SDK, advanced AML, webhook testing, and platform improvements across the Didit identity verification platform.

### Node-Based Workflows & Decision Engine

We have completely overhauled how verification flows are built.

* **Node-Based Workflows** — Create custom workflows with complex decision trees and specific nodes (e.g., "Determine Final Status")
* **Custom Rules** — Added support for granular custom rules within the workflow graph
* **Visual Editor** — The Console now features a new visual graph editor to help you design and visualize complex user journeys

<Frame>
  <img alt="Node-Based Workflow Visual Editor" />
</Frame>

### Native iOS SDK

We are excited to launch our fully native iOS SDK, bringing a smoother experience to Apple devices.

* **Compatibility** — Full support for devices running iOS 13+
* **NFC Capabilities** — Native NFC chip reading enabled for devices running iOS 15+

### Advanced AML & Fraud Detection

We've deepened the data available for compliance teams.

* **Risk & Match Scores** — The AML report now includes detailed `risk_score`, `match_score`, and configurable thresholds/weights
* **AML Summary Page** — A dedicated summary page in the Console for a quick overview of hits
* **Phone Fraud Signals** — Added "Shared Device Mode" and new phone verification signals to detect high-risk numbers or reused devices

<Frame>
  <img alt="AML Screening in Workflows" />
</Frame>

### Webhook Testing

Developers can now test webhooks directly from the dashboard to ensure their listeners are configured correctly before going live.

<Frame>
  <img alt="Test Webhook from Console" />
</Frame>

### Improvements

* **Face Verification Benchmarks** — Updated thresholds for face matching and liveness to improve pass rates for genuine users
* **Health Insurance Cards** — Added as a valid document type
* **New Document Support** — USA California ID/DL, Costa Rica ID, Malaysia/Netherlands/Australia DL improvements, Mexico Voter Card
* **Performance** — Lower memory usage and faster processing on older devices
* **Database Optimization** — Significantly faster API response times for session lookups
* **CSV Exports** — Now includes more columns for POA and Phone verifications

### Fixes

* Fixed Android WebView `Java object is gone` error affecting post-message communication
* Fixed questionnaire migration, locale/translation loading, and header rendering bugs
* Fixed blurry photos when switching cameras on multi-lens devices


# July 2025
Source: https://docs.didit.me/changelog/july-2025

Shared sessions API, passive liveness API, face search enhancements, and low-bandwidth support across Didit's identity verification platform.

* **Shared Sessions API** — New Share Session and Import Shared Session APIs for B2B verification data sharing between trusted partners
* **Passive Liveness API** — New standalone API for performing passive liveness checks
* **Face Search Enhancements** — Refined algorithm with significantly improved accuracy for duplicate detection and blocklist matching
* **Data Retention Controls** — Set custom data retention policies from 1 month to 60 months, or indefinitely
* **PDF Multilingual Support** — PDF reports now support RTL languages (Arabic, Hebrew) with improved compatibility
* **Improved Photo & Video Capture** — Better quality during ID and face liveness checks for improved OCR accuracy
* **Faster Verification** — Reduced number of steps in the flow; quicker screen transitions
* **Language Picker** — Users can select their preferred language directly during verification
* **Low Bandwidth Support** — Verification flows run smoothly on 3G networks and older devices with dynamic feature adjustment
* **User Logout Button** — Secure logout from the verification process when authenticated
* **Real-Time Web Notifications** — Desktop users receive real-time updates when continuing verification on mobile
* **New Territories** — Western Sahara, Saint Martin, Luhansk, Falkland Islands, Christmas Island, Cocos Islands


# July 2026
Source: https://docs.didit.me/changelog/july-2026

July 2026 release: Travel Rule compliance, Console Copilot, applicant data review, Test mode, device integrity, SOC 2 Type 2 and FSM certifications, and native SDK updates.

### Travel Rule for Crypto Transfers

When your users send or receive crypto, regulators increasingly require you to exchange sender and recipient details with the counterparty institution before the transfer settles. Didit now handles that end to end.

* **Encrypted information exchange** — sender and recipient details are exchanged automatically using IVMS 101, the industry data standard, with encrypted payloads
* **Broad interoperability** — Didit routes each transfer over the counterparty's preferred network and includes a native implementation of the open TRP messaging standard
* **Secure email fallback** — when a counterparty isn't reachable on any network, Didit sends a protected pickup link so the transfer still gets compliant treatment
* **Counterparty directory and address book** — find virtual asset service providers (VASPs) in a directory seeded from the EU's official register of authorized crypto-asset providers, then save and reuse tagged wallet addresses
* **Self-custody ownership proof** — a white-labelled widget lets users prove control of their own wallet by signature (or screenshot proof where you allow it) across Ethereum-compatible networks, Solana, Bitcoin, and Tron — connecting any major wallet, including by QR code
* **Ready-made EU rules** — start from a preset bundle for the EU Transfer of Funds Regulation, and set your jurisdiction: EU, UK, Switzerland, Singapore, US, or UAE
* **Due diligence and timeouts** — every counterparty gets a due-diligence score that can gate a transfer, and you choose what happens when a confirmation deadline passes
* **Built-in testing and events** — create sample transfers in the **Console**, track usage, and receive a webhook for each status change

<Frame>
  <video />
</Frame>

### Didit Copilot in the Console

Didit Copilot helps you operate the Business Console from every page while keeping you in control of consequential actions.

* **Ask from anywhere** — open the resizable Copilot panel from the **Ask** pill in the **Console** header and get starting prompts tailored to the page you are viewing
* **Build and navigate for you** — create workflows, apply list filters, and open the right dialogs through natural-language requests
* **You approve every change** — anything that writes or deletes waits for your explicit confirmation
* **Watch the work happen** — see workflow blocks appear node by node, and stop the Copilot whenever you need to
* **Talk, type, or attach** — use voice input, add a file, and return to searchable conversation history that resumes after a dropped connection

<Frame>
  <video />
</Frame>

### ID Verification Data Review

A new applicant review step lets users confirm or correct extracted identity-document fields before they submit.

* **Review in every language** — applicants can check standard and document-specific fields in every supported language, including flows that also use chip reading
* **Actions by mismatch severity** — configure separate outcomes for critical and minor corrections while protecting fields validated by the document's machine-readable zone (MRZ) from edits
* **Complete correction history** — session details show each original value beside the applicant-confirmed value
* **Capture quality check** — optionally let applicants inspect and retake the cropped document image before submitting; this screen appears only for camera scans

<Frame>
  <img alt="Applicant reviewing and correcting extracted document data before submitting" />
</Frame>

### Test Mode

Sandbox applications now provide a complete Test mode for exercising integrations without contacting external providers.

* **Choose the result first** — pick approved, declined, or in review, including review scenarios for individual feature groups
* **Test more paths quickly** — run business-verification registry scenarios, upload sample documents with one tap, and enter any one-time password (OTP) code
* **Clear in every surface** — persistent banners identify Test mode in both the verification flow and the Console, while API keys carry environment badges
* **Visible simulated usage** — zero-price activity remains in usage tables, and mocked sections carry simulated-data chips
* **Real captures, mocked results** — captured media stays available for realistic review while extracted data remains synthetic
* **Integration-ready scenarios** — no external provider is ever called, your automated tests can assert the armed scenario (returned as `sandbox_scenario` in the v3 decision payload), and native SDKs support Test mode from version 4.2.0

### Device & Capture Integrity

New device and capture signals help you respond to tampered apps, emulators, and manipulated camera input without adding friction for legitimate users.

* **Operating-system attestation** — verify app and device integrity with Apple App Attest and Google Play Integrity
* **Capture integrity signals** — detect frame injection and show the attack subtype on face-attack warnings
* **Virtual-camera flag** — mark sessions that present a virtual or external capture device as a risk signal
* **Actions per workflow** — decline, review, or record device and capture risks according to each workflow's policy
* **Safe outage behavior** — configuration outages on Didit's side do not decline legitimate applicants, and risk reasons are translated
* **Escape from in-app browsers** — users in chat apps' built-in browsers get a clear screen for reopening camera steps in their main browser

<Frame>
  <img alt="Hardware-backed device attestation and capture integrity signals" />
</Frame>

### Workflow Builder Upgrades

The workflow builder now supports richer branching, clearer controls, and safer version management.

* **Merge and regional branches** — bring branches back to one merge point, route by US state, and apply IP geofencing rules
* **More configurable actions** — decide what happens when a phone number is flagged as high risk, when the same face appears under a different name, or when a database check does not apply
* **Recorded chip-read outcomes** — see the specific reason when near-field communication (NFC) is skipped
* **More KYB control** — configure registry fields and VAT actions, toggle beneficial owner (UBO) and shareholder collection, and accept business licences or tax registration certificates
* **True version recovery** — delete drafts and restore earlier versions for both workflows and questionnaires
* **Clearer build decisions** — see each step's price and a warning when file upload reduces forgery protection compared with camera capture
* **Safer standalone checks** — document liveness now starts enabled for the standalone ID Verification API

### Business Verification (KYB)

Business verification now collects the right registry and document information with less applicant effort across more markets.

* **EU VAT validation** — validate VAT numbers through the EU's VAT Information Exchange System (VIES)
* **Configurable company search** — choose registry fields and prefill and lock both company name and registration number for applicant confirmation
* **Local documents in 103 countries** — show familiar local document names and recognize business licences and tax registration certificates
* **Fewer false declines** — accept notarial deeds more reliably and treat user-entered information as the source of truth
* **Document AI results in KYB** — receive newly available extracted custom-document results in KYB payloads and the PDF report
* **Only enabled sections appear** — keep disabled UBO, shareholder, registration-number, and contact sections hidden from applicants
* **Larger uploads** — accept business, proof-of-address, and custom-document files up to 30 MB

### Ongoing AML Monitoring for Users and Businesses

You can now manage ongoing anti-money laundering (AML) monitoring directly for each user or business.

* **Per-record controls and status** — enable or disable monitoring from list rows and follow it in a dedicated column on the **Users** and **Businesses** tables, with screening categories explained inline
* **Know the impact first** — see a cost estimate before enabling monitoring and automatically screen identities that have not been checked before
* **One record per identity** — reuse a single monitored record instead of creating duplicates and duplicate charges
* **Transparent bulk jobs** — process many records together and see explicit skip reasons for every record that could not be monitored

### Transaction Monitoring: SDK Submission and Step-Up Remediation

Transaction monitoring now connects native submission, device intelligence, and biometric step-up remediation in one flow.

* **Submit from native SDKs** — send transactions with device intelligence attached, and receive an `action_required` response whenever the user has to do something
* **One-selfie step-up** — hold a flagged transaction while awaiting the user, then reuse the stored face for biometric remediation with one selfie and no document
* **Choose the remediation path** — select a workflow or workflow group for user-action rules
* **Richer rule inputs** — compare sender fields with receiver fields and use your custom lists in text rules
* **Faster list review** — use verification-style filters with currency and asset icons across transaction lists

### Verification Flow Experience

The verification flow is more reliable on real devices and clearer about what applicants need to do next.

* **Reliable auto-capture** — removed capture deadlocks and false “too dark” messages while improving distance guidance
* **Better camera control** — added pinch-to-zoom, localized rear-camera selection, iOS black-screen recovery, and clean camera release between document and face steps
* **Visible capture recovery** — camera failures show a retry action, microphone access never blocks the camera, and the frame border provides live feedback
* **Clearer waiting screens** — redesigned processing screens explain what is happening instead of leaving applicants guessing
* **Progress from start to finish** — the **Welcome** screen shows estimated time, while the progress bar, completion screens, error screens, one-time-code entry, and phone input use refreshed designs
* **Clearer proof of address** — show country and accepted languages, use canonical subtypes, and order document types by country, with Australia added to the per-country ordering

### Native SDK Updates

Versions 4.0.9 through 4.5.3 brought the latest Didit capabilities to iOS, Android, React Native, and Flutter.

* **Transactions and wallet ownership** — submit and retrieve transactions with automatic user actions, and run wallet-ownership proof natively
* **Test mode from 4.2.0** — use the scenario picker and sample documents directly in native integrations
* **Swift Package Manager support** — integrate the iOS SDK through Swift Package Manager in React Native and Flutter while keeping CocoaPods support
* **Smaller Flutter variants** — choose `didit_sdk_core`, `didit_sdk_autodetection`, or `didit_sdk_nfc` with the same Dart API and a smaller native footprint
* **Right-to-left and language coverage** — use Arabic right-to-left layouts and Hebrew localization
* **Capture polish and stability** — get image review by default, SMS OTP autofill, per-country document ordering, an unmirrored front camera, and more stable face capture on high-resolution Android cameras

<Frame>
  <img alt="Didit native SDK releases 4.0.9 through 4.5.3 for iOS, Android, React Native, and Flutter" />
</Frame>

### Document Coverage & AI Extraction

We continued June's extraction expansion with new documents, regions, and more precise field mapping.

* **New supported documents** — added Australia's Larrakia Nation ID Card and Northern Territory Proof of Identification Card, plus another Israeli ePassport variant
* **AI-powered extraction expanded again** — added coverage for Israeli and Kyrgyzstani documents, German health insurance cards, New Jersey IDs, Pennsylvania commercial driving licences, and the British Columbia ID family
* **Canonical issuing regions** — return a document's state or province as ISO 3166-2 so you can distinguish regional documents without parsing text
* **More precise document controls** — exclude the legacy Chilean carnet subtype and receive distinct Australian licence-number and card-number fields

### Database Validation & Analytics

New analytics and validation behavior make it easier to evaluate coverage, speed, and real-world outcomes.

* **Coverage and latency widgets** — compare match coverage and median and 95th-percentile response times by country and database
* **Flexible analytics views** — expand coverage to a full-screen world map and let charts choose the right time grouping for the selected range
* **Cleaner catalog** — low-coverage databases have been removed instead of returning consistently empty results
* **Regional validation updates** — derive Spain DNI/NIE addresses from proof-of-address data, while India Aadhaar no longer requires organization onboarding
* **Clearer outcomes** — incomplete requests return a clear validation error, and empty validation responses resolve to In Review instead of passing silently

### Right-to-Left Languages & Translation Quality

Arabic, Hebrew, and document translations now feel consistent across both the Console and the verification flow.

* **Arabic and Hebrew coverage** — use right-to-left Arabic layouts across the Console, Copilot, and verification flow, with Hebrew coverage throughout the flow
* **Reviewed labels and events** — get improved proof-of-address and business-document names in Estonian, Slovak, Korean, Japanese, Chinese, Catalan, Portuguese, and other supported languages, plus translated event labels
* **Locale links stay respected** — explicit language URLs keep the selected locale as you navigate

### New Certifications

Two independent credentials to announce, both verifiable from our public [Security & Compliance center](https://didit.me/security-compliance/).

* **SOC 2 Type 2** — an independent audit against the AICPA Trust Services Criteria confirmed that Didit's security, availability, and confidentiality controls **operated effectively** over a five-month observation period (March–July 2026) — the operational follow-up to April's Type 1. The report is available to customers under NDA
* **Certified for youth protection in Germany** — Germany's youth-protection self-regulator (FSM) certified that Didit's Age Verification System reliably establishes a closed user group under Section 4(2) of the Interstate Treaty on the Protection of Minors (JMStV), so only verified adults reach age-restricted content
* **Every credential in one place** — the docs gained a dedicated [Certifications page](/getting-started/certifications) listing every audit and attestation we hold, with dates and how to get each report — and we're adding more all the time

<Frame>
  <img alt="Didit certifications — SOC 2 Type 2 and FSM youth-protection certification" />
</Frame>

### Improvements

* **Reusable verification imports** — imported individual and business sessions return the complete decision, with `session_kind` and `shared_from_session` fields so you can trace where a reused verification came from; existing v2 integrations are untouched
* **Use Didit inside your identity provider** — identity providers can now delegate verification to Didit over OpenID Connect (with Pushed Authorization Requests and PKCE) and receive standards-based verified claims back
* **Reliable final webhooks** — the webhook that closes out a session can no longer be lost, and signature validation now works consistently for events carrying dates and amounts
* **Sessions never get stuck** — verifications stalled on a background step resume on their own, and session-list requests are answered once instead of twice
* **Balance safeguards** — balances update in real time, and new billable work stops when an account has a negative balance
* **Questionnaire drafts** — delete unpublished questionnaire versions cleanly
* **Accurate date and cost views** — custom date ranges follow your local calendar and every cost-breakdown row has a complete label
* **True-to-device customization preview** — preview every screen with the same proportions and presentation applicants see
* **Calmer Console updates** — real-time changes patch lists in place, and the sidebar stays open while you navigate
* **Findable session warnings** — the warnings filter adds search, collapsible groups, and per-group counts
* **Workflow-aware resubmission** — the resubmit dialog is built from your actual workflow graph, including branches, so you re-request only the steps you need
* **Honest check states** — checks that never ran show as "not evaluated", disabled validations read "Not applicable", and a skipped chip read states its reason
* **Sessions for existing users** — search your users when creating a session and reuse their stored portrait
* **Account security** — require a two-factor code to delete applications, recover accounts through identity-verified support, reset passkeys, protect sandbox applications from deletion, and keep application mode immutable
* **Longer, clearer invitations** — invitations remain valid for 30 days, show when expired, and correctly match email addresses from providers that treat dots as optional
* **Organization-wide administration** — owners and admins span every application, and the members page stays fast as teams grow
* **MCP server updated** — supports the latest Model Context Protocol revision (2026-07-28) while remaining compatible with existing clients
* **Deploy-safe flow reloads** — recover from a stale page after a deployment and continue the current session
* **Fewer false liveness rejections** — borderline passive-liveness results are automatically double-checked before a decision is made
* **Smarter proof-of-address review** — handle abbreviated or reordered names and respect printed expiration dates
* **More proof-of-address coverage** — accept India driving licences as proof of address
* **Safer manual checks** — run document liveness by default for individual checks started from the Console


# June 2025
Source: https://docs.didit.me/changelog/june-2025

PDF and POA enhancements, white-label improvements, Stripe invoice generation, and OCR optimization across Didit's identity verification platform.

* **PDF & POA Enhancements** — Improved text extraction, resolved missing pages, faster and more reliable POA verifications
* **White-Label Improvements** — Expanded customization including favicon support
* **Invoice Generation** — Stripe invoices integrated directly into the Business Console
* **Face Search** — Enhanced matching logic for faster and more accurate liveness checks
* **Barcode Optimizations** — Improved detection accuracy across multiple document types
* **OCR & Document Analysis** — Optimized for greater speed and accuracy
* **Adverse Media & AML** — Significantly expanded coverage and improved media quality
* **ID Verification** — Added first name, last name, expected details, and contact information to webhooks and session endpoints
* **Session Handling & API** — New endpoints for easier listing and management of sessions
* **Frontend** — Better loading indicators, improved camera support for older devices, auto-selection of document type, adapted video sizing, improved POA camera preview


# June 2026
Source: https://docs.didit.me/changelog/june-2026

June 2026 release: Document AI custom document verification, transaction detail redesign, native SDK 4.0.x updates, white-label brand import, and MCP Server v5.

### Document AI Verification

A brand-new verification feature. Define any custom document your business needs — contracts, licenses, certificates, statements — and Didit's AI reads it and extracts exactly the fields you configure.

* **Define any document** — create your own document types with the fields you want extracted, no template required
* **Auto-suggest fields from a sample** — upload a sample document and Didit proposes the extraction fields for you, with a per-organization daily limit
* **Built-in upload flow** — your users get a new "Documents" step in the verification flow, with clear retry prompts and an attempts-left counter when a file can't be read
* **Results everywhere** — extracted documents are returned in the decision and events endpoints and delivered through webhooks
* **Workflow builder integration** — auto-detect extraction fields from a sample right inside the editor, and map a full-name field so extracted names can be matched against the verified identity
* **Console review** — session details get a dedicated Document AI section, in the same style as KYB documents, showing every extracted field
* **Every language, automatically** — document definitions are translated into all supported verification languages the moment you save them
* **Native SDK support** — available on iOS, Android, React Native, and Flutter on SDK versions 4.0.7 and above

<Frame>
  <img alt="Workflow builder auto-detecting Document AI extraction fields from a sample document" />
</Frame>

### Transaction Detail Redesign

The transaction detail page was redesigned to match the KYC session experience, so reviewing a flagged transaction feels the same as reviewing a verification.

* **Counterparty flow cards** — sender and recipient are shown as horizontal flow cards, so you see who sent what to whom at a glance
* **State-aware rule rows** — triggered rules collapse into compact rows that surface each rule's outcome and description without opening a dialog
* **Related transactions table** — related activity is now a paginated table instead of an endless list
* **Threshold-colored score** — the transaction score pill takes its color from your organization's own review and decline thresholds
* **Dark mode polish** — badges, tags, and section animations were tuned for full dark-mode legibility

<Frame>
  <video />
</Frame>

### Native SDK Updates

A steady stream of 4.0.x releases across iOS, Android, React Native, and Flutter this month.

* **Document AI support** — the new custom-document verification step works natively in every SDK
* **KYB upgrades** — document requirements guide users to upload the right business document, and ownership percentage is now optional to match industry practice
* **PACE NFC on Android** — passports and IDs protected with PACE can now be read over NFC on Android
* **Social Security Card** — new document type supported across all four SDKs
* **iPhone 17 liveness fix** — liveness video recording issues on the newest iPhones were resolved
* **App Store submission fix** — resolved the iOS privacy-manifest warning so your submissions pass review cleanly
* **Algeria NFC** — chip reading now works for Algerian documents
* **Active liveness polish** — removed the brief screen flash when the active-liveness intro starts

<Frame>
  <img alt="Didit native SDK releases for iOS, Android, React Native, and Flutter" />
</Frame>

### White-Label Upgrades & Brand Import

Making the verification flow look like *your* product now takes seconds instead of an afternoon.

* **Import your brand from your website** — enter your URL and Didit detects your logo, colors, and fonts and maps them onto the verification flow automatically (rate-limited per organization)
* **Applied from day one** — new organizations can have their branding imported and applied automatically during onboarding
* **Logos rendered faithfully** — customer logos are never clipped, cropped, or force-rounded, whatever their aspect ratio
* **Theme-aware everywhere** — every screen, including KYB steps, radio groups, and loaders, follows your theme
* **Softer default look** — the default white-label corner radius moved to 24 for a more modern feel

<Frame>
  <img alt="White-label customization preview in the Didit Business Console" />
</Frame>

### Notification Preferences

You now control exactly which notifications you receive, per event and per channel.

* **Preferences matrix** — a new Notifications tab in Account Settings lists every event with a toggle per channel, per user
* **Conservative defaults** — new accounts start with only the notifications that matter, not everything
* **Slack disconnect** — unlink your Slack notification channel in one click
* **Send a test** — fire a test notification to confirm a channel works before you rely on it
* **Throttled failure alerts** — webhook-failure notifications are limited to one per 30 minutes, so an outage doesn't flood your inbox
* **Redesigned emails** — notification emails were rebuilt to match the clean design of the rest of Didit's emails

<Frame>
  <img alt="Per-user notification preferences matrix in Account Settings" />
</Frame>

### KYB Registry Improvements

Business verification keeps getting more automatic — less typing for applicants, more data for reviewers.

* **Company field prefill** — registration number, address, share capital, and location are prefilled from the registry, so applicants only confirm
* **Previous and parent names** — a company's former names and parent-company names now appear on the business detail page
* **Registry section** — registry check results render in their own dedicated section on business details
* **Optional UBO email** — email is no longer required for beneficial owners who don't need to complete KYC
* **Automatic UBO emails** — beneficial owners who do need KYC receive their verification email automatically, with one-click resend
* **No duplicate parties** — associated parties confirmed once can be reused instead of being added twice

<Frame>
  <img alt="KYB business registry details in the Didit Business Console" />
</Frame>

### Smarter Transaction Rules

The transaction-monitoring rule engine understands more of your data.

* **New operators** — rule conditions now support date comparisons, regex matching, fuzzy matching, and `in` (match against a list of values), in the API and the Console rule editor alike
* **Better crypto screening** — wallet screening detects the correct chain for each transaction and surfaces screening failures instead of hiding them
* **Richer network graph** — the counterparty network graph shows a more complete picture of the accounts around a transaction
* **Live updates** — transaction lists and detail views update in real time, no refresh needed

### MCP Server v5.0.0

The Didit MCP server — the way AI agents run verifications, screen wallets, and manage your workflows — had its biggest release yet.

* **Public marketplace release** — v5.0.0 ships with a registry manifest and a Cursor plugin, and its tool metadata is aligned with OpenAI's app review guidelines, so you can install Didit wherever your agents live
* **Scoped access tokens** — agents exchange credentials for narrowly-scoped tokens using the standard token-exchange flow, so each agent only gets the permissions it needs
* **Org-scoped user tokens** — the session API now accepts organization-scoped user tokens, so agents can act on behalf of a signed-in user within the right organization

<Frame>
  <img alt="Didit MCP Server v5 — available in AI agent marketplaces" />
</Frame>

### Expanded AI Document Extraction

AI-powered data extraction was enabled for roughly 300 additional document types this month, focused on documents from Arabic-speaking countries and document types that historically had lower extraction accuracy. Expect noticeably better results on these documents with no integration changes on your side.

### Improvements

* **Faster verification flow** — the verification web flow loads significantly less code up front, making it noticeably faster on slow connections
* **Responsive Console redesign** — a sweep across the Business Console brought a responsive layout, restyled inputs, and consistent tables to every page
* **Column visibility** — Users and Businesses tables gained a column-visibility toolbar, matching the sessions list
* **Organization-level lists** — list sessions, businesses, transactions, and cases across all applications in your organization through the API, with each row attributed to its application
* **Guided onboarding** — a new post-signup create-organization wizard plus a self-driving guided tour that performs each step for you
* **Demo organization** — the demo environment now seeds 1,000+ realistic sessions so you can explore the Console with meaningful data
* **Sandbox template gallery** — pick a ready-made test persona and the sandbox sets the country and document type for you
* **Field blurring everywhere** — document field blurring for data minimization is now available for all countries, not just the EU
* **Better data imports** — CSV imports report specific row-level errors before committing, and imported records carry an "Imported" badge across lists
* **Stay signed in** — Console sessions now stay alive for about 30 days through silent renewal instead of logging you out
* **Console in Italian** — the Business Console is now available in Italian
* **Rename questionnaires** — published questionnaires can now be renamed
* **Questionnaire input validation** — questionnaire fields in the verification flow validate their format as the user types, with inline error messages
* **Password security** — changing your password now signs out your other active sessions

### Fixes

* Fixed the verification flow showing front-side instructions after navigating back from the back-side photo
* Fixed completed sessions occasionally missing their redirect when the final status update was dropped — the flow now recovers and redirects reliably
* Fixed KYB sub-sessions (beneficial owners and key people) starting on an outdated workflow version instead of the latest published one
* Fixed custom status rules not taking other status rules into account
* Fixed company AML screening applying cross-script name matching meant for people, which produced false-positive matches on business names
* Fixed names screened through database validation not appearing in session search results
* Fixed white-label logo and application name on verification emails sent through the API
* Fixed two-factor accounts with both a passkey and an authenticator app being forced into the passkey popup — you now choose the method
* Fixed adding faces to the blocklist failing in certain cases
* Fixed Chilean ePassport number validation and gender extraction on Mexican documents
* Fixed permission edge cases in organization member invitations


# March 2025
Source: https://docs.didit.me/changelog/march-2025

Enhanced AI models, liveness detection upgrades, 47-language coverage, and improved barcode detection across Didit's identity verification platform.

* **ID Verification** — Enhanced AI model accuracy with support for numerous new documents issued in the last quarter
* **Liveness Detection** — Flash and 3D Action models upgraded with 30% better accuracy and improved UX
* **White-Label** — Now billed per completed verification rather than per initiated one
* **AML Sources** — When a hit appears during AML Screening or Continuous Monitoring, you can now access the source directly from the Console
* **47 Languages** — Expanded to support 47 different languages. See [Supported Languages](/integration/supported-languages)
* **Barcode Detection** — Enhanced barcode detection on identity documents
* **IP Geolocation** — Much more accurate VPN and private network detection
* **Document Liveness** — Improved models to better identify photocopies or inconsistencies in real-time document capture


# March 2026
Source: https://docs.didit.me/changelog/march-2026

Revamped analytics, document liveness, database validation expansion, workflow improvements, and native SDK updates across Didit's identity platform.

### Revamped Analytics Dashboard

The analytics dashboard received a major overhaul with richer data and better performance across the board.

* **More Metrics** — New widgets covering warning breakdowns, country distribution, and feature-level stats
* **Faster Loading** — Optimized queries for significantly faster dashboard rendering
* **Improved Filters** — More reliable date-range, workflow, and status filtering

<Frame>
  <img alt="Revamped analytics dashboard in the Didit Business Console" />
</Frame>

### Node-Based Workflow Improvements

The visual workflow editor shipped in January received a wave of usability and reliability improvements this month.

* **Better UX** — Redesigned node layout, improved preview screen, and smoother drag-and-drop interactions
* **Validation on Publish** — Workflows are now validated before publishing, catching configuration errors early
* **Questionnaire Nodes** — Improved questionnaire integration within graph workflows, including better draft and propagation logic
* **Custom Status Rules** — You can now define custom status rules for simple (non-graph) workflows too — not just node-based ones

<Frame>
  <img alt="Node-based workflow editor with publish validation in the Didit Business Console" />
</Frame>

### Console Security & Authentication

* **Redesigned 2FA** — Choose between passkeys and authenticator apps with a cleaner two-factor authentication screen
* **Passkey Management** — Add and manage passkeys from your account settings
* **Connected Devices** — See which devices are signed into your account

### Document Liveness

* **Three Configurable Actions** — Choose what happens when document liveness fails: approve, decline, or send to manual review
* **Workflow Integration** — Configure document liveness directly in the workflow editor alongside other features

<Frame>
  <img alt="Didit document liveness detection with configurable approve, decline, and review actions" />
</Frame>

### Database Validation Expansion

* **Argentina (RENAPER)** — Real-time identity verification against Argentina's national civil registry, joining Brazil, Dominican Republic, Chile, and Paraguay
* **Panama** — Improved integration for more reliable results

<Frame>
  <img alt="Didit database validation — Argentina coverage launch and improved Panama integration" />
</Frame>

### Custom Email Branding

White-label customers can now set a custom sender email address for verification emails, so end users see your brand — not Didit's — in their inbox.

### User Profile Editing

You can now edit a user's date of birth and full name directly from their profile page in the Console — useful for correcting OCR errors or updating records after manual review.

### New Languages

The verification flow, Console, and native SDKs now support three additional languages:

* **Albanian**
* **Bosnian**
* **Kyrgyz**

### Native SDK Updates

Major updates across all native SDKs this month.

* **Android SDK v3.4.1 – v3.4.3** — Fixed document back upload loop, step transition freeze on repeated liveness, questionnaire translations, Samsung file upload picker, and responsive layout issues
* **iOS SDK v3.2.2** — Removed microphone requirement from passive liveness, stripped OpenSSL bitcode for smaller binary size, and resolved symbol collisions with other SDKs
* **Portrait Lock** — The verification process now forces portrait orientation on mobile to prevent layout issues
* **Close & Exit Configuration** — Unified close/exit behavior across iOS, Android, Flutter, and React Native SDKs

### New Document Support

* **Korea** — Improved Korean ID document recognition
* **Ireland** — Enhanced driver's license accuracy
* **Brazil** — Updated support for the 2022 driver's license format
* **India & Panama** — Fixed ID recognition issues
* **Guatemala** — Added support for alien residence cards
* **Mexico** — Fixed surname parsing for names with only two words

### Improvements

* Session creation is faster with fewer database queries per request
* Full-name search is now normalized for more accurate results across different name formats
* Selfie capture added when creating database validation sessions for some countries for stronger identity matching
* NFC certificates expanded for broader document chip reading coverage
* Questionnaire draft and propagation logic improved for more reliable form building
* Blur detection added for document images — flagging low-quality captures before processing


# May 2026
Source: https://docs.didit.me/changelog/may-2026

May 2026 release: native SDK 4.0 with modular variants, configurable document liveness, South Africa database validation, and Mexico INE checks.

### Native SDK 4.0 — Modular Variants

The biggest native SDK release of the year. iOS, Android, React Native, and Flutter all shipped a 4.0 line that splits the SDK into independent variants so you only ship the binary you actually need.

* **Four variants** — `Core` (no NFC, no auto-capture), `AutoDetection` (auto-capture, no NFC), `NFC` (NFC reading, no auto-capture), and `All` (everything)
* **84% smaller binary on iOS Core** — about 6 MB on disk and 3 MB compressed in the IPA, down from \~40 MB in 3.x for apps that don't need MediaPipe-backed auto capture
* **Backward compatible** — existing `pod 'DiditSDK'` and Gradle integrations keep working unchanged; `All` is the default
* **Per-platform pickers** — CocoaPods subspecs and SPM library products on iOS, separate artifacts on Android, Expo config plugin flags on React Native, and `DIDIT_SDK_IOS_VARIANT` / `$DiditSdkIosVariant` on Flutter
* **Migration guide** — new tables in every SDK README explain the install matrix and how to move from 3.x

<Frame>
  <img alt="Didit native SDK 4.0 — modular variants for iOS, Android, React Native, and Flutter" />
</Frame>

### Configurable Document Liveness

Document liveness moved from a single approve/decline switch to a richer per-fraud-type configuration, exposed both in the API and in a brand-new Forgery tab inside the workflow editor.

* **Per-fraud thresholds** — set independent **Decline** and **Review** scores for Screen Replay, Printed Copy, and Portrait Replacement
* **New Forgery tab in the Console** — three sliders replace the older approve/review/decline chips, with full localization across all supported languages
* **Evidence on every warning** — session tooltips now show the actual liveness score, the active thresholds, the decision bucket, and which side of the document produced the result
* **Smarter on uploads** — false-positive "printed copy" warnings on legitimate scanned or photographed IDs were removed; screen-replay and portrait-manipulation still trigger on uploads

<Frame>
  <img alt="Configurable document liveness thresholds in the Forgery tab of the Didit workflow editor" />
</Frame>

### Front and Back Consistency Check

A new check catches users who upload the front of one ID and the back of a different one — caught for the first time on a Bolivian cedula in production.

* **New `DATA_INCONSISTENT` risk** — fires when OCR data on the front doesn't match the back
* **Workflow action** — route inconsistent submissions to Decline, Review, or Approve through the existing `inconsistent_data_action` setting
* **Persisted correctly** — the saved front image always reflects the front step, even when OCR initially swaps front and back labels

### South Africa Database Validation Expansion

South Africa coverage grew from a single national-ID check into a full data-source suite, all callable through the same database validation API.

* **Department of Home Affairs** — fingerprint match and DHA photo lookup
* **Vehicle data** — ownership and lookup by VIN
* **Business data** — company registry, company directors, and person directorships
* **Banking and consumer signals** — bank account holder verification and contactability
* **Fraud and AML** — fraud prevention check, refugee verification, and criminal screening by face
* **Cheaper national ID** — the South African national-ID validation moved to a new integration with significantly lower per-call cost

<Frame>
  <img alt="Didit database validation — expanded data-source coverage for South Africa" />
</Frame>

### Mexico INE Voter-Card Validity

Mexican INE/IFE voter cards can now be validated against the official registry in real time.

* **Document validity** — confirms the credential model (`modelo`), expiration (`vigencia`), and whether it's valid as identification
* **Voting rights** — confirms the holder's right-to-vote status

### AML Screening Optimization

AML screenings are now deduplicated on resubmits when the identity hasn't changed, so you stop getting billed for repeated screenings of the same person.

* **Skip on identical resubmits** — name, date of birth, nationality, and document number all unchanged from the prior screening means no new screening (and no new charge)
* **Unchanged behavior** when the identity actually changes, on the first screening, in sandbox sessions, and on the standalone AML endpoint
* **Applies to KYB too** — company AML screenings dedupe the same way for unchanged business identity on resubmit

### Upload User Face

Faces imported through the **Upload User Face** endpoint now behave like any face captured in a verification session.

* **Visible on the user profile** — the portrait shows up on the Console user-detail page like an organic capture
* **Included in duplicate detection** — imported faces are now part of the 1:N search index, so re-registrations under a different vendor data identifier are correctly flagged
* **Backfill-friendly** — useful when migrating an existing identity database into Didit

### Whitelabel Custom Domain Errors

Custom verification domains no longer silently flip to "Verified" when your DNS provider's CAA records actually block the certificate from being issued.

* **Real error surfaced** — the Console now shows the exact reason (typically a CAA record blocking AWS from issuing the SSL cert)
* **5-step recovery instructions** — the exact DNS records you need to add are listed in the Customization page
* **No more invisible failures** — domains that look verified but don't load are caught before they reach end users

<Frame>
  <img alt="Didit custom domain error diagnostics for white-label verification domains" />
</Frame>

### Redesigned Transactional Emails

All 11 authentication and organization emails were rebuilt to match the Console design system — clean white layout, full-width pill CTA, and a text-forward footer with `hello@didit.me`. White-label customers still get their own logo and theme on the verification email.

### Compound Name Matching

Database validation lookups now correctly handle compound first names across consumer-records services.

* **US** — "Jorge Luis", "Miguel Angel Jr", and similar Spanish double-given-name patterns now match correctly
* **UK** — compound first names like "Lukasz Marcin" are parsed as first + middle instead of being treated as a single token

### New Document Support

* **Tax Card document type** — a new document subtype added across iOS, Android, Flutter, and React Native SDKs for tax-residency verification
* **Netherlands 2025 driver's license** — the new design is supported end-to-end
* **Brazil Digital Driving License** — two-sided captures with "Side C" / "Page B" markers now save the correct front photo and back image
* **Spain Refugee Convention Travel Document** — and similar stateless travel documents using D / DV / TI MRZ prefixes and `XXA` nationality now parse correctly
* **11 newly-supported documents** synced into the production registry from real-world submissions

### Mongolian Language

The verification flow and all four native SDKs now support Mongolian (mn), bringing total language coverage to 54.

### Native SDK Releases

Beyond the 4.0 modular variants, every native SDK shipped a steady stream of stability fixes through May.

* **Android SDK 3.5.3 – 4.0.2** — Document photo quality and face-intro styling, recovery after ambiguous network failures, white-label theme flash fix on completion, camera switching with state reset for both document and liveness, upload guards when video segments are missing, terms and translation updates, front-camera selfie capture fix, back-button and questionnaire polish, Mongolian language, and the 4.0 line with configurable default cameras and switcher visibility
* **iOS SDK 3.3.3 – 4.0.2** — Document capture quality and playable MP4 / H.264 uploads, step recovery after interrupted backend responses, optional no-NFC build, inline podspec license, 3.5 / 3.6 routine releases, a critical fix for an `EXC_BAD_ACCESS` crash on iOS 13–17 introduced by a Swift 6 runtime symbol, Mongolian language, and 4.0 with the modular variant split and Tax Card support
* **React Native SDK 3.2.11 – 4.0.1** — Bumped to the latest native iOS and Android releases each cycle, added `iosNfcEnabled` / `androidNfcEnabled` flags to the Expo config plugin so consumers can pick the no-NFC variant, and shipped 4.0 with the full variant matrix
* **Flutter SDK 3.5.0 – 4.0.2** — Pulled in the latest native iOS and Android releases, added an Android no-NFC build option, exposed the full native configuration surface (`showCloseButton`, `showExitConfirmation`, `closeOnComplete`), and shipped 4.0 with native variant selection and Tax Card support

### Device Intelligence

Server-side device fingerprinting got more accurate and harder to fool.

* **Deterministic anchor required** — fuzzy fingerprint matches now require a hardware-rooted identifier (Android SSAID or Widevine, iOS `identifierForVendor`) before two sessions can be linked, eliminating false-positives
* **TLS / JA4 corroboration** — web fingerprints are now corroborated against TLS fingerprint signals for stronger deterministic match classification

### Improvements

* Stale "image too blurry" warnings no longer attach to approved sessions when the user successfully retook the document on the final allowed attempt
* The face-capture algorithm now uses real bounding-box geometry instead of normalized ranges, with new "move away" and "move closer" instructions and device-specific stability tuning
* Camera permission errors are classified consistently across the verification flow, with clearer messages distinguishing permission timeouts from camera-access failures
* Unverified accounts can no longer permanently squat an email address — re-registration takes over the unverified row instead of being blocked
* Workflow graph and questionnaire-editor fullscreen toggles now work on Safari
* Australian ImmiCard and travel-document fields, New Zealand passport expiration, and structured-address resolution were fixed across roughly 35 address-aware database validation services

### Fixes

* Fixed corrupted `front_image` crop returned by the ID Verification API when front and back were swapped during OCR (Argentina 2019 and 2020 IDs)
* Fixed missing `FILE_UPLOADED` events on resubmitted sessions, which had caused resubmitted documents to show up with no file in the Console
* Fixed translations and white-label customization issues across the verification web flow


# November 2025
Source: https://docs.didit.me/changelog/november-2025

Front-camera desktop, face privacy mode, unilinks, SSO, and data retention up to 10 years across Didit's identity verification platform.

* **Front-Camera on Desktop** — Laptops/desktops now use the front camera by default with better device handling (including iPhone/iOS and Huawei setups)
* **Face Privacy Mode** — For passive liveness, admins can enable a privacy mode with a blurry effect during the check
* **Sharper Video** — Higher quality iPhone recordings, reduced black-screen edge cases, and more reliable WebView redirects
* **Quicker 2FA Steps** — Enter key submits SMS/email codes; phone inputs auto-format (even in countries with multiple calling codes)
* **Unilinks** — Reusable, no-code verification links for any workflow. Share a single permanent link instead of creating sessions via API
* **Age Rules: Min & Max** — Enforce both minimum and maximum age with configurable actions (decline or set to In Review)
* **Bengali Language** — Product now available in Bengali
* **SSO & Authentication** — New sign-in methods, device management, and SSO setup under organization settings
* **Questionnaires Simplified** — Cleaner, faster editor for creating/editing forms (sections, translations, uploads)
* **Manual Checks Upgraded** — Clearer views for Face Match/POA/AML/ID, new risk indicators, better PDF exports
* **Database Validation** — More options, streamlined UI, continued 1×1 and 2×2 match support
* **Data Retention up to 10 Years** — Set longer data-retention windows directly in settings
* **Similarity Tuning** — Optional ethnicity-based thresholds for duplicate face detection
* **Workflow UX Polish** — Session approval controls, clearer status displays, reliable reusable links, accurate whitelabel preview


# October 2025
Source: https://docs.didit.me/changelog/october-2025

Desktop verification, manual checks in the Console, OCR improvements, and admin quality-of-life updates across Didit's identity verification platform.

* **Desktop Verification** — Complete ID + liveness verification on desktop with a polished, responsive UI
* **Smoother Liveness & Face Capture** — Fewer false errors, better handling on older/quirky devices (incl. Huawei models)
* **Faster Uploads on Slow Networks** — Images/PDFs compressed automatically; previews attach when possible
* **Clearer Toasts** — Replaced disruptive alerts with consistent, dismissible messages
* **Better Address Forms** — Smarter suggestions, per-field validation, support for extra address info (apartment, street 2)
* **More Reliable Document Capture** — Fixed image rotation issues and improved front/back capture flows
* **Questionnaires Easier** — Cleaner phone/email inputs, multi-file/image fields, improved multilingual support
* **New Event Tracking** — Improved status updates, reduced "stuck step" situations
* **Admin Console Quality-of-Life** — Richer document previews (incl. PDFs), persistent filters, events timeline grouped by day
* **Manual Checks** — Perform AML/ID/Liveness/POA checks in the Console without user interaction
* **OCR Optimization** — Major accuracy and speed improvements for Japan, Colombia, and Bolivia


# September 2025
Source: https://docs.didit.me/changelog/september-2025

Redesigned Console, email verification, questionnaires, multi-channel phone flow, and session lists at scale across Didit's identity platform.

* **New Console Design** — Redesigned Console with better navigation and more intuitive UX
* **Email & Phone Blocklist** — Backend support for email/phone blocklisting with per-session info and pagination
* **Email Verification** — Now available in workflows and APIs with corresponding frontend screens
* **Questionnaires** — Launched end-to-end for collecting structured attestations and supporting documents via customizable forms
* **White-Label Configuration** — New WL config across flows with more customization flexibility
* **ID/POA Enhancements** — ID flow supports PDF uploads; POA returns document metadata
* **Compliance Links & Policies** — Added Privacy Policy and Terms of Service URLs with data-retention settings
* **Session Lists at Scale** — Heavily optimized queries with normalized search
* **Phone Flow** — Multiple channels (SMS, WhatsApp, Telegram, Discord, Viber); clearer status semantics; better OTP UX
* **Frontend Polish** — New WL theming, improved KYC step list, progress bars, camera overlays, country selection
* **Events & Telemetry** — More precise events, richer device context, targeted debug logs
* **Docs & Media Handling** — PDF to JPG conversion stabilized; better frame-rate handling; more video formats
* **Internationalization** — More translations (incl. Montenegrin and Emirates ID), robust country handling


# September 2026
Source: https://docs.didit.me/changelog/september-2026

ID Verification gets three methods: photograph a document, check a national ID number against an authoritative source, or sign in with a digital ID wallet.

### Three ways to verify an identity

ID Verification is still one configurable feature, with billing determined by the method used, but a document photograph is no longer the only way through it. You now choose, country by country, which methods a person may use.

* **Document capture, unchanged** — every document type, capture rule and threshold you already configure keeps working exactly as before, and a workflow that says nothing about methods stays document capture only
* **Non-document lookup, available now** — the user types their national ID number plus a few personal details and we check them against the authoritative source for that country. No photograph, no upload. That source is a government register in most countries and a credit-bureau, financial-services, utility or residential-records file in some, so [the coverage table](/core-technology/id-verification/non-doc-lookup) names the exact source per country
* **Digital ID wallets, not live yet** — the roadmap is published and configurable in the console as **Coming soon**, but no wallet can be enabled or offered to an end user in production yet. MitID, BankID, itsme, Vipps, iDIN, UAE PASS, gov.br and the EUDI Wallet are on [the wallet page](/core-technology/id-verification/digital-id-wallets); talk to your account team about being in the first cohort
* **Choose per country** — the **Countries** tab on the ID Verification step turns each method on or off for each country, and the same settings are available through the API

### Sources that return a photograph verify the person too

Where a government register returns the person's portrait — South Africa, Nigeria, Argentina and Panama — the lookup also takes a selfie, runs passive liveness on it and matches it to that portrait. All of it is included in the lookup price, and the workflow can skip its own Liveness and Face Match steps afterwards because they would repeat work already done.

### You decide what happens when a method does not land

Every non-document method has a switch for each way it can fail: a partial match, no match, no response from the source, or a wallet sign-in that was cancelled or timed out. Each one either sends the user to document capture or declines the session.

* **Retries are yours to set** — one to five attempts, two by default, and only lookups the source actually answered are counted
* **A typo costs nothing** — a number that fails the format check never reaches the source, so it is neither counted nor billed
* **The console shows the bill before you save** — each switch spells out what that configuration costs

### Every result says how it was verified

Sessions, the decision API and the `status.updated` webhook now carry the method that produced each ID Verification and the assurance tier that goes with it — **Documentary** for a document, **Data match** for a lookup, **Cryptographic** for a wallet. The tiers describe different evidence; they are not a ranking.

* **Registry comparison** — every compared field with what the user provided, what the source held, and whether it matched, plus an error row when a source did not answer
* **Credential details** — the wallet, its issuing authority, the level of assurance it asserted, and whether the signature checked out
* **Existing integrations are untouched** — a document session reports `document` and `documentary` and leaves the new fields empty

### Pricing

Document capture is unchanged: \$0.15 per check with the first 500 checks each month free. Lookup prices are published in the [country and identifier table](/core-technology/id-verification/non-doc-lookup#coverage-and-pricing), in USD per answered attempt. Multi-source attempts sum answered service rates; retries can add charges. Wallet prices remain pending publication and no placeholder rate is quoted.

* A source that answered bills the lookup, whether it matched or not
* A source that never answered is not billed
* An abandoned or failed wallet sign-in is not billed
* A user who falls back to document capture pays for that capture on top

Read more in [ID Verification methods](/core-technology/id-verification/verification-methods), [Non-document lookup](/core-technology/id-verification/non-doc-lookup) and [Digital ID wallets](/core-technology/id-verification/digital-id-wallets).

### Web SDK 0.3.1

`@didit-protocol/sdk-web` 0.3.1 is on npm. Upgrade with `npm install @didit-protocol/sdk-web@latest`; nothing in the API surface changed.

* **The modal no longer clips** — on short desktop and landscape viewports the iframe tracks the visible viewport instead of a fixed 700px, so the last step of a verification is always reachable
* **Embedded mode fills your container** — it uses your host element's content box instead of inheriting the modal's height cap
* **`SDK_VERSION` tells the truth** — it is generated from the package version in every build format and in the TypeScript declaration. Earlier releases reported `0.2.1` no matter what you installed

Read more in the [Web SDK guide](/integration/web-sdks/javascript-sdk).

### Mobile SDK capture reliability

[iOS SDK 4.7.6](/integration/native-sdks/ios-sdk), [Android SDK 4.7.6](/integration/native-sdks/android-sdk), [React Native SDK 4.7.7](/integration/native-sdks/react-native-sdk), and [Flutter SDK 4.7.6](/integration/native-sdks/flutter-sdk) are available.
Both wrappers pin the native SDKs to 4.7.6, including every Flutter variant package.

* **More reliable iOS recording** - completed recordings are accepted when the camera reports success, and face capture waits for every recording segment to finish.
* **Document capture stays locked while saving** - the shutter stays disabled until the captured media has finished processing.
* **Sandbox catalog access** - iOS requests include the session credentials needed to load the catalog.
* **Aligned Android packages** - all six Android artifacts use 4.7.6, with no behavior changes from 4.7.5.

No integration API changes are required.


# Didit V3 Launch
Source: https://docs.didit.me/changelog/v3-launch

Didit V3 launches: unified identity verification platform with pay-per-call pricing, graph workflows, KYB, transaction monitoring, and 220+ countries.

We're thrilled to announce the launch of **Didit v3** — a major leap forward in identity infrastructure!

### What's New in v3

**Workflow & Automation Power-Ups**

* **Graph-Based Workflows** — Create complex, visual workflows to map any identity flow. Centralize, automate, and optimize your operations and compliance
* **Workflow Templates** — Get started faster with pre-built templates in the Console
* **Conditional Questionnaires** — Build sophisticated logic into questionnaires for dynamic user experiences

**Enhanced Verification & Security**

* **Advanced AML** — Define match scores and weight names, DOBs, and countries to precisely determine match percentages
* **Improved UI/UX** — Continuously optimized based on global A/B testing
* **New Database Validations** — Expanded country coverage
* **Age Estimation** — Privacy-preserving age estimation for compliance

### Pricing Updates

*Effective February 15 at 00:00 UTC*

**Free Tier** — 500 free checks per month (resets monthly), each feature counted independently.

| Feature              | Price after free tier |
| -------------------- | --------------------- |
| ID Verification      | \$0.15                |
| Passive Liveness     | \$0.10                |
| Face Match 1:1       | \$0.05                |
| Device & IP Analysis | \$0.03                |

**Price Reductions**

| Feature            | New Price             | Previous Price |
| ------------------ | --------------------- | -------------- |
| Phone Verification | Dynamic carrier rates | —              |
| White Label        | \$0.20                | \$0.30         |
| AML Screening      | \$0.20                | \$0.35         |
| Proof of Address   | \$0.20                | \$0.50         |

No changes to existing enterprise contracts.


# Analytics dashboard
Source: https://docs.didit.me/console/analytics

Track KYC, KYB, and transaction performance: conversion rates, workflow funnels, verification times, geography, top rules, analyst performance, and more.

This Didit Academy lesson shows where analytics live in the console, then covers date filters, the geography and channel splits, the audit log, applications and environments, and the five built-in roles.

<VideoEmbed title="Analytics, teams and roles — Didit Academy" />

The analytics dashboard gives you a shared view of KYC, KYB, and transaction activity directly inside the Business Console. You can keep the default widget set, or customize the home dashboard by adding, removing, and reordering widgets for the whole application.

Volume widgets compare the selected date range against the immediately previous period. On the transactions overview, the approved, rejected, and in-review trend chart also overlays the previous period so you can spot changes in decision mix at a glance.

## Key Metrics

| Category           | Metrics                                                                                                                                                                                                                                                                                                                 |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **KYC**            | Verification volume, workflow funnels, average active verification time, conversion by country, resubmission insights, automatic verdict breakdown (how many completed sessions the system originally classified as approved, in review, or declined before any manual override), demographics, and device distribution |
| **KYB**            | KYB request volume, average processing time, business-country distribution, IP distribution, automatic verdict breakdown (how many completed business sessions originally landed in approved, in review, or declined), and device context for business sessions                                                         |
| **Transactions**   | Transaction count and volume, average amount, category and action-type breakdowns, approved vs. rejected vs. flagged trends, user geography, top rules triggered, analyst performance, and score histograms                                                                                                             |
| **Home dashboard** | A shared per-application layout that can mix KYC, KYB, and transaction widgets in a single customizable view                                                                                                                                                                                                            |

## Home dashboard customization

The **Dashboard** page is now customizable per application:

* Click **Add widgets** to browse all supported KYC, KYB, and transaction analytics.
* Remove widgets you do not need from the selected list.
* Drag widgets to reorder the layout.
* Save the layout once and every teammate looking at the same application sees the same home dashboard configuration.

## Overview pages

The console overview pages use the same analytics system:

* **Dashboard**: mixed home dashboard with your saved widget layout.
* **KYB overview**: KYB-focused widgets using the same date-range filters and visual system.
* **Transactions overview**: transaction-specific analytics including rule, geography, analyst, and score widgets.

## Filtering

The dashboard supports scope-aware filtering:

* **Workflow**: Filter analytics by a specific workflow. Defaults to the latest published workflow.
* **Version**: Filter by a specific published version of the selected workflow.
* **Branch Path**: For workflows with conditional branching, filter by a specific path through the workflow. Each path is labeled with its conditions and features.
* **Time Range**: Last 7 days, 30 days, 90 days, 12 months, or a custom date range.
* **Transaction tag**: Filter the transactions overview by a single application tag.
* **Transaction type**: Filter the transactions overview by finance or travel-rule flows.
* **Action type**: Filter the transactions overview by the customer-defined action type, such as `deposit`, `withdrawal`, or channel-specific actions.

## Active Verification Time

The average verification time metric tracks only the time users are actively engaged in the verification flow. If a user starts a step, leaves, and returns later to continue, the gap is **not** counted. This gives you an accurate picture of the actual user experience duration.


# Audit logs
Source: https://docs.didit.me/console/audit-logs

Track all API activity with searchable audit logs. Filter by user, method, status, and date range for compliance audits, security review, and debugging.

Audit Logs provide a comprehensive, searchable record of all API activity within your organization. Every request made to the Didit platform — whether from the Console, your integration, or team members — is automatically logged for security, compliance, and troubleshooting.

<Frame>
  <img alt="Audit logs in the Didit console" />
</Frame>

***

## Why audit logs?

| Challenge                          | Solution                                    |
| ---------------------------------- | ------------------------------------------- |
| Regulatory compliance requirements | Complete 1-year audit trail of all activity |
| Security incident investigation    | Trace exactly who did what and when         |
| Debugging integration issues       | See the exact requests and responses        |
| Team accountability                | Track which team members accessed what data |
| Usage monitoring                   | Understand API consumption patterns         |

***

## Accessing audit logs

Navigate to **Audit Logs** in your Didit Console sidebar. The interface displays a chronological list of all API requests made within your organization.

Each log entry includes:

| Field           | Description                                                                                           |
| --------------- | ----------------------------------------------------------------------------------------------------- |
| **Timestamp**   | When the request was made                                                                             |
| **User**        | Email of the authenticated user (empty for API key requests, which are attributed to the application) |
| **Method**      | HTTP method (GET, POST, PUT, DELETE)                                                                  |
| **Path**        | The API endpoint that was called                                                                      |
| **Status**      | HTTP response status code                                                                             |
| **IP Address**  | Origin IP of the request                                                                              |
| **Application** | Which application the request was associated with                                                     |

***

## Filtering and search

The Audit Logs interface provides powerful filtering capabilities to help you find exactly what you're looking for.

### Smart search

The search bar automatically detects what you're looking for:

| Search type      | Example                          | Behavior                                |
| ---------------- | -------------------------------- | --------------------------------------- |
| **Exact path**   | `/v1/organization/.../sessions/` | Finds logs with this exact request path |
| **Exact email**  | `admin@company.com`              | Finds logs from this specific user      |
| **Exact IP**     | `192.168.1.100`                  | Finds logs from this IP address         |
| **Wildcard**     | `/v1/*/analytics/*`              | Matches patterns with wildcards         |
| **General text** | `sessions`                       | Fuzzy search across all fields          |

### Available filters

| Filter          | Description                    | Example                        |
| --------------- | ------------------------------ | ------------------------------ |
| **Application** | Filter by specific application | Select from dropdown           |
| **Method**      | Filter by HTTP method          | `GET`, `POST`, `PUT`, `DELETE` |
| **Status Code** | Filter by response status      | `200`, `401`, `500`            |
| **Date Range**  | Filter by time period          | Last 7 days, custom range      |

***

## Data retention

Audit logs are retained for **1 year (365 days)** to meet common compliance requirements:

| Timeframe         | Availability          |
| ----------------- | --------------------- |
| Last 24 hours     | Available             |
| Last 7 days       | Available             |
| Last 30 days      | Available             |
| Last 90 days      | Available             |
| Last 365 days     | Available             |
| Older than 1 year | Automatically deleted |

<Note>
  For extended retention requirements, contact our support team to discuss enterprise options.
</Note>

***

## Security and privacy

### What's logged

Audit logs capture metadata about API requests:

* Request timestamp and duration
* User identity (email, user ID)
* Request path and query parameters
* Response status codes
* Client IP address and user agent

### What's NOT logged

To protect sensitive data, the following are automatically excluded:

* Request/response bodies
* Authentication tokens and credentials
* Passwords and secrets
* Personal data from verification sessions

### Access control

Audit log access is restricted to users with **Admin** or **Owner** roles in your organization. Regular team members cannot view audit logs unless explicitly granted elevated permissions.

***

## Common use cases

<AccordionGroup>
  <Accordion title="Compliance auditing">
    Demonstrate to auditors that you have complete visibility into who accessed verification data:

    1. Filter by date range matching the audit period
    2. Filter by specific applications or users if needed
    3. Export or screenshot the results for documentation
  </Accordion>

  <Accordion title="Security investigation">
    If you suspect unauthorized access:

    1. Search for the affected user's email or suspicious IP addresses
    2. Filter by date range around the suspected incident
    3. Look for unusual patterns: failed authentication attempts, unexpected endpoints, odd hours
  </Accordion>

  <Accordion title="Integration debugging">
    When troubleshooting API integration issues:

    1. Search for the specific endpoint path
    2. Filter by `4xx` or `5xx` status codes to find errors
    3. Note the timestamps to correlate with your application logs
  </Accordion>

  <Accordion title="Team activity review">
    Monitor how your team uses the platform:

    1. Filter by specific team member emails
    2. Review which sessions and features they accessed
    3. Ensure team members are following proper procedures
  </Accordion>
</AccordionGroup>

***

## Best practices

1. **Regular reviews** — periodically review audit logs to catch anomalies early.
2. **Narrow your search** — use specific filters to reduce noise and find relevant entries faster.
3. **Date ranges** — always specify a date range for better performance on large datasets.
4. **Bookmark searches** — save common filter combinations as browser bookmarks for quick access.


# Blocklist users
Source: https://docs.didit.me/console/blocklist-users

Auto-decline fraudulent verifications by blocklisting documents, faces, phone numbers, and emails. Stop identity fraud, multi-accounting, and repeat offenders.

The blocklist feature automatically declines verification sessions that match previously identified documents, faces, phone numbers, or emails that should be rejected. This helps prevent fraud and ensures the integrity of your verification process.

<Frame>
  <img alt="Blocklist dialog in the Didit console" />
</Frame>

***

## Overview

The blocklist operates on four entity types:

<CardGroup>
  <Card title="Document blocklist" icon="id-card">
    Prevents reuse of specific documents identified as fraudulent, stolen, or otherwise problematic.
  </Card>

  <Card title="Face blocklist" icon="face-viewfinder">
    Prevents users whose biometric data matches previously blocklisted faces from passing verification.
  </Card>

  <Card title="Phone number blocklist" icon="phone">
    Prevents verifications using phone numbers that have been blocklisted.
  </Card>

  <Card title="Email blocklist" icon="envelope">
    Prevents verifications using email addresses that have been blocklisted.
  </Card>
</CardGroup>

<Note>
  When a blocklisted entity is detected during verification, the session is automatically declined with the corresponding warning: `ID_DOCUMENT_IN_BLOCKLIST`, `FACE_IN_BLOCKLIST`, `PHONE_NUMBER_IN_BLOCKLIST`, `EMAIL_IN_BLOCKLIST`, `IP_ADDRESS_IN_BLOCKLIST`, or `DEVICE_FINGERPRINT_IN_BLOCKLIST`.
</Note>

***

## How blocklisting works

### Document blocklisting

When a document is added to the blocklist, the system stores secure fingerprints of the document's unique identifiers (document number, MRZ data, etc.). During future verification sessions, if a document matches these fingerprints, the session is automatically declined.

Useful for:

* Preventing reuse of known fraudulent documents
* Blocking documents reported as stolen
* Preventing multiple accounts using the same document

### Face blocklisting

When a face is added to the blocklist, the system stores biometric templates derived from facial features. These templates are compared against faces in new verification sessions.

Useful for:

* Preventing users who have attempted fraud from creating new accounts
* Enforcing platform bans across new registration attempts
* Implementing regulatory exclusion requirements

### Phone number blocklisting

When a phone number is added to the blocklist, the system evaluates new verification sessions against the blocklisted numbers (including normalized E.164 formats).

Useful for:

* Blocking numbers associated with repeat abuse or policy violations
* Preventing re-registration attempts using the same phone number
* Enforcing regional compliance requirements

### Email blocklisting

When an email address is added to the blocklist, the system checks new verification sessions against blocklisted addresses (case-insensitive, normalized).

Useful for:

* Preventing repeat fraud or spam attempts from the same email address
* Enforcing bans across multiple accounts tied to the same email
* Meeting compliance requirements for account creation

***

## Transaction blocklists

In addition to verification blocklists, the following entity types are checked during **transaction monitoring**. If any match is found, the transaction is **immediately declined** before rules are evaluated:

| Blocklist                        | Entity checked                                                        |
| -------------------------------- | --------------------------------------------------------------------- |
| **Wallet Address Blocklist**     | The `account_id` of crypto wallet payment methods                     |
| **Bank Account Blocklist**       | The `account_id` of bank transfer payment methods                     |
| **IP Address Blocklist**         | IP address from the transaction party's device (supports CIDR ranges) |
| **Device Fingerprint Blocklist** | Device fingerprint from the transaction party                         |
| **User Blocklist**               | The applicant's `vendor_data` identifier                              |
| **Business Blocklist**           | The business's `vendor_data` identifier                               |

<Note>
  Transaction blocklist checks are separate from verification blocklist checks. Both use the same underlying lists, so an entity blocklisted for verification is also blocklisted for transactions.
</Note>

***

## Managing the blocklist

Items can be added to the blocklist through:

* **The Didit Console** — navigate to the blocklist section and add items manually.
* **The Lists API** — programmatically manage blocklist entries. See the [Lists API reference](/management-api/lists/overview).

<Info>
  For API-based blocklist management, see the [Create entry](/management-api/lists/create-entry), [Delete entry](/management-api/lists/delete-entry), and [List entries](/management-api/lists/list-entries) endpoints.
</Info>


# Overview & Analytics
Source: https://docs.didit.me/console/case-management/analytics

Track workload and outcomes across your case queue: an officer and manager overview dashboard, plus per-officer, per-blueprint, and per-source analytics.

Two pills give you visibility into the case queue: **Overview** for day-to-day workload, and **Analytics** for trends and outcomes over a date range.

***

## Overview dashboard

The Overview pill adapts to the viewer:

* **Officer view**: cases needing resolution, cases awaiting user, and open/resolved counts by blueprint, plus FIU report tracking for reports the officer created.
* **Manager view**: SLA breach risk (cases with the least time remaining before their due date), unassigned high-priority cases, team availability from console presence, and top officers by throughput.

## Analytics pill

Pick a date range (defaults to the last 30 days, up to 731 days) to see:

* A **created vs. reviewed** chart, cases opened and cases resolved per day across the range.
* Four tables, **Officer**, **Blueprint**, **Creation source**, and **Total**, each with the same metrics:

| Metric                | Description                                        |
| --------------------- | -------------------------------------------------- |
| `created`             | Cases created in range                             |
| `assigned`            | Assignment events in range                         |
| `resolved`            | Cases resolved in range                            |
| `threat_rate`         | Share of resolved cases marked Valid threat        |
| `false_positive_rate` | Share of resolved cases marked False positive      |
| `unresolved`          | Cases created in range still Open or Awaiting user |
| `reassignment_rate`   | Share of created cases assigned more than once     |
| `escalation_rate`     | Share of created cases escalated at least once     |
| `avg_assign_hours`    | Average time from creation to first assignment     |
| `avg_resolve_hours`   | Average time from creation to resolution           |
| `avg_handling_hours`  | Average time from assignment to resolution         |

A live **queue** count (open cases, and overdue cases) sits alongside the range-scoped metrics so you always see today's backlog regardless of the selected date range.

Export any table as CSV from the same controls used elsewhere in the console.

<Tip>
  Cross-check one officer's row against their case list (filter by Assignee) the first time you rely on these numbers for a review, it is the fastest way to confirm the date range and filters mean what you expect.
</Tip>


# Blueprints
Source: https://docs.didit.me/console/case-management/blueprints

Configure how a category of cases is assigned, escalated, transferred, and displayed, and install the four built-in presets.

A blueprint defines how one category of case is handled: who it is assigned to, how it routes, and what shows up on its case page. Every case belongs to exactly one blueprint.

***

## General settings

| Setting                     | Description                                                                            |
| --------------------------- | -------------------------------------------------------------------------------------- |
| **Name**                    | Up to 24 characters                                                                    |
| **Description**             | Optional, free text                                                                    |
| **Who handles cases**       | Assignee pool, required, at least one member ("Pick at least one assignee")            |
| **Assignment**              | **Manually**, or **Automatically**                                                     |
| **Case transfer**           | Toggle; when on, cases can move to another active blueprint of the same application    |
| **Escalation**              | Toggle plus a target blueprint select                                                  |
| **4-eyes review**           | Pair with a checker blueprint, see [4-eyes review](/console/case-management/four-eyes) |
| **Require resolution note** | Toggle; when on, the Resolve dialog's note becomes mandatory                           |

### Automatic assignment

Automatic mode reveals "Assign to users with fewer than **N** cases of the current blueprint assigned to them". Only officers currently online in the console are considered. When the whole assignee pool is at or over the threshold, new cases queue unassigned and are pulled automatically as soon as an officer resolves a case or comes online.

### Escalation and transfer

Escalation moves a case to a fixed target blueprint (its queue, its content configuration) in one action. Case transfer instead lets an officer pick any active blueprint of the same application to move a case to. Both are hidden from the case page unless the current blueprint enables them, and both are blocked server-side (400) if attempted while disabled.

A blueprint cannot reference itself as its own escalation target or 4-eyes checker.

### Connected sources

A blueprint's right rail lists:

* **Case creation sources**: AML configs, transaction rules, and workflow nodes currently routing new cases into it, with shortcuts to each one.
* **Receives escalation from**: other blueprints whose escalation target points here.

## Presets

Install any of the four built-in presets from the **Blueprints** pill's presets gallery. Installing copies the preset into your application as a fully editable blueprint, you can then change any setting freely without affecting the catalogue. Installing is idempotent per preset, so re-installing an already-installed preset is a no-op.

| Preset                  | Case content                                                                                                |
| ----------------------- | ----------------------------------------------------------------------------------------------------------- |
| **Screening hit**       | AML control (financial + identity), identity (personal information, risk overview)                          |
| **AML investigation**   | AML control (financial), identity (personal information, contact information, risk overview, PoI documents) |
| **Suspicious activity** | Identity (personal information, risk overview, PoI documents), financial (payment methods, transactions)    |
| **KYC review**          | Identity (all fields), verification summary                                                                 |

None of the presets pre-configure assignment, escalation, 4-eyes, or transfer, those routing decisions are always yours to make per blueprint.

## Case content

The **Case content** tab controls which tabs and fields appear on the case page, as six togglable sections:

| Section                        | Fields                                                                                                                            |
| ------------------------------ | --------------------------------------------------------------------------------------------------------------------------------- |
| **Checklist**                  | Enable, make optional for resolution, and the checklist item list, see [Checklist](/console/case-management/checklist)            |
| **AML control**                | Financial AML information, identity AML information                                                                               |
| **Identity**                   | Personal information, applicant tags, contact information, risk overview, proof of identity documents, proof of address documents |
| **Verifications**              | Verification summary                                                                                                              |
| **Reporting**                  | FIU reports                                                                                                                       |
| **Financial data and sources** | Payment methods, financial transactions                                                                                           |

A blueprint with no sections enabled still shows the case Overview tab, just without the extra content blocks.

<Tip>
  There is deliberately no priority, severity, case type, or default-due-hours setting on the blueprint. Priority and due date are set per case (by whatever created it, or edited from the case page), keeping the blueprint focused on routing and content.
</Tip>

## Deleting a blueprint

Deleting a blueprint always succeeds and does not touch its cases: existing cases keep their blueprint reference, and its settings (content sections, escalation, transfer, 4-eyes pairing) continue to apply to them. A deleted blueprint no longer appears in blueprint lists and can no longer be chosen as a transfer target. If a maker blueprint is deleted while one of its resolutions is pending 4-eyes approval, a rejected resolution leaves the case on the checker blueprint instead of returning it.

To wind a blueprint down cleanly, transfer its active cases to another blueprint before deleting it.


# Cases
Source: https://docs.didit.me/console/case-management/cases

Open, work, and resolve investigation cases anchored to a single user or business, with saved views, SLA due dates, and bulk actions.

Case Management is the investigation hub of the Didit Console. Every AML hit, flagged verification, or suspicious transaction can become a **case** your compliance team works from open to resolution, with a full audit trail.

***

## Lifecycle

A case moves through exactly three statuses:

| Status          | Meaning                                                           |
| --------------- | ----------------------------------------------------------------- |
| `Open`          | Under active investigation                                        |
| `Awaiting user` | Paused while more information is collected from the verified user |
| `Resolved`      | Investigation complete, with a resolution recorded                |

Resolving a case requires a resolution:

| Resolution       | Meaning                                     |
| ---------------- | ------------------------------------------- |
| `False positive` | The activity was legitimate                 |
| `Valid threat`   | Confirmed suspicious or fraudulent activity |

Every case also carries a **priority** (`Low`, `Medium`, `High`, default `Medium`) and an optional **due date** that drives SLA sorting and overdue flags.

<Note>
  There is no `Under review`, `On hold`, `Pending approval`, `Critical` severity, or case type axis. The lifecycle is deliberately fixed to keep analytics, SLAs, and permissions unambiguous across every case, regardless of how it was created.
</Note>

## One subject per case

Every case is anchored to **exactly one** user or one business. You cannot mix subjects on a single case, and you cannot attach a session, business session, or transaction that belongs to a different subject than the case, doing so returns a clear error.

This keeps every case page focused: the subject card, risk overview, documents, and financial data all describe the same person or business the case investigates. To review a second entity, open (or create) a separate case.

## Lists

Case Management has status tabs: **Open**, **Awaiting user**, **Resolved**, and **All**.

Search matches subject name or ID, tag, case number, case title, linked session ID, and linked transaction ID, so you can paste in a session or transaction UUID and land directly on its case.

Filter chips: **Blueprint**, **Created**, **Source**, **Assignee**, **Tag**, plus **Add filter** for **Priority** and **Due**.

Columns: Created (date and creator), Case details (title), Status, Blueprint, Subject (name and ID), Subject tags, Assignee, Priority, and Due date, with more available behind horizontal scroll and column configuration.

### Sort and SLA

Sort by **Created at** (default) or **Due date**. Sorting by due date surfaces overdue cases first; a case is overdue once its due date has passed while it is still Open or Awaiting user, shown with a red due chip.

### Saved views

Save the current combination of filters and columns as a named view with **Save view**, switch between views with **Select a view**, and reset with **Clear filters**. Views are personal and persist the same way other console table preferences do.

### Bulk actions

Select multiple cases to:

* **Assign to** an officer. All selected cases must share the same blueprint, the console warns before submitting if they do not.
* **Set status** to Awaiting user, Reopen, or Resolve (with a resolution and optional note). Each case is evaluated independently, so a case blocked by an incomplete checklist or a missing required note is reported individually without failing the rest of the batch.

### Exports

The list menu offers two CSV exports, delivered through the [Reports page](/console/export-pdf-csv):

* **All cases report**, one row per case with status, resolution, priority, tags, linked transactions, and the last FIU report filed.
* **SLA report**, per-case timing metrics: hours to assignment, hours to resolution, overdue, and SLA-met flags.

## Tags

Add tags to a case from its header (**Add tag**) to group related investigations, or filter and search by tag from the list. Tag changes are recorded on the case timeline.

## Related pages

<CardGroup>
  <Card title="Creating cases" icon="square-plus" href="/console/case-management/creating-cases">
    Every entry point: users, businesses, sessions, transactions, and automatic connectors.
  </Card>

  <Card title="Blueprints" icon="sliders" href="/console/case-management/blueprints">
    Configure assignment, escalation, transfer, and the case page content.
  </Card>

  <Card title="Checklist" icon="list-check" href="/console/case-management/checklist">
    Gate resolution on required investigation steps.
  </Card>

  <Card title="4-eyes review" icon="user-check" href="/console/case-management/four-eyes">
    Maker/checker approval for sensitive resolutions.
  </Card>
</CardGroup>


# Checklist
Source: https://docs.didit.me/console/case-management/checklist

Gate case resolution on a required list of investigation steps, configured per blueprint and tracked per case.

The checklist is a short, auto-numbered list of steps an officer must work through before a case can be resolved.

***

## Configuring a checklist

On a blueprint's **Case content** tab, enable **Checklist** and add items with **+ Add field**. Items are auto-numbered and can be reordered by drag and drop. Didit recommends 5-7 items, enough to standardize an investigation without turning it into busywork.

Toggle **Make checklist optional for case resolution** to let officers resolve a case with incomplete items. Leave it off to make every item mandatory.

Every new case created on the blueprint copies the current checklist items at creation time, later edits to the blueprint's checklist do not retroactively change checklists already running on existing cases.

## Working the checklist

The case page's persistent right rail shows the checklist as "**n / m completed**". Officers check items off as they complete each step; every completion is logged on the case timeline.

## Resolution gating

Attempting to resolve a case with incomplete, non-optional checklist items is blocked with a 400 listing the incomplete item labels, and the Resolve dialog surfaces them inline so the officer knows exactly what is left. Once the blueprint marks the checklist optional, resolution proceeds regardless of checklist state.

<Note>
  The optional flag lives on the blueprint, not per item. Earlier per-item mandatory flags have been replaced by this single blueprint-level toggle, keeping the gating rule unambiguous.
</Note>


# Creating Cases
Source: https://docs.didit.me/console/case-management/creating-cases

Open a case from a user, business, verification session, or transaction, manually or automatically through AML screening, transaction rules, and the workflow builder.

A case can be opened from any of the entities you already work with, or created automatically as your rules and workflows run.

***

## Manual creation

The same **Create case** dialog appears from every entry point:

* **Case title**, prefilled as `Manual - <subject name>`
* **Case blueprint** (required), with a **Manage blueprints** link if you need to set one up first
* **Assign to** (optional), with the current user shown first as `<your name> (Assign to me)`

Entry points:

* A user's detail page (overflow menu, and the user's **Cases** tab with **+ Create case**)
* A business's detail page (overflow menu, and the business's **Cases** tab)
* A KYC session's detail page (overflow menu)
* A KYB session's detail page (overflow menu)

Creating from any of these anchors the new case to that user or business automatically, satisfying the [one-subject-per-case](/console/case-management/cases#one-subject-per-case) rule without any extra steps.

## From a transaction

From a transaction's row menu, **Add to case** either:

* Attaches the transaction to one of the subject's existing open cases, or
* Creates a new case anchored to the transaction's subject and attaches the transaction to it.

Attaching a transaction that belongs to a different subject than the case is rejected, the console shows "belongs to a different profile" and the API returns a 400.

## Automatic creation

Three connectors open cases without an officer in the loop, each recorded with a distinct **source**:

| Source             | Trigger                                                                     | Configured in                           |
| ------------------ | --------------------------------------------------------------------------- | --------------------------------------- |
| `AML screening`    | An ongoing-monitoring AML hit, when the toggle is enabled on the AML config | AML settings, per verification workflow |
| `Transaction rule` | A transaction rule match with the **Create case** effect                    | The rule's effect configuration         |
| `Workflow builder` | A session completing a **Create case** node                                 | The workflow graph                      |

### AML screening

Enable **Create cases from ongoing monitoring hits** on a workflow's AML configuration and pick a blueprint. A second hit against a subject that already has an open case attaches to that case instead of opening a duplicate.

### Transaction rules

Add the **Create case** effect to a [transaction rule](/console/transaction-monitoring) with:

* **Blueprint** to route the case to
* **Grouping**: **By applicant** (reuses the subject's open case across every rule) or **By rule and applicant** (opens one case per rule per applicant)
* **Attach matched transaction**, to link the triggering transaction automatically

### Workflow builder

Add a **Create case** action node to a workflow graph, configured with a blueprint, priority, and due date. When a session reaches that node, a case opens with source `Workflow builder` and the session's user as its subject.

### Where connectors are visible

A blueprint's detail view lists every connector currently routing cases into it (**Connected sources**) and any blueprints that escalate into it (**Receives escalation from**), with shortcuts to the AML config, rule editor, or workflow builder that owns each connection.

## Manual vs. automatic sources

Manually created cases always carry source `Manual`. This distinction feeds the [analytics](/console/case-management/analytics) Creation source table, so you can see at a glance how much of your caseload originates from each channel.


# FIU Reports & Templates
Source: https://docs.didit.me/console/case-management/fiu-reports

Generate SAR, STR, CTR, and other FIU regulatory filings from a case or from the standalone Reports page, using reusable per-jurisdiction templates.

When an investigation concludes that activity must be reported to your Financial Intelligence Unit, generate the filing directly from case data, or from the standalone Reports page.

***

## Report types

| Code  | Report                              |
| ----- | ----------------------------------- |
| `SAR` | Suspicious Activity Report          |
| `STR` | Suspicious Transaction Report       |
| `CTR` | Cash Transaction Report             |
| `TTR` | Threshold Transaction Report        |
| `UTR` | Unusual Transaction Report          |
| `IFT` | International Funds Transfer Report |
| `CBR` | Cross-Border Report                 |
| `TFR` | Terrorism Financing Report          |

Every report renders in two formats: **goAML XML**, the UN-standard schema your FIU portal accepts, and a **PDF** for internal records and 4-eyes review.

## Report templates

A report template captures the parts of a goAML header that stay constant across your filings for a given jurisdiction and report type, so you are not re-entering them on every report:

* **Reporting entity ID** (`rentity_id`) and branch, the identifier your organization received from the FIU
* **Submission code** (electronic or manual)
* **Local currency code**
* Which optional blocks to include (reporting person, location, reason, action) via `enabled_fields`

Build templates from the Reports pill's **Templates** tab, one per jurisdiction and report type. A template is only usable once it passes validation, missing obligatory goAML fields are listed and block both saving an invalid template and creating a report from it.

## Creating a report

### From a case

1. Open the case and go to its **FIU reports** tab, shown when the blueprint's Reporting section is enabled.
2. Click **Create report**, pick a template (or leave it blank and fill fields manually), and optionally choose which of the case's linked transactions to include.
3. Didit auto-populates the draft: reporting entity details from the template, the case's subject, linked transactions, and a structured narrative.
4. Review the draft, then **Validate** to check obligatory goAML fields before finalizing.
5. **Finalize**. The goAML XML and PDF are generated, uploaded, and appear on the case's report list with download links for both files.

### From the standalone Reports page

The **Reports** pill also has a **Create report** button that works app-wide: pick a **case** and a **template**, both required, then follow the same validate and finalize flow. Use this when you are working from a queue of pending filings rather than from inside a specific case.

## Report lifecycle

| Status      | Meaning                                                                         |
| ----------- | ------------------------------------------------------------------------------- |
| `Draft`     | Editable, not yet validated                                                     |
| `Validated` | Passed obligatory-field validation                                              |
| `Finalized` | XML and PDF generated and stored; the report can no longer be edited or deleted |

### SAR narrative

SAR, STR, and TFR reports include a narrative structured around the five Ws: **who** is conducting the activity, **what** instruments are involved, **when** and **where** it took place, **why** it is suspicious, and **how** it occurred. Didit drafts each section from case data; edit any section before finalizing.

### Alert lifecycle

Finalizing a SAR, STR, or TFR automatically moves the case's transaction alerts from **Pending SAR** to **SAR filed**, keeping your alert queue in sync with your filings.

## Print case (separate from FIU reports)

**Print case**, in the case page's overflow menu, produces a full-case PDF independent of any FIU filing: case summary, subject, checklist state, notes, attached sessions and transactions, the event timeline, and the list of FIU reports on the case. Use it for internal audits or handoffs that need the whole investigation in one document, not a regulator-facing filing.

## Case exports

From the Cases list, queue two CSV reports (delivered through the [Reports page](/console/export-pdf-csv)):

* **All cases report**, status, resolution, priority, linked transactions, and the last FIU report filed per case.
* **SLA report**, per-case timing metrics.

## Related pages

<CardGroup>
  <Card title="Cases" icon="folder-open" href="/console/case-management/cases">
    Lifecycle, lists, and bulk actions.
  </Card>

  <Card title="Analytics" icon="chart-line" href="/console/case-management/analytics">
    Overview dashboard and case analytics.
  </Card>
</CardGroup>


# 4-Eyes Review
Source: https://docs.didit.me/console/case-management/four-eyes

Require a second officer to approve or reject every resolution on a blueprint, with the proposed outcome staged until a different reviewer signs off.

4-eyes review adds a second, independent sign-off before a resolution takes effect, a standard segregation-of-duties control for higher-risk investigations.

***

## Setting it up

On the maker blueprint, set **4-eyes review** to a **checker blueprint**. Setting this field is what turns 4-eyes on for the maker blueprint, there is no separate toggle.

## How it works

1. An officer on the maker blueprint resolves a case as usual (false positive or valid threat, plus a note if required).
2. Instead of closing, the case status stays **Open**, the proposed resolution is staged, and the case moves into the **checker blueprint's** queue. The case timeline logs `Submitted for approval`.
3. A checker reviews the case's Overview tab, where a dual-control banner shows **Approve** and **Reject** actions.
4. **Approve** applies the staged resolution: the case becomes **Resolved** with the original resolution and note, credited to the officer who submitted it. The timeline logs `Approval granted` then `Resolved`.
5. **Reject** clears the staged resolution and returns the case to the **maker blueprint**. The timeline logs `Approval rejected`, and the maker is notified.

<Warning>
  The officer who submitted the resolution cannot approve or reject it themselves, enforced server-side. Attempting to do so returns a 403. (Approving or rejecting a case with no resolution pending approval returns a 409.)
</Warning>

## Notes

* The checker blueprint's own assignment, escalation, and content settings apply while a case is in its queue, it is a real blueprint, not a special mode.
* A case can only have one resolution staged at a time; requesting more information (**Awaiting user**) is blocked while a resolution is pending approval.
* 4-eyes pairs with [required resolution notes](/console/case-management/blueprints#general-settings): turn both on for your highest-risk blueprints to require both a documented rationale and a second reviewer.


# Custom domain
Source: https://docs.didit.me/console/custom-domain

Serve the verification flow from your own subdomain instead of verify.didit.me. Add the domain, create two DNS records, and verify ownership.

Serve the verification flow from your own subdomain — `verify.yourbrand.com` instead of `verify.didit.me`. Users stay on your domain for the whole journey, which removes the last visible reference to Didit in a [white-label](/console/white-label) flow.

<Note>
  Custom domain is part of White Label and must be enabled on your account. You also need **write access to Customization** — members with read-only access see the section disabled.
</Note>

***

## Requirements

| Requirement            | Detail                                                                                                    |
| ---------------------- | --------------------------------------------------------------------------------------------------------- |
| **Subdomain only**     | Use `verify.yourbrand.com`. Root domains such as `yourbrand.com` are rejected, and so is a `www.` prefix. |
| **Not already in use** | The subdomain cannot point to an existing website or application of yours.                                |
| **DNS access**         | You need to create two records at your DNS provider.                                                      |

***

## How it works

You enter your subdomain in the Business Console. Didit then generates two DNS records for you to add at your provider:

| Record                 | Purpose                                                      |
| ---------------------- | ------------------------------------------------------------ |
| **Verification CNAME** | Proves you own the domain, which issues the SSL certificate. |
| **CloudFront CNAME**   | Points your subdomain at the verification UI.                |

Both records are required. Once they resolve, you verify ownership from the console and the flow starts serving from your domain.

***

## Set up your domain

<Steps>
  <Step title="Add the domain">
    Go to **Business Console → White Label → Domain**, enter your subdomain (for example `verify.yourbrand.com`), and click **Add Domain**.

    The console generates your DNS records. This takes a few seconds.
  </Step>

  <Step title="Copy the two records">
    The console shows a card for each record — **Verification CNAME** and **CloudFront CNAME**. Each card gives you two values:

    | Card field   | Where it goes at your DNS provider |
    | ------------ | ---------------------------------- |
    | **Hostname** | The record **name** (host)         |
    | **Data/URL** | The record **value** (target)      |

    <Warning>
      Don't swap **Hostname** and **Data/URL** when you paste them into your DNS provider, and use the copy button for each value. The verification values are long and easy to mistype.
    </Warning>
  </Step>

  <Step title="Add both records at your DNS provider">
    Create both records as `CNAME`. Adding only the CloudFront record is the most common reason verification fails later.

    Set the TTL to `300` so any correction you make afterwards propagates in minutes instead of hours.
  </Step>

  <Step title="Verify ownership">
    Back in the console, click **Verify domain**. On success the panel changes to **Domain verified** and the button disappears.

    If it fails, the console shows a **Verification failed** box with the specific reason. Read it before you change anything — it names the record that is missing or incorrect.
  </Step>
</Steps>

<Note>
  DNS usually propagates within minutes, but it can take up to **24–48 hours**. If the console reports **DNS changes detected**, your records are correct and propagation is still finishing — no action needed.
</Note>

***

## Change or remove your domain

To move the flow to a different subdomain, enter the new one and click **Update Domain**. Didit issues a new pair of records, so you have to add those at your DNS provider and verify again.

To go back to `verify.didit.me`, clear the field and click **Remove Domain**.

<Note>
  While a custom domain is configured, you cannot re-enable the Didit login screen. Remove the domain first.
</Note>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="500 error, or a message about another CloudFront distribution">
    Your subdomain has an `A` record conflicting with the CNAME — a host cannot have both. Delete the `A` record and keep only the CNAME.

    If there is no `A` record, the CloudFront CNAME points at the wrong target. Match it character for character against the **Data/URL** value in the console.
  </Accordion>

  <Accordion title="Verification never succeeds">
    Check that **both** records exist at your provider. Adding only the CloudFront record is the most common cause, because the flow appears to load while the certificate never issues.

    The **Verification failed** box in the console names the record that is missing or wrong.
  </Accordion>

  <Accordion title="The certificate never issues (Cloudflare)">
    Set both records to **DNS only** — the grey cloud, proxy off. The orange-cloud proxy intercepts the request and breaks certificate issuance.

    Providers without a proxy toggle, such as cPanel, are not affected.
  </Accordion>

  <Accordion title="The record name gets duplicated">
    Some providers append your zone automatically, turning `verify.yourbrand.com` into `verify.yourbrand.com.yourbrand.com`.

    On those providers, enter the **relative** name rather than the full one the console shows — `verify` instead of `verify.yourbrand.com`, and `_abc123.verify` instead of `_abc123.verify.yourbrand.com`. Then re-open the saved record and check that the full name it stored matches the console **Hostname** exactly.
  </Accordion>

  <Accordion title="A correction is taking hours to apply">
    Your records are cached for the length of their TTL. Lower the TTL to `300` and wait for the previous value to expire before testing again.
  </Accordion>
</AccordionGroup>

***

## Next steps

* **Match the rest of the UI to your brand** — colors, logo, and typography live in the [White Label](/console/white-label) style editor.
* **Enable your style per workflow** — branding only applies to workflows with **Include custom style** turned on. See [White Label](/console/white-label#activate-custom-style-in-your-workflow).
* **Review your disclosure obligations** — a custom domain hides Didit's branding but not its role. See [compliance responsibilities](/console/white-label#compliance-responsibilities-in-white-label-flows).


# Data retention
Source: https://docs.didit.me/console/data-retention

Configure how long Didit stores verification data, delete sessions on demand, and implement privacy-first KYC with EU residency, GDPR, and DPA support.

## Role and processing location

| Aspect                 | Detail                                                                                                                               |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| **Processor role**     | Didit acts as a **data processor**; you remain the data controller.                                                                  |
| **Processing region**  | EU by default. Enterprise accounts can enable **in-country processing** (local data residency) subject to availability and contract. |
| **Regulatory posture** | Designed to support **GDPR** and local data-protection regimes. Configure retention below to meet your obligations.                  |

<Note>
  Need a DPA, TOMs, or other compliance attestations? Contact your Didit representative.
</Note>

***

## Retention controls

Configure retention in **Business Console → App Settings → Data**.

<Steps>
  <Step title="Open retention settings">
    Go to **Business Console → App Settings → Data**.
  </Step>

  <Step title="Choose a retention policy">
    Select a window from **1 month** to **10 years**, or leave as **unlimited** (default).
  </Step>

  <Step title="Save">
    Click **Save** to apply the policy to all future and existing sessions.
  </Step>
</Steps>

The policy applies to verification inputs/outputs, derived results, and operational metadata stored by Didit. When a session reaches the end of the window it is deleted exactly as by [Delete Session](/sessions-api/delete-session), including its face embedding unless you have enabled [biometric-template retention](#biometric-template-retention).

<Frame>
  <img alt="Data retention settings in the Business Console" />
</Frame>

***

## Manual deletion

Delete individual sessions from the Console when you need one-off removals.

1. Navigate to **Dashboard → Verifications**.
2. Search or filter for the target session.
3. Click the **Delete** button (top-right) and confirm.

<Frame>
  <img alt="Delete a verification session from the Console" />
</Frame>

***

## Programmatic deletion

Delete a session via the API at any time by calling the [Delete Session](/sessions-api/delete-session) endpoint.

```bash theme={null}
curl --request DELETE \
  --url https://verification.didit.me/v3/session/{session_id}/delete/ \
  --header 'x-api-key: YOUR_API_KEY'
```

| Response        | Meaning                                                                                                |
| --------------- | ------------------------------------------------------------------------------------------------------ |
| `200 OK`        | Session deleted. The body reports what happened to the face biometric data (`face_retention_outcome`). |
| `404 Not Found` | Session already deleted or unknown `session_id`.                                                       |

For a data-subject erasure request, send `{"deletion_instruction": "privacy_erasure"}` in the body so that any retained biometric template for that person is purged as well.

***

## Biometric template retention

Every KYC session with a liveness selfie carries a face embedding that powers duplicate detection and [Face Search 1:N](/core-technology/face-search/overview). By default that embedding is deleted with the session, so a person whose session you deleted can verify again without being flagged as a duplicate.

If you delete sessions soon after approval but still need to catch repeat sign-ups, enable **biometric-template retention**. Didit then deletes the session and all of its data as usual and keeps one separately managed, image-free face biometric template anchored to the User.

<Warning>
  A retained biometric template is biometric data. It is not anonymous, it is not transient, and it is not deleted with the session. It stays until its scheduled expiry, an earlier applicable-law deadline, User deletion, a privacy-erasure request, or an explicit purge. Enable retention only when your controller instruction and privacy notice cover it, and choose a retention period that satisfies the laws that apply to your users.
</Warning>

### Enable it

<Steps>
  <Step title="Open retention settings">
    Go to **Business Console → App Settings → Data**.
  </Step>

  <Step title="Turn on Retain biometric template">
    Select **Retain until scheduled expiry or earlier deletion**. The setting reads: *Keeps an image-free face biometric template for tenant-scoped duplicate detection after an operational session deletion. It remains biometric data and is deleted on its configured schedule, applicable-law deadline, User deletion, privacy-erasure request, or explicit purge.*
  </Step>

  <Step title="Set a finite retention period">
    Enter the number of days (1 to 3650) a template may be kept. The setting cannot be saved without it. Didit applies the shorter of this period, your general retention window, and any deadline you send on a deletion call.
  </Step>

  <Step title="Save">
    The policy applies to deletions from now on. No existing template is created or purged by changing the setting.
  </Step>
</Steps>

Programmatically, set the same policy with `PATCH /v3/webhook/`:

```bash theme={null}
curl -X PATCH https://verification.didit.me/v3/webhook/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"face_retention_policy": "retain_until_user_deleted", "face_retention_days": 365}'
```

| Field                   | Values                                                       | Description                                                                                                                                             |
| ----------------------- | ------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `face_retention_policy` | `delete_with_session` (default), `retain_until_user_deleted` | What happens to the face embedding when a session is deleted.                                                                                           |
| `face_retention_days`   | integer 1-3650                                               | Finite retention period for retained templates. Required when the policy is `retain_until_user_deleted`; the request is rejected with `400` without it. |

Existing applications stay on `delete_with_session` until you change the policy. Nothing enables retention on your behalf.

### What is retained and what is erased

| Deleted with the session                                                          | Retained (opt-in only)                                                                          |
| --------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------- |
| Decision, extracted data, and every feature record                                | The numeric face template used for matching                                                     |
| Document images, portraits, selfies, liveness video, POA documents, extra uploads | A new random template id and an opaque provenance reference                                     |
| The session id, number, and its link to any media                                 | The owning User, the retention dates, the instruction class and id, and the acting principal id |

The retained template is tenant-scoped and used only on your instruction for duplicate-face and multi-account detection, biometric authentication, and your own face lists. It is never used for model training, analytics, cross-organization matching, or Didit's own fraud processing.

### Per-deletion control

Every deletion reports its outcome, and every delete call can override the policy:

* **Console**: the delete confirmation shows whether each session's template will be retained or deleted. The confirmation reads: *This deletes the session and starts deletion of its session data. If biometric-template retention is enabled for this operational deletion, an image-free biometric template remains separately until its scheduled expiry or earlier purge. Privacy-erasure requests also purge the template.* Sessions without a User cannot retain a template and are marked as such.
* **API**: send `retain_face_embeddings`, `face_retention_days`, `face_retention_deadline`, `deletion_instruction`, and `instruction_id` on [Delete Session](/sessions-api/delete-session) or [Batch Delete Sessions](/management-api/sessions/batch-delete).

### Two kinds of deletion instruction

| Instruction                                                          | What it does                                                                                                                                         |
| -------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- |
| Operational session deletion (`operational_session_delete`, default) | Deletes the session and its data. A template is retained only when the policy or the request says so, and the response states the outcome.           |
| Privacy erasure (`privacy_erasure`)                                  | Deletes the session and purges every retained template for that person. The application policy cannot override it. Use it for data-subject requests. |

### When a template is purged

* You purge it in **Lists → Biometric templates** or through the [Biometric Templates API](/management-api/biometric-templates/overview).
* You delete the User with [Batch Delete Users](/management-api/users/delete).
* You delete any session of that User with `deletion_instruction: "privacy_erasure"`.
* Its retention period ends. Didit purges it automatically.

Switching the policy back to **Delete with session** stops new templates from being created but does not purge existing ones; purge them explicitly.

### Where to see them

* **Lists → Biometric templates** lists every template with its User, source, retained and expiry dates, and status, with single and bulk purge.
* **Users → \[user] → Biometric templates** shows the templates anchored to one User.
* The [Biometric Templates API](/management-api/biometric-templates/overview) exposes the same data and actions, and every retain and purge is recorded on the audit trail.

<Note>
  Retained templates are covered by the biometric-data terms of your DPA. Nothing in this page is legal advice: you remain responsible for the legal basis, notices, consent, and the retention period that applies to your users.
</Note>

***

## Process-and-purge pattern

For maximum data minimization, process verification data through Didit and purge it immediately after receiving results via webhooks.

<Steps>
  <Step title="Create a session">
    Your backend calls the [Create Session](/sessions-api/create-session) API.
  </Step>

  <Step title="Didit runs checks">
    Identity, liveness, AML, and any other configured checks execute automatically.
  </Step>

  <Step title="Receive webhook">
    Didit sends a [webhook](/integration/webhooks) with `status`, `session_id`, `vendor_data`, and full verification data.
  </Step>

  <Step title="Persist only what you need">
    Store the minimum fields required for your records (e.g., `status`, `vendor_data`).
  </Step>

  <Step title="Delete from Didit">
    Call the [Delete Session](/sessions-api/delete-session) API for that `session_id` to delete the session and its data from Didit. If you rely on duplicate detection across future sign-ups, enable [biometric-template retention](#biometric-template-retention) first; otherwise the face embedding is deleted too.
  </Step>
</Steps>

***

## Security and assurance

<CardGroup>
  <Card title="ISO/IEC 27001" icon="shield-check">
    ISMS in place. Certificate and excerpts available on request.
  </Card>

  <Card title="Penetration testing" icon="bug">
    Periodic third-party penetration tests with tracked remediation.
  </Card>

  <Card title="No known breaches" icon="lock">
    No security breaches reported to date.
  </Card>

  <Card title="Internal security team" icon="user-shield">
    Dedicated cybersecurity team with least-privilege access and strict environment separation.
  </Card>
</CardGroup>

<Info>
  All API activity is recorded in **Audit Logs** for security, compliance, and troubleshooting. Logs are retained for **365 days** and then auto-deleted.
</Info>

***

## Privacy-minimized storage

We are adding features that let you **retain only selected data fields** — for example, keep `status` and `vendor_data` while auto-purging heavier artifacts like images and documents. This gives stricter control for teams operating under data-minimization principles.

<Tip>
  Want early access to artifact-level retention rules? Contact your Didit representative.
</Tip>

***

## FAQ

<AccordionGroup>
  <Accordion title="Can I set different retention per environment?">
    Yes. You can configure different retention policies for each application you have in Didit.
  </Accordion>

  <Accordion title="Can I export data before deletion?">
    Yes. Export session data via the Console or API, then call the Delete Session endpoint.
  </Accordion>

  <Accordion title="Will a deleted user still be caught as a duplicate?">
    Only if you enabled biometric-template retention before deleting their session. By default the face embedding is deleted with the session and the person can verify again without a duplicate flag. See [Biometric template retention](#biometric-template-retention).
  </Accordion>

  <Accordion title="Where can I see who accessed what?">
    Use **Audit Logs** in the Console. Filter by user, endpoint, or date range. Logs are retained for **365 days**.
  </Accordion>
</AccordionGroup>

***

## Implementation checklist

<Steps>
  <Step title="Configure retention">
    Set your retention policy in **Console → App Settings → Data**.
  </Step>

  <Step title="Subscribe to webhooks">
    Set up [webhooks](/integration/webhooks) and verify signatures.
  </Step>

  <Step title="Persist minimal fields">
    Store only the fields your business requires.
  </Step>

  <Step title="Implement programmatic deletion">
    Call the [Delete Session](/sessions-api/delete-session) API if you use the process-and-purge pattern.
  </Step>

  <Step title="Confirm processing region">
    Verify your processing region (EU by default, or in-country for enterprise).
  </Step>

  <Step title="Separate environments">
    Use separate Sandbox and Live API keys with independent retention policies. Rotate keys regularly.
  </Step>
</Steps>


# Export to PDF & CSV
Source: https://docs.didit.me/console/export-pdf-csv

Export KYC verification results to PDF reports or CSV files for compliance audits, regulatory reporting, and data analysis. Available in the console or via API.

Didit lets you export verification data in two formats — **PDF** for individual session reports and **CSV** for bulk data exports. Both options are available from the Didit Console and through the API.

***

## Export PDF

Generate a PDF report containing the full verification results of an individual session. You can do this in two ways:

* **From the Console** — open any session and click the **Download PDF** button.
* **Via the API** — call the [Generate PDF](/sessions-api/generate-pdf) endpoint.

<Frame>
  <img alt="Export PDF from the verification dashboard" />
</Frame>

The PDF includes all verification steps, extracted data, biometric scores, AML results, and the final decision — formatted for compliance audits and regulatory filings.

### Full user history PDF

To get every session for one user in a single file, open that user's detail page and use **Actions → Download PDF**. The report bundles a cover page (profile summary, feature status, session index) with the full standard report of every completed session sharing that user's `vendor_data`, merged in chronological order.

Only sessions in a reportable status (`Approved`, `Declined`, `In Review`, `Kyc Expired`) are included, capped at the 20 most recent. The cover page states when older sessions were left out.

***

## Export CSV

The CSV export allows you to download verification session data in bulk for further analysis or record-keeping. Customize the exported data by selecting specific columns and filtering sessions.

<Frame>
  <img alt="Export CSV with column selection" />
</Frame>

<Tip>
  Use CSV exports for periodic compliance reports, internal analytics, or importing verification data into your own systems.
</Tip>


# ID Verification Methods in the Console
Source: https://docs.didit.me/console/id-verification-methods

Choose which of the three ID Verification methods each country may use, set the fallback switches, and read the method a session actually used.

The [ID Verification](/core-technology/id-verification/verification-methods) step in a workflow has a **Countries** tab. That is where you decide, country by country, which of the three methods a person may use and what happens when a non-document method does not land. Everything on the tab writes the [`methods`](/management-api/workflows/feature-configs#ocr--id-verification) key on the ID Verification node — the console and the Management API are two views of the same object.

## Countries and allowed ID methods

Open a workflow, select the **ID Verification** node, then **Countries**. Each country row shows the methods it accepts. Pick a country to open its editor.

| Section                                 | What it controls                                                                                                                                                                               | Config it writes                                                                                          |
| --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------- |
| **Document capture**                    | Whether a photographed document is accepted, plus the document types, subtypes and capture rules for that country                                                                              | `document.enabled`, `documents_allowed`                                                                   |
| **Non-doc lookup**                      | Whether the non-document lookup is offered, how many answered attempts the user gets, and whether the workflow's later Liveness and Face Match steps are skipped after a portrait-backed match | `id_lookup.enabled`, `id_lookup.max_attempts`, `id_lookup.skip_liveness_and_face_match`                   |
| **Wallets accepted**                    | Which digital ID wallets that country offers. An accept-list, not a ranking — the end user picks from what you tick                                                                            | `wallet.enabled`, `wallet.providers`                                                                      |
| **Fall back to document capture when…** | One switch per failure mode                                                                                                                                                                    | `id_lookup.on_partial_match`, `id_lookup.on_no_match`, `id_lookup.on_provider_error`, `wallet.on_failure` |

A country where you turn every method off is rejected on save with **No method enabled — nobody can verify here**, because that configuration cannot verify anybody.

### Availability is server-driven

The tab reads the same capability catalog the API validates against, so it can only ever offer you what the platform actually supports:

* A method the catalog does not offer in that country is not shown as a choice.
* A source or wallet the catalog marks **Coming soon** is listed so you can see the roadmap, but it cannot be switched on.
* Wallet sign-in is switched on per environment. While it is off, every wallet reads **Coming soon** whatever the catalog says.

### Expected request and response

**See details** on a lookup source or a wallet opens the expected request and response: what the end user is asked for, in plain language, and what the source returns. Each lookup source is named exactly — a government register in most countries, a credit-bureau or residential-records file in some — because that is what determines provenance and the consent regime. The end user never sees the response fields, the source name or the price.

### Bulk switches

**Global settings** turns a method on in every country that supports it, so you do not have to walk 36 countries by hand. The per-country editor still wins: switch a method on globally, then turn it off for the one country where you do not want it.

## Prices on the tab

Each method shows what it costs. Document capture is \$0.15 with the first 500 checks each month free. Non-document methods are priced per country and per wallet, and any price the pricing catalog has not published yet is labelled a placeholder on the tab rather than presented as a quote.

The tab also spells out the billing consequence of each fallback switch, so the cost of a configuration is visible before you save it:

* A registry that answered bills the lookup — a match and a no match both count — and the document capture then bills on top when the user falls back.
* A lookup that never returned is not billed, so an outage costs you the document price only.
* Turn a fallback off and those users are declined; nothing further is billed.
* An abandoned or failed wallet sign-in is not billed.

## Reading a session

The **ID Verification** block on a session detail carries a chip for the method that produced it and a second chip for its [assurance tier](/core-technology/id-verification/verification-methods#assurance-tiers): **Document / Documentary**, **Non-doc lookup / Data match**, or the wallet's name with **Cryptographic**.

<Note>
  A session that fell back from a non-document method to document capture reads as a **Document / Documentary** session. The API does not yet record the method that was tried first on a successful fallback — [`fallback_from`](/reference/data-models#id-verification) is populated only when the country's switch was `decline` and the session was declined — so the console has nothing to draw a "tried this, then that" trail from. To see which non-document method was attempted, use the checks list on the session.
</Note>

Below the chips, each method shows its own evidence:

* **Document** — unchanged: the front, back and selfie images, quality scores, extracted fields and warnings.
* **Non-doc lookup** — a **Registry comparison** listing every compared field with what the user provided, what the source held, and a **Match**, **Partial** or **No match** result, plus the source name, the time it was checked and the attempt count. A source that did not answer appears as its own row with an error rather than a field verdict. Where the source returned a portrait, that portrait and the user's selfie are shown side by side with the face score.
* **Wallet** — the **Credential** card: the wallet, its issuing authority, the credential type, the level of assurance it asserted, when it was verified, whether the signature checked out, and the attributes the wallet shared.

Where a source or a wallet shares no portrait, the panel says so instead of leaving an empty frame: there is nothing to face-match, and Liveness and Face Match run as their own steps if the workflow has them.

## Related

* [ID Verification methods](/core-technology/id-verification/verification-methods) — the three methods, fallback and billing
* [Non-document lookup](/core-technology/id-verification/non-doc-lookup) — per-country fields and consent
* [Digital ID wallets](/core-technology/id-verification/digital-id-wallets) — per-wallet attributes and assurance
* [Workflows](/console/workflows) — building and publishing a workflow
* [Workflow feature configs](/management-api/workflows/feature-configs#ocr--id-verification) — the same settings through the API


# Manual review
Source: https://docs.didit.me/console/manual-review

Review flagged identity verification sessions with the Didit console dashboard. Approve, decline, or request resubmission with full audit trails and evidence.

Manual review is a critical part of any robust identity verification and KYC compliance workflow. When the automated system flags a verification session with warnings or inconsistencies, it moves to **In Review** status — requiring a trained reviewer to make the final decision.

This guide walks you through the complete manual review process, including how to use the **resubmission** feature to give users a second chance.

***

## Verification dashboard overview

<Frame>
  <img alt="Manual review verifications overview" />
</Frame>

The verification table view lists all sessions with their current status, document type, country, and other key details at a glance. Sessions can have the following statuses:

| Status          | Meaning                                                      |
| --------------- | ------------------------------------------------------------ |
| **Approved**    | The user passed all identity checks                          |
| **Declined**    | The user failed one or more verification checks              |
| **In Review**   | Requires your manual attention before a decision can be made |
| **Resubmitted** | The user has been asked to redo specific verification steps  |

<Warning>
  Sessions marked as **In Review** have triggered one or more warning signals during automated processing. The total count of sessions pending review is displayed at the top of the verification dashboard.
</Warning>

***

## How to conduct an effective manual review

<Steps>
  <Step title="Initial assessment">
    Click on any session to open the detailed session view:

    1. **Review all warnings** displayed in the session overview — these are the specific signals that triggered the manual review (e.g., low liveness score, AML match, document inconsistency).
    2. **Review the user's previous verification attempts** — click on the user's vendor data to access the session history and see if they have prior verification sessions.
    3. **Review the session events timeline** — the events section provides a chronological log of every action taken during the session.
  </Step>

  <Step title="Document inspection">
    Didit's automated system already performs comprehensive document verification — including security feature detection, field-level data consistency checks, MRZ validation, expiry date verification, and image quality analysis. Your role is to **evaluate the flagged warnings** and visually confirm the document when needed.

    1. **Review document warnings** — check the specific warnings the system raised. Common warnings include data inconsistencies between fields, failed MRZ check digit validation, expired documents, or suspected tampering.
    2. **Visually verify when warnings are ambiguous** — if a warning suggests potential tampering or low image quality, inspect the document images directly. Look for signs of digital editing, cropping, screen capture, or physical manipulation.
    3. **Check extracted OCR data** — review the data the system extracted from the document and confirm it looks consistent. The system highlights fields where confidence is low.
    4. **Review decoded QR codes and barcodes** — when Document AI detects a QR code or barcode on the document, the session view highlights its location on the image or PDF preview and shows the decoded payload. A code that was found but could not be decoded is shown as detected only, with no payload claimed. This location overlay is separate from the document-manipulation warning highlights, which keep their existing treatment.
    5. **Review document matches** — if **Face Search** or duplicate detection is enabled, check whether this user has been verified before under a different identity or if the document appears in your **blocklist**.

    <Tip>
      Hover over document images in the Didit console to use the **zoom feature** for detailed pixel-level inspection. This is especially useful when verifying microprinting and holograms.
    </Tip>
  </Step>

  <Step title="Biometric and liveness verification">
    Didit automatically performs **face matching**, **liveness detection**, and — if enabled — **face search**. Your role is to review the results when they are flagged.

    1. **Face match score** — the system computes a biometric similarity score between the selfie and the document portrait. When reviewing a flagged face match, focus on structural features like eye shape, nose geometry, jawline, and distinguishing marks.
    2. **Liveness detection score** — the liveness system detects presentation attacks such as printed photos, screen replays, deepfakes, and 3D masks. Poor camera quality or low lighting can sometimes produce lower scores for genuine users — consider **requesting resubmission** rather than declining.
    3. **Face search results** — review any matches carefully:
       * **Duplicate detection** — a match with a different session may indicate the same person verifying under multiple identities.
       * **Blocklist matches** — if the face matches a blocklisted user, this typically warrants a decline.
       * **False positives** — facial similarity between different people does occur. Evaluate the confidence score and compare images visually.
  </Step>

  <Step title="Risk and signal review">
    Navigate through the **AML**, **Device & IP Analysis**, and **Database Validation** sections to assess contextual risk.

    <Frame>
      <img alt="AML screening results in manual review" />
    </Frame>

    **AML Screening**

    * **No matches** — low risk. No hits found against global watchlists, sanctions lists, or PEP databases.
    * **Matches found** — review each matched entry. Check whether it's a true positive or false positive, review the match category (PEP, sanctions, watchlist, adverse media), and consider the source and recency of the data.

    **Device & IP Analysis and device intelligence**

    * **Geographic consistency** — compare the document's country of issue, the user's claimed address, and the IP geolocation.
    * **VPN / Proxy detection** — check if the user is connecting through a VPN, proxy, or Tor network.
    * **Device metadata** — review the device type, operating system, and browser information for anomalies.
  </Step>
</Steps>

***

## Making a decision

After completing your review, you have three options: **Approve**, **Decline**, or **Request Resubmission**.

<CardGroup>
  <Card title="Approve" icon="circle-check">
    * Document appears authentic and unaltered
    * All data fields are consistent and legible
    * Selfie biometric match confirms the same person
    * Liveness check score is within acceptable range
    * No relevant AML, sanctions, or PEP matches
    * Device and location data are consistent
  </Card>

  <Card title="Decline" icon="circle-xmark">
    * Document appears tampered, forged, or altered
    * Selfie does not match the document photo
    * High-confidence AML or sanctions match confirmed
    * Strong indicators of a presentation attack
    * Fraudulent identity patterns detected
    * Critical device or location inconsistencies
  </Card>

  <Card title="Request resubmission" icon="rotate">
    * Blurry or low-quality document images
    * Failed liveness check due to technical issues
    * Wrong document submitted
    * Incomplete or expired verification steps
    * Fixable issues the user can correct
  </Card>
</CardGroup>

<Frame>
  <img alt="Decline criteria selection dialog" />
</Frame>

<Info>
  Always **select a decline reason** and add detailed **review notes** when declining a session. This supports quality assurance, regulatory audits, and internal analytics.
</Info>

***

## Requesting a resubmission

When a session cannot be clearly approved or declined — typically because of **fixable issues** — you can request the user to resubmit specific verification steps.

### How to request resubmission

<Steps>
  <Step title="Open the session">
    Navigate to the session in the Didit console.
  </Step>

  <Step title="Select Request Resubmission">
    Click the actions menu and select **Request Resubmission**.
  </Step>

  <Step title="Choose features to resubmit">
    The dialog shows all non-approved features with their current status. Select or deselect individual steps. Features that were never started are automatically required.
  </Step>

  <Step title="Optionally send an email notification">
    If the user's email is available, send them a localized notification with a direct link to resume.
  </Step>

  <Step title="Confirm">
    The session status changes to **Resubmitted** and a webhook is sent to your server.
  </Step>
</Steps>

### What happens after resubmission

1. **Feature data is reset** — only the selected features are cleared. All previous attempt data is archived and marked as `previous_attempt` in the logs.
2. **The user re-enters the verification flow** — they only need to complete the specific steps that were requested.
3. **Session stays in Resubmitted status** — distinct from **In Progress**, helping you track resubmission sessions separately.
4. **Automatic re-evaluation** — once all resubmitted features are completed, the system recalculates the final status automatically.
5. **New webhook fires** — your server receives a webhook with the updated final status.

<Tip>
  You can request resubmission multiple times on the same session. Each cycle preserves the complete history of all previous attempts for compliance audits.
</Tip>

### Resubmission vs. creating a new session

|                       | Resubmission                                                  | New session                            |
| --------------------- | ------------------------------------------------------------- | -------------------------------------- |
| **Session ID**        | Same session ID preserved                                     | New session ID created                 |
| **History**           | Previous attempts archived within the same session            | Separate session, no linked history    |
| **User effort**       | Only redo failed/selected steps                               | Full verification from scratch         |
| **Conversion impact** | Higher completion rates                                       | Risk of user drop-off                  |
| **Webhook**           | Same session ID, status changes to Resubmitted → final status | New session lifecycle from Not Started |
| **Audit trail**       | Complete history in one place                                 | Spread across multiple sessions        |

***

## Review best practices

<AccordionGroup>
  <Accordion title="Be consistent">
    Apply the same standards to every review. Document your reasoning so other team members can understand and replicate your decisions.
  </Accordion>

  <Accordion title="Prefer resubmission over decline for fixable issues">
    If the problem is a blurry photo or a technical error, requesting resubmission preserves the session and avoids unnecessary friction for genuine users.
  </Accordion>

  <Accordion title="Use the zoom feature">
    Always zoom into document images to check for subtle tampering, microprinting, or security features not visible at standard zoom levels.
  </Accordion>

  <Accordion title="Cross-reference data points">
    Don't evaluate signals in isolation. A low liveness score combined with a VPN connection and mismatched geolocation is more concerning than any single factor alone.
  </Accordion>

  <Accordion title="Document everything">
    Add detailed review notes for every decision, especially declines. These notes support internal QA, regulatory audits, and help train new team members.
  </Accordion>

  <Accordion title="Set up alerts">
    Configure email or Slack alerts to get immediately notified when sessions enter **In Review** status. Fast response times improve both compliance and user experience.
  </Accordion>

  <Accordion title="Monitor resubmission patterns">
    If a user has multiple resubmission cycles, review the full history carefully. Repeated failures on the same feature may indicate a systemic issue.
  </Accordion>
</AccordionGroup>


# Marketplace
Source: https://docs.didit.me/console/marketplace

Choose which engine runs each workflow feature: Didit's own, or a third-party provider you connect from the Marketplace, with automatic fallback to Didit.

The **Marketplace** lets you connect third-party identity verification providers to your organization and choose, feature by feature, which engine actually runs the check: Didit's own engine, or a provider you connect yourself.

***

## Choosing an engine per feature

Every feature node's first configuration tab — in both **Simple** and **Advanced** workflow mode — starts with a **Verification engine** control. It shows the engine currently running that check and, next to it, how many providers are available for that feature.

Opening the control lists every provider for that feature with an explicit status:

| Status      | Meaning                                                                                                                                |
| ----------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| **Active**  | This is the engine currently selected for the feature.                                                                                 |
| **Switch**  | A provider you've already connected. Select it to make it the active engine for this feature.                                          |
| **Connect** | A provider you have not connected yet. Selecting it opens the setup dialog so you can connect it without leaving the workflow builder. |

Features that only Didit's own engine supports show that engine with a "no other providers" note and a direct link into the Marketplace, so the control stays consistent across every feature even where there is nothing to switch to.

## Automatic fallback to Didit

Once you select a connected third-party engine for a feature, a **Fall back to Didit if my provider fails** switch appears for that feature:

* **On** (default): if your provider is unavailable, Didit's own engine runs automatically for that step, so the verification never fails outright.
* **Off**: if your provider is unavailable, the step fails instead of silently running on Didit.

## Configuring engine selection through the API

Engine selection and fallback are not part of the [workflow feature config reference](/management-api/workflows/feature-configs) — the Management API accepts them as `provider_key` and `fallback_to_native` on the feature's `config` object, but they are managed through this Marketplace UI rather than being documented per-feature fields:

| Field                | Type    | Description                                                                                                   |
| -------------------- | ------- | ------------------------------------------------------------------------------------------------------------- |
| `provider_key`       | string  | The key of the connected provider to run this feature. Omit it, or leave it unset, to use Didit's own engine. |
| `fallback_to_native` | boolean | Whether to fall back to Didit's own engine if the selected provider is unavailable. Defaults to `true`.       |

***

<CardGroup>
  <Card title="Workflows" icon="diagram-project" href="/console/workflows">
    Build the workflow that each feature's engine selection applies to.
  </Card>

  <Card title="Workflow feature configs" icon="sliders" href="/management-api/workflows/feature-configs">
    The full config reference for every workflow feature.
  </Card>
</CardGroup>


# Model training preference
Source: https://docs.didit.me/console/model-training-preference

Control whether your organization's verification data can be selected for future model training and evaluation.

Didit allows model training by default. An organization owner or administrator can opt the entire organization out at any time.

## Change the preference

1. Open the Business Console and select the organization.
2. Go to **Settings**.
3. Find **Help improve Didit's models**.
4. Turn the switch off and confirm **Opt out**.

The control is available only to roles with permission to update the organization. Other organization members can see the current state but cannot change it.

## What opting out does

Once the change takes effect, Didit excludes both historical and newly collected data belonging to the organization from future:

* model training and fine-tuning;
* model evaluation and validation;
* dataset curation; and
* training-data exports.

Opting out does not delete verification records, change retention settings, or affect live verification, fraud detection, support, security, or compliance processing. It also does not reverse updates already incorporated into a model before the opt-out took effect.

Turning the switch on again makes the organization's eligible data available for future model work. Each effective preference change is recorded for audit purposes.

<Note>
  For deletion or other privacy rights, follow the process in Didit's [Privacy Policy](https://didit.me/terms/privacy-policy) or contact [privacy@didit.me](mailto:privacy@didit.me).
</Note>


# Networks
Source: https://docs.didit.me/console/networks

Detect fraud rings automatically by clustering applicants sharing device, IP, face, document, phone, email, or address signals.

Networks automatically groups applicants, businesses, and transaction parties in your organization that share device, IP, biometric, document, or contact signals, so a ring of fraudulent accounts surfaces as one investigation instead of dozens of unrelated flags.

***

## What a network is

A network is a cluster of subjects (vendor users, vendor businesses, or transaction parties) connected through one or more shared signals. Didit builds networks continuously as verification sessions, business sessions, and transactions complete, clustering **organization-wide** across every application in your organization so a fraud ring that touches two of your products still surfaces as one network. Each application only sees the networks that include at least one of its own subjects.

<Note>
  Clustering runs on production data only. Sandbox applications are excluded entirely, sandbox sessions never create or join a network.
</Note>

## Signal types

A network forms when two or more subjects match on any of these signals:

<CardGroup>
  <Card title="Exact device match" icon="fingerprint">
    The same device fingerprint appears across sessions.
  </Card>

  <Card title="Similar device match" icon="mobile">
    Device fingerprints similar enough to indicate the same physical device with minor variation.
  </Card>

  <Card title="Same IP address" icon="globe">
    Sessions or transactions originating from the same IP address.
  </Card>

  <Card title="Same physical address" icon="map-pin">
    Proof-of-address or registry data resolving to the same address.
  </Card>

  <Card title="Similar selfie backgrounds" icon="camera">
    Liveness captures sharing a visually similar background, a signal of a single operator running multiple sessions from one location.
  </Card>

  <Card title="Similar POA documents" icon="file-lines">
    Proof-of-address documents similar enough to indicate template reuse or a shared source document.
  </Card>
</CardGroup>

Three additional exact-match signals extend the same clustering without a dedicated design pattern yet:

| Signal                 | Trigger                                                      |
| ---------------------- | ------------------------------------------------------------ |
| Shared document number | The same ID document number appears on more than one subject |
| Shared phone number    | The same phone number appears on more than one subject       |
| Shared email address   | The same email address appears on more than one subject      |

<Note>
  Signal values are never stored or displayed in the clear. Every signal except the selfie-background and face-similarity signals is identified by a keyed hash of its normalized value, exact matches link subjects without Didit (or you) ever seeing the underlying device ID, IP, document number, phone, or email again.
</Note>

A signal that links an unusually large number of subjects (a shared office IP, a kiosk device, a data-center IP) is flagged as a **hub** rather than treated as automatic fraud evidence, hub signals are common in legitimate high-traffic settings and are surfaced for review, not auto-declined.

## Viewing a network

The **Networks** list is a table of every network visible to your application: network id, name, status, risk, the patterns and signals detected, and first/last activity, with the same status, signal, pattern, and risk-band filters as the API, plus free-text search by network name, member name, or network id.

Opening a network gives you four ways to explore it:

<CardGroup>
  <Card title="Graph" icon="share-nodes">
    Subject and signal nodes connected by edges. Focus on one applicant and bound the view to 1, 2, or 3 hops to isolate their immediate connections instead of the whole network.
  </Card>

  <Card title="Table" icon="table">
    Every member as a row, with outcome status, risk, tags, and signal coverage, for scanning or exporting a large network.
  </Card>

  <Card title="Map" icon="map">
    Geographic points where members' addresses and locations converge, useful for spotting a ring anchored on one address or city.
  </Card>

  <Card title="Timeline" icon="clock">
    Chronological history of the network: when it was first detected, when each signal was observed, and every status change with its reason.
  </Card>
</CardGroup>

## Lifecycle

A network moves through exactly four statuses:

| Status      | Meaning                                                                                    |
| ----------- | ------------------------------------------------------------------------------------------ |
| `Active`    | Newly detected or still accumulating members, not yet reviewed                             |
| `In review` | An analyst is actively investigating                                                       |
| `Resolved`  | Investigation complete, the network was a legitimate cluster or the fraud has been handled |
| `Dismissed` | Reviewed and determined not to warrant action                                              |

Every status change is recorded with a reason and the acting analyst, forming the network's audit trail alongside its signal and detection history.

<Note>
  Network status describes the investigation, not any one member. Each member also carries its own **outcome status** inside the network (`Approved`, `In review`, `Declined`, `Not completed`), which is that applicant's own verification decision. A network can be `Active` while individual members are already `Approved` or `Declined`.
</Note>

## Acting on a network

From a network's detail page you can:

* **Create a case** to hand the network to your compliance team for a formal investigation, anchored to the network rather than a single subject.
* **Add to blocklist** a member's identity, or the signal itself, so future sessions matching it are automatically declined.
* **Change status** to move the network to In review, Resolved, or Dismissed, with a required reason.
* **Dismiss** a network in one step when it is clearly not fraud, this also closes out an active review if one is open.

## Related pages

<CardGroup>
  <Card title="List networks" icon="list" href="/management-api/networks/list">
    Retrieve networks for your organization through the API.
  </Card>

  <Card title="Network membership lookup" icon="magnifying-glass" href="/management-api/networks/membership-lookup">
    Look up which networks a session, user, business, or transaction belongs to.
  </Card>

  <Card title="Blocklist users" icon="ban" href="/console/blocklist-users">
    How blocklisting a document, face, phone, or email affects future sessions.
  </Card>

  <Card title="Cases" icon="clipboard-check" href="/console/case-management/cases">
    Investigate a network case through to resolution.
  </Card>
</CardGroup>


# Roles & Permissions
Source: https://docs.didit.me/console/roles-permissions

Manage team access with role-based permissions in the Didit Console. Use built-in roles or create custom roles with granular per-resource permission control.

This chapter of the Didit Academy dashboard and roles lesson picks up at team members and roles.

The Academy lesson on teams reaches members and roles at 4:04, then walks the five built-in roles and custom roles.

<VideoEmbed title="Team members and roles — Didit Academy" />

## Overview

Didit uses a role-based access control (RBAC) system to manage what team members can do in the console. Each member is assigned a **role**, and each role has a set of **permissions** that control access to specific features.

## Default roles

Didit provides five built-in (system) roles that cover common team structures:

| Role                   | Description                                                                                                                                                 |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Owner**              | Full access to all features including organization management, billing, and role management. Only owners can transfer ownership or delete the organization. |
| **Admin**              | Full management access to verification features, team members, and application settings. Cannot delete the organization or manage roles.                    |
| **Compliance Officer** | Focused on reviewing sessions, managing AML/blocklists, viewing audit logs, and handling transactions and business profiles.                                |
| **Developer**          | Manages workflows, webhooks, API keys, questionnaires, and application configuration. Read-only access to verification sessions.                            |
| **Reader**             | Read-only access to all console sections. Cannot modify any data.                                                                                           |

System roles cannot be edited or deleted.

## Custom roles

Organization owners can create **custom roles** with specific permission combinations tailored to your team's needs.

To create a custom role:

1. Go to **Settings** > **Roles**
2. Click **Create Role**
3. Enter a name, slug, and description
4. Select the permissions you want to grant
5. Click **Create Role**

Custom roles can be edited and deleted at any time. You cannot delete a role that is currently assigned to members — reassign them first.

## Permission reference

Permissions follow an `action:resource` format. The available actions are:

* **read** — View a resource
* **write** — Update a resource
* **create** — Create new instances of a resource
* **delete** — Remove a resource
* **list** — List multiple instances of a resource

### Resource permissions

| Resource         | Available actions                 | Console section                                             |
| ---------------- | --------------------------------- | ----------------------------------------------------------- |
| `organization`   | read, write, delete               | Organization settings                                       |
| `members`        | read, list, write, delete         | Team members                                                |
| `roles`          | read, list, write, create, delete | Role management                                             |
| `applications`   | read, list, write, create, delete | Application settings                                        |
| `sessions`       | read, list, create, write, delete | Verification sessions, status changes, and session deletion |
| `users`          | read, list                        | End-user directory                                          |
| `businesses`     | read, list, write                 | Business profiles (KYB)                                     |
| `transactions`   | read, list, create, write         | Transaction monitoring                                      |
| `workflows`      | read, write, create, delete       | Workflow editor                                             |
| `questionnaires` | read, write, create, delete       | Questionnaires                                              |
| `customization`  | read, write                       | White-label branding                                        |
| `lists`          | read, write, create, delete       | Lists (blocklists/allowlists)                               |
| `blocklist`      | read, write, create               | Blocklist management                                        |
| `webhooks`       | read, write, create, delete       | Webhook destinations                                        |
| `api-keys`       | read, write                       | API key management                                          |
| `analytics`      | read                              | Analytics dashboard                                         |
| `audit-logs`     | read, list                        | Audit logs                                                  |
| `subscription`   | read, write                       | Billing and usage                                           |
| `invoices`       | read, list                        | Invoice management                                          |
| `saml`           | read, write                       | SSO/SAML configuration                                      |

## Assigning roles

When inviting a new team member or editing an existing member, you select from all available roles (both system and custom).

Members can only be assigned one role at a time. To change a member's role, go to **Settings** > **Team** and edit the member.

## Invitation links

Each invitation is emailed as a single-use link scoped to the invited address and expires after **30 days**. If an invitee reports that their link shows **Invitation unavailable**, the original invitation is no longer valid - go to **Settings** > **Team** and send them a new one rather than resending the old email.


# Session chats
Source: https://docs.didit.me/console/session-chats

Collaborate on verification reviews with in-session chats. Mention teammates, document compliance decisions, and get real-time notifications via WebSocket.

Session Chats enable compliance teams to collaborate directly within verification sessions. Leave comments, mention colleagues with `@email`, and receive real-time notifications — all within the Didit Console.

This feature transforms the manual review process from an isolated task into a collaborative workflow, ensuring your team can efficiently discuss edge cases, escalate concerns, and document decisions without leaving the platform.

<Frame>
  <img alt="Session chats in the Didit console" />
</Frame>

***

## Why session chats?

| Challenge                       | Solution                                         |
| ------------------------------- | ------------------------------------------------ |
| Context switching between tools | All discussion happens directly on the session   |
| Lost audit trails               | Every comment and activity is permanently logged |
| Delayed responses               | Real-time notifications via WebSocket and email  |
| Unclear ownership               | @mentions notify specific team members instantly |
| Scattered documentation         | Comments create a searchable history per session |

***

## Core features

### Comments and mentions

Add comments to any verification session to discuss findings, request clarifications, or document decisions. Use `@email` syntax to mention specific team members.

```text theme={null}
"I've reviewed the document and the address doesn't match.
@maria@company.com can you verify with the customer?"
```

When you mention a colleague:

* They receive an **instant notification** in the Console
* The notification includes a direct link to the session

***

## Notification types

| Type         | Trigger                                   | Description                                                         |
| ------------ | ----------------------------------------- | ------------------------------------------------------------------- |
| **Mention**  | `@email` in comment                       | You were directly mentioned in a comment                            |
| **Comment**  | New comment on a session you've reviewed  | Someone added a comment to a session you previously interacted with |
| **Activity** | Any activity on a session you've reviewed | Status change, file upload, tag change, etc.                        |

***

## Best practices

<CardGroup>
  <Card title="Use mentions for escalations" icon="at">
    When you need a specific person's attention, use `@email` to ensure they're notified immediately.
  </Card>

  <Card title="Document decisions" icon="file-lines">
    Create an audit trail by explaining why you approved, rejected, or escalated a session.
  </Card>

  <Card title="Combine tags and comments" icon="tags">
    Add a tag like `needs-review` and leave a comment explaining what needs attention.
  </Card>
</CardGroup>


# Transaction monitoring
Source: https://docs.didit.me/console/transaction-monitoring

Review transactions, tune rules, investigate alerts, manage cases, and monitor wallet and travel-rule exposures. AML, KYT, and crypto monitoring in one console.

Use **Transactions** in the Business Console to:

* Review incoming and outgoing transactions with scores, tags, and rule matches.
* Use the **Overview** tab to monitor transaction count, transaction volume, average amount, action-type and category breakdowns, user geography, top rules triggered, analyst performance, and score distribution.
* Start from a built-in KYT rule library covering finance monitoring, AML/CTF red flags, device-intelligence patterns, crypto-monitoring exposures, Travel Rule escalations, and responsible-gaming scenarios.
* Build custom monitoring rules with velocity windows and remediation actions.
* Investigate alerts, open cases, and assign analysts.
* Monitor wallet-risk snapshots, travel-rule obligations, and network graph payloads.
* Configure default currencies, thresholds, and remediation workflows.

When a rule moves a transaction to `AWAITING_USER`, Didit creates a linked remediation session and returns a verification URL so you can continue the flow without leaving the transaction workspace.

## Built-in rule bundles

Didit seeds a preset KYT rule library for every application with transaction monitoring enabled. The starting library covers common regulatory typologies, including:

* **AML/CTF and finance**: structuring, cumulative volume, large single transactions, rapid in-and-out movement, sanctions, PEP exposure, and high-risk jurisdictions.
* **Device intelligence and fraud prevention**: repeated bonus-campaign use from the same fingerprint, multiple device fingerprints for one subject, and multi-accounting patterns.
* **Crypto monitoring**: mixer exposure and high-risk wallet exposures.
* **Travel Rule**: pending counterparty, pending action, and missing required data scenarios.
* **Responsible gaming**: rapid deposit bursts and other gaming-focused escalation patterns.


# Unilinks
Source: https://docs.didit.me/console/uni-links

Launch identity verification without code using Didit Unilinks — one reusable URL per workflow. Share via email, SMS, QR code, or button for instant KYC.

**Unilink** is a single, reusable link per workflow that starts the hosted Didit verification flow — no backend required. Put it behind a button on your site, send it to users, or print it as a **QR code**. Each visit spins up a session for that workflow; results are visible in the **Business Console** for manual review.

***

## When Unilink is the right choice

Choose **Unilink** when you want **zero backend integration** and **maximum speed to market**, especially for manual or operational review scenarios:

<CardGroup>
  <Card title="Low-code / no-code teams" icon="wand-magic-sparkles">
    No API integration or backend setup needed.
  </Card>

  <Card title="MVPs and pilots" icon="flask">
    Validate your verification flow before investing in a full integration.
  </Card>

  <Card title="In-person KYC" icon="qrcode">
    Use the QR code in-store, at a branch, or on a kiosk.
  </Card>

  <Card title="Affiliate or referral verification" icon="share-nodes">
    Share the link via email, SMS, or WhatsApp.
  </Card>
</CardGroup>

***

## When NOT to use Unilink

Skip Unilink if you need any of the following — use the [API (Create Session)](/sessions-api/create-session) instead:

* **Deep backend control** over sessions and lifecycle
* **Fully automated** user journey (no manual steps)
* **Silent** or background checks
* **Dynamic workflows** based on user attributes
* **Complex conditional logic** (branching by country, risk, document type)
* **High-volume, highly customized** enterprise orchestration

***

## Unilink vs API

| Use case                          | Best option |
| --------------------------------- | ----------- |
| Quick launch / MVP                | **Unilink** |
| No backend                        | **Unilink** |
| Send a link to a user             | **Unilink** |
| QR verification (kiosk / branch)  | **Unilink** |
| Manual operator review in Console | **Unilink** |
| Fully custom flow                 | **API**     |
| Backend automation                | **API**     |
| Conditional risk logic            | **API**     |
| Mass scale with per-user context  | **API**     |

<Info>
  **Simple rule of thumb:** if you want **speed and simplicity**, choose Unilink. If you want **control and automation**, choose the API integration.
</Info>

***

## How to use Unilink

<Steps>
  <Step title="Configure a workflow">
    In the **Business Console**, set up your verification steps, liveness/AML checks, and branding.
  </Step>

  <Step title="Copy the Unilink">
    Each workflow has a unique Unilink. Copy it from the workflow settings.
  </Step>

  <Step title="Distribute">
    Share the link via:

    * A button on your website
    * Email / SMS / WhatsApp
    * Printed or on-screen QR code
  </Step>

  <Step title="Review results">
    Operators review results in the **Console** and match to internal records.
  </Step>
</Steps>

### Example: website button

```html theme={null}
<a class="btn btn-primary"
   href="https://verify.didit.me/verify/UNILINK_TOKEN"
   rel="noopener"
   target="_blank">
  Verify your identity
</a>
```

***

## Best practices

1. **Start with Unilink** for manual ops and MVPs; evolve to [Create Session](/sessions-api/create-session) as automation needs grow.
2. **Sandbox vs. Live** — test with sandbox keys/links; swap for production at go-live.
3. **Security** — if you expose the link publicly, consider bot-mitigation on the host page.
4. **Webhooks** — verify signatures, retry on failure, and store event history if you automate later. See the [Webhooks guide](/integration/webhooks).


# Verification links
Source: https://docs.didit.me/console/verification-links

Create secure verification links and QR codes from the Didit console or API. Launch hosted identity verification in minutes with no frontend development.

A Verification Link is a unique, secure URL that directs your end user to a verification flow hosted entirely by Didit. You design the verification steps and logic in your Business Console, and Didit handles the user interface, data capture, and security. This allows you to launch a robust verification process in minutes, often with no code required.

This method is part of the **Orchestrated Workflows** integration path, giving you the power of the workflow engine with maximum simplicity.

***

## How it works

<Steps>
  <Step title="Configure your workflow">
    In the [Didit Business Console](https://business.didit.me), use the no-code editor to design a workflow with the exact sequence of checks you need (e.g., ID Document Scan → Liveness Check → AML Screening). Each workflow has a unique `workflow_id`.
  </Step>

  <Step title="Generate a verification link">
    Create a unique session for a user. This can be done **no-code** directly from the Business Console, or **low-code** via a single API call to the [Create Session](/sessions-api/create-session) endpoint.
  </Step>

  <Step title="Share the link">
    Send the generated URL to your user through any channel — email, SMS, in-app message — or embed it in an iframe.
  </Step>

  <Step title="Get real-time results">
    Didit sends automated updates to your configured [webhook URL](/integration/webhooks) as the user progresses and when the final verification result is ready.
  </Step>
</Steps>

***

## Generating verification links

### Method 1: No-code generation (via Business Console)

The perfect method for getting started instantly, for manual processes, or for teams without developer resources.

1. Navigate to the **Verifications** section in your [Didit Business Console](https://business.didit.me).
2. Click **+ Create Verification**.
3. Select the `workflow_id` you want to use for this session.
4. Optionally enter `vendor_data` (like a user ID from your system) to map the verification back to your user.
5. A **unique URL and QR code** are generated instantly.
6. Copy the link, have the user scan the QR code, or send the link directly to the user's email.

### Method 2: Low-code generation (via API)

This method offers full automation and is the standard way to integrate verification links into your application logic.

Send a single `POST` request to the `/v3/session/` endpoint with your API key and `workflow_id`:

```bash theme={null}
curl --request POST \
     --url https://verification.didit.me/v3/session/ \
     --header 'x-api-key: YOUR_API_KEY' \
     --header 'Content-Type: application/json' \
     --data '{
       "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
       "vendor_data": "your_internal_user_id_123",
       "callback": "https://yourapp.com/didit/webhook/handler"
     }'
```

The API returns a JSON object containing the `session_id` and the unique verification `url`:

```json theme={null}
{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_number": 1234,
  "vendor_data": "your_internal_user_id_123",
  "status": "Not Started",
  "workflow_id": "550e8400-e29b-41d4-a716-446655440000",
  "callback": "https://yourapp.com/didit/webhook/handler",
  "url": "https://verify.didit.me/session/abcdef123456"
}
```

<Info>
  Full API details are available in the [Create Session API Reference](/sessions-api/create-session).
</Info>

***

## When to use verification links

<CardGroup>
  <Card title="Speed to market" icon="rocket">
    Launch a complete, secure, and compliant verification process in hours, not weeks.
  </Card>

  <Card title="No frontend development" icon="code">
    Offload the entire user interface — document capture, liveness checks, and user guidance — to Didit's pre-built UI.
  </Card>

  <Card title="Multi-channel delivery" icon="share-nodes">
    Send verification requests via email, SMS, support chat, or any other communication channel.
  </Card>

  <Card title="Physical onboarding" icon="qrcode">
    Use the QR code for in-person scenarios where a user needs to complete verification on their own device.
  </Card>
</CardGroup>

***

## Next steps

* **Configure your first workflow** — head to the [Business Console](https://business.didit.me) to design your verification journey.
* **Set up your webhooks** — learn how to receive real-time status updates in the [Handling Webhooks](/integration/webhooks) guide.
* **Explore Unilinks** — for a reusable, zero-backend alternative, see [Unilinks](/console/uni-links).


# White Label
Source: https://docs.didit.me/console/white-label

Fully white-label the Didit verification UI with your colors, logo, typography, and custom domain. Deliver a seamless branded KYC experience to your users.

White-label the verification flow to match your brand identity, creating a seamless experience for your users.

The workflow Academy lesson reaches white-labelling at 13:43, applying your branding to a live flow.

<VideoEmbed title="White-labelling the flow — Didit Academy" />

## Customization

In the Style Editor you can customize **everything** in the verification UI:

| Category          | What you can customize                                                                                |
| ----------------- | ----------------------------------------------------------------------------------------------------- |
| **Colors**        | Buttons, text, panels, backgrounds — every color element                                              |
| **Typography**    | Fonts that match your brand                                                                           |
| **Logos**         | Square and rectangular logo uploads                                                                   |
| **Layout**        | Border radius for panels and buttons                                                                  |
| **Login screen**  | Show or skip the login screen                                                                         |
| **Custom domain** | Host on your own subdomain instead of `verify.didit.me` — see [Custom domain](/console/custom-domain) |

<Frame>
  <img alt="White label style editor in the Business Console" />
</Frame>

## Activate custom style in your workflow

After configuring your custom style, you must **enable it per workflow** for it to apply:

1. Go to **Workflows** in the sidebar
2. Open the workflow you want to brand
3. Click **Settings** (or the gear icon)
4. Under **Options**, find **Include custom style**
5. **Enable** the toggle

<Note>
  Custom styles only apply to workflows where **Include custom style** is enabled. If you don't enable it, the workflow will use the default Didit branding.
</Note>

## Custom text

Beyond colors, logos, and layout, the **Texts** tab lets you override the wording of specific verification-flow screens and change how the completion screen behaves, without forking translations for every locale.

Open **Console → White Label → Texts** to configure:

* **Text overrides** — replace the wording of a fixed set of strings across the welcome screen, document selection, document capture, selfie intro, questionnaire navigation buttons, the completion screen, and common buttons like Continue and Retry. An override applies for one locale at a time, and you can set a different value per locale.
* **Completion screen mode** — choose **Decision** (default) to show the real outcome on the final screen, or **Submitted for review** to always show a neutral "we received your data and are reviewing it" message, even when Didit already approved the session. Use this if your own product communicates the final decision to users later.

Text overrides and the completion screen mode apply everywhere the verification flow renders: the hosted web flow, the iOS SDK, and the Android SDK.

### Dynamic placeholders

Override text can include these placeholders, resolved per user at render time:

| Placeholder   | Resolves to                                      |
| ------------- | ------------------------------------------------ |
| `{appName}`   | Your application's public name                   |
| `{stepIndex}` | The current step number in the user's workflow   |
| `{stepTotal}` | The total number of steps in the user's workflow |

`{stepIndex}` and `{stepTotal}` are computed from the actual workflow the user is running, so the same stored string correctly renders "step 1 of 3" for a three-step workflow and "step 1 of 2" for a two-step workflow.

<Note>
  Each overridden string has a 500-character limit. The Texts tab supports every locale your application can translate into, which is a longer list than the language selector in the Style Editor. Use **Auto-translate** to draft overrides for other locales from a value you've written by hand, then review before saving.
</Note>

Custom text and the completion screen mode are configured entirely from the Console and only apply where **Include custom style** is enabled for the workflow, same as the rest of white-label.

## Setup

<Steps>
  <Step title="Open the Style Editor">
    Navigate to **Console → White Label → Style Editor**.
  </Step>

  <Step title="Configure visual elements">
    * Select your brand colors using the color picker
    * Upload logos in both square and rectangular formats
    * Adjust typography and border radius settings
  </Step>

  <Step title="Set up custom domain (optional)">
    Serve the flow from your own subdomain instead of `verify.didit.me`. Follow [Custom domain](/console/custom-domain) for the DNS records and verification steps.
  </Step>

  <Step title="Override text (optional)">
    Open the **Texts** tab to change the wording of specific screens per locale, or switch the completion screen to **Submitted for review**. See [Custom text](#custom-text).
  </Step>

  <Step title="Enable in your workflow">
    For each workflow that should use your branding: **Workflow → Settings → Options → Include custom style** → enable.
  </Step>

  <Step title="Preview and test">
    Use the live preview to see changes in real-time. Test the full verification flow before going live.
  </Step>
</Steps>

## Compliance responsibilities in white-label flows

White-labeling changes the **branding** of the verification flow. It does **not** remove your obligations as the controller of that user journey.

Before you launch a white-label flow, make sure you:

1. Tell the end user that **your company** is requesting the verification and that **Didit** powers the verification workflow.
2. Link to **your own privacy notice** and any controller-side legal terms that apply to the journey.
3. Link to Didit's [Verification Privacy Notice](https://didit.me/terms/verification-privacy-notice) and [End User Terms for Identity Verification](https://didit.me/terms/identity-verification).
4. Collect **explicit affirmative consent** before document capture, selfie capture, liveness, or biometric processing whenever the applicable law or your legal position requires it.
5. Keep any proof of notice or consent that your legal team requires in your own systems.

<Warning>
  Using a custom domain or removing visible Didit branding does not eliminate Didit's role as the verification provider. If you use a custom UI or an API-driven flow, you must surface the required disclosures in your own interface.
</Warning>


# Workflows
Source: https://docs.didit.me/console/workflows

Build no-code identity verification flows with the visual workflow builder. Drag-and-drop ID, liveness, AML, NFC, branching logic. Pay only for completed steps.

Didit's Orchestrated Workflows are the most powerful and flexible way to design and deploy comprehensive, multi-step identity verification journeys.

This Didit Academy lesson builds a verification workflow in the real console, from template to published flow: picking checks on each node, rules and thresholds, AML branching, webhook nodes, and version rollback.

<VideoEmbed title="Build your first verification flow — Didit Academy" />

This integration path allows you to leverage the full intelligence of the Didit V2 platform, creating sophisticated verification sequences with our no-code visual builder. You define the logic once in your Business Console, and Didit handles the entire user-facing experience, state management, and conditional steps.

Choose this path when you need a complete, end-to-end solution for user onboarding (KYC), age verification, or re-authentication, and you want to launch quickly with minimal development effort while retaining maximum control over the process.

## Country identity methods

In ID Verification, open **Countries and allowed ID methods** to configure document capture, non-doc lookup, and digital identity wallets for each country.
**Additional settings** contains document subtypes, lookup attempts, and fallback rules.

Non-doc lookup uses your organization's Database Validation service pricing.
Each completed attempt is charged separately, including partial matches and no matches: two completed attempts mean two charges.
Format errors and provider failures that return no answer are not charged.
If several database services answer one attempt, their applicable service prices are added together.
The default is **one attempt before fallback**, configurable from one to five.
Document capture is charged additionally when a completed lookup falls back to documents.

Live applications can enable only wallets available for production.
Wallets awaiting launch stay disabled.
Sandbox applications can test every wallet in the catalog with simulated results and no charges; sandbox availability does not indicate production availability.
See [Sandbox testing](/integration/sandbox-testing) for lookup and wallet failure scenarios.

## Workflow Versioning

Workflows support **draft/publish versioning**. This means you can safely iterate on your workflow without affecting live sessions:

* **Draft versions** are fully editable — add, remove, or restructure nodes freely
* **Publishing** a draft creates an immutable version that new sessions will use
* **Previous versions** are preserved, so you can inspect the exact configuration used for any past session
* **Sessions always reference the specific version** they were created with, ensuring consistency even after you publish updates

To make changes to a published workflow, create a new draft from the published version, edit it, and publish when ready. The version history is available via the Management API.

***

## Two Ways to Build Workflows

Didit offers **two distinct approaches** to creating verification workflows, allowing you to choose the right level of complexity for your needs:

<Frame>
  <img alt="Didit KYC workflow simple and advanced builder modes side by side" />
</Frame>

### 1. Simple Mode: Template-Based Builder

The **Simple Mode** is perfect for getting started quickly. Select a pre-built template, toggle the features you need on or off, and you're ready to go.

<Frame>
  <img alt="Didit identity verification workflow simple mode template builder interface" />
</Frame>

**Best for:**

* Quick setup and deployment
* Standard verification flows
* Teams new to identity verification
* Use cases that fit common patterns

**How it works:**

1. Choose a workflow template (KYC, Age Verification, etc.)
2. Toggle features on/off (Liveness, Face Match, AML, etc.)
3. Configure basic settings for each feature
4. Publish and start verifying

***

### 2. Advanced Mode: Visual Graph Builder

The **Advanced Mode** unlocks the full power of Didit's orchestration engine. Build complex, conditional verification flows using our visual graph editor with drag-and-drop nodes, branches, and custom logic.

<Frame>
  <img alt="Node-based workflow visual graph builder" />
</Frame>

**Best for:**

* Complex, multi-path verification journeys
* Conditional logic based on user data or verification results
* Custom business rules and branching
* Enterprise-grade compliance requirements

**Key capabilities:**

* **Visual node editor**: Drag, drop, and connect nodes on an infinite canvas
* **Smart connections**: Drag from a node handle to empty space to instantly create and connect a new node
* **Conditional branches**: Route users based on extracted data, verification status, country, document type, [document subtype](/core-technology/id-verification/document-subtypes-id-verification), date of issue, age, webhook JSON response paths, or custom rules
* **Action automation**: Add tags, set metadata, or route to manual review based on flow outcomes
* **Keyboard shortcuts**: Undo (Ctrl/Cmd+Z), Redo (Ctrl/Cmd+Shift+Z), Delete (Delete/Backspace)
* **Zoom and pan**: Navigate complex flows with scroll-to-zoom and drag-to-pan

#### Graph Builder Node Types

| Node Type         | Icon Color      | Description                                          | Examples                                                                                                                                                                                 |
| ----------------- | --------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Feature Nodes** | Blue            | Verification checks that process user data           | ID Verification (OCR), Liveness, Face Match, NFC, AML, Phone/Email Verification, Questionnaire, Proof of Address, Document AI, Database Validation, Device & IP Analysis, Age Estimation |
| **Branch Nodes**  | Purple          | Conditional routing based on data or results         | Route by country, risk score, document type, document subtype, age, date of issue, months since issue, verification status                                                               |
| **Action Nodes**  | Amber           | Automation triggers that modify session or user data | Add tag, Remove tag, Set metadata, Add review note                                                                                                                                       |
| **Webhook Nodes** | Cyan            | HTTP requests that can feed data into later branches | Send session data to your server, parse JSON responses, branch on paths such as `category`, `status`, or `tags.0`                                                                        |
| **Status Nodes**  | Green/Red/Amber | Final outcomes that end the verification flow        | Approved, Declined, In Review                                                                                                                                                            |

#### Feature Node Categories

**User-Interactive Features** (can start a workflow):

* ID Verification (OCR)
* Liveness Detection
* Face Match
* Age Estimation
* Phone Verification
* Email Verification
* Questionnaire
* Proof of Address
* Document AI
* NFC / ePassport

**Backend-Only Features** (run automatically, no user interaction):

* AML Screening (requires OCR first)
* Database Validation (requires OCR first)
* Device & IP Analysis

> **Note:** Backend-only features are marked with a special indicator in the builder and execute automatically without user interaction once their dependencies are met.

Each feature node's first configuration tab starts with a **Verification engine** control: run the check with Didit's own engine, or switch it to a third-party provider you connect from the [Marketplace](/console/marketplace), with automatic fallback to Didit if that provider is unavailable.

#### How Branch Conditions Read Session Data

**Which record a condition reads.** A branch condition is bound to the feature node it was built from, and it reads that node's result. When a single node produced more than one record, the condition reads the **most recent** one. This matters most for **Device & IP Analysis**: Didit records one observation per device and IP address a session is opened from, so a user who switches phone or network mid-session leaves several records on the same node. A rule such as `IP COUNTRY is in [...]` is then evaluated against the **latest** observation - the same record shown first in the session's Device & IP Analysis panel and in the `ip_analyses` array of the decision payload. Sessions with more than one observation also carry the `MULTIPLE_DEVICES_IN_SESSION` warning, which is the signal to review the full list rather than the branch outcome alone.

**Country values.** Country conditions are matched on the country itself, not on the notation. Pick countries from the field picker and Didit normalizes both sides of the comparison, so a rule written in ISO 3166-1 alpha-3 (`UKR`) still matches a value captured as alpha-2 (`UA`).

**Resubmissions.** Branch nodes are evaluated on every attempt, including a resubmission. When you send a session back for specific steps, the branches and actions placed between those steps run again as the user re-completes them, against the data of the **new** attempt. A user who moves to a restricted jurisdiction between attempts is therefore routed by the branch that covers it, and a branch that ends on a Declined outcome ends the resubmitted session there.

***

## Workflow Templates: Your Starting Point

Think of templates not as rigid types, but as **smart, pre-configured starting points** designed for common use cases. In Simple Mode, these are ready to use. In Advanced Mode, they provide a foundation you can customize extensively.

<Frame>
  <img alt="Didit KYC workflow templates gallery for KYC, KYB and age verification use cases" />
</Frame>

### Available Templates

#### **1. KYC Workflow**

The comprehensive solution for onboarding new users and meeting full Know Your Customer (KYC) compliance.

* **Starts with:** Core ID Document Verification.
* **Commonly Added Features:**
  * `[+]` **Liveness Detection:** Ensure the user is physically present and prevent spoofing.
  * `[+]` **Face Match 1:1:** Biometrically match the user's selfie to their ID photo.
  * `[+]` **AML Screening:** Check users against global sanctions, PEP, and adverse media lists.
  * `[+]` **NFC Verification:** Add a layer of government-grade security by reading e-passport/e-ID chips.
  * `[+]` **Proof of Address (PoA):** Verify the user's residential address.
  * `[+]` **Phone Verification:** Validate phone number ownership as an additional factor.
  * `[+]` **Email Verification:** Validate email address ownership as an additional factor.
  * `[+]` **Database Validation:** Validate against official government and credit databases.
  * `[+]` **Questionnaire:** Collect structured attestations and supporting documents via customizable forms.
  * `[+]` **Device & IP Analysis:** Analyze location and connection risk.

***

#### **2. Adaptive Age Verification Workflow**

A low-friction, privacy-preserving flow for age-gated services.

* **Starts with:** Selfie-based Age Estimation.
* **Key Logic:**
  * If the estimated age is clearly above your threshold (e.g., estimated 25+ for an 18+ service), the user passes instantly.
  * If the estimate is below or within a "buffer zone" (e.g., estimated 16-20), you can configure the workflow to automatically trigger a **fallback to full ID Verification** to confirm the exact date of birth.
* **Commonly Added Features:**
  * `[+]` **Device & IP Analysis:** Restrict access based on geographic location.

***

#### **3. Biometric Authentication Workflow**

A fast and secure way to re-verify returning users without asking for their documents again.

* **Starts with:** A Liveness Detection check to confirm the user is present.
* **Core Logic:**
  * The system performs a Face Match between the new live selfie and the trusted biometric template from the user's initial, approved KYC verification.
  * If the user already has a stored face under the same `vendor_data` (approved liveness face, ePassport photo, ID document portrait, or an enrolled profile face), you can omit `portrait_image` when creating the session and Didit reuses the stored face automatically. Otherwise pass `portrait_image` (Base64-encoded image, max 2MB); without either, session creation fails with `400`.
* **Commonly Added Features:**
  * `[+]` **Phone Verification:** Link the address to a verified phone number.
  * `[+]` **Email Verification:** Validate email address ownership as an additional factor.
  * `[+]` **Device & IP Analysis:** Flag suspicious login attempts from new locations.

***

#### **4. Address Verification Workflow**

A dedicated flow for when Proof of Address (PoA) is the primary requirement.

* **Starts with:** The user submitting a Proof of Address document (e.g., utility bill, bank statement).
* **Core Logic:** Our AI extracts and validates the name and address from the document.
* **Commonly Added Features:**
  * `[+]` **Phone Verification:** Link the address to a verified phone number.
  * `[+]` **Email Verification:** Validate email address ownership as an additional factor.
  * `[+]` **Device & IP Analysis:** Compare the document address to the user's current geo-location for added assurance.

***

#### **5. Questionnaire Verification Workflow**

A focused flow when your primary goal is to collect structured attestations and supporting documents via customizable forms.

* **Starts with:** Questionnaire.
* **Core Logic:** The system presents your configured questionnaire (sections, translated content, required fields, uploads).
* **Commonly Added Features:**
  * `[+]` **Device & IP Analysis:** Add location and connection context to your questionnaire submissions.

> **Full Customization**
> Each feature within a workflow can be further customized with specific parameters to meet your exact requirements. Explore the settings for each check in the builder.

***

## Build rules from marital status

In **Advanced Mode**, you can use the OCR field `kyc.marital_status` in conditional branches and custom status rules. Choose the value from the field picker so the rule uses the supported enum rather than free-form text. If the document does not provide marital status, the value is empty and your fallback branch applies.

The workflow copilot can also create and configure **Database Validation** steps in one action. When you ask it to add this check, specify the countries you need; the console resolves the supported service for each country and shows the saved configuration on the canvas.

***

## Simple vs Advanced Mode Comparison

| Capability                         | Simple Mode | Advanced Mode  |
| ---------------------------------- | ----------- | -------------- |
| Template selection                 | ✅           | ✅              |
| Toggle features on/off             | ✅           | ✅              |
| Basic feature configuration        | ✅           | ✅              |
| Visual graph editor                | ❌           | ✅              |
| Conditional branching              | ❌           | ✅              |
| Action automation (tags, metadata) | ❌           | ✅              |
| Parallel verification paths        | ❌           | ✅              |
| Risk-based decisions               | Limited     | ✅ Full control |
| Undo/Redo support                  | ❌           | ✅              |
| Keyboard shortcuts                 | ❌           | ✅              |

***

## Integration Flow

Integrating an Orchestrated Workflow is straightforward. Your server creates a session with Didit, receives a unique URL, and redirects your user to that URL. Didit handles the rest and notifies your server of the results via webhooks.

```mermaid theme={null}
sequenceDiagram
participant Customer
participant Client
participant Server
participant Didit
Customer->>Client: Go to verification page
Client->>Server: POST /create-verification-session
Server->>Didit: POST /v3/session/
Didit-->>Server: Return new verification session
Server-->>Client: Return verification session's url
Client->>Customer: Redirect customer to url
Customer->>Didit: Complete verification steps
Didit->>Server: Send status updates
Server->>Customer: Notify of status changes
Customer->>Customer: Return to callback URL
```

***

## Common Use Cases

<table>
  <thead>
    <tr>
      <th>Use Case</th>
      <th>Recommended Template</th>
      <th>Recommended Mode</th>
      <th>Suggested Features</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>Basic identity verification</td>
      <td>KYC</td>
      <td>Simple</td>
      <td>Liveness, Face Match</td>
    </tr>

    <tr>
      <td>High-security onboarding</td>
      <td>KYC</td>
      <td>Advanced</td>
      <td>NFC, Liveness, Face Match, AML, Phone Verification</td>
    </tr>

    <tr>
      <td>Age-gated content/services</td>
      <td>Adaptive Age Verification</td>
      <td>Simple</td>
      <td>ID Verification fallback</td>
    </tr>

    <tr>
      <td>Returning user authentication</td>
      <td>Biometric Authentication</td>
      <td>Simple</td>
      <td>Device & IP Analysis</td>
    </tr>

    <tr>
      <td>Address verification</td>
      <td>Proof of Address</td>
      <td>Simple</td>
      <td>Phone Verification</td>
    </tr>

    <tr>
      <td>Financial services onboarding</td>
      <td>KYC</td>
      <td>Advanced</td>
      <td>Liveness, Face Match, Proof of Address, AML, Database Validation</td>
    </tr>

    <tr>
      <td>Region-specific compliance</td>
      <td>KYC</td>
      <td>Advanced</td>
      <td>Conditional routing by country, different checks per region</td>
    </tr>

    <tr>
      <td>Risk-based verification</td>
      <td>KYC</td>
      <td>Advanced</td>
      <td>Conditional branches based on risk scores, escalation paths</td>
    </tr>
  </tbody>
</table>

***

## Getting Started

1. **New to Didit?** Start with **Simple Mode** and a pre-built template
2. **Need customization?** Switch to **Advanced Mode** to add conditional logic

> Contact our sales team to discuss custom workflow configurations or to get guidance on the best setup for your specific requirements.


# Age Estimation Overview
Source: https://docs.didit.me/core-technology/age-estimation/overview

Verify user age from selfies with AI facial analysis. Pay-per-call $0.10, ±3.5 year accuracy, configurable ID-verification fallback for edge cases.

Didit's Age Estimation technology provides enterprise-grade age verification through advanced facial analysis and machine learning. Our system delivers high accuracy with typical estimation within ±3.5 years for most age ranges.

<AgentPromptAccordion title="Age Estimation Integration Prompt" />

## Age Estimation Methods

Our platform implements age estimation in conjunction with different liveness verification technologies:

<table>
  <thead>
    <tr>
      <th>Method</th>
      <th>Description</th>
      <th>Security Level</th>
      <th>Best For</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**`3D Action & Flash`**</td>

      <td>
        • Combines multi-factor biometric verification with a **randomized action sequence** and **dynamic light pattern analysis**.<br />
        • At the start, the user is prompted to perform a simple action—like **blinking** or **nodding**—ensuring real-time interaction.<br />
        • Simultaneously, the system projects a sequence of light patterns onto the face, analyzing the **reflections** to confirm the face's three-dimensional structure.<br />
        • **Deep learning algorithms** examine micro-expressions and the light reflection responses to verify the presence of a live person.<br />
        • Offers the **highest security** by integrating behavioral (action) and physical (light-based depth) cues, making it nearly impossible to spoof with static images, videos, or even advanced masks.
      </td>

      <td>Highest</td>
      <td>Banking, healthcare, government applications</td>
    </tr>

    <tr>
      <td>**`3D Flash`**</td>

      <td>
        • Uses **dynamic light pattern analysis** to validate facial topology without requiring user interaction.<br />
        • Projects a series of light patterns onto the face at over **30 frames per second**, analyzing the reflections to create a **depth map**.<br />
        • This depth map confirms the face's three-dimensional structure, distinguishing it from flat images or 2D spoofs.<br />
        • Provides a **seamless experience** while maintaining **high security** against presentation attacks like photos or screens.<br />
      </td>

      <td>High</td>
      <td>Financial services, account access, identity verification</td>
    </tr>

    <tr>
      <td>**`Passive Liveness`**</td>

      <td>
        • Relies on **single-frame deep learning analysis** to detect signs of liveness.<br />
        • For privacy, the user's face appears blurry in the interface, assuring them that their image is being analyzed for age estimation only, not for identification.<br />
        • Examines the image for **artifacts**, **texture patterns**, and other subtle indicators that differentiate a real face from a spoof.<br />
        • A **convolutional neural network (CNN)** validates facial features and identifies anomalies, such as those from printed photos or digital screens.<br />
        • Offers **fast and convenient** verification but provides **standard security**, suitable for low-risk use cases.<br />
      </td>

      <td>Standard</td>
      <td>Low-friction scenarios, consumer applications</td>
    </tr>
  </tbody>
</table>

Each method generates a precise age estimate along with confidence scores and supplementary gender estimation data.

### Configurable Thresholds

You can customize security levels by setting different thresholds for age estimation. For example:

<Frame>
  <img alt="Didit age estimation threshold configuration for age gating policies" />
</Frame>

<Note>
  These thresholds can be adjusted based on your risk tolerance and security requirements.
</Note>

### Per-Country Age Restrictions

Age restrictions can be configured on a **per-country basis**, reflecting the fact that the legal age of majority varies across jurisdictions. Instead of setting a single global minimum or maximum age, you can define specific age limits for each country -- and even for individual states or regions within a country.

#### How It Works

* **Country-level configuration**: Set a minimum and/or maximum age for each country (identified by the document's issuing state). For example, you might require a minimum age of 18 in the United States, 19 in South Korea, and 21 in the United Arab Emirates.
* **State/Region overrides**: For countries with sub-national variation (such as the United States or Mexico), you can configure overrides per state. For example, Mississippi may require a minimum age of 21 while the US default is 18. The system matches the state using the region extracted from the document by OCR.
* **Age of majority defaults**: The console provides a one-click "Apply age of majority" button that auto-populates each country's minimum age based on the known legal age of majority worldwide. You can then customize individual countries or states as needed.
* **Configurable actions**: When a user's age falls below the minimum or exceeds the maximum for their document's country, you can choose the action to take: **Decline** or **Review**.

#### Example Configuration

| Country | Min Age | Max Age | State Overrides              |
| ------- | ------- | ------- | ---------------------------- |
| USA     | 18      | --      | Mississippi: 21, Alabama: 19 |
| KOR     | 19      | --      | --                           |
| GBR     | 18      | 65      | --                           |
| ARE     | 21      | --      | --                           |

<Note>
  Per-country age restrictions are available in both standard KYC workflows and Adaptive Age Verification workflows. In adaptive workflows, when ID verification is triggered for borderline cases, the age check uses the per-country settings configured in the ID Verification step.
</Note>

## How It Works

<Steps>
  <Step title="Image or Video Capture" icon="camera">
    The user provides a clear facial image through API upload or completes a liveness verification process.

    | Check                     | Description                                    |
    | ------------------------- | ---------------------------------------------- |
    | **Image quality**         | Validates lighting, positioning, and clarity   |
    | **Liveness verification** | Ensures the subject is present and not a spoof |
    | **Multi-frame analysis**  | Selects the optimal frame for best accuracy    |
    | **Adaptive capture**      | Adjusts to various device capabilities         |
  </Step>

  <Step title="Facial Feature Analysis" icon="face-viewfinder">
    Advanced computer vision isolates the face and maps key facial landmarks.

    * **80+ reference points** mapped across the face
    * Deep learning algorithms analyze facial morphology, proportions, and texture
    * Demographic-specific features identified with precise pixel mapping
    * Facial regions segmented for specialized analysis (eye region, jawline, skin texture)
  </Step>

  <Step title="Neural Network Processing" icon="microchip-ai">
    Convolutional neural networks (CNNs) process the extracted features through multiple layers.

    * Model trained on **millions of diverse faces** across age ranges, ethnicities, and genders
    * Feature vectors compared against age-correlated datasets with demographic calibration
    * Multiple sub-models employed for different age brackets to enhance accuracy
    * Cross-validation against complementary models for robust estimation
  </Step>

  <Step title="Decision & Supplementary Analysis" icon="chart-simple">
    The system generates a comprehensive result:

    | Output                    | Description                                  |
    | ------------------------- | -------------------------------------------- |
    | **Age estimate**          | Primary estimate with confidence scoring     |
    | **Gender estimation**     | Supplementary demographic context (optional) |
    | **Confidence metrics**    | Overall reliability assessment               |
    | **Environmental factors** | Impact assessment on estimation quality      |
  </Step>

  <Step title="Rule Application" icon="gavel">
    Your configured business rules are applied to the estimation results.

    * Age estimate compared against your **configured thresholds** (min/max per country)
    * Confidence scores checked against your minimum requirements
    * **Borderline cases** can trigger ID verification fallback (Adaptive mode)
    * Results documented with detailed **audit trail** for compliance
  </Step>
</Steps>

## Adaptive Age Estimation

For scenarios where precise age verification is critical, our platform offers adaptive age estimation with ID verification fallback. This approach provides a balance between user convenience and regulatory compliance.

### How Adaptive Age Estimation Works

<Steps>
  <Step title="Initial Age Estimation" icon="camera">
    The system first attempts to estimate the user's age using facial analysis. A confidence score is generated alongside the age estimate.
  </Step>

  <Step title="Threshold Evaluation" icon="scale-balanced">
    The estimated age is compared against your configured thresholds. Three outcomes:

    | Outcome        | Description                                                         |
    | -------------- | ------------------------------------------------------------------- |
    | **Clear Pass** | User is clearly above your required age threshold                   |
    | **Clear Fail** | User is clearly below your required age threshold                   |
    | **Borderline** | Estimated age falls within an uncertain range or has low confidence |
  </Step>

  <Step title="Intelligent Fallback" icon="code-branch">
    * **Clear pass/fail**: Verification completes immediately with the appropriate result
    * **Borderline cases**: System automatically initiates an **ID verification flow**
    * This ensures regulatory compliance while minimizing friction for most users
  </Step>

  <Step title="Document Verification (when needed)" icon="id-card">
    For borderline cases, the user provides a government-issued ID document:

    * Document authenticity and age information are verified
    * **Per-country age restrictions** from the ID Verification step are applied
    * The system checks date of birth against the minimum/maximum age for the document's issuing country and region
  </Step>
</Steps>

<Note>
  Adaptive age estimation can be configured using [Adaptive Age Verification](/console/workflows) workflows type. You can define the borderline age thresholds that determine when ID verification is triggered. The final age-based approval or decline for borderline cases is then governed by the per-country age restrictions configured in the ID Verification step.
</Note>

### Benefits of Adaptive Age Estimation

* **Reduced Friction**: Most users complete verification with just a selfie
* **Enhanced Compliance**: Uncertain cases receive thorough document verification with country-specific age rules
* **Cost Efficiency**: ID verification is only used when necessary
* **Customizable Risk Tolerance**: Adjust thresholds based on your regulatory requirements
* **Jurisdiction-Aware**: Automatically applies the correct age of majority based on the user's document issuing country and region

This approach is particularly valuable for age-gated services like online gaming, alcohol delivery, and adult content platforms where balancing user experience with regulatory compliance is essential.

## Model Performance and Statistics

Our age estimation technology is built on advanced deep learning models that deliver industry-leading accuracy. Below are key performance metrics based on extensive validation across diverse datasets.

### Accuracy Metrics

<table>
  <thead>
    <tr>
      <th>Metric</th>
      <th>Value</th>
      <th>Description</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**Mean Absolute Error (MAE)**</td>
      <td>3.5 years</td>
      <td>Average difference between estimated and actual age across all age ranges</td>
    </tr>

    <tr>
      <td>**Standard Deviation**</td>
      <td>1.2 years</td>
      <td>Variation in estimation error across the dataset</td>
    </tr>

    <tr>
      <td>**Accuracy within ±5 years**</td>
      <td>89%</td>
      <td>Percentage of estimations within 5 years of actual age</td>
    </tr>

    <tr>
      <td>**Accuracy within ±3 years**</td>
      <td>76%</td>
      <td>Percentage of estimations within 3 years of actual age</td>
    </tr>
  </tbody>
</table>

### Performance Across Demographics

Our models are trained on diverse datasets to ensure consistent performance across different demographic groups.

<table>
  <thead>
    <tr>
      <th>Demographic Group</th>
      <th>MAE (years)</th>
      <th>Confidence Score</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>-18 age range</td>
      <td>1.5</td>
      <td>High</td>
    </tr>

    <tr>
      <td>18-25 age range</td>
      <td>2.8</td>
      <td>High</td>
    </tr>

    <tr>
      <td>26-40 age range</td>
      <td>3.2</td>
      <td>High</td>
    </tr>

    <tr>
      <td>41-60 age range</td>
      <td>3.9</td>
      <td>Medium-High</td>
    </tr>

    <tr>
      <td>60+ age range</td>
      <td>4.5</td>
      <td>Medium</td>
    </tr>
  </tbody>
</table>

<Note>
  Our models are regularly retrained and validated to ensure consistent performance across changing visual conditions and demographic representation.
</Note>


# Age Estimation Report
Source: https://docs.didit.me/core-technology/age-estimation/report-age-estimation

Parse Age Estimation responses: estimated age, passive liveness score, face quality metrics, decline thresholds, and warning codes. Pay-per-call from $0.10.

The Age Estimation report captures a model-predicted age (in years) for the largest face detected in an image, combined with a passive liveness check that confirms the subject is a real person rather than a photo, screen, or mask. The two checks always run together — Age Estimation never returns an age without a liveness score.

This page documents the JSON shape returned by both call paths: the standalone `POST /v3/age-estimation/` endpoint and the embedded `age_estimation` field on workflow liveness reports.

<Frame>
  <img alt="Didit age estimation report with predicted age, passive liveness score and face quality metrics" />
</Frame>

## Overview

Age Estimation has two delivery modes:

* **Standalone API.** `POST /v3/age-estimation/` accepts a single face image (`user_image`) and returns the predicted age and passive liveness score synchronously. See the [Age Estimation standalone API reference](/standalone-apis/age-estimation).
* **Embedded in a workflow.** Every workflow liveness report carries the predicted age under `age_estimation` — the value is always populated from the largest detected face. Age thresholds are only *enforced* (raising age warnings) on age-estimation flows: adaptive age verification workflows or `AGE_ESTIMATION` workflow nodes.

Each report contains:

* The overall `status` (`Approved`, `Declined`).
* The liveness `method` (always `PASSIVE` on the standalone API; `ACTIVE_3D` / `FLASHING` / `PASSIVE` in workflows).
* A liveness `score` (0–100; higher is more confident the subject is live; `null` is treated as `0` for threshold checks).
* The predicted `age_estimation` in years (float — for example `27.33`; `null` when no face age could be estimated).
* Standalone only: a `user_image` object with an `entities[]` array (one entry per detected face — `age`, `bbox`, `confidence`, `gender`) and the `best_angle` orientation.
* Workflow only: `reference_image`, `video_url`, `matches[]`, and the passive-liveness quality metrics `face_quality` (0–100%) and `face_luminance` (0–100%). The standalone response does **not** include these fields.
* A `warnings[]` array — risk events emitted during the check (see [Age Estimation warnings](/core-technology/age-estimation/warnings-age-estimation)).

The standalone decision is `Declined` whenever `warnings` is non-empty — `Approved` requires an empty array. Warnings fire when:

* The liveness `score` is at or below `face_liveness_score_decline_threshold` (default `30`) — `LOW_LIVENESS_SCORE`.
* The predicted age is below `age_estimation_decline_threshold` (default `18`) — `AGE_BELOW_MINIMUM`. Set the threshold to `0` to disable the age check.
* No face is detected (`NO_FACE_DETECTED`) or no face age could be estimated (`AGE_NOT_DETECTED`).
* The liveness model flags a presentation attack (`LIVENESS_FACE_ATTACK`).

## Where it appears in API responses

### Standalone API — `POST /v3/age-estimation/`

The standalone response wraps the result under a single top-level `age_estimation` object, alongside `request_id` and the echoed `vendor_data` / `metadata`. When `save_api_request=true` (the default), `request_id` is the persisted session id and the result can also be fetched later from the decision endpoint; when `false`, it is a one-off correlation UUID.

```json theme={null}
{
  "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "age_estimation": {
    "status": "Approved",
    "method": "PASSIVE",
    "score": 97.5,
    "age_estimation": 27.33,
    "user_image": { "entities": [ /* ... */ ], "best_angle": 0 },
    "warnings": []
  },
  "vendor_data": "user-123",
  "metadata": { "flow": "age-gate" },
  "created_at": "2026-06-12T02:24:11.512941+00:00"
}
```

### Workflow decision — `GET /v3/session/{session_id}/decision/`

In a workflow session, the predicted age is **embedded inside the liveness report — there is no separate age-estimation array**. The V3 decision endpoint returns liveness reports under the plural array key **`liveness_checks`** (`ReducedSessionV3DecisionSerializer.get_liveness_checks`), and each entry carries an `age_estimation` float — the estimated age of the largest detected face — or `null` if no age was computed (`LivenessV2Serializer.get_age_estimation`).

```json theme={null}
{
  "session_id": "11111111-1111-1111-1111-111111111111",
  "status": "Approved",
  "features": ["AGE_ESTIMATION"],
  "liveness_checks": [
    {
      "node_id": "feature_age_estimation_1",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 89.92,
      "age_estimation": 24.3,
      "...": "..."
    }
  ]
}
```

Read the age from `liveness_checks[].age_estimation`. Persisted standalone calls (`save_api_request=true`) appear the same way on the decision endpoint, with `features` containing `AGE_ESTIMATION`.

## Schema

The canonical field-by-field schema lives on the [Data models](/reference/data-models#age-estimation) page. The standalone response shape is documented by `AgeEstimationResponseSerializer` and assembled in `AgeEstimationAPIView`; the workflow value is produced by `LivenessV3Serializer`.

```typescript theme={null}
interface AgeEstimationStandalone {
  request_id: string;                  // Session id when save_api_request=true
  age_estimation: {
    status: "Approved" | "Declined";
    method: "PASSIVE";
    score: number | null;              // Passive liveness score (0-100); null counts as 0
    age_estimation: number | null;     // Predicted age in years of the largest face (float)
    user_image: {
      entities: Array<{
        age: number;                   // Estimated age of this face
        bbox: [number, number, number, number];  // [x_min, y_min, x_max, y_max]
        confidence: number;            // Face-detection confidence (0-1)
        gender: "male" | "female";
      }>;
      best_angle: number | null;       // Rotation (0/90/180/270) with best detection
    };
    warnings: Warning[];
  };
  vendor_data: string | null;          // Echoed from the request
  metadata: object | null;             // Echoed from the request
  created_at: string;                  // ISO 8601
}

interface WorkflowLivenessWithAge {
  node_id: string | null;
  status: "Approved" | "Declined" | "In Review";
  method: "ACTIVE_3D" | "FLASHING" | "PASSIVE";
  score: number | null;                // Liveness score (0-100)
  reference_image: string;             // Presigned URL
  video_url: string | null;            // Presigned URL (active liveness only)
  age_estimation: number | null;       // Predicted age in years (float)
  face_quality: number | null;         // 0-100% (passive liveness only)
  face_luminance: number | null;       // 0-100% (passive liveness only)
  warnings: Warning[];
  matches: FaceMatch[];
}
```

### Status values

Status strings come from the shared feature-status enum (see [Status enums](/reference/data-models#status-enums)). The standalone endpoint only ever returns:

| Status     | Meaning                                                                                           |
| ---------- | ------------------------------------------------------------------------------------------------- |
| `Approved` | No warnings fired — the subject is live and the predicted age meets the configured threshold.     |
| `Declined` | At least one warning fired — low liveness score, age below threshold, no face, no age, or attack. |

In workflow sessions, the liveness check can also resolve to `In Review` when a configurable risk fires with a review action (for example `POSSIBLE_DUPLICATED_FACE`). See the [status enum reference](/reference/data-models#status-enum-reference).

## Examples

### Approved — standalone, adult subject

```json theme={null}
{
  "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "age_estimation": {
    "status": "Approved",
    "method": "PASSIVE",
    "score": 97.5,
    "age_estimation": 27.33,
    "user_image": {
      "entities": [
        { "age": 27.33, "bbox": [40, 40, 100, 100], "confidence": 0.72, "gender": "male" }
      ],
      "best_angle": 0
    },
    "warnings": []
  },
  "vendor_data": "user-123",
  "metadata": { "flow": "age-gate" },
  "created_at": "2026-06-12T02:24:11.512941+00:00"
}
```

### Declined — standalone, predicted age below threshold

```json theme={null}
{
  "request_id": "b2c3d4e5-f6a7-8901-2345-67890abcdef0",
  "age_estimation": {
    "status": "Declined",
    "method": "PASSIVE",
    "score": 92.0,
    "age_estimation": 15.8,
    "user_image": {
      "entities": [
        { "age": 15.8, "bbox": [55, 60, 110, 110], "confidence": 0.81, "gender": "female" }
      ],
      "best_angle": 0
    },
    "warnings": [
      {
        "risk": "AGE_BELOW_MINIMUM",
        "feature": "LIVENESS",
        "additional_data": null,
        "log_type": "error",
        "short_description": "Age below minimum",
        "long_description": "The age of the face is below the minimum age threshold for the application."
      }
    ]
  },
  "vendor_data": "user-456",
  "metadata": null,
  "created_at": "2026-06-12T02:26:40.118332+00:00"
}
```

### Approved — embedded in a workflow liveness report

```json theme={null}
{
  "node_id": "feature_age_estimation_1",
  "status": "Approved",
  "method": "PASSIVE",
  "score": 89.92,
  "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
  "video_url": null,
  "age_estimation": 24.3,
  "matches": [],
  "face_quality": 87.5,
  "face_luminance": 54.12,
  "warnings": []
}
```

## Security note

All image and video URLs returned in the response are pre-signed links with a limited validity window. Treat these as short-lived references — do not share them publicly, and re-call the decision endpoint to refresh expired URLs. As a best practice, store only the verification status and confidence values on your side rather than the underlying biometric media.

## Related

* [Age Estimation overview](/core-technology/age-estimation/overview) — feature behavior, pricing, decision logic.
* [Age Estimation warnings](/core-technology/age-estimation/warnings-age-estimation) — every risk code and decline trigger.
* [Standalone API reference](/standalone-apis/age-estimation) — `POST /v3/age-estimation/` request and response.
* [Data models — age estimation](/reference/data-models#age-estimation) — canonical field-by-field schema.
* [Passive liveness](/core-technology/liveness/overview) — the shared liveness model used in age-estimation responses.


# Age Estimation Warnings
Source: https://docs.didit.me/core-technology/age-estimation/warnings-age-estimation

Reference for every Age Estimation risk code — AGE_BELOW_MINIMUM, AGE_NOT_DETECTED, LOW_LIVENESS_SCORE, NO_FACE_DETECTED — with thresholds and actions.

The Age Estimation feature emits **warnings** whenever a risk signal fires on the combined age + passive liveness check: the predicted age is below your minimum, the age could not be computed, the subject failed liveness, no face was found, or a presentation attack was detected. This page lists every code, what triggers it, and how to configure the workflow response.

## Overview

Age Estimation always runs **two checks in one call** — a passive liveness test and an age regression model — so its warnings flow through the shared liveness pipeline and are tagged with feature `LIVENESS`. They appear on the report under `age_estimation.warnings[]` (standalone API) or `liveness_checks[].warnings[]` (embedded in a workflow). The warning object schema is documented under [Data models — Warning object](/reference/data-models#warning-object).

Producers:

* **Standalone API** — the endpoint generates the five warnings listed under [Decline triggers](#decline-triggers).
* **Workflows** — the shared liveness producers plus the age-specific checks. Age warnings only fire on age-estimation flows (adaptive age verification workflows or `AGE_ESTIMATION` workflow nodes) — a plain liveness step reports an estimated age but never raises age warnings.

Severities: the five auto-decline risks (`NO_FACE_DETECTED`, `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, `AGE_BELOW_MINIMUM`, `AGE_NOT_DETECTED`) are always `log_type: "error"` and force `Declined`; the remaining risks resolve to `error` / `warning` / `information` based on thresholds or the configured action.

## Decline triggers

On the standalone API, the decision is `Declined` whenever **any** warning fires:

* **Age below threshold** — predicted age strictly below `age_estimation_decline_threshold` (default `18`; `0` disables the age check). Raises `AGE_BELOW_MINIMUM`.
* **Age not computed** — no face age could be estimated (no detectable face, or no usable face for the age model). Raises `AGE_NOT_DETECTED`.
* **Liveness score at or below threshold** — `score <= face_liveness_score_decline_threshold` (default `30`); a `null` score counts as `0`. Raises `LOW_LIVENESS_SCORE`. Suppressed when `NO_FACE_DETECTED` fires — the two are mutually exclusive.
* **No face detected** — the liveness model found no face. Raises `NO_FACE_DETECTED`.
* **Presentation attack** — the liveness model flagged a screen, printed photo, mask, or other spoof. Raises `LIVENESS_FACE_ATTACK`.

In workflows, the age checks compare the truncated estimated age (whole years) against the configured thresholds:

* **With ID-verification fallback enabled** (`enable_id_verification_fallback`, default on): an age below `borderline_minimum_age_threshold` (default `18`) raises `AGE_BELOW_MINIMUM`; ages in the borderline band (up to `borderline_maximum_age_threshold`) continue to document verification instead of raising a warning, and `AGE_NOT_DETECTED` is never raised — an undetected age routes to document verification too.
* **With fallback disabled**: no estimated age raises `AGE_NOT_DETECTED`, and an age below `minimum_age_threshold` (default `18`) raises `AGE_BELOW_MINIMUM`.

## Configurable risks

The following risks let you tune thresholds or the action per workflow setting:

| Setting                  | Risk code                  | Configurable options                                                                                                                                                                                                       |
| ------------------------ | -------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Age thresholds           | `AGE_BELOW_MINIMUM`        | Standalone: `age_estimation_decline_threshold` (default `18`, `0` disables). Workflows: `minimum_age_threshold` / `borderline_minimum_age_threshold` (default `18`) plus the ID-verification fallback for borderline ages. |
| Low Liveness Score       | `LOW_LIVENESS_SCORE`       | Separate **Decline threshold** (default `30` → `error` + decline) and **Review threshold** (default `60` → `warning` + review) applied against the liveness score.                                                         |
| Possible Duplicated Face | `POSSIBLE_DUPLICATED_FACE` | Action on detection: `DECLINE` / `REVIEW` / `NO_ACTION` (default `NO_ACTION`). Workflow sessions only.                                                                                                                     |
| Multiple Faces           | `MULTIPLE_FACES_DETECTED`  | Action on detection: `DECLINE` / `REVIEW` / `NO_ACTION` (default `NO_ACTION`). Workflow passive liveness only.                                                                                                             |

Workflow sessions also screen the face against your lists: `FACE_IN_BLOCKLIST` always auto-declines (`error`), while `POSSIBLE_FACE_IN_BLOCKLIST` moves the session to `In Review`.

## Warnings produced

| Tag                        | Severity (`log_type`)                                                   | Description                                                                                                                                                                                                                                      |
| -------------------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `AGE_BELOW_MINIMUM`        | `error` — auto-decline                                                  | The estimated age is below the active threshold (standalone `age_estimation_decline_threshold`; workflow `minimum_age_threshold` / `borderline_minimum_age_threshold`; all default `18`). `additional_data` is always `null`.                    |
| `AGE_NOT_DETECTED`         | `error` — auto-decline                                                  | No face age could be estimated. Always raised by the standalone API when the age is `null`; in workflows only when the ID-verification fallback is disabled.                                                                                     |
| `LOW_LIVENESS_SCORE`       | `error` at/below decline threshold; `warning` at/below review threshold | The liveness score is at or below the configured threshold (standalone and workflow decline default `30`; workflow review default `60`), indicating potential use of a static photo, screen, or video. Not raised when `NO_FACE_DETECTED` fires. |
| `NO_FACE_DETECTED`         | `error` — auto-decline                                                  | No face was detected in the submitted image. Re-prompt the user to center the camera with adequate lighting.                                                                                                                                     |
| `LIVENESS_FACE_ATTACK`     | `error` — auto-decline                                                  | The liveness model flagged a presentation attack (screen replay, printed photo, mask, deepfake).                                                                                                                                                 |
| `MULTIPLE_FACES_DETECTED`  | Per configured action (default `information`, no action)                | More than one face was found in the image; the largest face drives the result. Workflow passive liveness only — the standalone API does not raise it.                                                                                            |
| `FACE_IN_BLOCKLIST`        | `error` — auto-decline                                                  | The detected face matches an entry in your face blocklist managed via the [Lists API](/management-api/lists/overview). Workflow sessions only.                                                                                                   |
| `POSSIBLE_DUPLICATED_FACE` | Per configured action (default `information`, no action)                | The detected face is significantly similar to a previously approved face on another session (matches sharing the same `vendor_data` are excluded). Workflow sessions only.                                                                       |

## Example

```json theme={null}
{
  "warnings": [
    {
      "risk": "LOW_LIVENESS_SCORE",
      "feature": "LIVENESS",
      "additional_data": null,
      "log_type": "error",
      "short_description": "Low liveness score",
      "long_description": "The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data."
    },
    {
      "risk": "AGE_BELOW_MINIMUM",
      "feature": "LIVENESS",
      "additional_data": null,
      "log_type": "error",
      "short_description": "Age below minimum",
      "long_description": "The age of the face is below the minimum age threshold for the application."
    }
  ]
}
```

In workflow decision payloads (`liveness_checks[].warnings[]`), each warning also carries a `node_id` identifying the workflow node that raised it.

## Warning types

Each risk is assigned a severity based on your application's configuration. Severities fall into three categories:

<WarningTypes />

## Related

* [Age Estimation overview](/core-technology/age-estimation/overview) — feature behavior, pricing, and decision logic.
* [Age Estimation report](/core-technology/age-estimation/report-age-estimation) — full response shape for both the standalone API and the embedded workflow value.
* [Standalone API reference](/standalone-apis/age-estimation) — `POST /v3/age-estimation/` request and response.
* [Passive liveness](/core-technology/liveness/overview) — the shared liveness model used in age-estimation responses.
* [Data models — age estimation](/reference/data-models#age-estimation) — canonical field-by-field schema.


# AML Match Score
Source: https://docs.didit.me/core-technology/aml-screening/aml-match-score

Learn how AML match scores measure identity confidence via name, DOB, and country matching. Tune weights and thresholds to cut false positives.

The **Match Score** is a weighted confidence metric that determines **how closely a potential AML match corresponds to the screened individual**. This score is used to classify individual matches as either **False Positives** or **Possible Matches** that require further review.

<Frame>
  <img alt="Didit AML match score configuration showing weighted name, DOB and country thresholds" />
</Frame>

> ⚠️ **Important:** The Match Score determines **individual match classification**, NOT the final AML status. The final AML status (Approved/In Review/Declined) is determined by the [Risk Score](/core-technology/aml-screening/aml-risk-score) of non-false-positive matches.

## Overview

When screening a person against AML watchlists, each potential match receives a **match score from 0-100**. This score answers the question: **"Is this match actually the same person we're screening?"**

### Match Score vs Risk Score

| Aspect        | Match Score                                          | Risk Score                           |
| ------------- | ---------------------------------------------------- | ------------------------------------ |
| **Question**  | Is this the same person?                             | How risky is this entity?            |
| **Purpose**   | Classify matches as False Positive vs Possible Match | Determine final AML status           |
| **Factors**   | Name, DOB, Country, Document Number                  | Country, Category, Criminal Records  |
| **Threshold** | Match Score Threshold (default: 93)                  | Approve Threshold / Review Threshold |

***

## How Match Score Determines Review Status

Each match is classified based on its match score:

| Match Score                             | Review Status      | Meaning                             |
| --------------------------------------- | ------------------ | ----------------------------------- |
| Score below Match Score Threshold       | **False Positive** | Match is likely NOT the same person |
| Score at or above Match Score Threshold | **Unreviewed**     | Match requires manual review        |

> **Default threshold:** 93%

**Example:** With a threshold of 93:

* Match with score 85 → **False Positive** (auto-dismissed)
* Match with score 95 → **Unreviewed** (needs review, risk score determines urgency)

### Review Statuses Explained

All AML matches start with one of two initial statuses based on their match score:

| Status             | Description                                                                                        | When Set                 |
| ------------------ | -------------------------------------------------------------------------------------------------- | ------------------------ |
| **False Positive** | The match is likely NOT the same person as the screened individual. Excluded from risk assessment. | Match score \< threshold |
| **Unreviewed**     | The match is a possible match that requires manual review to confirm or dismiss.                   | Match score ≥ threshold  |

After manual review, compliance officers can update the status to:

| Status              | Description                                          |
| ------------------- | ---------------------------------------------------- |
| **Confirmed Match** | The match has been verified as the same person.      |
| **Inconclusive**    | Unable to determine if the match is the same person. |

<Note>
  ### **Tip:** You can change a match's review status in the Console by viewing the AML overview or clicking on a specific match to see its details.
</Note>

***

## How the Match Score is Calculated

### Step 1: Base Score Calculation

The base score is calculated using three components with configurable weights:

```
Base Score = (Name Score × Name Weight) + (DOB Score × DOB Weight) + (Country Score × Country Weight)
```

| Component               | Default Weight | Description                                                  |
| ----------------------- | -------------- | ------------------------------------------------------------ |
| **Name**                | 60%            | Fuzzy string similarity between screened name and match name |
| **Date of Birth**       | 25%            | Exact, partial (year only), or mismatch scoring              |
| **Country/Nationality** | 15%            | Comparison between screened nationality and match countries  |

> **Note:** Weights must always sum to 100%.

### Step 2: Document Number "Golden Key" Logic

After calculating the base score, the document number is evaluated separately using special override logic:

| Scenario          | Effect                     | Example                                       |
| ----------------- | -------------------------- | --------------------------------------------- |
| **Match**         | Override score to **100**  | Passport numbers match exactly                |
| **Neutral**       | Keep base score unchanged  | Different document types, or one side missing |
| **Hard Mismatch** | Apply penalty (-50 points) | Same document type but different values       |

This approach recognizes that a matching document number is definitive proof of identity (the "Golden Key"), while mismatched document types shouldn't penalize the score.

***

## Component Scoring Details

### Name Similarity (0-100)

Name matching uses the **WRatio algorithm** from RapidFuzz, which is robust to:

* Typos and misspellings
* Word order differences ("John Smith" vs "Smith, John")
* Middle name variations ("Robert J. Smith" vs "Robert James Smith")
* Length differences

### Date of Birth Scoring

| Scenario                             | Score           | Example                                                                                   |
| ------------------------------------ | --------------- | ----------------------------------------------------------------------------------------- |
| **Exact Match**                      | 100%            | "1985-03-15" matches "1985-03-15"                                                         |
| **Year Match (match has year only)** | 100%            | "1985-03-15" matches "1985" — full match because match only provides year-level precision |
| **Year Match (different day/month)** | 50%             | "1985-03-15" matches "1985-06-20" — same year but dates differ                            |
| **Year Mismatch**                    | -100% (penalty) | "1985-03-15" does not match "1990-03-15"                                                  |
| **No Data**                          | 0% (neutral)    | Either side missing DOB                                                                   |

> **Important:** When the match only provides a year (e.g., "1974"), matching that year counts as a **full match** because that's all the information available to verify.

### Country/Nationality Scoring

| Scenario             | Score          | Example                          |
| -------------------- | -------------- | -------------------------------- |
| **Exact Match**      | 100%           | "ES" matches "Spain" or "ESP"    |
| **No Data on Match** | 0% (neutral)   | Match has no country information |
| **Mismatch**         | -50% (penalty) | "ES" does not match "France"     |

The system automatically converts between:

* ISO alpha-2 codes (ES)
* ISO alpha-3 codes (ESP)
* Full country names (Spain)

It also checks the `citizenship` field in addition to `countries`.

***

## Score Normalization (Re-weighting)

When data is missing from either the screened person or the match, the system uses **score normalization** to avoid penalizing for unavailable information.

### Example: Name-Only Screening

If you screen with only a name (no DOB or country):

| Original Weights | Normalized Weights           |
| ---------------- | ---------------------------- |
| Name: 60%        | Name: **100%**               |
| DOB: 25%         | DOB: 0% (not comparable)     |
| Country: 15%     | Country: 0% (not comparable) |

**Result:** The name score becomes the entire match score.

### Example: Missing Country on Match

If the match doesn't have country data but has DOB:

| Original Weights | Normalized Weights           |
| ---------------- | ---------------------------- |
| Name: 60%        | Name: **70.6%**              |
| DOB: 25%         | DOB: **29.4%**               |
| Country: 15%     | Country: 0% (not comparable) |

This ensures fair scoring regardless of data availability.

***

## Configuration Options

You can customize the match score calculation via the API or workflow settings:

### Match Score Threshold

| Setting               | Default | Description                                                                                                                          |
| --------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| Match Score Threshold | 93      | Matches below this are classified as **False Positive**. Matches at or above are **Unreviewed** (Possible Matches) that need review. |

### Weights (must sum to 100)

| Setting        | Default | Description                            |
| -------------- | ------- | -------------------------------------- |
| Name Weight    | 60      | Weight for name similarity (0-100)     |
| DOB Weight     | 25      | Weight for date of birth (0-100)       |
| Country Weight | 15      | Weight for country/nationality (0-100) |

***

## API Request Example

```json theme={null}
{
  "full_name": "John Doe",
  "date_of_birth": "1990-01-01",
  "nationality": "USA",
  "document_number": "SAMPLE-DOC-12345",
  "aml_name_weight": 60,
  "aml_dob_weight": 25,
  "aml_country_weight": 15,
  "aml_match_score_threshold": 93
}
```

***

## Response: Score Breakdown

Each match in the response includes:

* `match_score` — The calculated match score (0-100)
* `risk_score` — The calculated risk score (0-100) - see [Risk Score](/core-technology/aml-screening/aml-risk-score)
* `review_status` — "False Positive" or "Unreviewed" based on match score threshold
* `score_breakdown` — Detailed breakdown of the match score calculation

```json theme={null}
{
  "caption": "David Sanchez",
  "match_score": 95,
  "risk_score": 65.5,
  "review_status": "Unreviewed",
  "score_breakdown": {
    "name_score": 95,
    "name_weight": 60,
    "name_weight_normalized": 70.59,
    "name_contribution": 67.06,
    "dob_score": 100,
    "dob_weight": 25,
    "dob_weight_normalized": 29.41,
    "dob_contribution": 29.41,
    "country_score": 0,
    "country_weight": 15,
    "country_weight_normalized": 0,
    "country_contribution": 0,
    "document_number_match_type": "NEUTRAL",
    "document_number_effect": "No document number provided for screening",
    "total_score": 95
  }
}
```

***

## Complete Flow: From Match Score to Final AML Status

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           AML SCREENING FLOW                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  1. RETRIEVE MATCHES FROM WATCHLISTS                                        │
│     └── All matches with score ≥ 75% are included                           │
│                                                                             │
│  2. CALCULATE MATCH SCORE FOR EACH MATCH                                    │
│     Match Score = (Name × W1) + (DOB × W2) + (Country × W3)                │
│     + Golden Key document number logic                                      │
│                                                                             │
│  3. CLASSIFY MATCHES BY MATCH SCORE (Match Score Threshold = 93)           │
│     ├── Match Score < 93 → FALSE POSITIVE (excluded from risk assessment)  │
│     └── Match Score ≥ 93 → UNREVIEWED (included in risk assessment)        │
│                                                                             │
│  4. CALCULATE RISK SCORE FOR NON-FALSE-POSITIVE MATCHES                     │
│     Risk Score = (Country × 30%) + (Category × 50%) + (Criminal × 20%)     │
│                                                                             │
│  5. DETERMINE FINAL AML STATUS (based on highest risk score)               │
│     ├── Highest Risk Score < approve_threshold → APPROVED                   │
│     ├── Highest Risk Score ≤ review_threshold → IN REVIEW                   │
│     └── Highest Risk Score > review_threshold → DECLINED                    │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

***

## Calculation Examples

### Example 1: Strong Match → Unreviewed

**Screened Data:**

* Name: "Robert J. Smith"
* DOB: "1985-03-15"
* Country: "US"

**Match Data:**

* Name: "Robert James Smith"
* DOB: "1985"
* Country: "United States"

**Calculation:**

1. Name Score: 90% (fuzzy match)
2. DOB Score: 100% (match only has year, year matches)
3. Country Score: 100% (exact match)

```
Match Score = (90 × 0.60) + (100 × 0.25) + (100 × 0.15)
            = 54 + 25 + 15
            = 94
```

**Result:** Match Score (94) ≥ threshold (93) → **Unreviewed**
→ Risk score will be calculated and used for final AML status

### Example 2: Weak Match → False Positive

**Screened Data:**

* Name: "John Smith"
* DOB: "1990-05-20"
* Country: "US"

**Match Data:**

* Name: "Johnny Smithson"
* DOB: "1975"
* Country: "Canada"

**Calculation:**

1. Name Score: 72% (weak fuzzy match)
2. DOB Score: -100% (year mismatch penalty)
3. Country Score: -50% (country mismatch penalty)

```
Match Score = (72 × 0.60) + (-100 × 0.25) + (-50 × 0.15)
            = 43.2 - 25 - 7.5
            = 10.7 → 11
```

**Result:** Match Score (11) \< threshold (93) → **False Positive**
→ This match is excluded from risk assessment

### Example 3: Golden Key Override

**Screened Data:**

* Name: "John D. Smith"
* Document Number: "A12345678"

**Match Data:**

* Name: "Jonathan David Smith"
* Document Number: "A12345678"

**Calculation:**

1. Base Score: \~70 (name fuzzy match)
2. Document Number: **MATCH** (exact match)

**Result:** Score overridden to **100** (Golden Key match) → **Unreviewed**

***

## Managing Review Status

After the initial classification, you can manually update each match's review status:

### In the Console

1. Navigate to the session's AML overview
2. Click on a specific match to view details
3. Use the status dropdown to change the review status:
   * **Confirmed Match** — Verify the match is the same person
   * **False Positive** — Mark the match as not matching
   * **Inconclusive** — Unable to determine

***

## Best Practices

1. **Start with default threshold (93)** — This provides a good balance between catching true matches and filtering false positives.

2. **Lower threshold for high-risk scenarios** — If you need to be more cautious, lower the Match Score Threshold to catch more potential matches.

3. **Use document numbers when available** — They provide the strongest identity confirmation and can override low match scores.

4. **Review normalized weights** — Check the normalized weight fields in the score breakdown to understand how missing data affected the score.

5. **Monitor false positive rates** — If too many legitimate matches are being marked as false positives, lower the threshold.


# AML Risk Score
Source: https://docs.didit.me/core-technology/aml-screening/aml-risk-score

Understand how AML risk scores are calculated from country, category, and criminal record factors. Tune thresholds to automate AML decisions.

The **Risk Score** is a quantitative assessment that evaluates **how risky an AML hit entity is**. This score is used to determine the **final AML status** (Approved/In Review/Declined) based on the highest risk score among all non-false-positive hits.

> ⚠️ **Important:** The Risk Score determines the **final AML status**, NOT individual hit classification. Individual hits are first classified as False Positive vs Unreviewed using the [Match Score](/core-technology/aml-screening/aml-match-score).

## Overview

Each AML hit receives a **risk score from 0-100**, calculated by combining three key risk factors. This score answers the question: **"If this is a true match, how risky is this entity?"**

### Risk Score vs Match Score

| Aspect         | Match Score                                   | Risk Score                          |
| -------------- | --------------------------------------------- | ----------------------------------- |
| **Question**   | Is this the same person?                      | How risky is this entity?           |
| **Purpose**    | Classify hits as False Positive vs Unreviewed | Determine final AML status          |
| **Factors**    | Name, DOB, Country, Document Number           | Country, Category, Criminal Records |
| **Applied to** | All hits                                      | Only non-false-positive hits        |

***

## How Risk Score Determines Final AML Status

The final AML status is determined by the **highest risk score** among all hits that are NOT classified as False Positive:

| Highest Risk Score                          | Final AML Status |
| ------------------------------------------- | ---------------- |
| Score below Approve Threshold               | **Approved**     |
| Score between Approve and Review Thresholds | **In Review**    |
| Score above Review Threshold                | **Declined**     |

> **Default thresholds:**
>
> * Approve Threshold: 80
> * Review Threshold: 100

**Example:** With default thresholds:

* Highest risk score = 50 → **Approved** (low risk)
* Highest risk score = 90 → **In Review** (medium risk, needs manual review)
* Highest risk score = 101 (impossible, but >100) → **Declined** (high risk)

***

## Risk Score Formula

The overall risk score is calculated using a weighted average:

```
Risk Score = (Country Score × 0.30) + (Category Score × 0.50) + (Criminal Score × 0.20)
```

| Component            | Weight | Description                                         |
| -------------------- | ------ | --------------------------------------------------- |
| **Country**          | 30%    | Geographic risk assessment based on AML/CFT factors |
| **Category**         | 50%    | Risk level based on the type of watchlist listing   |
| **Criminal Records** | 20%    | Risk from criminal history and convictions          |

***

## Risk Levels

Based on the calculated risk score, entities are classified into three risk tiers:

| Risk Level         | Score Range | Description                                          |
| ------------------ | ----------- | ---------------------------------------------------- |
| 🟢 **Low Risk**    | \< 30       | Minimal compliance concern, standard due diligence   |
| 🟡 **Medium Risk** | 30 – 49     | Elevated concern, enhanced due diligence recommended |
| 🔴 **High Risk**   | ≥ 50        | Significant concern, thorough investigation required |

***

## Component Scoring Details

### Country Score (30% Weight)

The country score reflects the inherent AML/CFT risk associated with a jurisdiction. Factors include:

* Money laundering and terrorist financing risks
* Compliance with FATF recommendations
* Presence of international sanctions
* Corruption perception indices
* Regulatory framework strength

**Scoring Range:** 0-100 (higher = more risk)

> **Note:** When a hit is associated with multiple countries, the **highest country score** is used in the calculation.

#### Country Risk Scores

| Country                               | Code | Risk Score | Risk Level |
| ------------------------------------- | ---- | ---------- | ---------- |
| 🇮🇷 Iran                             | `IR` | 81.66      | 🔴 High    |
| 🇰🇵 North Korea                      | `KP` | 78.20      | 🔴 High    |
| 🇲🇲 Myanmar                          | `MM` | 75.09      | 🔴 High    |
| 🇦🇫 Afghanistan                      | `AF` | 74.63      | 🔴 High    |
| 🇸🇾 Syria                            | `SY` | 74.49      | 🔴 High    |
| 🇭🇹 Haiti                            | `HT` | 74.30      | 🔴 High    |
| 🇨🇩 Democratic Republic of the Congo | `CD` | 71.66      | 🔴 High    |
| 🇷🇺 Russia                           | `RU` | 71.25      | 🔴 High    |
| 🇻🇪 Venezuela                        | `VE` | 71.09      | 🔴 High    |
| 🇸🇸 South Sudan                      | `SS` | 70.77      | 🔴 High    |
| 🇾🇪 Yemen                            | `YE` | 68.40      | 🔴 High    |
| 🇱🇧 Lebanon                          | `LB` | 67.76      | 🔴 High    |
| 🇸🇴 Somalia                          | `SO` | 65.38      | 🔴 High    |
| 🇲🇱 Mali                             | `ML` | 62.78      | 🔴 High    |
| 🇱🇾 Libya                            | `LY` | 61.96      | 🔴 High    |
| 🇲🇿 Mozambique                       | `MZ` | 57.15      | 🔴 High    |
| 🇧🇮 Burundi                          | `BI` | 56.48      | 🔴 High    |
| 🇵🇭 Philippines                      | `PH` | 56.44      | 🔴 High    |
| 🇬🇼 Guinea-Bissau                    | `GW` | 55.99      | 🔴 High    |
| 🇰🇪 Kenya                            | `KE` | 55.49      | 🔴 High    |
| 🇽🇰 Kosovo                           | `XK` | 55.49      | 🔴 High    |
| 🇪🇷 Eritrea                          | `ER` | 54.72      | 🔴 High    |
| 🇵🇸 State of Palestine               | `PS` | 54.41      | 🔴 High    |
| 🇳🇬 Nigeria                          | `NG` | 54.40      | 🔴 High    |
| 🇻🇳 Vietnam                          | `VN` | 54.24      | 🔴 High    |
| 🇮🇶 Iraq                             | `IQ` | 54.15      | 🔴 High    |
| 🇹🇿 Tanzania                         | `TZ` | 53.22      | 🔴 High    |
| 🇭🇷 Croatia                          | `HR` | 53.03      | 🔴 High    |
| 🇩🇿 Algeria                          | `DZ` | 52.28      | 🔴 High    |
| 🇵🇦 Panama                           | `PA` | 52.28      | 🔴 High    |
| 🇨🇮 Cote D'Ivoire                    | `CI` | 51.61      | 🔴 High    |
| 🇨🇲 Cameroon                         | `CM` | 51.35      | 🔴 High    |
| 🇨🇫 Central African Republic         | `CF` | 50.98      | 🔴 High    |
| 🇸🇩 Sudan                            | `SD` | 49.52      | 🔴 High    |
| 🇦🇴 Angola                           | `AO` | 49.47      | 🟡 Medium  |
| 🇳🇮 Nicaragua                        | `NI` | 49.07      | 🟡 Medium  |
| 🇹🇹 Trinidad and Tobago              | `TT` | 48.45      | 🟡 Medium  |
| 🇧🇫 Burkina Faso                     | `BF` | 47.94      | 🟡 Medium  |
| 🇹🇷 Turkey                           | `TR` | 47.93      | 🟡 Medium  |
| 🇻🇺 Vanuatu                          | `VU` | 47.93      | 🟡 Medium  |
| 🇳🇪 Niger                            | `NE` | 47.02      | 🟡 Medium  |
| 🇬🇹 Guatemala                        | `GT` | 47.01      | 🟡 Medium  |
| 🇧🇦 Bosnia and Herzegovina           | `BA` | 46.75      | 🟡 Medium  |
| 🇺🇬 Uganda                           | `UG` | 46.67      | 🟡 Medium  |
| 🇿🇦 South Africa                     | `ZA` | 46.60      | 🟡 Medium  |
| 🇺🇦 Ukraine                          | `UA` | 46.43      | 🟡 Medium  |
| 🇨🇳 China                            | `CN` | 45.92      | 🟡 Medium  |
| 🇨🇺 Cuba                             | `CU` | 45.89      | 🟡 Medium  |
| 🇧🇬 Bulgaria                         | `BG` | 45.70      | 🟡 Medium  |
| 🇦🇪 United Arab Emirates             | `AE` | 45.39      | 🟡 Medium  |
| 🇿🇼 Zimbabwe                         | `ZW` | 45.37      | 🟡 Medium  |
| 🇦🇱 Albania                          | `AL` | 45.34      | 🟡 Medium  |
| 🇯🇲 Jamaica                          | `JM` | 45.11      | 🟡 Medium  |
| 🇧🇧 Barbados                         | `BB` | 45.04      | 🟡 Medium  |
| 🇬🇳 Guinea                           | `GN` | 44.80      | 🟡 Medium  |
| 🇸🇽 Sint Maarten                     | `SX` | 44.79      | 🟡 Medium  |
| 🇱🇷 Liberia                          | `LR` | 44.66      | 🟡 Medium  |
| 🇷🇸 Serbia                           | `RS` | 44.26      | 🟡 Medium  |
| 🇲🇪 Montenegro                       | `ME` | 43.47      | 🟡 Medium  |
| 🇲🇨 Monaco                           | `MC` | 43.13      | 🟡 Medium  |
| 🇪🇹 Ethiopia                         | `ET` | 42.85      | 🟡 Medium  |
| 🇩🇯 Djibouti                         | `DJ` | 41.96      | 🟡 Medium  |
| 🇳🇦 Namibia                          | `NA` | 41.83      | 🟡 Medium  |
| 🇱🇦 Laos                             | `LA` | 41.73      | 🟡 Medium  |
| 🇹🇳 Tunisia                          | `TN` | 41.35      | 🟡 Medium  |
| 🇬🇮 Gibraltar                        | `GI` | 41.21      | 🟡 Medium  |
| 🇧🇾 Belarus                          | `BY` | 41.17      | 🟡 Medium  |
| 🇬🇾 Guyana                           | `GY` | 40.75      | 🟡 Medium  |
| 🇰🇲 Comoros                          | `KM` | 40.50      | 🟡 Medium  |
| 🇨🇼 Curacao                          | `CW` | 39.88      | 🟡 Medium  |
| 🇵🇰 Pakistan                         | `PK` | 39.49      | 🟡 Medium  |
| 🇸🇱 Sierra Leone                     | `SL` | 39.44      | 🟡 Medium  |
| 🇸🇷 Suriname                         | `SR` | 39.38      | 🟡 Medium  |
| 🇲🇰 North Macedonia                  | `MK` | 39.14      | 🟡 Medium  |
| 🇦🇿 Azerbaijan                       | `AZ` | 38.69      | 🟡 Medium  |
| 🇹🇩 Chad                             | `TD` | 38.54      | 🟡 Medium  |
| 🇰🇮 Kiribati                         | `KI` | 37.94      | 🟡 Medium  |
| 🇰🇭 Cambodia                         | `KH` | 37.90      | 🟡 Medium  |
| 🇬🇶 Equatorial Guinea                | `GQ` | 37.90      | 🟡 Medium  |
| 🇸🇨 Seychelles                       | `SC` | 37.60      | 🟡 Medium  |
| 🇲🇩 Moldova                          | `MD` | 37.54      | 🟡 Medium  |
| 🇧🇿 Belize                           | `BZ` | 37.48      | 🟡 Medium  |
| 🇭🇰 Hong Kong                        | `HK` | 37.47      | 🟡 Medium  |
| 🇨🇴 Colombia                         | `CO` | 37.26      | 🟡 Medium  |
| 🇵🇬 Papua New Guinea                 | `PG` | 37.20      | 🟡 Medium  |
| 🇸🇿 Eswatini                         | `SZ` | 37.00      | 🟡 Medium  |
| 🇦🇬 Antigua and Barbuda              | `AG` | 36.74      | 🟡 Medium  |
| 🇻🇬 British Virgin Islands           | `VG` | 36.70      | 🟡 Medium  |
| 🇸🇹 Sao Tome and Principe            | `ST` | 36.64      | 🟡 Medium  |
| 🇧🇯 Benin                            | `BJ` | 36.60      | 🟡 Medium  |
| 🇲🇻 Maldives                         | `MV` | 36.20      | 🟡 Medium  |
| 🇱🇨 Saint Lucia                      | `LC` | 36.18      | 🟡 Medium  |
| 🇰🇳 Saint Kitts and Nevis            | `KN` | 36.03      | 🟡 Medium  |
| 🇫🇲 Micronesia                       | `FM` | 35.97      | 🟡 Medium  |
| 🇹🇻 Tuvalu                           | `TV` | 35.94      | 🟡 Medium  |
| 🇨🇬 Congo                            | `CG` | 35.92      | 🟡 Medium  |
| 🇹🇯 Tajikistan                       | `TJ` | 35.90      | 🟡 Medium  |
| 🇸🇳 Senegal                          | `SN` | 35.88      | 🟡 Medium  |
| 🇵🇾 Paraguay                         | `PY` | 35.77      | 🟡 Medium  |
| 🇹🇭 Thailand                         | `TH` | 35.71      | 🟡 Medium  |
| 🇼🇸 Samoa                            | `WS` | 35.68      | 🟡 Medium  |
| 🇬🇦 Gabon                            | `GA` | 35.54      | 🟡 Medium  |
| 🇪🇨 Ecuador                          | `EC` | 35.29      | 🟡 Medium  |
| 🇭🇳 Honduras                         | `HN` | 35.28      | 🟡 Medium  |
| 🇸🇻 El Salvador                      | `SV` | 35.15      | 🟡 Medium  |
| 🇲🇽 Mexico                           | `MX` | 35.01      | 🟡 Medium  |
| 🇹🇬 Togo                             | `TG` | 35.01      | 🟡 Medium  |
| 🇧🇷 Brazil                           | `BR` | 34.94      | 🟡 Medium  |
| 🇬🇩 Grenada                          | `GD` | 34.87      | 🟡 Medium  |
| 🇹🇲 Turkmenistan                     | `TM` | 34.75      | 🟡 Medium  |
| 🇦🇷 Argentina                        | `AR` | 34.71      | 🟡 Medium  |
| 🇲🇬 Madagascar                       | `MG` | 34.67      | 🟡 Medium  |
| 🇸🇮 Slovenia                         | `SI` | 34.62      | 🟡 Medium  |
| 🇳🇵 Nepal                            | `NP` | 34.60      | 🟡 Medium  |
| 🇰🇬 Kyrgyzstan                       | `KG` | 34.54      | 🟡 Medium  |
| 🇹🇱 East Timor                       | `TL` | 34.50      | 🟡 Medium  |
| 🇮🇩 Indonesia                        | `ID` | 34.44      | 🟡 Medium  |
| 🇬🇭 Ghana                            | `GH` | 34.18      | 🟡 Medium  |
| 🇦🇮 Anguilla                         | `AI` | 34.17      | 🟡 Medium  |
| 🇻🇨 Saint Vincent and the Grenadines | `VC` | 34.08      | 🟡 Medium  |
| 🇨🇷 Costa Rica                       | `CR` | 33.84      | 🟡 Medium  |
| 🇧🇴 Bolivia                          | `BO` | 33.75      | 🟡 Medium  |
| 🇧🇸 The Bahamas                      | `BS` | 33.48      | 🟡 Medium  |
| 🇩🇲 Dominica                         | `DM` | 33.16      | 🟡 Medium  |
| 🇹🇴 Tonga                            | `TO` | 33.13      | 🟡 Medium  |
| 🇪🇭 Western Sahara                   | `EH` | 33.03      | 🟡 Medium  |
| 🇵🇪 Peru                             | `PE` | 32.99      | 🟡 Medium  |
| 🇰🇾 Cayman Islands                   | `KY` | 32.89      | 🟡 Medium  |
| 🇨🇾 Cyprus                           | `CY` | 32.74      | 🟡 Medium  |
| 🇦🇲 Armenia                          | `AM` | 32.69      | 🟡 Medium  |
| 🇨🇻 Cape Verde                       | `CV` | 32.61      | 🟡 Medium  |
| 🇳🇺 Niue                             | `NU` | 32.38      | 🟡 Medium  |
| 🇵🇼 Palau                            | `PW` | 32.18      | 🟡 Medium  |
| 🇲🇾 Malaysia                         | `MY` | 32.16      | 🟡 Medium  |
| 🇸🇧 Solomon Islands                  | `SB` | 32.08      | 🟡 Medium  |
| 🇮🇳 India                            | `IN` | 32.02      | 🟡 Medium  |
| 🇮🇱 Israel                           | `IL` | 31.77      | 🟡 Medium  |
| 🇬🇲 The Gambia                       | `GM` | 31.70      | 🟡 Medium  |
| 🇦🇼 Aruba                            | `AW` | 31.64      | 🟡 Medium  |
| 🇲🇸 Montserrat                       | `MS` | 31.63      | 🟡 Medium  |
| 🇧🇭 Bahrain                          | `BH` | 31.61      | 🟡 Medium  |
| 🇰🇼 Kuwait                           | `KW` | 31.52      | 🟡 Medium  |
| 🇱🇸 Lesotho                          | `LS` | 31.50      | 🟡 Medium  |
| 🇩🇴 Dominican Republic               | `DO` | 31.28      | 🟡 Medium  |
| 🇪🇬 Egypt                            | `EG` | 31.17      | 🟡 Medium  |
| 🇲🇭 Marshall Islands                 | `MH` | 31.11      | 🟡 Medium  |
| 🇲🇷 Mauritania                       | `MR` | 31.08      | 🟡 Medium  |
| 🇹🇨 Turks and Caicos                 | `TC` | 31.08      | 🟡 Medium  |
| 🇧🇩 Bangladesh                       | `BD` | 30.99      | 🟡 Medium  |
| 🇫🇯 Fiji                             | `FJ` | 30.88      | 🟡 Medium  |
| 🇳🇷 Nauru                            | `NR` | 30.84      | 🟡 Medium  |
| 🇺🇿 Uzbekistan                       | `UZ` | 30.78      | 🟡 Medium  |
| 🇱🇰 Sri Lanka                        | `LK` | 30.67      | 🟡 Medium  |
| 🇲🇦 Morocco                          | `MA` | 30.03      | 🟡 Medium  |
| 🇯🇴 Jordan                           | `JO` | 29.73      | 🟢 Low     |
| 🇲🇺 Mauritius                        | `MU` | 29.73      | 🟢 Low     |
| 🇬🇪 Georgia                          | `GE` | 29.40      | 🟢 Low     |
| 🇰🇿 Kazakhstan                       | `KZ` | 28.92      | 🟢 Low     |
| 🇸🇰 Slovakia                         | `SK` | 28.88      | 🟢 Low     |
| 🇲🇳 Mongolia                         | `MN` | 28.82      | 🟢 Low     |
| 🇷🇼 Rwanda                           | `RW` | 28.82      | 🟢 Low     |
| 🇲🇼 Malawi                           | `MW` | 28.76      | 🟢 Low     |
| 🇭🇺 Hungary                          | `HU` | 28.70      | 🟢 Low     |
| 🇷🇴 Romania                          | `RO` | 28.62      | 🟢 Low     |
| 🇲🇹 Malta                            | `MT` | 28.46      | 🟢 Low     |
| 🇸🇦 Saudi Arabia                     | `SA` | 28.32      | 🟢 Low     |
| 🇿🇲 Zambia                           | `ZM` | 28.16      | 🟢 Low     |
| 🇨🇰 Cook Islands                     | `CK` | 28.13      | 🟢 Low     |
| 🇵🇱 Poland                           | `PL` | 28.13      | 🟢 Low     |
| 🇴🇲 Oman                             | `OM` | 27.90      | 🟢 Low     |
| 🇹🇼 Taiwan                           | `TW` | 27.90      | 🟢 Low     |
| 🇨🇱 Chile                            | `CL` | 27.74      | 🟢 Low     |
| 🇧🇹 Bhutan                           | `BT` | 27.70      | 🟢 Low     |
| 🇮🇹 Italy                            | `IT` | 27.66      | 🟢 Low     |
| 🇧🇼 Botswana                         | `BW` | 27.50      | 🟢 Low     |
| 🇧🇶 Caribbean Netherlands            | `BQ` | 27.23      | 🟢 Low     |
| 🇳🇱 Netherlands                      | `NL` | 27.23      | 🟢 Low     |
| 🇬🇷 Greece                           | `GR` | 26.70      | 🟢 Low     |
| 🇮🇲 Isle of Man                      | `IM` | 26.69      | 🟢 Low     |
| 🇻🇮 U.S. Virgin Islands              | `VI` | 26.64      | 🟢 Low     |
| 🇮🇪 Ireland                          | `IE` | 25.95      | 🟢 Low     |
| 🇪🇸 Spain                            | `ES` | 25.71      | 🟢 Low     |
| 🇨🇿 Czech Republic                   | `CZ` | 25.46      | 🟢 Low     |
| 🇧🇪 Belgium                          | `BE` | 25.38      | 🟢 Low     |
| 🇸🇬 Singapore                        | `SG` | 25.31      | 🟢 Low     |
| 🇺🇸 United States                    | `US` | 25.22      | 🟢 Low     |
| 🇱🇻 Latvia                           | `LV` | 25.16      | 🟢 Low     |
| 🇲🇴 Macao                            | `MO` | 25.07      | 🟢 Low     |
| 🇨🇦 Canada                           | `CA` | 24.95      | 🟢 Low     |
| 🇬🇧 United Kingdom                   | `GB` | 24.79      | 🟢 Low     |
| 🇶🇦 Qatar                            | `QA` | 24.70      | 🟢 Low     |
| 🇨🇭 Switzerland                      | `CH` | 24.51      | 🟢 Low     |
| 🇲🇵 Northern Mariana Islands         | `MP` | 24.19      | 🟢 Low     |
| 🇦🇸 American Samoa                   | `AS` | 24.10      | 🟢 Low     |
| 🇬🇺 Guam                             | `GU` | 24.10      | 🟢 Low     |
| 🇯🇵 Japan                            | `JP` | 23.94      | 🟢 Low     |
| 🇩🇪 Germany                          | `DE` | 23.52      | 🟢 Low     |
| 🇰🇷 South Korea                      | `KR` | 23.48      | 🟢 Low     |
| 🇱🇺 Luxembourg                       | `LU` | 23.41      | 🟢 Low     |
| 🇵🇹 Portugal                         | `PT` | 23.40      | 🟢 Low     |
| 🇱🇮 Liechtenstein                    | `LI` | 23.23      | 🟢 Low     |
| 🇦🇩 Andorra                          | `AD` | 22.55      | 🟢 Low     |
| 🇦🇹 Austria                          | `AT` | 22.38      | 🟢 Low     |
| 🇻🇦 Holy See                         | `VA` | 22.17      | 🟢 Low     |
| 🇦🇺 Australia                        | `AU` | 22.12      | 🟢 Low     |
| 🇵🇷 Puerto Rico                      | `PR` | 22.11      | 🟢 Low     |
| 🇱🇹 Lithuania                        | `LT` | 22.08      | 🟢 Low     |
| 🇺🇾 Uruguay                          | `UY` | 22.06      | 🟢 Low     |
| 🇧🇲 Bermuda                          | `BM` | 21.85      | 🟢 Low     |
| 🇫🇷 France                           | `FR` | 21.71      | 🟢 Low     |
| 🇧🇳 Brunei                           | `BN` | 21.40      | 🟢 Low     |
| 🇪🇪 Estonia                          | `EE` | 21.37      | 🟢 Low     |
| 🇫🇰 Falkland Islands                 | `FK` | 21.20      | 🟢 Low     |
| 🇸🇭 Saint Helena                     | `SH` | 21.20      | 🟢 Low     |
| 🇬🇫 French Guiana                    | `GF` | 21.05      | 🟢 Low     |
| 🇵🇫 French Polynesia                 | `PF` | 21.05      | 🟢 Low     |
| 🇬🇵 Guadeloupe                       | `GP` | 21.05      | 🟢 Low     |
| 🇲🇶 Martinique                       | `MQ` | 21.05      | 🟢 Low     |
| 🇳🇨 New Caledonia                    | `NC` | 21.05      | 🟢 Low     |
| 🇧🇱 Saint Barthelemy                 | `BL` | 21.05      | 🟢 Low     |
| 🇲🇫 Saint Martin                     | `MF` | 21.05      | 🟢 Low     |
| 🇵🇲 Saint Pierre and Miquelon        | `PM` | 21.05      | 🟢 Low     |
| 🇼🇫 Wallis and Futuna                | `WF` | 21.05      | 🟢 Low     |
| 🇮🇸 Iceland                          | `IS` | 21.04      | 🟢 Low     |
| 🇬🇱 Greenland                        | `GL` | 19.43      | 🟢 Low     |
| 🇳🇿 New Zealand                      | `NZ` | 19.19      | 🟢 Low     |
| 🇹🇰 Tokelau                          | `TK` | 19.18      | 🟢 Low     |
| 🇸🇲 San Marino                       | `SM` | 19.10      | 🟢 Low     |
| 🇸🇪 Sweden                           | `SE` | 18.85      | 🟢 Low     |
| 🇩🇰 Denmark                          | `DK` | 18.46      | 🟢 Low     |
| 🇫🇴 Faroe Islands                    | `FO` | 18.46      | 🟢 Low     |
| 🇫🇮 Finland                          | `FI` | 18.01      | 🟢 Low     |
| 🇳🇴 Norway                           | `NO` | 17.62      | 🟢 Low     |

<p>
  233 countries · Risk scores based on AML/CFT factors
</p>

***

### Category Score (50% Weight)

The category score reflects the inherent risk level based on the type of watchlist the entity appears on. This is the **most heavily weighted** component because the listing type directly indicates regulatory and compliance risk.

| Category                    | Score | Description                                                       |
| --------------------------- | ----- | ----------------------------------------------------------------- |
| **Sanctions**               | 100   | Listed on international sanctions lists (OFAC, UN, EU, etc.)      |
| **PEP**                     | 100   | Politically Exposed Person (general classification)               |
| **PEP Level 1**             | 100   | Heads of state, senior government officials, supreme court judges |
| **Warnings and Regulatory** | 95    | Regulatory warnings, enforcement actions                          |
| **Insolvency**              | 80    | Bankruptcy, liquidation proceedings                               |
| **PEP Level 2**             | 80    | Members of parliament, senior military officers, ambassadors      |
| **SIE**                     | 75    | State-Influenced Enterprise — companies with government ties      |
| **SIP**                     | 75    | State-Influenced Person — individuals with government influence   |
| **PEP Level 3**             | 70    | Regional government officials, local mayors, judges               |
| **Fitness and Probity**     | 65    | Financial services fitness assessments, regulatory reviews        |
| **Adverse Media**           | 60    | Negative news coverage related to financial crime                 |
| **PEP Level 4**             | 55    | Lower-level officials, political party members                    |
| **Businessperson**          | 55    | High-profile business figures with potential exposure             |
| **Business**                | 40    | General business entities with watchlist presence                 |

> **Note:** When a hit belongs to multiple categories, the **highest category score** is used.

#### Category Risk Tiers

```
┌─────────────────────────────────────────────────────────────────┐
│  CRITICAL (100)     │ Sanctions, PEP, PEP Level 1              │
├─────────────────────────────────────────────────────────────────┤
│  VERY HIGH (80-95)  │ Warnings, Insolvency, PEP Level 2        │
├─────────────────────────────────────────────────────────────────┤
│  HIGH (70-79)       │ SIE, SIP, PEP Level 3                    │
├─────────────────────────────────────────────────────────────────┤
│  ELEVATED (55-69)   │ Fitness/Probity, Adverse Media, PEP L4   │
├─────────────────────────────────────────────────────────────────┤
│  MODERATE (40-54)   │ Business, Businessperson                 │
└─────────────────────────────────────────────────────────────────┘
```

***

### Criminal Records Score (20% Weight)

The criminal records component evaluates any criminal history associated with the entity.

| Criminal Status               | Score | Description                                         |
| ----------------------------- | ----- | --------------------------------------------------- |
| **Convicted by court**        | 100   | Entity has been convicted of a criminal offense     |
| **Criminal penalty enforced** | 90    | Entity has had criminal penalties or fines enforced |
| **No criminal records**       | 0     | No known criminal history                           |

> **Note:** Criminal records carry significant weight despite the 20% allocation because a conviction can dramatically change the risk profile of an entity.

***

## Configuration Options

### Risk Score Thresholds (Determine Final AML Status)

| Setting           | Default | Description                                                                                                     |
| ----------------- | ------- | --------------------------------------------------------------------------------------------------------------- |
| Approve Threshold | 80      | Risk scores below this result in **Approved** status                                                            |
| Review Threshold  | 100     | Risk scores above this result in **Declined** status. Scores between thresholds result in **In Review** status. |

### Match Score Threshold (Determine Hit Classification)

| Setting               | Default | Description                                                                                                                |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| Match Score Threshold | 93      | Match scores below this classify hits as **False Positive**. Only non-false-positive hits are included in risk assessment. |

***

## Complete Flow: From Screening to Final Status

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           AML SCREENING FLOW                                 │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  1. SCREEN AGAINST WATCHLISTS                                               │
│     └── Returns list of potential hits (match score ≥ 75%)                  │
│                                                                             │
│  2. FOR EACH HIT: CALCULATE MATCH SCORE                                     │
│     Match Score = (Name × W1) + (DOB × W2) + (Country × W3)                │
│     + Golden Key document number logic                                      │
│                                                                             │
│  3. CLASSIFY HITS BY MATCH SCORE                                            │
│     ├── Match Score < 93 → FALSE POSITIVE (excluded)                        │
│     └── Match Score ≥ 93 → UNREVIEWED (included)                            │
│                                                                             │
│  4. FOR EACH UNREVIEWED HIT: CALCULATE RISK SCORE                           │
│     Risk Score = (Country × 30%) + (Category × 50%) + (Criminal × 20%)     │
│                                                                             │
│  5. DETERMINE FINAL AML STATUS                                              │
│     If no non-false-positive hits → APPROVED                                │
│     Else, based on HIGHEST RISK SCORE:                                      │
│     ├── Risk Score < 86 → APPROVED                                          │
│     ├── 86 ≤ Risk Score ≤ 100 → IN REVIEW                                   │
│     └── Risk Score > 100 → DECLINED                                         │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

***

## Calculation Examples

### Example 1: High-Risk PEP from Sanctioned Country

**Hit Data:**

* Country: Iran (Score: 81.66)
* Category: Sanctions (Score: 100)
* Criminal Records: None (Score: 0)

**Risk Score Calculation:**

```
Risk Score = (81.66 × 0.30) + (100 × 0.50) + (0 × 0.20)
           = 24.50 + 50.00 + 0.00
           = 74.50
```

**Result:** Risk Score 74.50 → Entity Risk Level: **High** 🔴

* If this is the highest risk score among unreviewed hits and thresholds are default (86/100):
* 74.50 \< 86 → Final AML Status: **Approved** (entity is risky but below review threshold)

### Example 2: PEP Level 1 from High-Risk Country

**Hit Data:**

* Country: Russia (Score: 71.25)
* Category: PEP Level 1 (Score: 100)
* Criminal Records: Convicted by court (Score: 100)

**Risk Score Calculation:**

```
Risk Score = (71.25 × 0.30) + (100 × 0.50) + (100 × 0.20)
           = 21.38 + 50.00 + 20.00
           = 91.38
```

**Result:** Risk Score 91.38 → Entity Risk Level: **High** 🔴

* With default thresholds (86/100): 86 ≤ 91.38 ≤ 100 → Final AML Status: **In Review**

### Example 3: Low-Risk Business Entity

**Hit Data:**

* Country: United Kingdom (Score: 24.79)
* Category: Business (Score: 40)
* Criminal Records: None (Score: 0)

**Risk Score Calculation:**

```
Risk Score = (24.79 × 0.30) + (40 × 0.50) + (0 × 0.20)
           = 7.44 + 20.00 + 0.00
           = 27.44
```

**Result:** Risk Score 27.44 → Entity Risk Level: **Low** 🟢

* With default thresholds (86/100): 27.44 \< 86 → Final AML Status: **Approved**

***

## API Response Example

Each hit in the AML response includes both scores:

```json theme={null}
{
  "caption": "John Doe",
  "match_score": 95,
  "risk_score": 74.5,
  "review_status": "Unreviewed",
  "properties": {
    "countries": ["IR"],
    "topics": ["sanction"]
  }
}
```

The overall AML result includes the final status based on the highest risk score:

```json theme={null}
{
  "status": "In Review",
  "total_hits": 3,
  "score": 91,
  "hits": [
    {
      "caption": "John Doe",
      "match_score": 95,
      "risk_score": 91,
      "review_status": "Unreviewed"
    },
    {
      "caption": "Johnny D.",
      "match_score": 88,
      "risk_score": 45,
      "review_status": "False Positive"
    },
    {
      "caption": "J. Doe",
      "match_score": 94,
      "risk_score": 65,
      "review_status": "Unreviewed"
    }
  ]
}
```

In this example:

* Hit 2 is a False Positive (match\_score 88 \< threshold 93), so it's excluded
* The highest risk\_score among unreviewed hits is 91 (from Hit 1)
* 86 ≤ 91 ≤ 100 → Final status: **In Review**

***

## Managing Hit Review Status

You can manually update each hit's review status after the initial classification:

| Status              | Description                                                                |
| ------------------- | -------------------------------------------------------------------------- |
| **Unreviewed**      | Initial status for hits with match score ≥ threshold                       |
| **False Positive**  | Initial status for hits with match score \< threshold (or manually marked) |
| **Confirmed Match** | Manually verified as the same person                                       |
| **Inconclusive**    | Unable to determine if the hit is the same person                          |

<Note>
  ### **Tip:** Update hit review status in the Console by navigating to the AML overview or clicking on a specific hit's details.
</Note>

***

## Best Practices

1. **Understand the two-score system** — Match score filters false positives; risk score determines urgency.

2. **Review high-risk hits first** — Use risk score to prioritize your compliance team's workload among unreviewed hits.

3. **Adjust thresholds based on your risk appetite:**
   * Lower Match Score Threshold → More hits considered as unreviewed
   * Lower Approve Threshold → More sessions auto-approved
   * Lower Review Threshold → More sessions auto-declined

4. **Document your decisions** — When manually reviewing hits, record why you approved or escalated based on both match confidence and risk factors.

5. **Monitor trends** — Track your organization's hit distribution by both match score and risk level to identify patterns.


# Continuous AML Monitoring
Source: https://docs.didit.me/core-technology/aml-screening/continuous-monitoring-aml-screening

Automated daily AML rescreening for verified users. Webhook alerts on new sanctions hits and status changes. Ongoing compliance from $0.07/year.

Ongoing monitoring is a critical component of our Pro plan. It ensures that your customer due diligence remains up-to-date and helps you identify potential risks that may arise after the initial onboarding process. This feature is automatically included for all sessions where an AML check has been performed, requiring no additional integration steps.

<Frame>
  <img alt="Didit continuous AML monitoring dashboard with daily rescreening and webhook alerts" />
</Frame>

### How It Works

Our ongoing monitoring system continuously checks your verified users against various watchlists, sanctions lists, and adverse media sources. Here's a detailed overview of the process:

1. **Daily Automated Checks**:
   * Our system runs daily automated checks for all sessions that have previously been approved
   * Each check rescreens the user against our comprehensive database of watchlists and sanctions lists
   * The system compares any new findings against your configured AML thresholds

2. **Threshold-Based Updates**:
   * If new hits are found that exceed your configured review threshold, the session status changes to "In Review"
   * If new hits exceed your decline threshold, the session status automatically changes to "Declined"
   * These thresholds are the same ones you've configured in your [Workflows](/console/workflows)

3. **Real-time Notifications**:
   * When a status change occurs, your application receives a webhook notification
   * The webhook payload includes the updated status and detailed information about the new AML hits
   * These notifications follow the same format as our standard [webhook system](/integration/webhooks)

4. **Business Console Updates**:
   * All changes are immediately reflected in your Business Console
   * Your compliance team can inspect new AML hits, review detailed findings, and take appropriate actions
   * The console maintains a complete audit trail of all monitoring activities and status changes

### Enabling monitoring for users and businesses

You can turn ongoing monitoring on or off for whole users and businesses directly from the console — including users that never went through an AML check, such as imported users.

1. Open **Users** (or **Businesses**) in your Business Console, select the profiles you want to monitor, and click **AML Ongoing monitoring**.
2. The dialog shows a cost estimate before anything runs: how many profiles are selected, how many need a new AML screening, the one-time screening cost, and the yearly monitoring cost.
3. Click **Enable monitoring**. Small selections complete immediately; larger ones run in the background while the dialog shows live progress.
4. When the run finishes, the dialog breaks down the result per profile: enabled, screened and enabled, already enabled, or skipped with the reason (for example, a profile without the full name, date of birth, and country needed to screen).

A few details worth knowing:

* **Profiles without an AML screening are screened first.** Didit creates a new AML verification for them (visible in the profile's **Verifications** tab), billed as a regular AML screening. Monitoring is then enabled on that screening.
* **One monitored screening per profile.** Enabling keeps exactly one monitored AML screening per user or business, so a person who verified multiple times is only monitored — and billed — once. Disabling turns monitoring off across all of the profile's screenings.
* **The lists show monitoring at a glance.** Both the **Users** and **Businesses** lists include an **Ongoing monitoring** column; hover over it to see the next yearly billing date.
* **Select all works with your filters.** With every row selected, the action applies to your current filtered view, not just the loaded page.

The same operations are available via API: `PATCH .../vendor-users/toggle-ongoing-monitoring/` and its businesses counterparts support an `estimate_only` dry-run and return a job you can poll — see the [API reference](/api-reference/overview) for details.

### Benefits of Ongoing Monitoring

1. **Continuous Compliance**: Ensure ongoing adherence to AML/KYC regulations with zero additional setup.
2. **Risk Mitigation**: Quickly identify and address emerging risks through automatic monitoring.
3. **Operational Efficiency**: Automate time-consuming manual rescreening processes with no extra integration work.
4. **Enhanced Due Diligence**: Maintain up-to-date customer profiles automatically.
5. **Regulatory Support**: Easily demonstrate ongoing compliance efforts to regulators.
6. **Zero-Touch Integration**: Benefit from continuous monitoring without any additional development work.


# AML Screening Overview
Source: https://docs.didit.me/core-technology/aml-screening/overview

Screen users against 1,300+ global sanctions, PEP, and watchlist databases in real time. Pay-per-call $0.20, two-score risk system, no contracts.

Didit's AML Screening provides real-time risk detection by screening users against global watchlists and databases. The solution combines advanced data matching with AI-powered risk assessment to ensure regulatory compliance while maintaining a smooth user experience.

<AgentPromptAccordion title="AML Screening Integration Prompt" />

The Academy lesson on reading a verification result reaches AML screening at 8:40: sanctions, PEPs, and adverse media on a real session.

<VideoEmbed title="AML screening: sanctions, PEPs and adverse media — Didit Academy" />

<Frame>
  <img alt="Didit AML screening watchlist sources table including OFAC, EU, UN sanctions and PEP lists" />
</Frame>

## Key Concepts: Match Score vs Risk Score

Didit uses a **two-score system** for AML screening:

### Match Score (Identity Confidence)

* **Question:** Is this match the same person we're screening?
* **Factors:** Name similarity, Date of Birth, Country/Nationality, Document Number
* **Purpose:** Classifies match as **False Positive** or **Unreviewed** (Possible Match)
* **Threshold:** Match Score Threshold (default: 93)

### Risk Score (Entity Risk Level)

* **Question:** How risky is this entity if it's a true match?
* **Factors:** Country risk, Category (PEP/Sanctions/etc.), Criminal records
* **Purpose:** Determines the **final AML status** (Approved/In Review/Declined)
* **Thresholds:** Approve Threshold (default: 80) and Review Threshold (default: 100)

```
┌─────────────────────────────────────────────────────────────────────────────┐
│                           AML SCREENING FLOW                                │
├─────────────────────────────────────────────────────────────────────────────┤
│                                                                             │
│  STEP 1: Screen against watchlists                                          │
│     └── Returns potential matches (match score ≥ 75% included)              │
│                                                                             │
│  STEP 2: For each match, calculate MATCH SCORE                              │
│     └── Match Score = (Name × W1) + (DOB × W2) + (Country × W3)             │
│                                                                             │
│  STEP 3: Classify match by match score                                      │
│     ├── Match Score < 93 → FALSE POSITIVE (excluded from risk)              │
│     └── Match Score ≥ 93 → UNREVIEWED (included in risk)                    │
│                                                                             │
│  STEP 4: For unreviewed matches, calculate RISK SCORE                       │
│     └── Risk Score = (Country × 30%) + (Category × 50%) + (Criminal × 20%)  │
│                                                                             │
│  STEP 5: Determine AML STATUS (highest risk score among non-FP matches)     │
│     ├── Risk Score < 86 → APPROVED                                          │
│     ├── 86 ≤ Risk Score ≤ 100 → IN REVIEW                                   │
│     └── Risk Score > 100 → DECLINED                                         │
│                                                                             │
└─────────────────────────────────────────────────────────────────────────────┘
```

## Match Review Statuses

Each AML match is assigned a review status based on its match score:

| Status              | Description                                     | When Assigned                            |
| ------------------- | ----------------------------------------------- | ---------------------------------------- |
| **False Positive**  | Match is likely NOT the same person             | Match score \< threshold (auto-assigned) |
| **Unreviewed**      | Match is a possible match requiring review      | Match score ≥ threshold (auto-assigned)  |
| **Confirmed Match** | Match has been verified as the same person      | Manually set by compliance officer       |
| **Inconclusive**    | Unable to determine if match is the same person | Manually set by compliance officer       |

<Note>
  ### **Tip:** You can change a match review status in the Console by viewing the AML overview or clicking on a specific match to see its details.
</Note>

## Key Features

### 1. Comprehensive Data Extraction

* **Accurate Extraction**: Extract data from user-provided information or identity documents using advanced OCR technology.
* **Fuzzy Logic**: Account for name variations and misspellings to ensure comprehensive data capture.

### 2. Extensive Watchlist Coverage

Screen against multiple categories including:

* **Sanctions Lists**: From government and international bodies.
* **Politically Exposed Persons (PEPs)**: Individuals with prominent public functions.
* **Criminal Records**: Including global and local criminal databases.
* **Adverse Media Mentions**: News articles and reports on financial crimes and other risks.
* **Custom Watchlists**: Configurable based on specific client requirements.

### 3. Advanced Matching Algorithms

* **Fuzzy Matching**: Catch slight variations in names or details to ensure accurate matching.
* **Multiple Data Points**: Utilize name, date of birth, nationality, and other identifiers for thorough screening.
* **Golden Key Logic**: Document number matching that can override scores for definitive identification.

### 4. Two-Score Risk Assessment

Each match receives TWO scores:

| Score                   | Purpose                   | Classification               |
| ----------------------- | ------------------------- | ---------------------------- |
| **Match Score** (0-100) | Is this the same person?  | False Positive vs Unreviewed |
| **Risk Score** (0-100)  | How risky is this entity? | Determines final AML status  |

**Match Review Status (based on Match Score):**

* **False Positive**: Match score below threshold - likely NOT the same person
* **Unreviewed**: Match score at or above threshold - requires review

**Final AML Status (based on highest Risk Score among non-false-positive matches):**

* **Approved**: All unreviewed matches have low risk scores
* **In Review**: At least one unreviewed match has medium-high risk score
* **Declined**: At least one unreviewed match has very high risk score

### 5. Detailed Adverse Media Screening

Screen against a wide range of adverse media categories, including:

* **Financial Crimes**: Money laundering, embezzlement, and more.
* **Violent Crimes**: Assault, murder, and related offenses.
* **Terrorism**: Involvement in or support for terrorist activities.
* **Narcotics**: Drug trafficking and related crimes.
* **Fraud**: Various types of fraud and deceptive practices.
* **Regulatory Violations**: Breaches of regulatory compliance requirements.

### 6. Customizable Screening Parameters

* **Adjustable Sensitivity**: Configure the screening sensitivity based on your organization's risk appetite.
* **Customizable Watchlists**: Select which watchlists and categories to include in the screening process to meet specific requirements.

### Configurable Thresholds

You can customize security levels by setting different thresholds:

**Match Score Configuration:**

| Setting               | Default | Description                                                        |
| --------------------- | ------- | ------------------------------------------------------------------ |
| Match Score Threshold | 93      | Matches below this are False Positives, at or above are Unreviewed |
| Name Weight           | 60      | Weight for name in match score                                     |
| DOB Weight            | 25      | Weight for DOB in match score                                      |
| Country Weight        | 15      | Weight for country in match score                                  |

**Risk Score Thresholds (Final Status):**

| Setting           | Default | Description                                       |
| ----------------- | ------- | ------------------------------------------------- |
| Approve Threshold | 80      | Risk scores below = Approved                      |
| Review Threshold  | 100     | Risk scores above = Declined; between = In Review |

<Frame>
  <img alt="Didit AML risk score thresholds for Approved, In Review and Declined statuses" />
</Frame>

<Note>
  These thresholds can be adjusted based on your risk tolerance and security requirements.
</Note>

## How It Works

Our AML Screening process efficiently identifies potential risks while minimizing delays for legitimate users.

<Steps>
  <Step title="Data Extraction" icon="file-lines">
    The system extracts relevant information from either user-provided data or uploaded identity documents.

    | Input                  | Method                                                 |
    | ---------------------- | ------------------------------------------------------ |
    | **Identity documents** | Advanced OCR technology for accurate data extraction   |
    | **User-provided data** | Direct input (name, DOB, nationality, document number) |
    | **Fuzzy logic**        | Accounts for name variations and misspellings          |
  </Step>

  <Step title="Watchlist Screening" icon="magnifying-glass">
    The extracted data is cross-checked against **1,300+ global watchlists** and databases in real time:

    * **Sanctions Lists** — Government and international bodies (OFAC, EU, UN, etc.)
    * **Politically Exposed Persons (PEPs)** — Individuals with prominent public functions
    * **Criminal Records** — Global and local criminal databases
    * **Adverse Media** — News articles and reports on financial crimes
    * **Custom Watchlists** — Configurable based on your requirements
  </Step>

  <Step title="Match Score Calculation" icon="calculator">
    For each potential match, the system calculates an **identity confidence score** — how likely it is the same person.

    | Factor                  | Default Weight | Description                              |
    | ----------------------- | :------------: | ---------------------------------------- |
    | **Name similarity**     |       60%      | Fuzzy matching accounting for variations |
    | **Date of Birth**       |       25%      | Exact or partial DOB comparison          |
    | **Country/Nationality** |       15%      | Country of origin comparison             |

    * Match Score **below threshold** (default: 93) → classified as **False Positive**
    * Match Score **at or above threshold** → classified as **Unreviewed** (possible match)
    * **Golden Key**: Document number match can override to 100% for definitive identification
  </Step>

  <Step title="Risk Score Calculation" icon="triangle-exclamation">
    For non-false-positive matches, the system calculates the entity's **risk level**:

    | Factor               | Weight | Description                                  |
    | -------------------- | :----: | -------------------------------------------- |
    | **Category**         |   50%  | PEP level, sanctions type, criminal severity |
    | **Country risk**     |   30%  | Risk rating of associated countries          |
    | **Criminal records** |   20%  | Presence and severity of criminal history    |
  </Step>

  <Step title="Final Status Determination" icon="gavel">
    Based on the **highest risk score** among all non-false-positive matches:

    |        Risk Score       | Status        | Action                               |
    | :---------------------: | ------------- | ------------------------------------ |
    | Below approve threshold | **Approved**  | Auto-cleared, no credible risk       |
    |    Between thresholds   | **In Review** | Flagged for manual compliance review |
    |  Above review threshold | **Declined**  | High risk, automatic rejection       |

    If **all** matches are false positives, the result is **Approved** (no credible matches found).
  </Step>

  <Step title="Result Generation" icon="file-export">
    A detailed report is generated with full transparency:

    * Each match's **match score** and **risk score** with breakdowns
    * Match classification (False Positive vs. Unreviewed vs. Confirmed)
    * Source database and category details for every hit
    * Results delivered via **API response**, **webhook**, or **Business Console**
    * Automatic decisioning based on your configured risk score thresholds
  </Step>
</Steps>

## AML Hit Data Reference

Each AML hit returned in the API response contains detailed information about the matched entity. Below are the key fields and their possible values.

### Dataset Categories

The `datasets` field on each hit indicates which compliance database categories the entity was found in. Possible values:

| Value                                 | Description                                                     |
| ------------------------------------- | --------------------------------------------------------------- |
| `PEP`                                 | Politically Exposed Person (general)                            |
| `PEP Level 1`                         | Heads of state, senior politicians, supreme court judges        |
| `PEP Level 2`                         | Members of parliament, ambassadors, military leaders            |
| `PEP Level 3`                         | Local government officials, mid-level civil servants            |
| `PEP Level 4`                         | RCA (Relatives and Close Associates) of PEP individuals         |
| `Sanctions`                           | International and national sanctions lists (OFAC, EU, UN, etc.) |
| `Adverse Media`                       | Negative news articles and reports related to financial crime   |
| `Warnings and Regulatory Enforcement` | Regulatory warnings, enforcement actions, and compliance alerts |
| `Fitness and Probity`                 | Fitness and probity registers from financial regulators         |
| `SIP`                                 | Special Interest Person lists                                   |
| `SIE`                                 | Special Interest Entity lists                                   |
| `Insolvency`                          | Insolvency and bankruptcy registers                             |

### Sanction Matches

The `sanction_matches` array contains details for each sanction list where the entity was found. Key fields:

| Field                   | Type       | Description                                                                                                                                                                                                                                                                       |
| ----------------------- | ---------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_name`             | `string[]` | Name(s) of the sanction list(s)                                                                                                                                                                                                                                                   |
| `matched_name`          | `string`   | Name as it appears in the sanction list                                                                                                                                                                                                                                           |
| `description`           | `string`   | Description of the sanction entry                                                                                                                                                                                                                                                 |
| `reason`                | `string`   | Free-text reason why the entity was sanctioned. This is not an enum — values come directly from the sanctioning authority and describe the specific grounds for the listing (e.g., "Executive Order 13224 (Terrorism)", "Support for actions undermining Ukraine's sovereignty"). |
| `legal_basis`           | `string[]` | Legal basis for the sanction                                                                                                                                                                                                                                                      |
| `sanction_program`      | `string[]` | Sanction program(s) the entity is listed under                                                                                                                                                                                                                                    |
| `sanctioning_authority` | `string[]` | Authority that imposed the sanction                                                                                                                                                                                                                                               |
| `listed_on`             | `string[]` | Date(s) when the entity was listed                                                                                                                                                                                                                                                |
| `source_url`            | `string`   | URL to the source                                                                                                                                                                                                                                                                 |

### Warning Matches

The `warning_matches` array contains details for matches from warning, regulatory enforcement, and related lists. The `additional_data` field may include a `data.case_details` array with structured case information.

#### Warning Case Types

The `case_type` field within `additional_data.data.case_details[]` describes the nature of the warning case. Known values:

| Value                       | Description                                  |
| --------------------------- | -------------------------------------------- |
| `Accusation`                | Formal accusation or charge                  |
| `Arrest`                    | Arrest record                                |
| `Bribery`                   | Bribery-related case                         |
| `Criminal`                  | General criminal case                        |
| `Fraud`                     | Fraud-related case                           |
| `Illegal Fundraising`       | Illegal fundraising activity                 |
| `Non-conviction Terror`     | Terrorism-related listing without conviction |
| `Proclaimed Offender`       | Officially proclaimed offender               |
| `Regulatory Enforcement`    | Regulatory enforcement action                |
| `Terrorism`                 | Terrorism-related case                       |
| `Terrorism-related`         | Related to terrorism activities              |
| `Terrorism-related listing` | Listed in connection with terrorism          |


# AML screening report
Source: https://docs.didit.me/core-technology/aml-screening/report-aml-screening

Parse AML screening responses: hits, sanctions, PEP, adverse media, risk scores, match scores, screened data, and ongoing-monitoring fields.

## Overview

AML screening cross-references the verified subject's identity against global sanctions, PEP, watchlist, and adverse-media datasets. Each hit returns the matched entity, the dataset(s) that produced the match, two scores — `match_score` (identity confidence) and `risk_score` (entity risk) — and a structured breakdown by source (`pep_matches[]`, `sanction_matches[]`, `warning_matches[]`, `adverse_media_matches[]`). The aggregate `score` is the highest `risk_score` among hits that are not marked `False Positive`.

The same shape is returned by AML screening on user (KYC) sessions, business (KYB) sessions, and the standalone AML API.

<Frame>
  <img alt="Didit AML screening report screenshot with sanctions, PEP and adverse media hits" />
</Frame>

## Where it appears in API responses

On the session decision endpoint, AML screening is returned as the plural array **`aml_screenings[]`**. Every entry corresponds to one AML execution in the workflow (an AML check that runs twice produces two entries with different `node_id` values).

```text theme={null}
GET /v3/session/{sessionId}/decision/
  ──▶ { "aml_screenings": [ { node_id, status, total_hits, hits, … }, … ] }
```

Standalone AML and business sessions return the same per-record shape. The fields below mirror the canonical schema on the [Data models](/reference/data-models#aml-screening) page.

## Schema

See [AML Screening in the Data Models reference](/reference/data-models#aml-screening) for the canonical schema. Top-level fields:

| Field                               | Type                                                      | Notes                                                                                                                                                                                                   |
| ----------------------------------- | --------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`                            | `Not Finished` \| `Approved` \| `Declined` \| `In Review` | Feature-level status (`FeatureStatusChoices`). Drives workflow rules and the manual-review screen.                                                                                                      |
| `total_hits`                        | integer                                                   | Count of entries in `hits[]`. `0` when no matches.                                                                                                                                                      |
| `entity_type`                       | `person` \| `company`                                     | The kind of subject screened. Companies and individuals use different match logic.                                                                                                                      |
| `score`                             | float (0-100) \| null                                     | Aggregate AML risk score — the highest `risk_score` among hits not marked `False Positive`. `0` when there are no possible matches; `null` until screening has run.                                     |
| `hits`                              | `Hit[]`                                                   | One entry per matched record, **including** hits auto-classified as `False Positive` (they stay listed but are excluded from the aggregate `score`). See per-hit fields below.                          |
| `screened_data`                     | object                                                    | The exact values Didit sent to screening: `full_name`, `date_of_birth`, `nationality` (ISO 3166-1 alpha-2), `document_number`. Useful for explaining a hit to a reviewer or auditing what was searched. |
| `is_ongoing_monitoring_enabled`     | boolean                                                   | `true` once you enable continuous monitoring for the session.                                                                                                                                           |
| `next_ongoing_monitoring_bill_date` | string \| null                                            | `YYYY-MM-DD` of the next annual renewal (`last_aml_bill_date` + 365 days). `null` until monitoring is enabled.                                                                                          |
| `warnings`                          | `Warning[]`                                               | AML-specific warning tags. See [AML warnings](/core-technology/aml-screening/warnings-aml-screening).                                                                                                   |
| `node_id`                           | string \| null                                            | Identifies the workflow graph node that produced this AML execution on `/v3/` session responses. The standalone AML API response omits it.                                                              |

### Per-hit fields

Every entry in `hits[]` has the following fields (subset shown). Match-source arrays — `pep_matches[]`, `sanction_matches[]`, `warning_matches[]`, `adverse_media_matches[]` — are populated only for the dataset(s) the hit belongs to.

| Field                      | Type                                                                    | Notes                                                                                                                                                                                                                                                                                   |
| -------------------------- | ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `id`                       | string                                                                  | Stable hit identifier. Use it as `hit_id` when updating `review_status` via the AML hit-status endpoint.                                                                                                                                                                                |
| `caption`                  | string                                                                  | The entity's primary name as stored in the dataset.                                                                                                                                                                                                                                     |
| `datasets`                 | string\[]                                                               | E.g. `["PEP"]`, `["PEP Level 1"]`, sanctions list names.                                                                                                                                                                                                                                |
| `match_score`              | number (0-100)                                                          | Identity confidence — how likely the hit is the same person. Hits below `aml_match_score_threshold` (default `93`) start as `False Positive`; at or above it they start as `Unreviewed`. See [AML match score](/core-technology/aml-screening/aml-match-score).                         |
| `risk_score`               | number (0-100)                                                          | Entity risk — how risky the matched entity is. The highest `risk_score` among non-`False Positive` hits becomes the top-level `score`. See [AML risk score](/core-technology/aml-screening/aml-risk-score).                                                                             |
| `score`                    | number (0-1)                                                            | **Deprecated** weighted match score. Use `match_score` instead.                                                                                                                                                                                                                         |
| `match`                    | boolean \| null                                                         | Legacy exact-match flag. Prefer `match_score` + `review_status`.                                                                                                                                                                                                                        |
| `target`                   | boolean \| null                                                         | Whether the entity is the direct target of the listing.                                                                                                                                                                                                                                 |
| `review_status`            | `Unreviewed` \| `Confirmed Match` \| `False Positive` \| `Inconclusive` | Initial value is derived from `match_score` vs `aml_match_score_threshold`. Mutable via the AML hit-status endpoint; updating it fires a `data.updated` webhook but does **not** automatically recompute the feature `status` — use the AML status endpoint or console review for that. |
| `score_breakdown`          | object                                                                  | How `match_score` was calculated: name/DOB/country scores, weights, contributions, and the document-number "golden key" effect (`MATCH` overrides to 100, `NEUTRAL` keeps the base score, `HARD_MISMATCH` penalises).                                                                   |
| `properties`               | object                                                                  | Raw dataset attributes (names, aliases, birth dates, citizenship, …). Useful for adjudication.                                                                                                                                                                                          |
| `url`                      | string \| null                                                          | Source URL for the matched entity, when available.                                                                                                                                                                                                                                      |
| `rca_name`                 | string \| null                                                          | When the hit is a relative/close associate (RCA), the name of the related person through which it matched.                                                                                                                                                                              |
| `pep_matches[]`            | object\[]                                                               | PEP positions, publishers, dates of birth, and education for the hit.                                                                                                                                                                                                                   |
| `sanction_matches[]`       | object\[]                                                               | Sanction list name, program, sanctioning authority, listed-on date, and source URLs.                                                                                                                                                                                                    |
| `warning_matches[]`        | object\[]                                                               | Generic watchlist or enforcement-action records.                                                                                                                                                                                                                                        |
| `adverse_media_matches[]`  | object\[]                                                               | Article-level adverse media: headline, summary, sentiment, source URL, publication date, keywords.                                                                                                                                                                                      |
| `adverse_media_details`    | object \| null                                                          | Aggregate adverse-media sentiment and keyword counts across the hit.                                                                                                                                                                                                                    |
| `risk_view`                | object                                                                  | Category-, country-, and crime-weighted risk breakdown for the hit (`risk_level`, `risk_scores`, `weightage`).                                                                                                                                                                          |
| `linked_entities[]`        | object\[]                                                               | Related entities the dataset connects to the hit (e.g., family or business associates).                                                                                                                                                                                                 |
| `first_seen` / `last_seen` | string \| null                                                          | When the dataset first/last observed this entry.                                                                                                                                                                                                                                        |
| `additional_information`   | object                                                                  | Free-form extra data from the dataset provider.                                                                                                                                                                                                                                         |

<Note>
  Hits classified as `False Positive` (because `match_score` fell below the match-score threshold, or because a reviewer marked them) remain in `hits[]` for auditability. They are excluded only from the aggregate `score` calculation.
</Note>

### Ongoing monitoring

When `is_ongoing_monitoring_enabled` is `true`, Didit re-screens the subject continuously and re-emits the AML report any time a hit is added, removed, or changes. Re-screens that change the AML status fire a `status.updated` webhook; re-screens that only change hit data fire `data.updated`. The monitoring window runs from the `last_aml_bill_date` for 365 days; `next_ongoing_monitoring_bill_date` exposes when the next annual renewal hits. See [Continuous AML monitoring](/core-technology/aml-screening/continuous-monitoring-aml-screening) for the full lifecycle.

## Status values

| Value          | Meaning                                                                                                                                                    |
| -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Not Finished` | AML has not yet executed for this session/node.                                                                                                            |
| `Approved`     | The aggregate score is at or below the approve threshold (default `80`) — including when there are no hits or every hit is a `False Positive` (score `0`). |
| `In Review`    | Aggregate score is above the approve threshold (and at or below the review threshold), or `COULD_NOT_PERFORM_AML_SCREENING` fired.                         |
| `Declined`     | Aggregate score is above the review threshold (default `100`, so auto-decline only happens once you lower it), or the status was set manually.             |

The thresholds are configurable per workflow node — see [AML risk score](/core-technology/aml-screening/aml-risk-score). Custom status rules combine with the derived status using `Declined` > `In Review` > `Approved` precedence; reviewers can also override the AML status from the console or the AML status endpoint.

## Examples

### Approved — no hits

```json theme={null}
{
  "aml_screenings": [
    {
      "node_id": "aml-1",
      "status": "Approved",
      "total_hits": 0,
      "entity_type": "person",
      "score": 0,
      "hits": [],
      "screened_data": {
        "full_name": "Jane Doe",
        "nationality": "US",
        "date_of_birth": "1990-06-12",
        "document_number": "P9876543"
      },
      "is_ongoing_monitoring_enabled": false,
      "next_ongoing_monitoring_bill_date": null,
      "warnings": []
    }
  ]
}
```

### In Review — PEP + adverse media hit

All names, URLs, and articles below are fictional.

```json theme={null}
{
  "aml_screenings": [
    {
      "node_id": "aml-1",
      "status": "In Review",
      "total_hits": 1,
      "entity_type": "person",
      "score": 85,
      "hits": [
        {
          "id": "cPtTGRKkyddAcAC4xgsLCm",
          "caption": "John Q. Exampleton",
          "datasets": ["PEP"],
          "match_score": 96,
          "risk_score": 85,
          "score": 0.97,
          "match": false,
          "target": null,
          "review_status": "Unreviewed",
          "properties": {
            "name": ["John Q. Exampleton"],
            "alias": ["Johnny Example"],
            "birthDate": ["1974"],
            "birthPlace": ["Springfield"]
          },
          "score_breakdown": {
            "name_score": 95,
            "name_weight": 60,
            "name_weight_normalized": 70.59,
            "name_contribution": 67.06,
            "dob_score": 100,
            "dob_weight": 25,
            "dob_weight_normalized": 29.41,
            "dob_contribution": 29.41,
            "country_score": 0,
            "country_weight": 15,
            "country_weight_normalized": 0,
            "country_contribution": 0,
            "document_number_match_type": "NEUTRAL",
            "document_number_effect": "No document number provided for screening",
            "total_score": 96
          },
          "pep_matches": [
            {
              "list_name": "Example PEP Registry",
              "publisher": "Example Registry",
              "matched_name": "John Q. Exampleton",
              "pep_position": "Regional council member",
              "date_of_birth": "1974-01-01",
              "place_of_birth": "Springfield",
              "source_url": "https://example.org/registry/entities/Q0000001"
            }
          ],
          "sanction_matches": [],
          "warning_matches": [],
          "adverse_media_matches": [
            {
              "country": "freedonia",
              "headline": "Court opens inquiry into council hiring irregularities",
              "summary": "John Q. Exampleton is named in a legal investigation regarding irregularities in public hiring.",
              "sentiment": "moderately negative",
              "sentiment_score": -2,
              "source_url": "https://example-news.org/articles/12345",
              "publication_date": "2025-06-09T10:19:10",
              "adverse_keywords": ["fraud", "irregularities"]
            }
          ],
          "adverse_media_details": {
            "sentiment": "Moderately Negative",
            "sentiment_score": -2,
            "entity_type": "person",
            "adverse_keywords": { "fraud": 3, "corruption": 2 }
          },
          "risk_view": {
            "categories": { "score": 100.0, "weightage": 50, "risk_level": "High", "risk_scores": { "PEP": 100.0 } },
            "countries":  { "score": 0.0,   "weightage": 30, "risk_level": "Low",  "risk_scores": {} },
            "crimes":     { "score": 0.0,   "weightage": 20, "risk_level": "Low",  "risk_scores": {} },
            "custom_list": {}
          },
          "linked_entities": [
            { "name": ["Mary Exampleton"], "relation": [], "details": [], "active": [], "status": [] }
          ],
          "first_seen": "2025-01-18T00:00:00",
          "last_seen": "2025-06-13T00:00:00"
        }
      ],
      "screened_data": {
        "full_name": "John Q. Exampleton",
        "nationality": "US",
        "date_of_birth": "1974-01-01",
        "document_number": null
      },
      "is_ongoing_monitoring_enabled": true,
      "next_ongoing_monitoring_bill_date": "2027-05-17",
      "warnings": [
        {
          "feature": "AML",
          "risk": "POSSIBLE_MATCH_FOUND",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Possible match found in AML screening",
          "long_description": "The Anti-Money Laundering (AML) screening process identified potential matches with watchlists or high-risk databases, requiring further review.",
          "node_id": "aml-1"
        }
      ]
    }
  ]
}
```

## Related

* [AML warnings](/core-technology/aml-screening/warnings-aml-screening) — every warning code AML can emit
* [AML risk score](/core-technology/aml-screening/aml-risk-score) and [AML match score](/core-technology/aml-screening/aml-match-score) — how the two scores are calculated
* [Continuous AML monitoring](/core-technology/aml-screening/continuous-monitoring-aml-screening) — enabling and consuming monitoring events
* [Watchlist database](/core-technology/aml-screening/watchlist-database-aml-screening) — datasets covered
* [Data models — AML screening](/reference/data-models#aml-screening) — canonical schema
* [Webhooks](/integration/webhooks) — `status.updated` fires when AML changes the session status; hit review-status changes and monitoring data refreshes fire `data.updated`


# AML screening warnings
Source: https://docs.didit.me/core-technology/aml-screening/warnings-aml-screening

Understand AML warning codes: POSSIBLE_MATCH_FOUND and COULD_NOT_PERFORM_AML_SCREENING. Configure thresholds and re-run behavior when KYC data is missing.

## Overview

AML screening emits a small set of warning tags on the `warnings[]` array of each entry in `aml_screenings[]`. The two tags below are the **only** AML warnings Didit produces — everything else you see on a hit is encoded in the hit's own fields (`risk_view`, `match_score`, `risk_score`, `sanction_matches[]`, …) rather than as a warning. Both workflow sessions and the standalone AML API emit `POSSIBLE_MATCH_FOUND` the same way.

The status returned on the AML record (`Approved`, `In Review`, `Declined`) is derived from the aggregate `score` and your thresholds — the warnings tag the same conditions so you can react to them programmatically. See [AML risk score](/core-technology/aml-screening/aml-risk-score) for how thresholds map to status.

## Warnings produced

| Risk                              | Cause                                                                                                                                                                                                                                      | `log_type`                                                                                                    | Affects status                                                                                               | Recommended remediation                                                                                                                                                                                                                                                               |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `POSSIBLE_MATCH_FOUND`            | The aggregate `score` is non-zero and above the `aml_score_approve_threshold` (default `80`) — at least one possible-match hit crosses your risk band. (The standalone AML API also emits it when the score exactly equals the threshold.) | `warning`; escalates to `error` when the score also exceeds the `aml_score_review_threshold` (default `100`). | `In Review` when the score is above the approve threshold; `Declined` when it is above the review threshold. | Review each hit in `hits[]`. Use the AML hit-status endpoint to mark hits `Confirmed Match`, `False Positive`, or `Inconclusive`. Hit updates fire a `data.updated` webhook but do not recompute the AML status — set the final status via the AML status endpoint or console review. |
| `COULD_NOT_PERFORM_AML_SCREENING` | The KYC record is missing one or more of `full_name`, `date_of_birth`, or `issuing_state`. No billable screening call is made.                                                                                                             | `warning`                                                                                                     | Forces `In Review`.                                                                                          | Populate the missing fields on the KYC record. AML re-runs automatically once all three are present — the stale warning log is removed and no manual retrigger is needed.                                                                                                             |

Warnings are stored with `feature: "AML"` and follow the standard [warning object](/reference/data-models#warning-object) shape.

## Configurable settings

Per-workflow-node AML controls (also accepted as options on the standalone AML API):

* **`aml_score_approve_threshold`** — default `80`. A non-zero score above it produces `POSSIBLE_MATCH_FOUND` and routes the AML check to `In Review`. Scores at or below it do **not** produce the warning in session workflows, regardless of hit count.
* **`aml_score_review_threshold`** — default `100`. A score above it auto-declines the AML check (with the default of `100` this never triggers until you lower it).
* **`aml_match_score_threshold`** — default `93`. Per-hit classification: hits with `match_score` below it start as `False Positive` and are excluded from the aggregate score; at or above it they start as `Unreviewed`.
* **Match-score weights** — `aml_name_weight` / `aml_dob_weight` / `aml_country_weight`, defaults `60` / `25` / `15` (must sum to 100). See [AML match score](/core-technology/aml-screening/aml-match-score).
* **Ongoing monitoring** — when enabled, AML re-screens the subject as datasets change and re-emits the report plus a `status.updated` (status changed) or `data.updated` (hits changed) webhook.

<Note>
  When `COULD_NOT_PERFORM_AML_SCREENING` fires, the AML check sits at `In Review` until the missing identity fields are supplied. Once Didit has the full name, date of birth, and issuing state, AML re-runs automatically and the warning clears — there is no manual retrigger.
</Note>

## Examples

### `POSSIBLE_MATCH_FOUND` (score above approve threshold)

```json theme={null}
{
  "warnings": [
    {
      "feature": "AML",
      "risk": "POSSIBLE_MATCH_FOUND",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "Possible match found in AML screening",
      "long_description": "The Anti-Money Laundering (AML) screening process identified potential matches with watchlists or high-risk databases, requiring further review.",
      "node_id": "aml-1"
    }
  ]
}
```

### `COULD_NOT_PERFORM_AML_SCREENING` (missing KYC fields)

```json theme={null}
{
  "warnings": [
    {
      "feature": "AML",
      "risk": "COULD_NOT_PERFORM_AML_SCREENING",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "Could not retrieve data from KYC for performing AML Screening",
      "long_description": "The system encountered issues accessing or processing Know Your Customer (KYC) data necessary for conducting the Anti-Money Laundering (AML) screening. please fill the KYC full name, birth date, issuing state and document number to automatically proceed with AML screening.",
      "node_id": "aml-1"
    }
  ]
}
```

## Related

* [AML report](/core-technology/aml-screening/report-aml-screening) — full response shape, hit fields, status semantics
* [AML risk score](/core-technology/aml-screening/aml-risk-score) — how the aggregate score is calculated
* [AML match score](/core-technology/aml-screening/aml-match-score) — per-hit confidence
* [Continuous AML monitoring](/core-technology/aml-screening/continuous-monitoring-aml-screening) — monitoring lifecycle
* [Data models — AML screening](/reference/data-models#aml-screening) — canonical schema, including the [Warning object](/reference/data-models#warning-object)

### Warning types

<WarningTypes />


# AML Watchlist Coverage
Source: https://docs.didit.me/core-technology/aml-screening/watchlist-database-aml-screening

Explore Didit's 1,300+ AML databases: OFAC, UN, EU sanctions, PEPs, adverse media, law enforcement, and terrorism-financing sources updated daily.

Didit's AML screening process leverages a comprehensive and up-to-date +1300 databases of global watchlists. Our dataset includes sanctions lists, law enforcement wanted lists, politically exposed persons (PEPs) lists, and other regulatory and compliance-related data sources from various countries and international organizations.

### 1. **Watchlist & Sanctions Screening**

We maintain up‑to‑date coverage of all sanctions, watchlists, law‑enforcement, and regulatory databases, including:

* **Global sanctions regimes** (e.g., OFAC SDN, UN, EU, HM Treasury)
* **Government enforcement lists** (e.g., FBI/Interpol Most Wanted, exclusion/debarment lists)
* **Regulatory enforcement and financial crime** (e.g., fraud warnings, disciplinary actions)

### 2. **Politically Exposed Persons (PEPs), RCAs & State‑Owned Entities**

We screen for:

* **PEPs** across various tiers (heads of state, officials, etc.)
* **Relatives and Close Associates (RCAs)**
* **Entities with political ties** (e.g., state-owned or state-invested businesses)

### 3. **Adverse Media & Negative News Screening**

We analyze global news sources (50k+), tagging records across 415+ risk categories for structured sentiment analysis, including allegations, investigations, convictions, and reputational issues

### 4. **Crime & Financial Crime Categories**

Our coverage includes individuals/entities associated with:

* **Fraud, misappropriation, corruption, tax evasion**, and other financial crimes
* **Drug‑trafficking and narcotics offenses**
* **Bribery and anti‑corruption**

### 5. **Terrorism & Insurgency**

We detect connections to terrorist activity, including support networks, financiers, and operational personnel—profiling these cases both pre- and post-official designation

### 6. **Geopolitical & Country Risk**

Our system flags activities linked to:

* **High-risk countries** (e.g., FATF grey‑ or black‑listed, embargoed nations)
* **Entities like shell banks or sanctioned state financial institutions**

### 7. **Regulatory, Judicial & Enforcement Risk**

Coverage extends to:

* **Persons/entities subject to court rulings** (e.g., convicted, indicted)
* **Regulatory actions** (e.g., fines, debarments)
* **Asset seizures and enforcement measures** (\[uabonline.org]\[5], \[moodys.com]\[8])

### 8. **Special‑Interest & Corporate Entities**

We cover a wide range of high-risk corporate structures, including:

* **Shell banks, state-backed financial entities**, and bogus institutions
* **Corporates under sanction or regulatory scrutiny**

***

### Granular Taxonomy & Structured Metadata

Every match is enriched with structured metadata to aid remediation and risk prioritization:

* **Categorization**: primary categories and subcategories
* **Identifiers**: PEP status, sanctions type, conviction status, etc.
* **Other fields**: aliases, birth date, nationality, position/title, etc.

This ensures easy filtering and supports detailed differential risk workflows.

***

## Summary Table

| **Risk Category**                     | **Key Coverage**                                                           |
| ------------------------------------- | -------------------------------------------------------------------------- |
| **Sanctions & Watchlists**            | OFAC, UN, HM Treasury, EU, Interpol, FBI, exclusion/debarment, enforcement |
| **PEPs & State-Associated**           | Government officials, RCAs, state-owned/invested entities                  |
| **Adverse Media**                     | 415+ risk tags, sentiment, investigations, convictions, negative media     |
| **Financial Crime**                   | Fraud, money-laundering, corruption, tax evasion                           |
| **Narcotics**                         | Drug trafficking and narcotics-related offenses                            |
| **Terrorism/CFT**                     | Terror financing, insurgent networks, terrorist organization support       |
| **Geopolitical Risk**                 | High-risk nations, shell banks, sanctioned financial institutions          |
| **Regulatory & Judicial Enforcement** | Fines, asset seizures, convictions, judicial rulings                       |
| **Corporate Risk**                    | Blacklisted entities, corporate sanctions, debarments                      |

***

### PEPs (Levels 1–4), SIPs, and SIEs

Below is a table of the PEPs (Levels 1–4), SIPs, and SIEs included in our AML screening process:

| Publisher                                                                                                           | Country                               | Category    |
| ------------------------------------------------------------------------------------------------------------------- | ------------------------------------- | ----------- |
| House of the People (Wolesi Jirga)                                                                                  | 🇦🇫 Afghanistan                      | Pep Level 1 |
| Afghan Ministry of Foreign Affairs                                                                                  | 🇦🇫 Afghanistan                      | Pep Level 2 |
| House of Elders (Meshrano Jirga)                                                                                    | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Free and Fair Election Foundation of Afghanistan                                                                    | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Attorney General's Office                                                                                           | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Afghanistan National Army                                                                                           | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Ministry of Rural Rehabilitation and Development                                                                    | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Ministry of Justice                                                                                                 | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Ministry of Public Health                                                                                           | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Ministry of Agriculture                                                                                             | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Ministry of Education                                                                                               | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Ministry of Mines and Petroleum                                                                                     | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Afghanistan Independent Election Commission                                                                         | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Afghanistan National Police                                                                                         | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Central Bank of Afghanistan (Da Afghanistan Bank)                                                                   | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Ministry of Urban Development and Housing                                                                           | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Ministry of Energy and Water                                                                                        | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Ministry of Commerce and Industry                                                                                   | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Ministry of Finance                                                                                                 | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Ministry of Higher Education                                                                                        | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Ministry of Women's Affairs                                                                                         | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Ministry of Haj and Religious Affairs                                                                               | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Ministry of Border and Tribal Affairs                                                                               | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Ministry of Religious Affairs and Wakfs                                                                             | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Ministry of Urban Planning                                                                                          | 🇦🇫 Afghanistan                      | Pep Level 2 |
| Afghan United Bank                                                                                                  | 🇦🇫 Afghanistan                      | SIP         |
| Social Democracy Party                                                                                              | 🇦🇱 Albania                          | Pep Level 1 |
| Energy Regulatory Authority                                                                                         | 🇦🇱 Albania                          | Pep Level 3 |
| Agjencia Kombetare e Mjedisit                                                                                       | 🇦🇱 Albania                          | SIE         |
| Montagne & Paesi                                                                                                    | 🇦🇱 Albania                          | SIP         |
| Ministry of National Defense Naval Forces                                                                           | 🇩🇿 Algeria                          | Pep Level 1 |
| Algerian Central Bank (Bank of Algeria)                                                                             | 🇩🇿 Algeria                          | Pep Level 2 |
| Ministry of Energy                                                                                                  | 🇩🇿 Algeria                          | Pep Level 2 |
| Supreme Court                                                                                                       | 🇩🇿 Algeria                          | Pep Level 2 |
| Algerian Centre for Research in Applied Economics for Development                                                   | 🇩🇿 Algeria                          | Pep Level 3 |
| Tizi Ouzou Province                                                                                                 | 🇩🇿 Algeria                          | Pep Level 4 |
| American Samoa Bar Association                                                                                      | 🇦🇸 American Samoa                   | Pep Level 1 |
| Government of Andorra                                                                                               | 🇦🇩 Andorra                          | Pep Level 1 |
| SWITZERLAND - FINMA-DU - Swiss Financial Market Supervisory Authority-Enforcement                                   | 🇦🇩 Andorra                          | SIP         |
| Constitutional Court of Angola                                                                                      | 🇦🇴 Angola                           | Pep Level 1 |
| British West Indies Guard Ship                                                                                      | 🇦🇴 Angola                           | Pep Level 2 |
| Atlético Petróleos de Luanda (Petro Atlético)                                                                       | 🇦🇴 Angola                           | Pep Level 3 |
| National Bank of Angola                                                                                             | 🇦🇴 Angola                           | Pep Level 3 |
| Movement for the Liberation of Angola (MPLA)                                                                        | 🇦🇴 Angola                           | Pep Level 3 |
| Banco Nacional de Angola                                                                                            | 🇦🇴 Angola                           | SIE         |
| Anguilla Customs and Excise Department                                                                              | 🇦🇮 Anguilla                         | Pep Level 1 |
| Diplomatic Academy                                                                                                  | 🇦🇮 Anguilla                         | Pep Level 2 |
| Anguilla Financial Services Commission                                                                              | 🇦🇮 Anguilla                         | Pep Level 3 |
| Government of Antigua and Barbuda                                                                                   | 🇦🇬 Antigua and Barbuda              | Pep Level 1 |
| Governor of Córdoba                                                                                                 | 🇦🇬 Antigua and Barbuda              | Pep Level 2 |
| ANTIGUA & BARBUDA - OFFICE OF NATIONAL DRUG & MONEY LAUNDERING CONTROL POLICY - ONDCP                               | 🇦🇬 Antigua and Barbuda              | SIP         |
| Anti-Corruption Bureau (Argentina)                                                                                  | 🇦🇷 Argentina                        | Pep Level 1 |
| National Congress                                                                                                   | 🇦🇷 Argentina                        | Pep Level 2 |
| Armenia Nuclear Regulatory Authority                                                                                | 🇦🇲 Armenia                          | Pep Level 2 |
| ARGENTINA - ARINAES - National Institute Of Associativism And Social Economy                                        | 🇦🇷 Argentina                        | SIE         |
| El Tribuno de Salta 2.0                                                                                             | 🇦🇷 Argentina                        | SIP         |
| Armenian National Congress                                                                                          | 🇦🇲 Armenia                          | Pep Level 1 |
| Ministry of Defence                                                                                                 | 🇦🇲 Armenia                          | Pep Level 2 |
| Ministry of Transportation                                                                                          | 🇦🇲 Armenia                          | Pep Level 2 |
| Ministry of High-Tech Industry                                                                                      | 🇦🇲 Armenia                          | Pep Level 2 |
| Institute of Social Science Research                                                                                | 🇦🇲 Armenia                          | Pep Level 2 |
| Campaign Against Sanctions and Military Intervention in Iran                                                        | 🇦🇲 Armenia                          | SIE         |
| Parliament of Aruba                                                                                                 | 🇦🇼 Aruba                            | Pep Level 1 |
| Department of Climate Change                                                                                        | 🇦🇺 Australia                        | Pep Level 1 |
| Ministry of Justice                                                                                                 | 🇦🇺 Australia                        | Pep Level 2 |
| Civil Aviation Safety Authority (CASA)                                                                              | 🇦🇺 Australia                        | Pep Level 3 |
| AWB Limited (Australian Wheat Board)                                                                                | 🇦🇺 Australia                        | Pep Level 3 |
| AUSTRALIA - ASIC - Securities and Investments Comm                                                                  | 🇦🇺 Australia                        | SIP         |
| Social Democratic Party of Austria (SPÖ)                                                                            | 🇦🇹 Austria                          | Pep Level 1 |
| Ministry of Foreign Affairs                                                                                         | 🇦🇹 Austria                          | Pep Level 2 |
| Ministry of Defense                                                                                                 | 🇦🇹 Austria                          | Pep Level 2 |
| Austria Freedom Party                                                                                               | 🇦🇹 Austria                          | Pep Level 2 |
| Ministry of Labor and Social Development                                                                            | 🇦🇹 Austria                          | Pep Level 2 |
| Radio Prague International                                                                                          | 🇦🇹 Austria                          | SIE         |
| Ministry of Finance of Republic of Azerbaijan                                                                       | 🇦🇿 Azerbaijan                       | Pep Level 1 |
| Azerbaijan National Academy of Sciences (ANAS)                                                                      | 🇦🇿 Azerbaijan                       | Pep Level 3 |
| Azerbaijan Investment Company (AIC)                                                                                 | 🇦🇿 Azerbaijan                       | Pep Level 3 |
| Azerbaijan State News Agency (AZERTAC)                                                                              | 🇦🇿 Azerbaijan                       | Pep Level 3 |
| Supreme Council for Environment                                                                                     | 🇧🇭 Bahrain                          | Pep Level 1 |
| Bahrain Petroleum Company (Bapco)                                                                                   | 🇧🇭 Bahrain                          | Pep Level 2 |
| Bureau of Anti-Corruption (Bangladesh)                                                                              | 🇧🇩 Bangladesh                       | Pep Level 2 |
| Ministry of Textile and Jute                                                                                        | 🇧🇩 Bangladesh                       | Pep Level 1 |
| Ministry of Finance                                                                                                 | 🇧🇩 Bangladesh                       | Pep Level 2 |
| Bureau of Manpower                                                                                                  | 🇧🇩 Bangladesh                       | Pep Level 2 |
| Ministry of Science and Technology                                                                                  | 🇧🇩 Bangladesh                       | Pep Level 2 |
| Bangladesh Bank (Central Bank of Bangladesh)                                                                        | 🇧🇩 Bangladesh                       | Pep Level 2 |
| Ministry of Education                                                                                               | 🇧🇩 Bangladesh                       | Pep Level 2 |
| Ministry of Foreign Affairs                                                                                         | 🇧🇩 Bangladesh                       | Pep Level 2 |
| Union Parishad (local government)                                                                                   | 🇧🇩 Bangladesh                       | Pep Level 2 |
| Office of the President                                                                                             | 🇧🇩 Bangladesh                       | Pep Level 2 |
| Supreme Court                                                                                                       | 🇧🇩 Bangladesh                       | Pep Level 2 |
| Jatiya Sangsad (Parliament of Bangladesh)                                                                           | 🇧🇩 Bangladesh                       | Pep Level 2 |
| Judicial Service Commission                                                                                         | 🇧🇩 Bangladesh                       | Pep Level 2 |
| Bangladesh Road Transport Authority (BRTA)                                                                          | 🇧🇩 Bangladesh                       | Pep Level 2 |
| Anti-Corruption Commission (ACC) Bangladesh                                                                         | 🇧🇩 Bangladesh                       | Pep Level 2 |
| Cabinet of Barbados                                                                                                 | 🇧🇧 Barbados                         | Pep Level 2 |
| Bangladesh Ansar and Village Defence Party                                                                          | 🇧🇩 Bangladesh                       | Pep Level 3 |
| Refugee Relief and Rehabilitation Commission                                                                        | 🇧🇩 Bangladesh                       | Pep Level 3 |
| INTERNATIONAL - AIIB - Asian Infrastructure Investment Bank                                                         | 🇧🇩 Bangladesh                       | SIE         |
| MALAYSIA - MYMACC                                                                                                   | 🇧🇩 Bangladesh                       | SIP         |
| Electoral and Boundaries Commission                                                                                 | 🇧🇧 Barbados                         | Pep Level 1 |
| Ministry of Defense                                                                                                 | 🇧🇧 Barbados                         | Pep Level 2 |
| The Edge Malaysia                                                                                                   | 🇲🇾 Malaysia                         | SIE         |
| Council of the Republic                                                                                             | 🇧🇾 Belarus                          | Pep Level 1 |
| Ministry of Energy                                                                                                  | 🇧🇾 Belarus                          | Pep Level 2 |
| Supreme Court                                                                                                       | 🇧🇾 Belarus                          | Pep Level 2 |
| Council of Ministers                                                                                                | 🇧🇾 Belarus                          | Pep Level 2 |
| Ministry of Foreign Affairs                                                                                         | 🇧🇾 Belarus                          | Pep Level 2 |
| National Bank of Belarus (NBRB)                                                                                     | 🇧🇾 Belarus                          | Pep Level 2 |
| Cabinet of Ministers (Belarus)                                                                                      | 🇧🇾 Belarus                          | Pep Level 2 |
| Ministry of Interior                                                                                                | 🇧🇾 Belarus                          | Pep Level 2 |
| Ministry of Economy                                                                                                 | 🇧🇾 Belarus                          | Pep Level 2 |
| Ministry of Agriculture                                                                                             | 🇧🇾 Belarus                          | Pep Level 2 |
| Ministry of Communications and Informatization                                                                      | 🇧🇾 Belarus                          | Pep Level 2 |
| Ministry of Education                                                                                               | 🇧🇾 Belarus                          | Pep Level 2 |
| Ministry of National Defense                                                                                        | 🇧🇾 Belarus                          | Pep Level 2 |
| Brest City Executive Committee                                                                                      | 🇧🇾 Belarus                          | Pep Level 4 |
| Министерство информации Республики Беларусь                                                                         | 🇧🇾 Belarus                          | SIE         |
| Rights in Russia                                                                                                    | 🇧🇾 Belarus                          | SIP         |
| Federal Public Service Finance                                                                                      | 🇧🇪 Belgium                          | Pep Level 1 |
| Chamber of Representatives                                                                                          | 🇧🇪 Belgium                          | Pep Level 2 |
| Constitutional Court                                                                                                | 🇧🇪 Belgium                          | Pep Level 2 |
| National Bank of Belgium (NBB)                                                                                      | 🇧🇪 Belgium                          | Pep Level 2 |
| Belize Police Department                                                                                            | 🇧🇿 Belize                           | Pep Level 2 |
| Santa Fe Relocation                                                                                                 | 🇧🇪 Belgium                          | SIE         |
| La Province (inferred)                                                                                              | 🇧🇪 Belgium                          | SIP         |
| National Assembly of Belize                                                                                         | 🇧🇿 Belize                           | Pep Level 1 |
| Belize Defence Force                                                                                                | 🇧🇿 Belize                           | Pep Level 2 |
| Benin Electricity Company                                                                                           | 🇧🇯 Benin                            | Pep Level 2 |
| National Electoral Commission of Benin                                                                              | 🇧🇯 Benin                            | Pep Level 1 |
| Royal Civil Service Commission                                                                                      | 🇧🇯 Benin                            | Pep Level 2 |
| Bermuda Parliament - Cabinet                                                                                        | 🇧🇲 Bermuda                          | Pep Level 1 |
| INTERNATIONAL - PPICIJ-WC - International Consortium Of Investigative Journalist Paradise Papers - World-Check Data | 🇧🇲 Bermuda                          | SIE         |
| Bhutan National Legal Institute                                                                                     | 🇧🇹 Bhutan                           | Pep Level 1 |
| Bhutan Chamber of Commerce & Industry                                                                               | 🇧🇹 Bhutan                           | Pep Level 2 |
| Ministry of Trade                                                                                                   | 🇧🇹 Bhutan                           | Pep Level 2 |
| Civil Service Commission                                                                                            | 🇧🇹 Bhutan                           | Pep Level 2 |
| Bhutan Election Commission                                                                                          | 🇧🇹 Bhutan                           | Pep Level 2 |
| Ministry of Foreign Affairs                                                                                         | 🇧🇹 Bhutan                           | Pep Level 2 |
| Ministry of Finance                                                                                                 | 🇧🇹 Bhutan                           | Pep Level 2 |
| Ministry of Home and Cultural Affairs                                                                               | 🇧🇹 Bhutan                           | Pep Level 2 |
| Ministry of Education                                                                                               | 🇧🇹 Bhutan                           | Pep Level 2 |
| Bhutan Broadcasting Service                                                                                         | 🇧🇹 Bhutan                           | Pep Level 2 |
| Ministry of Agriculture and Forests                                                                                 | 🇧🇹 Bhutan                           | Pep Level 2 |
| Ministry of Economic Affairs                                                                                        | 🇧🇹 Bhutan                           | Pep Level 2 |
| Ministry of Information and Communications                                                                          | 🇧🇹 Bhutan                           | Pep Level 2 |
| Judiciary of Bhutan                                                                                                 | 🇧🇹 Bhutan                           | Pep Level 2 |
| Election Commission of Bhutan                                                                                       | 🇧🇹 Bhutan                           | Pep Level 2 |
| Ministry of Economy                                                                                                 | 🇧🇹 Bhutan                           | Pep Level 2 |
| Ministry of Water and Environment                                                                                   | 🇧🇹 Bhutan                           | Pep Level 3 |
| Bhutan National Bank                                                                                                | 🇧🇹 Bhutan                           | Pep Level 3 |
| Ministry of Justice and Institutional Transparency                                                                  | 🇧🇴 Bolivia                          | Pep Level 1 |
| Office of the President                                                                                             | 🇧🇴 Bolivia                          | Pep Level 2 |
| Ministry of Foreign Affairs                                                                                         | 🇧🇴 Bolivia                          | Pep Level 2 |
| Bolivian National Police                                                                                            | 🇧🇴 Bolivia                          | Pep Level 2 |
| Ministry of Defense                                                                                                 | 🇧🇴 Bolivia                          | Pep Level 2 |
| Senate of Bolivia                                                                                                   | 🇧🇴 Bolivia                          | Pep Level 2 |
| Bolivia Central Bank                                                                                                | 🇧🇴 Bolivia                          | Pep Level 2 |
| Ministry of Justice                                                                                                 | 🇧🇴 Bolivia                          | Pep Level 2 |
| Ministry of Culture                                                                                                 | 🇧🇴 Bolivia                          | Pep Level 2 |
| Ministry of Education                                                                                               | 🇧🇴 Bolivia                          | Pep Level 2 |
| Ministry of Finance                                                                                                 | 🇧🇴 Bolivia                          | Pep Level 2 |
| Bolivian Socialist Falange                                                                                          | 🇧🇴 Bolivia                          | Pep Level 3 |
| BOLIVIA - BOASFI - Bolivian Supervisor Authority of The Financial System                                            | 🇧🇴 Bolivia                          | SIE         |
| El Deber Digital                                                                                                    | 🇧🇴 Bolivia                          | SIP         |
| Border Police of Bosnia and Herzegovina                                                                             | 🇧🇦 Bosnia and Herzegovina           | Pep Level 1 |
| Ministry of Defense                                                                                                 | 🇧🇦 Bosnia and Herzegovina           | Pep Level 2 |
| Office of the Prime Minister                                                                                        | 🇧🇦 Bosnia and Herzegovina           | Pep Level 2 |
| Ministry of Foreign Affairs                                                                                         | 🇧🇦 Bosnia and Herzegovina           | Pep Level 2 |
| Botswana National Assembly                                                                                          | 🇧🇼 Botswana                         | Pep Level 2 |
| Digitalni arhiv - Infobiro                                                                                          | 🇧🇦 Bosnia and Herzegovina           | SIE         |
| BOSNIA AND HERZEGOVINA - BAPO - Prosecutor's Office of Bosnia and Herzegovina                                       | 🇧🇦 Bosnia and Herzegovina           | SIP         |
| High Commission of Republic of Botswana in New Delhi                                                                | 🇧🇼 Botswana                         | Pep Level 1 |
| Botswana Defense Force                                                                                              | 🇧🇼 Botswana                         | Pep Level 2 |
| Ministry of Defense                                                                                                 | 🇧🇼 Botswana                         | Pep Level 2 |
| Ministry of Finance                                                                                                 | 🇧🇼 Botswana                         | Pep Level 2 |
| Ministry of Health                                                                                                  | 🇧🇼 Botswana                         | Pep Level 2 |
| Botswana National Sports Commission                                                                                 | 🇧🇼 Botswana                         | Pep Level 3 |
| Botswana Press Agency (BOPA)                                                                                        | 🇧🇼 Botswana                         | Pep Level 3 |
| Civil Police of the State of São Paulo                                                                              | 🇧🇷 Brazil                           | Pep Level 1 |
| Chamber of Deputies                                                                                                 | 🇧🇷 Brazil                           | Pep Level 2 |
| Brazilian Institute of Geography and Statistics (IBGE)                                                              | 🇧🇷 Brazil                           | Pep Level 2 |
| Ministry of Energy                                                                                                  | 🇧🇷 Brazil                           | Pep Level 2 |
| Brazilian Federal Police                                                                                            | 🇧🇷 Brazil                           | Pep Level 2 |
| Supreme Federal Court                                                                                               | 🇧🇷 Brazil                           | Pep Level 2 |
| Superior Court of Justice                                                                                           | 🇧🇷 Brazil                           | Pep Level 2 |
| Court of Accounts (Tribunal de Contas da União)                                                                     | 🇧🇷 Brazil                           | Pep Level 2 |
| Deputy Prime Minister for Judicial Reforms                                                                          | 🇧🇷 Brazil                           | Pep Level 2 |
| Câmara de Comercialização de Energia Elétrica                                                                       | 🇧🇷 Brazil                           | Pep Level 3 |
| BRAZIL - BRCNEP - National Registry of Punished Companies                                                           | 🇧🇷 Brazil                           | SIE         |
| VGN - Notícias em MT com credibilidade                                                                              | 🇧🇷 Brazil                           | SIP         |
| BVI Trade Commission                                                                                                | 🇻🇬 British Virgin Islands           | Pep Level 1 |
| Department of Registrar of Companies and Official Receiver (DRCOR)                                                  | 🇻🇬 British Virgin Islands           | SIE         |
| VIRGIN ISLANDS (BRITISH) - BVIFSC- Financial Services Comm. - Advisory Warnings                                     | 🇻🇬 British Virgin Islands           | SIP         |
| National Department of Justice                                                                                      | 🇧🇳 Brunei                           | Pep Level 1 |
| JERSEY - JFSC - Financial Services Comm.                                                                            | 🇧🇳 Brunei                           | SIE         |
| Audit Chamber of the Republic of Bulgaria                                                                           | 🇧🇬 Bulgaria                         | Pep Level 1 |
| Ministry of Defense                                                                                                 | 🇧🇬 Bulgaria                         | Pep Level 2 |
| Ministry of Public Service                                                                                          | 🇧🇬 Bulgaria                         | Pep Level 2 |
| BULGARIA - BGCPC - Commission for Protection of Competition                                                         | 🇧🇬 Bulgaria                         | SIE         |
| Bulgarian Persons of Interest                                                                                       | 🇧🇬 Bulgaria                         | SIP         |
| Ministry of Economy                                                                                                 | 🇧🇫 Burkina Faso                     | Pep Level 1 |
| Burundi Senate                                                                                                      | 🇧🇮 Burundi                          | Pep Level 2 |
| Senatorial Institution of The Republic of Burundi                                                                   | 🇧🇮 Burundi                          | Pep Level 1 |
| Ministry of Finance                                                                                                 | 🇧🇮 Burundi                          | Pep Level 2 |
| House of Representatives                                                                                            | 🇨🇮 Côte d'Ivoire                    | Pep Level 1 |
| Council of Ministers                                                                                                | 🇨🇻 Cabo Verde                       | Pep Level 2 |
| Minister of Economy and Finance                                                                                     | 🇰🇭 Cambodia                         | Pep Level 1 |
| National Bank of Cambodia                                                                                           | 🇰🇭 Cambodia                         | Pep Level 2 |
| Cambodia National Assembly                                                                                          | 🇰🇭 Cambodia                         | Pep Level 2 |
| Cambodia Senate                                                                                                     | 🇰🇭 Cambodia                         | Pep Level 2 |
| Cambodian People's Party                                                                                            | 🇰🇭 Cambodia                         | Pep Level 2 |
| Cambodia National Rescue Party                                                                                      | 🇰🇭 Cambodia                         | Pep Level 2 |
| Office of the President                                                                                             | 🇰🇭 Cambodia                         | Pep Level 2 |
| Kingdom of Cambodia Business Registration                                                                           | 🇰🇭 Cambodia                         | SIE         |
| The Cameroon High Commission South Africa                                                                           | 🇨🇲 Cameroon                         | Pep Level 1 |
| Ministry of Foreign Affairs                                                                                         | 🇨🇲 Cameroon                         | Pep Level 2 |
| Constitutional Council                                                                                              | 🇨🇲 Cameroon                         | Pep Level 2 |
| Cameron People's Democratic Movement                                                                                | 🇨🇲 Cameroon                         | Pep Level 2 |
| National Elections Agency                                                                                           | 🇨🇲 Cameroon                         | Pep Level 2 |
| Ministry of Defence                                                                                                 | 🇨🇲 Cameroon                         | Pep Level 2 |
| Cameroon People's Democratic Movement                                                                               | 🇨🇲 Cameroon                         | Pep Level 2 |
| Ministry of Interior                                                                                                | 🇨🇲 Cameroon                         | Pep Level 2 |
| Ministry of National Education                                                                                      | 🇨🇲 Cameroon                         | Pep Level 2 |
| Ministry of Health                                                                                                  | 🇨🇲 Cameroon                         | Pep Level 2 |
| Supreme Court of Canada                                                                                             | 🇨🇦 Canada                           | Pep Level 1 |
| National Assembly of Québec                                                                                         | 🇨🇦 Canada                           | Pep Level 2 |
| Ministry of Finance                                                                                                 | 🇨🇦 Canada                           | Pep Level 2 |
| Ministry of Natural Resources                                                                                       | 🇨🇦 Canada                           | Pep Level 2 |
| Cabinet of Canada                                                                                                   | 🇨🇦 Canada                           | Pep Level 2 |
| Ministry of Immigration                                                                                             | 🇨🇦 Canada                           | Pep Level 2 |
| Ministry of Labour                                                                                                  | 🇨🇦 Canada                           | Pep Level 2 |
| Ministry of Foreign Affairs                                                                                         | 🇨🇦 Canada                           | Pep Level 2 |
| Ministry of National Defense                                                                                        | 🇨🇦 Canada                           | Pep Level 2 |
| Ministry of Health                                                                                                  | 🇨🇦 Canada                           | Pep Level 2 |
| Ministry of Public Safety                                                                                           | 🇨🇦 Canada                           | Pep Level 2 |
| Ministry of Employment and Social Development                                                                       | 🇨🇦 Canada                           | Pep Level 2 |
| Ministry of Transport                                                                                               | 🇨🇦 Canada                           | Pep Level 2 |
| Ministry of Public Services                                                                                         | 🇨🇦 Canada                           | Pep Level 2 |
| Ministry of Defense                                                                                                 | 🇨🇦 Canada                           | Pep Level 2 |
| Canada Named Research Organizations List                                                                            | 🇨🇦 Canada                           | SIE         |
| The Netcheck Commerce Bureau Inc.                                                                                   | 🇨🇦 Canada                           | SIP         |
| Government of Cape Verde                                                                                            | 🇨🇻 Cape Verde                       | Pep Level 1 |
| Cayman Islands Government                                                                                           | 🇰🇾 Cayman Islands                   | Pep Level 2 |
| National Office of the Caribbean Netherlands                                                                        | 🇧🇶 Caribbean Netherlands            | Pep Level 1 |
| Cayman Islands Senior Judicial Officers                                                                             | 🇰🇾 Cayman Islands                   | Pep Level 1 |
| Ministry of Finance                                                                                                 | 🇰🇾 Cayman Islands                   | Pep Level 2 |
| Iowa Insurance Division                                                                                             | 🇰🇾 Cayman Islands                   | SIE         |
| Ministry of Justice in the Central African Republic                                                                 | 🇨🇫 Central African Republic         | Pep Level 1 |
| Ministry of National Education and Civic Promotion                                                                  | 🇹🇩 Chad                             | Pep Level 1 |
| Ministry of Defense                                                                                                 | 🇹🇩 Chad                             | Pep Level 2 |
| Court of Accounts                                                                                                   | 🇹🇩 Chad                             | Pep Level 2 |
| High Judicial Council                                                                                               | 🇹🇩 Chad                             | Pep Level 3 |
| Office of National Marine Sanctuaries                                                                               | 🇯🇪 Channel Islands                  | Pep Level 1 |
| President Of Chile                                                                                                  | 🇨🇱 Chile                            | Pep Level 1 |
| National Congress                                                                                                   | 🇨🇱 Chile                            | Pep Level 2 |
| Ministry of Health                                                                                                  | 🇨🇱 Chile                            | Pep Level 2 |
| Ministry of Mining                                                                                                  | 🇨🇱 Chile                            | Pep Level 2 |
| Ministry of Justice                                                                                                 | 🇨🇱 Chile                            | Pep Level 2 |
| Ministry of National Defense                                                                                        | 🇨🇱 Chile                            | Pep Level 2 |
| Mining Association                                                                                                  | 🇨🇱 Chile                            | Pep Level 3 |
| Superintendencia de Pensiones - Gobierno de Chile                                                                   | 🇨🇱 Chile                            | SIE         |
| Diario y Radio Universidad Chile                                                                                    | 🇨🇱 Chile                            | SIP         |
| National Narcotics Control Commission (NNCC)                                                                        | 🇨🇳 China                            | Pep Level 1 |
| Guizhou Provincial People's Congress                                                                                | 🇨🇳 China                            | Pep Level 3 |
| Central Commission for Discipline Inspection                                                                        | 🇨🇳 China                            | Pep Level 3 |
| CHINA - CNMCA-USO - China Ministry of Civil Affairs - Unregistered Social Organizations                             | 🇨🇳 China                            | SIE         |
| China Daily Liaoning                                                                                                | 🇨🇳 China                            | SIP         |
| Ministry of Finance and Public Credit                                                                               | 🇨🇴 Colombia                         | Pep Level 1 |
| House of Representatives                                                                                            | 🇨🇴 Colombia                         | Pep Level 2 |
| Senate Colombia                                                                                                     | 🇨🇴 Colombia                         | Pep Level 2 |
| Constitutional Court                                                                                                | 🇨🇴 Colombia                         | Pep Level 2 |
| COLOMBIA - COSIC - Superintendence of Industry and Commerce                                                         | 🇨🇴 Colombia                         | SIE         |
| Fiscalia General de la República                                                                                    | 🇨🇴 Colombia                         | SIP         |
| Presidency of the Union of the Comoros                                                                              | 🇰🇲 Comoros                          | Pep Level 1 |
| President of the Republic of the Congo                                                                              | 🇨🇬 Congo                            | Pep Level 1 |
| CONGO REP. - CGPALF - PALF Wildlife Law Enforcement                                                                 | 🇨🇬 Congo                            | SIP         |
| Office of the President (Costa Rica)                                                                                | 🇨🇷 Costa Rica                       | Pep Level 1 |
| Ministry of Public                                                                                                  | 🇨🇷 Costa Rica                       | Pep Level 1 |
| Council of Ministers                                                                                                | 🇨🇷 Costa Rica                       | Pep Level 2 |
| COSTA RICA - CRSUGESE - Costa Rican General Superintendency of Insurance                                            | 🇨🇷 Costa Rica                       | SIE         |
| U.S. District Court for the District of Rhode Island                                                                | 🇨🇷 Costa Rica                       | SIP         |
| SIVES - Special Interest Vessel                                                                                     | 🇨🇮 Cote D'Ivoire (Ivory Coast)      | SIE         |
| Le Journal International                                                                                            | 🇨🇮 Cote D'Ivoire (Ivory Coast)      | SIP         |
| Ministry of Foreign Affairs                                                                                         | 🇨🇮 Cote d'Ivoire                    | Pep Level 2 |
| Ministry of Defense                                                                                                 | 🇨🇮 Cote d'Ivoire                    | Pep Level 2 |
| Ministry of Security and Civil Protection                                                                           | 🇨🇮 Cote d'Ivoire                    | Pep Level 2 |
| Ministry of Justice                                                                                                 | 🇨🇮 Cote d'Ivoire                    | Pep Level 2 |
| Ministry of Finance                                                                                                 | 🇨🇮 Cote d'Ivoire                    | Pep Level 2 |
| Ministry of Commerce and Industry                                                                                   | 🇨🇮 Cote d'Ivoire                    | Pep Level 2 |
| Ministry of Economic Infrastructure                                                                                 | 🇨🇮 Cote d'Ivoire                    | Pep Level 2 |
| Ministry of Employment and Social Protection                                                                        | 🇨🇮 Cote d'Ivoire                    | Pep Level 2 |
| Ministry of Mines and Geology                                                                                       | 🇨🇮 Cote d'Ivoire                    | Pep Level 2 |
| Ministry of Agriculture and Rural Development                                                                       | 🇨🇮 Cote d'Ivoire                    | Pep Level 2 |
| Ministry of Petroleum                                                                                               | 🇨🇮 Cote d'Ivoire                    | Pep Level 2 |
| Ministry of Environment and Sustainable Development                                                                 | 🇨🇮 Cote d'Ivoire                    | Pep Level 2 |
| Ministry of Higher Education and Scientific Research                                                                | 🇨🇮 Cote d'Ivoire                    | Pep Level 2 |
| Constitutional Council                                                                                              | 🇨🇮 Cote d'Ivoire                    | Pep Level 2 |
| National Assembly                                                                                                   | 🇨🇮 Cote d'Ivoire                    | Pep Level 2 |
| Senate                                                                                                              | 🇨🇮 Cote d'Ivoire                    | Pep Level 2 |
| National Commission for the Restoration of Democracy                                                                | 🇨🇮 Cote d'Ivoire                    | Pep Level 2 |
| Ministry of Foreign Affairs                                                                                         | 🇭🇷 Croatia                          | Pep Level 1 |
| Dubrovnik City Government                                                                                           | 🇭🇷 Croatia                          | Pep Level 4 |
| Dubrovački - Naslovnica                                                                                             | 🇭🇷 Croatia                          | SIP         |
| People's Provincial Court Of Havana                                                                                 | 🇨🇺 Cuba                             | Pep Level 3 |
| ACN - Noticias de Cuba                                                                                              | 🇨🇺 Cuba                             | SIP         |
| SWEDEN - SEGA - Swedish Gaming Authority                                                                            | 🇨🇼 Curacao                          | SIE         |
| House of Representatives of Cyprus                                                                                  | 🇨🇾 Cyprus                           | Pep Level 1 |
| U.S. Department of the Treasury                                                                                     | 🇨🇾 Cyprus                           | SIP         |
| Czech Social Democratic Party (ČSSD)                                                                                | 🇨🇿 Czech Republic                   | Pep Level 1 |
| Prague City Hall                                                                                                    | 🇨🇿 Czech Republic                   | Pep Level 4 |
| CZECH - CZUOHS - Czech Office for the Protection of Competition                                                     | 🇨🇿 Czech Republic                   | SIE         |
| Nejrychlejší zprávy (Jižní Čechy Teď!)                                                                              | 🇨🇿 Czech Republic                   | SIP         |
| Cabinet of Ministers (DRC)                                                                                          | 🇨🇩 Democratic Republic of the Congo | Pep Level 2 |
| Ministry of Foreign Affairs                                                                                         | 🇨🇩 Democratic Republic of the Congo | Pep Level 2 |
| Ministry of Finance                                                                                                 | 🇨🇩 Democratic Republic of the Congo | Pep Level 2 |
| Ministry of Defense                                                                                                 | 🇨🇩 Democratic Republic of the Congo | Pep Level 2 |
| Ministry of Health                                                                                                  | 🇨🇩 Democratic Republic of the Congo | Pep Level 2 |
| Congolese National Police                                                                                           | 🇨🇩 Democratic Republic of the Congo | Pep Level 2 |
| Central Bank of the Congo                                                                                           | 🇨🇩 Democratic Republic of the Congo | Pep Level 2 |
| Senate                                                                                                              | 🇨🇩 Democratic Republic of the Congo | Pep Level 2 |
| National Assembly                                                                                                   | 🇨🇩 Democratic Republic of the Congo | Pep Level 2 |
| Attorney General's Office of the Republic                                                                           | 🇨🇩 Democratic Republic of the Congo | Pep Level 2 |
| DRC Central Bank                                                                                                    | 🇨🇩 Democratic Republic of the Congo | Pep Level 3 |
| Compagnie Africaine d'Aviation                                                                                      | 🇨🇩 Democratic Republic of the Congo | SIE         |
| Security Council Report                                                                                             | 🇨🇩 Democratic Republic of the Congo | SIP         |
| PCAOB (Public Company Accounting Oversight Board)                                                                   | 🇩🇰 Denmark                          | SIE         |
| Djibouti Presidential Police                                                                                        | 🇩🇯 Djibouti                         | Pep Level 1 |
| House of Assembly of Dominica                                                                                       | 🇩🇲 Dominica                         | Pep Level 1 |
| Constitutional Court of Dominican Republic                                                                          | 🇩🇴 Dominican Republic               | Pep Level 1 |
| National Telecommunications Commission                                                                              | 🇩🇴 Dominican Republic               | Pep Level 3 |
| DOMINICAN REPUBLIC - DOSIMV - Dominican Stock Market Superintendence                                                | 🇩🇴 Dominican Republic               | SIE         |
| Woonsocket, RI Patch                                                                                                | 🇩🇴 Dominican Republic               | SIP         |
| Ministry for Foreign Affairs of East Timor                                                                          | 🇹🇱 East Timor                       | Pep Level 1 |
| Ministry of Defense                                                                                                 | 🇪🇨 Ecuador                          | Pep Level 2 |
| National Assembly                                                                                                   | 🇪🇨 Ecuador                          | Pep Level 2 |
| National Electoral Council (CNE)                                                                                    | 🇪🇨 Ecuador                          | Pep Level 2 |
| Ministry of Foreign Affairs                                                                                         | 🇪🇨 Ecuador                          | Pep Level 2 |
| Ministry of Finance                                                                                                 | 🇪🇨 Ecuador                          | Pep Level 2 |
| Ministry of the Interior                                                                                            | 🇪🇨 Ecuador                          | Pep Level 2 |
| Ministry of Justice                                                                                                 | 🇪🇨 Ecuador                          | Pep Level 2 |
| Ministry of Agriculture and Livestock                                                                               | 🇪🇨 Ecuador                          | Pep Level 2 |
| Ministry of Energy and Non-Renewable Natural Resources                                                              | 🇪🇨 Ecuador                          | Pep Level 2 |
| Ministry of Public Health                                                                                           | 🇪🇨 Ecuador                          | Pep Level 2 |
| ECUADOR - ECSRI - Ecuador Internal Revenue Service                                                                  | 🇪🇨 Ecuador                          | SIE         |
| ECUADOR - ECPN-MW - National Police of Ecuador - Most Wanted                                                        | 🇪🇨 Ecuador                          | SIP         |
| Department of Justice / Ministère de la Justice                                                                     | 🇪🇬 Egypt                            | SIP         |
| The Maritime Executive                                                                                              | 🇸🇻 El Salvador                      | SIE         |
| El Salvador Times                                                                                                   | 🇸🇻 El Salvador                      | SIP         |
| Office of the Prime Minister                                                                                        | 🇬🇶 Equatorial Guinea                | Pep Level 1 |
| National Assembly of Eritrea                                                                                        | 🇪🇷 Eritrea                          | Pep Level 1 |
| Eritrean Liberation Front                                                                                           | 🇪🇷 Eritrea                          | Pep Level 3 |
| Asmara and Eritrea                                                                                                  | 🇪🇷 Eritrea                          | SIE         |
| Estonian Centre Party                                                                                               | 🇪🇪 Estonia                          | Pep Level 1 |
| Harju County Government                                                                                             | 🇪🇪 Estonia                          | Pep Level 4 |
| ניקוי חלונות ג'נסיס                                                                                                 | 🇮🇱 Israel                           | SIE         |
| ESTONIA - EEPPA - Estonian Police and Border Guard Board                                                            | 🇪🇪 Estonia                          | SIP         |
| National House of Representatives                                                                                   | 🇸🇿 Eswatini                         | Pep Level 1 |
| House of Federation (Ethiopia)                                                                                      | 🇪🇹 Ethiopia                         | Pep Level 3 |
| Ethiopian Revenues and Customs Authority (ERCA)                                                                     | 🇪🇹 Ethiopia                         | Pep Level 3 |
| Addis Ababa City Administration                                                                                     | 🇪🇹 Ethiopia                         | Pep Level 4 |
| Congress of the Republic (Congressional Commissions)                                                                | 🇫🇯 Fiji                             | Pep Level 1 |
| judiciary.gov.fj - Fiji judiciary                                                                                   | 🇫🇯 Fiji Islands                     | SIP         |
| Suomen Sosialidemokraattinen Puolue (SDP)                                                                           | 🇫🇮 Finland                          | Pep Level 1 |
| FINLAND - FIKKV - Finnish Competition and Consumer Authority                                                        | 🇫🇮 Finland                          | SIE         |
| Ministry of Justice (France)                                                                                        | 🇫🇷 France                           | Pep Level 1 |
| Constitutional Council                                                                                              | 🇫🇷 France                           | Pep Level 2 |
| Ministry of Foreign Affairs                                                                                         | 🇫🇷 France                           | Pep Level 2 |
| Council of State                                                                                                    | 🇫🇷 France                           | Pep Level 2 |
| Court of Cassation                                                                                                  | 🇫🇷 France                           | Pep Level 2 |
| Ministry of Economy and Finance                                                                                     | 🇫🇷 France                           | Pep Level 2 |
| Ministry of Defense                                                                                                 | 🇫🇷 France                           | Pep Level 2 |
| French Communist Party                                                                                              | 🇫🇷 France                           | Pep Level 3 |
| La République En Marche!                                                                                            | 🇫🇷 France                           | Pep Level 3 |
| FRANCE - AUTORITE DES MARCHES FINANCIERS - FRAMF                                                                    | 🇫🇷 France                           | SIE         |
| Collectif des Contribuables des Terres d'Aurignac                                                                   | 🇫🇷 France                           | SIP         |
| La Dépêche de Tahiti                                                                                                | 🇵🇫 French Polynesia                 | SIP         |
| Parliament of Gabon                                                                                                 | 🇬🇦 Gabon                            | Pep Level 1 |
| National Assembly                                                                                                   | 🇬🇲 Gambia                           | Pep Level 1 |
| National Bank of Georgia                                                                                            | 🇬🇪 Georgia                          | Pep Level 2 |
| National Bank of Georgia                                                                                            | 🇬🇪 Georgia                          | Pep Level 3 |
| PSYCHIATRIC ASSOCIATION FOR EASTERN EUROPE AND THE BALKANS - PAEEB                                                  | 🇬🇪 Georgia                          | SIP         |
| City of Krefeld                                                                                                     | 🇩🇪 Germany                          | Pep Level 4 |
| Unternehmensverzeichnis für Deutschland                                                                             | 🇩🇪 Germany                          | SIE         |
| Michael Turgut ©                                                                                                    | 🇩🇪 Germany                          | SIP         |
| Ghana Railway Corporation                                                                                           | 🇬🇭 Ghana                            | Pep Level 1 |
| Ghana Maritime Authority                                                                                            | 🇬🇭 Ghana                            | Pep Level 2 |
| Ghana Police Service                                                                                                | 🇬🇭 Ghana                            | Pep Level 2 |
| Office of the Attorney General                                                                                      | 🇬🇭 Ghana                            | Pep Level 2 |
| New Patriotic Party (NPP)                                                                                           | 🇬🇭 Ghana                            | Pep Level 2 |
| Bank of Ghana                                                                                                       | 🇬🇭 Ghana                            | Pep Level 3 |
| National Pensions Regulatory Authority (NPRA)                                                                       | 🇬🇭 Ghana                            | Pep Level 3 |
| Accra Metropolitan Assembly                                                                                         | 🇬🇭 Ghana                            | Pep Level 4 |
| Hellenic Parliament                                                                                                 | 🇬🇷 Greece                           | Pep Level 3 |
| Eurobank Asset Management                                                                                           | 🇬🇷 Greece                           | SIE         |
| Анархический черный крест Беларусь                                                                                  | 🇧🇾 Belarus                          | SIP         |
| Norse Federation of Greenland                                                                                       | 🇬🇱 Greenland                        | Pep Level 1 |
| Grenada Institute of Politics                                                                                       | 🇬🇩 Grenada                          | Pep Level 1 |
| Ministry of Home Affairs                                                                                            | 🇬🇺 Guam                             | Pep Level 1 |
| Guatemala Presidency                                                                                                | 🇬🇹 Guatemala                        | Pep Level 1 |
| Ministry of Public Health and Social Assistance                                                                     | 🇬🇹 Guatemala                        | Pep Level 2 |
| Guatemala City Government                                                                                           | 🇬🇹 Guatemala                        | Pep Level 4 |
| Diario de Centro América                                                                                            | 🇬🇹 Guatemala                        | SIP         |
| National Assembly of Guinea                                                                                         | 🇬🇳 Guinea                           | Pep Level 1 |
| EAGLE Network - Eco Activists for Governance and Law Enforcement                                                    | 🇬🇳 Guinea                           | SIP         |
| Ministry of Agriculture and Natural Resources                                                                       | 🇬🇼 Guinea-Bissau                    | Pep Level 1 |
| National Assembly of Guyana                                                                                         | 🇬🇾 Guyana                           | Pep Level 1 |
| The Colorado Bar                                                                                                    | 🇬🇾 Guyana                           | SIP         |
| Chamber of Representatives                                                                                          | 🇭🇹 Haiti                            | Pep Level 1 |
| Appeal Court (Haiti)                                                                                                | 🇭🇹 Haiti                            | Pep Level 3 |
| Ministry of Interior                                                                                                | 🇭🇳 Honduras                         | Pep Level 1 |
| Ministry of Security (Honduras)                                                                                     | 🇭🇳 Honduras                         | Pep Level 2 |
| CBC Canal 6                                                                                                         | 🇭🇳 Honduras                         | SIP         |
| Hong Kong Monetary Authority - Register of Securities Staff of AIs                                                  | 🇭🇰 Hong Kong                        | SIP         |
| National Assembly of Hungary                                                                                        | 🇭🇺 Hungary                          | Pep Level 1 |
| Hungarian Socialist Party                                                                                           | 🇭🇺 Hungary                          | Pep Level 2 |
| Ministry of Education                                                                                               | 🇭🇺 Hungary                          | Pep Level 2 |
| Attorney General's Office of Hungary                                                                                | 🇭🇺 Hungary                          | Pep Level 2 |
| Hungarian Workers' Party                                                                                            | 🇭🇺 Hungary                          | Pep Level 3 |
| HUNGARY - GVH - Hungarian Competition Authority - Gazdasagi Versenyhivatal                                          | 🇭🇺 Hungary                          | SIE         |
| ZAOL - Zala vármegyei hírportál                                                                                     | 🇭🇺 Hungary                          | SIP         |
| Parliament of Iceland                                                                                               | 🇮🇸 Iceland                          | Pep Level 1 |
| Council of States                                                                                                   | 🇮🇳 India                            | Pep Level 2 |
| Parliament of India                                                                                                 | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Defense                                                                                                 | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Home Affairs                                                                                            | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Finance                                                                                                 | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Law and Justice                                                                                         | 🇮🇳 India                            | Pep Level 2 |
| Ministry of External Affairs                                                                                        | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Defence                                                                                                 | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Information and Broadcasting                                                                            | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Parliamentary Affairs                                                                                   | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Personnel                                                                                               | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Power                                                                                                   | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Railways                                                                                                | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Road Transport and Highways                                                                             | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Science and Technology                                                                                  | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Shipping                                                                                                | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Skill Development and Entrepreneurship                                                                  | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Social Justice and Empowerment                                                                          | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Statistics and Programme Implementation                                                                 | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Steel                                                                                                   | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Tourism                                                                                                 | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Tribal Affairs                                                                                          | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Women and Child Development                                                                             | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Youth Affairs and Sports                                                                                | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Corporate Affairs                                                                                       | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Environment                                                                                             | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Civil Aviation                                                                                          | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Agriculture & Farmers Welfare                                                                           | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Chemical and Fertilizers                                                                                | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Coal                                                                                                    | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Commerce and Industry                                                                                   | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Communications                                                                                          | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Consumer Affairs                                                                                        | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Culture                                                                                                 | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Development of North Eastern Region                                                                     | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Earth Sciences                                                                                          | 🇮🇳 India                            | Pep Level 2 |
| Ministry of Electronics and Information Technology                                                                  | 🇮🇳 India                            | Pep Level 2 |
| All India United Democratic Front (AIUDF)                                                                           | 🇮🇳 India                            | Pep Level 3 |
| Bharti AXA Life Insurance Company                                                                                   | 🇮🇳 India                            | SIE         |
| PubMed Central (PMC)                                                                                                | 🇮🇳 India                            | SIP         |
| House of Representatives                                                                                            | 🇮🇩 Indonesia                        | Pep Level 1 |
| BPJS Ketenagakerjaan (Workers Social Security Agency)                                                               | 🇮🇩 Indonesia                        | Pep Level 3 |
| LPSE Provinsi Sulawesi Selatan                                                                                      | 🇮🇩 Indonesia                        | SIE         |
| INDONESIA - IDMA - Indonesian Supreme Court                                                                         | 🇮🇩 Indonesia                        | SIP         |
| Nuclear Threat Initiative (NTI)                                                                                     | 🌐 International                      | Pep Level 2 |
| Glencore plc                                                                                                        | 🌐 International                      | Pep Level 3 |
| Committee of Permanent Representatives to ASEAN (CPR)                                                               | 🌐 International                      | Pep Level 3 |
| European Commission                                                                                                 | 🌐 International                      | Pep Level 3 |
| South Asian Association for Regional Cooperation (SAARC)                                                            | 🌐 International                      | Pep Level 3 |
| International Investment Bank (IIB)                                                                                 | 🌐 International                      | Pep Level 3 |
| Transnistrian Republican Bank                                                                                       | 🌐 International                      | Pep Level 3 |
| Unitaid                                                                                                             | 🌐 International                      | Pep Level 3 |
| Russian Unified State Register of Legal Entities (EGRUL)                                                            | 🌐 International                      | SIE         |
| Bank Melli Iran                                                                                                     | 🇮🇷 Iran                             | Pep Level 1 |
| Islamic Revolutionary Guard Corps                                                                                   | 🇮🇷 Iran                             | Pep Level 2 |
| Ministry of Industry                                                                                                | 🇮🇷 Iran                             | Pep Level 2 |
| Ministry of Justice                                                                                                 | 🇮🇷 Iran                             | Pep Level 2 |
| Expediency Discernment Council                                                                                      | 🇮🇷 Iran                             | Pep Level 3 |
| Assembly of Experts                                                                                                 | 🇮🇷 Iran                             | Pep Level 3 |
| Islamic Revolutionary Guard Corps – Quds Force                                                                      | 🇮🇷 Iran                             | Pep Level 3 |
| ECVES - Embargoed Country or Region Maritime Vessel                                                                 | 🇮🇷 Iran                             | SIE         |
| Center for Human Rights in Iran                                                                                     | 🇮🇷 Iran                             | SIP         |
| House of Representatives of Iraq                                                                                    | 🇮🇶 Iraq                             | Pep Level 1 |
| Ministry of Finance                                                                                                 | 🇮🇶 Iraq                             | Pep Level 2 |
| Ministry of Agriculture                                                                                             | 🇮🇶 Iraq                             | Pep Level 2 |
| Iraqi National Congress                                                                                             | 🇮🇶 Iraq                             | Pep Level 2 |
| Ministry of Labor                                                                                                   | 🇮🇶 Iraq                             | Pep Level 2 |
| Ministry of Defense                                                                                                 | 🇮🇶 Iraq                             | Pep Level 2 |
| Ministry of Oil                                                                                                     | 🇮🇶 Iraq                             | Pep Level 2 |
| Iraqi National Oil Company (INOC)                                                                                   | 🇮🇶 Iraq                             | Pep Level 2 |
| Iraqi Trade Bank (TBI)                                                                                              | 🇮🇶 Iraq                             | Pep Level 3 |
| Chaldean Syrian Church                                                                                              | 🇮🇶 Iraq                             | Pep Level 3 |
| S.J. Quinney College of Law                                                                                         | 🇮🇶 Iraq                             | SIP         |
| House of Assembly of Ireland                                                                                        | 🇮🇪 Ireland                          | Pep Level 1 |
| The Irish Times                                                                                                     | 🇮🇪 Ireland                          | SIP         |
| Parliament of the Isle of Man                                                                                       | 🇮🇲 Isle of Man                      | Pep Level 1 |
| ISLE OF MAN - FIN. SUPERVISION COMM. - IOMFSC                                                                       | 🇮🇲 Isle of Man                      | SIE         |
| House of the People (Israel)                                                                                        | 🇮🇱 Israel                           | Pep Level 1 |
| Ministry of Finance                                                                                                 | 🇮🇱 Israel                           | Pep Level 2 |
| Cabinet of Israel                                                                                                   | 🇮🇱 Israel                           | Pep Level 2 |
| Likud Party                                                                                                         | 🇮🇱 Israel                           | Pep Level 2 |
| Knesset (Israeli Parliament)                                                                                        | 🇮🇱 Israel                           | Pep Level 2 |
| Ministry of Agriculture                                                                                             | 🇮🇱 Israel                           | Pep Level 2 |
| Ministry of Defense                                                                                                 | 🇮🇱 Israel                           | Pep Level 2 |
| Ministry of Energy                                                                                                  | 🇮🇱 Israel                           | Pep Level 2 |
| Ministry of Foreign Affairs                                                                                         | 🇮🇱 Israel                           | Pep Level 2 |
| Ministry of Health                                                                                                  | 🇮🇱 Israel                           | Pep Level 2 |
| Ministry of Justice                                                                                                 | 🇮🇱 Israel                           | Pep Level 2 |
| Ministry of Public Security                                                                                         | 🇮🇱 Israel                           | Pep Level 2 |
| Ministry of Science and Technology                                                                                  | 🇮🇱 Israel                           | Pep Level 2 |
| Ministry of Transportation                                                                                          | 🇮🇱 Israel                           | Pep Level 2 |
| Supreme Court                                                                                                       | 🇮🇱 Israel                           | Pep Level 2 |
| תמיר פישמן- בית השקעות חכם                                                                                          | 🇮🇱 Israel                           | SIE         |
| ISRAEL - ILITA - Israel Tax Authority                                                                               | 🇮🇱 Israel                           | SIP         |
| House of Representatives of Italy                                                                                   | 🇮🇹 Italy                            | Pep Level 1 |
| ITALY - ITGPDP - Italian Data Protection Authority                                                                  | 🇮🇹 Italy                            | SIE         |
| Città di Castenaso                                                                                                  | 🇮🇹 Italy                            | SIP         |
| Jamaica Civil Aviation Authority                                                                                    | 🇯🇲 Jamaica                          | Pep Level 1 |
| Ministry of Agriculture                                                                                             | 🇯🇲 Jamaica                          | Pep Level 2 |
| Stamford Daily Voice                                                                                                | 🇯🇲 Jamaica                          | SIP         |
| National Diet Library                                                                                               | 🇯🇵 Japan                            | Pep Level 1 |
| Ministry of Defense                                                                                                 | 🇯🇵 Japan                            | Pep Level 2 |
| Ministry of Justice                                                                                                 | 🇯🇵 Japan                            | Pep Level 2 |
| Ministry of Foreign Affairs                                                                                         | 🇯🇵 Japan                            | Pep Level 2 |
| Ministry of Finance                                                                                                 | 🇯🇵 Japan                            | Pep Level 2 |
| Ministry of Health                                                                                                  | 🇯🇵 Japan                            | Pep Level 2 |
| Ministry of Education                                                                                               | 🇯🇵 Japan                            | Pep Level 2 |
| Ministry of Economy                                                                                                 | 🇯🇵 Japan                            | Pep Level 2 |
| Ministry of Land                                                                                                    | 🇯🇵 Japan                            | Pep Level 2 |
| Ministry of Agriculture                                                                                             | 🇯🇵 Japan                            | Pep Level 2 |
| Public Prosecutor's Office                                                                                          | 🇯🇵 Japan                            | Pep Level 2 |
| Supreme Court                                                                                                       | 🇯🇵 Japan                            | Pep Level 2 |
| House of Councillors (Japan)                                                                                        | 🇯🇵 Japan                            | Pep Level 2 |
| INPEX Corporation                                                                                                   | 🇯🇵 Japan                            | Pep Level 3 |
| Local government of Yamanouchi                                                                                      | 🇯🇵 Japan                            | Pep Level 4 |
| Fuji Electric Global                                                                                                | 🇯🇵 Japan                            | SIE         |
| データ・マックス (Data Max)                                                                                                 | 🇯🇵 Japan                            | SIP         |
| Emirate Council                                                                                                     | 🇯🇴 Jordan                           | Pep Level 1 |
| The Middle East (الشرق الأوسط)                                                                                      | 🇯🇴 Jordan                           | SIP         |
| Assembly of the Republic                                                                                            | 🇰🇿 Kazakhstan                       | Pep Level 1 |
| Kazakh National Academy of Natural Sciences                                                                         | 🇰🇿 Kazakhstan                       | Pep Level 3 |
| Kazakhstan Railways (KTZ)                                                                                           | 🇰🇿 Kazakhstan                       | Pep Level 3 |
| House of Representatives of Kazakhstan                                                                              | 🇰🇿 Kazakhstan                       | Pep Level 3 |
| KAZAKHSTAN - KZKGD - State Revenue Committee of The Ministry of Finance                                             | 🇰🇿 Kazakhstan                       | SIE         |
| KAZAKHSTAN - KZACA - Anti-Corruption Agency of Kazakhstan                                                           | 🇰🇿 Kazakhstan                       | SIP         |
| National Assembly of Kenya                                                                                          | 🇰🇪 Kenya                            | Pep Level 1 |
| Kenya Tourism Board                                                                                                 | 🇰🇪 Kenya                            | Pep Level 3 |
| Kenya Rural Roads Authority                                                                                         | 🇰🇪 Kenya                            | Pep Level 3 |
| Nairobi Securities Exchange                                                                                         | 🇰🇪 Kenya                            | Pep Level 3 |
| County Government of Kisii                                                                                          | 🇰🇪 Kenya                            | Pep Level 4 |
| Bomet County Government                                                                                             | 🇰🇪 Kenya                            | Pep Level 4 |
| ADB - Asian Development Bank                                                                                        | 🇰🇪 Kenya                            | SIE         |
| Kenyan Wall Street                                                                                                  | 🇰🇪 Kenya                            | SIP         |
| National Assembly of Kiribati                                                                                       | 🇰🇮 Kiribati                         | Pep Level 1 |
| Parliament of Kosovo                                                                                                | 🇽🇰 Kosovo                           | Pep Level 1 |
| Kosovo Energy Corporation (KEK)                                                                                     | 🇽🇰 Kosovo                           | Pep Level 3 |
| Kosovo National Intelligence Agency                                                                                 | 🇽🇰 Kosovo                           | Pep Level 3 |
| National Assembly of Kuwait                                                                                         | 🇰🇼 Kuwait                           | Pep Level 1 |
| KUWAIT - KWCMA - Kuwait Capital Markets Authority                                                                   | 🇰🇼 Kuwait                           | SIP         |
| National Assembly of Kyrgyzstan                                                                                     | 🇰🇬 Kyrgyzstan                       | Pep Level 1 |
| National Assembly (Zhogorku Kenesh)                                                                                 | 🇰🇬 Kyrgyzstan                       | Pep Level 2 |
| National Statistical Committee (NSC)                                                                                | 🇰🇬 Kyrgyzstan                       | Pep Level 2 |
| KYRGYZSTAN - KGFIU - Kyrgyzstan Financial Intelligence Service                                                      | 🇰🇬 Kyrgyzstan                       | SIP         |
| National Assembly of Laos                                                                                           | 🇱🇦 Laos                             | Pep Level 1 |
| Parliament of Latvia                                                                                                | 🇱🇻 Latvia                           | Pep Level 1 |
| Latvian SSR                                                                                                         | 🇱🇻 Latvia                           | Pep Level 3 |
| UR informācijas portāls                                                                                             | 🇱🇻 Latvia                           | SIE         |
| Global Arbitration Review                                                                                           | 🇱🇻 Latvia                           | SIP         |
| House of Representatives of Lebanon                                                                                 | 🇱🇧 Lebanon                          | Pep Level 1 |
| Banque du Liban (Central Bank of Lebanon)                                                                           | 🇱🇧 Lebanon                          | Pep Level 3 |
| USA - US BUREAU OF INDUSTRY & SECURITY - EXPORT VIOLATIONS - USBIS-EV                                               | 🇱🇧 Lebanon                          | SIE         |
| Lists of sanctions                                                                                                  | 🇱🇧 Lebanon                          | SIP         |
| National Assembly of Lesotho                                                                                        | 🇱🇸 Lesotho                          | Pep Level 1 |
| House of Representatives of Liberia                                                                                 | 🇱🇷 Liberia                          | Pep Level 1 |
| Liberia Petroleum Refining Company                                                                                  | 🇱🇷 Liberia                          | Pep Level 2 |
| National Oil Company of Liberia                                                                                     | 🇱🇷 Liberia                          | Pep Level 2 |
| Government of Montserrado County                                                                                    | 🇱🇷 Liberia                          | Pep Level 4 |
| Georgia Bankers Association                                                                                         | 🇱🇷 Liberia                          | SIP         |
| Parliament of Libya                                                                                                 | 🇱🇾 Libya                            | Pep Level 1 |
| Libyan House of Representatives                                                                                     | 🇱🇾 Libya                            | Pep Level 3 |
| Focal Maritime Services                                                                                             | 🇱🇾 Libya                            | SIE         |
| The American Presidency Project                                                                                     | 🇱🇾 Libya                            | SIP         |
| Parliament of Liechtenstein                                                                                         | 🇱🇮 Liechtenstein                    | Pep Level 1 |
| House of Representatives of Lithuania                                                                               | 🇱🇹 Lithuania                        | Pep Level 1 |
| LITHUANIA - CENTRAL BANK OF LITHUANIA - WARNING NOTICES - LTLCB                                                     | 🇱🇹 Lithuania                        | SIP         |
| National Assembly of Luxembourg                                                                                     | 🇱🇺 Luxembourg                       | Pep Level 1 |
| McDermott Will & Emery                                                                                              | 🇱🇺 Luxembourg                       | SIE         |
| National Assembly of Macau                                                                                          | 🇲🇴 Macau                            | Pep Level 1 |
| National Assembly of Madagascar                                                                                     | 🇲🇬 Madagascar                       | Pep Level 1 |
| National Assembly of Malawi                                                                                         | 🇲🇼 Malawi                           | Pep Level 1 |
| Dewan Rakyat                                                                                                        | 🇲🇾 Malaysia                         | Pep Level 1 |
| Bank Negara Malaysia (Central Bank of Malaysia)                                                                     | 🇲🇾 Malaysia                         | Pep Level 3 |
| MALAYSIA - LFSA-ALERT - Labuan Financial Services Authority-Alert                                                   | 🇲🇾 Malaysia                         | SIE         |
| MALAYSIA - MYOCR-MFC - Office of The Chief Registrar - Malaysia Federal Court                                       | 🇲🇾 Malaysia                         | SIP         |
| National Assembly of Maldives                                                                                       | 🇲🇻 Maldives                         | Pep Level 1 |
| Ministry of National Planning and Infrastructure                                                                    | 🇲🇻 Maldives                         | Pep Level 3 |
| Progressive Party of Maldives                                                                                       | 🇲🇻 Maldives                         | Pep Level 3 |
| National Assembly of Mali                                                                                           | 🇲🇱 Mali                             | Pep Level 1 |
| INTERNATIONAL - UNSCPE-WC - United Nations Security Council Panel of Experts - World-Check Data                     | 🇲🇱 Mali                             | SIP         |
| House of Assembly (Malta)                                                                                           | 🇲🇹 Malta                            | Pep Level 1 |
| Asset Recovery Bureau                                                                                               | 🇲🇹 Malta                            | SIP         |
| Parliament of Marshall Islands                                                                                      | 🇲🇭 Marshall Islands                 | Pep Level 1 |
| National Assembly of Mauritania                                                                                     | 🇲🇷 Mauritania                       | Pep Level 1 |
| Les Blogs de la Rédaction                                                                                           | 🇲🇷 Mauritania                       | SIP         |
| National Assembly of Mauritius                                                                                      | 🇲🇺 Mauritius                        | Pep Level 1 |
| MAURITIUS - MUFSC - Mauritius Financial Services Commission                                                         | 🇲🇺 Mauritius                        | SIP         |
| Chamber of Senators                                                                                                 | 🇲🇽 Mexico                           | Pep Level 2 |
| MEXICO - MXSAT - Mexican Tax Administration Service                                                                 | 🇲🇽 Mexico                           | SIE         |
| Cuba Libre Digital                                                                                                  | 🇲🇽 Mexico                           | SIP         |
| Congress of the Federated States of Micronesia                                                                      | 🇫🇲 Micronesia                       | Pep Level 1 |
| Audiovisual Council of Moldova                                                                                      | 🇲🇩 Moldova                          | Pep Level 3 |
| MOLDOVA - MDBP-W - Moldova Border Police - Wanted                                                                   | 🇲🇩 Moldova                          | SIP         |
| Parliament of Monaco                                                                                                | 🇲🇨 Monaco                           | Pep Level 1 |
| National Assembly of Mongolia                                                                                       | 🇲🇳 Mongolia                         | Pep Level 1 |
| House of Representatives of Montenegro                                                                              | 🇲🇪 Montenegro                       | Pep Level 1 |
| KK PARTIZAN MOZZART BET                                                                                             | 🇲🇪 Montenegro                       | SIP         |
| Parliament of Montserrat                                                                                            | 🇲🇸 Montserrat                       | Pep Level 1 |
| Parliament of Morocco                                                                                               | 🇲🇦 Morocco                          | Pep Level 1 |
| Justice and Development Party (PJD)                                                                                 | 🇲🇦 Morocco                          | Pep Level 3 |
| Meyn Food Processing Technology B.V.                                                                                | 🇲🇦 Morocco                          | SIP         |
| Assembly of the Republic                                                                                            | 🇲🇿 Mozambique                       | Pep Level 1 |
| Club of Mozambique                                                                                                  | 🇲🇿 Mozambique                       | SIE         |
| Parliament of Myanmar (Burma)                                                                                       | 🇲🇲 Myanmar                          | Pep Level 1 |
| Myanmar Union Parliament (Pyidaungsu Hluttaw)                                                                       | 🇲🇲 Myanmar                          | Pep Level 3 |
| Myanmar Treasure Resort Bagan                                                                                       | 🇲🇲 Myanmar                          | SIE         |
| Democratic Voice of Burma                                                                                           | 🇲🇲 Myanmar                          | SIP         |
| Parliament of Namibia                                                                                               | 🇳🇦 Namibia                          | Pep Level 1 |
| NAMIBIA - NAMFISA - Namibia Financial Institutions Supervisory Authority                                            | 🇳🇦 Namibia                          | SIE         |
| NAMIBIA - NAACC - Anti-Corruption Commission of Namibia                                                             | 🇳🇦 Namibia                          | SIP         |
| Parliament of Nauru                                                                                                 | 🇳🇷 Nauru                            | Pep Level 1 |
| National Assembly of Nepal                                                                                          | 🇳🇵 Nepal                            | Pep Level 1 |
| Nepal Electricity Authority                                                                                         | 🇳🇵 Nepal                            | Pep Level 2 |
| Ministry of Finance                                                                                                 | 🇳🇵 Nepal                            | Pep Level 2 |
| Ministry of Foreign Affairs                                                                                         | 🇳🇵 Nepal                            | Pep Level 2 |
| Ministry of Home Affairs                                                                                            | 🇳🇵 Nepal                            | Pep Level 2 |
| Ministry of Defense                                                                                                 | 🇳🇵 Nepal                            | Pep Level 2 |
| Ministry of Federal Affairs and General Administration                                                              | 🇳🇵 Nepal                            | Pep Level 2 |
| Ministry of Industry                                                                                                | 🇳🇵 Nepal                            | Pep Level 2 |
| Ministry of Agriculture and Livestock Development                                                                   | 🇳🇵 Nepal                            | Pep Level 2 |
| Ministry of Energy                                                                                                  | 🇳🇵 Nepal                            | Pep Level 2 |
| Ministry of Education - Science and Technology                                                                      | 🇳🇵 Nepal                            | Pep Level 2 |
| Ministry of Health and Population                                                                                   | 🇳🇵 Nepal                            | Pep Level 2 |
| Ministry of Physical Infrastructure and Transport                                                                   | 🇳🇵 Nepal                            | Pep Level 2 |
| Chitwan National Park                                                                                               | 🇳🇵 Nepal                            | SIP         |
| House of Representatives of the Netherlands                                                                         | 🇳🇱 Netherlands                      | Pep Level 1 |
| Party for Freedom (PVV)                                                                                             | 🇳🇱 Netherlands                      | Pep Level 3 |
| Autoriteit Consument & Markt (ACM.nl)                                                                               | 🇳🇱 Netherlands                      | SIE         |
| Opgelicht?! - AVROTROS                                                                                              | 🇳🇱 Netherlands                      | SIP         |
| Parliament of New Zealand                                                                                           | 🇳🇿 New Zealand                      | Pep Level 1 |
| NEW ZEALAND - RBNZ-ALERT - Reserve Bank of New Zealand-Alert                                                        | 🇳🇿 New Zealand                      | SIE         |
| Immigration New Zealand                                                                                             | 🇳🇿 New Zealand                      | SIP         |
| National Assembly of Nicaragua                                                                                      | 🇳🇮 Nicaragua                        | Pep Level 1 |
| Procuraduría General de la República – PGR                                                                          | 🇳🇮 Nicaragua                        | SIP         |
| National Assembly of Niger                                                                                          | 🇳🇪 Niger                            | Pep Level 1 |
| National Assembly of Nigeria                                                                                        | 🇳🇬 Nigeria                          | Pep Level 1 |
| Ministry of Finance                                                                                                 | 🇳🇬 Nigeria                          | Pep Level 2 |
| Nigerian National Petroleum Corporation (NNPC)                                                                      | 🇳🇬 Nigeria                          | Pep Level 2 |
| Nigeria Sovereign Investment Authority (NSIA)                                                                       | 🇳🇬 Nigeria                          | Pep Level 2 |
| Senate (Nigeria)                                                                                                    | 🇳🇬 Nigeria                          | Pep Level 2 |
| Nigeria House of Representatives                                                                                    | 🇳🇬 Nigeria                          | Pep Level 2 |
| Ministry of Petroleum Resources                                                                                     | 🇳🇬 Nigeria                          | Pep Level 2 |
| Ministry of Power                                                                                                   | 🇳🇬 Nigeria                          | Pep Level 2 |
| Ministry of Works and Housing                                                                                       | 🇳🇬 Nigeria                          | Pep Level 2 |
| Ministry of Transportation                                                                                          | 🇳🇬 Nigeria                          | Pep Level 2 |
| Bank of Industry                                                                                                    | 🇳🇬 Nigeria                          | Pep Level 3 |
| National Broadcasting Commission                                                                                    | 🇳🇬 Nigeria                          | Pep Level 3 |
| Nigeria Immigration Service                                                                                         | 🇳🇬 Nigeria                          | Pep Level 3 |
| Nigerian National Petroleum Corporation (NNPC)                                                                      | 🇳🇬 Nigeria                          | Pep Level 3 |
| Nigerian Senate                                                                                                     | 🇳🇬 Nigeria                          | Pep Level 3 |
| Bureau of Public Enterprises                                                                                        | 🇳🇬 Nigeria                          | Pep Level 4 |
| Lagos State Government                                                                                              | 🇳🇬 Nigeria                          | Pep Level 4 |
| Daily Post Nigeria                                                                                                  | 🇳🇬 Nigeria                          | SIE         |
| NIGERIA - NDLEA - NATIONAL DRUG LAW ENFORCEMENT AGENCY                                                              | 🇳🇬 Nigeria                          | SIP         |
| Parliament of Niue                                                                                                  | 🇳🇺 Niue                             | Pep Level 1 |
| Parliament of North Korea                                                                                           | 🇰🇵 North Korea                      | Pep Level 1 |
| Maritime Safety Information                                                                                         | 🇰🇵 North Korea                      | SIE         |
| James Martin Center for Nonproliferation Studies                                                                    | 🇰🇵 North Korea                      | SIP         |
| Parliament of North Macedonia                                                                                       | 🇲🇰 North Macedonia                  | Pep Level 1 |
| SLOVENIA - SLOVENIAN SECURITIES MARKET AGENCY - SISMA                                                               | 🇸🇮 Slovenia                         | SIE         |
| P4 Radio Hele Norge                                                                                                 | 🇳🇴 Norway                           | SIP         |
| National Assembly of Oman                                                                                           | 🇴🇲 Oman                             | Pep Level 1 |
| National Assembly of Pakistan                                                                                       | 🇵🇰 Pakistan                         | Pep Level 1 |
| Pakistan Muslim League (Nawaz) – PML(N)                                                                             | 🇵🇰 Pakistan                         | Pep Level 3 |
| Pakistan People's Party (PPP)                                                                                       | 🇵🇰 Pakistan                         | Pep Level 3 |
| Tehrik-i-Taliban Pakistan (TTP)                                                                                     | 🇵🇰 Pakistan                         | Pep Level 3 |
| Hizbul Mujahideen                                                                                                   | 🇵🇰 Pakistan                         | Pep Level 3 |
| Bilal Fibres Limited                                                                                                | 🇵🇰 Pakistan                         | SIP         |
| House of Representatives of Palau                                                                                   | 🇵🇼 Palau                            | Pep Level 1 |
| Palestinian Legislative Council (PLC)                                                                               | 🇵🇸 Palestine                        | Pep Level 1 |
| Palestinian People's Party (PPP)                                                                                    | 🇵🇸 Palestine                        | Pep Level 2 |
| Ministry of the Interior                                                                                            | 🇵🇸 Palestine                        | Pep Level 2 |
| Ministry of Foreign Affairs                                                                                         | 🇵🇸 Palestine                        | Pep Level 2 |
| Ministry of Finance                                                                                                 | 🇵🇸 Palestine                        | Pep Level 2 |
| Ministry of National Economy                                                                                        | 🇵🇸 Palestine                        | Pep Level 2 |
| Ministry of Education                                                                                               | 🇵🇸 Palestine                        | Pep Level 2 |
| Ministry of Health                                                                                                  | 🇵🇸 Palestine                        | Pep Level 2 |
| Ministry of Agriculture                                                                                             | 🇵🇸 Palestine                        | Pep Level 2 |
| Ministry of Justice                                                                                                 | 🇵🇸 Palestine                        | Pep Level 2 |
| Ministry of Labor                                                                                                   | 🇵🇸 Palestine                        | Pep Level 2 |
| Palestinian Monetary Authority (PMA)                                                                                | 🇵🇸 Palestine                        | Pep Level 3 |
| National Assembly of Panama                                                                                         | 🇵🇦 Panama                           | Pep Level 1 |
| PANAMA - PASSRP - Superintendence of Insurance and Reinsurance of Panama                                            | 🇵🇦 Panama                           | SIE         |
| PANAMA - PAMP-MW - Public Ministry of Panama - Most Wanted                                                          | 🇵🇦 Panama                           | SIP         |
| Parliament of Papua New Guinea                                                                                      | 🇵🇬 Papua New Guinea                 | Pep Level 1 |
| Papua New Guinea Treasury                                                                                           | 🇵🇬 Papua New Guinea                 | Pep Level 3 |
| National Assembly of Paraguay                                                                                       | 🇵🇾 Paraguay                         | Pep Level 1 |
| ADN Paraguayo - ADN Digital                                                                                         | 🇵🇾 Paraguay                         | SIP         |
| House of Representatives of Peru                                                                                    | 🇵🇪 Peru                             | Pep Level 1 |
| PERU - INDECOPI - National Institute for Free Competition and Protection of Intellectual Property                   | 🇵🇪 Peru                             | SIE         |
| Beneficencia de Lima                                                                                                | 🇵🇪 Peru                             | SIP         |
| House of Representatives of the Philippines                                                                         | 🇵🇭 Philippines                      | Pep Level 1 |
| Research Institute for Tropical Medicine                                                                            | 🇵🇭 Philippines                      | Pep Level 2 |
| Land Bank of the Philippines                                                                                        | 🇵🇭 Philippines                      | Pep Level 3 |
| Civil Aviation Authority of the Philippines                                                                         | 🇵🇭 Philippines                      | Pep Level 3 |
| National Economic and Development Authority                                                                         | 🇵🇭 Philippines                      | Pep Level 3 |
| Philippines Bureau of Customs                                                                                       | 🇵🇭 Philippines                      | Pep Level 3 |
| Philippines House of Representatives                                                                                | 🇵🇭 Philippines                      | Pep Level 3 |
| Cebu City Government                                                                                                | 🇵🇭 Philippines                      | Pep Level 4 |
| Philippines Business Database                                                                                       | 🇵🇭 Philippines                      | SIE         |
| PHILIPPINES - PHPNP - Philippine National Police Most Wanted                                                        | 🇵🇭 Philippines                      | SIP         |
| House of Representatives of Poland                                                                                  | 🇵🇱 Poland                           | Pep Level 1 |
| Senate of the Republic of the Poland                                                                                | 🇵🇱 Poland                           | Pep Level 1 |
| National Electoral Office                                                                                           | 🇵🇱 Poland                           | Pep Level 2 |
| Office of Competition and Consumer Protection (UOKiK)                                                               | 🇵🇱 Poland                           | Pep Level 2 |
| Ministry of Internal Affairs and Administration                                                                     | 🇵🇱 Poland                           | Pep Level 2 |
| Ministry of Maritime Economy and Inland Navigation                                                                  | 🇵🇱 Poland                           | Pep Level 2 |
| Ministry of Justice                                                                                                 | 🇵🇱 Poland                           | Pep Level 2 |
| Ministry of National Defense                                                                                        | 🇵🇱 Poland                           | Pep Level 2 |
| Ministry of Investment and Economic Development                                                                     | 🇵🇱 Poland                           | Pep Level 2 |
| Ministry of Energy                                                                                                  | 🇵🇱 Poland                           | Pep Level 2 |
| Ministry of Labor and Social Policy                                                                                 | 🇵🇱 Poland                           | Pep Level 2 |
| Ministry of Science and Higher Education                                                                            | 🇵🇱 Poland                           | Pep Level 2 |
| Ministry of Family                                                                                                  | 🇵🇱 Poland                           | Pep Level 2 |
| Ministry of National Education                                                                                      | 🇵🇱 Poland                           | Pep Level 2 |
| Ministry of the Environment                                                                                         | 🇵🇱 Poland                           | Pep Level 2 |
| Ministry of Infrastructure                                                                                          | 🇵🇱 Poland                           | Pep Level 2 |
| Ministry of Health                                                                                                  | 🇵🇱 Poland                           | Pep Level 2 |
| Ministry of Digital Affairs                                                                                         | 🇵🇱 Poland                           | Pep Level 2 |
| Ministry of Sport and Tourism                                                                                       | 🇵🇱 Poland                           | Pep Level 2 |
| Ministry of Regional Development                                                                                    | 🇵🇱 Poland                           | Pep Level 2 |
| Financial Supervision Authority (KNF)                                                                               | 🇵🇱 Poland                           | Pep Level 2 |
| Public Procurement Office                                                                                           | 🇵🇱 Poland                           | Pep Level 2 |
| General Prosecutor's Office                                                                                         | 🇵🇱 Poland                           | Pep Level 2 |
| National Security Bureau                                                                                            | 🇵🇱 Poland                           | Pep Level 2 |
| Committee for Financial Supervision (KNF)                                                                           | 🇵🇱 Poland                           | Pep Level 2 |
| Stocznia Marynarki Wojennej S.A.                                                                                    | 🇵🇱 Poland                           | Pep Level 3 |
| City of Kraków                                                                                                      | 🇵🇱 Poland                           | Pep Level 4 |
| Business Insider Polska                                                                                             | 🇵🇱 Poland                           | SIE         |
| Urząd Gminy Bielice                                                                                                 | 🇵🇱 Poland                           | SIP         |
| National Assembly of Portugal                                                                                       | 🇵🇹 Portugal                         | Pep Level 1 |
| Caixa Geral de Depósitos                                                                                            | 🇵🇹 Portugal                         | Pep Level 3 |
| Banco Português de Gestão (BPG)                                                                                     | 🇵🇹 Portugal                         | SIE         |
| TSF Rádio Notícias                                                                                                  | 🇵🇹 Portugal                         | SIP         |
| Puerto Rico Online                                                                                                  | 🇵🇷 Puerto Rico                      | SIE         |
| St. John Source                                                                                                     | 🇵🇷 Puerto Rico                      | SIP         |
| House of Representatives of Qatar                                                                                   | 🇶🇦 Qatar                            | Pep Level 1 |
| Qatar Financial Centre Regulatory Authority (QFCRA)                                                                 | 🇶🇦 Qatar                            | SIE         |
| Central Registry of North Macedonia                                                                                 | 🇲🇰 Republic of North Macedonia      | SIE         |
| EU - EUMW - Europe's Most Wanted                                                                                    | 🇲🇰 Republic of North Macedonia      | SIP         |
| National Assembly of Romania                                                                                        | 🇷🇴 Romania                          | Pep Level 1 |
| Romanian Radio Broadcasting Company (Radio Romania)                                                                 | 🇷🇴 Romania                          | Pep Level 3 |
| Generali Societate de Administrare a Fondurilor de Pensii Private S.A.                                              | 🇷🇴 Romania                          | SIE         |
| Нижегородский областной суд                                                                                         | 🇷🇺 Russia                           | SIP         |
| Russian Ministry of Defense (Northern Fleet)                                                                        | 🇷🇺 Russia                           | Pep Level 2 |
| Biysk Urban Okrug (Altai Krai)                                                                                      | 🇷🇺 Russia                           | Pep Level 4 |
| Ust-Kutsky Municipal District (Irkutsk Oblast)                                                                      | 🇷🇺 Russia                           | Pep Level 4 |
| Moscow City Government                                                                                              | 🇷🇺 Russia                           | Pep Level 4 |
| Khabarovsk Krai Government                                                                                          | 🇷🇺 Russia                           | Pep Level 4 |
| Legal Entity Identifier                                                                                             | 🇷🇺 Russia                           | SIP         |
| House of Representatives of Rwanda                                                                                  | 🇷🇼 Rwanda                           | Pep Level 1 |
| National Electoral Commission                                                                                       | 🇷🇼 Rwanda                           | Pep Level 2 |
| Rwanda National Police                                                                                              | 🇷🇼 Rwanda                           | Pep Level 2 |
| Office of the Prime Minister                                                                                        | 🇷🇼 Rwanda                           | Pep Level 2 |
| Rwanda Development Board (RDB)                                                                                      | 🇷🇼 Rwanda                           | Pep Level 2 |
| Ministry of Finance and Economic Planning                                                                           | 🇷🇼 Rwanda                           | Pep Level 2 |
| Ministry of Defense                                                                                                 | 🇷🇼 Rwanda                           | Pep Level 2 |
| Rwanda Utilities Regulatory Authority (RURA)                                                                        | 🇷🇼 Rwanda                           | Pep Level 2 |
| National Security Council                                                                                           | 🇷🇼 Rwanda                           | Pep Level 2 |
| Rwanda Biomedical Center                                                                                            | 🇷🇼 Rwanda                           | Pep Level 2 |
| Rwanda Broadcasting Agency                                                                                          | 🇷🇼 Rwanda                           | Pep Level 2 |
| Rwanda Agriculture Board (RAB)                                                                                      | 🇷🇼 Rwanda                           | Pep Level 2 |
| Rwanda Governance Board                                                                                             | 🇷🇼 Rwanda                           | Pep Level 2 |
| Ministry of Education                                                                                               | 🇷🇼 Rwanda                           | Pep Level 2 |
| Ministry of Gender and Family Promotion                                                                             | 🇷🇼 Rwanda                           | Pep Level 2 |
| Ministry of Trade and Industry                                                                                      | 🇷🇼 Rwanda                           | Pep Level 2 |
| Ministry of Youth and Culture                                                                                       | 🇷🇼 Rwanda                           | Pep Level 2 |
| Ministry of Sports                                                                                                  | 🇷🇼 Rwanda                           | Pep Level 2 |
| Ministry of Health                                                                                                  | 🇷🇼 Rwanda                           | Pep Level 2 |
| Ministry of Local Government                                                                                        | 🇷🇼 Rwanda                           | Pep Level 4 |
| Kigali City Council                                                                                                 | 🇷🇼 Rwanda                           | Pep Level 4 |
| RWANDA - RWOMBUD - Rwanda Office of the Ombudsman                                                                   | 🇷🇼 Rwanda                           | SIP         |
| National Assembly of São Tomé and Príncipe                                                                          | 🇸🇹 São Tomé and Príncipe            | Pep Level 1 |
| São Tomé and Príncipe Central Bank                                                                                  | 🇸🇹 São Tomé and Príncipe            | Pep Level 3 |
| House of Representatives of Saint Kitts and Nevis                                                                   | 🇰🇳 Saint Kitts and Nevis            | Pep Level 1 |
| St Kitts and Nevis Labour Party                                                                                     | 🇰🇳 Saint Kitts and Nevis            | Pep Level 3 |
| House of Representatives of Saint Lucia                                                                             | 🇱🇨 Saint Lucia                      | Pep Level 1 |
| St Lucia Mortgage Finance Company Ltd.                                                                              | 🇱🇨 Saint Lucia                      | Pep Level 3 |
| Government of Kazakhstan                                                                                            | 🇰🇿 Kazakhstan                       | SIE         |
| Trinity Washington University                                                                                       | 🇻🇨 Saint Vincent And The Grenadines | SIP         |
| House of Assembly of Saint Vincent and the Grenadines                                                               | 🇻🇨 Saint Vincent and the Grenadines | Pep Level 1 |
| Saint Vincent and the Grenadines Tourism Authority                                                                  | 🇻🇨 Saint Vincent and the Grenadines | Pep Level 3 |
| National Legislative Assembly                                                                                       | 🇼🇸 Samoa                            | Pep Level 1 |
| Parliament of San Marino                                                                                            | 🇸🇲 San Marino                       | Pep Level 1 |
| Tribuna Politica Web.sm                                                                                             | 🇸🇲 San Marino                       | SIP         |
| National Assembly of Saudi Arabia                                                                                   | 🇸🇦 Saudi Arabia                     | Pep Level 1 |
| Ministry of Interior                                                                                                | 🇸🇦 Saudi Arabia                     | Pep Level 3 |
| Ministry of Islamic Affairs                                                                                         | 🇸🇦 Saudi Arabia                     | Pep Level 3 |
| Ministry of Hajj and Umrah                                                                                          | 🇸🇦 Saudi Arabia                     | Pep Level 3 |
| Ministry of Culture                                                                                                 | 🇸🇦 Saudi Arabia                     | Pep Level 3 |
| Ministry of Labor and Social Development                                                                            | 🇸🇦 Saudi Arabia                     | Pep Level 3 |
| Ministry of Education                                                                                               | 🇸🇦 Saudi Arabia                     | Pep Level 3 |
| Ministry of Defense                                                                                                 | 🇸🇦 Saudi Arabia                     | Pep Level 3 |
| Ministry of Foreign Affairs                                                                                         | 🇸🇦 Saudi Arabia                     | Pep Level 3 |
| Ministry of Finance                                                                                                 | 🇸🇦 Saudi Arabia                     | Pep Level 3 |
| Ministry of Health                                                                                                  | 🇸🇦 Saudi Arabia                     | Pep Level 3 |
| Ministry of Communications and Information Technology                                                               | 🇸🇦 Saudi Arabia                     | Pep Level 3 |
| Ministry of Commerce and Investment                                                                                 | 🇸🇦 Saudi Arabia                     | Pep Level 3 |
| Ministry of Energy and Mineral Resources                                                                            | 🇸🇦 Saudi Arabia                     | Pep Level 3 |
| Ministry of Housing                                                                                                 | 🇸🇦 Saudi Arabia                     | Pep Level 3 |
| Ministry of Justice                                                                                                 | 🇸🇦 Saudi Arabia                     | Pep Level 3 |
| Ministry of Municipal and Rural Affairs                                                                             | 🇸🇦 Saudi Arabia                     | Pep Level 3 |
| Ministry of Transport                                                                                               | 🇸🇦 Saudi Arabia                     | Pep Level 3 |
| Ministry of Water                                                                                                   | 🇸🇦 Saudi Arabia                     | Pep Level 3 |
| Ministry of Economy and Planning                                                                                    | 🇸🇦 Saudi Arabia                     | Pep Level 3 |
| Ministry of Civil Service                                                                                           | 🇸🇦 Saudi Arabia                     | Pep Level 3 |
| Ministry of Environment - Water and Agriculture                                                                     | 🇸🇦 Saudi Arabia                     | Pep Level 3 |
| Ministry of Communications                                                                                          | 🇸🇦 Saudi Arabia                     | Pep Level 3 |
| National Assembly of Senegal                                                                                        | 🇸🇳 Senegal                          | Pep Level 1 |
| National Assembly of Serbia                                                                                         | 🇷🇸 Serbia                           | Pep Level 1 |
| Company for Forests in Serbia (Srbijašume)                                                                          | 🇷🇸 Serbia                           | Pep Level 3 |
| SLOVENIA - SLOVENIAN GENERAL POLICE DIRECTORATE - SIGPD                                                             | 🇸🇮 Slovenia                         | SIP         |
| National Assembly of Seychelles                                                                                     | 🇸🇨 Seychelles                       | Pep Level 1 |
| SEYCHELLES - FINANCIAL SERVICES AUTHORITY SEYCHELLES - SYFSA                                                        | 🇸🇨 Seychelles                       | SIE         |
| National Assembly of Sierra Leone                                                                                   | 🇸🇱 Sierra Leone                     | Pep Level 1 |
| National Elections Commission                                                                                       | 🇸🇱 Sierra Leone                     | Pep Level 2 |
| Ministry of Culture                                                                                                 | 🇸🇱 Sierra Leone                     | Pep Level 2 |
| Ministry of Health                                                                                                  | 🇸🇱 Sierra Leone                     | Pep Level 2 |
| Ministry of Defense                                                                                                 | 🇸🇱 Sierra Leone                     | Pep Level 2 |
| Ministry of Finance                                                                                                 | 🇸🇱 Sierra Leone                     | Pep Level 2 |
| Ministry of Foreign Affairs                                                                                         | 🇸🇱 Sierra Leone                     | Pep Level 2 |
| Concord Times Communication                                                                                         | 🇸🇱 Sierra Leone                     | SIP         |
| Parliament of Singapore                                                                                             | 🇸🇬 Singapore                        | Pep Level 1 |
| Ministry of Defense                                                                                                 | 🇸🇬 Singapore                        | Pep Level 3 |
| Ministry of Education                                                                                               | 🇸🇬 Singapore                        | Pep Level 3 |
| Ministry of Finance                                                                                                 | 🇸🇬 Singapore                        | Pep Level 3 |
| Ministry of Foreign Affairs                                                                                         | 🇸🇬 Singapore                        | Pep Level 3 |
| Ministry of Health                                                                                                  | 🇸🇬 Singapore                        | Pep Level 3 |
| Ministry of Home Affairs                                                                                            | 🇸🇬 Singapore                        | Pep Level 3 |
| Ministry of Law                                                                                                     | 🇸🇬 Singapore                        | Pep Level 3 |
| Ministry of Manpower                                                                                                | 🇸🇬 Singapore                        | Pep Level 3 |
| Ministry of National Development                                                                                    | 🇸🇬 Singapore                        | Pep Level 3 |
| Ministry of Social and Family Development                                                                           | 🇸🇬 Singapore                        | Pep Level 3 |
| Ministry of the Environment and Water Resources                                                                     | 🇸🇬 Singapore                        | Pep Level 3 |
| Ministry of Trade and Industry                                                                                      | 🇸🇬 Singapore                        | Pep Level 3 |
| Ministry of Transport                                                                                               | 🇸🇬 Singapore                        | Pep Level 3 |
| SINGAPORE - MASW - Monetary Authority Warnings                                                                      | 🇸🇬 Singapore                        | SIE         |
| Državno odvjetništvo Republike Hrvatske                                                                             | 🇭🇷 Croatia                          | SIP         |
| National Assembly of Slovakia                                                                                       | 🇸🇰 Slovakia                         | Pep Level 1 |
| Ministry of Interior                                                                                                | 🇸🇰 Slovakia                         | Pep Level 2 |
| Corrupt Practices Investigation Bureau                                                                              | 🇸🇰 Slovakia                         | SIP         |
| National Assembly of Slovenia                                                                                       | 🇸🇮 Slovenia                         | Pep Level 1 |
| Local Government of Krško                                                                                           | 🇸🇮 Slovenia                         | Pep Level 4 |
| National Assembly of the Solomon Islands                                                                            | 🇸🇧 Solomon Islands                  | Pep Level 1 |
| Honiara City Council                                                                                                | 🇸🇧 Solomon Islands                  | Pep Level 4 |
| House of Representatives of Somalia                                                                                 | 🇸🇴 Somalia                          | Pep Level 1 |
| Ministerstvo spravodlivosti SR                                                                                      | 🇸🇰 Slovakia                         | SIP         |
| National Assembly of South Africa                                                                                   | 🇿🇦 South Africa                     | Pep Level 1 |
| National Council of Provinces                                                                                       | 🇿🇦 South Africa                     | Pep Level 2 |
| Legal Aid South Africa                                                                                              | 🇿🇦 South Africa                     | Pep Level 3 |
| Paramount Group (South Africa)                                                                                      | 🇿🇦 South Africa                     | Pep Level 3 |
| Superb Maize (inferred)                                                                                             | 🇿🇦 South Africa                     | SIE         |
| Il Caffè Geopolitico                                                                                                | 🇮🇹 Italy                            | SIP         |
| National Assembly of South Korea                                                                                    | 🇰🇷 South Korea                      | Pep Level 1 |
| KOREA, SOUTH - KRFSS - Korea Financial Supervisory Service                                                          | 🇰🇷 South Korea                      | SIE         |
| Free State Weekly                                                                                                   | 🇰🇷 South Korea                      | SIP         |
| National Assembly of South Sudan                                                                                    | 🇸🇸 South Sudan                      | Pep Level 1 |
| South Sudan Democratic Movement (SSDM)                                                                              | 🇸🇸 South Sudan                      | Pep Level 3 |
| Warrap State Government                                                                                             | 🇸🇸 South Sudan                      | Pep Level 4 |
| Congress of Spain                                                                                                   | 🇪🇸 Spain                            | Pep Level 1 |
| SPAIN - CNMV - Com. Nacional Del Mercado De Valores                                                                 | 🇪🇸 Spain                            | SIE         |
| Agencia Mayorista de Viajes a Cuba - Guama                                                                          | 🇪🇸 Spain                            | SIE         |
| SPAIN - ESGC-MW - Guardia Civil - Most Wanted                                                                       | 🇪🇸 Spain                            | SIP         |
| La Voz de Gran Canaria                                                                                              | 🇪🇸 Spain                            | SIP         |
| Parliament of Sri Lanka                                                                                             | 🇱🇰 Sri Lanka                        | Pep Level 1 |
| Bar Association of Sri Lanka (BASL)                                                                                 | 🇱🇰 Sri Lanka                        | Pep Level 2 |
| United National Party (UNP)                                                                                         | 🇱🇰 Sri Lanka                        | Pep Level 3 |
| United National Front (Sri Lanka)                                                                                   | 🇱🇰 Sri Lanka                        | Pep Level 3 |
| Ceylon Electricity Board (CEB)                                                                                      | 🇱🇰 Sri Lanka                        | Pep Level 3 |
| Sri Lanka Ports Authority (SLPA)                                                                                    | 🇱🇰 Sri Lanka                        | Pep Level 3 |
| Sri Lanka Freedom Party (SLFP)                                                                                      | 🇱🇰 Sri Lanka                        | Pep Level 3 |
| Parliament of Sudan                                                                                                 | 🇸🇩 Sudan                            | Pep Level 1 |
| ھیئة الموانىء البحریة - السودان                                                                                     | 🇸🇩 Sudan                            | SIE         |
| Parliament of Suriname                                                                                              | 🇸🇷 Suriname                         | Pep Level 1 |
| National Assembly of Sweden                                                                                         | 🇸🇪 Sweden                           | Pep Level 1 |
| Ministry of Employment                                                                                              | 🇸🇪 Sweden                           | Pep Level 2 |
| Modern Times Group                                                                                                  | 🇸🇪 Sweden                           | SIE         |
| National Assembly of Switzerland                                                                                    | 🇨🇭 Switzerland                      | Pep Level 1 |
| Federal Assembly (Bundesversammlung)                                                                                | 🇨🇭 Switzerland                      | Pep Level 2 |
| HSBC Global Private Banking                                                                                         | 🇨🇭 Switzerland                      | SIE         |
| Katsura Suzuki GmbH                                                                                                 | 🇨🇭 Switzerland                      | SIP         |
| National Assembly of Syria                                                                                          | 🇸🇾 Syria                            | Pep Level 1 |
| Free Syrian Army (FSA)                                                                                              | 🇸🇾 Syria                            | Pep Level 3 |
| Syrian Democratic Forces (SDF)                                                                                      | 🇸🇾 Syria                            | Pep Level 3 |
| Travel Weekly Asia                                                                                                  | 🇸🇾 Syria                            | SIE         |
| The Syrian Observer                                                                                                 | 🇸🇾 Syria                            | SIP         |
| TURKEY - TRCA - Turkey Competition Authority                                                                        | 🇹🇷 Türkiye                          | SIE         |
| Stockholm Center for Freedom                                                                                        | 🇹🇷 Türkiye                          | SIP         |
| National Assembly of Taiwan (Legislative Yuan)                                                                      | 🇹🇼 Taiwan                           | Pep Level 1 |
| Tainan City Council                                                                                                 | 🇹🇼 Taiwan                           | Pep Level 4 |
| Taipei City Government                                                                                              | 🇹🇼 Taiwan                           | Pep Level 4 |
| 富邦金控 Fubon Financial                                                                                                | 🇹🇼 Taiwan                           | SIE         |
| Báo Phụ Nữ                                                                                                          | 🇻🇳 Vietnam                          | SIP         |
| National Assembly of Tajikistan                                                                                     | 🇹🇯 Tajikistan                       | Pep Level 1 |
| Tajik Aluminium Company (TALCO)                                                                                     | 🇹🇯 Tajikistan                       | Pep Level 3 |
| National Bank of Tajikistan                                                                                         | 🇹🇯 Tajikistan                       | Pep Level 3 |
| National Assembly of Tanzania                                                                                       | 🇹🇿 Tanzania                         | Pep Level 1 |
| National Assembly of Thailand                                                                                       | 🇹🇭 Thailand                         | Pep Level 1 |
| Electricity Generating Authority of Thailand International Co.Ltd                                                   | 🇹🇭 Thailand                         | Pep Level 3 |
| THAILAND - SECTHAI - Sec. Exchange Comm.                                                                            | 🇹🇭 Thailand                         | SIE         |
| 77 ขาวเด็ด - 77 จังหวัด                                                                                             | 🇹🇭 Thailand                         | SIP         |
| Bahamas Financial Services Board                                                                                    | 🇧🇸 The Bahamas                      | SIE         |
| Gambia Tourism Board                                                                                                | 🇬🇲 The Gambia                       | SIP         |
| Central Tibetan Administration                                                                                      | 🇨🇳 Tibet                            | Pep Level 3 |
| National Assembly of Togo                                                                                           | 🇹🇬 Togo                             | Pep Level 1 |
| EAGLE Togo – Eco Activists for Governance and Law Enforcement                                                       | 🇹🇬 Togo                             | SIP         |
| Tonga Legislative Assembly                                                                                          | 🇹🇴 Tonga                            | Pep Level 1 |
| House of Assembly of Trinidad and Tobago                                                                            | 🇹🇹 Trinidad and Tobago              | Pep Level 1 |
| Akun Demo Slot, Demo Pragmatic, Demo PG Soft, Demo Habanero, Slot Demo Online                                       | 🇹🇹 Trinidad and Tobago              | SIE         |
| Financial Intelligence Unit – Trinidad and Tobago                                                                   | 🇹🇹 Trinidad and Tobago              | SIP         |
| House of Representatives of Tunisia                                                                                 | 🇹🇳 Tunisia                          | Pep Level 1 |
| Tunisia Stock Exchange                                                                                              | 🇹🇳 Tunisia                          | Pep Level 3 |
| Tunisian General Labour Union (UGTT)                                                                                | 🇹🇳 Tunisia                          | Pep Level 3 |
| Tunis Governorate                                                                                                   | 🇹🇳 Tunisia                          | Pep Level 4 |
| Agenzia Giornalistica Italia (AGI)                                                                                  | 🇹🇳 Tunisia                          | SIP         |
| Grand National Assembly of Turkey                                                                                   | 🇹🇷 Turkey                           | Pep Level 1 |
| Parliament of Turkmenistan                                                                                          | 🇹🇲 Turkmenistan                     | Pep Level 1 |
| Parliament of Tuvalu                                                                                                | 🇹🇻 Tuvalu                           | Pep Level 1 |
| Tuvalu government's public relations agency                                                                         | 🇹🇻 Tuvalu                           | Pep Level 3 |
| Parliament of Uganda                                                                                                | 🇺🇬 Uganda                           | Pep Level 1 |
| Uganda National Council for Science and Technology                                                                  | 🇺🇬 Uganda                           | Pep Level 2 |
| Kabale District Local Government                                                                                    | 🇺🇬 Uganda                           | Pep Level 2 |
| Local Government of Napak District                                                                                  | 🇺🇬 Uganda                           | Pep Level 4 |
| Ministry of Local Government                                                                                        | 🇺🇬 Uganda                           | Pep Level 4 |
| UGANDA - UGPPDA - Ugandan Public Procurement and Disposal of Public Assets Authority                                | 🇺🇬 Uganda                           | SIE         |
| Front Line Defenders                                                                                                | 🇺🇬 Uganda                           | SIP         |
| Parliament of Ukraine                                                                                               | 🇺🇦 Ukraine                          | Pep Level 1 |
| Cabinet of Ministers (Ukraine)                                                                                      | 🇺🇦 Ukraine                          | Pep Level 2 |
| Ministry of Interior                                                                                                | 🇺🇦 Ukraine                          | Pep Level 2 |
| Ministry of Defense                                                                                                 | 🇺🇦 Ukraine                          | Pep Level 2 |
| Ministry of Foreign Affairs                                                                                         | 🇺🇦 Ukraine                          | Pep Level 2 |
| Ministry of Energy                                                                                                  | 🇺🇦 Ukraine                          | Pep Level 2 |
| Ministry of Health                                                                                                  | 🇺🇦 Ukraine                          | Pep Level 2 |
| Ministry of Finance                                                                                                 | 🇺🇦 Ukraine                          | Pep Level 2 |
| Verkhovna Rada (Parliament of Ukraine)                                                                              | 🇺🇦 Ukraine                          | Pep Level 2 |
| Ministry of Digital Transformation                                                                                  | 🇺🇦 Ukraine                          | Pep Level 2 |
| Ministry of Reintegration of Temporarily Occupied Territories                                                       | 🇺🇦 Ukraine                          | Pep Level 2 |
| Ministry of Veterans Affairs                                                                                        | 🇺🇦 Ukraine                          | Pep Level 2 |
| Ministry of Strategic Industries                                                                                    | 🇺🇦 Ukraine                          | Pep Level 2 |
| Ministry of Internal Affairs                                                                                        | 🇺🇦 Ukraine                          | Pep Level 2 |
| Office of the President                                                                                             | 🇺🇦 Ukraine                          | Pep Level 2 |
| Opposition Bloc                                                                                                     | 🇺🇦 Ukraine                          | Pep Level 3 |
| Odessa Regional State Administration                                                                                | 🇺🇦 Ukraine                          | Pep Level 4 |
| Mykolaiv Regional State Administration                                                                              | 🇺🇦 Ukraine                          | Pep Level 4 |
| UKRAINE - Enterprises of Ukraine                                                                                    | 🇺🇦 Ukraine                          | SIE         |
| HUNGARY - HUPOL - Hungarian Police Wanted                                                                           | 🇺🇦 Ukraine                          | SIP         |
| Dubai Municipality                                                                                                  | 🇦🇪 United Arab Emirates             | Pep Level 4 |
| Committee on Homeland Security & Governmental Affairs                                                               | 🇦🇪 United Arab Emirates             | SIE         |
| House of Commons of the United Kingdom                                                                              | 🇬🇧 United Kingdom                   | Pep Level 1 |
| University of St. Andrews                                                                                           | 🇬🇧 United Kingdom                   | Pep Level 2 |
| National Cyber Security Centre                                                                                      | 🇬🇧 United Kingdom                   | Pep Level 2 |
| Local Government Association (LGA)                                                                                  | 🇬🇧 United Kingdom                   | Pep Level 3 |
| Lambeth London Borough Council                                                                                      | 🇬🇧 United Kingdom                   | Pep Level 4 |
| London Borough of Hackney                                                                                           | 🇬🇧 United Kingdom                   | Pep Level 4 |
| Royal Borough of Kensington and Chelsea                                                                             | 🇬🇧 United Kingdom                   | Pep Level 4 |
| Organized Crime and Corruption Reporting Project - OCCRP                                                            | 🇬🇧 United Kingdom                   | SIE         |
| Bradford Telegraph and Argus                                                                                        | 🇬🇧 United Kingdom                   | SIP         |
| House of Representatives of the United States                                                                       | 🇺🇸 United States                    | Pep Level 1 |
| Federal Communications Commission                                                                                   | 🇺🇸 United States                    | Pep Level 2 |
| Ministry of Homeland Security                                                                                       | 🇺🇸 United States                    | Pep Level 2 |
| Puerto Rico Department of Treasury                                                                                  | 🇺🇸 United States                    | Pep Level 2 |
| Government Accountability Office (GAO)                                                                              | 🇺🇸 United States                    | Pep Level 3 |
| Delaware Department of State                                                                                        | 🇺🇸 United States                    | Pep Level 4 |
| State of Utah                                                                                                       | 🇺🇸 United States                    | Pep Level 4 |
| New York Companies Search Services                                                                                  | 🇺🇸 United States                    | SIE         |
| Department of Justice                                                                                               | 🇺🇸 United States                    | SIP         |
| CyberCrime & Doing Time                                                                                             | 🇺🇸 United States                    | SIP         |
| Parliament of Uruguay                                                                                               | 🇺🇾 Uruguay                          | Pep Level 1 |
| URUGUAY - BCUSSF - Central Bank of Uruguay - Superintendency of Financial Services                                  | 🇺🇾 Uruguay                          | SIE         |
| URUGUAY - UYMI-SI - Ministry of Interior of Uruguay - Sentenced Individuals                                         | 🇺🇾 Uruguay                          | SIP         |
| Parliament of Uzbekistan                                                                                            | 🇺🇿 Uzbekistan                       | Pep Level 1 |
| UZBEKISTAN - UZGUVD - Department of Internal Affairs of Tashkent - Wanted                                           | 🇺🇿 Uzbekistan                       | SIP         |
| House of Representatives of Vanuatu                                                                                 | 🇻🇺 Vanuatu                          | Pep Level 1 |
| National Assembly of Vatican City                                                                                   | 🇻🇦 Vatican City                     | Pep Level 1 |
| National Assembly of Venezuela                                                                                      | 🇻🇪 Venezuela                        | Pep Level 1 |
| Venezuelan Communist Party (PCV)                                                                                    | 🇻🇪 Venezuela                        | Pep Level 3 |
| Ministry of People's Power for Tourism (Ministerio del Poder Popular para el Turismo)                               | 🇻🇪 Venezuela                        | Pep Level 3 |
| Democratic Unity Roundtable (MUD)                                                                                   | 🇻🇪 Venezuela                        | Pep Level 3 |
| Consultoría Legal para Empresas                                                                                     | 🇻🇪 Venezuela                        | SIP         |
| National Assembly of Vietnam                                                                                        | 🇻🇳 Vietnam                          | Pep Level 1 |
| People's Court of Bình Thuận Province                                                                               | 🇻🇳 Vietnam                          | Pep Level 3 |
| Ho Chi Minh City People's Committee                                                                                 | 🇻🇳 Vietnam                          | Pep Level 4 |
| Chứng khoán Guotai Junan (Việt Nam)                                                                                 | 🇻🇳 Vietnam                          | SIE         |
| Báo Lao Động online                                                                                                 | 🇻🇳 Vietnam                          | SIP         |
| National Assembly of Yemen                                                                                          | 🇾🇪 Yemen                            | Pep Level 1 |
| Houthis (Ansar Allah)                                                                                               | 🇾🇪 Yemen                            | Pep Level 4 |
| National Assembly of Zambia                                                                                         | 🇿🇲 Zambia                           | Pep Level 1 |
| Zambia Consolidated Copper Mines                                                                                    | 🇿🇲 Zambia                           | Pep Level 4 |
| Zambia National Broadcasting Corporation (ZNBC)                                                                     | 🇿🇲 Zambia                           | SIP         |
| National Assembly of Zimbabwe                                                                                       | 🇿🇼 Zimbabwe                         | Pep Level 1 |
| Zimbabwe Republic Police                                                                                            | 🇿🇼 Zimbabwe                         | SIP         |

<p>
  1012 sources across 225 countries
</p>

### Sanctions & Watchlists

Below is a table of the Sanctions & Watchlists included in our AML screening process:

| Publisher                                                                                                                              | Country                    | Category  |
| -------------------------------------------------------------------------------------------------------------------------------------- | -------------------------- | --------- |
| Financial Intelligence Agency Albania - Administrative Measures                                                                        | 🇦🇱 Albania               | Sanctions |
| Financial Intelligence Agency Albania - List of Announced Persons                                                                      | 🇦🇱 Albania               | Sanctions |
| Algerian Financial Intelligence Processing Unit - National List of Terrorist Person and Entities                                       | 🇩🇿 Algeria               | Sanctions |
| Financial Intelligence Unit of Andorra (UIFAND) - Designated Entities                                                                  | 🇦🇩 Andorra               | Sanctions |
| Autoritat Financera Andorrana (AFA) - Sanctions                                                                                        | 🇦🇩 Andorra               | Sanctions |
| Ministry of Justice and Human Rights Argentina - Public Registry of Persons and Entities linked to acts of Terrorism and its Financing | 🇦🇷 Argentina             | Sanctions |
| Central Bank of Armenia-Punishments                                                                                                    | 🇦🇲 Armenia               | Sanctions |
| Central Bank of Armenia - Domestic Lists (Sanctions)                                                                                   | 🇦🇲 Armenia               | Sanctions |
| Central Bank of Aruba - Domestic List                                                                                                  | 🇦🇼 Aruba                 | Sanctions |
| Central Bank of Aruba - Warnings                                                                                                       | 🇦🇼 Aruba                 | Sanctions |
| Department of Foreign Affairs and Trade(DFAT) Australia - Consolidated Sanctions                                                       | 🇦🇺 Australia             | Sanctions |
| Australian National Security - Listed Terrorist Organisations                                                                          | 🇦🇺 Australia             | Sanctions |
| Australian Government AUSTRAC - Infringement Notices                                                                                   | 🇦🇺 Australia             | Sanctions |
| Austria Oesterreichische Nationalbank OENB Historical Sanctions                                                                        | 🇦🇹 Austria               | Sanctions |
| Azerbaijan Financial Monitoring Service - Targeted Financial Sanctions                                                                 | 🇦🇿 Azerbaijan            | Sanctions |
| Bangladesh Domestic Sanctions List                                                                                                     | 🇧🇩 Bangladesh            | Sanctions |
| Bangladesh Financial Intelligence Unit (BFIU) - Domestic Sanction List                                                                 | 🇧🇩 Bangladesh            | Sanctions |
| Financial Intelligence Unit of Barbados - Declaratory Orders                                                                           | 🇧🇧 Barbados              | Sanctions |
| Belgium Federal Public Service Finance - Consolidated List                                                                             | 🇧🇪 Belgium               | Sanctions |
| Belgium Federal Public Service Finance - National Financial Sanctions                                                                  | 🇧🇪 Belgium               | Sanctions |
| The Financial Intelligence Unit (FIU) of Belize - Consolidated Belize Sanctions List                                                   | 🇧🇿 Belize                | Sanctions |
| Government of Brazil (Securities and Exchange Commission) - Judgments and Terms of Commitment                                          | 🇧🇷 Brazil                | Sanctions |
| Systems Center - Suspension                                                                                                            | 🇧🇷 Brazil                | Sanctions |
| Transparency Portal - Disreputable and Suspended Companies                                                                             | 🇧🇷 Brazil                | Sanctions |
| Transparency Portal - Prohibited Non-Profit Entities                                                                                   | 🇧🇷 Brazil                | Sanctions |
| Transparency Portal - Companies Punished                                                                                               | 🇧🇷 Brazil                | Sanctions |
| Transparency Portal - Leniency Agreements                                                                                              | 🇧🇷 Brazil                | Sanctions |
| Government of Canada - Consolidated Canadian Autonomous Sanctions List                                                                 | 🇨🇦 Canada                | Sanctions |
| Government of Canada - Justice for Victims of Corrupt Foreign Officials Regulations                                                    | 🇨🇦 Canada                | Sanctions |
| Government of Canada - Freezing Assets of Corrupt Foreign Officials (Tunisia) Regulations                                              | 🇨🇦 Canada                | Sanctions |
| Government of Canada - Freezing Assets of Corrupt Foreign Officials (Ukraine) Regulations                                              | 🇨🇦 Canada                | Sanctions |
| Government of Canada-Regulations Establishing a List of Entities                                                                       | 🇨🇦 Canada                | Sanctions |
| Government of Canada - Enforcement Notifications                                                                                       | 🇨🇦 Canada                | Sanctions |
| Government of Canada - United Nations Resolutions on the Suppression of Terrorism                                                      | 🇨🇦 Canada                | Sanctions |
| British Columbia Securities Commission (Disciplined List)                                                                              | 🇨🇦 Canada                | Sanctions |
| Cayman Islands Monetary Authority - Financial Sanctions Notices                                                                        | 🇰🇾 Cayman Islands        | Sanctions |
| Government of Jersey - Financial Sanctions Notice                                                                                      | 🇯🇪 Channel Islands       | Sanctions |
| Comisión Para el Mercado Financiero (CMF) - Sanctions Resolutions Issued                                                               | 🇨🇱 Chile                 | Sanctions |
| Comisión Para el Mercado Financiero (CMF) - Insurance Market Sanctions                                                                 | 🇨🇱 Chile                 | Sanctions |
| Unidad De Análisis Financiero - Enforceable Sanctions                                                                                  | 🇨🇱 Chile                 | Sanctions |
| China Securities Regulatory Commission-Administrative Penalties and Regulations                                                        | 🇨🇳 China                 | Sanctions |
| UEL MOFCOM Unreliable Entity List                                                                                                      | 🇨🇳 China                 | Sanctions |
| AMV - Autorregulador Del Mercado De Valores - Sanctions                                                                                | 🇨🇴 Colombia              | Sanctions |
| AMV-Autorregulador Del Mercado De Valores                                                                                              | 🇨🇴 Colombia              | Sanctions |
| Financial Superintendence of Colombia - Administrative Sanctions                                                                       | 🇨🇴 Colombia              | Sanctions |
| Financial Superintendence of Colombia - Report of Final Sanctions                                                                      | 🇨🇴 Colombia              | Sanctions |
| Cyprus Securities and Exchange Commission (CySEC) - Administrative Sanctions                                                           | 🇨🇾 Cyprus                | Sanctions |
| Ministry of Foreign Affairs of the Czech Republic-National Sanction List                                                               | 🇨🇿 Czech Republic        | Sanctions |
| Danish Immigration Service - Banned Religious Preachers                                                                                | 🇩🇰 Denmark               | Sanctions |
| Egyptian Anti-Money Laundering and Terrorism Financing Unit - Lists of terrorist entities and domestic terrorists                      | 🇪🇬 Egypt                 | Sanctions |
| Egyptian Anti-Money Laundering and Terrorism Financing Unit - Security Council lists                                                   | 🇪🇬 Egypt                 | Sanctions |
| Transparency Portal - Government Ethics Tribunal                                                                                       | 🇸🇻 El Salvador           | Sanctions |
| National Frost Registry - Sanctions List                                                                                               | 🇫🇷 France                | Sanctions |
| The Autorité des Marchés Financiers (AMF), France - Decisions of the Sanctions Commission                                              | 🇫🇷 France                | Sanctions |
| Commission Nationale de l'Informatique et des Libertés (CNIL) - Sanctions                                                              | 🇫🇷 France                | Sanctions |
| LEPL Financial Monitoring Service of Georgia - List of Sanctioned Persons                                                              | 🇬🇪 Georgia               | Sanctions |
| National Bank of Georgia - Sanctions                                                                                                   | 🇬🇪 Georgia               | Sanctions |
| Federal Ministry of the Interior Germany - Bans on Associations                                                                        | 🇩🇪 Germany               | Sanctions |
| Bank of Greece - Sanctions                                                                                                             | 🇬🇷 Greece                | Sanctions |
| National Tax and Customs Administration (NTCA) - Canceled tax numbers                                                                  | 🇭🇺 Hungary               | Sanctions |
| National Tax and Customs Administration (NTCA) - Announcement on decisions deleting the tax number                                     | 🇭🇺 Hungary               | Sanctions |
| Ministry of Home Affairs India - List of Banned Organisations/Individuals                                                              | 🇮🇳 India                 | Sanctions |
| Ministry of Home Affairs India - Unlawful Associations                                                                                 | 🇮🇳 India                 | Sanctions |
| Financial Transaction Reporting and Analysis Centre Indonesia - List of Suspected Terrorists and Terrorist Organizations (DTTOT)       | 🇮🇩 Indonesia             | Sanctions |
| African Development Bank-Debarred Entities                                                                                             | 🌐 International           | Sanctions |
| Asian Development bank - Sanction List                                                                                                 | 🌐 International           | Sanctions |
| European Bank for Research and Development - Ineligible Entities                                                                       | 🌐 International           | Sanctions |
| European Commission - The EU Air Safety List                                                                                           | 🌐 International           | Sanctions |
| European Union - Consolidated List of EU Financial Sanctions                                                                           | 🌐 International           | Sanctions |
| EUR-Lex - Decisions                                                                                                                    | 🌐 International           | Sanctions |
| United Nation Security Council - Consolidated List                                                                                     | 🌐 International           | Sanctions |
| The World Bank - Debarred Firms and Individuals                                                                                        | 🌐 International           | Sanctions |
| Asian Infrastructure Investment Bank - Debarment List                                                                                  | 🌐 International           | Sanctions |
| Inter-American Development Bank (IDB) - Sanctioned Individuals and Firms                                                               | 🌐 International           | Sanctions |
| International Organization of Securities Commission - Investor Alerts Portal                                                           | 🌐 International           | Sanctions |
| EU Consolidated Sanctions                                                                                                              | 🌐 International           | Sanctions |
| EU Sanctions - Consolidated List of Travel Bans                                                                                        | 🌐 International           | Sanctions |
| Uyghur Human Rights Project - Sanctions                                                                                                | 🌐 International           | Sanctions |
| Islamic Republic of Iran Ministry of Foreign Affairs Reference List of Sanctions - Consolidated                                        | 🇮🇷 Iran                  | Sanctions |
| Islamic Republic of Iran Ministry of Foreign Affairs Reference List of Sanctions                                                       | 🇮🇷 Iran                  | Sanctions |
| Anti-Money Laundering and Countering Financing of Terrorism Office, Iraq - Fund Freezing List                                          | 🇮🇶 Iraq                  | Sanctions |
| Anti-Money Laundering and Countering Financing of Terrorism Office, Iraq - Local List                                                  | 🇮🇶 Iraq                  | Sanctions |
| The Isle of Man Financial Services Authority (IOMFSA) - Disqualified Directors                                                         | 🇮🇲 Isle of Man           | Sanctions |
| The Isle of Man Financial Services Authority (IOMFSA) - Enforcement Action                                                             | 🇮🇲 Isle of Man           | Sanctions |
| National Bureau for Counter Terror Financing - NBCTF Israel - Associations and Terrorist Organizations                                 | 🇮🇱 Israel                | Sanctions |
| National Bureau for Counter Terror Financing - NBCTF Israel - Seizures                                                                 | 🇮🇱 Israel                | Sanctions |
| Ministry of Finance, Israel - Designated entities and individuals                                                                      | 🇮🇱 Israel                | Sanctions |
| National Bureau for Counter Terror Financing - NBCTF Israel - Declarations On Activists                                                | 🇮🇱 Israel                | Sanctions |
| Ministry of Finance, Japan - Economic Sanctions and Target Lists                                                                       | 🇯🇵 Japan                 | Sanctions |
| The Anti Money Laundering and Counter Terrorist Financing Unit - National List                                                         | 🇯🇴 Jordan                | Sanctions |
| The Anti Money Laundering and Counter Terrorist Financing Unit - Sanctions List                                                        | 🇯🇴 Jordan                | Sanctions |
| Kyrgyzstan State Financial Intelligence Service - National List of Sanctions                                                           | 🇰🇬 Kyrgyzstan            | Sanctions |
| Financial Intelligence Service Latvia - Subjects of Sanctions                                                                          | 🇱🇻 Latvia                | Sanctions |
| Financial Intelligence Service Latvia - Frozen economic resources                                                                      | 🇱🇻 Latvia                | Sanctions |
| Latvijas Banka - Sanctions                                                                                                             | 🇱🇻 Latvia                | Sanctions |
| Internal Security Forces, Lebanon - National Sanctions List                                                                            | 🇱🇧 Lebanon               | Sanctions |
| Lithuania Financial Crime Investigation Service - International financial sanctions                                                    | 🇱🇹 Lithuania             | Sanctions |
| Commission de Surveillance du Secteur Financier - Administrative sanctions and Warnings                                                | 🇱🇺 Luxembourg            | Sanctions |
| Commissariat aux Assurances                                                                                                            | 🇱🇺 Luxembourg            | Sanctions |
| Malaysia Ministry of Home Affairs - List of Sanctioned Entities                                                                        | 🇲🇾 Malaysia              | Sanctions |
| Ministry of Home Affairs, Malaysia - Sanction List                                                                                     | 🇲🇾 Malaysia              | Sanctions |
| Securities Commission Malaysia (SC) - AOB Sanctions                                                                                    | 🇲🇾 Malaysia              | Sanctions |
| Government of Mexico - Consolidated Sanctions                                                                                          | 🇲🇽 Mexico                | Sanctions |
| Bank of Mexico - Financial Sanctions                                                                                                   | 🇲🇽 Mexico                | Sanctions |
| Gouvernement Princier Monaco - National Funds Freezing List                                                                            | 🇲🇨 Monaco                | Sanctions |
| Financial Services Commission Montserrat - Sanctions                                                                                   | 🇲🇸 Montserrat            | Sanctions |
| Government of the Netherlands - Dutch National Sanction List                                                                           | 🇳🇱 Netherlands           | Sanctions |
| New Zealand Police - Designated Terrorists                                                                                             | 🇳🇿 New Zealand           | Sanctions |
| New Zealand Foreign Affairs & Trade - Russia Sanctions Register                                                                        | 🇳🇿 New Zealand           | Sanctions |
| Nigeria Sanctions Committee - NIGSAC                                                                                                   | 🇳🇬 Nigeria               | Sanctions |
| National Counter Terrorism Committee, Oman - Sanctions Local List                                                                      | 🇴🇲 Oman                  | Sanctions |
| National Counter Terrorism Authority - Proscribed Organizations                                                                        | 🇵🇰 Pakistan              | Sanctions |
| National Counter Terrorism Authority (NACTA) Pakistan - Proscribed Persons                                                             | 🇵🇰 Pakistan              | Sanctions |
| National Counter Terrorism Authority Pakistan - Denotified List                                                                        | 🇵🇰 Pakistan              | Sanctions |
| Palestine Monetary Authority - Local Freezing List                                                                                     | 🇵🇸 Palestine             | Sanctions |
| Superintendence of the Securities Market (SMV) Peru - Sanctioned Companies                                                             | 🇵🇪 Peru                  | Sanctions |
| Office of the Comptroller General of the Republic of Peru - Registered and Current Sanctions                                           | 🇵🇪 Peru                  | Sanctions |
| Superintendency of Banking, Insurance and AFP, Peru - Sanctions for Supervised Companies                                               | 🇵🇪 Peru                  | Sanctions |
| Ministry of Internal Affairs and Administration - Sanction List                                                                        | 🇵🇱 Poland                | Sanctions |
| Ministry of Interior National Counter Terrorism Committee Qatar - Sanction List                                                        | 🇶🇦 Qatar                 | Sanctions |
| Federal Security Service of the Russian Federation - Terrorist Organizations                                                           | 🇷🇺 Russia                | Sanctions |
| National Antiterrorism Committee, Russia - Unified Federal List of Organizations                                                       | 🇷🇺 Russia                | Sanctions |
| Financial Services Regulatory Commission - St. Kitts Branch International Sanctions                                                    | 🇰🇳 Saint Kitts and Nevis | Sanctions |
| Permanent Counter Terrorism Committee, Presidency of State Security - National List Pursuant to UNSCR 1373                             | 🇸🇦 Saudi Arabia          | Sanctions |
| Ministry of Economy and Finance Senegal - Consolidated List                                                                            | 🇸🇳 Senegal               | Sanctions |
| Administration for the Prevention of Money Laundering (APML), Serbia - Lists of Designated Persons                                     | 🇷🇸 Serbia                | Sanctions |
| Singapore Statutes Online - Terrorists and Terrorist Entities                                                                          | 🇸🇬 Singapore             | Sanctions |
| Monetary Authority of Singapore - Investor Alert List                                                                                  | 🇸🇬 Singapore             | Sanctions |
| National Anti-Money Laundering Committee NAMLC - Targeted Financial Sanction List                                                      | 🇸🇴 Somalia               | Sanctions |
| Financial Intelligence Centre (FIC) - South Africa Sanctions                                                                           | 🇿🇦 South Africa          | Sanctions |
| South African Reserve Bank Prudential Authority - Administrative Sanctions                                                             | 🇿🇦 South Africa          | Sanctions |
| Securities and Exchange Commission of Sri Lanka - Administrative Sanctions                                                             | 🇱🇰 Sri Lanka             | Sanctions |
| State Secretariat for Economic Affairs, Switzerland - List of Sanctioned Individuals, Entities and Organizations                       | 🇨🇭 Switzerland           | Sanctions |
| State Secretariat for Economic Affairs, Switzerland - Sanctions List                                                                   | 🇨🇭 Switzerland           | Sanctions |
| Republic of Turkey Ministry of Treasury and Finance - TF Current List                                                                  | 🇹🇷 Türkiye               | Sanctions |
| Anti-Money Laundering Division (AMLD), Taiwan - Sanction List of Ministry of Justice                                                   | 🇹🇼 Taiwan                | Sanctions |
| Financial Supervisory Commission, R.O.C.(Taiwan) - Securities and Futures Bureau                                                       | 🇹🇼 Taiwan                | Sanctions |
| National Bank of Tajikistan - List of individuals convicted of terrorist crimes                                                        | 🇹🇯 Tajikistan            | Sanctions |
| National Bank of Tajikistan                                                                                                            | 🇹🇯 Tajikistan            | Sanctions |
| Anti-Money Laundering Office, Thailand - High Risk Persons List                                                                        | 🇹🇭 Thailand              | Sanctions |
| National Commission for the Fight Against Terrorism, Tunisia - National Sanction List                                                  | 🇹🇳 Tunisia               | Sanctions |
| Attorney General's Chambers - Turks and Caicos Islands                                                                                 | 🇹🇨 Turks and Caicos      | Sanctions |
| National Security and Defense Council of Ukraine - Personal Sanctions                                                                  | 🇺🇦 Ukraine               | Sanctions |
| The State Financial Monitoring Service of Ukraine - Persons Related to Terrorist Activity                                              | 🇺🇦 Ukraine               | Sanctions |
| Executive Office for Control and Non-Proliferation, UAE - Sanctions List                                                               | 🇦🇪 United Arab Emirates  | Sanctions |
| United Arab Emirates- Local Terrorist List                                                                                             | 🇦🇪 United Arab Emirates  | Sanctions |
| Government of United Kingdom - The UK Sanctions List                                                                                   | 🇬🇧 United Kingdom        | Sanctions |
| Department of State Directorate of Defense Trade Controls, United States - Statutorily Debarred Parties                                | 🇺🇸 United States         | Sanctions |
| Department of State Directorate of Defense Trade Controls, United States - Administratively Debarred Parties                           | 🇺🇸 United States         | Sanctions |
| U.S Department of State - Nonproliferation Sanctions                                                                                   | 🇺🇸 United States         | Sanctions |
| U.S Department of State - Cuba Restricted List                                                                                         | 🇺🇸 United States         | Sanctions |
| U.S Department of State - Terrorist Exclusion List                                                                                     | 🇺🇸 United States         | Sanctions |
| Department of State, United States - Public Listings                                                                                   | 🇺🇸 United States         | Sanctions |
| Office of Foreign Assets Control (OFAC ) - SDN and Blocked Persons List                                                                | 🇺🇸 United States         | Sanctions |
| Office of Foreign Assets Control (OFAC) - Non-SDN Sanction List                                                                        | 🇺🇸 United States         | Sanctions |
| Office of Foreign Assets Control, United States - Sanctions Programs and Country Information                                           | 🇺🇸 United States         | Sanctions |
| Bureau of Industry and Security, United States - The Denied Persons List                                                               | 🇺🇸 United States         | Sanctions |
| Code of Federal Regulations, United States - Entity List                                                                               | 🇺🇸 United States         | Sanctions |
| Code of Federal Regulations, United States - Unverified List                                                                           | 🇺🇸 United States         | Sanctions |
| Code of Federal Regulations, United States - Military End User (MEU) List                                                              | 🇺🇸 United States         | Sanctions |
| United States Bureau of Industry and Security - Military Intelligence End User List (MIEUL)                                            | 🇺🇸 United States         | Sanctions |
| Bureau of Industry and Security, United States - Charging Letters                                                                      | 🇺🇸 United States         | Sanctions |
| United States Bureau of Industry and Security - Commercial and Private Aircraft in Potential Violation                                 | 🇺🇸 United States         | Sanctions |
| Financial Crimes Enforcement Network (FINCEN) - Money Laundering Concerns List                                                         | 🇺🇸 United States         | Sanctions |
| U.S. Department of Homeland Security - UFLPA Entity List                                                                               | 🇺🇸 United States         | Sanctions |
| International Trade Administration - Consolidated Screening List (CSL)                                                                 | 🇺🇸 United States         | Sanctions |
| United States Department of Defense - List of People's Republic of China (PRC) Military Companies                                      | 🇺🇸 United States         | Sanctions |
| Office of the Comptroller of the Currency, United States - OTS Enforcement Order Archive                                               | 🇺🇸 United States         | Sanctions |
| Michigan Department of Health and Human Services (MDHHS) - List of Sanctioned Providers                                                | 🇺🇸 United States         | Sanctions |
| Department for Combating Economic Crimes under the General Prosecutor's Office of the Republic of Uzbekistan - List of Natural Persons | 🇺🇿 Uzbekistan            | Sanctions |
| Vendata - Sanctions and Sanctioned Database                                                                                            | 🇻🇪 Venezuela             | Sanctions |
| Ministry of Public Security                                                                                                            | 🇻🇳 Vietnam               | Sanctions |

<p>
  172 sources across 80 countries
</p>

### Regulatory Actions & Warnings

Below is a table of the Regulatory Actions & Warnings included in our AML screening process:

| Publisher                                                                                                       | Country                               | Category |
| --------------------------------------------------------------------------------------------------------------- | ------------------------------------- | -------- |
| Special Inspector General for Afghanistan Reconstruction SIGAR                                                  | 🇦🇫 Afghanistan                      | Warnings |
| Algerian National Television Network (ENTV)                                                                     | 🇩🇿 Algeria                          | Warnings |
| Andorra Financial Authority Sanctions to Supervised Entities                                                    | 🇦🇩 Andorra                          | Warnings |
| Angola Police Wanted List                                                                                       | 🇦🇴 Angola                           | Warnings |
| Anguilla Financial Services Commission                                                                          | 🇦🇮 Anguilla                         | Warnings |
| Antigua and Barbuda Directorate of Offshore Gaming                                                              | 🇦🇬 Antigua and Barbuda              | Warnings |
| National Value Commission                                                                                       | 🇦🇷 Argentina                        | Warnings |
| Central Bank of Armenia - Punishments                                                                           | 🇦🇲 Armenia                          | Warnings |
| Office of The Representative on International Legal Matters                                                     | 🇦🇲 Armenia                          | Warnings |
| Australian Transaction Reports and Analysis Centre                                                              | 🇦🇺 Australia                        | Warnings |
| Austria Stock Exchange                                                                                          | 🇦🇹 Austria                          | Warnings |
| Ministry of Internal Affairs Azerbaijan-Wanted list                                                             | 🇦🇿 Azerbaijan                       | Warnings |
| National Health Regulatory Authority, Kingdom of Bahrain                                                        | 🇧🇭 Bahrain                          | Warnings |
| New Age                                                                                                         | 🇧🇩 Bangladesh                       | Warnings |
| Barbados Judicial System                                                                                        | 🇧🇧 Barbados                         | Warnings |
| Ministry of Antimonopoly Regulation and Trade                                                                   | 🇧🇾 Belarus                          | Warnings |
| Data Protection Authority- Market Court Judgements                                                              | 🇧🇪 Belgium                          | Warnings |
| The Financial Services Commission                                                                               | 🇧🇿 Belize                           | Warnings |
| Ministry of Justice and Legislation - Wanted Persons                                                            | 🇧🇯 Benin                            | Warnings |
| Bermuda Monetary Authority Enforcement Actions                                                                  | 🇧🇲 Bermuda                          | Warnings |
| Corporate Regulatory Authority of Bhutan                                                                        | 🇧🇹 Bhutan                           | Warnings |
| Electronic Gazette of the Trade Register of Bolivia                                                             | 🇧🇴 Bolivia                          | Warnings |
| SAFF Portal                                                                                                     | 🇧🇦 Bosnia and Herzegovina           | Warnings |
| Non-Bank Financial Institutions Regulatory Authority                                                            | 🇧🇼 Botswana                         | Warnings |
| Government of Brazil (Securities and Exchange Commission)                                                       | 🇧🇷 Brazil                           | Warnings |
| Financial Services Commission                                                                                   | 🇻🇬 British Virgin Islands           | Warnings |
| Brunei Darussalam Central Bank                                                                                  | 🇧🇳 Brunei                           | Warnings |
| Financial Supervision Commission (FSC)                                                                          | 🇧🇬 Bulgaria                         | Warnings |
| Crisis Group                                                                                                    | 🇧🇮 Burundi                          | Warnings |
| Security and Exchange Regulators of Cambodia                                                                    | 🇰🇭 Cambodia                         | Warnings |
| Business in Cameroon                                                                                            | 🇨🇲 Cameroon                         | Warnings |
| Canadian Securities Administrators (Investor Alerts)                                                            | 🇨🇦 Canada                           | Warnings |
| Bank of Cape Verde                                                                                              | 🇨🇻 Cape Verde                       | Warnings |
| Dutch Caribbean Securities Exchange - Termination                                                               | 🇧🇶 Caribbean Netherlands            | Warnings |
| Cayman Island Monetary Authority (CIMA)                                                                         | 🇰🇾 Cayman Islands                   | Warnings |
| Fish Farming Expert                                                                                             | 🇨🇱 Chile                            | Warnings |
| China Securities Regulatory Commission - Administrative Penalties and Regulations                               | 🇨🇳 China                            | Warnings |
| Credit China (Jilin)                                                                                            | 🇨🇳 China                            | Warnings |
| La Guajira Hoy.com                                                                                              | 🇨🇴 Colombia                         | Warnings |
| Common Market for Eastern and Southern Africa (COMESA)                                                          | 🇰🇲 Comoros                          | Warnings |
| Ministry of Mining                                                                                              | 🇨🇬 Congo                            | Warnings |
| National Stock Exchange                                                                                         | 🇨🇷 Costa Rica                       | Warnings |
| The Agency for the Protection of Market Competition                                                             | 🇭🇷 Croatia                          | Warnings |
| Curaçao Chamber of Commerce                                                                                     | 🇨🇼 Curacao                          | Warnings |
| Cyprus Securities and Exchange Commission                                                                       | 🇨🇾 Cyprus                           | Warnings |
| Czech Republic Office for the Protection of Competition                                                         | 🇨🇿 Czech Republic                   | Warnings |
| Public Procurement Regulatory Authority                                                                         | 🇨🇩 Democratic Republic of the Congo | Warnings |
| The Gambling Authority                                                                                          | 🇩🇰 Denmark                          | Warnings |
| Dominica Government of Commonwealth                                                                             | 🇩🇲 Dominica                         | Warnings |
| Ministry of Transportation and Public Works                                                                     | 🇪🇨 Ecuador                          | Warnings |
| American Center for Democracy                                                                                   | 🇪🇬 Egypt                            | Warnings |
| El Salvador Crime Stoppers Most Wanted                                                                          | 🇸🇻 El Salvador                      | Warnings |
| Estonia Police- Wanted Persons                                                                                  | 🇪🇪 Estonia                          | Warnings |
| Federal Services Regulatory Authority                                                                           | 🇸🇿 Eswatini                         | Warnings |
| Ethiopian Federal Police                                                                                        | 🇪🇹 Ethiopia                         | Warnings |
| Finnish Competition and Consumer Authority                                                                      | 🇫🇮 Finland                          | Warnings |
| Economist Intelligence                                                                                          | 🇬🇦 Gabon                            | Warnings |
| Registrar's General Department                                                                                  | 🇬🇭 Ghana                            | Warnings |
| Gibraltar Stock Exchange                                                                                        | 🇬🇮 Gibraltar                        | Warnings |
| Hellenic Capital Market Commission                                                                              | 🇬🇷 Greece                           | Warnings |
| Guam Crime Stoppers                                                                                             | 🇬🇺 Guam                             | Warnings |
| Customs Anti Narcotic Unit- Wanted                                                                              | 🇬🇾 Guyana                           | Warnings |
| Haitian National Police                                                                                         | 🇭🇹 Haiti                            | Warnings |
| ONCAE - Procurement Regulatory Office of the State of Honduras                                                  | 🇭🇳 Honduras                         | Warnings |
| Hong Kong Monetary Authority Fraudulent Websites                                                                | 🇭🇰 Hong Kong                        | Warnings |
| Hungarian Police                                                                                                | 🇭🇺 Hungary                          | Warnings |
| Supreme Court- Judgements                                                                                       | 🇮🇸 Iceland                          | Warnings |
| Badan Pengawas Perdagangan Berjangka Komoditi                                                                   | 🇮🇩 Indonesia                        | Warnings |
| International Organization of Securities Commission (IOSCO) - Investor Alerts Portal                            | 🌐 International                      | Warnings |
| INTERPOL Yellow Notices                                                                                         | 🌐 International                      | Warnings |
| Financial Intelligence Agency                                                                                   | 🇮🇷 Iran                             | Warnings |
| Anadolu Ajansı                                                                                                  | 🇮🇶 Iraq                             | Warnings |
| Ireland National police and Security Service                                                                    | 🇮🇪 Ireland                          | Warnings |
| Isle of Man Courts                                                                                              | 🇮🇲 Isle of Man                      | Warnings |
| שיחה מקומית                                                                                                     | 🇮🇱 Israel                           | Warnings |
| Italy Italian Companies and Exchange Commission Warnings                                                        | 🇮🇹 Italy                            | Warnings |
| Jamaica Constabulary Force-Missing Persons                                                                      | 🇯🇲 Jamaica                          | Warnings |
| Japan Financial Service Agency - Illegal Financial Companies                                                    | 🇯🇵 Japan                            | Warnings |
| Jordan Securities Commission-Circulars and Regulatory Decisions                                                 | 🇯🇴 Jordan                           | Warnings |
| State Register of Industrial Property Objects of the Republic of Kazakhstan                                     | 🇰🇿 Kazakhstan                       | Warnings |
| Ministry of Information, Communications, Transport and Tourism Development                                      | 🇰🇮 Kiribati                         | Warnings |
| Supreme Court of Kosovo - Disciplinary Actions                                                                  | 🇽🇰 Kosovo                           | Warnings |
| Kuwait Capital Market Authority-Restricted Persons                                                              | 🇰🇼 Kuwait                           | Warnings |
| Ministry of Internal Affairs of Kyrgyz Republic                                                                 | 🇰🇬 Kyrgyzstan                       | Warnings |
| Latvia Financial and Capital Market Commission                                                                  | 🇱🇻 Latvia                           | Warnings |
| Lesotho Mounted Police Service                                                                                  | 🇱🇸 Lesotho                          | Warnings |
| Central Bank of Liberia - Gazette                                                                               | 🇱🇷 Liberia                          | Warnings |
| The University of Edinburgh                                                                                     | 🇱🇾 Libya                            | Warnings |
| Liechtenstein Gazette                                                                                           | 🇱🇮 Liechtenstein                    | Warnings |
| Lithuania Public Procurement Office                                                                             | 🇱🇹 Lithuania                        | Warnings |
| Commission de Surveillance du Secteur Financier (CSSF) - Administrative sanctions and Warnings                  | 🇱🇺 Luxembourg                       | Warnings |
| Luxembourg Police                                                                                               | 🇱🇺 Luxembourg                       | Warnings |
| UNICEF Madagascar                                                                                               | 🇲🇬 Madagascar                       | Warnings |
| Anti-Corruption Bureau Malawi (Arrested for illegal activities)                                                 | 🇲🇼 Malawi                           | Warnings |
| Bank Negara Malaysia                                                                                            | 🇲🇾 Malaysia                         | Warnings |
| Ministry of Finance Maldives                                                                                    | 🇲🇻 Maldives                         | Warnings |
| Australian National Security Website                                                                            | 🇲🇱 Mali                             | Warnings |
| Malta Transport Maritime                                                                                        | 🇲🇹 Malta                            | Warnings |
| Corporate and Business Registration Department                                                                  | 🇲🇺 Mauritius                        | Warnings |
| Mexico Comisión Nacional de Seguros y Fianzas - Sanciones a personas que intermediaron sin autorización         | 🇲🇽 Mexico                           | Warnings |
| Moldovan Ban List of Economic Operators                                                                         | 🇲🇩 Moldova                          | Warnings |
| Monaco Fund Freezing Measures                                                                                   | 🇲🇨 Monaco                           | Warnings |
| Mongolian Stock Exchange - Ceased Trading                                                                       | 🇲🇳 Mongolia                         | Warnings |
| Montenegro Agency for Prevention of Corruption                                                                  | 🇲🇪 Montenegro                       | Warnings |
| Moroccan Capital Market Authority                                                                               | 🇲🇦 Morocco                          | Warnings |
| The Bank of Mozambique                                                                                          | 🇲🇿 Mozambique                       | Warnings |
| Reporters Without Borders                                                                                       | 🇲🇲 Myanmar                          | Warnings |
| Ministry of Labour, Industrial Relation and Employment Creation                                                 | 🇳🇦 Namibia                          | Warnings |
| New Business Age-Fine                                                                                           | 🇳🇵 Nepal                            | Warnings |
| Authority for Financial Markets Netherlands-Warnings                                                            | 🇳🇱 Netherlands                      | Warnings |
| Michigan-Fine                                                                                                   | 🇳🇨 New Caledonia                    | Warnings |
| Financial Market Authority New Zealand-Penalties                                                                | 🇳🇿 New Zealand                      | Warnings |
| Nicaraguan Stock Exchange                                                                                       | 🇳🇮 Nicaragua                        | Warnings |
| Nigeria Sexual Offender & Service Provider Database                                                             | 🇳🇬 Nigeria                          | Warnings |
| District Court for the Northern Mariana Islands                                                                 | 🇲🇵 Northern Mariana Islands         | Warnings |
| Dagsavisen Norway                                                                                               | 🇳🇴 Norway                           | Warnings |
| Pakistan Competition Authority Decisions                                                                        | 🇵🇰 Pakistan                         | Warnings |
| Financial Institution Commission                                                                                | 🇵🇼 Palau                            | Warnings |
| Palestine Monetary Authority - Local Freezing List                                                              | 🇵🇸 Palestine                        | Warnings |
| Superintendency of Securities Market of Panama                                                                  | 🇵🇦 Panama                           | Warnings |
| Ministry of Interior Peru                                                                                       | 🇵🇪 Peru                             | Warnings |
| Philippines Anti-Money Laundering                                                                               | 🇵🇭 Philippines                      | Warnings |
| Bird & Bird-Fine                                                                                                | 🇵🇱 Poland                           | Warnings |
| Portugal OSAE                                                                                                   | 🇵🇹 Portugal                         | Warnings |
| Puerto Rico Police                                                                                              | 🇵🇷 Puerto Rico                      | Warnings |
| International Adviser-Fine                                                                                      | 🇶🇦 Qatar                            | Warnings |
| United Nations Security Council                                                                                 | 🇶🇦 Qatar                            | Warnings |
| Municipality of Gjorche Petrov Skopje - Gazette                                                                 | 🇲🇰 Republic of North Macedonia      | Warnings |
| The National Supervisory Authority For Personal Data Processing                                                 | 🇷🇴 Romania                          | Warnings |
| Rwanda Ministry of Foreign Affairs and International Cooperation                                                | 🇷🇼 Rwanda                           | Warnings |
| Financial Services Regulatory Authority                                                                         | 🇱🇨 Saint Lucia                      | Warnings |
| St. Vincent & Grenadines Financial Intelligence Unit Alerts                                                     | 🇻🇨 Saint Vincent And The Grenadines | Warnings |
| Samoa Police                                                                                                    | 🇼🇸 Samoa                            | Warnings |
| Saudi Arabia Stock Exchange Unlisted Corporates Sukuk/Bonds                                                     | 🇸🇦 Saudi Arabia                     | Warnings |
| NDARINFO.COM Senegal                                                                                            | 🇸🇳 Senegal                          | Warnings |
| Serbia Securities and Exchange Commission Public Censure                                                        | 🇷🇸 Serbia                           | Warnings |
| Official Gazette of Republic of Seychelles                                                                      | 🇸🇨 Seychelles                       | Warnings |
| Committee To Protect Journalists                                                                                | 🇸🇱 Sierra Leone                     | Warnings |
| Monetary Authority of Singapore - Investor Alert List                                                           | 🇸🇬 Singapore                        | Warnings |
| Singapore Monetary Authority Enforcement Actions Companies                                                      | 🇸🇬 Singapore                        | Warnings |
| St. Maarten Chamber of Commerce                                                                                 | 🇸🇽 Sint Maarten                     | Warnings |
| Gambling Regulation Office - Court Orders                                                                       | 🇸🇰 Slovakia                         | Warnings |
| Official Gazette of the Republic of Slovenia                                                                    | 🇸🇮 Slovenia                         | Warnings |
| Wakaaladda Wararka Qaranka Soomaaliyeed                                                                         | 🇸🇴 Somalia                          | Warnings |
| South Africa National Treasury                                                                                  | 🇿🇦 South Africa                     | Warnings |
| The Guardian-Most Wanted                                                                                        | 🇪🇸 Spain                            | Warnings |
| UTHR(J), SRI LANKA                                                                                              | 🇱🇰 Sri Lanka                        | Warnings |
| ISRAEL - ILSHABAK - Israel Security Agency - SHABAK                                                             | 🇵🇸 State of Palestine               | Warnings |
| صوت الھامش                                                                                                      | 🇸🇩 Sudan                            | Warnings |
| Aviation Analysis-Wanted person                                                                                 | 🇸🇷 Suriname                         | Warnings |
| Ústavný súd Slovenskej republiky                                                                                | 🇸🇰 Slovakia                         | Warnings |
| ITALY - CONSOB - National Comm. Borsa                                                                           | 🇮🇹 Italy                            | Warnings |
| Global Times                                                                                                    | 🇸🇾 Syria                            | Warnings |
| Financial Supervisory Commission (Insurance Bureau)-Sanctions                                                   | 🇹🇼 Taiwan                           | Warnings |
| Ministry of Internal Affairs-Missing Person                                                                     | 🇹🇯 Tajikistan                       | Warnings |
| Bank of Tanzania                                                                                                | 🇹🇿 Tanzania                         | Warnings |
| THAILAND - THAMLO-SANC - Thailand Anti Money Laundering Office - Sanctions                                      | 🇹🇭 Thailand                         | Warnings |
| Compliance Commission of The Bahamas                                                                            | 🇧🇸 The Bahamas                      | Warnings |
| Regulatory Authority for Electronic Communications & Posts                                                      | 🇹🇬 Togo                             | Warnings |
| Trinidad and Tobago Securities and Exchange Commission (TTSEC)                                                  | 🇹🇹 Trinidad and Tobago              | Warnings |
| Ministry of border control and immigration services- Repatriations                                              | 🇹🇨 Turks and Caicos                 | Warnings |
| Capital Market Authority (CMA)                                                                                  | 🇺🇬 Uganda                           | Warnings |
| Ukraine SFMS Blacklist                                                                                          | 🇺🇦 Ukraine                          | Warnings |
| Dubai International Finance Centre                                                                              | 🇦🇪 United Arab Emirates             | Warnings |
| Global Influence Operations Report                                                                              | 🇬🇧 United Kingdom                   | Warnings |
| Georgia Department of Banking and Finance                                                                       | 🇺🇸 United States                    | Warnings |
| The U.S. Department of State - Directorate of Defense Trade Controls (DDTC) - Administratively Debarred Parties | 🇺🇸 United States                    | Warnings |
| Ministry of Industry, Energy and Mining                                                                         | 🇺🇾 Uruguay                          | Warnings |
| Ministry of Internal Affairs of the Republic of Uzbekistan                                                      | 🇺🇿 Uzbekistan                       | Warnings |
| Judiciary of Republic of Vanuatu                                                                                | 🇻🇺 Vanuatu                          | Warnings |
| Institute for Works of Religion                                                                                 | 🇻🇦 Vatican City                     | Warnings |
| Tribunal of Supreme Court of Justice                                                                            | 🇻🇪 Venezuela                        | Warnings |
| The Economic Times- Blacklisted firms                                                                           | 🇻🇳 Vietnam                          | Warnings |
| Securities and Exchange Commission Zambia                                                                       | 🇿🇲 Zambia                           | Warnings |
| Zimbabwe Legal Information Institute (ZimLII)                                                                   | 🇿🇼 Zimbabwe                         | Warnings |

<p>
  175 sources across 168 countries
</p>


# Biometric Authentication
Source: https://docs.didit.me/core-technology/biometric-auth/overview

Authenticate returning users with liveness + face match. No documents, sub-2-second passwordless verification. Pay-per-call $0.10.

Didit's Biometric Authentication solution provides a streamlined verification experience for returning users. This workflow can be configured to perform a liveness-only check for simple presence verification, or combine liveness with facial recognition for stronger identity confirmation against a stored portrait. This flexibility creates a frictionless experience while maintaining high security standards.

<AgentPromptAccordion title="Biometric Authentication Integration Prompt" />

## Key Features

#### Fast Re-Verification

* No document scanning required
* Complete verification in seconds
* Reduces user friction and abandonment

#### Advanced Security

* Uses the same neural network architecture as Face Match 1:1
* Prevents account takeover attempts
* Includes liveness detection to prevent spoofing

#### Integration Flexibility

* Available as web-based
* Configurable matching thresholds
* Optional Device & IP Analysis for enhanced security

## How It Works

<Steps>
  <Step title="Session Creation" icon="circle-play">
    When you create a biometric authentication session for a workflow with **face matching**, Didit needs a reference face to compare the live selfie against.
    You have two options:

    * **Send `portrait_image`** in Base64 (max 2MB) from your own database. It always takes precedence when provided.
    * **Omit `portrait_image`** and pass the user's `vendor_data`. Didit automatically reuses the face already stored for that user, resolved in this order:
      1. Face captured during an **approved liveness check**
      2. **ePassport chip photo** from an approved ID verification
      3. **Portrait cropped from the ID document** of an approved ID verification
      4. **Manually enrolled profile face** (Users API or Console upload)

    ```json theme={null}
    {
      "workflow_id": "11111111-2222-3333-4444-555555555555",
      "vendor_data": "user-123",
      "callback": "https://example.com/verification/callback",
      "metadata": { "login_attempt": "2" }
    }
    ```

    <Warning>
      Only faces from **approved** sessions (or faces you enrolled yourself) are ever reused. If you omit `portrait_image` and the user has no stored face, session creation fails with `400` and the message `No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first.` If you omit `vendor_data` as well, the `400` message asks you to send a `portrait_image` or a `vendor_data` with a stored face.
    </Warning>
  </Step>

  <Step title="Live Photo Capture" icon="camera">
    During the authentication process:

    | Check                     | Description                                                    |
    | ------------------------- | -------------------------------------------------------------- |
    | **Liveness verification** | Prevents spoofing using Passive Liveness or 3D Action & Flash  |
    | **Image quality**         | System evaluates lighting, positioning, and clarity            |
    | **Retry guidance**        | Poor quality images are rejected with improvement instructions |
    | **Real-time feedback**    | User sees positioning guides for optimal capture               |
  </Step>

  <Step title="Verification & Result Processing" icon="shield-check">
    The system processes the verification based on your workflow configuration:

    <AccordionGroup>
      <Accordion title="Liveness-Only Mode" icon="face-viewfinder">
        If **Face Match is disabled** in the workflow, the system only confirms the user's liveness; no reference face is needed and `portrait_image` is not required. A successful check results in an **approved** authentication, useful for simple presence verification.
      </Accordion>

      <Accordion title="Liveness + Face Match Mode" icon="user-check">
        If **Face Match is enabled** in the workflow (reference face from `portrait_image` or the user's stored face):

        1. System performs the **liveness check** first
        2. If liveness passes, compares the new selfie with the reference face
        3. A **similarity score (0–100%)** is generated
        4. Score above your configured threshold → **Approved**
        5. Score below threshold → **Declined**
      </Accordion>
    </AccordionGroup>

    Results are available via **API response**, **Business Console**, and **webhooks**.
  </Step>
</Steps>


# Biometric Authentication Report
Source: https://docs.didit.me/core-technology/biometric-auth/report-biometric-authentication

Parse Biometric Authentication responses with liveness and optional face match against a stored portrait, returned via liveness_checks and face_matches.

The Biometric Authentication report is how Didit reports back a returning-user re-verification. The workflow runs a fresh liveness check and, when Face Match is enabled in the workflow, a 1:1 face match against the reference face resolved at session creation (the `portrait_image` you supplied, or the user's stored face looked up by `vendor_data`). Both checks appear as standard feature items in the V3 session decision response.

<Frame>
  <img alt="Didit biometric authentication report combining liveness check and face match against a stored portrait" />
</Frame>

## Overview

Biometric Authentication is a workflow type (`workflow_type: "biometric_authentication"`), not a separate response object. When the workflow runs it emits:

* One **liveness check** that captures a live selfie and scores it for spoofing.
* One **face match** comparing the captured face against the reference face resolved at session creation (only when Face Match is enabled in the workflow).

Whenever the workflow includes Face Match, session creation needs a reference face. Send `portrait_image` (base64-encoded image, max 2MB), or omit it and Didit reuses the face already stored for the `vendor_data` user: an approved liveness face first, then the ePassport chip photo, then the ID document portrait, then a manually enrolled profile face. If neither `portrait_image` nor a stored face is available, session creation returns `400` with `{"portrait_image": "No stored face image was found for this user. Send a portrait_image, or complete an approved verification with face liveness or an ID document for this vendor_data first."}`. In both cases the resolved reference is recorded under the new session, so the face-match item's `source_image_session_id` is set to that session's own `session_id` (it tells you the reference came from the session's stored portrait rather than from a document portrait captured in the same session, which would leave the field `null`).

## Where it appears

| Decision response key | Plural                                                      | Item schema                                                         |
| --------------------- | ----------------------------------------------------------- | ------------------------------------------------------------------- |
| `liveness_checks[]`   | One per liveness step (usually 1 in biometric auth)         | [data-models#liveness-check](/reference/data-models#liveness-check) |
| `face_matches[]`      | One per face-match step (`null` in liveness-only workflows) | [data-models#face-match](/reference/data-models#face-match)         |

Both arrays are returned by [`GET /v3/session/{sessionId}/decision/`](/sessions-api/retrieve-session) for sessions whose workflow type is `biometric_authentication`. They are always arrays — never singular objects — and each is `null` until its step has produced data. Each item carries a `node_id` so that multi-instance workflows can disambiguate steps.

## Schema reference

The full field list is defined once on the data-models page so every report that surfaces these features shares one source of truth:

* [Liveness item schema](/reference/data-models#liveness-check) — `status`, `method`, `score`, `reference_image`, `video_url`, `age_estimation`, `matches[]`, `face_quality`, `face_luminance`, `warnings[]`, `node_id`.
* [Face match item schema](/reference/data-models#face-match) — `status`, `score`, `source_image_session_id`, `source_image`, `target_image`, `warnings[]`, `node_id`.
* [Warning entry shape](/reference/data-models#warning-object) — `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`.

## Status values

Both `liveness_checks[].status` and `face_matches[].status` use the shared feature lifecycle ([feature-level statuses](/reference/data-models#feature-level-statuses)):

| Status            | Meaning                                                                                                                                                                     |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Not Finished`    | The step has not produced a final result yet (user has not completed it, or dropped off). Before a step starts at all, its array is simply `null` in the decision response. |
| `Approved`        | The check passed all configured thresholds.                                                                                                                                 |
| `In Review`       | The score fell in the review band, or a configurable warning was set to review.                                                                                             |
| `Declined`        | The score fell at or below the decline threshold, or an auto-decline warning fired (face attack, no face detected, face blocklisted, no reference image for face match).    |
| `Resub Requested` | A reviewer asked the user to retry this step.                                                                                                                               |

The overall session `status` aggregates both items: any feature in `Declined` declines the session, any in `In Review` puts the session in `In Review`, otherwise `Approved` (after every feature finishes).

For threshold behavior and the full list of warning codes, see [Biometric Authentication warnings](/core-technology/biometric-auth/warnings-biometric-authentication).

## Example — liveness + face match (approved)

Examples are abridged: the full decision envelope also carries `session_url`, `metadata`, `callback`, `reviews`, `contact_details`, `expected_details`, `environment`, `created_at`, and `expires_at`.

```json theme={null}
{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_kind": "user",
  "session_number": 1234,
  "status": "Approved",
  "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa",
  "features": ["LIVENESS", "FACE_MATCH"],
  "vendor_data": "user-123",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 89.92,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": 92.4,
      "face_luminance": 58.1,
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "Approved",
      "score": 88.47,
      "source_image_session_id": "11111111-2222-3333-4444-555555555555",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": []
    }
  ],
  "id_verifications": null,
  "nfc_verifications": null,
  "poa_verifications": null,
  "phone_verifications": null,
  "email_verifications": null,
  "aml_screenings": null
}
```

## Example — liveness-only (Face Match disabled in the workflow)

```json theme={null}
{
  "session_id": "22222222-3333-4444-5555-666666666666",
  "session_kind": "user",
  "status": "Approved",
  "workflow_id": "018e7b2c-6666-7777-9999-bbbbbbbbbbbb",
  "features": ["LIVENESS"],
  "vendor_data": "user-456",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "ACTIVE_3D",
      "score": 96.10,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": null,
      "face_luminance": null,
      "warnings": []
    }
  ],
  "face_matches": null
}
```

Liveness-only mode is a workflow configuration: when Face Match is disabled, no reference face is needed at session creation and `face_matches` stays `null`. When Face Match **is** enabled, omitting `portrait_image` does not fall back to liveness-only: Didit reuses the face stored for the `vendor_data` user, and if no stored face exists session creation fails with `400`.

## Example — face-match declined on low similarity

```json theme={null}
{
  "session_id": "33333333-4444-5555-6666-777777777777",
  "status": "Declined",
  "workflow_id": "018e7b2c-5555-7777-9999-aaaaaaaaaaaa",
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Approved",
      "method": "PASSIVE",
      "score": 91.20,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": 90.15,
      "face_luminance": 55.30,
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "Declined",
      "score": 41.18,
      "source_image_session_id": "33333333-4444-5555-6666-777777777777",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "LOW_FACE_MATCH_SIMILARITY",
          "additional_data": null,
          "log_type": "error",
          "short_description": "Low face match similarity",
          "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
          "node_id": "feature_face_match"
        }
      ]
    }
  ]
}
```

## Security note

`reference_image`, `video_url`, `source_image`, and `target_image` are signed URLs that expire after a limited validity window (4 hours by default). They point at biometric data — do not cache or surface them publicly. Store the verification result (status, score, `source_image_session_id`) on your side; re-fetch the decision endpoint if you need fresh URLs.

## Related

<CardGroup>
  <Card title="Biometric Auth warnings" icon="triangle-exclamation" href="/core-technology/biometric-auth/warnings-biometric-authentication">
    Warning codes, thresholds, and automatic decline conditions.
  </Card>

  <Card title="Liveness report" icon="face-viewfinder" href="/core-technology/liveness/report-liveness">
    Full field reference for `liveness_checks[]` items.
  </Card>

  <Card title="Face Match report" icon="user-check" href="/core-technology/face-match/report-face-match">
    Full field reference for `face_matches[]` items.
  </Card>
</CardGroup>


# Biometric Authentication Warnings
Source: https://docs.didit.me/core-technology/biometric-auth/warnings-biometric-authentication

Handle biometric auth warnings: LOW_LIVENESS_SCORE, face attacks, blocklist matches, and low face-match similarity. Configure thresholds and decline actions.

Biometric Authentication combines a liveness check with an optional 1:1 face match against the reference face resolved at session creation (the supplied `portrait_image`, or the user's stored face looked up by `vendor_data`). Each step emits its own warnings in the V3 decision payload. This page lists every code, where it appears, and how thresholds translate into a final session status.

## Overview

When a biometric authentication session runs, Didit:

* Captures a live selfie using 3D Action, Flash, or Passive Liveness (`method`: `ACTIVE_3D`, `FLASHING`, or `PASSIVE`).
* Extracts the largest face from the capture and scores its liveness.
* If the workflow includes Face Match, compares the captured face against the session's reference face (supplied `portrait_image` or the user's stored face).
* Writes the outcome of each step plus any warnings into the session decision.

Warnings keep the shared [warning object](/reference/data-models#warning-object) shape used across the platform: `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, and `node_id`.

## Where warnings appear

| Decision response key          | Feature tag on the warning | When it fires                                                                                                 |
| ------------------------------ | -------------------------- | ------------------------------------------------------------------------------------------------------------- |
| `liveness_checks[].warnings[]` | `LIVENESS`                 | Liveness scoring, face quality, luminance, multiple-faces, and blocklist / allowlist / duplicate-face checks. |
| `face_matches[].warnings[]`    | `FACEMATCH`                | Face match against the session's reference face (supplied `portrait_image` or the user's stored face).        |

In a typical biometric-auth session there is one item in each array. In multi-instance workflows the `node_id` on each warning disambiguates which step produced it.

## Automatic decline conditions

The following warnings always decline their step (`log_type: "error"`) regardless of how you configured the workflow:

| Risk                   | Feature     | Why it auto-declines                                                                                                |
| ---------------------- | ----------- | ------------------------------------------------------------------------------------------------------------------- |
| `FACE_IN_BLOCKLIST`    | `LIVENESS`  | The face matched an entry in your face blocklist.                                                                   |
| `NO_FACE_DETECTED`     | `LIVENESS`  | No face was located during the liveness capture, or the user exhausted the capture retry attempts.                  |
| `LIVENESS_FACE_ATTACK` | `LIVENESS`  | A presentation attack was detected (mask, screen replay, deepfake-class spoof).                                     |
| `NO_REFERENCE_IMAGE`   | `FACEMATCH` | No reference image was available to run the comparison. When this fires, `LOW_FACE_MATCH_SIMILARITY` is suppressed. |

When `NO_FACE_DETECTED` fires, `LOW_LIVENESS_SCORE` is suppressed (there is no face to score).

## Configurable thresholds and actions

These warnings are scored and then mapped to a status through thresholds and actions you set per workflow:

| Risk                                           | Feature     | Configurable behavior                                                                                                                                                                                                                                                                                                              |
| ---------------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LOW_LIVENESS_SCORE`                           | `LIVENESS`  | Score at or below the review threshold → `In Review`; at or below the decline threshold → `Declined`.                                                                                                                                                                                                                              |
| `LOW_FACE_MATCH_SIMILARITY`                    | `FACEMATCH` | Score at or below the review threshold (default 70) → `In Review`; at or below the decline threshold (default 50) → `Declined`.                                                                                                                                                                                                    |
| `LOW_FACE_QUALITY`                             | `LIVENESS`  | Review threshold (default 15) → `In Review`; decline threshold (default 0, i.e. decline disabled) → `Declined`. Passive Liveness only.                                                                                                                                                                                             |
| `LOW_FACE_LUMINANCE`                           | `LIVENESS`  | Below the minimum luminance threshold (default 20): No action / Review (default) / Decline. Passive Liveness only.                                                                                                                                                                                                                 |
| `HIGH_FACE_LUMINANCE`                          | `LIVENESS`  | Above the maximum luminance threshold (default 80): No action / Review (default) / Decline. Passive Liveness only.                                                                                                                                                                                                                 |
| `MULTIPLE_FACES_DETECTED`                      | `LIVENESS`  | No action (default) / Review / Decline when more than one face is captured. Passive Liveness only.                                                                                                                                                                                                                                 |
| `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` | `LIVENESS`  | One shared duplicate-face action: No action (default) / Review / Decline for matches against other users' approved or imported faces.                                                                                                                                                                                              |
| `DUPLICATED_FACE_NAME_MISMATCH`                | `LIVENESS`  | Own action (`face_liveness_duplicated_face_name_mismatch_action`): No action / Review (default) / Decline. Emitted alongside `DUPLICATED_FACE` when the matched session's identity does not match this session's resolved name — see [Liveness warnings](/core-technology/liveness/warnings-liveness#cross-session-face-matching). |

`POSSIBLE_FACE_IN_BLOCKLIST` (`LIVENESS`) is **not** configurable — a lower-confidence blocklist match is always routed to Review (`log_type: "warning"`).

## Capture retries

Failures driven only by fixable capture-quality risks (low score, no face, quality, luminance, multiple faces — and low similarity on face match) enter a retry loop before the status sticks: the user gets up to `face_liveness_max_attempts` / `face_match_max_attempts` total attempts (default 3, configurable 2–5 per workflow node). When the budget is exhausted, the last attempt's computed status applies and `LIVENESS_MAX_ATTEMPTS_EXCEEDED` or `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` is logged as `information` to record it.

## Liveness warnings

The API returns these exact `short_description` and `long_description` strings:

| `risk`                                     | `short_description`                                  | `long_description`                                                                                                                                                                                                        |
| ------------------------------------------ | ---------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `LOW_LIVENESS_SCORE`                       | Low liveness score                                   | The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data.                                                                                   |
| `NO_FACE_DETECTED`                         | No Face Detected in liveness                         | The system couldn't identify a face during the liveness check, which may be due to poor image quality, improper positioning, or technical issues.                                                                         |
| `LIVENESS_FACE_ATTACK`                     | Liveness Face Attack                                 | The system detected a potential attempt to bypass the liveness check.                                                                                                                                                     |
| `FACE_IN_BLOCKLIST`                        | Face in blocklist                                    | The system identified a face in the blocklist, which means the face is not allowed to be verified.                                                                                                                        |
| `POSSIBLE_FACE_IN_BLOCKLIST`               | Possible face in blocklist                           | The system identified a possible face in the blocklist, which means the face is not allowed to be verified.                                                                                                               |
| `FACE_IN_ALLOWLIST`                        | Face in allowlist                                    | The face matched the application's face allowlist, so duplicate-face actions were skipped for this signal.                                                                                                                |
| `POSSIBLE_FACE_IN_ALLOWLIST`               | Possible face in allowlist                           | The face possibly matched the application's face allowlist, so possible duplicate-face actions were skipped for this signal.                                                                                              |
| `DUPLICATED_FACE`                          | Duplicated face from other approved session          | The system identified a duplicated face from another approved session, requiring further investigation.                                                                                                                   |
| `POSSIBLE_DUPLICATED_FACE`                 | Possible duplicated face from other approved session | The system identified a possible duplicate face from another approved session, requiring further investigation.                                                                                                           |
| `DUPLICATED_FACE_NAME_MISMATCH`            | Duplicated face under a different name               | The same face was already approved on another session, but under a different name. The identity behind the duplicate does not match the identity declared on this session, which is a strong indicator of identity fraud. |
| `MULTIPLE_FACES_DETECTED` *(Passive only)* | Multiple faces detected                              | Multiple faces were detected in the liveness image. The system uses the largest face for liveness verification and face comparison, but the presence of multiple faces may require additional review.                     |
| `LOW_FACE_QUALITY` *(Passive only)*        | Low face quality                                     | The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.                              |
| `LOW_FACE_LUMINANCE` *(Passive only)*      | Low face luminance                                   | The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.                                                                                            |
| `HIGH_FACE_LUMINANCE` *(Passive only)*     | High face luminance                                  | The facial image is too bright or overexposed, which may affect the accuracy of liveness detection. Reduced lighting or avoiding direct light is recommended.                                                             |
| `LIVENESS_MAX_ATTEMPTS_EXCEEDED`           | Maximum liveness attempts exceeded                   | The maximum number of liveness capture attempts has been reached. The last attempt's computed status (decline or review) has been applied.                                                                                |

Blocklist, allowlist, and duplicate matches carry `additional_data` with the matched session (`blocklisted_session_id` / `allowlisted_session_id` / `duplicated_session_id`, the matching `*_session_number`, and `api_service`). Only one of those six codes appears per report. `DUPLICATED_FACE_NAME_MISMATCH` is the exception: it is emitted **in addition to** `DUPLICATED_FACE`, never instead of it, when the matched session's identity does not match this session's resolved name. Its `additional_data` adds `name_match_score` to the same duplicate-session fields.

## Face-match warnings

| `risk`                             | `short_description`                             | `long_description`                                                                                                                           |
| ---------------------------------- | ----------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| `LOW_FACE_MATCH_SIMILARITY`        | Low face match similarity                       | The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.                 |
| `NO_REFERENCE_IMAGE`               | No source image found for performing face match | A reference image for facial comparison is missing, preventing the system from completing the face matching process.                         |
| `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` | Maximum face match attempts exceeded            | The maximum number of face match capture attempts has been reached. The last attempt's computed status (decline or review) has been applied. |

## Example — declined on face attack

```json theme={null}
{
  "liveness_checks": [
    {
      "node_id": "feature_liveness",
      "status": "Declined",
      "method": "ACTIVE_3D",
      "score": 12.40,
      "reference_image": "https://<media-host>/.../reference.jpg",
      "video_url": "https://<media-host>/.../video.mp4",
      "age_estimation": null,
      "matches": [],
      "face_quality": null,
      "face_luminance": null,
      "warnings": [
        {
          "feature": "LIVENESS",
          "risk": "LIVENESS_FACE_ATTACK",
          "additional_data": null,
          "log_type": "error",
          "short_description": "Liveness Face Attack",
          "long_description": "The system detected a potential attempt to bypass the liveness check.",
          "node_id": "feature_liveness"
        }
      ]
    }
  ],
  "face_matches": null
}
```

## Example — in review on low similarity

```json theme={null}
{
  "face_matches": [
    {
      "node_id": "feature_face_match",
      "status": "In Review",
      "score": 58.70,
      "source_image_session_id": "11111111-2222-3333-4444-555555555555",
      "source_image": "https://<media-host>/.../source.jpg",
      "target_image": "https://<media-host>/.../target.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "LOW_FACE_MATCH_SIMILARITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face match similarity",
          "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
          "node_id": "feature_face_match"
        }
      ]
    }
  ]
}
```

The score (58.70) sits between the decline threshold (default 50) and the review threshold (default 70), so the warning carries `log_type: "warning"` and the face-match status is `In Review`. In this example the warning fired on a session whose `session_id` is `11111111-2222-3333-4444-555555555555` — `source_image_session_id` carries the session's own id because the reference came from the portrait stored at session creation.

## Warning types

Each risk is assigned a warning type based on your application's configuration. Warnings fall into three severity categories:

<WarningTypes />

## Related

<CardGroup>
  <Card title="Biometric Auth report" icon="user-shield" href="/core-technology/biometric-auth/report-biometric-authentication">
    Where `liveness_checks[]` and `face_matches[]` appear in the V3 decision.
  </Card>

  <Card title="Liveness warnings" icon="face-viewfinder" href="/core-technology/liveness/warnings-liveness">
    Full liveness-warning reference including duplicate-face matching.
  </Card>

  <Card title="Face Match warnings" icon="user-check" href="/core-technology/face-match/warnings-face-match">
    Full face-match warning reference for 1:1 comparisons.
  </Card>
</CardGroup>


# Database Validation Matching Methods
Source: https://docs.didit.me/core-technology/database-validation/database-validation-matching-methods

How 1x1 and 2x2 outcomes are derived from per-service matches: fuzzy name thresholds, partialMatchAction rules, waterfall logic. From $0.05/check.

Didit's [Database Validation](/core-technology/database-validation/overview) API checks identity data against the authoritative civil registry, tax authority or electoral roll for each country — RENAPER (Argentina), Receita Federal (Brazil), Tribunal Electoral (Panama), RENAPO (Mexico), Junta Central Electoral (Dominican Republic), Registraduría Nacional (Colombia) and more. Each query is billed per successful call, from **\$0.05/check** with no monthly minimums.

Outcomes are derived from per-service results: **1×1** when a single registry returns a full match, **2×2** when two independent registries corroborate the data. This page documents how those outcomes are computed, the fuzzy-match thresholds applied to names, and the decision logic that governs `partialMatchAction` and `noMatchAction` in your workflow rules.

## 1×1 matching

This method involves matching one input data point (typically a national ID or similar identifier) against our database. If a direct match is found, we confirm the identity. However, if the initial attempt fails, we may try alternate trusted data sources in a waterfall sequence. This means we continue validating through successive providers until we either achieve a match or exhaust all options. Importantly, a partial match does not stop the process—we only stop once we find a full and conclusive match or determine that no match exists.

The 1x1 Matching logic requires matching a user’s personal data against one source to receive a <span>Full Match</span> on their identity.\*

| Verification Result        | Name Category              | ID Category             | Date of Birth Category |
| :------------------------- | :------------------------- | :---------------------- | :--------------------- |
| <span>Full Match</span>    | <span>Full Match</span>    | <span>Full Match</span> | Any Value              |
| <span>Partial Match</span> | <span>Partial Match</span> | <span>Full Match</span> | Any Value              |
| <span>No Match</span>      | All other combinations     |                         |                        |

*\*The applicable country sources are screened until a Full Match on the identity is made. If a Full Match is not found, the system then repeatedly screens those sources for a Partial Match on the user’s identity.*

## 2×2 matching

This method requires matching two input data points (e.g., name + date of birth, or national ID + phone number) against two corresponding fields in our database. Just like with 1x1, we follow a waterfall approach, querying multiple data sources sequentially. We persist through each step until we find a complete match across both data fields. Partial or single-field matches are not sufficient; the validation process continues until a definitive 2-field match is achieved or all sources have been checked.

The 2x2 Matching logic requires matching a user’s personal data against two sources to receive a <span>Full Match</span> on their identity.\*

| Verification Result        | 1st Data Source                                                       | 2nd Data Source                                                       |
| :------------------------- | :-------------------------------------------------------------------- | :-------------------------------------------------------------------- |
| <span>Full Match</span>    | Name <span>Full Match</span> + National ID <span>Full Match</span>    | Name <span>Full Match</span> + National ID <span>Full Match</span>    |
| <span>Full Match</span>    | Name <span>Full Match</span> + National ID <span>Full Match</span>    | Name <span>Partial Match</span> + National ID <span>Full Match</span> |
| <span>Full Match</span>    | Name <span>Full Match</span> + National ID <span>Full Match</span>    | Name <span>Full Match</span> + Date of Birth <span>Full Match</span>  |
| <span>Full Match</span>    | Name <span>Full Match</span> + National ID Any Value                  | Name <span>Full Match</span> + National ID Any Value                  |
| <span>Partial Match</span> | Name <span>Full Match</span> + National ID <span>Full Match</span>    |                                                                       |
| <span>Partial Match</span> | Name <span>Partial Match</span> + National ID <span>Full Match</span> |                                                                       |
| <span>Partial Match</span> | Name <span>Full Match</span> + Date of Birth <span>Full Match</span>  |                                                                       |
| <span>Partial Match</span> | Name <span>Full Match</span> + National ID Any Value                  |                                                                       |
| <span>No Match</span>      | All other combinations                                                |                                                                       |

*\*The applicable country sources are screened until a Full Match on the identity is made. If a Full Match is not found, the system then repeatedly screens those sources for a Partial Match on the user’s identity.*

***

## Data category and attribute matching

The following are the scenarios that result in a <span>Full Match</span> for the Name, Date of Birth, and ID data categories. A <span>Partial Match</span> is only possible for the Name category.

### Name category matching

A **<span>Full Match</span>** on the Name category is considered when any of the following data attribute matching scenarios is met:

* Full Name Concatenation <span>Full Match</span> (First Name + Last Name combined with 85% similarity threshold)
* First Name <span>Full Match</span> + Last Name <span>Full Match</span>
* First Name <span>Full Match</span> + Maternal Name <span>Full Match</span>
* First Name <span>Full Match</span> + Paternal Name <span>Full Match</span>

A **<span>Partial Match</span>** on the Name category is considered when any of the following data attribute matching scenarios is met:

* First Name <span>Full Match</span>
* Last Name <span>Full Match</span>
* Paternal Name <span>Full Match</span>
* Maternal Name <span>Full Match</span>
* Maternal Name <span>Full Match</span> + Paternal Name <span>Full Match</span>

### Date of birth category matching

A **<span>Full Match</span>** on the Date of Birth category is considered only when the following data attribute matching scenario is met:

* Year of Birth <span>Full Match</span> + Month of Birth <span>Full Match</span> + Day of Birth <span>Full Match</span>

A <span>Partial Match</span> on the Date of Birth category is not possible.

### ID category matching

A **<span>Full Match</span>** on the ID category is considered only when the following data attribute matching scenario is met:

* Identification Number <span>Full Match</span>

A <span>Partial Match</span> on the ID category is not possible.

***

## Fuzzy matching for data attributes

These are the criteria for fuzzy matching on different data attributes against country sources.

* **Name Data Attributes**
  For a Name category data attribute to generate a <span>Full Match</span>, it should be within 70% of the Levenshtein character similarity in comparison to the records in the data sources. For full name concatenation (First Name + Last Name combined), a higher threshold of 85% similarity is used. E.g., if the Name attribute input is 'Christophel' and the actual name is 'Christopher', a <span>Full Match</span> is returned based on the fuzzy matching logic. This system is applicable to the *First Name*, *Last Name*, *Paternal Name*, and *Maternal Name* data attributes.

* **Date of Birth and ID Data Attributes**
  We do not employ any kind of fuzzy matching on data attributes within the Date of Birth or ID data categories. An exact match is required for these fields.

### Examples

Below are examples of data attribute inputs that would satisfy the criteria of the fuzzy matching logic and generate a <span>Full Match</span>.

| Data Attribute | Input       | Data Source Record | Result                  |
| :------------- | :---------- | :----------------- | :---------------------- |
| first\_name    | Christopher | Christopher        | <span>Full Match</span> |
| first\_name    | Christophel | Christopher        | <span>Full Match</span> |
| first\_name    | Chris       | Christopher        | <span>No Match</span>   |
| last\_name     | Smith       | Smith              | <span>Full Match</span> |
| last\_name     | Smyth       | Smith              | <span>Full Match</span> |
| last\_name     | Smitty      | Smith              | <span>No Match</span>   |

## See also

* [Database Validation overview](/core-technology/database-validation/overview) — how the API works end-to-end, supported registries, pricing.
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes) — full list of provider response codes (deceased, minor, document not found, biometric mismatch).
* [Warnings](/core-technology/database-validation/database-validation-warnings) — what we surface when a service can't run due to missing input.
* [Supported Countries & Services](/core-technology/database-validation/database-validation-supported-countries) — every live registry, required fields and per-call price.
* [Reports](/core-technology/database-validation/database-validation-report) — monthly per-service billing exports.


# Database Validation Outcome Codes
Source: https://docs.didit.me/core-technology/database-validation/database-validation-outcome-codes

Every outcome code Didit's Database Validation returns: match, no match, deceased, minor, document not found, biometric mismatch. From $0.05/check.

Didit's [Database Validation](/core-technology/database-validation/overview) API queries the authoritative civil registry for each country — RENAPER (Argentina, \$0.20/check with biometric face-match), Receita Federal (Brazil, \$0.20), Tribunal Electoral SIB (Panama, \$0.75 biometric), Junta Central Electoral (Dominican Republic, \$0.05) and 14 more — billed per successful query, no monthly minimums.

When you run a Database Validation, you get back two layers of result:

1. A **standard outcome code** that works the same way across every supported country, so you can write one piece of handling logic that covers all of them.
2. An optional **country-specific detail code** that tells you exactly which condition the government registry returned — useful for support, analytics, and deciding whether to prompt the user to retry.

This page lists every value you can see and tells you how to react to each one.

## Standard outcome codes

These codes are identical across every country. Build your review, decline, and retry logic on top of these — not on the per-country detail codes.

| Outcome code               | Meaning                                                                                                                                                                                                                                                                                                                                                                                                         | Retryable? | Recommended handling                                                                                                                                                                                                               |
| :------------------------- | :-------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | :--------: | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MATCH`                    | The registry confirmed the identity and every checked field matched.                                                                                                                                                                                                                                                                                                                                            |      —     | Approve.                                                                                                                                                                                                                           |
| `PARTIAL_MATCH`            | The identification number was found but one or more personal fields did not fully match (usually name or date of birth).                                                                                                                                                                                                                                                                                        |      —     | Send to review or configure a [Partial Match Action](/core-technology/database-validation/database-validation-warnings) to auto-decline.                                                                                           |
| `NO_MATCH`                 | The registry returned no match for the submitted data.                                                                                                                                                                                                                                                                                                                                                          |     No     | Decline, or send to review depending on your policy.                                                                                                                                                                               |
| `DOCUMENT_SUPERSEDED`      | The registry confirmed the person's identity, but the **edition of the document** presented is not the one it holds on file — a newer edition has since been issued, so the credential in hand is stale. Argentina's DNI *ejemplar* letter is the canonical case. Distinct from `NO_MATCH` (the person did not match) and `DOCUMENT_NOT_FOUND` (no record at all): only the physical credential is out of date. |     No     | Send to review and ask for the current edition of the document. It rides your **No Match Action** and raises [`DATABASE_VALIDATION_DOCUMENT_SUPERSEDED`](/core-technology/database-validation/database-validation-warnings).       |
| `DOCUMENT_NOT_FOUND`       | The identification number is syntactically valid but does not exist in the government registry.                                                                                                                                                                                                                                                                                                                 |     No     | Decline.                                                                                                                                                                                                                           |
| `INVALID_DOCUMENT_FORMAT`  | The submitted identification number is malformed (wrong length, non-numeric, bad checksum).                                                                                                                                                                                                                                                                                                                     |     No     | Ask the user to re-enter their document number.                                                                                                                                                                                    |
| `INVALID_INPUT`            | A required input field (selfie, gender, date of birth, etc.) was missing or malformed.                                                                                                                                                                                                                                                                                                                          |     No     | Ask the user to resubmit the missing field. The session will automatically reprocess once the data is provided — see [`COULD_NOT_PERFORM_DATABASE_VALIDATION`](/core-technology/database-validation/database-validation-warnings). |
| `MINOR_BLOCKED`            | The registry withheld the record because the subject is a minor. Applies in jurisdictions with data-protection laws for minors (Brazil LGPD, Argentina).                                                                                                                                                                                                                                                        |     No     | Decline. Respect the local legal framework — do not retry.                                                                                                                                                                         |
| `DECEASED`                 | The registry reports that the subject is deceased.                                                                                                                                                                                                                                                                                                                                                              |     No     | Decline.                                                                                                                                                                                                                           |
| `BIOMETRIC_NO_MATCH`       | For biometric validations (Argentina, Panama), the face-match score was below the acceptance threshold.                                                                                                                                                                                                                                                                                                         |     No     | Decline, or send to review.                                                                                                                                                                                                        |
| `BIOMETRIC_IMAGE_UNUSABLE` | The selfie could not be processed — image was empty, had no face, had low quality, or the registry could not read it.                                                                                                                                                                                                                                                                                           |     Yes    | Prompt the user to retake the selfie.                                                                                                                                                                                              |
| `INCONCLUSIVE`             | The registry could not determine whether the person matches — the result is genuinely uncertain (they may or may not be in the registry). Distinct from `NO_MATCH` (definitively absent) and from `BIOMETRIC_IMAGE_UNUSABLE` (a technical image problem): nothing was confirmed either way, so `match_type` is `null`.                                                                                          |    Maybe   | Send to review. A retry with a clearer selfie or additional data may resolve it.                                                                                                                                                   |
| `REGISTRY_UNAVAILABLE`     | The government registry is temporarily unreachable (timeout, connectivity error, upstream 5xx).                                                                                                                                                                                                                                                                                                                 |     Yes    | Retry after a short delay. Didit already retries transient errors automatically, so seeing this in the final report means the retries were exhausted.                                                                              |
| `REGISTRY_ERROR`           | The registry returned an unexpected failure that does not fit any of the buckets above.                                                                                                                                                                                                                                                                                                                         |    Maybe   | Escalate to support with the detail code.                                                                                                                                                                                          |

<Note>
  The `outcome_code` lives inside each entry of the `validations` array on the validation report. See [Database Validation Report](/core-technology/database-validation/database-validation-report) for where it fits in the response.
</Note>

<Note>
  `REGISTRY_UNAVAILABLE` and `REGISTRY_ERROR` mean the source registry never answered the query, so those two outcomes are **not billed** - see [pricing](/core-technology/database-validation/overview). Every other outcome code is a real, paid response from the registry, even one that confirms nothing (`INCONCLUSIVE`, `BIOMETRIC_IMAGE_UNUSABLE`) and even one that rejects what you sent (`INVALID_DOCUMENT_FORMAT`, `INVALID_INPUT` — as outcome codes these mean the registry itself refused the data, after the query went out).

  Input that never reaches a registry produces no outcome code at all: `POST /v3/database-validation/` answers `400` when a value fails the country format rules, and a workflow service with missing or malformed fields is skipped with [`COULD_NOT_PERFORM_DATABASE_VALIDATION`](/core-technology/database-validation/database-validation-warnings). Neither is billed. Full breakdown on the [Database Validation pricing page](/getting-started/database-validation-pricing).
</Note>

## Country-specific detail codes

The detail code is returned as `outcome_detail` alongside `outcome_code`. Only countries listed below produce detail codes beyond the standard outcome — every other supported country returns the standard codes only.

### Argentina (RENAPER)

Argentina uses a biometric 1×1 validation against the RENAPER national identity registry, combining the DNI, a selfie, and declared gender.

| Detail code      | Standard outcome           | What it means                                                    |
| :--------------- | :------------------------- | :--------------------------------------------------------------- |
| `300`            | `INVALID_DOCUMENT_FORMAT`  | The DNI field must be a 7–8 digit number.                        |
| `301`            | `DOCUMENT_NOT_FOUND`       | The submitted DNI does not match a valid record.                 |
| `303`            | `INVALID_INPUT`            | The selfie field was empty.                                      |
| `304`            | `INVALID_INPUT`            | The gender field was empty or not one of `M`, `F`, `X`.          |
| `305`            | `NO_MATCH`                 | The DNI and gender combination was not found.                    |
| `306`            | `REGISTRY_UNAVAILABLE`     | The query cannot be carried out at this time.                    |
| `307`            | `REGISTRY_UNAVAILABLE`     | Error connecting to the public identity validation system.       |
| `311`            | `REGISTRY_ERROR`           | The integration does not have access to this product.            |
| `313`            | `MINOR_BLOCKED`            | The record belongs to an underage person.                        |
| `400`            | `REGISTRY_UNAVAILABLE`     | Connection error.                                                |
| `401`            | `NO_MATCH`                 | No results found for the provided data.                          |
| `405`            | `BIOMETRIC_IMAGE_UNUSABLE` | Conflict with the image; it cannot be processed.                 |
| `406`            | `BIOMETRIC_IMAGE_UNUSABLE` | Error in image processing.                                       |
| `NO.HIT`         | `BIOMETRIC_NO_MATCH`       | The face-match score was below the acceptance threshold (\< 50). |
| `INTERNAL_ERROR` | `REGISTRY_UNAVAILABLE`     | Timeout exceeded.                                                |

### Brazil (Receita Federal — Consulta CPF)

Brazil validates the CPF against the Receita Federal's official CPF service, with explicit handling for minors under the LGPD (Lei Geral de Proteção de Dados) and the Children's and Adolescents' Digital Statute.

| Detail code | Standard outcome          | What it means                                                                                                                                                                                  |
| :---------- | :------------------------ | :--------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `200`       | `MATCH`                   | CPF found and data returned successfully.                                                                                                                                                      |
| `206`       | `MATCH`                   | CPF found, but some non-essential fields were not returned.                                                                                                                                    |
| `400`       | `INVALID_DOCUMENT_FORMAT` | CPF number is not valid.                                                                                                                                                                       |
| `404`       | `DOCUMENT_NOT_FOUND`      | No CPF exists with the submitted number.                                                                                                                                                       |
| `422`       | `MINOR_BLOCKED`           | Data for a minor under 18 is withheld per LGPD (Law 13.709/2018). The response includes `minor_under_18: true`.                                                                                |
| `451`       | `MINOR_BLOCKED`           | Data for a minor under 16 is withheld per LGPD and the Children's and Adolescents' Digital Statute (Law 15.211/2025). The response includes `minor_under_18: true` and `minor_under_16: true`. |
| `500`       | `REGISTRY_UNAVAILABLE`    | Upstream server error.                                                                                                                                                                         |
| `504`       | `REGISTRY_UNAVAILABLE`    | Gateway timeout — the request did not reach the Consulta CPF API.                                                                                                                              |

<Note>
  For `MINOR_BLOCKED` outcomes in Brazil, `source_data` still returns the `lgpd_minor`, `minor_under_18`, and `minor_under_16` flags so you can apply age-appropriate flows without retrying.
</Note>

### Panama (SIB — Tribunal Electoral)

Panama uses biometric validation against the SIB (Servicio de Identificación Biométrica) registry operated by the Tribunal Electoral. If a technical SIB error occurs, the session falls back to a 1×1 lookup automatically.

| Detail code | Standard outcome           | What it means                            |
| :---------- | :------------------------- | :--------------------------------------- |
| `601`       | `REGISTRY_UNAVAILABLE`     | Operator does not exist in the database. |
| `602`       | `MINOR_BLOCKED`            | Citizen is under 12 years old.           |
| `603`       | `DECEASED`                 | Citizen is deceased.                     |
| `604`       | `NO_MATCH`                 | Citizen has an invalid registration.     |
| `605`       | `NO_MATCH`                 | Citizen not recognized.                  |
| `606`       | `INVALID_INPUT`            | Cédula field is empty.                   |
| `607`       | `DOCUMENT_NOT_FOUND`       | Citizen not found.                       |
| `608`       | `REGISTRY_ERROR`           | No SIB access for this client.           |
| `610`       | `BIOMETRIC_IMAGE_UNUSABLE` | General facial validation error.         |
| `611`       | `BIOMETRIC_IMAGE_UNUSABLE` | Image for comparison was not sent.       |
| `612`       | `BIOMETRIC_IMAGE_UNUSABLE` | Image has no content.                    |
| `613`       | `BIOMETRIC_IMAGE_UNUSABLE` | Invalid image format.                    |
| `614`       | `BIOMETRIC_IMAGE_UNUSABLE` | No face detected in the image.           |
| `615`       | `BIOMETRIC_NO_MATCH`       | Similarity threshold not reached.        |

### Other supported countries

The countries below return the standard outcome codes only — there are no country-specific detail codes to handle.

* **Bolivia, Colombia, Costa Rica, El Salvador, Guatemala, Honduras, Paraguay, Spain, Uruguay, Venezuela** — 1×1 lookup against the corresponding civil registry. Results map directly to `MATCH`, `NO_MATCH`, `DOCUMENT_NOT_FOUND`, `INVALID_DOCUMENT_FORMAT`, or `REGISTRY_UNAVAILABLE`.
* **Chile (Registro Civil)** — RUT lookup. Maps to the standard outcomes plus `MINOR_BLOCKED` when the registry flags an underage record.
* **Dominican Republic (JCE)** — Cédula lookup that returns a boolean validity; maps to `MATCH` or `NO_MATCH`.
* **Ecuador (Registro Civil)** — Cédula lookup.
* **Mexico (RENAPO, plus INE for 2×2)** — CURP lookup via RENAPO. When `validation_type` is `two_by_two`, an additional INE cross-reference runs; both feed into the same standard outcome codes.
* **Peru (RENIEC)** — DNI lookup.

## Handling recipe

The simplest robust handler looks like this:

```typescript theme={null}
switch (result.outcome_code) {
  case "MATCH":
    return approve();
  case "PARTIAL_MATCH":
    return review();
  case "NO_MATCH":
  case "DOCUMENT_NOT_FOUND":
  case "DECEASED":
  case "MINOR_BLOCKED":
  case "BIOMETRIC_NO_MATCH":
    return decline();
  case "INVALID_DOCUMENT_FORMAT":
  case "INVALID_INPUT":
    return askUserToFixInput(result.outcome_detail);
  case "BIOMETRIC_IMAGE_UNUSABLE":
    return askUserToRetakeSelfie();
  case "REGISTRY_UNAVAILABLE":
  case "REGISTRY_ERROR":
    return review();  // Didit already retried; a human can decide.
  default:
    return review();
}
```

<Note>
  You don't need to branch on `outcome_detail` for business logic — use it for analytics, debugging, and support tickets. The standard `outcome_code` is guaranteed to stay stable across countries and over time.
</Note>

## See also

* [Database Validation Warnings](/core-technology/database-validation/database-validation-warnings) — the session-level warning tags (`COULD_NOT_PERFORM_DATABASE_VALIDATION`, `DATABASE_VALIDATION_PARTIAL_MATCH`, `DATABASE_VALIDATION_NO_MATCH`) and how to configure your application's review/decline actions.
* [Database Validation Report](/core-technology/database-validation/database-validation-report) — the full response structure and where `outcome_code` / `outcome_detail` appear.
* [Database Validation Supported Countries](/core-technology/database-validation/database-validation-supported-countries) — the full country and matching-method list.


# Database Validation Report
Source: https://docs.didit.me/core-technology/database-validation/database-validation-report

Parse Database Validation responses: per-service match outcomes, registry source data, biometric face-match scores, and warning codes. Pay-per-call from $0.05.

Didit's [Database Validation](/core-technology/database-validation/overview) feature cross-references each user's identity data against the authoritative source for that country — RENAPER (Argentina), Receita Federal (Brazil), Tribunal Electoral (Panama, with biometric face-match), Junta Central Electoral (Dominican Republic), and more — billed per successful query with no monthly minimums.

Each entry in `database_validations[]` is one full Database Validation report — one run of a Database Validation node against one issuing state. The per-service registry outcomes live inside that entry's `validations[]` sub-array. This page documents the JSON shape so you can parse match outcomes, registry source data, and biometric scores returned by each service.

<Frame>
  <img alt="Didit database validation report showing match types and registry response fields" />
</Frame>

## Overview

A Database Validation report is produced every time a workflow node runs the Database Validation feature. Each entry in the `database_validations[]` array represents **one node run** against **one issuing state**; if the node runs multiple services for that country (for example CPF + CNH in Brazil), each service appears as a separate item inside the entry's `validations[]` sub-array. Each report contains:

* The overall feature `status` — a [`FeatureStatusChoices`](/reference/data-models#status-enum-reference) value (`Not Finished`, `Approved`, `Declined`, `In Review`).
* A roll-up `match_type` (`full_match`, `partial_match`, `no_match`, or `null` when no service returned a usable result) aggregated across services via the [matching method](/core-technology/database-validation/database-validation-matching-methods).
* The `issuing_state` (ISO 3166-1 alpha-3) and the derived `validation_type` (`one_by_one`, `two_by_two`, or `not_enabled` — never `null`).
* The `screened_data` block — the user-provided data that was sent to the registry.
* A `validations[]` array — one entry per service that produced a result, with the catalog `service_id`/`service_name`, the vendor-neutral `outcome_code`, an optional `outcome_detail`, the per-field `validation` map and the cleaned `source_data` lifted from the registry response.
* An `errors[]` array — per-service errors when a lookup failed or was skipped; the key is **omitted entirely** when there are no errors.
* A `warnings[]` array — risk events emitted during the validation (see [Database Validation warnings](/core-technology/database-validation/database-validation-warnings)).
* A `node_id` that identifies which workflow graph node produced the report (V3 sessions only).

## Where it appears in API responses

The report appears as **`database_validations[]`** in `GET /v3/session/{sessionId}/decision/` — always a JSON array, never a singular object. The array contains one entry per Database Validation node in the workflow graph; in turn, each entry's `validations[]` sub-array contains one item per registry service that produced a result.

```json theme={null}
{
  "session_id": "11111111-1111-1111-1111-111111111111",
  "status": "Approved",
  "database_validations": [
    { "node_id": "feature_db_validation_1", "status": "Approved", "...": "..." }
  ]
}
```

A `null` value means no Database Validation step has run yet.

## Schema

The canonical field-by-field schema lives on the [Data models](/reference/data-models#database-validation) page. It is produced by `DatabaseValidationV3Serializer`.

```typescript theme={null}
interface DatabaseValidation {
  node_id: string | null;
  status: "Not Finished" | "Approved" | "Declined" | "In Review"; // FeatureStatusChoices
  issuing_state: string | null;      // ISO 3166-1 alpha-3, e.g. "ARG"
  validation_type: "one_by_one" | "two_by_two" | "not_enabled"; // derived, never null
  match_type: "full_match" | "partial_match" | "no_match" | null; // null when no service returned a usable result
  screened_data: {                   // What we sent to the registry (varies by country/service)
    tax_number?: string;
    personal_number?: string;
    document_number?: string;
    first_name?: string;
    last_name?: string;
    date_of_birth?: string;          // YYYY-MM-DD
    selfie?: string;                 // Presigned URL (biometric services)
    cnh_qr_code_image?: string;      // Presigned URL (Brazil CNH QR + face match)
    document_image?: string;         // Presigned URL (services that take a document image)
    gender?: string;                 // Biometric registry services (e.g. Argentina RENAPER)
  };
  validations: Array<{
    // Catalog metadata
    service_id?: string;             // e.g. "arg_renaper"
    service_name?: string;           // e.g. "Argentina - DNI verification (RENAPER)"
    // Per-field match outcome — keys vary by service
    // (full_name, first_name, last_name, date_of_birth, identification_number, address, …)
    validation?: Record<string, "full_match" | "partial_match" | "no_match">;
    outcome_code?: string;           // Vendor-neutral outcome, see below
    outcome_detail?: string;         // Raw upstream status detail backing the outcome code
    source_data?: {                  // Cleaned registry record
      identification_number?: string;
      first_name?: string;
      last_name?: string;
      full_name?: string;
      date_of_birth?: string;
      place_of_birth?: string;
      gender?: string;
      nationality?: string;
      issue_date?: string;
      expiration_date?: string;
      photo?: string;                // Pre-signed JPEG URL
      signature?: string;            // Pre-signed JPEG URL
      face_match_score?: number;     // Biometric services only (0-100)
    };
  }>;
  errors?: Array<{                   // Omitted entirely when empty
    service_id: string;
    code?: string;                   // e.g. "invalid_screened_data", "empty_provider_response"
    message?: string;
    missing_required_fields?: string[];
    invalid_format_fields?: string[];
    field_reasons?: Record<string, string>;
  }>;
  warnings: Warning[];               // See /reference/data-models#warning-object
}
```

### Status values

`status` uses the standard feature-level enum (see [Status enums](/reference/data-models#status-enums)) — see the [Status enum reference](/reference/data-models#status-enum-reference). The enum also defines `Resub Requested`, which is not produced by Database Validation in practice.

| Status         | Meaning                                                                                                                                                                    |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Not Finished` | The validation has not produced a result yet (initial state; also recorded when a standalone call fails across all services).                                              |
| `Approved`     | No risk fired, or the only fired risks are configured `NO_ACTION` (the partial-match default).                                                                             |
| `Declined`     | A no-match or partial-match outcome whose configured action is `DECLINE`.                                                                                                  |
| `In Review`    | A no-match or partial-match outcome whose configured action is `REVIEW`, or the validation could not run at all (`COULD_NOT_PERFORM_DATABASE_VALIDATION` — always review). |

Custom per-node status rules are applied on top of this base status. See [Database Validation warnings](/core-technology/database-validation/database-validation-warnings) for the configurable actions and their defaults.

### Outcome codes

Each entry in `validations[]` carries a vendor-neutral `outcome_code` — one of `MATCH`, `PARTIAL_MATCH`, `NO_MATCH`, `DOCUMENT_NOT_FOUND`, `INVALID_DOCUMENT_FORMAT`, `INVALID_INPUT`, `MINOR_BLOCKED`, `DECEASED`, `BIOMETRIC_NO_MATCH`, `BIOMETRIC_IMAGE_UNUSABLE`, `INCONCLUSIVE`, `DOCUMENT_SUPERSEDED`, `REGISTRY_UNAVAILABLE`, `REGISTRY_ERROR`. Note the distinctions: `NO_MATCH` means the registry definitively did not confirm the data, `INCONCLUSIVE` means the registry could not determine either way (route to review, not decline), and `BIOMETRIC_IMAGE_UNUSABLE` is a technical selfie problem (retake) — unlike the definitive `BIOMETRIC_NO_MATCH`. See the full taxonomy and recommended handling on the [Outcome codes](/core-technology/database-validation/database-validation-outcome-codes) page.

### One entry per service

The `validations[]` array contains **one item for each service that produced a result payload** (a `validation` map, `source_data`, `outcome_code`, or `outcome_detail`). If your workflow runs multiple services for the same country (for example Brazil CPF + Brazil CNH), each one appears separately with its own `service_id`, `outcome_code`, and `source_data`. The roll-up `match_type` aggregates across all services (any full match → `full_match`; else any partial → `partial_match`; else `no_match`), and `validation_type` is derived from how many distinct services full-matched — see [Matching methods](/core-technology/database-validation/database-validation-matching-methods).

### Pre-signed image URLs

Image fields in `source_data` (`photo`, `signature`) and `screened_data` (`selfie`, `cnh_qr_code_image`, `document_image`) are returned as **pre-signed URLs** that expire — refresh by re-calling the decision endpoint. The raw upstream payload is intentionally not exposed via the API.

## Examples

### Approved — Brazil CPF status check (Receita Federal)

```json theme={null}
{
  "node_id": "feature_db_validation_1",
  "status": "Approved",
  "issuing_state": "BRA",
  "validation_type": "one_by_one",
  "match_type": "full_match",
  "screened_data": {
    "tax_number": "12345678900",
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1980-01-01"
  },
  "validations": [
    {
      "service_id": "bra_cpf",
      "service_name": "Brazil - CPF status check",
      "outcome_code": "MATCH",
      "outcome_detail": "200",
      "validation": {
        "full_name": "full_match",
        "date_of_birth": "full_match",
        "identification_number": "full_match"
      },
      "source_data": {
        "identification_number": "12345678900",
        "first_name": "JOHN",
        "last_name": "DOE",
        "date_of_birth": "1980-01-01",
        "lgpd_minor": false,
        "minor_under_16": false,
        "minor_under_18": false
      }
    }
  ],
  "warnings": []
}
```

### Approved — Argentina DNI biometric (RENAPER)

For Argentina, the validation uses RENAPER with a biometric face-match. The response includes a `face_match_score` and additional identity fields returned by the registry.

```json theme={null}
{
  "node_id": "feature_db_validation_1",
  "status": "Approved",
  "issuing_state": "ARG",
  "validation_type": "one_by_one",
  "match_type": "full_match",
  "screened_data": {
    "document_number": "12345678",
    "selfie": "https://<media-host>/sessions/<session-id>/selfie.jpg?X-Amz-Signature=...",
    "gender": "M",
    "first_name": "John",
    "last_name": "Doe"
  },
  "validations": [
    {
      "service_id": "arg_renaper",
      "service_name": "Argentina - DNI verification (RENAPER)",
      "outcome_code": "MATCH",
      "validation": {
        "full_name": "full_match",
        "identification_number": "full_match"
      },
      "source_data": {
        "identification_number": "12345678",
        "first_name": "John",
        "last_name": "Doe",
        "full_name": "John Doe",
        "date_of_birth": "1990-01-01",
        "tax_id": "20000000019",
        "tax_id_type": "CUIT",
        "face_match_score": 97
      }
    }
  ],
  "warnings": []
}
```

### In Review — registry could not run

When no service returns a usable result — required fields missing or malformed, or the registry unreachable — `match_type` stays `null`, `validation_type` is `not_enabled`, a `COULD_NOT_PERFORM_DATABASE_VALIDATION` warning is emitted, and the feature moves to `In Review` until the data is corrected. **No charge** is applied for skipped services.

```json theme={null}
{
  "node_id": "feature_db_validation_1",
  "status": "In Review",
  "issuing_state": "PAN",
  "validation_type": "not_enabled",
  "match_type": null,
  "screened_data": {
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1990-01-01",
    "selfie": "https://<media-host>/sessions/<session-id>/selfie.jpg?X-Amz-Signature=..."
  },
  "validations": [],
  "errors": [
    {
      "code": "invalid_screened_data",
      "message": "Database validation was skipped before calling the provider because the screened data has missing required fields: personal_number.",
      "missing_required_fields": ["personal_number"],
      "service_id": "pan_cedula_sib_plus"
    }
  ],
  "warnings": [
    {
      "feature": "DATABASE_VALIDATION",
      "risk": "COULD_NOT_PERFORM_DATABASE_VALIDATION",
      "additional_data": {
        "reason": "Database validation was skipped before any provider request because the screened data is incomplete or invalid.",
        "database_validation_errors": [
          {
            "code": "invalid_screened_data",
            "message": "Database validation was skipped before calling the provider because the screened data has missing required fields: personal_number.",
            "missing_required_fields": ["personal_number"],
            "service_id": "pan_cedula_sib_plus"
          }
        ],
        "missing_required_fields_by_service": { "pan_cedula_sib_plus": ["personal_number"] },
        "invalid_format_fields_by_service": {},
        "field_reasons_by_service": {}
      },
      "log_type": "warning",
      "short_description": "Could not perform database validation",
      "long_description": "The system couldn't perform the database validation, please fill the required fields for this country to automatically proceed with database validation.",
      "node_id": "feature_db_validation_1"
    }
  ]
}
```

Fill the missing field from the session detail page in the Console — saving it re-triggers the check automatically and clears the warning on success.

## Related

* [Database Validation overview](/core-technology/database-validation/overview) — how the API works end-to-end and supported registries.
* [Matching methods](/core-technology/database-validation/database-validation-matching-methods) — how 1×1 / 2×2 outcomes (`validation_type: one_by_one` / `two_by_two`) are derived.
* [Outcome codes](/core-technology/database-validation/database-validation-outcome-codes) — full per-result taxonomy with country-specific detail codes.
* [Supported countries & services](/core-technology/database-validation/database-validation-supported-countries) — every live registry, required fields and per-call price.
* [Database Validation warnings](/core-technology/database-validation/database-validation-warnings) — what we surface when a service can't run.
* [Data models — database validation](/reference/data-models#database-validation) — canonical field-by-field schema.


# Supported Countries & Services
Source: https://docs.didit.me/core-technology/database-validation/database-validation-supported-countries

Every Database Validation service: country, source registry, required fields, per-call price. Cheapest pay-per-call government-registry KYC from $0.05.

Didit's **Database Validation** verifies the identity data extracted from a user's ID document directly against the authoritative source for that country — the national civil registry, tax authority, electoral roll or biometric service that issued the document. Each call returns a per-field match plus the underlying record.

## Why teams pick Didit for Database Validation

* **Cheapest in the market.** Pay-per-call from **\$0.05** (Dominican Republic) up to **\$7.00** for the most expensive specialist sources, priced per service rather than per country. No monthly minimums, no platform fees, no per-seat charges. Check the exact rate in the [per-service pricing table](/getting-started/database-validation-pricing) before you budget a country.
* **Fastest to integrate.** [Sign up](https://business.didit.me/), grab an API key, and you can call `POST /v3/database-validation/` within minutes. No sales call, no procurement cycle, no proof-of-concept paperwork.
* **Authoritative sources, not aggregator scrapes.** RENAPER, Receita Federal (SERPRO), Tribunal Electoral, RENAPO, RENAP, RNP, RNPN, Junta Central Electoral, Registraduría Nacional, SEGIP, Servicio de Registro Civil, Tribunal Supremo de Elecciones, Dirección General de la Policía and more.
* **Biometric face-match included** for countries where the registry stores an official photo (Argentina via RENAPER, Panama via Tribunal Electoral SIB / SIB Plus). Confirm the person on the camera is the legitimate holder of the ID — not just that the number is real.
* **Per-call billing surfaced as it happens.** Every successful query becomes a line item; you see exactly what you spent, by service, in your monthly Database Validation report.

<Note>
  Customise the services per workflow in the [console](/console/workflows). Required and optional inputs are derived from the union of the services you enable. See [Database Validation Pricing](/getting-started/database-validation-pricing) for full per-country price ranges.
</Note>

## All live services

The table lists every service we run today, the source registry, the inputs each service requires, and the per-call price. Services tagged **`BIOMETRIC`** also face-match the user's selfie against the registry photo.

<DbValidationCountriesTable />

## How to call any of these

Every service is reachable through the same `POST /v3/database-validation/` endpoint. Pass the country in `issuing_state`, the service IDs you want to run in `services`, and the inputs each service requires. Omit `services` to run every configured service for that country.

```bash theme={null}
curl -X POST "https://verification.didit.me/v3/database-validation/" \
  -H "x-api-key: YOUR_API_KEY" \
  -F "issuing_state=BRA" \
  -F "tax_number=SAMPLE-TAX-12345" \
  -F "services=bra_cpf"
```

Per-country reference pages with full request/response examples live under **Database Validation** in the API Reference sidebar.

## Technical service metadata

This generated table is built from the service catalog plus captured workflow responses. It shows the valid document types, API inputs, workflow availability, consent requirement, and the exact `source_data` fields Didit has observed for each service.

<Note>
  If a service requires consent, collect explicit end-user consent before calling it and send `consent=true` in `POST /v3/database-validation/`. If a service requires onboarding, it appears in the console but stays disabled until Didit support enables it for your workspace.
</Note>

<DbValidationServicesMetadataTable />

<Note>
  We're constantly expanding coverage. If you need a registry that isn't on this list yet, [contact us](https://api.whatsapp.com/send/?phone=%2B34681310687) — most new integrations go live in 2–3 weeks.
</Note>

## Live registries by country

Direct links to every per-service reference page — request shape, response, outcome codes and per-call price.

* [🇦🇷 Argentina — DNI verification (RENAPER, biometric, \$0.20)](/api-reference/database-validation/argentina/renaper)
* [🇧🇴 Bolivia — Cédula verification (SEGIP, 90-95%, \$0.20)](/api-reference/database-validation/bolivia/cedula)
* [🇧🇷 Brazil — CPF status check (Receita Federal, \$0.20)](/api-reference/database-validation/brazil/cpf)
* [🇨🇱 Chile — RUT verification (Servicio de Registro Civil, \$0.20)](/api-reference/database-validation/chile/rut)
* [🇨🇴 Colombia — Cédula verification (Registraduría / ANI, 90-95%, \$0.20)](/api-reference/database-validation/colombia/cedula)
* [🇨🇷 Costa Rica — Cédula verification (Tribunal Supremo de Elecciones, 90-95%, \$0.20)](/api-reference/database-validation/costa-rica/cedula)
* [🇩🇴 Dominican Republic — Cédula verification (Junta Central Electoral, \$0.05 — cheapest in catalog)](/api-reference/database-validation/dominican-republic/cedula)
* [🇪🇨 Ecuador — Cédula verification (Registro Civil, \$0.20)](/api-reference/database-validation/ecuador/cedula)
* [🇸🇻 El Salvador — DUI verification (RNPN, 90-95%, \$0.20)](/api-reference/database-validation/el-salvador/dui)
* [🇪🇸 Spain — DNI / NIE verification (Dirección General de la Policía, \$1.26)](/api-reference/database-validation/spain/dni)
* [🇬🇹 Guatemala — DPI verification (SAT, 90-95%, \$0.20)](/api-reference/database-validation/guatemala/dpi)
* [🇭🇳 Honduras — DNI verification (CNE, 90-95%, \$0.20)](/api-reference/database-validation/honduras/dni)
* [🇲🇽 Mexico — CURP verification (RENAPO, \$0.20)](/api-reference/database-validation/mexico/curp)
* [🇲🇽 Mexico — INE credential validity verification (INE, \$0.10)](/api-reference/database-validation/mexico/ine-vigencia)
* [🇵🇦 Panama — Cédula via Tribunal Electoral SIB (biometric, \$0.75)](/api-reference/database-validation/panama/sib)
* [🇵🇦 Panama — Cédula via Tribunal Electoral SIB Plus (premium biometric, \$1.50)](/api-reference/database-validation/panama/sib-plus)
* [🇵🇾 Paraguay — Cédula verification (Registro del Estado Civil, 90-95%, \$0.20)](/api-reference/database-validation/paraguay/cedula)
* [🇵🇪 Peru — DNI verification (RENIEC, \$0.17)](/api-reference/database-validation/peru/dni)
* [🇺🇾 Uruguay — Cédula verification (Registro de Estado Civil, 90-95%, \$0.20)](/api-reference/database-validation/uruguay/cedula)
* [🇻🇪 Venezuela — Cédula verification (CNE, 90-95%, \$0.20)](/api-reference/database-validation/venezuela/cedula)
* [🇿🇦 South Africa — National ID verification (DHA, \$0.50)](/api-reference/database-validation/south-africa/national-id)
* [🇿🇦 South Africa — Driving License verification (NATIS, \$0.20)](/api-reference/database-validation/south-africa/drivers-license)
* [🇿🇦 South Africa — Vehicle Ownership (NATIS, \$0.20)](/api-reference/database-validation/south-africa/vehicle-ownership)
* [🇿🇦 South Africa — Bank Account Holder Verification (AHV, \$0.40)](/api-reference/database-validation/south-africa/bank-account-holder)
* [🇿🇦 South Africa: Company Registry Lookup (CIPC, USD 0.30)](/api-reference/database-validation/south-africa/company-registry)
* [🇿🇦 South Africa — Fraud Prevention Screening (SAFPS, \$0.40)](/api-reference/database-validation/south-africa/fraud-prevention)

## Global expansion

Beyond our directly-integrated LATAM and Spain registries, Didit also fronts a broad global identity network — 81 datasets across 26 countries (identity, residential, credit, document, government and demographic data) reachable through the same `POST /v3/database-validation/` endpoint.

Coverage spans Australia, Austria, Cambodia, Canada, China, Denmark, Finland, France, Germany, India, Indonesia, Italy, Kenya, Malaysia, Netherlands, New Zealand, Nigeria, Norway, Philippines, Singapore, South Africa, Sweden, Switzerland, Thailand, United Kingdom and United States. Pricing is surfaced per service in the catalog and billing exports.

Per-country pages with the full dataset list (and which datasets are workflow-compatible vs. standalone-API-only) live under **🌐 Database Validation** in the API Reference sidebar — see e.g. [Australia](/api-reference/database-validation/australia), [United Kingdom](/api-reference/database-validation/united-kingdom), [India](/api-reference/database-validation/india), [United States](/api-reference/database-validation/united-states).

## See also

* [Database Validation overview](/core-technology/database-validation/overview) — how the API works end-to-end, biometric face-match, pricing.
* [Matching Methods](/core-technology/database-validation/database-validation-matching-methods) — how 1×1 / 2×2 outcomes are derived.
* [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes) — full per-result taxonomy with country-specific detail codes.
* [Warnings](/core-technology/database-validation/database-validation-warnings) — what we surface when a service can't run.
* [Reports](/core-technology/database-validation/database-validation-report) — monthly per-service billing exports.
* [Database Validation Pricing](/getting-started/database-validation-pricing) — the full per-country price list.


# Database Validation Warnings
Source: https://docs.didit.me/core-technology/database-validation/database-validation-warnings

Reference for every Database Validation warning: COULD_NOT_PERFORM_DATABASE_VALIDATION, partial or no match, registry unreachable, and missing fields.

Didit's [Database Validation](/core-technology/database-validation/overview) feature verifies identity data against authoritative civil registries — RENAPER (Argentina), Receita Federal (Brazil), Tribunal Electoral (Panama, biometric), Junta Central Electoral (Dominican Republic), and more — billed per successful query with no monthly minimums.

When no service can run (required fields missing or malformed, registry unavailable), the document itself cannot be checked (it does not carry the identifier the configured services need — e.g. a passport without a national ID number), or the aggregate outcome is non-conclusive (partial match, no match), the feature emits a **warning** on the session. If the issuing state isn't enabled in the workflow at all, the step is skipped silently with no warning and no charge. This page documents every warning code, what triggers it, and how to configure the workflow response.

## Overview

Warnings are produced both in workflow sessions and by the standalone API (`POST /v3/database-validation/`). All five risks are tagged with feature `DATABASE_VALIDATION`, appear on the report under `database_validations[].warnings[]`, and follow the standard [warning object](/reference/data-models#warning-object) shape (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`).

There are no hard auto-decline triggers for Database Validation. The two match-outcome risks, the superseded-document risk and the not-applicable risk map to a **configurable action** (`DECLINE`, `REVIEW`, or `NO_ACTION`); `COULD_NOT_PERFORM_DATABASE_VALIDATION` is the one fixed behavior — it always routes the feature to **In Review**.

## Configurable risks

| Setting               | Risk code                                 | Behavior                                                                                                                                                                                                                                                                                                 |
| --------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| No Match Action       | `DATABASE_VALIDATION_NO_MATCH`            | `REVIEW` (workflow default) sets the feature to **In Review**; `DECLINE` declines; `NO_ACTION` records the warning without affecting status. The standalone API's `no_match_action` parameter defaults to `DECLINE` instead.                                                                             |
| Partial Match Action  | `DATABASE_VALIDATION_PARTIAL_MATCH`       | `NO_ACTION` (default) records the warning without affecting status; `REVIEW` sets the feature to **In Review**; `DECLINE` declines.                                                                                                                                                                      |
| No Match Action       | `DATABASE_VALIDATION_DOCUMENT_SUPERSEDED` | Shares the **No Match Action** setting — there is no separate knob. The registry contradicted what was submitted, so an organization that declines on no-match declines on a stale credential too.                                                                                                       |
| Not Applicable Action | `DATABASE_VALIDATION_NOT_APPLICABLE`      | `NO_ACTION` (default) records the warning without affecting status; `REVIEW` sets the feature to **In Review**; `DECLINE` declines. Fires when the document cannot be checked at all — it does not carry the identifier the configured services query by (e.g. a passport without a national ID number). |

The configured action also drives the warning's `log_type`: `DECLINE` → `error`, `REVIEW` → `warning`, `NO_ACTION` → `information`.

The match outcome itself is aggregated from the per-service `validation` entries (any full match → `full_match`; else any partial → `partial_match`; else `no_match`) — see [Matching methods](/core-technology/database-validation/database-validation-matching-methods) for the full decision logic that derives 1×1 / 2×2 outcomes.

## Warnings produced

| Tag                                       | Short description                                    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| ----------------------------------------- | ---------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `COULD_NOT_PERFORM_DATABASE_VALIDATION`   | Could not perform database validation                | No service returned a usable result (`match_type` stays `null`) — typically because required fields are missing or malformed, or the registry returned an error. `additional_data` carries the per-service skip summary (`reason`, `database_validation_errors`, `missing_required_fields_by_service`, `invalid_format_fields_by_service`, `field_reasons_by_service`); the standalone API uses `{ "validation_errors": [...] }` instead. **You are not charged** when this warning fires; the feature moves to **In Review** until the data is corrected. |
| `DATABASE_VALIDATION_NOT_APPLICABLE`      | Database validation not applicable for this document | The document provided does not carry the identifier the configured database service(s) require (`match_type` stays `null`) — for example, a Brazilian passport carries no CPF, so the CPF registry cannot be queried. This is expected for the document type and does not indicate a problem with the document. `additional_data` carries the per-service skip summary. **You are not charged** when this warning fires. Action configurable (default `NO_ACTION`).                                                                                        |
| `DATABASE_VALIDATION_PARTIAL_MATCH`       | Database validation partial match                    | The aggregate `match_type` is `partial_match` — some screened fields matched the registry but not all of them. Action configurable (default `NO_ACTION`).                                                                                                                                                                                                                                                                                                                                                                                                  |
| `DATABASE_VALIDATION_NO_MATCH`            | Database validation no match                         | The aggregate `match_type` is `no_match` — the registry could not confirm the screened identity. Action configurable (default `REVIEW` in workflows, `DECLINE` on the standalone API).                                                                                                                                                                                                                                                                                                                                                                     |
| `DATABASE_VALIDATION_DOCUMENT_SUPERSEDED` | Superseded document edition                          | A service returned `DOCUMENT_SUPERSEDED`: the registry confirmed the person, but the edition of the document presented is not the one on file — a newer edition has since been issued. Raised independently of `match_type`, which stays `full_match` because every personal field did match, so the finding would otherwise be invisible. `additional_data` names the services that reported it. Follows the **No Match Action** setting.                                                                                                                 |

<Note>
  `COULD_NOT_PERFORM_DATABASE_VALIDATION` covers two different situations, and the warning's `long_description` (and, for a per-service failure, `database_validation_errors[].message`) now states which one applied instead of a single generic sentence: the screened data was missing or malformed before any service could be queried, or a service was queried and did not return a usable result. In the second case, when the registry reported its own diagnostic detail for that attempt, that detail is included in the message so you don't have to contact support to learn why. The upstream service is never named in the response.
</Note>

<Note>
  When `COULD_NOT_PERFORM_DATABASE_VALIDATION` or `DATABASE_VALIDATION_NOT_APPLICABLE` fires in a workflow session, the check is automatically re-triggered once the missing data is filled in on the session detail page in the Console — saving the field re-runs the validation, and the warning is removed on success. This also works when the not-applicable action declined the session, so a declined session can be remediated by correcting the data. For `DATABASE_VALIDATION_NOT_APPLICABLE` the re-run helps when the document can carry the identifier but it wasn't read (for example, a residence card whose national ID number wasn't extracted); document types that never carry the identifier (for example, passports without a national ID number) keep the warning. **No charge** is applied for skipped services; you only pay when a service returns a billable result.
</Note>

## Example

```json theme={null}
{
  "warnings": [
    {
      "feature": "DATABASE_VALIDATION",
      "risk": "DATABASE_VALIDATION_NO_MATCH",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "Database validation no match",
      "long_description": "The system identified a no match in the database validation, requiring further investigation.",
      "node_id": "feature_db_validation_1"
    }
  ]
}
```

## Warning types

Each risk is assigned a severity based on your application's configuration. Severities fall into three categories:

<WarningTypes />

## Related

* [Database Validation overview](/core-technology/database-validation/overview) — how the feature works end-to-end and supported registries.
* [Database Validation report](/core-technology/database-validation/database-validation-report) — full response shape including per-service `validations[]`.
* [Matching methods](/core-technology/database-validation/database-validation-matching-methods) — how 1×1 / 2×2 outcomes (`validation_type: one_by_one` / `two_by_two`) are derived from per-service matches.
* [Outcome codes](/core-technology/database-validation/database-validation-outcome-codes) — full per-result taxonomy with country-specific detail codes.
* [Supported countries & services](/core-technology/database-validation/database-validation-supported-countries) — every live registry, required fields and per-call price.
* [Data models — database validation](/reference/data-models#database-validation) — canonical field-by-field schema.


# Database Validation Overview
Source: https://docs.didit.me/core-technology/database-validation/overview

Cheapest, fastest pay-per-call government-registry verification API. From $0.05/check, 60+ live countries, biometric face-match where registry holds photo.

Didit's **Database Validation** verifies a person's identity data against the authoritative source for that country — the national civil registry, tax authority, electoral roll, credit bureau or biometric registry that issued the document in the first place. Each check returns a per-field match (`identification_number`, `first_name`, `last_name`, `date_of_birth`, and address fields when the service uses them) plus an aggregated outcome and the underlying record details when available.

It is the strongest defence against synthetic-identity fraud: a stolen real DNI or CPF will fail the registry lookup, and a fabricated number won't be in the official database at all. Database Validation pairs with our biometric face-match in countries where the registry holds an official photo (Argentina via RENAPER, Panama via Tribunal Electoral SIB / SIB Plus) so you can confirm not just that a number is real, but that the **person standing in front of the camera owns it**.

<AgentPromptAccordion title="Database Validation Integration Prompt" />

## Why Didit

* **Cheapest pay-per-call pricing.** From **\$0.05** per check (Dominican Republic) up to **\$7.00** for the most expensive specialist sources. The price is set per service, not per country — a registry that charges a high wholesale rate is priced accordingly (Kenya National ID is **\$3.15**). Always read the rate for the exact service you plan to call from the [per-service pricing table](/getting-started/database-validation-pricing). No monthly minimums, no platform fees, no per-seat billing — only successful queries are charged.
* **Fastest to integrate.** [Sign up](https://business.didit.me/), grab an API key from the console, and you can call `POST /v3/database-validation/` within minutes. No sales call, no procurement cycle, no proof-of-concept paperwork — Didit is fully self-service.
* **Direct hits to the authoritative source.** RENAPER, Receita Federal (SERPRO), Tribunal Electoral, RENAPO, RENAP, RNP, RNPN, Junta Central Electoral, Registraduría Nacional, SEGIP, Servicio de Registro Civil, Tribunal Supremo de Elecciones, Dirección General de la Policía — not aggregator scrapes.
* **Biometric face-match where the registry has an official photo on file.** Higher-than-OCR confidence with no extra integration work.
* **Production-ready latency.** p95 typically under 1.5 s end-to-end, 99.9% quarterly availability.

The Academy lesson on reading a verification result reaches database validation at 11:05 and shows full, partial, and no-match outcomes.

<VideoEmbed title="Database validation: full, partial and no match — Didit Academy" />

## Global coverage

Hover any highlighted country to see every Database Validation service we run there, the data domain (Identity, Financial, Biometric, Address, Telecom, …) and the per-call price. Live countries are production-ready today; the rest are wired in on demand once a customer asks.

<CoverageWorldMap />

<Tip>
  **Don't see your country?** Reach out — our catalog tracks 60+ countries with hundreds of services that we activate on demand once a customer needs them. New integrations typically go live in 2–3 weeks.
</Tip>

## How a Database Validation runs

A Database Validation never fires speculatively. It only runs when **all** of the following are true:

1. The session resolved a country to query — from the `issuing_state` of an [ID Verification](/core-technology/id-verification/overview), or, when the workflow has no ID Verification step, from the single country the Database Validation step is configured for.
2. That country has at least one Database Validation service enabled in the workflow.
3. The steps in front of the Database Validation step supplied **every required field** the chosen service needs.

If a service is enabled but the required fields never arrived (e.g. CPF wasn't extractable from a smudged Brazilian RG), the service is skipped, **you are not charged**, and a warning is raised on the session: `DATABASE_VALIDATION_NOT_APPLICABLE` when the document simply does not carry the identifier that service queries by, `COULD_NOT_PERFORM_DATABASE_VALIDATION` when it should have been available and was not. Both are listed in the [warnings catalogue](/core-technology/database-validation/database-validation-warnings).

Someone on your team with review access to the session can then fill the missing field by hand from the session detail page in the Console, and saving it re-triggers the check automatically. That is a reviewer action, not something the end user can do — to let the **user** supply a field their document does not carry, ask for it in a Questionnaire (or a Document AI extraction, or a value you send when you create the session) and map it on the Database Validation step, as described below.

### Database Validation does not require ID Verification

A Database Validation step used to imply an ID Verification step in front of it, because an ID document's OCR was the only wired way to obtain the end user's data. That is no longer the case: **each required field declares which steps can supply it**, and a service becomes available as soon as your workflow contains a step that supplies every field it needs.

| Input source       | Supplies                                                                                                                                                                             |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| ID Verification    | Names, date of birth, address, document/personal number, and the country-specific identifiers printed on an ID (tax number, national ID, passport number, driving licence number, …) |
| NFC                | The chip-read subset of the above, at higher trust                                                                                                                                   |
| Liveness           | The live selfie, for facial-biometric registry services                                                                                                                              |
| Phone Verification | The verified phone number                                                                                                                                                            |
| Email Verification | The verified email address                                                                                                                                                           |
| Proof of Address   | The verified residential address and its components                                                                                                                                  |
| Document AI        | Any field you map to one of your extraction field keys                                                                                                                               |
| Questionnaire      | Any field you map to one of your questions                                                                                                                                           |
| API input          | Anything, on the standalone API — the caller supplies the values directly                                                                                                            |

This means a **facial-biometric service can run from a Liveness step alone**, with no ID document anywhere in the workflow, and a service keyed on a tax number, phone number or email can be satisfied from a questionnaire answer, a Phone/Email Verification step, or a Document AI extraction.

Two rules keep this safe:

* **A workflow with no ID Verification must configure exactly one country** on the Database Validation step. Without an `issuing_state` from a document, that is the only unambiguous signal for which national registry to query, so a multi-country configuration with no ID Verification runs nothing rather than guessing.
* **The required-field check is unchanged.** A service whose fields are not all present at run time is skipped before any provider is queried, so you are never billed for a database that was never asked.

#### Mapping Document AI and questionnaire fields

Document AI extraction fields and questionnaire questions use *your* key names, not Didit's. A key that exactly matches a Database Validation input name (`tax_number`, `date_of_birth`, `phone`, …) is mapped automatically and needs no configuration. For anything else, the workflow editor shows a picker on the Database Validation step for the fields that are still unfilled, where you point each one at the Document AI field key or questionnaire answer that supplies it.

In the Console, a service your workflow cannot yet run is shown disabled with the reason — which fields are missing and which step would provide them — and the editor offers to add that step for you. Adding it lights up every service it unblocks immediately.

<Tip>
  **Worked example — an identifier the document does not carry.** Nigeria's National ID service queries by the 11-digit NIN, which is frequently not printed on the documents people upload, so relying on the ID document alone leaves the check skipped as not applicable for a large share of users. Put a **Questionnaire** step in front of the Database Validation step asking for the NIN, then map `national_id` to that question on the Database Validation step. The same mapping is what makes an identifier that is never on a document at all — a bank verification number, a company registration number — usable inside a workflow.
</Tip>

For address-based services, Didit splits the ID document's single `address` into structured address elements automatically:

| Didit field         | Meaning                                               |
| ------------------- | ----------------------------------------------------- |
| `address_element_1` | Street address, including number and street type      |
| `address_element_2` | Optional unit, building, floor, or extra address line |
| `address_element_3` | Suburb, district, locality, or neighborhood           |
| `address_element_4` | City, town, state, province, or region                |
| `address_element_5` | Postcode or postal code                               |

When calling the standalone API, you can send either a single `address` or these structured fields directly. Structured fields win when both are present. Services that require address search need `address_element_1` plus at least one other address element; if Didit cannot derive those from the ID document or Proof of Address in the workflow, the service is skipped and not billed.

If the resolved country is not enabled at all, the step is skipped silently with no warning and no charge.

<Frame>
  <img alt="Didit database validation flow checking user data against government identity registries" />
</Frame>

## The match outcome

Each enabled service returns a per-field validation:

| Field                   | Outcomes                                    |
| ----------------------- | ------------------------------------------- |
| `identification_number` | `full_match` · `partial_match` · `no_match` |
| `first_name`            | `full_match` · `partial_match` · `no_match` |
| `last_name`             | `full_match` · `partial_match` · `no_match` |
| `date_of_birth`         | `full_match` · `no_match`                   |
| `address`               | `full_match` · `partial_match` · `no_match` |

The aggregated `match_type` rolls up to:

* **`full_match`** — every requested field agrees with at least one source.
* **`partial_match`** — some agreement; route to a review queue per your workflow rules.
* **`no_match`** — no source confirmed the data; usually decline.

## How matching is derived (1×1 / 2×2)

We do not ask you to pre-pick "1×1" or "2×2" anymore — those are derived from how many distinct services full-matched the input data:

* **1×1 outcome** — one service returned a full match (a single authoritative source confirmed the data).
* **2×2 outcome** — two or more services returned a full match (independent corroboration; the highest confidence we can express).

A workflow can enable any number of services per country; you are billed per service that actually returned a result. Services whose required fields couldn't be extracted are skipped with no charge.

➡️ See **[Matching Methods](./database-validation-matching-methods)** for the full decision logic and how it interacts with `partialMatchAction` / `noMatchAction`.

## Biometric Database Validation

Some countries' civil registries publish a biometric template (a portrait or a fingerprint). When that's available, we pair the registry lookup with a **biometric face-match** against the user's selfie:

* **Argentina (`arg_renaper`)** — biometric face-match against the official RENAPER photo on file. 100% population coverage; every Argentine citizen with a DNI is in the database.
* **Panama (`pan_cedula_sib`, `pan_cedula_sib_plus`)** — biometric face-match against the Tribunal Electoral SIB service. SIB Plus is the elevated-tier variant with stronger biometric thresholds and richer match metadata.

For these services the `selfie` field is **required**. Inside a session flow we re-use the liveness selfie (highest quality) and fall back to the document portrait. Outside a session, when calling the standalone API (`POST /v3/database-validation/`, Mode B above), you supply the JPEG/PNG yourself.

## Global identity enrichment

`glb_identity_enrichment` is a **global, standalone-only** Database Validation service. From an email and/or phone number it resolves associated persons (names, dates of birth, addresses, phones, emails and national IDs) and returns a name-match score, mapped to the standard [outcome codes](/core-technology/database-validation/database-validation-outcome-codes) `MATCH` / `PARTIAL_MATCH` / `NO_MATCH` / `DOCUMENT_NOT_FOUND` (with the corresponding `match_type` of `full_match` / `partial_match` / `no_match`).

Because it is a global (`GLB`) service keyed on email/phone rather than a document's issuing country, it is **not available in the workflow builder**. Call it directly through the standalone API with `issuing_state` set to `GLB`:

```json theme={null}
POST /v3/database-validation/
{
  "issuing_state": "GLB",
  "services": ["glb_identity_enrichment"],
  "email": "john.doe@example.com",
  "phone": "+14155552671"
}
```

It is billed at **\$0.20 per request** (charged only when the provider returns a result).

## Configuration

Database Validation is configured per-workflow from the Console. For each country you select the specific services you want to run; required and optional input fields are derived from the union of those services. The action taken on `partial_match` and `no_match` outcomes is configured separately and can be `approve`, `review`, or `decline`.

<Frame>
  <img alt="Didit database validation console settings selecting per-country registry services and outcome rules" />
</Frame>

## Pricing — pay only for what you use

Database Validation is billed **per successful query, per service**, at the rate published for that service. Rates run from **\$0.05** per check (Dominican Republic via Junta Central Electoral) up to **\$7.00** for the most expensive specialist sources. Many government registry lookups sit in the **USD 0.20 to USD 0.30** band, but a good number cost considerably more because the source itself charges more — Kenya National ID (`ken_national_id`) is **\$3.15** per successful query. Price a country from its own row in the [pricing table](/getting-started/database-validation-pricing), never from a range. There are no monthly minimums, commitments, or platform fees.

You only pay when a service returns a result. Services that skip because of missing input data are not billed, and neither is a service whose source call itself fails - a registry error or an unreachable registry (`REGISTRY_ERROR` / `REGISTRY_UNAVAILABLE`) means the query was never answered, so it's not a chargeable result.

<Warning>
  The **500 free checks per month** described on the [pricing page](/getting-started/pricing) apply to ID Verification, Passive Liveness, Face Match 1:1 and Device & IP Analysis only. Database Validation is **not** part of that free tier: every successful registry query is charged from the first one, whether it runs inside a workflow or through the standalone `POST /v3/database-validation/` API.
</Warning>

➡️ [Database Validation Pricing](/getting-started/database-validation-pricing) · [Sign up and get an API key](https://business.didit.me/)

## All services

<DatabaseValidationServicesTable />

## Continue reading

* [Matching Methods](./database-validation-matching-methods) — how 1×1 / 2×2 outcomes are derived and how to react to them.
* [Outcome Codes](./database-validation-outcome-codes) — the full list of provider response codes (deceased, minor, document not found, biometric mismatch, …) and how they map to session decisions.
* [Warnings](./database-validation-warnings) — what we surface when a service can't run due to missing data.
* [Reports](./database-validation-report) — monthly per-service billing exports with country, service ID, usage, unit price and total cost.
* [Supported Countries](./database-validation-supported-countries) — a static table view of every country we cover today.


# Document AI Overview
Source: https://docs.didit.me/core-technology/document-ai/overview

Collect up to 3 custom documents and extract the exact fields you define with AI, then cross-check them against other steps and your own rules.

Document AI lets you collect documents that don't fit a fixed template — proof of funds, payslips, source-of-wealth letters, tax statements, and anything else — and extract exactly the fields **you** define. You configure each document's on-screen title and description (automatically translated into every verification language) and the list of data points to read. Didit's AI extracts those fields, optionally cross-references them against other verification steps, and applies your rules to produce a status.

<AgentPromptAccordion title="Document AI Integration Prompt" />

<Note>
  Already have the document on your server? Call the [Document AI API](/standalone-apis/document-ai) directly: send the file plus your field definitions in one `POST /v3/document-ai/` request and get the extracted fields, name match, and status back synchronously, with no hosted flow. \$0.20 per document.
</Note>

## How it works

<Steps>
  <Step title="Configure documents and fields" icon="sliders">
    In the workflow builder you define up to **3 documents**. For each document you set:

    | Setting                 | Description                                                                                                                                                                                                                                                                                                                                                                                              |
    | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Title & description** | Shown to the user on the upload screen. Entered once and **auto-translated** into every verification language.                                                                                                                                                                                                                                                                                           |
    | **Fields to extract**   | A list of typed fields — each with a name, an extraction instruction for the AI, a type (`text`, `number`, `date`), a required flag, and an optional **full name** marker.                                                                                                                                                                                                                               |
    | **Name field**          | Optionally mark one text field per document as the name to match. On a person (KYC) workflow it is the **full name**, compared against the verified identity; on a business (KYB) workflow it is the **company name**, compared against the verified company. `document_ai_name_mismatch_action` decides what happens on a mismatch. Optional — leave it unset to skip the name check for that document. |

    Start from a [template](#starter-templates) or build from scratch.
  </Step>

  <Step title="The user uploads documents" icon="cloud-arrow-up">
    The user uploads one file per configured document (PDF or image). Each upload is processed independently; the step completes once every required document has been provided.
  </Step>

  <Step title="AI extraction" icon="wand-magic-sparkles">
    Didit renders each document and runs a vision-language model with a schema built from your field definitions. Extracted values are returned typed (numbers as numbers, dates as `YYYY-MM-DD`) and stored per document. PDF/EXIF forensics run to detect manipulation.
  </Step>

  <Step title="Cross-reference & rules" icon="shield-check">
    Extracted fields can be cross-checked against other steps — for example, the document holder name against the verified ID, or any field against questionnaire answers — and against your **basic rules** and **custom status rules**. The resulting per-document statuses combine into the feature status.
  </Step>
</Steps>

## Starter templates

When you add a Document AI node you can start from a ready-made template that pre-fills the title, description, and typed fields. Customize anything afterward.

| Template                      | Typical fields                                        |
| ----------------------------- | ----------------------------------------------------- |
| **Proof of Funds**            | Account holder, balance, currency, statement date     |
| **Proof of Income (payslip)** | Employer, employee name, gross/net salary, pay period |
| **Source of Wealth**          | Source type, amount, date, institution                |
| **Tax Document**              | Taxpayer name, tax year, declared income, tax ID      |

## Cross-referencing other steps

Document AI fields are addressable as `document_ai.<field_key>` and can be compared against fields from other completed steps using a custom status rule with `value_type: "field"`. For example:

* `document_ai.account_holder` **equals** `kyc.full_name` — the document holder matches the verified identity.
* `document_ai.balance` **greater\_than** `50000` — flag high balances for review.

Matching rules fold into the decision using the platform precedence **Declined > In Review > Approved**, so a rule can raise severity but never override a stricter risk-driven status. See [Rules & warnings](/core-technology/document-ai/warnings-document-ai).

## Document requirements

| Requirement            | Detail                                                                     |
| ---------------------- | -------------------------------------------------------------------------- |
| **Documents per step** | Up to 3, each configured independently                                     |
| **Supported formats**  | PDF, JPG, JPEG, PNG, TIFF, WebP                                            |
| **Pages**              | Multi-page PDFs supported                                                  |
| **Quality**            | Original document or high-quality scan; no digital editing or manipulation |

<Note>
  Document AI performs unstructured-text reading, which introduces a few seconds of latency per document. Webhooks fire only when the entire workflow step completes — do not poll the decision endpoint faster than every 5 s during this window.
</Note>


# Document AI report
Source: https://docs.didit.me/core-technology/document-ai/report-document-ai

Parse Document AI results: the upload endpoint, per-document extracted fields keyed by your configuration, status, and where the feature appears in the decision.

## Overview

Document AI accepts up to 3 documents per step (PDF or image — PDF, JPG, JPEG, PNG, TIFF, WebP). Each document is classified by its configured `document_key`, read by a vision-language model using a schema built from your field definitions, and run through PDF/EXIF forensics. For every document it stores:

* The **extracted fields** — a map keyed by your configured field `key`, with values typed as you declared them (`text` → string, `number` → number, `date` → `YYYY-MM-DD`). Fields that could not be read are `null`.
* **Detected QR codes and barcodes** - decoded payloads and pixel coordinates for every rendered page. A QR code that can be located but not decoded is still returned with `parsed_payload: null`.
* The **document status** — `Approved`, `In Review`, `Declined`, or `Not Finished`.
* **Document metadata** — file forensics including any overlay/manipulation evidence.
* **Cross-check results** — the outcome of name matching against the verified identity and of any custom field cross-references.

## Uploading documents

Documents are uploaded one at a time to the Document AI endpoint. In a hosted session or SDK flow this is handled for you; the contract is:

```text theme={null}
POST https://verification.didit.me/v3/document-ai/documents/
multipart/form-data — Session-Token: <session token>
```

| Field          | Required | Description                                            |
| -------------- | -------- | ------------------------------------------------------ |
| `document_key` | yes      | The configured document this file fulfills             |
| `document`     | yes      | The file to upload                                     |
| `locale`       | no       | Locale used to resolve the on-screen title/description |

The response advances the flow:

```json theme={null}
{
  "valid": true,
  "next_step": "DOCUMENT_AI",
  "document_ai_status": "In Progress",
  "uploaded_document_keys": ["proof_of_funds"],
  "required_document_keys": ["proof_of_funds", "payslip"]
}
```

The step completes (`next_step` moves past `DOCUMENT_AI`) once every entry in `required_document_keys` appears in `uploaded_document_keys` and no document is left unfinished.

## Where it appears in API responses

`GET /v3/session/{sessionId}/decision/` surfaces Document AI in two places, for both User Verification (KYC) and Business Verification (KYB) sessions — the `document_ai_documents[]` array and PDF report are identical regardless of `session_kind`:

* **`features[]`** — a summary entry per Document AI node, used to enumerate which features ran:

  ```json theme={null}
  { "features": [ { "feature": "DOCUMENT_AI", "node_id": "feature_document_ai_1" } ] }
  ```

* **`document_ai_documents[]`** — the full result, one group per Document AI node. Each group carries the node's combined `status`, the list of uploaded `items`, and any `warnings`. Every uploaded document is an item with the fields you configured (under `extracted_data`), detected codes (under `detected_codes`), its own `status`, the field definitions, forensic `document_metadata`, and `cross_check_result`.

Each node's per-document statuses combine into the node status using the precedence **Declined > In Review > Approved**.

## Decision example

For a **Proof of Funds** document configured with `account_holder` (text), `balance` (number), `currency` (text), and `statement_date` (date):

```json theme={null}
{
  "document_ai_documents": [
    {
      "node_id": "feature_document_ai_1",
      "status": "Approved",
      "items": [
        {
          "uuid": "5c1f0a2e-9b3d-4c7a-8f21-0a4e8e7d6c12",
          "document_key": "proof_of_funds",
          "status": "Approved",
          "original_filename": "statement.pdf",
          "extracted_data": {
            "account_holder": "Sophia Martinez",
            "balance": 18450.75,
            "currency": "EUR",
            "statement_date": "2026-05-31"
          },
          "detected_codes": [
            {
              "type": "QR_CODE",
              "page_number": 2,
              "position": [[124, 86], [306, 86], [306, 268], [124, 268]],
              "x": 124,
              "y": 86,
              "width": 182,
              "height": 182,
              "page_width": 1190,
              "page_height": 1684,
              "raw_payload": "SU5WLTIwMjYtMDA0Mg==",
              "parsed_payload": "INV-2026-0042"
            }
          ],
          "fields": [
            { "key": "account_holder", "name": "Account holder", "type": "text", "required": true },
            { "key": "balance", "name": "Balance", "type": "number", "required": false },
            { "key": "currency", "name": "Currency", "type": "text", "required": false },
            { "key": "statement_date", "name": "Statement date", "type": "date", "required": false }
          ],
          "document_metadata": { "is_tampered": false },
          "cross_check_result": null,
          "created_at": "2026-05-31T10:12:00Z"
        }
      ],
      "warnings": []
    }
  ]
}
```

`page_number` is 1-based. `position` contains the detected polygon, while `x`, `y`, `width`, and `height` provide its bounding box. All coordinates use the rendered page's pixel space, whose dimensions are `page_width` and `page_height`. `detected_codes` is an empty array when no supported code is found. Treat an item with `parsed_payload: null` as presence and location only, not as a decoded value.

Because every field is addressable as `document_ai.<field_key>`, you can drive branching and [custom status rules](/core-technology/document-ai/warnings-document-ai) directly from the `extracted_data` values — including cross-references against other steps such as `kyc.full_name` or questionnaire answers.


# Document AI rules & warnings
Source: https://docs.didit.me/core-technology/document-ai/warnings-document-ai

Document AI basic rules and custom status rules: unreadable documents, missing required fields, tampering, name mismatch, and field-level cross-references.

## Overview

Document AI produces a status for each uploaded document from two layers of rules, and the per-document statuses combine into the feature status using the precedence **Declined > In Review > Approved**.

1. **Basic rules** — built-in checks, each mapped to a configurable action: `DECLINE`, `REVIEW`, or `NO_ACTION`.
2. **Custom status rules** — your own conditions on any extracted field, including cross-references against other steps.

## Basic rules

Each rule below is detected automatically during extraction and forensic analysis. Configure the action for each in the Document AI feature's **Rules** tab.

| Rule                        | Config field                                 | Triggers when                                                                                                                                                                                                |
| --------------------------- | -------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Document unreadable**     | `document_ai_unreadable_document_action`     | The document can't be read or no data can be extracted                                                                                                                                                       |
| **Missing required fields** | `document_ai_missing_required_fields_action` | A field marked **required** can't be extracted                                                                                                                                                               |
| **Document tampering**      | `document_ai_document_tampering_action`      | Forensics detect signs of manipulation                                                                                                                                                                       |
| **Name mismatch**           | `document_ai_name_mismatch_action`           | The name on the document doesn't match the verified subject — the holder's identity on a person (KYC) workflow, or the company on a business (KYB) workflow (below `document_ai_name_match_score_threshold`) |
| **Unsupported file**        | `document_ai_unsupported_file_action`        | The uploaded file type is not supported                                                                                                                                                                      |
| **Exceeded attempts**       | `document_ai_max_attempts_exceeded_action`   | The user exceeds `document_ai_max_retry_attempts`                                                                                                                                                            |

The **name mismatch** check compares the document's marked name field against the verified subject using a 0–100 score: on a person (KYC) workflow against the verified ID (and the expected details supplied at session creation), and on a business (KYB) workflow against the verified company (the registry-matched company, or the expected company name). Set the cut-off with `document_ai_name_match_score_threshold`.

## Custom status rules

Custom status rules let you set a status (`Approved`, `In Review`, `Declined`, or `No Action`) when a condition on an extracted field is met. Each rule is:

```json theme={null}
{
  "field": "document_ai.balance",
  "operator": "greater_than",
  "value": 50000,
  "status": "In Review"
}
```

To **cross-reference another step**, set `value_type: "field"` and point `value` at another field path:

```json theme={null}
{
  "field": "document_ai.account_holder",
  "operator": "fuzzy_match",
  "value": "kyc.full_name",
  "value_type": "field",
  "score": 80,
  "status": "Declined"
}
```

Every matching rule contributes its status, and the strictest of those plus the base status wins (Declined > In Review > Approved). A rule can therefore raise severity but never pull a risk-driven `Declined`/`In Review` back up. `No Action` rules are recorded but leave the status unchanged.

<Note>
  Extracted fields are addressable as `document_ai.<field_key>` using the `key` you configured for each field. Number and date fields support comparison operators (`greater_than`, `less_than`, date ranges); text fields support equality, `contains`, and `fuzzy_match`.
</Note>


# Email Verification Overview
Source: https://docs.didit.me/core-technology/email-verification/overview

Verify emails with OTP and risk assessment. Detect breached, disposable, and undeliverable addresses. Pay-per-call $0.03, no monthly minimums.

Didit's Email Verification provides a reliable method to verify user email addresses through one-time passcodes (OTP) and advanced risk assessment. This feature helps ensure valid, reachable contact information while protecting against high-risk and compromised emails.

<AgentPromptAccordion title="Email Verification Integration Prompt" />

The Academy lesson on reading a verification result reaches the email verification check at 8:34.

<VideoEmbed title="Email verification — Didit Academy" />

<Frame>
  <img alt="Email verification flow diagram" />
</Frame>

## How it works

Our Email Verification solution combines OTP verification with intelligence signals such as breach exposure, deliverability, and provider reputation.

<Steps>
  <Step title="Email Collection" icon="envelope">
    The system securely collects:

    | Input                  | Description                                                                                                                                                   |
    | ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Email Address**      | If not provided during session creation, the user enters their email address. If provided during session creation, the user must verify the pre-filled email. |
    | **Preferred Language** | Used for localized communications when applicable.                                                                                                            |
  </Step>

  <Step title="OTP Generation & Delivery" icon="key">
    Our verification system:

    * Generates a secure, time-limited one-time passcode
    * Delivers the code via email to the provided address
    * Implements deliverability best practices to maximize inbox placement
    * Provides resend flows with safeguards to prevent abuse
  </Step>

  <Step title="Code Validation" icon="circle-check">
    The user completes verification by:

    * Entering the received code into the verification interface
    * Submitting within the configured timeframe (5 minutes)
    * Requesting a new code if needed (with appropriate rate limiting)
  </Step>

  <Step title="Risk Assessment" icon="shield-halved">
    Our system performs advanced checks:

    | Check                             | Description                                                               |
    | --------------------------------- | ------------------------------------------------------------------------- |
    | **Breach Exposure**               | Looks up the email across known data breaches and lists exposed services. |
    | **Disposable Provider Detection** | Flags emails from temporary/disposable providers.                         |
    | **Deliverability Checks**         | Detects undeliverable or syntactically invalid addresses.                 |
    | **Reputation Signals**            | Identifies potentially high-risk email patterns.                          |
    | **Duplicate Use**                 | Cross-references with historical verification data.                       |
  </Step>

  <Step title="Result Delivery" icon="paper-plane">
    Access verification results through multiple channels:

    | Channel       | Description                                                   |
    | ------------- | ------------------------------------------------------------- |
    | **Dashboard** | Real-time dashboard updates.                                  |
    | **Webhooks**  | Webhook notifications.                                        |
    | **API**       | RESTful API responses.                                        |
    | **Reports**   | Comprehensive reports with detailed verification information. |
  </Step>
</Steps>

## Verification Features

Our Email Verification service offers several key features to enhance your verification process:

#### OTP Verification

* **Secure Code Generation**: Random, time-bound one-time passcodes
* **Email Delivery**: Reliable and localized email delivery
* **Configurable Timeouts**: Set expiration times based on your security requirements
* **Retry Options**: Allow users to request new codes with appropriate limits

#### Email Analysis

* **Syntax Validation**: Ensure the email address follows RFC-compliant format
* **Provider Checks**: Identify disposable/temporary providers
* **Deliverability Insight**: Detect undeliverable addresses
* **Breach Intelligence**: Surface known breach records with details

#### Risk Assessment

* **Exposure Detection**: Identify if the email appears in known breaches
* **Disposable Detection**: Flag temporary or throwaway emails
* **Activity Monitoring**: Track suspicious patterns across attempts
* **Blocklist Checking**: Check against internal lists of previously misused emails


# Email Verification Report
Source: https://docs.didit.me/core-technology/email-verification/report-email-verification

Parse Email Verification responses: OTP lifecycle, breach exposure, disposable and undeliverable flags, cross-session matches, and risk warnings.

The Email Verification report captures the full outcome of an email OTP challenge: who the message was sent to, whether the address is disposable or undeliverable, whether it appears in known data breaches, how many attempts the user took, and any cross-session matches against your blocklist or other approved users.

This page documents the JSON shape returned by the decision endpoint so you can parse OTP outcomes, breach exposure, and risk flags for each verified address.

<Frame>
  <img alt="Didit email verification report showing OTP outcome, breach data and risk flags" />
</Frame>

## Overview

An email report is produced every time a workflow node runs the Email Verification feature. Each report represents one OTP challenge against one address and contains:

* The verified `email` address.
* Boolean risk flags (`is_breached`, `is_disposable`, `is_undeliverable`) and the supporting `breaches[]` array sourced from a breach-intelligence database.
* The count of OTP send attempts (`verification_attempts`) and the approval timestamp.
* A chronological `lifecycle[]` log of every send, retry and code-check attempt.
* A `matches[]` array surfacing the same address on other approved email verifications or your blocklist.
* A `warnings[]` array — risk events emitted during the verification (see [Email Verification warnings](/core-technology/email-verification/warnings-email-verification)).
* A `node_id` that identifies which workflow graph node produced the report (V3 sessions only).

In hosted workflow sessions the OTP challenge runs inside the Didit verification UI — you only read the result from the decision payload. For server-to-server OTP without a hosted flow, use the standalone Email API: [`POST /v3/email/send/`](/standalone-apis/email-send) delivers the code and [`POST /v3/email/check/`](/standalone-apis/email-check) validates the user's entry; finalized standalone verifications surface through the same report shape.

Hosted sessions cap the user at **2 wrong code entries** (`email_max_check_attempts`) and **2 OTP sends — the initial send plus one resend** (`email_max_retries`) by default, tunable per workflow node. Exceeding either cap finalizes the step as `Declined` with `EMAIL_CODE_ATTEMPTS_EXCEEDED`.

## Where it appears in API responses

The decision endpoint (`GET /v3/session/{sessionId}/decision/`) returns email reports under the plural array key **`email_verifications`**. The array contains one entry per Email Verification node in the workflow graph — typically one, but step-up flows may produce several.

```json theme={null}
{
  "session_id": "11111111-1111-1111-1111-111111111111",
  "status": "Approved",
  "email_verifications": [
    { "node_id": "feature_email_1", "status": "Approved", "...": "..." }
  ]
}
```

A `null` value means no Email Verification step has run yet. Iterate the array (rather than reading `email_verifications[0]`) when your workflow can collect more than one email address.

## Schema

The canonical field-by-field schema lives on the [Data models](/reference/data-models#email-verification) page.

```typescript theme={null}
interface EmailVerification {
  node_id: string | null;
  status: "Not Finished" | "Approved" | "Declined" | "In Review" | "Expired";
  email: string;
  is_breached: boolean;
  breaches: Breach[];                // Up to the 5 most recent known breaches
  is_disposable: boolean;            // Disposable / throwaway provider
  is_undeliverable: boolean;         // Failed syntax / DNS (MX) validation or OTP delivery
  verification_attempts: number;     // OTP send attempts
  verified_at: string | null;        // ISO 8601, null until a valid code is entered
  lifecycle: EmailLifecycleEvent[];  // OTP send/retry/check timeline
  warnings: Warning[];               // Risk events (see Data models → Warning object)
  matches: EmailMatch[];             // Cross-session / blocklist matches
}

interface Breach {
  name: string;                      // Breached service name
  domain: string;                    // Affected domain
  breach_date: string;               // YYYY-MM-DD
  breach_emails_count: number;       // Total affected accounts
  description: string;               // HTML description of the breach
  logo_path: string;                 // Breached-service logo URL
  data_classes: string[];            // Exposed data categories (snake_case)
  is_verified: boolean;              // true when the breach is a verified incident
}
```

An undeliverable address — invalid syntax, a non-existent domain, missing MX records, or a failed OTP delivery — finalizes the step as **`Declined`** with the auto-decline warning `UNDELIVERABLE_EMAIL_DETECTED`. The only exception: when the user typed the address themselves (it was not pre-filled at session creation), an undeliverable send returns an inline error so they can retry with a different address instead of being declined immediately.

### Status values

| Status         | Meaning                                                                                                                               |
| -------------- | ------------------------------------------------------------------------------------------------------------------------------------- |
| `Not Finished` | The OTP send has been initiated but the verification has not been finalized yet.                                                      |
| `Approved`     | The user entered a valid OTP and no declining risk matched.                                                                           |
| `Declined`     | An auto-decline warning fired (blocklist, undeliverable address, attempts exceeded) or a risk action configured to `DECLINE` matched. |
| `In Review`    | A risk action configured to `REVIEW` routed the step to manual review.                                                                |
| `Expired`      | The 5-minute OTP window elapsed with no valid code — applies to verifications created via the standalone email API.                   |

### Lifecycle event types

`lifecycle[]` is sorted chronologically. Each event has `type`, `timestamp`, `details` and a billable `fee` (when applicable):

| Event type                              | Emitted when                                                            |
| --------------------------------------- | ----------------------------------------------------------------------- |
| `EMAIL_VERIFICATION_MESSAGE_SENT`       | First OTP send attempt — including sends that come back undeliverable.  |
| `EMAIL_VERIFICATION_RETRY_MESSAGE_SENT` | Subsequent OTP send after the user requested a resend.                  |
| `VALID_CODE_ENTERED`                    | The user submitted the correct OTP code.                                |
| `INVALID_CODE_ENTERED`                  | The user submitted a wrong or expired OTP code (counts toward the cap). |
| `EMAIL_VERIFICATION_APPROVED`           | Feature-level status was set to `Approved`.                             |
| `EMAIL_VERIFICATION_DECLINED`           | Feature-level status was set to `Declined`.                             |
| `EMAIL_VERIFICATION_IN_REVIEW`          | Feature-level status was set to `In Review`.                            |
| `EMAIL_VERIFICATION_EXPIRED`            | The OTP window elapsed without a valid code (standalone email API).     |

The `details` payload depends on the event family:

* **Send events** (`EMAIL_VERIFICATION_MESSAGE_SENT`, `EMAIL_VERIFICATION_RETRY_MESSAGE_SENT`) — `{ status, reason }`. `status` is `Success`, `Retry` or `Undeliverable`; `reason` is `null` unless the send failed (`email_can_not_be_delivered`, or `unknown` for unrecognized legacy values).
* **Check events** (`VALID_CODE_ENTERED`, `INVALID_CODE_ENTERED`) — `{ code_tried, status }` with `status` `Approved`, `Failed`, `Expired or Not Found` or `Declined`.
* **Final status events** — `null`, except `EMAIL_VERIFICATION_DECLINED` / `EMAIL_VERIFICATION_IN_REVIEW`, which carry `{ "reason": "<risk code>" }` (e.g. `UNDELIVERABLE_EMAIL_DETECTED`).

Sends with `status` `Success` or `Undeliverable` record the \$0.03 Email Verification fee; `Retry` sends, check events and status events always carry `fee: 0`.

### Cross-session matches

`matches[]` records the same address on **previously approved** email verifications in the same application — across KYC, KYB and standalone API sessions — plus blocklist hits configured in the [management-api lists](/management-api/lists/overview). Verifications sharing the current session's `vendor_data` are excluded (the same end-user does not match themselves), the array is capped at **5** entries, ordered oldest-first. When the address is on your blocklist but none of the matched sessions is blocklisted, a synthetic entry with `source: "list_entry"` (all session fields `null`) is prepended to the array.

```typescript theme={null}
interface EmailMatch {
  session_id: string | null;         // null when source = "list_entry"
  session_number: number | null;
  vendor_data: string | null;
  verification_date: string | null;  // ISO 8601, creation date of the matched session
  email: string;
  status: string | null;             // Status of the matched session
  is_blocklisted: boolean;
  api_service: string | null;        // Set when the matched session came from a standalone API
  source: "session" | "list_entry";  // "list_entry" = manual blocklist hit
}
```

## Examples

### Approved — clean OTP with one informational breach

```json theme={null}
{
  "node_id": "feature_email_1",
  "status": "Approved",
  "email": "alex.sample@example.com",
  "is_breached": true,
  "breaches": [
    {
      "name": "ExampleAir",
      "domain": "example-air.com",
      "breach_date": "2022-08-25",
      "breach_emails_count": 6083479,
      "description": "In August 2022, the airline ExampleAir suffered a data breach that exposed customers' personal information.",
      "logo_path": "https://<media-host>/logos/ExampleAir.png",
      "data_classes": [
        "dates_of_birth", "email_addresses", "genders", "names",
        "nationalities", "phone_numbers", "physical_addresses",
        "salutations", "spoken_languages"
      ],
      "is_verified": true
    }
  ],
  "is_disposable": false,
  "is_undeliverable": false,
  "verification_attempts": 1,
  "verified_at": "2025-09-15T17:36:19.963451Z",
  "lifecycle": [
    {
      "type": "EMAIL_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2025-09-15T17:35:50.000000+00:00",
      "details": { "status": "Success", "reason": null },
      "fee": 0.03
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2025-09-15T17:36:19.000000+00:00",
      "details": { "code_tried": "123456", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "EMAIL_VERIFICATION_APPROVED",
      "timestamp": "2025-09-15T17:36:19.963451+00:00",
      "details": null,
      "fee": 0
    }
  ],
  "warnings": [
    {
      "feature": "EMAIL",
      "risk": "BREACHED_EMAIL_DETECTED",
      "additional_data": null,
      "log_type": "information",
      "short_description": "Breached email detected",
      "long_description": "This email address was found in one or more known data breaches.",
      "node_id": "feature_email_1"
    }
  ],
  "matches": []
}
```

### Declined — undeliverable address

A pre-filled address that fails syntax or DNS (MX) validation — or whose OTP email cannot be delivered — finalizes immediately as `Declined`. No code-check events appear because no code ever reached the user.

```json theme={null}
{
  "node_id": "feature_email_1",
  "status": "Declined",
  "email": "user@nonexistent-domain.example",
  "is_breached": false,
  "breaches": [],
  "is_disposable": false,
  "is_undeliverable": true,
  "verification_attempts": 1,
  "verified_at": null,
  "lifecycle": [
    {
      "type": "EMAIL_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2025-09-15T18:00:00.000000+00:00",
      "details": { "status": "Undeliverable", "reason": "email_can_not_be_delivered" },
      "fee": 0.03
    },
    {
      "type": "EMAIL_VERIFICATION_DECLINED",
      "timestamp": "2025-09-15T18:00:01.500000+00:00",
      "details": { "reason": "UNDELIVERABLE_EMAIL_DETECTED" },
      "fee": 0
    }
  ],
  "warnings": [
    {
      "feature": "EMAIL",
      "risk": "UNDELIVERABLE_EMAIL_DETECTED",
      "additional_data": null,
      "log_type": "error",
      "short_description": "Undeliverable email detected",
      "long_description": "The system detected that the email is undeliverable, which is not allowed.",
      "node_id": "feature_email_1"
    }
  ],
  "matches": []
}
```

### Declined — blocklisted disposable mailbox

The user completed the OTP, but the address matched your email blocklist (auto-decline). The disposable flag is also raised — at `information` level here because `disposable_email_action` is left at its default `NO_ACTION`.

```json theme={null}
{
  "node_id": "feature_email_1",
  "status": "Declined",
  "email": "user@mailinator.com",
  "is_breached": false,
  "breaches": [],
  "is_disposable": true,
  "is_undeliverable": false,
  "verification_attempts": 1,
  "verified_at": "2025-09-15T18:05:42.201734Z",
  "lifecycle": [
    {
      "type": "EMAIL_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2025-09-15T18:05:01.000000+00:00",
      "details": { "status": "Success", "reason": null },
      "fee": 0.03
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2025-09-15T18:05:42.000000+00:00",
      "details": { "code_tried": "654321", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "EMAIL_VERIFICATION_DECLINED",
      "timestamp": "2025-09-15T18:05:42.201734+00:00",
      "details": { "reason": "EMAIL_IN_BLOCKLIST" },
      "fee": 0
    }
  ],
  "warnings": [
    {
      "feature": "EMAIL",
      "risk": "EMAIL_IN_BLOCKLIST",
      "additional_data": {
        "blocklisted_session_id": null,
        "blocklisted_session_number": null,
        "api_service": null
      },
      "log_type": "error",
      "short_description": "Email in blocklist",
      "long_description": "The system detected that the email is in the blocklist, which is not allowed.",
      "node_id": "feature_email_1"
    },
    {
      "feature": "EMAIL",
      "risk": "DISPOSABLE_EMAIL_DETECTED",
      "additional_data": null,
      "log_type": "information",
      "short_description": "Disposable email detected",
      "long_description": "The system detected that the email is disposable, which is not allowed.",
      "node_id": "feature_email_1"
    }
  ],
  "matches": [
    {
      "session_id": null,
      "session_number": null,
      "vendor_data": null,
      "verification_date": null,
      "email": "user@mailinator.com",
      "status": null,
      "is_blocklisted": true,
      "api_service": null,
      "source": "list_entry"
    }
  ]
}
```

## Related

* [Email Verification overview](/core-technology/email-verification/overview) — feature behavior and pricing.
* [Email Verification warnings](/core-technology/email-verification/warnings-email-verification) — every risk code, decline triggers and configurable actions.
* [Data models — email verification](/reference/data-models#email-verification) — canonical field-by-field schema.
* [Email API — Send OTP](/standalone-apis/email-send) and [Check OTP](/standalone-apis/email-check) — standalone server-to-server endpoints.
* [Management API — Lists](/management-api/lists/overview) — manage the email blocklist that feeds `matches[]` with `source: list_entry`.


# Email Verification Warnings
Source: https://docs.didit.me/core-technology/email-verification/warnings-email-verification

Reference for every Email Verification risk code: BREACHED_EMAIL_DETECTED, DISPOSABLE_EMAIL_DETECTED, UNDELIVERABLE_EMAIL_DETECTED, blocklist, and OTP caps.

The Email Verification feature emits **warnings** whenever a risk signal fires on the OTP flow or the address itself: a known data breach, a disposable provider, an undeliverable mailbox, an OTP attempt cap, or a hit against your blocklist or another approved verification. This page lists every code, what triggers it, and how to configure the workflow response.

## Overview

Warnings are tagged with feature `EMAIL`. They appear on the report under `email_verifications[].warnings[]` and follow the standard [warning object](/reference/data-models#warning-object) shape (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`). Each warning is also routed into the per-session log so it surfaces in the Business Console under the Email section.

Some warnings are **hard auto-decline** triggers — they always set the feature status to `Declined` and carry `log_type: "error"`. The others map to a **configurable action** (`DECLINE`, `REVIEW`, or the default `NO_ACTION`) defined per workflow node or per API call, so the same risk code may decline one workflow while only flagging another. The configured action also sets the severity: `DECLINE` → `error`, `REVIEW` → `warning`, `NO_ACTION` → `information`.

## Auto-decline conditions

The following warnings always decline the Email Verification step regardless of configuration:

* `EMAIL_CODE_ATTEMPTS_EXCEEDED` — the user exhausted the OTP budget: 2 wrong code entries (`email_max_check_attempts`) or 2 OTP sends — the initial send plus one resend (`email_max_retries`) — by default.
* `EMAIL_IN_BLOCKLIST` — the address is in a blocklist managed via the [Lists API](/management-api/lists/overview), or matched a previously approved email verification that was blocklisted.
* `UNDELIVERABLE_EMAIL_DETECTED` — the address cannot receive mail: invalid syntax, a non-existent domain, missing DNS (MX) records, or the OTP email could not be delivered. The step finalizes as `Declined` immediately — no code check ever runs. Exception: when the user typed the address themselves (it was not pre-filled at session creation), an undeliverable send returns an inline error so they can retry with a different address instead of being declined.

## Configurable risks

Each of the following risks maps to a setting (per workflow node, or per call on the standalone [check endpoint](/standalone-apis/email-check)) you can configure to `DECLINE`, `REVIEW`, or `NO_ACTION`:

| Setting                   | Risk code                   | Default behavior                                                                                    |
| ------------------------- | --------------------------- | --------------------------------------------------------------------------------------------------- |
| `breached_email_action`   | `BREACHED_EMAIL_DETECTED`   | `NO_ACTION` — surface breach details at `information` level without changing the status.            |
| `disposable_email_action` | `DISPOSABLE_EMAIL_DETECTED` | `NO_ACTION` — flag the throwaway provider at `information` level without changing the status.       |
| `duplicated_email_action` | `DUPLICATED_EMAIL`          | `NO_ACTION` — record the duplicate at `information` level. Skipped when the address is allowlisted. |

Duplicate detection only considers **previously approved** email verifications in the same application, grouped by `vendor_data` — verifications sharing the same `vendor_data` are treated as one end-user and excluded. Leave `vendor_data` empty and every session is treated as a distinct user. If the address is on your email allowlist, the duplicate action is skipped and `EMAIL_IN_ALLOWLIST` is emitted instead.

## Verification attempt limits

The Email Verification feature applies a hard cap on OTP attempts to prevent abuse:

* **Code-entry attempts** — `email_max_check_attempts`, default **2**: the second wrong (or expired) code finalizes the step.
* **Send attempts** — `email_max_retries`, default **2** sends in total (the initial send plus one resend): a further resend request finalizes the step.

Exceeding either cap raises `EMAIL_CODE_ATTEMPTS_EXCEEDED` and auto-declines. You can tune both caps per workflow node.

## Warnings produced

| Tag                            | Severity                                                 | Description                                                                                                                                                                                                                                                                                            |
| ------------------------------ | -------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `EMAIL_CODE_ATTEMPTS_EXCEEDED` | `error`                                                  | The user exceeded the code-entry or send cap. Auto-declines.                                                                                                                                                                                                                                           |
| `EMAIL_IN_BLOCKLIST`           | `error`                                                  | The address is present in a blocklist created via the [Lists API](/management-api/lists/overview), or matched a blocklisted approved verification. Auto-declines. `additional_data` carries `blocklisted_session_id`, `blocklisted_session_number` and `api_service` (all `null` for a pure list hit). |
| `EMAIL_IN_ALLOWLIST`           | `information`                                            | The address matched an allowlist created via the [Lists API](/management-api/lists/overview), so the duplicate-email action was skipped.                                                                                                                                                               |
| `BREACHED_EMAIL_DETECTED`      | Per `breached_email_action` (`information` by default)   | The address was found in one or more known data breaches. The `breaches[]` array on the report carries the breached service, date and data classes.                                                                                                                                                    |
| `DISPOSABLE_EMAIL_DETECTED`    | Per `disposable_email_action` (`information` by default) | The domain is a known disposable / throwaway provider often used to evade traceability.                                                                                                                                                                                                                |
| `UNDELIVERABLE_EMAIL_DETECTED` | `error`                                                  | The address cannot receive mail (invalid syntax, non-existent domain, missing MX records, or failed delivery). Auto-declines.                                                                                                                                                                          |
| `DUPLICATED_EMAIL`             | Per `duplicated_email_action` (`information` by default) | The address matches a previously approved email verification belonging to a different end-user (grouped by `vendor_data`). `additional_data` carries `duplicated_session_id`, `duplicated_session_number` and `api_service`.                                                                           |

At most one of `EMAIL_IN_BLOCKLIST`, `DUPLICATED_EMAIL` and `EMAIL_IN_ALLOWLIST` fires per attempt — blocklist takes precedence over duplicate, which takes precedence over allowlist.

## Cross-session matches

When an address is detected on previously approved email verifications or on your blocklist, those hits also appear under `email_verifications[].matches[]` (capped at 5 entries). Each match carries `session_id`, `session_number`, `vendor_data`, `verification_date`, `email`, `status`, `is_blocklisted`, `api_service`, and a `source` of `session` (another approved verification) or `list_entry` (a blocklist entry). If the current address is on your email allowlist, Didit keeps the match evidence but emits `EMAIL_IN_ALLOWLIST` instead of applying the duplicate-email action. See the [Email Verification report](/core-technology/email-verification/report-email-verification#cross-session-matches) for the full match schema.

## Example

```json theme={null}
{
  "warnings": [
    {
      "feature": "EMAIL",
      "risk": "EMAIL_IN_BLOCKLIST",
      "additional_data": {
        "blocklisted_session_id": null,
        "blocklisted_session_number": null,
        "api_service": null
      },
      "log_type": "error",
      "short_description": "Email in blocklist",
      "long_description": "The system detected that the email is in the blocklist, which is not allowed.",
      "node_id": "feature_email_1"
    },
    {
      "feature": "EMAIL",
      "risk": "DISPOSABLE_EMAIL_DETECTED",
      "additional_data": null,
      "log_type": "information",
      "short_description": "Disposable email detected",
      "long_description": "The system detected that the email is disposable, which is not allowed.",
      "node_id": "feature_email_1"
    }
  ]
}
```

## Warning types

Each risk is assigned a severity based on your application's configuration. Severities fall into three categories:

<WarningTypes />

## Related

* [Email Verification overview](/core-technology/email-verification/overview) — feature behavior and pricing.
* [Email Verification report](/core-technology/email-verification/report-email-verification) — full response shape including `lifecycle[]` and `matches[]`.
* [Data models — email verification](/reference/data-models#email-verification) — canonical field-by-field schema.
* [Management API — Lists](/management-api/lists/overview) — manage the email blocklist used by `EMAIL_IN_BLOCKLIST`.


# Face Match 1:1
Source: https://docs.didit.me/core-technology/face-match/overview

Compare live selfies against ID document photos with AI facial recognition. Pay-per-call $0.05, 500 free/month, sub-2-second response.

In the Academy lesson on reading a verification result, the 6:16 chapter covers the face match check inside a real session.

<VideoEmbed title="Face match — Didit Academy" />

Powered by cutting-edge AI, computer vision, and biometric technology, our solution ensures fast, accurate, and secure identity verification at scale. Designed to combat fraud, simplify compliance, and enhance user experience, Didit provides a robust and trustworthy platform that meets the highest industry standards.

<AgentPromptAccordion title="Face Match Integration Prompt" />

<Frame>
  <img alt="ID verification steps overview" />
</Frame>

## Retries & actionable feedback

In a Didit session, a face match that fails for a **fixable capture reason** (the selfie is too dark, blurry, off-center, or the similarity is borderline) does not immediately decline. The user is asked to **retry with guidance**, up to a configurable number of attempts — the same model used for [Liveness](/core-technology/liveness/overview).

* **Attempt budget** — `face_match_max_attempts` controls the total number of face-match submissions per session. Default **3** (one initial attempt plus two retries), configurable per workflow node (range 1–3).

* **Retry feedback** — while attempts remain, a retryable failure keeps the user on the step and returns `feedback_codes` (the Web and Mobile SDKs surface these as coaching messages automatically):

  ```json theme={null}
  {
    "detail": "Make sure your face matches your document photo, improve lighting and try again.",
    "error": "LOW_FACE_MATCH_SIMILARITY",
    "feedback_codes": ["LOW_FACE_MATCH_SIMILARITY"],
    "attempts_used": 1,
    "max_attempts": 3
  }
  ```

* **Exhaustion** — once the budget is exhausted the computed status is applied (`Declined` or `In Review`).

<Note>
  Retries apply to the **session flow** only. The standalone `POST /v3/face-match/` endpoint is stateless and single-shot — it returns the similarity score directly with no retry budget.
</Note>

## How It Works

<Steps>
  <Step title="Intelligent Capture" icon="camera">
    Effortlessly begin the verification process with our intuitive, AI-driven capture system.

    Users upload or photograph their ID documents with real-time assistance:

    | Feature                | Description                                                            |
    | ---------------------- | ---------------------------------------------------------------------- |
    | **Auto-detection**     | Identifies document type and issuing country automatically             |
    | **Real-time guidance** | Visual cues for optimal positioning, lighting, and focus               |
    | **Smart capture**      | Automatic capture when conditions are ideal — no manual retries needed |
    | **Broad support**      | Passports, driver's licenses, national ID cards, and residence permits |

    <Note>
      *Why it matters*: Our intelligent capture reduces user friction and ensures high-quality submissions on the first attempt, boosting conversion rates and trust.
    </Note>
  </Step>

  <Step title="Advanced Data Processing" icon="gears">
    Extract and validate identity data with unmatched precision.

    **Data Extraction** — State-of-the-art technology processes all key fields:

    | Capability           | Details                                                                              |
    | -------------------- | ------------------------------------------------------------------------------------ |
    | **Field extraction** | Full name, date of birth, document number, issue/expiry dates, nationality, and more |
    | **OCR**              | High-precision optical character recognition for text                                |
    | **MRZ parsing**      | Machine-Readable Zone parsing and barcode decoding                                   |

    **Data Validation**:

    * Cross-references data between visual zones, MRZ, and barcodes for consistency
    * Format and pattern matching to detect anomalies
    * Real-time queries against government databases (where permitted) for authoritative verification

    <Note>
      *Why it matters*: Comprehensive data processing ensures accuracy and eliminates errors, giving you confidence in every verification.
    </Note>
  </Step>

  <Step title="Advanced Analysis" icon="shield-check">
    Our AI-powered system performs comprehensive checks:

    * Document authenticity verification
    * Tamper detection and image integrity analysis
    * Security feature validation (holograms, watermarks, etc.)
    * Template matching against certified database

    **Document liveness detection** prevents fraud from:

    | Attack type           | Description                                         |
    | --------------------- | --------------------------------------------------- |
    | **Screen captures**   | Digital documents photographed from a screen        |
    | **Screen replay**     | Photos of documents displayed on screens            |
    | **Printed copies**    | Physical reproductions of original documents        |
    | **Altered portraits** | Manipulated documents with swapped or edited photos |
  </Step>

  <Step title="Seamless Results & Integration" icon="plug">
    Get actionable insights instantly with flexible delivery options.

    **Real-Time Results**:

    | Channel       | Description                                           |
    | ------------- | ----------------------------------------------------- |
    | **Dashboard** | Immediate updates via an intuitive dashboard          |
    | **Webhooks**  | Instant webhook notifications for automated workflows |
    | **REST API**  | Seamless integration into your existing systems       |

    **Comprehensive Reporting**:

    * Detailed PDF reports with verification outcomes and evidence
    * Audit trails for compliance and record-keeping
    * Customizable options to align with your operational needs

    <Note>
      *Why it matters*: Fast, accessible results empower your team to act quickly while maintaining a secure, auditable process.
    </Note>
  </Step>
</Steps>

***

## Document Requirements

For optimal verification success, documents must meet these standards:

#### General Requirements

* Government-issued and valid within its configured validity period
* Physically intact (no damage, scratches, or stains obscuring details)
* All critical information (full name, date of birth, MRZ, etc.) clearly legible
* Consistent data across all submitted documents

#### Image Requirements

* Original, real-time photo (no screenshots, scans, or digital copies)
* Supported formats: JPG, JPEG, PNG, PDF
* Maximum file size: 5MB
* Full-color image with all document corners visible
* Free from glare, shadows, digital editing, or manipulation
* Physical documents required (digital IDs supported only in select regions where officially recognized)

## Additional Settings by Country & Document Type

Configure fine-grained rules per country and document type directly from the console. These controls let you tailor acceptance criteria and transcription preferences to your compliance needs.

<Frame>
  <img alt="Didit face match advanced settings panel for similarity thresholds and acceptance rules" />
</Frame>

* **Expiration mode**: Choose how to handle documents with past expiration dates.
  * **Reject expired**: If the document's expiration date is earlier than today, mark it as expired and reject.
  * **Allow expired**: Do not flag or block documents with a past expiration date.
* **Preferred character format**: Select how extracted names and fields should be normalized.
  * **Prefer Latin characters (A–Z)**: Example: "Mohammed"
  * **Prefer original script (non‑Latin)**: Example: "محمد"
* **Regional support & subtypes**: Enable documents by region and specify acceptable subtypes when a document type contains many variations.
  * Example: For United States driver's licenses, select the exact subtypes you accept (e.g., Arizona Commercial Driver License, Indiana Operator License (REAL ID), New York Enhanced Driver License, etc.).
  * Use the "Accepted subtypes" control to quickly include/exclude many variants (e.g., "128 selected").

> Tip: These settings apply per country and document type, so you can be strict in some markets while more permissive in others.


# Face match report
Source: https://docs.didit.me/core-technology/face-match/report-face-match

How to read Didit's face match 1:1 report: status, similarity score, source/target image URLs, warnings, and where the data appears in API responses.

## Overview

The **face match report** captures a 1:1 biometric comparison between the live selfie captured during liveness and a reference image — most commonly the portrait extracted from the ID document. It returns a single 0–100 similarity score, signed URLs for the two compared images, the source session for the reference image, and any warnings raised by the match.

The report is produced after the user completes both the liveness step and the document step in a workflow (or, for portrait-based workflows such as biometric authentication, after liveness alone), or directly via the standalone [Face Match API](/standalone-apis/face-match) when you supply two arbitrary face images yourself.

Each report carries its own `status` — independent of the overall session status — that reflects how the face match step alone resolved:

* **Approved** — `score` is above the review threshold and no auto-decline warning fired.
* **In Review** — `score` is between the decline and review thresholds.
* **Declined** — `score` is at or below the decline threshold, or `NO_REFERENCE_IMAGE` fired.
* **Resub Requested** — a reviewer requested the user resubmit this step from the console.
* **Not Finished** — the face match step has not produced a result yet (including while the user is retrying a failed capture).

## Where it appears in API responses

The face match report ships inside the `face_matches[]` array — **always a JSON array**, never a singular `face_match` object. It is `null` until at least one face-match step has produced data, and multiple entries appear when a workflow runs face match more than once.

* **Session decision API** — `GET /v3/session/{sessionId}/decision/` returns `face_matches[]` at the top level. See [Retrieve session decision](/sessions-api/retrieve-session).
* **Webhooks** — `session.status.updated` payloads include the same `face_matches[]` array once the step has produced data. See [Webhooks](/integration/webhooks).
* **Standalone Face Match API** — for direct 1:1 comparisons, see [Face Match standalone API](/standalone-apis/face-match).

<Note>
  Read `response.face_matches[0]` and iterate the array — the singular `face_match` shape some older tutorials referenced does not exist on the v3 decision endpoint.
</Note>

## Schema

The canonical field-by-field schema lives on the [Data models](/reference/data-models#face-match) reference page. The fields below mirror that canonical schema.

| Field                     | Type                                                                             | Description                                                                                                                                                                                                                                                                  |
| ------------------------- | -------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`                  | `"Approved" \| "Declined" \| "In Review" \| "Resub Requested" \| "Not Finished"` | Face match step status (`FeatureStatusChoices`).                                                                                                                                                                                                                             |
| `node_id`                 | string \| null                                                                   | Workflow graph node that produced this report.                                                                                                                                                                                                                               |
| `score`                   | number 0–100 \| null                                                             | Biometric similarity score, rounded to 2 decimals. `null` when no comparison was possible.                                                                                                                                                                                   |
| `source_image_session_id` | string \| null                                                                   | UUID of the session whose stored portrait supplied the reference (source) image — set in portrait-based flows (biometric authentication, or a portrait supplied at session creation). `null` when the reference image is the document portrait captured in the same session. |
| `source_image`            | string (signed URL)                                                              | The reference image (usually the document portrait). Short-lived signed URL — download promptly, never persist the URL.                                                                                                                                                      |
| `target_image`            | string (signed URL)                                                              | The target image (usually the liveness selfie). Short-lived signed URL — download promptly, never persist the URL.                                                                                                                                                           |
| `warnings[]`              | array                                                                            | Module-level warnings. Each entry carries `feature` (always `"FACEMATCH"`), `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, and `node_id` — see [Face match warnings](/core-technology/face-match/warnings-face-match).                      |

## Status values

| Status            | Meaning                                                                                                                                                                | Downstream effect                                                          |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `Approved`        | Score above the review threshold and no auto-decline warning fired.                                                                                                    | Counts as a successful face match.                                         |
| `In Review`       | Score above the decline threshold but at or below the review threshold.                                                                                                | Session also moves to `In Review` until a reviewer acts.                   |
| `Declined`        | Score at or below the decline threshold, or `NO_REFERENCE_IMAGE` fired.                                                                                                | Session is declined unless another approved branch satisfies the workflow. |
| `Resub Requested` | A reviewer requested resubmission of this step from the console.                                                                                                       | The user is asked to capture again.                                        |
| `Not Finished`    | The face match step has not produced a result (an input was missing, the workflow never reached the compare step, or the user is still inside the capture-retry loop). | The branch did not complete.                                               |

Low-similarity failures are retried before the status sticks: the user gets up to `face_match_max_attempts` captures (3 by default), and only the final attempt's score is applied. Custom status rules configured on the workflow node can further adjust the resulting status, combining with the score-derived status under `Declined` > `In Review` > `Approved` precedence.

## Examples

### Approved — clean match

```json theme={null}
{
  "face_matches": [
    {
      "status": "Approved",
      "node_id": "feature_face_match_1",
      "score": 96.42,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": []
    }
  ]
}
```

### In Review — borderline similarity

```json theme={null}
{
  "face_matches": [
    {
      "status": "In Review",
      "node_id": "feature_face_match_1",
      "score": 65.43,
      "source_image_session_id": null,
      "source_image": "https://<media-host>/source-image.jpg",
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "LOW_FACE_MATCH_SIMILARITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face match similarity",
          "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
          "node_id": "feature_face_match_1"
        }
      ]
    }
  ]
}
```

### Declined — no reference image to compare against

```json theme={null}
{
  "face_matches": [
    {
      "status": "Declined",
      "node_id": "feature_face_match_1",
      "score": null,
      "source_image_session_id": null,
      "source_image": null,
      "target_image": "https://<media-host>/target-image.jpg",
      "warnings": [
        {
          "feature": "FACEMATCH",
          "risk": "NO_REFERENCE_IMAGE",
          "additional_data": null,
          "log_type": "error",
          "short_description": "No source image found for performing face match",
          "long_description": "A reference image for facial comparison is missing, preventing the system from completing the face matching process.",
          "node_id": "feature_face_match_1"
        }
      ]
    }
  ]
}
```

## Security note

The signed URLs for `source_image` and `target_image` are biometric data and expire after a short validity window. Treat them as short-lived: do not cache or surface them publicly. Typically your application only needs `status` and `score` — store as little as possible to minimize biometric data on your servers.

## Related

* [Face match warnings](/core-technology/face-match/warnings-face-match) — full warning enum, causes, and remediation.
* [Liveness report](/core-technology/liveness/report-liveness) — the upstream step that captures the target image.
* [Webhooks](/integration/webhooks) — listen for `session.status.updated` to receive the report.
* [Data models — Face match](/reference/data-models#face-match) — canonical schema with every field.


# Face match warnings
Source: https://docs.didit.me/core-technology/face-match/warnings-face-match

Every warning Didit's face match 1:1 module emits — low similarity, missing reference image, exhausted retries — with cause, severity, and remediation.

## Overview

Warnings on the face match report flag every condition Didit observed while running the 1:1 face comparison. They land in the `warnings[]` array on each item of `face_matches[]` (see [Face match report](/core-technology/face-match/report-face-match)). Each entry also carries `feature: "FACEMATCH"` and the `node_id` of the workflow node that raised it.

Every warning has three layers:

1. **The `risk` code** — a stable identifier you can match on in your code.
2. **The `log_type`** — `information`, `warning`, or `error`, derived from your workflow's similarity-score thresholds.
3. **The decision impact** — set by the workflow's review and decline thresholds for the similarity score.

The face match module is intentionally small — there are exactly five risk codes, listed in full below.

## Auto-decline conditions

The following risk always forces the face match report (and the session) to `Declined`:

| Risk                 | Trigger                                                                                                 |
| -------------------- | ------------------------------------------------------------------------------------------------------- |
| `NO_REFERENCE_IMAGE` | One of `source_image` (reference) or `target_image` (selfie) is missing, so no comparison was possible. |

When `NO_REFERENCE_IMAGE` fires, `LOW_FACE_MATCH_SIMILARITY` is suppressed (there is nothing to score).

## Configurable verification settings

In the Didit console, the face match similarity score is governed by two thresholds (no Approve/Review/Decline toggle):

| Setting                              | Default | Behavior                                                                                             |
| ------------------------------------ | ------- | ---------------------------------------------------------------------------------------------------- |
| `face_match_score_review_threshold`  | 70      | When `score` ≤ this value, `LOW_FACE_MATCH_SIMILARITY` fires and the status moves to `In Review`.    |
| `face_match_score_decline_threshold` | 50      | When `score` ≤ this value, the same warning escalates to `error` and the status moves to `Declined`. |

Tune the review threshold higher if you observe too many false approvals; tune the decline threshold lower if you observe too many false declines.

A separate setting controls what happens when a similarity score **cannot be computed at all** because no face was detected in one of the images:

| Setting                          | Default  | Behavior                                                                                                                                                                                                                                  |
| -------------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `face_match_not_computed_action` | `REVIEW` | Action applied once the "could not compute" outcome is terminal. `REVIEW` sends the report to `In Review`; `DECLINE` sets it to `Declined`. (There is no auto-approve option — a score that was never computed is never silently passed.) |

This action governs both `FACE_MATCH_NOT_COMPUTED` (no face in the document portrait) and an exhausted `NO_FACE_IN_SELFIE` (no face in the selfie after the user's retries). When the selfie is the problem, the user is first asked to recapture — see below — and the action only applies if a face still cannot be detected once the attempt budget runs out.

Low-similarity failures also enter a capture-retry loop before the status sticks: the user gets up to `face_match_max_attempts` total attempts (default 3, configurable 2–5 per workflow node) to recapture. A `NO_FACE_IN_SELFIE` failure uses the same retry loop, since recapturing a clearer selfie can fix it. A `FACE_MATCH_NOT_COMPUTED` failure does **not** retry — the document portrait cannot be recaptured at this step. Only when the budget is exhausted does the last attempt's status apply — and `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` is logged to record it.

On the standalone [Face Match API](/standalone-apis/face-match) only a decline threshold exists (`face_match_score_decline_threshold` request option, default 30); any fired warning declines the request, and `NO_REFERENCE_IMAGE` fires when no face could be compared at all.

## Warnings produced

| Risk                               | Cause                                                                                                                                                      | Severity                                                                            | Affects status?                                                                              | Remediation                                                                                                                      |
| ---------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------- |
| `LOW_FACE_MATCH_SIMILARITY`        | `score` ≤ `face_match_score_review_threshold`. Suppressed when `NO_REFERENCE_IMAGE` is also present.                                                       | `warning` between the thresholds; `error` at or below the decline threshold         | `In Review` between the thresholds; `Declined` at or below the decline threshold             | Tune thresholds, or accept via manual review.                                                                                    |
| `FACE_MATCH_NOT_COMPUTED`          | A similarity score could not be computed because no face was detected in the **document portrait**. Suppressed when `NO_REFERENCE_IMAGE` is also present.  | `warning` when `face_match_not_computed_action` is `REVIEW`; `error` when `DECLINE` | `In Review` or `Declined`, per `face_match_not_computed_action`                              | The document image cannot be recaptured at this step — resolve via manual review, or recapture the document earlier in the flow. |
| `NO_FACE_IN_SELFIE`                | A similarity score could not be computed because no face was detected in the user's **selfie**. The user is asked to retake the selfie before this sticks. | `warning` when `face_match_not_computed_action` is `REVIEW`; `error` when `DECLINE` | `In Review` or `Declined`, per `face_match_not_computed_action`, after retries are exhausted | The user recaptures a clearer, well-lit, front-facing selfie.                                                                    |
| `NO_REFERENCE_IMAGE`               | Either the reference image or the target image is missing.                                                                                                 | `error`                                                                             | **Auto-decline**                                                                             | Ensure both the document portrait and the liveness selfie are captured. For the standalone API, pass two valid face images.      |
| `FACE_MATCH_MAX_ATTEMPTS_EXCEEDED` | The user exhausted the capture-retry budget (`face_match_max_attempts`) after repeated low-similarity failures.                                            | `information`                                                                       | No — records that the last attempt's computed status (decline or review) was applied         | Raise `face_match_max_attempts` on the workflow node, or resolve via manual review.                                              |

## Examples

### In Review — borderline similarity

```json theme={null}
"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "LOW_FACE_MATCH_SIMILARITY",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Low face match similarity",
    "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
    "node_id": "feature_face_match_1"
  }
]
```

### In Review — face match could not be computed

```json theme={null}
"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "FACE_MATCH_NOT_COMPUTED",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Face match could not be computed",
    "long_description": "A face match score could not be computed because a face could not be detected in the document portrait. Because the document image cannot be recaptured, the result follows the configured action for this case (manual review by default) rather than being treated as a low-similarity mismatch.",
    "node_id": "feature_face_match_1"
  }
]
```

### Auto-decline — missing reference

```json theme={null}
"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "NO_REFERENCE_IMAGE",
    "additional_data": null,
    "log_type": "error",
    "short_description": "No source image found for performing face match",
    "long_description": "A reference image for facial comparison is missing, preventing the system from completing the face matching process.",
    "node_id": "feature_face_match_1"
  }
]
```

### Retries exhausted — last attempt's status applied

```json theme={null}
"warnings": [
  {
    "feature": "FACEMATCH",
    "risk": "LOW_FACE_MATCH_SIMILARITY",
    "additional_data": null,
    "log_type": "error",
    "short_description": "Low face match similarity",
    "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
    "node_id": "feature_face_match_1"
  },
  {
    "feature": "FACEMATCH",
    "risk": "FACE_MATCH_MAX_ATTEMPTS_EXCEEDED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "Maximum face match attempts exceeded",
    "long_description": "The maximum number of face match capture attempts has been reached. The last attempt's computed status (decline or review) has been applied.",
    "node_id": "feature_face_match_1"
  }
]
```

<Note>
  The standalone [Face Match API](/standalone-apis/face-match) returns the same warning shape minus `node_id` (the comparison is not bound to a workflow node).
</Note>

## Warning types

Each risk is assigned a severity based on your application's configuration. The three severities are:

<WarningTypes />

## Related

* [Face match report](/core-technology/face-match/report-face-match) — full report schema and statuses.
* [Liveness warnings](/core-technology/liveness/warnings-liveness) — upstream warnings on the selfie capture.
* [Webhooks](/integration/webhooks) — `session.status.updated` carries the warnings as soon as the step finishes.
* [Data models — Face match](/reference/data-models#face-match) — canonical schema.
* [Data models — Warning object](/reference/data-models#warning-object) — the shape of every entry in `warnings[]`.


# Face Search 1:N
Source: https://docs.didit.me/core-technology/face-search/overview

Search faces across all verified users to spot duplicates and blocklisted fraudsters. Free with Didit identity verification, sub-2-second response.

Face Search is a powerful feature that allows you to search for a specific face across all your approved identity verification sessions. This capability helps identify duplicate accounts, prevent fraud, and enhance your security measures.

<AgentPromptAccordion title="Face Search Integration Prompt" />

The Academy lesson on reading a verification result reaches face search and block lists at 6:53.

<VideoEmbed title="Face search and block lists — Didit Academy" />

<Frame>
  <img alt="Didit face search 1:N flow integrated with liveness for duplicate and blocklist detection" />
</Frame>

## Automatic Face Search Integration

> Face Search is automatically performed during liveness checks in verification sessions to detect duplicate users and check against blocklisted faces.

### Automatic Duplicate Detection

When a user completes a liveness check during identity verification:

* Their facial biometrics are automatically compared against all previously verified users
* The system identifies potential duplicate accounts based on facial similarity
* Matches are flagged according to your configured similarity thresholds
* You can review and take action on potential duplicate users

### Blocklist Integration

Face Search seamlessly integrates with the [blocklist feature](/management-api/lists/overview):

* During verification, faces are automatically checked against your blocklist
* If a match to a blocklisted face is found, the verification is automatically declined
* This prevents previously identified problematic users from creating new accounts
* Helps maintain the integrity of your verification process

### API Access

Face Search functionality is also available through our [API](/standalone-apis/face-search), allowing you to:

* Programmatically submit face searches
* Integrate face matching capabilities into your own applications
* Build custom fraud detection workflows
* Create automated systems for duplicate detection

## Key Features

* **High Accuracy**: Advanced biometric algorithms provide reliable match results
* **Configurable Thresholds**: Customize match sensitivity based on your risk tolerance
* **Comprehensive Scanning**: Search across all your verified users
* **Rapid Results**: Process searches quickly even with large user databases
* **Privacy-Focused**: Matching uses numeric face templates scoped to your application; the index never leaves your tenant

### Configurable Thresholds

You can customize search sensitivity by setting different thresholds for similarity scores:

<Note>
  These thresholds can be adjusted based on your risk tolerance and security requirements.
</Note>

## How It Works

<Steps>
  <Step title="Face Extraction" icon="face-viewfinder">
    When a search is initiated, the system processes the reference image:

    | Process                | Description                                              |
    | ---------------------- | -------------------------------------------------------- |
    | **Feature extraction** | Isolates facial features from the reference image        |
    | **Normalization**      | Standardizes facial data for consistent comparison       |
    | **Quality validation** | Checks image quality and facial clarity                  |
    | **Vector encoding**    | Creates a mathematical vector representation of the face |
  </Step>

  <Step title="Comparison Algorithm" icon="magnifying-glass">
    The system searches across your entire database of verified sessions:

    * Compares the reference facial vector against **every face enrolled in your application**: session faces, faces uploaded to User profiles, your face lists, and any retained biometric templates
    * Employs advanced neural network architecture optimized for speed and accuracy
    * Supports two search modes: **most similar** (ranked list) and **blocklisted or approved** (status-filtered)
    * Processes large databases rapidly using optimized indexing
  </Step>

  <Step title="Similarity Scoring" icon="percent">
    For each comparison, a similarity percentage is generated:

    |  Score Range  | Interpretation                             |
    | :-----------: | ------------------------------------------ |
    |    **90%+**   | Strong match — very likely the same person |
    |   **70–89%**  | Possible match — may require manual review |
    | **Below 70%** | Likely different individuals               |

    Your configured match thresholds determine which results are flagged.
  </Step>

  <Step title="Results Delivery" icon="file-export">
    The system returns a comprehensive result set:

    * **Ranked list** of potential matches sorted by similarity score
    * **Match details** including session ID, verification date, and vendor data
    * **Similarity percentage** for each match
    * **Match images** available for visual review
    * **Blocklist status** indicating if the matched face is blocklisted
  </Step>
</Steps>

## Deleted sessions and retained biometric templates

Deleting a session deletes its face embedding by default, so the person drops out of the index and can verify again without a duplicate flag. Applications that delete sessions soon after approval but still need to catch repeat sign-ups can enable [biometric-template retention](/console/data-retention#biometric-template-retention). Didit then keeps one image-free biometric template anchored to the User after the session is deleted, and that template takes part in Face Search and automatic duplicate detection exactly like a live session face.

A hit on a retained template is reported with `source: "retained_template"`, the owning User's `vendor_user_id` and `vendor_data`, and a `biometric_template_id`. It carries no session id, match image, identity details, or session status, because the session that produced the face no longer exists. Retained templates are never blocklisted; face blocklist entries keep their own independent biometric entry.

The template stays until its scheduled expiry, User deletion, a privacy-erasure request, or an explicit purge through the [Biometric Templates API](/management-api/biometric-templates/overview) or **Lists → Biometric templates** in the Console.

## Similarity Percentage

The similarity percentage is the core metric used to determine potential matches:

* **High percentage (typically 90% and above)**: Indicates a strong likelihood that the faces belong to the same person.
* **Medium percentage (70-89%)**: Suggests possible matches that may require further review.
* **Low percentage (below 70%)**: Likely indicates different individuals.

The exact threshold for what constitutes a "match" can be configured based on your security requirements. Increasing the threshold reduces false positives but may increase false negatives.

## Use Cases

* **Fraud Prevention**: Identify users attempting to create multiple accounts
* **Enhanced KYC**: Add an additional layer of verification to your KYC process
* **Regulatory Compliance**: Meet requirements for detecting duplicate accounts
* **Access Control**: Verify user authenticity for high-security areas
* **Law Enforcement**: Assist authorized agencies in identifying persons of interest


# Face search report
Source: https://docs.didit.me/core-technology/face-search/report-face-search

Read the Face Search 1:N response: matched sessions, similarity percentages, blocklist and allowlist flags, and user details for fraud investigation and duplicate detection.

## Overview

Face Search is a **1:N** biometric search: Didit takes the largest detected face in your `user_image` and searches it against your application's face search index — faces enrolled from verification sessions, saved standalone API calls, direct user-profile face uploads, and your block/allow lists. It is distinct from Face Match, which is **1:1** — Face Match compares a selfie against the portrait on a specific document, while Face Search asks "have we seen this person anywhere before?".

Two behaviors are worth understanding before you parse the report:

* **Only blocklist matches decline.** `face_search.status` is `Declined` only when a `FACE_IN_BLOCKLIST` or `POSSIBLE_FACE_IN_BLOCKLIST` warning fires. Duplicate matches alone return `Approved` — inspect `matches` and `warnings`, not just `status`.
* **Optional persistence and enrollment.** When `save_api_request=true` (the default), the call is persisted as an API-type session and the searched face is enrolled into your face search index. Faces enrolled by Face Search calls are **excluded from future Face Search results**, so repeated searches never match each other. Pass `save_api_request=false` for a one-shot query: nothing is stored and the face is not enrolled.

## Where the results appear

Face Search is a standalone API. The search results are returned **synchronously, in the `POST /v3/face-search/` response only**, as a singular `face_search` object at the top level:

```text theme={null}
POST /v3/face-search/  ──▶  { "request_id": …, "face_search": { … }, "vendor_data": …, "metadata": …, "created_at": … }
```

There is no plural `face_searches[]` array anywhere — the plural-array convention used by `id_verifications[]`, `aml_screenings[]`, and `liveness_checks[]` on the session decision endpoint does not apply.

When `save_api_request=true` (the default), the call is also persisted as an API-type session:

* **Business Console** — the session appears in your sessions list with the search image, matches, and warnings.
* **`GET /v3/session/{sessionId}/decision/`** — retrievable using the returned `request_id` as the session id. The persisted data surfaces as a `FACE_SEARCH` entry in `features[]` and as a `liveness_checks[]` item carrying the stored `matches` (with freshly signed `match_image_url` values) and `warnings` — **not** as a `face_search` object.

When `save_api_request=false`, `request_id` is a transient correlation UUID: the session is never stored, so it cannot be fetched from the Console or the decision endpoint.

## Schema

See [Face Search in the Data Models reference](/reference/data-models#face-search) for the canonical field tables. The shape below reflects what the endpoint actually returns at runtime.

```typescript theme={null}
interface FaceSearchResponse {
  request_id: string;            // UUID — the persisted session id when save_api_request=true
  face_search: {
    status: 'Approved' | 'Declined';
    total_matches: number;       // 0-5, length of matches[]
    matches: FaceSearchMatch[];  // capped at 5, ordered by similarity
    user_image: {                // always present
      entities: {
        bbox: [number, number, number, number];
        confidence: number;      // 0-1, one entry per detected face
      }[];
      best_angle: 0 | 90 | 180 | 270;
    };
    warnings: Warning[];
  };
  vendor_data: string | null;    // echoed from the request
  metadata: object | null;       // echoed from the request
  created_at: string;            // ISO 8601, e.g. "2026-06-12T01:04:42.763237+00:00"
}

interface FaceSearchMatch {
  session_id: string | null;     // UUID of the matched session; null for non-session matches
  session_number: number | null; // Console-friendly number; null for non-session matches
  similarity_percentage: number; // 0-100
  source: 'session' | 'imported' | 'list_entry' | 'retained_template';
  vendor_data: string | null;    // the matched session's, imported profile's, or retained template's User vendor_data
  vendor_user_id: string | null; // UUID of the linked User; null for list_entry matches and sessions without a User
  biometric_template_id: string | null; // set only for retained_template matches
  verification_date: string | null;  // "YYYY-MM-DDThh:mm:ssZ"; null for list_entry matches; the retention date for retained_template matches
  user_details: {
    full_name: string | null;
    document_type: string | null;
    document_number: string | null;
  } | null;                      // null when the matched session has no document data
  match_image_url: string | null; // signed URL when save_api_request=true; raw storage path otherwise; null for retained_template matches
  status: 'Approved' | 'Declined' | 'In Review' | null;  // the matched session's status
  is_blocklisted: boolean;
  is_allowlisted: boolean;
  api_service: 'ID_VERIFICATION' | 'FACE_MATCH' | 'AGE_ESTIMATION' | 'POA' | 'AML'
             | 'PASSIVE_LIVENESS' | 'DATABASE_VALIDATION' | 'PHONE_VERIFICATION'
             | 'EMAIL_VERIFICATION' | null;  // null when the match comes from a workflow session
}

interface Warning {
  risk: string;
  feature: 'LIVENESS';           // always LIVENESS on this endpoint
  additional_data: object | null;
  log_type: 'error' | 'warning' | 'information';
  short_description: string;
  long_description: string;
}
```

Field notes:

* **`matches[]` is capped at 5** entries above the similarity floor, ordered by descending similarity (`search_type=blocklisted_or_approved` ranks blocklisted entries first, then allowlisted, then similarity).
* **`source`** tells you where the matched face was enrolled from: `session` — a verification session or a saved standalone API call; `imported` — a face uploaded directly to a user profile; `list_entry` — a face attached to one of your lists; `retained_template` — an image-free [biometric template](/management-api/biometric-templates/overview) the application retained after deleting the source session. `session_id`, `session_number`, `status`, and `api_service` are `null` for `imported`, `list_entry`, and `retained_template` matches.
* **`retained_template` matches** carry `vendor_user_id`, `vendor_data`, and `biometric_template_id`, and always `null` for `match_image_url`, `user_details`, and everything session-related: the session that produced the face no longer exists and the template holds no image or identity data. `is_blocklisted` is always `false` for a retained template; a blocklisted face is reported separately as a `list_entry` match. Purge the template with `DELETE /v3/biometric-templates/{biometric_template_id}/`.
* **`api_service`** is the matched session's standalone API type (uppercase, e.g. `PASSIVE_LIVENESS`) and `null` when the matched face came from a regular workflow verification session.
* **`user_details`** comes from the matched session's document verification. For `source: imported` matches it is populated from the user profile instead (`full_name` set, `document_type`/`document_number` null); it is `null` when no identity data exists (for example liveness-only sessions).
* **Warnings use a reduced shape** compared with workflow warnings: there is no `node_id`. The documented response contract (`FaceSearchResponseSerializer`) declares the five fields `risk`, `additional_data`, `log_type`, `short_description`, `long_description`; the runtime payload additionally carries `feature`, which is always `"LIVENESS"` here. See [Face Search warnings](/core-technology/face-search/warnings-face-search).
* **Same-user matches are not excluded** — unlike workflow duplicate detection, the standalone endpoint does not filter out prior sessions with the same `vendor_data`, so a returning legitimate user matches their own earlier sessions.

## Status values

The top-level `face_search.status` is derived from `warnings[]`. The match-level `status` reflects the **matched session's** verification outcome and is independent.

| Value      | When it appears                                                                                                                        |
| ---------- | -------------------------------------------------------------------------------------------------------------------------------------- |
| `Approved` | No blocklist warning fired. Includes the case where duplicate matches were found — duplicates are informational signals, not declines. |
| `Declined` | A `FACE_IN_BLOCKLIST` or `POSSIBLE_FACE_IN_BLOCKLIST` warning fired — the search image matched a face in your face blocklist.          |

Note: when the search image contains no detectable face the API returns HTTP `400` with `{"error": "No face detected in the image"}` **before** a `face_search` object is built — there is no `Declined` status for that case. Insufficient credits return HTTP `403` before any image processing.

## Examples

### Approved — duplicate match, no blocklist

```json theme={null}
{
  "request_id": "5e0c3a1f-7b2d-4c8e-9f10-2a3b4c5d6e7f",
  "face_search": {
    "status": "Approved",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "1f2e3d4c-5b6a-7980-1122-334455667788",
        "session_number": 1024,
        "similarity_percentage": 87.42,
        "source": "session",
        "vendor_data": "user-9",
        "verification_date": "2025-11-20T09:15:00Z",
        "user_details": {
          "full_name": "Jane Marie Doe",
          "document_type": "Passport",
          "document_number": "X1234567"
        },
        "match_image_url": "https://<media-host>/face/9c8b7a6d/reference.jpg?signature=...",
        "status": "Approved",
        "is_blocklisted": false,
        "is_allowlisted": false,
        "api_service": null
      }
    ],
    "user_image": {
      "entities": [
        {
          "bbox": [40, 40, 120, 120],
          "confidence": 0.732973
        }
      ],
      "best_angle": 0
    },
    "warnings": [
      {
        "risk": "DUPLICATED_FACE",
        "feature": "LIVENESS",
        "additional_data": {
          "duplicated_session_id": "1f2e3d4c-5b6a-7980-1122-334455667788",
          "duplicated_session_number": 1024,
          "api_service": null
        },
        "log_type": "information",
        "short_description": "Duplicated face from other approved session",
        "long_description": "The system identified a duplicated face from another approved session, requiring further investigation."
      }
    ]
  },
  "vendor_data": "user-123",
  "metadata": null,
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}
```

### Declined — blocklist match

```json theme={null}
{
  "request_id": "a1b2c3d4-e5f6-7890-1234-567890abcdef",
  "face_search": {
    "status": "Declined",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
        "session_number": 323442,
        "similarity_percentage": 99.99,
        "source": "session",
        "vendor_data": "user-1",
        "verification_date": "2025-01-01T00:00:00Z",
        "user_details": {
          "full_name": "Jane Marie Doe",
          "document_type": "ID",
          "document_number": "X1234567"
        },
        "match_image_url": "https://<media-host>/face/3f6a1c2e/reference.jpg?signature=...",
        "status": "Approved",
        "is_blocklisted": true,
        "is_allowlisted": false,
        "api_service": "PASSIVE_LIVENESS"
      }
    ],
    "user_image": {
      "entities": [
        {
          "bbox": [40, 40, 120, 120],
          "confidence": 0.732973
        }
      ],
      "best_angle": 0
    },
    "warnings": [
      {
        "risk": "FACE_IN_BLOCKLIST",
        "feature": "LIVENESS",
        "additional_data": {
          "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
          "blocklisted_session_number": 323442,
          "api_service": "PASSIVE_LIVENESS"
        },
        "log_type": "error",
        "short_description": "Face in blocklist",
        "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified."
      }
    ]
  },
  "vendor_data": "user-123",
  "metadata": null,
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}
```

## Related

* [Face Search warnings](/core-technology/face-search/warnings-face-search) — every warning code the search can emit
* [Face Search API reference](/standalone-apis/face-search) — request parameters and `search_type` modes
* [Data models — Face Search](/reference/data-models#face-search) — canonical schema
* [Webhooks](/integration/webhooks) — `status.updated` payloads for persisted sessions

<Note>
  When `save_api_request=true`, `match_image_url` values are signed, short-lived URLs — re-fetch the session decision endpoint with the returned `request_id` to get fresh ones. When `save_api_request=false`, they are internal storage paths and are not directly downloadable. Store only the matched session id, status, and `similarity_percentage` on your side — do not retain the underlying biometric image.
</Note>


# Face search warnings
Source: https://docs.didit.me/core-technology/face-search/warnings-face-search

Reference for Face Search 1:N warning codes: blocklist matches, duplicate faces, multiple faces, and the search-image gate that rejects images with no detectable face.

## Overview

Face Search emits a small set of warnings so your team can tell **why** a search returned `Approved` or `Declined`. Warnings are returned in the `face_search.warnings[]` array of the `POST /v3/face-search/` response (see [Face Search report](/core-technology/face-search/report-face-search)).

Warnings here use a **reduced shape** compared with workflow warnings: there is no `node_id`. The documented response contract declares five fields — `risk`, `additional_data`, `log_type`, `short_description`, `long_description` — and the runtime payload additionally carries `feature`, which is always `"LIVENESS"` on this endpoint.

## Warnings produced

| Risk                         | Cause                                                                                                                                                                                                                                                 | Severity (`log_type`) | Affects status                                                                                                                    | Recommended remediation                                                                                                             |
| ---------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | --------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------- |
| `FACE_IN_BLOCKLIST`          | The search image matched a face in your application's face blocklist above the high-confidence similarity band.                                                                                                                                       | `error`               | Forces `Declined`.                                                                                                                | Reject the user. Investigate the linked session via `additional_data.blocklisted_session_id`.                                       |
| `POSSIBLE_FACE_IN_BLOCKLIST` | A blocklisted face matched within the lower "possible" similarity band, below the high-confidence band.                                                                                                                                               | `error`               | Forces `Declined` on the standalone Face Search API (stricter than the workflow liveness check, which sends this risk to review). | Manual review. Confirm the hit against the original blocklist evidence before acting.                                               |
| `MULTIPLE_FACES_DETECTED`    | More than one face was found in the submitted search image. The search still runs, using the largest detected face.                                                                                                                                   | `warning`             | None — never declines on its own.                                                                                                 | Re-capture with a single subject in frame if the largest face is not the intended one.                                              |
| `DUPLICATED_FACE`            | The face matched, above the high-confidence band, a face from an **approved** session or an imported user-profile face. The standalone endpoint does not exclude same-`vendor_data` sessions, so a returning user matches their own earlier sessions. | `information`         | None — duplicates are surfaced as signal, not declines.                                                                           | Investigate the linked session via `additional_data.duplicated_session_id`. Decide whether to block or merge accounts on your side. |
| `POSSIBLE_DUPLICATED_FACE`   | Same as `DUPLICATED_FACE` but the similarity sits in the lower "possible" band rather than the high-confidence band.                                                                                                                                  | `information`         | None.                                                                                                                             | Manual review before treating the two records as the same person.                                                                   |

Producer: `FaceSearchAPIView.add_warnings` (`apis/views/face_search.py:250-330`); status derivation: `get_face_search_status` (`apis/views/face_search.py:242-248`), which declines **only** for the two blocklist risks.

Emission rules worth knowing:

* **Blocklist takes precedence over duplicates.** A confirmed blocklist hit suppresses `DUPLICATED_FACE`, and a possible blocklist hit suppresses `POSSIBLE_DUPLICATED_FACE` — you never get both members of a pair for the same confidence band.
* **`additional_data` references the first matching face only**, even when `matches[]` contains several. Blocklist warnings carry `{blocklisted_session_id, blocklisted_session_number, api_service}`; duplicate warnings carry `{duplicated_session_id, duplicated_session_number, api_service}`; `MULTIPLE_FACES_DETECTED` carries `null`. The `api_service` value is uppercase (e.g. `PASSIVE_LIVENESS`) or `null` for workflow sessions.
* **Allowlisted faces suppress duplicate warnings** — a high-confidence allowlist match clears `DUPLICATED_FACE`/`POSSIBLE_DUPLICATED_FACE` (it never clears blocklist warnings).

### Exact warning strings

| Risk                         | `short_description`                                  | `long_description`                                                                                                                                                                                    |
| ---------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `FACE_IN_BLOCKLIST`          | Face in blocklist                                    | The system identified a face in the blocklist, which means the face is not allowed to be verified.                                                                                                    |
| `POSSIBLE_FACE_IN_BLOCKLIST` | Possible face in blocklist                           | The system identified a possible face in the blocklist, which means the face is not allowed to be verified.                                                                                           |
| `DUPLICATED_FACE`            | Duplicated face from other approved session          | The system identified a duplicated face from another approved session, requiring further investigation.                                                                                               |
| `POSSIBLE_DUPLICATED_FACE`   | Possible duplicated face from other approved session | The system identified a possible duplicate face from another approved session, requiring further investigation.                                                                                       |
| `MULTIPLE_FACES_DETECTED`    | Multiple faces detected                              | Multiple faces were detected in the liveness image. The system uses the largest face for liveness verification and face comparison, but the presence of multiple faces may require additional review. |

### Search-image gate

When no face is detected in `user_image`, the API rejects the request with HTTP `400` and `{"error": "No face detected in the image"}` **before** a `face_search` object is built — so a `NO_FACE_DETECTED` warning never appears in a successful Face Search response. This is returned as a top-level `error` string, not in `warnings[]`.

## Configurable settings

The similarity bands that split confirmed hits (`FACE_IN_BLOCKLIST`, `DUPLICATED_FACE`) from possible hits (`POSSIBLE_FACE_IN_BLOCKLIST`, `POSSIBLE_DUPLICATED_FACE`) are fixed internally — per-application threshold tuning applies to the workflow liveness check, not this endpoint. The switches you control per request are:

* **`search_type`** (`most_similar`, default | `blocklisted_or_approved`) — `most_similar` ranks every enrolled face by similarity; `blocklisted_or_approved` restricts candidates to blocklisted faces, allowlisted faces, faces from approved sessions, and imported user-profile faces, ranking blocklisted entries first.
* **`save_api_request`** (default `true`) — persists the call as an API-type session and enrolls the searched face into your face search index. Faces enrolled by Face Search calls are excluded from future Face Search results. Set to `false` to query without storing or enrolling.
* **`rotate_image`** (default `false`) — tries 90-degree rotations and keeps the orientation with the best face detection; useful when EXIF orientation is missing.

## Examples

### Blocklist hit (forces `Declined`)

```json theme={null}
{
  "warnings": [
    {
      "risk": "FACE_IN_BLOCKLIST",
      "feature": "LIVENESS",
      "additional_data": {
        "blocklisted_session_id": "882c42d5-8a4d-4d20-8080-a22f57822c86",
        "blocklisted_session_number": 323442,
        "api_service": "PASSIVE_LIVENESS"
      },
      "log_type": "error",
      "short_description": "Face in blocklist",
      "long_description": "The system identified a face in the blocklist, which means the face is not allowed to be verified."
    }
  ]
}
```

### Duplicate signal (status stays `Approved`)

```json theme={null}
{
  "warnings": [
    {
      "risk": "MULTIPLE_FACES_DETECTED",
      "feature": "LIVENESS",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "Multiple faces detected",
      "long_description": "Multiple faces were detected in the liveness image. The system uses the largest face for liveness verification and face comparison, but the presence of multiple faces may require additional review."
    },
    {
      "risk": "DUPLICATED_FACE",
      "feature": "LIVENESS",
      "additional_data": {
        "duplicated_session_id": "1f2e3d4c-5b6a-7980-1122-334455667788",
        "duplicated_session_number": 1024,
        "api_service": null
      },
      "log_type": "information",
      "short_description": "Duplicated face from other approved session",
      "long_description": "The system identified a duplicated face from another approved session, requiring further investigation."
    }
  ]
}
```

## Related

* [Face Search report](/core-technology/face-search/report-face-search) — full response shape
* [Face Search API reference](/standalone-apis/face-search) — request parameters
* [Face Match warnings](/core-technology/id-verification/warnings-id-verification) — 1:1 selfie-to-document warnings (separate from Face Search)
* [Data models — Face Search](/reference/data-models#face-search) — canonical schema

### Warning types

<WarningTypes />


# Digital ID Wallets
Source: https://docs.didit.me/core-technology/id-verification/digital-id-wallets

Let people verify with the government or bank digital identity they already hold - MitID, BankID, itsme, UAE PASS, gov.br and the EUDI Wallet.

Wallet sign-in is one of the three [ID Verification methods](/core-technology/id-verification/verification-methods). The user signs in with a digital identity they already hold — a national eID or a bank identity — and that provider shares a signed set of attributes with Didit.

The result carries the assurance tier `cryptographic`: an identity provider authenticated the person and signed the attributes it returned. That is all the tier claims. It is not a ranking against the other two tiers — they describe [different evidence](/core-technology/id-verification/verification-methods#assurance-tiers), not more or less of the same thing — and how long a sign-in takes is the wallet's own flow, which Didit neither controls nor promises.

<Warning>
  **No wallet is live in production yet.** The launch switch is off there, so every wallet below reads **Coming soon**, cannot be enabled on a workflow, and is not offered to end users — whatever a wallet's own row would otherwise say. The table is the roadmap, not today's capability. Talk to your account team about being in the first cohort.
</Warning>

## Prerequisites and pricing

Each wallet requires an active identity with the issuer named below and access to its authentication method. The account must be eligible for the requested attributes, and the user must consent to sharing them. A signature verifies the issuer and returned claims; it does not guarantee that every requested attribute is present, current or sufficient for your compliance policy. A wallet without a portrait does not include a selfie comparison.

All 22 catalog wallet entries are listed below, including both BankID countries. Every wallet retail rate is still marked as a placeholder and is therefore **pending publication**, in USD per completed verified sign-in. Failed, cancelled, expired or abandoned sign-ins are not charged. A configured document fallback is a separate document check, subject to the document allowance. The 500 free document checks do not include wallet sign-in. No launch date is promised.

These are **identity wallets**. [Crypto wallet screening](/core-technology/wallet-screening/overview) checks blockchain addresses for financial risk and is a separate product with separate pricing.

## What the user does

1. Picks their country in the ID step and chooses a wallet from the ones you accept.
2. Signs in with that wallet, the way they sign in to their bank or their government portal.
3. Approves sharing their identity attributes with you.
4. Comes back verified.

**Same-device** sign-in hands the user to the wallet app and returns them to the verification flow when they are done. **Cross-device** sign-in shows a QR code on the desktop screen that they scan with the phone holding the wallet. Both are offered where the wallet supports them; the user picks.

A started sign-in stays valid for a limited window (10 minutes by default). After that the user has to start it again.

## Wallets are an accept-list

`wallet.providers` is the list of wallets a country may offer. It is not a ranking: the order you send carries no meaning, is normalised into catalog order on save, and the end user chooses from whatever you accepted. Enable one wallet or every wallet in a country — the choice is theirs.

The API rejects a workflow that enables a wallet the catalog does not offer in that country, or one that is still **Coming soon**.

<Note>
  Every wallet's attribute list below includes a **signed assertion**. Didit verifies that signature and reports the verdict as `wallet_verification.signature_valid` on the session; the assertion itself is not handed back, so there is no reference to fetch or store. The **On the session** column says which of the two you get for each attribute.
</Note>

## Supported wallets

| Wallet                | Wallet id         | Countries                           | Issuing authority                                           | Level of assurance | Availability | Price      |
| --------------------- | ----------------- | ----------------------------------- | ----------------------------------------------------------- | ------------------ | ------------ | ---------- |
| MitID                 | `mitid`           | Denmark                             | Danish Agency for Digital Government                        | Substantial        | Coming soon  | On request |
| BankID                | `bankid_se`       | Sweden                              | Finansiell ID-Teknik / bank consortium                      | Substantial        | Coming soon  | On request |
| BankID                | `bankid_no`       | Norway                              | BankID BankAxept AS                                         | High               | Coming soon  | On request |
| Vipps                 | `vipps`           | Norway                              | Vipps MobilePay / BankID NO                                 | Substantial        | Coming soon  | On request |
| Buypass ID            | `buypass`         | Norway                              | Buypass AS                                                  | High               | Coming soon  | On request |
| itsme                 | `itsme`           | Belgium, Luxembourg, Netherlands    | Belgian Mobile ID                                           | Substantial        | Coming soon  | On request |
| iDIN                  | `idin`            | Netherlands                         | Dutch banks (Currence iDIN)                                 | Substantial        | Coming soon  | On request |
| Finnish Trust Network | `ftn`             | Finland                             | Finnish banks and mobile operators (FTN)                    | Substantial        | Coming soon  | On request |
| Personalausweis       | `personalausweis` | Germany                             | Bundesministerium des Innern (eID)                          | High               | Coming soon  | On request |
| Freja eID             | `frejaid`         | Sweden                              | Freja eID Group                                             | Substantial        | Coming soon  | On request |
| UAE PASS              | `uae_pass`        | United Arab Emirates                | UAE Digital Government Authority                            | High               | Coming soon  | On request |
| gov.br                | `govbr`           | Brazil                              | Governo Federal do Brasil                                   | Substantial        | Coming soon  | On request |
| OneID                 | `oneid`           | United Kingdom                      | OneID (UK bank-verified identity)                           | Substantial        | Coming soon  | On request |
| GOV.UK Wallet         | `govuk_wallet`    | United Kingdom                      | UK Government Digital Service                               | High               | Coming soon  | On request |
| Smart-ID              | `smart_id`        | Estonia, Latvia, Lithuania, Belgium | SK ID Solutions                                             | High               | Coming soon  | On request |
| Mobile-ID             | `mobile_id`       | Estonia, Latvia, Lithuania          | SK ID Solutions with the national mobile operators          | High               | Coming soon  | On request |
| Bank iD               | `bankid_cz`       | Czechia                             | Bankovní identita, a.s.                                     | Substantial        | Coming soon  | On request |
| MojeID                | `mojeid`          | Czechia                             | CZ.NIC                                                      | Substantial        | Coming soon  | On request |
| Diia                  | `diia`            | Ukraine                             | Ministry of Digital Transformation of Ukraine               | High               | Coming soon  | On request |
| FranceConnect         | `franceconnect`   | France                              | DINUM (French state)                                        | Substantial        | Coming soon  | On request |
| Auðkenni              | `audkenni`        | Iceland                             | Auðkenni (Icelandic electronic ID)                          | High               | Coming soon  | On request |
| EUDI Wallet           | `eudi`            | 30 EU/EEA member states             | The user's own member state; the issuer differs per country | High               | Coming soon  | On request |

<Note>
  **Availability** is served by the capability catalog, not hand-maintained here. **Coming soon** means the wallet is visible in the console and cannot be switched on yet; it carries no committed date. Prices marked **On request** are not published yet — wallets are priced per wallet and quoted by your account team.
</Note>

## Level of assurance

Every wallet asserts a [eIDAS](https://en.wikipedia.org/wiki/EIDAS) level of assurance — `low`, `substantial` or `high` — and Didit records the level the wallet actually asserted on the result, not the level the catalog hoped for. If the wallet returns a weaker level than the one that was requested, the sign-in fails rather than quietly downgrading.

Check `wallet_verification.level_of_assurance` on the session when your compliance rules depend on it.

## Per-wallet reference

### MitID

`mitid` · Denmark · **Coming soon**

|                                 |                                                           |
| ------------------------------- | --------------------------------------------------------- |
| Issuing authority               | Danish Agency for Digital Government                      |
| Coverage                        | Covers \~95% of adults                                    |
| Level of assurance              | Substantial                                               |
| Shares a portrait               | No                                                        |
| Price (USD / completed sign-in) | On request                                                |
| Prerequisite                    | An active MitID identity and access to its sign-in method |

**Attributes requested:** Name · Date of birth · CPR alias (pseudonymised)

| Attribute returned         | Key                  | On the session                                                                              |
| -------------------------- | -------------------- | ------------------------------------------------------------------------------------------- |
| Full name                  | `full_name`          | Returned in `wallet_verification.attributes`                                                |
| Date of birth              | `date_of_birth`      | Returned in `wallet_verification.attributes`                                                |
| CPR alias (pseudonymised)  | `cpr_alias`          | Returned in `wallet_verification.attributes`                                                |
| Level of assurance reached | `level_of_assurance` | Returned in `wallet_verification.attributes`                                                |
| Signed assertion           | `signed_assertion`   | Verified inside Didit; the session returns the `signature_valid` verdict, not the assertion |

### BankID

`bankid_se` · Sweden · **Coming soon**

|                                 |                                                            |
| ------------------------------- | ---------------------------------------------------------- |
| Issuing authority               | Finansiell ID-Teknik / bank consortium                     |
| Coverage                        | Covers \~99% of adults                                     |
| Level of assurance              | Substantial                                                |
| Shares a portrait               | No                                                         |
| Price (USD / completed sign-in) | On request                                                 |
| Prerequisite                    | An active BankID identity and access to its sign-in method |

**Attributes requested:** Name · Personal number

| Attribute returned | Key                | On the session                                                                              |
| ------------------ | ------------------ | ------------------------------------------------------------------------------------------- |
| Full name          | `full_name`        | Returned in `wallet_verification.attributes`                                                |
| Date of birth      | `date_of_birth`    | Returned in `wallet_verification.attributes`                                                |
| Personal number    | `personal_number`  | Returned in `wallet_verification.attributes`                                                |
| Signed assertion   | `signed_assertion` | Verified inside Didit; the session returns the `signature_valid` verdict, not the assertion |

### BankID

`bankid_no` · Norway · **Coming soon**

|                                 |                                                            |
| ------------------------------- | ---------------------------------------------------------- |
| Issuing authority               | BankID BankAxept AS                                        |
| Coverage                        | National eID                                               |
| Level of assurance              | High                                                       |
| Shares a portrait               | No                                                         |
| Price (USD / completed sign-in) | On request                                                 |
| Prerequisite                    | An active BankID identity and access to its sign-in method |

**Attributes requested:** Name · Date of birth · National identity number

| Attribute returned       | Key                        | On the session                                                                              |
| ------------------------ | -------------------------- | ------------------------------------------------------------------------------------------- |
| Full name                | `full_name`                | Returned in `wallet_verification.attributes`                                                |
| Date of birth            | `date_of_birth`            | Returned in `wallet_verification.attributes`                                                |
| National identity number | `national_identity_number` | Returned in `wallet_verification.attributes`                                                |
| Signed assertion         | `signed_assertion`         | Verified inside Didit; the session returns the `signature_valid` verdict, not the assertion |

### Vipps

`vipps` · Norway · **Coming soon**

|                                 |                                                           |
| ------------------------------- | --------------------------------------------------------- |
| Issuing authority               | Vipps MobilePay / BankID NO                               |
| Coverage                        | Covers \~90% of adults                                    |
| Level of assurance              | Substantial                                               |
| Shares a portrait               | No                                                        |
| Price (USD / completed sign-in) | On request                                                |
| Prerequisite                    | An active Vipps identity and access to its sign-in method |

**Attributes requested:** Name · Date of birth · National identity number

| Attribute returned       | Key                        | On the session                                                                              |
| ------------------------ | -------------------------- | ------------------------------------------------------------------------------------------- |
| Full name                | `full_name`                | Returned in `wallet_verification.attributes`                                                |
| Date of birth            | `date_of_birth`            | Returned in `wallet_verification.attributes`                                                |
| National identity number | `national_identity_number` | Returned in `wallet_verification.attributes`                                                |
| Signed assertion         | `signed_assertion`         | Verified inside Didit; the session returns the `signature_valid` verdict, not the assertion |

### Buypass ID

`buypass` · Norway · **Coming soon**

|                                 |                                                                |
| ------------------------------- | -------------------------------------------------------------- |
| Issuing authority               | Buypass AS                                                     |
| Coverage                        | Covers \~35% of adults                                         |
| Level of assurance              | High                                                           |
| Shares a portrait               | No                                                             |
| Price (USD / completed sign-in) | On request                                                     |
| Prerequisite                    | An active Buypass ID identity and access to its sign-in method |

**Attributes requested:** Name · Date of birth · National identity number

| Attribute returned | Key                | On the session                                                                              |
| ------------------ | ------------------ | ------------------------------------------------------------------------------------------- |
| Full name          | `full_name`        | Returned in `wallet_verification.attributes`                                                |
| Date of birth      | `date_of_birth`    | Returned in `wallet_verification.attributes`                                                |
| Signed assertion   | `signed_assertion` | Verified inside Didit; the session returns the `signature_valid` verdict, not the assertion |

### itsme

`itsme` · Belgium, Luxembourg, Netherlands · **Coming soon**

|                                 |                                                           |
| ------------------------------- | --------------------------------------------------------- |
| Issuing authority               | Belgian Mobile ID                                         |
| Coverage                        | Covers \~78% of adults                                    |
| Level of assurance              | Substantial                                               |
| Shares a portrait               | No                                                        |
| Price (USD / completed sign-in) | On request                                                |
| Prerequisite                    | An active itsme identity and access to its sign-in method |

**Attributes requested:** Name · Date of birth · National register number

| Attribute returned       | Key                        | On the session                                                                              |
| ------------------------ | -------------------------- | ------------------------------------------------------------------------------------------- |
| Full name                | `full_name`                | Returned in `wallet_verification.attributes`                                                |
| Date of birth            | `date_of_birth`            | Returned in `wallet_verification.attributes`                                                |
| National register number | `national_register_number` | Returned in `wallet_verification.attributes`                                                |
| Signed assertion         | `signed_assertion`         | Verified inside Didit; the session returns the `signature_valid` verdict, not the assertion |

### iDIN

`idin` · Netherlands · **Coming soon**

|                                 |                                                          |
| ------------------------------- | -------------------------------------------------------- |
| Issuing authority               | Dutch banks (Currence iDIN)                              |
| Coverage                        | Every Dutch bank customer                                |
| Level of assurance              | Substantial                                              |
| Shares a portrait               | No                                                       |
| Price (USD / completed sign-in) | On request                                               |
| Prerequisite                    | An active iDIN identity and access to its sign-in method |

**Attributes requested:** Name · Date of birth · Address

| Attribute returned | Key                | On the session                                                                              |
| ------------------ | ------------------ | ------------------------------------------------------------------------------------------- |
| Full name          | `full_name`        | Returned in `wallet_verification.attributes`                                                |
| Date of birth      | `date_of_birth`    | Returned in `wallet_verification.attributes`                                                |
| Gender             | `gender`           | Returned in `wallet_verification.attributes`                                                |
| Address            | `address`          | Returned in `wallet_verification.attributes`                                                |
| Bank identifier    | `bank_identifier`  | Returned in `wallet_verification.attributes`                                                |
| Signed assertion   | `signed_assertion` | Verified inside Didit; the session returns the `signature_valid` verdict, not the assertion |

### Finnish Trust Network

`ftn` · Finland · **Coming soon**

|                                 |                                                                           |
| ------------------------------- | ------------------------------------------------------------------------- |
| Issuing authority               | Finnish banks and mobile operators (FTN)                                  |
| Coverage                        | Every Finnish bank customer                                               |
| Level of assurance              | Substantial                                                               |
| Shares a portrait               | No                                                                        |
| Price (USD / completed sign-in) | On request                                                                |
| Prerequisite                    | An active Finnish Trust Network identity and access to its sign-in method |

**Attributes requested:** Name · Personal identity code

| Attribute returned     | Key                      | On the session                                                                              |
| ---------------------- | ------------------------ | ------------------------------------------------------------------------------------------- |
| Full name              | `full_name`              | Returned in `wallet_verification.attributes`                                                |
| Date of birth          | `date_of_birth`          | Returned in `wallet_verification.attributes`                                                |
| Personal identity code | `personal_identity_code` | Returned in `wallet_verification.attributes`                                                |
| Signed assertion       | `signed_assertion`       | Verified inside Didit; the session returns the `signature_valid` verdict, not the assertion |

### Personalausweis

`personalausweis` · Germany · **Coming soon**

|                                 |                                                                     |
| ------------------------------- | ------------------------------------------------------------------- |
| Issuing authority               | Bundesministerium des Innern (eID)                                  |
| Coverage                        | Every German ID card with the online function activated             |
| Level of assurance              | High                                                                |
| Shares a portrait               | No                                                                  |
| Price (USD / completed sign-in) | On request                                                          |
| Prerequisite                    | An active Personalausweis identity and access to its sign-in method |

**Attributes requested:** Name · Date of birth

| Attribute returned | Key                | On the session                                                                              |
| ------------------ | ------------------ | ------------------------------------------------------------------------------------------- |
| Full name          | `full_name`        | Returned in `wallet_verification.attributes`                                                |
| Date of birth      | `date_of_birth`    | Returned in `wallet_verification.attributes`                                                |
| Address            | `address`          | Returned in `wallet_verification.attributes`                                                |
| Signed assertion   | `signed_assertion` | Verified inside Didit; the session returns the `signature_valid` verdict, not the assertion |

### Freja eID

`frejaid` · Sweden · **Coming soon**

|                                 |                                                               |
| ------------------------------- | ------------------------------------------------------------- |
| Issuing authority               | Freja eID Group                                               |
| Coverage                        | Government-approved Swedish eID                               |
| Level of assurance              | Substantial                                                   |
| Shares a portrait               | No                                                            |
| Price (USD / completed sign-in) | On request                                                    |
| Prerequisite                    | An active Freja eID identity and access to its sign-in method |

**Attributes requested:** Name · Personal number

| Attribute returned | Key                | On the session                                                                              |
| ------------------ | ------------------ | ------------------------------------------------------------------------------------------- |
| Full name          | `full_name`        | Returned in `wallet_verification.attributes`                                                |
| Date of birth      | `date_of_birth`    | Returned in `wallet_verification.attributes`                                                |
| Personal number    | `personal_number`  | Returned in `wallet_verification.attributes`                                                |
| Signed assertion   | `signed_assertion` | Verified inside Didit; the session returns the `signature_valid` verdict, not the assertion |

### UAE PASS

`uae_pass` · United Arab Emirates · **Coming soon**

|                                 |                                                              |
| ------------------------------- | ------------------------------------------------------------ |
| Issuing authority               | UAE Digital Government Authority                             |
| Coverage                        | Government sign-in                                           |
| Level of assurance              | High                                                         |
| Shares a portrait               | Yes                                                          |
| Price (USD / completed sign-in) | On request                                                   |
| Prerequisite                    | An active UAE PASS identity and access to its sign-in method |

**Attributes requested:** Name · Emirates ID number · Nationality · Portrait

| Attribute returned    | Key                  | On the session                                                                              |
| --------------------- | -------------------- | ------------------------------------------------------------------------------------------- |
| Full name (EN and AR) | `full_name`          | Returned in `wallet_verification.attributes`                                                |
| Emirates ID number    | `emirates_id_number` | Returned in `wallet_verification.attributes`                                                |
| Nationality           | `nationality`        | Returned in `wallet_verification.attributes`                                                |
| Date of birth         | `date_of_birth`      | Returned in `wallet_verification.attributes`                                                |
| Portrait              | `portrait`           | Returned in `wallet_verification.attributes`                                                |
| Signed assertion      | `signed_assertion`   | Verified inside Didit; the session returns the `signature_valid` verdict, not the assertion |

### gov.br

`govbr` · Brazil · **Coming soon**

|                                 |                                                            |
| ------------------------------- | ---------------------------------------------------------- |
| Issuing authority               | Governo Federal do Brasil                                  |
| Coverage                        | Government sign-in                                         |
| Level of assurance              | Substantial                                                |
| Shares a portrait               | No                                                         |
| Price (USD / completed sign-in) | On request                                                 |
| Prerequisite                    | An active gov.br identity and access to its sign-in method |

**Attributes requested:** Name · CPF

| Attribute returned | Key                | On the session                                                                              |
| ------------------ | ------------------ | ------------------------------------------------------------------------------------------- |
| Full name          | `full_name`        | Returned in `wallet_verification.attributes`                                                |
| CPF                | `tax_number`       | Returned in `wallet_verification.attributes`                                                |
| Signed assertion   | `signed_assertion` | Verified inside Didit; the session returns the `signature_valid` verdict, not the assertion |

### OneID

`oneid` · United Kingdom · **Coming soon**

|                                 |                                                           |
| ------------------------------- | --------------------------------------------------------- |
| Issuing authority               | OneID (UK bank-verified identity)                         |
| Coverage                        | Bank-verified identity for UK current-account holders     |
| Level of assurance              | Substantial                                               |
| Shares a portrait               | No                                                        |
| Price (USD / completed sign-in) | On request                                                |
| Prerequisite                    | An active OneID identity and access to its sign-in method |

**Attributes requested:** Name · Date of birth

| Attribute returned | Key                | On the session                                                                              |
| ------------------ | ------------------ | ------------------------------------------------------------------------------------------- |
| Full name          | `full_name`        | Returned in `wallet_verification.attributes`                                                |
| Date of birth      | `date_of_birth`    | Returned in `wallet_verification.attributes`                                                |
| Address            | `address`          | Returned in `wallet_verification.attributes`                                                |
| Signed assertion   | `signed_assertion` | Verified inside Didit; the session returns the `signature_valid` verdict, not the assertion |

### GOV.UK Wallet

`govuk_wallet` · United Kingdom · **Coming soon**

|                                 |                                                                   |
| ------------------------------- | ----------------------------------------------------------------- |
| Issuing authority               | UK Government Digital Service                                     |
| Coverage                        | Government wallet; driving licence credential rolling out         |
| Level of assurance              | High                                                              |
| Shares a portrait               | Yes                                                               |
| Price (USD / completed sign-in) | On request                                                        |
| Prerequisite                    | An active GOV.UK Wallet identity and access to its sign-in method |

**Attributes requested:** Name · Date of birth · Portrait

| Attribute returned | Key                | On the session                                                                              |
| ------------------ | ------------------ | ------------------------------------------------------------------------------------------- |
| Full name          | `full_name`        | Returned in `wallet_verification.attributes`                                                |
| Date of birth      | `date_of_birth`    | Returned in `wallet_verification.attributes`                                                |
| Portrait           | `portrait`         | Returned in `wallet_verification.attributes`                                                |
| Signed assertion   | `signed_assertion` | Verified inside Didit; the session returns the `signature_valid` verdict, not the assertion |

### Smart-ID

`smart_id` · Estonia, Latvia, Lithuania, Belgium · **Coming soon**

|                                 |                                                              |
| ------------------------------- | ------------------------------------------------------------ |
| Issuing authority               | SK ID Solutions                                              |
| Coverage                        | Covers most adults in the Baltics                            |
| Level of assurance              | High                                                         |
| Shares a portrait               | No                                                           |
| Price (USD / completed sign-in) | On request                                                   |
| Prerequisite                    | An active Smart-ID identity and access to its sign-in method |

**Attributes requested:** Name · Personal identification code

| Attribute returned           | Key                | On the session                                                                              |
| ---------------------------- | ------------------ | ------------------------------------------------------------------------------------------- |
| Full name                    | `full_name`        | Returned in `wallet_verification.attributes`                                                |
| Date of birth                | `date_of_birth`    | Returned in `wallet_verification.attributes`                                                |
| Personal identification code | `personal_code`    | Returned in `wallet_verification.attributes`                                                |
| Signed assertion             | `signed_assertion` | Verified inside Didit; the session returns the `signature_valid` verdict, not the assertion |

### Mobile-ID

`mobile_id` · Estonia, Latvia, Lithuania · **Coming soon**

|                                 |                                                               |
| ------------------------------- | ------------------------------------------------------------- |
| Issuing authority               | SK ID Solutions with the national mobile operators            |
| Coverage                        | SIM-based national eID                                        |
| Level of assurance              | High                                                          |
| Shares a portrait               | No                                                            |
| Price (USD / completed sign-in) | On request                                                    |
| Prerequisite                    | An active Mobile-ID identity and access to its sign-in method |

**Attributes requested:** Name · Personal identification code

| Attribute returned           | Key                | On the session                                                                              |
| ---------------------------- | ------------------ | ------------------------------------------------------------------------------------------- |
| Full name                    | `full_name`        | Returned in `wallet_verification.attributes`                                                |
| Date of birth                | `date_of_birth`    | Returned in `wallet_verification.attributes`                                                |
| Personal identification code | `personal_code`    | Returned in `wallet_verification.attributes`                                                |
| Signed assertion             | `signed_assertion` | Verified inside Didit; the session returns the `signature_valid` verdict, not the assertion |

### Bank iD

`bankid_cz` · Czechia · **Coming soon**

|                                 |                                                             |
| ------------------------------- | ----------------------------------------------------------- |
| Issuing authority               | Bankovní identita, a.s.                                     |
| Coverage                        | Federated bank identity; the most used Czech sign-in        |
| Level of assurance              | Substantial                                                 |
| Shares a portrait               | No                                                          |
| Price (USD / completed sign-in) | On request                                                  |
| Prerequisite                    | An active Bank iD identity and access to its sign-in method |

**Attributes requested:** Name · Date of birth

| Attribute returned | Key                | On the session                                                                              |
| ------------------ | ------------------ | ------------------------------------------------------------------------------------------- |
| Full name          | `full_name`        | Returned in `wallet_verification.attributes`                                                |
| Date of birth      | `date_of_birth`    | Returned in `wallet_verification.attributes`                                                |
| Address            | `address`          | Returned in `wallet_verification.attributes`                                                |
| Signed assertion   | `signed_assertion` | Verified inside Didit; the session returns the `signature_valid` verdict, not the assertion |

### MojeID

`mojeid` · Czechia · **Coming soon**

|                                 |                                                            |
| ------------------------------- | ---------------------------------------------------------- |
| Issuing authority               | CZ.NIC                                                     |
| Coverage                        | About 500k active accounts; substantial LoA on a subset    |
| Level of assurance              | Substantial                                                |
| Shares a portrait               | No                                                         |
| Price (USD / completed sign-in) | On request                                                 |
| Prerequisite                    | An active MojeID identity and access to its sign-in method |

**Attributes requested:** Name · Date of birth

| Attribute returned | Key                | On the session                                                                              |
| ------------------ | ------------------ | ------------------------------------------------------------------------------------------- |
| Full name          | `full_name`        | Returned in `wallet_verification.attributes`                                                |
| Date of birth      | `date_of_birth`    | Returned in `wallet_verification.attributes`                                                |
| Signed assertion   | `signed_assertion` | Verified inside Didit; the session returns the `signature_valid` verdict, not the assertion |

### Diia

`diia` · Ukraine · **Coming soon**

|                                 |                                                               |
| ------------------------------- | ------------------------------------------------------------- |
| Issuing authority               | Ministry of Digital Transformation of Ukraine                 |
| Coverage                        | Government app with national ID, passport and driving licence |
| Level of assurance              | High                                                          |
| Shares a portrait               | Yes                                                           |
| Price (USD / completed sign-in) | On request                                                    |
| Prerequisite                    | An active Diia identity and access to its sign-in method      |

**Attributes requested:** Name · Date of birth · Portrait

| Attribute returned | Key                | On the session                                                                              |
| ------------------ | ------------------ | ------------------------------------------------------------------------------------------- |
| Full name          | `full_name`        | Returned in `wallet_verification.attributes`                                                |
| Date of birth      | `date_of_birth`    | Returned in `wallet_verification.attributes`                                                |
| Document number    | `document_number`  | Returned in `wallet_verification.attributes`                                                |
| Portrait           | `portrait`         | Returned in `wallet_verification.attributes`                                                |
| Signed assertion   | `signed_assertion` | Verified inside Didit; the session returns the `signature_valid` verdict, not the assertion |

### FranceConnect

`franceconnect` · France · **Coming soon**

|                                 |                                                                   |
| ------------------------------- | ----------------------------------------------------------------- |
| Issuing authority               | DINUM (French state)                                              |
| Coverage                        | Federated state identity; FranceConnect+ for substantial LoA      |
| Level of assurance              | Substantial                                                       |
| Shares a portrait               | No                                                                |
| Price (USD / completed sign-in) | On request                                                        |
| Prerequisite                    | An active FranceConnect identity and access to its sign-in method |

**Attributes requested:** Name · Date of birth

| Attribute returned | Key                | On the session                                                                              |
| ------------------ | ------------------ | ------------------------------------------------------------------------------------------- |
| Full name          | `full_name`        | Returned in `wallet_verification.attributes`                                                |
| Date of birth      | `date_of_birth`    | Returned in `wallet_verification.attributes`                                                |
| Place of birth     | `birthplace`       | Returned in `wallet_verification.attributes`                                                |
| Signed assertion   | `signed_assertion` | Verified inside Didit; the session returns the `signature_valid` verdict, not the assertion |

### Auðkenni

`audkenni` · Iceland · **Coming soon**

|                                 |                                                              |
| ------------------------------- | ------------------------------------------------------------ |
| Issuing authority               | Auðkenni (Icelandic electronic ID)                           |
| Coverage                        | National electronic ID on SIM and app                        |
| Level of assurance              | High                                                         |
| Shares a portrait               | No                                                           |
| Price (USD / completed sign-in) | On request                                                   |
| Prerequisite                    | An active Auðkenni identity and access to its sign-in method |

**Attributes requested:** Name · Kennitala

| Attribute returned | Key                | On the session                                                                              |
| ------------------ | ------------------ | ------------------------------------------------------------------------------------------- |
| Full name          | `full_name`        | Returned in `wallet_verification.attributes`                                                |
| Date of birth      | `date_of_birth`    | Returned in `wallet_verification.attributes`                                                |
| Kennitala          | `national_id`      | Returned in `wallet_verification.attributes`                                                |
| Signed assertion   | `signed_assertion` | Verified inside Didit; the session returns the `signature_valid` verdict, not the assertion |

### EUDI Wallet

`eudi` · 30 EU/EEA member states · **Coming soon**

|                                 |                                                                 |
| ------------------------------- | --------------------------------------------------------------- |
| Issuing authority               | The user's own member state; the issuer differs per country     |
| Coverage                        | Coming soon - EU rollout                                        |
| Level of assurance              | High                                                            |
| Shares a portrait               | Yes                                                             |
| Price (USD / completed sign-in) | On request                                                      |
| Prerequisite                    | An active EUDI Wallet identity and access to its sign-in method |

**Attributes requested:** PID - person identification data

| Attribute returned                   | Key   | On the session                               |
| ------------------------------------ | ----- | -------------------------------------------- |
| Schema follows the ARF PID rule book | `pid` | Returned in `wallet_verification.attributes` |

## Failure and fallback

| Outcome     | Means                                                                  | Billed |
| ----------- | ---------------------------------------------------------------------- | ------ |
| `verified`  | The user signed in and the signed attributes checked out.              | Yes    |
| `cancelled` | The user backed out of the wallet sign-in.                             | No     |
| `timeout`   | The sign-in window expired before it completed.                        | No     |
| `failed`    | The sign-in could not be completed or the assertion did not check out. | No     |

Anything other than `verified` follows the country's `wallet.on_failure` switch: `fallback_to_document` sends the user to document capture, `decline` ends the session with a declined ID Verification. `fallback_to_document` with document capture disabled for that country declines instead, because there is nowhere to fall back to.

Only a completed sign-in is billed. Abandoned, cancelled, timed-out and failed sign-ins cost nothing.

## What lands on the session

```json theme={null}
{
  "node_id": "feature_ocr_1",
  "status": "Approved",
  "verification_method": "wallet",
  "assurance": "cryptographic",
  "wallet_provider": "mitid",
  "fallback_from": null,
  "id_lookup": null,
  "wallet_verification": {
    "provider": "mitid",
    "provider_name": "MitID",
    "issuing_authority": "Danish Agency for Digital Government",
    "issuing_country": "DNK",
    "credential_type": "person_identification",
    "level_of_assurance": "substantial",
    "verified_at": "2026-09-04T09:12:44Z",
    "signature_valid": true,
    "attributes": {
      "full_name": "Freja Nielsen",
      "date_of_birth": "1988-03-02",
      "cpr_alias": "b0f1c2d3-e4f5-4678-9abc-def012345678"
    },
    "portrait": null,
    "face_match_score": null
  }
}
```

`attributes` holds exactly what that wallet shared, keyed the way the per-wallet table above lists it. `portrait` is present only for the wallets that share one. `signature_valid` is the result of validating the signed assertion the wallet returned. It is `true` on a completed sign-in: an assertion that does not validate fails the sign-in and follows `wallet.on_failure` instead of producing an approved result.

Full field types are in the [ID verification data model](/reference/data-models#id-verification).

## Configuring wallets

```json theme={null}
{
  "feature": "OCR",
  "config": {
    "methods": {
      "DNK": {
        "document": { "enabled": true },
        "wallet": { "enabled": true, "providers": ["mitid"], "on_failure": "fallback_to_document" }
      },
      "NOR": {
        "document": { "enabled": true },
        "wallet": { "enabled": true, "providers": ["bankid_no", "vipps"], "on_failure": "decline" }
      }
    }
  }
}
```

Enable at least one wallet when `wallet.enabled` is `true`, or the save is rejected. The full reference is in [Workflow feature configs](/management-api/workflows/feature-configs#ocr--id-verification).

## Related

* [ID Verification methods](/core-technology/id-verification/verification-methods) — the three methods, fallback and billing
* [Non-document lookup](/core-technology/id-verification/non-doc-lookup) — the data-match method
* [ID Verification methods in the console](/console/id-verification-methods) — enabling wallets per country


# Document Geolocation
Source: https://docs.didit.me/core-technology/id-verification/document-geolocation-id-verification

Validate addresses with Didit's Document Geolocation: AI address extraction, Google Maps cross-checks, and fictitious-address detection in real time.

Didit's Document Address Geolocation verification offers a comprehensive solution to validate user addresses efficiently and accurately. Our system leverages advanced AI technology and external data sources to ensure the authenticity and validity of address information.

<Frame>
  <img alt="Didit document geolocation flow extracting and validating addresses from ID documents" />
</Frame>

<Steps>
  <Step title="Capture" icon="camera">
    Users upload an image of their document containing address information. Our advanced AI handles the rest.

    | Capability           | Description                                          |
    | -------------------- | ---------------------------------------------------- |
    | **Document types**   | Passports, IDs, residence permits, and more          |
    | **Language support** | Multi-language and multi-format recognition          |
    | **AI extraction**    | Automatic data extraction from the uploaded document |
  </Step>

  <Step title="Data Extraction" icon="map-location-dot">
    The extracted address is validated against multiple sources and geolocated by IP.

    | Capability               | Description                                                 |
    | ------------------------ | ----------------------------------------------------------- |
    | **Map integration**      | Google Maps and OpenStreetMap cross-referencing             |
    | **Component validation** | Street, city, region, and postal code verified individually |
    | **Fraud detection**      | Fictitious address detection to prevent possible fraud      |
  </Step>

  <Step title="Analysis" icon="chart-bar">
    A full report is generated on the validation status with standardized outputs.

    | Capability                | Description                                      |
    | ------------------------- | ------------------------------------------------ |
    | **Verification results**  | Detailed results with standardized output format |
    | **Comprehensive reports** | Full verification reports for every submission   |
    | **Delivery options**      | Results via dashboard, webhooks, or API          |
  </Step>
</Steps>

<Frame>
  <img alt="Didit address geolocation result on map cross-checking declared address against Google Maps" />
</Frame>

<Note>
  Our system supports global address formats and provides standardized outputs regardless of the input document type or region.
</Note>

### Report Structure

The Document Geolocation report returns a JSON object with a root-level `address` field containing all verification results.

#### Core Response Fields

```typescript theme={null}
interface DocumentGeolocationResponse {
  address: string;
  parsed_address: {
    id: string;
    label: string;
    street_1: string;
    street_2: string | null;
    city: string;
    region: string;
    postal_code: string;
    raw_results: {
      geometry: {
        location: {
          lat: number;
          lng: number;
        };
        location_type: string;
        viewport: {
          northeast: {
            lat: number;
            lng: number;
          };
          southwest: {
            lat: number;
            lng: number;
          };
        };
      };
      formatted_address: string;
    };
  };
}
```

### Response Fields

#### Address Information

* `address`: Complete address as extracted from document
* `parsed_address.street_1`: Primary street information
* `parsed_address.street_2`: Secondary street information
* `parsed_address.city`: City name
* `parsed_address.region`: State or region
* `parsed_address.postal_code`: ZIP or postal code

#### Geolocation Data

* `raw_results.geometry.location`: Precise coordinates
* `raw_results.location_type`: Accuracy level of geolocation
* `raw_results.viewport`: Coordinate boundaries
* `raw_results.formatted_address`: Standardized address format

### Sample JSON Response

```json theme={null}
{
  "address": "123 Sample Street",
  "parsed_address": {
    "id": "7c6280a2-fb6a-4258-93d5-2ac987cbc6ba",
    "city": "Madrid",
    "label": "Spain ID Card Address",
    "region": "Madrid",
    "street_1": "Avda de Madrid 34",
    "street_2": null,
    "postal_code": "28822",
    "raw_results": {
      "geometry": {
        "location": {
          "lat": 37.4222804,
          "lng": -122.0843428
        },
        "location_type": "ROOFTOP",
        "viewport": {
          "northeast": {
            "lat": 37.4237349802915,
            "lng": -122.083183169709
          },
          "southwest": {
            "lat": 37.4210370197085,
            "lng": -122.085881130292
          }
        }
      },
      "formatted_address": "Avda de Madrid 34, Madrid, Madrid 28822, Spain"
    }
  }
}
```

<Note>
  For a complete list of possible properties and their values, please refer to our [*API Reference*](/sessions-api/retrieve-session).
</Note>

### Security and Privacy Considerations

Address information extracted from documents should be handled with appropriate security measures and in compliance with relevant data protection regulations. Implement proper access controls and data retention policies for this sensitive information.


# Document Monitoring
Source: https://docs.didit.me/core-technology/id-verification/document-monitoring-id-verification

Track document expiration automatically with Didit's Document Monitoring. Real-time alerts, ongoing KYC compliance, reduced fraud risk across your user base.

Didit's Document Monitoring feature automatically tracks and validates user documents throughout their lifecycle. This proactive system helps maintain compliance, reduce fraud risks, and ensures your user base always has valid identification documents.

1. **Initial Verification**: User documents are verified during the onboarding process.
2. **Expiration Date Extraction**: The system extracts and records the expiration date from verified documents.
3. **Continuous Monitoring**: Our system regularly checks the expiration status of all stored documents.
4. **Status Update**: When a document expires, the user's status is automatically changed from "Approved" to "Kyc Expired".
5. **Notification**: You receive alerts about expired documents through our dashboard, webhooks, or API.

<Frame>
  <img alt="Didit document monitoring dashboard tracking ID expiration and KYC compliance status" />
</Frame>

## Key Features

#### 1. Intelligent Document Monitoring

* Real-time tracking of document expiration dates

* Automatic status updates based on document validity

* Support for multiple document types and jurisdictions

* Continuously monitor expiration dates of all verified documents

* Automatically update user statuses based on document validity

#### 2. Proactive Notifications

* Receive webhooks when a document status changes to "Kyc Expired"

#### 3. Comprehensive Reporting

* Access detailed reports on document statuses across your user base

<Note>
  Need more details? Check our [*API Reference*](/sessions-api/retrieve-session) for a complete list of properties and values.
</Note>

## Use Cases

#### Regulatory Compliance

* Maintain continuous compliance with KYC/AML regulations
* Automate document validity checks
* Generate compliance reports on demand

#### Risk Management

* Prevent fraud from expired documents
* Reduce operational risks through automated monitoring
* Maintain up-to-date user verification status

#### Operational Efficiency

* Automate manual document checking processes
* Reduce administrative overhead
* Streamline user re-verification workflows


# Document subtypes
Source: https://docs.didit.me/core-technology/id-verification/document-subtypes-id-verification

Every document_subtype code Didit's ID verification report can return, how the naming pattern works, and how to tell a commercial driver's license apart from a standard one.

`document_subtype` on the [ID verification report](/core-technology/id-verification/report-id-verification) identifies the specific document variant Didit recognized — for example a Queensland driver's licence versus a generic driver's licence, or a US Commercial Driver's License versus a standard one. This page enumerates every value the field can return.

<Note>
  Your own workflow only accepts a subset of these — whatever you selected in the workflow's document-settings step. Retrieve the exact accepted list for your workflow with the Management API's workflow-retrieve endpoint (`documents_allowed` on the OCR node) rather than assuming every value below is enabled for you.
</Note>

## Naming pattern

Every `document_subtype` value is one of two shapes:

* **Bare category** — `{CATEGORY}`, for documents Didit does not need to distinguish by region (most passports, most national IDs), for example `PASSPORT_GENERIC`, `ID_CARD_GENERIC`.
* **Region-prefixed** — `{REGION}_{CATEGORY}`, for documents whose format or classification genuinely differs by state, province, or territory, for example `QUEENSLAND_DRIVER_LICENSE_GENERIC` (Australia) or `CALIFORNIA_COMMERCIAL_DL` (United States). The region prefix is the issuing state/province name, upper-cased with spaces replaced by underscores.

A document only gets a region-prefixed subtype when Didit's document registry carries a distinct, separately classified variant for that region. The absence of a region-prefixed variant does not mean the document type doesn't exist in that region — it means Didit currently reports it under the country-level bare category instead (see the CDL caveat below for a concrete example).

## All subtype values

The table below is the full enumeration of `document_subtype` values the report can return, grouped by the `document_type` family. It already includes the region-prefixed variants — for example both `DRIVER_LICENSE_GENERIC` (most countries) and `CALIFORNIA_DRIVER_LICENSE_GENERIC` appear as distinct rows under Driver's License.

A bare-category code is not unique to one country — it's shared by every country whose registry entry for that document has no region-specific variant. `ID_CARD_GENERIC`, for instance, covers national ID cards for roughly 170 countries. Only look up a code by its `document_type` grouping and (when present) its region prefix, never by assuming a code maps to a single country.

<DocumentSubtypeCategoriesTable />

## US driver's licenses: standard vs. commercial (CDL)

`document_type` is `"Driver's License"` for both a standard driver's license and a Commercial Driver's License (CDL) — it never distinguishes them. The distinction lives entirely in `document_subtype`.

**In 48 of the 51 US states and territories Didit classifies, a CDL gets its own `{STATE}_COMMERCIAL_DL` subtype, distinct from that state's `{STATE}_DRIVER_LICENSE_GENERIC`.** Treating `document_subtype` ending in `_COMMERCIAL_DL` as "this is a CDL" is a reliable signal in those states.

<Warning>
  **Alaska, the District of Columbia, and Hawaii do not currently have a distinct CDL subtype.** A CDL from one of these three jurisdictions is reported under that jurisdiction's standard `_DRIVER_LICENSE_GENERIC` subtype — indistinguishable from a non-commercial license by `document_subtype` alone. If you need airtight CDL detection for these three jurisdictions specifically, [contact us](mailto:support@didit.me) to register the missing document variants, or apply an out-of-band control (for example, requiring the driver to separately supply their CDL/DOT number for verification).
</Warning>

<UsDriverLicenseSubtypesTable />

### `extra_fields.dl_categories` is not a reliable CDL signal

Some US licenses also produce `extra_fields.dl_categories` — a list of the class letters (`A`, `B`, `C`, …) printed on the card, read via OCR. **Do not use this as your CDL signal.** Today this field is populated for only a small minority of US driver's license configurations, class-letter meanings vary by state and are not normalized against a commercial/non-commercial semantic, and endorsement or restriction codes (which is where "commercial" is actually marked on many licenses) are not currently exposed on the report at all. `document_subtype` is the only structured, reliable signal for the standard-vs-commercial distinction today.

## Staying in sync

New `document_type` families are announced in the monthly changelog when they ship. `document_subtype` additions — a new region variant of an existing document type, for example — are not currently announced individually; Didit's document registry grows continuously as new document formats are onboarded. There is no version number on the webhook payload for this list.

If your integration needs to detect a subtype it has never seen before rather than assuming the set is fixed, treat any `document_subtype` value your code doesn't recognize as "unclassified, review manually" rather than erroring, and periodically re-check this page or your workflow's accepted-subtype list via the Management API.

## Related

* [ID verification report](/core-technology/id-verification/report-id-verification) — the `document_type` / `document_subtype` fields in context.
* [Supported ID documents](/core-technology/id-verification/supported-documents-id-verification) — countries and document types Didit supports.
* [Data models — ID verification](/reference/data-models#id-verification) — canonical field schema.


# Non-Document Lookup
Source: https://docs.didit.me/core-technology/id-verification/non-doc-lookup

Verify without a document: the user types their national ID number and a few details, checked against the authoritative source named for that country.

Non-doc lookup is one of the three [ID Verification methods](/core-technology/id-verification/verification-methods). Instead of photographing a document, the user types their national ID number plus a few personal details, and Didit checks them against the authoritative source for that country.

The result carries the assurance tier `data_match`: the details the user gave matched a record that source holds. No document was inspected, so nothing about a document's authenticity is being claimed.

## Which source is queried

Most countries are a government register — the Department of Home Affairs in South Africa, RENAPER in Argentina, UIDAI in India, the CPR register in Denmark. **Some are not.** In Canada, France, Indonesia, the Netherlands, Norway, Singapore, the United Kingdom and the United States the authoritative record Didit can reach is a credit-bureau, financial-services, utility or residential-records file rather than a state register.

That distinction is not cosmetic. It changes what the match proves, which consent regime the query runs under, and what you can tell a regulator about provenance, so this page never generalises: the **Source queried** column below names the exact source for every country, and it is the only statement of provenance to rely on. Read it before you enable a country.

<Note>
  The end user never sees the source name. It is on the session payload (`id_lookup.source`), in the console and in exports, for you and your auditors.
</Note>

## What the user does

1. Picks their country in the ID step.
2. Types the fields that country asks for — always the identifier, usually a name, sometimes a date of birth or an address.
3. Where the source returns a portrait, takes a selfie.
4. Gets a result: verified and moved on, asked to correct the number, retried, sent to document capture, or declined.

The whole step is typing and, for four countries, one selfie. There is no upload, no camera framing and no document at all.

## Sources that return a portrait

Four sources return the person's photograph: **South Africa**, **Nigeria**, **Argentina** and **Panama** — all four government registers. For those countries the user is asked for a selfie, [passive liveness](/core-technology/liveness/overview) runs on it, and it is face-matched to the registry portrait. All three happen inside the lookup and inside the lookup price — there is no separate Liveness or Face Match charge.

Because the lookup already proved a live person matching the register's photograph (all four are government registers), the country's `skip_liveness_and_face_match` switch (on by default) lets the workflow skip its own Liveness and Face Match steps after a match. Turn it off to run them anyway.

Every other source returns data only. There is no portrait to compare against, so no selfie is taken and the switch is normalised off on save. Add [Liveness](/core-technology/liveness/overview) and [Face Match](/core-technology/face-match/overview) as their own workflow steps if a biometric check matters in those countries — Face Match then needs a portrait from somewhere else in the workflow.

## Coverage and pricing

Prices below are public retail USD per answered attempt, checked against the anonymous Database Validation pricing feed on September 7, 2026. They use the services configured for the country. A price is not a production-launch announcement: enable only the methods your application catalog offers. The existing availability snapshot is retained separately from this price refresh.

For a country using multiple sources, the table shows their sum when all answer. An answered attempt charges only its billable source responses; a source that did not answer is excluded. Nigeria uses **NIN or BVN**, not their sum. Custom contract rates can differ and are shown in your console. These are ID-step lookup prices, not a quote for every other Database Validation service offered in that country.

| Country            | USD / attempt         | Code  | Source queried                                         | Availability | Selfie, liveness and face match | Consent regime            |
| ------------------ | --------------------- | ----- | ------------------------------------------------------ | ------------ | ------------------------------- | ------------------------- |
| Argentina          | \$0.20                | `ARG` | RENAPER                                                | Available    | Included in the lookup          | Ley 25.326                |
| Bolivia            | \$0.20                | `BOL` | SEGIP                                                  | Available    | Not applicable — data only      | —                         |
| Brazil             | \$0.20                | `BRA` | Receita Federal                                        | Available    | Not applicable — data only      | LGPD                      |
| Cambodia           | \$0.35                | `KHM` | Ministry of Interior voter register                    | Available    | Not applicable — data only      | Explicit consent required |
| Canada             | \$3.95                | `CAN` | Canadian credit bureau records (FINTRAC dual-process)  | Available    | Not applicable — data only      | PIPEDA                    |
| Chile              | \$0.20                | `CHL` | Servicio de Registro Civil e Identificación            | Available    | Not applicable — data only      | —                         |
| China              | \$0.30                | `CHN` | NCIIC (National Citizen Identity Information Center)   | Available    | Not applicable — data only      | Explicit consent required |
| Colombia           | \$0.20                | `COL` | Registraduría General de la Nación / ANI               | Available    | Not applicable — data only      | —                         |
| Costa Rica         | \$0.20                | `CRI` | Tribunal Supremo de Elecciones                         | Available    | Not applicable — data only      | —                         |
| Denmark            | \$1.39                | `DNK` | CPR register                                           | Available    | Not applicable — data only      | —                         |
| Dominican Republic | \$0.05                | `DOM` | Junta Central Electoral                                | Available    | Not applicable — data only      | —                         |
| Ecuador            | \$0.20                | `ECU` | Registro Civil del Ecuador                             | Available    | Not applicable — data only      | —                         |
| El Salvador        | \$0.20                | `SLV` | RNPN                                                   | Available    | Not applicable — data only      | —                         |
| Finland            | \$2.10                | `FIN` | DVV population register                                | Available    | Not applicable — data only      | Explicit consent required |
| France             | \$1.54                | `FRA` | French residential and utility records                 | Available    | Not applicable — data only      | GDPR                      |
| Guatemala          | \$0.20                | `GTM` | SAT                                                    | Available    | Not applicable — data only      | —                         |
| Honduras           | \$0.20                | `HND` | CNE                                                    | Available    | Not applicable — data only      | —                         |
| India              | \$0.25                | `IND` | UIDAI (Aadhaar)                                        | Available    | Not applicable — data only      | Aadhaar consent           |
| Indonesia          | \$0.35                | `IDN` | Indonesian population register via residential records | Available    | Not applicable — data only      | UU PDP                    |
| Kenya              | \$3.15                | `KEN` | IPRS (Integrated Population Registration System)       | Available    | Not applicable — data only      | —                         |
| Malaysia           | \$0.35                | `MYS` | JPN (National Registration Department)                 | Available    | Not applicable — data only      | Explicit consent required |
| Mexico             | \$0.20                | `MEX` | RENAPO                                                 | Available    | Not applicable — data only      | —                         |
| Netherlands        | \$0.90                | `NLD` | Dutch residential records                              | Available    | Not applicable — data only      | GDPR                      |
| Nigeria            | NIN $0.20 / BVN $0.35 | `NGA` | NIMC / NIBSS                                           | Available    | Included in the lookup          | NDPR                      |
| Norway             | \$2.42                | `NOR` | Norwegian residential records                          | Available    | Not applicable — data only      | GDPR                      |
| Panama             | \$0.75                | `PAN` | Tribunal Electoral / SIB                               | Available    | Included in the lookup          | —                         |
| Paraguay           | \$0.20                | `PRY` | Registro del Estado Civil                              | Available    | Not applicable — data only      | —                         |
| Peru               | \$0.20                | `PER` | RENIEC                                                 | Available    | Not applicable — data only      | —                         |
| Singapore          | \$4.30                | `SGP` | Singapore credit bureau and utility records            | Available    | Not applicable — data only      | PDPA                      |
| South Africa       | \$2.20                | `ZAF` | Department of Home Affairs                             | Available    | Included in the lookup          | POPIA                     |
| Sweden             | \$0.35                | `SWE` | Skatteverket population register                       | Available    | Not applicable — data only      | —                         |
| Thailand           | \$0.35                | `THA` | DOPA civil registration                                | Available    | Not applicable — data only      | Explicit consent required |
| United Kingdom     | \$1.85                | `GBR` | UK credit bureau and financial services records        | Available    | Not applicable — data only      | UK GDPR                   |
| United States      | \$0.27                | `USA` | US credit bureau and financial services records        | Available    | Not applicable — data only      | GLBA permissible purpose  |
| Uruguay            | \$0.20                | `URY` | Dirección Nacional del Registro de Estado Civil        | Available    | Not applicable — data only      | —                         |
| Venezuela          | \$0.20                | `VEN` | CNE                                                    | Available    | Not applicable — data only      | —                         |

<Note>
  Availability comes from the capability catalog the backend serves; the API rejects a workflow that enables a lookup the catalog does not mark `Available` for that country. Prices marked **On request** are not published yet — non-document methods are priced per country and quoted by your account team.
</Note>

## Format rules

Identifier fields carry a client-side format check before anything is sent — a length, a digit-only rule, a checksum or a pattern, depending on the country. A number that fails it never reaches the source, which means it is **never billed and never counted against `max_attempts`**: the user is shown a country-specific message and asked to correct it.

The per-country tables below list the rule for each field. A field with no rule is free text — a name, a date the interface collects, or an image capture.

Get the format right in your own pre-fill and you spend nothing on typos.

## Per-country fields

#### Argentina (`ARG`)

Source: **RENAPER**. The source returns a portrait, so a selfie is taken, passive liveness runs on it and it is face-matched to that portrait inside the lookup.

| Asked for     | Field key         | Required | Format check                |
| ------------- | ----------------- | -------- | --------------------------- |
| Argentine DNI | `document_number` | Yes      | 7-8 characters; digits only |
| Selfie        | `selfie`          | Yes      | —                           |
| Gender        | `gender`          | Yes      | One of `M`, `F`             |

| Returned          | Field key           | Required |
| ----------------- | ------------------- | -------- |
| Full name         | `full_name`         | Yes      |
| Date of birth     | `date_of_birth`     | Yes      |
| Registry portrait | `registry_portrait` | No       |
| Gender            | `gender`            | No       |
| Address           | `address`           | No       |
| Record status     | `record_status`     | No       |
| Source name       | `source_name`       | No       |
| Queried at        | `queried_at`        | No       |

#### Bolivia (`BOL`)

Source: **SEGIP**. This source returns data only, so there is no portrait to face-match against.

| Asked for     | Field key         | Required | Format check                 |
| ------------- | ----------------- | -------- | ---------------------------- |
| Bolivian CI   | `document_number` | Yes      | 6-10 characters; digits only |
| Date of birth | `date_of_birth`   | Yes      | —                            |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### Brazil (`BRA`)

Source: **Receita Federal**. This source returns data only, so there is no portrait to face-match against.

| Asked for     | Field key       | Required | Format check                       |
| ------------- | --------------- | -------- | ---------------------------------- |
| Brazilian CPF | `tax_number`    | Yes      | Exactly 11 characters; digits only |
| Date of birth | `date_of_birth` | Yes      | —                                  |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### Cambodia (`KHM`)

Source: **Ministry of Interior voter register**. This source returns data only, so there is no portrait to face-match against.

| Asked for       | Field key       | Required | Format check    |             |
| --------------- | --------------- | -------- | --------------- | ----------- |
| First name      | `first_name`    | Yes      | —               |             |
| Last name       | `last_name`     | Yes      | —               |             |
| Date of birth   | `date_of_birth` | Yes      | —               |             |
| Voter ID number | `voter_id`      | Yes      | Pattern \`(?:\d | \d-\d-\d)\` |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### Canada (`CAN`)

Source: **Canadian credit bureau records (FINTRAC dual-process)**. This source returns data only, so there is no portrait to face-match against.

| Asked for     | Field key       | Required | Format check |
| ------------- | --------------- | -------- | ------------ |
| First name    | `first_name`    | Yes      | —            |
| Last name     | `last_name`     | Yes      | —            |
| Date of birth | `date_of_birth` | Yes      | —            |
| Home address  | `address`       | Yes      | —            |

| Returned                                      | Field key             | Required |
| --------------------------------------------- | --------------------- | -------- |
| Name match (exact, partial or none)           | `name_match`          | Yes      |
| Date-of-birth match                           | `date_of_birth_match` | Yes      |
| Address match                                 | `address_match`       | Yes      |
| Number of sources that confirmed the identity | `sources_confirming`  | Yes      |
| Source name                                   | `source_name`         | No       |
| Queried at                                    | `queried_at`          | No       |

#### Chile (`CHL`)

Source: **Servicio de Registro Civil e Identificación**. This source returns data only, so there is no portrait to face-match against.

| Asked for   | Field key         | Required | Format check    |
| ----------- | ----------------- | -------- | --------------- |
| Chilean RUT | `personal_number` | Yes      | 8-12 characters |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### China (`CHN`)

Source: **NCIIC (National Citizen Identity Information Center)**. This source returns data only, so there is no portrait to face-match against.

| Asked for          | Field key       | Required | Format check  |              |
| ------------------ | --------------- | -------- | ------------- | ------------ |
| Full name          | `full_name`     | Yes      | —             |              |
| Date of birth      | `date_of_birth` | Yes      | —             |              |
| National ID number | `national_id`   | Yes      | Pattern \`(\d | \d\[\dXx])\` |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### Colombia (`COL`)

Source: **Registraduría General de la Nación / ANI**. This source returns data only, so there is no portrait to face-match against.

| Asked for        | Field key         | Required | Format check                 |
| ---------------- | ----------------- | -------- | ---------------------------- |
| Colombian Cédula | `personal_number` | Yes      | 6-11 characters; digits only |
| Date of issue    | `date_of_issue`   | Yes      | —                            |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### Costa Rica (`CRI`)

Source: **Tribunal Supremo de Elecciones**. This source returns data only, so there is no portrait to face-match against.

| Asked for          | Field key         | Required | Format check                 |
| ------------------ | ----------------- | -------- | ---------------------------- |
| Costa Rican Cédula | `personal_number` | Yes      | 9-12 characters; digits only |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### Denmark (`DNK`)

Source: **CPR register**. This source returns data only, so there is no portrait to face-match against.

| Asked for          | Field key       | Required | Format check           |
| ------------------ | --------------- | -------- | ---------------------- |
| First name         | `first_name`    | Yes      | —                      |
| Last name          | `last_name`     | Yes      | —                      |
| Date of birth      | `date_of_birth` | Yes      | —                      |
| National ID number | `national_id`   | Yes      | Pattern `\d{6}-?\d{4}` |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### Dominican Republic (`DOM`)

Source: **Junta Central Electoral**. This source returns data only, so there is no portrait to face-match against.

| Asked for        | Field key         | Required | Format check                       |
| ---------------- | ----------------- | -------- | ---------------------------------- |
| Dominican Cédula | `personal_number` | Yes      | Exactly 11 characters; digits only |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### Ecuador (`ECU`)

Source: **Registro Civil del Ecuador**. This source returns data only, so there is no portrait to face-match against.

| Asked for         | Field key         | Required | Format check                       |
| ----------------- | ----------------- | -------- | ---------------------------------- |
| Ecuadorian Cédula | `personal_number` | Yes      | Exactly 10 characters; digits only |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### El Salvador (`SLV`)

Source: **RNPN**. This source returns data only, so there is no portrait to face-match against.

| Asked for      | Field key         | Required | Format check                      |
| -------------- | ----------------- | -------- | --------------------------------- |
| Salvadoran DUI | `document_number` | Yes      | Exactly 9 characters; digits only |
| Date of birth  | `date_of_birth`   | Yes      | —                                 |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### Finland (`FIN`)

Source: **DVV population register**. This source returns data only, so there is no portrait to face-match against.

| Asked for          | Field key       | Required | Format check                     |                  |
| ------------------ | --------------- | -------- | -------------------------------- | ---------------- |
| First name         | `first_name`    | Yes      | —                                |                  |
| Last name          | `last_name`     | Yes      | —                                |                  |
| Date of birth      | `date_of_birth` | Yes      | —                                |                  |
| National ID number | `national_id`   | Yes      | Pattern \`(?:\d\[-+A]\d\[0-9A-Z] | \d\d\[0-9A-Z])\` |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### France (`FRA`)

Source: **French residential and utility records**. This source returns data only, so there is no portrait to face-match against.

| Asked for     | Field key       | Required | Format check |
| ------------- | --------------- | -------- | ------------ |
| First name    | `first_name`    | Yes      | —            |
| Last name     | `last_name`     | Yes      | —            |
| Date of birth | `date_of_birth` | Yes      | —            |
| Home address  | `address`       | Yes      | —            |

| Returned                                      | Field key             | Required |
| --------------------------------------------- | --------------------- | -------- |
| Name match (exact, partial or none)           | `name_match`          | Yes      |
| Date-of-birth match                           | `date_of_birth_match` | Yes      |
| Address match                                 | `address_match`       | Yes      |
| Number of sources that confirmed the identity | `sources_confirming`  | Yes      |
| Source name                                   | `source_name`         | No       |
| Queried at                                    | `queried_at`          | No       |

#### Guatemala (`GTM`)

Source: **SAT**. This source returns data only, so there is no portrait to face-match against.

| Asked for      | Field key         | Required | Format check                       |
| -------------- | ----------------- | -------- | ---------------------------------- |
| Guatemalan DPI | `document_number` | Yes      | Exactly 13 characters; digits only |
| Date of birth  | `date_of_birth`   | Yes      | —                                  |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### Honduras (`HND`)

Source: **CNE**. This source returns data only, so there is no portrait to face-match against.

| Asked for    | Field key         | Required | Format check                       |
| ------------ | ----------------- | -------- | ---------------------------------- |
| Honduran DNI | `document_number` | Yes      | Exactly 13 characters; digits only |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### India (`IND`)

Source: **UIDAI (Aadhaar)**. This source returns data only, so there is no portrait to face-match against.

| Asked for          | Field key         | Required | Format check                             |
| ------------------ | ----------------- | -------- | ---------------------------------------- |
| Full name          | `full_name`       | Yes      | —                                        |
| Date of birth      | `date_of_birth`   | Yes      | —                                        |
| National ID number | `personal_number` | Yes      | Exactly 12 characters; digits only       |
| PAN                | `pan`             | Yes      | Pattern `[A-Z]{5}\d{4}[A-Z]`; uppercased |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### Indonesia (`IDN`)

Source: **Indonesian population register via residential records**. This source returns data only, so there is no portrait to face-match against.

| Asked for       | Field key       | Required | Format check                       |
| --------------- | --------------- | -------- | ---------------------------------- |
| First name      | `first_name`    | Yes      | —                                  |
| Last name       | `last_name`     | Yes      | —                                  |
| Date of birth   | `date_of_birth` | Yes      | —                                  |
| Home address    | `address`       | Yes      | —                                  |
| NIK (16 digits) | `national_id`   | Yes      | Exactly 16 characters; digits only |

| Returned                                      | Field key             | Required |
| --------------------------------------------- | --------------------- | -------- |
| Name match (exact, partial or none)           | `name_match`          | Yes      |
| Date-of-birth match                           | `date_of_birth_match` | Yes      |
| Address match                                 | `address_match`       | Yes      |
| Number of sources that confirmed the identity | `sources_confirming`  | Yes      |
| Source name                                   | `source_name`         | No       |
| Queried at                                    | `queried_at`          | No       |

#### Kenya (`KEN`)

Source: **IPRS (Integrated Population Registration System)**. This source returns data only, so there is no portrait to face-match against.

| Asked for          | Field key       | Required | Format check      |
| ------------------ | --------------- | -------- | ----------------- |
| First name         | `first_name`    | Yes      | —                 |
| Last name          | `last_name`     | Yes      | —                 |
| Date of birth      | `date_of_birth` | Yes      | —                 |
| National ID number | `national_id`   | Yes      | Pattern `\d{8,9}` |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### Malaysia (`MYS`)

Source: **JPN (National Registration Department)**. This source returns data only, so there is no portrait to face-match against.

| Asked for          | Field key       | Required | Format check                       |
| ------------------ | --------------- | -------- | ---------------------------------- |
| Full name          | `full_name`     | Yes      | —                                  |
| Date of birth      | `date_of_birth` | Yes      | —                                  |
| National ID number | `national_id`   | Yes      | Exactly 12 characters; digits only |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### Mexico (`MEX`)

Source: **RENAPO**. This source returns data only, so there is no portrait to face-match against.

| Asked for    | Field key         | Required | Format check          |
| ------------ | ----------------- | -------- | --------------------- |
| Mexican CURP | `personal_number` | Yes      | Exactly 18 characters |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### Netherlands (`NLD`)

Source: **Dutch residential records**. This source returns data only, so there is no portrait to face-match against.

| Asked for     | Field key       | Required | Format check |
| ------------- | --------------- | -------- | ------------ |
| First name    | `first_name`    | Yes      | —            |
| Last name     | `last_name`     | Yes      | —            |
| Date of birth | `date_of_birth` | Yes      | —            |
| Home address  | `address`       | Yes      | —            |

| Returned                                      | Field key             | Required |
| --------------------------------------------- | --------------------- | -------- |
| Name match (exact, partial or none)           | `name_match`          | Yes      |
| Date-of-birth match                           | `date_of_birth_match` | Yes      |
| Address match                                 | `address_match`       | Yes      |
| Number of sources that confirmed the identity | `sources_confirming`  | Yes      |
| Source name                                   | `source_name`         | No       |
| Queried at                                    | `queried_at`          | No       |

#### Nigeria (`NGA`)

Source: **NIMC / NIBSS**. The source returns a portrait, so a selfie is taken, passive liveness runs on it and it is face-matched to that portrait inside the lookup.

| Asked for         | Field key         | Required | Format check                       |
| ----------------- | ----------------- | -------- | ---------------------------------- |
| ID type           | `identifier_type` | Yes      | One of `NIN`, `BVN`                |
| The number itself | `identifier`      | Yes      | Exactly 11 characters; digits only |
| First name        | `first_name`      | Yes      | —                                  |
| Last name         | `last_name`       | Yes      | —                                  |
| Selfie            | `selfie`          | Yes      | —                                  |

| Returned              | Field key             | Required |
| --------------------- | --------------------- | -------- |
| Full name             | `full_name`           | Yes      |
| Date of birth         | `date_of_birth`       | Yes      |
| Gender                | `gender`              | No       |
| State of origin       | `state_of_origin`     | No       |
| Phone number (masked) | `phone_number_masked` | No       |
| Registry portrait     | `registry_portrait`   | No       |
| Source name           | `source_name`         | No       |
| Queried at            | `queried_at`          | No       |

#### Norway (`NOR`)

Source: **Norwegian residential records**. This source returns data only, so there is no portrait to face-match against.

| Asked for     | Field key       | Required | Format check |
| ------------- | --------------- | -------- | ------------ |
| First name    | `first_name`    | Yes      | —            |
| Last name     | `last_name`     | Yes      | —            |
| Date of birth | `date_of_birth` | Yes      | —            |
| Home address  | `address`       | Yes      | —            |

| Returned                                      | Field key             | Required |
| --------------------------------------------- | --------------------- | -------- |
| Name match (exact, partial or none)           | `name_match`          | Yes      |
| Date-of-birth match                           | `date_of_birth_match` | Yes      |
| Address match                                 | `address_match`       | Yes      |
| Number of sources that confirmed the identity | `sources_confirming`  | Yes      |
| Source name                                   | `source_name`         | No       |
| Queried at                                    | `queried_at`          | No       |

#### Panama (`PAN`)

Source: **Tribunal Electoral / SIB**. The source returns a portrait, so a selfie is taken, passive liveness runs on it and it is face-matched to that portrait inside the lookup.

| Asked for         | Field key         | Required | Format check              |       |    |   |                                                 |
| ----------------- | ----------------- | -------- | ------------------------- | ----- | -- | - | ----------------------------------------------- |
| Panamanian Cédula | `personal_number` | Yes      | Pattern \`(?:\d(?:-?(?:AV | PI))? | PE | E | N)\[\d-]\*\`; at least 5 characters; uppercased |
| Selfie            | `selfie`          | Yes      | —                         |       |    |   |                                                 |

| Returned          | Field key           | Required |
| ----------------- | ------------------- | -------- |
| Full name         | `full_name`         | Yes      |
| Date of birth     | `date_of_birth`     | Yes      |
| Registry portrait | `registry_portrait` | No       |
| Gender            | `gender`            | No       |
| Address           | `address`           | No       |
| Record status     | `record_status`     | No       |
| Source name       | `source_name`       | No       |
| Queried at        | `queried_at`        | No       |

#### Paraguay (`PRY`)

Source: **Registro del Estado Civil**. This source returns data only, so there is no portrait to face-match against.

| Asked for     | Field key         | Required | Format check                 |
| ------------- | ----------------- | -------- | ---------------------------- |
| Paraguayan CI | `document_number` | Yes      | 6-10 characters; digits only |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### Peru (`PER`)

Source: **RENIEC**. This source returns data only, so there is no portrait to face-match against.

| Asked for    | Field key         | Required | Format check                      |
| ------------ | ----------------- | -------- | --------------------------------- |
| Peruvian DNI | `personal_number` | Yes      | Exactly 8 characters; digits only |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### Singapore (`SGP`)

Source: **Singapore credit bureau and utility records**. This source returns data only, so there is no portrait to face-match against.

| Asked for     | Field key       | Required | Format check                            |
| ------------- | --------------- | -------- | --------------------------------------- |
| First name    | `first_name`    | Yes      | —                                       |
| Last name     | `last_name`     | Yes      | —                                       |
| Date of birth | `date_of_birth` | Yes      | —                                       |
| Home address  | `address`       | Yes      | —                                       |
| NRIC / FIN    | `national_id`   | Yes      | Pattern `[STFGM]\d{7}[A-Z]`; uppercased |

| Returned                                      | Field key             | Required |
| --------------------------------------------- | --------------------- | -------- |
| Name match (exact, partial or none)           | `name_match`          | Yes      |
| Date-of-birth match                           | `date_of_birth_match` | Yes      |
| Address match                                 | `address_match`       | Yes      |
| Number of sources that confirmed the identity | `sources_confirming`  | Yes      |
| Source name                                   | `source_name`         | No       |
| Queried at                                    | `queried_at`          | No       |

#### South Africa (`ZAF`)

Source: **Department of Home Affairs**. The source returns a portrait, so a selfie is taken, passive liveness runs on it and it is face-matched to that portrait inside the lookup.

| Asked for          | Field key     | Required | Format check                                      |
| ------------------ | ------------- | -------- | ------------------------------------------------- |
| 13-digit ID number | `national_id` | Yes      | Exactly 13 characters; digits only; LUHN checksum |
| First name         | `first_name`  | Yes      | —                                                 |
| Last name          | `last_name`   | Yes      | —                                                 |
| Selfie             | `selfie`      | Yes      | —                                                 |

| Returned                               | Field key           | Required |
| -------------------------------------- | ------------------- | -------- |
| Full name                              | `full_name`         | Yes      |
| Date of birth                          | `date_of_birth`     | Yes      |
| Gender                                 | `gender`            | No       |
| Citizenship                            | `citizenship`       | No       |
| ID status (valid, deceased or blocked) | `id_status`         | Yes      |
| Registry portrait                      | `registry_portrait` | No       |
| Source name                            | `source_name`       | No       |
| Queried at                             | `queried_at`        | No       |

#### Sweden (`SWE`)

Source: **Skatteverket population register**. This source returns data only, so there is no portrait to face-match against.

| Asked for          | Field key       | Required | Format check  |                    |
| ------------------ | --------------- | -------- | ------------- | ------------------ |
| First name         | `first_name`    | Yes      | —             |                    |
| Last name          | `last_name`     | Yes      | —             |                    |
| Date of birth      | `date_of_birth` | Yes      | —             |                    |
| National ID number | `national_id`   | Yes      | Pattern \`(\d | \d)\`; digits only |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### Thailand (`THA`)

Source: **DOPA civil registration**. This source returns data only, so there is no portrait to face-match against.

| Asked for               | Field key       | Required | Format check                       |
| ----------------------- | --------------- | -------- | ---------------------------------- |
| First name              | `first_name`    | Yes      | —                                  |
| Last name               | `last_name`     | Yes      | —                                  |
| Date of birth           | `date_of_birth` | Yes      | —                                  |
| Thai national ID number | `national_id`   | Yes      | Exactly 13 characters; digits only |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### United Kingdom (`GBR`)

Source: **UK credit bureau and financial services records**. This source returns data only, so there is no portrait to face-match against.

| Asked for     | Field key       | Required | Format check |
| ------------- | --------------- | -------- | ------------ |
| First name    | `first_name`    | Yes      | —            |
| Last name     | `last_name`     | Yes      | —            |
| Date of birth | `date_of_birth` | Yes      | —            |
| Home address  | `address`       | Yes      | —            |

| Returned                                      | Field key             | Required |
| --------------------------------------------- | --------------------- | -------- |
| Name match (exact, partial or none)           | `name_match`          | Yes      |
| Date-of-birth match                           | `date_of_birth_match` | Yes      |
| Address match                                 | `address_match`       | Yes      |
| Number of sources that confirmed the identity | `sources_confirming`  | Yes      |
| Source name                                   | `source_name`         | No       |
| Queried at                                    | `queried_at`          | No       |

#### United States (`USA`)

Source: **US credit bureau and financial services records**. This source returns data only, so there is no portrait to face-match against.

| Asked for                               | Field key       | Required | Format check                |
| --------------------------------------- | --------------- | -------- | --------------------------- |
| First name                              | `first_name`    | Yes      | —                           |
| Last name                               | `last_name`     | Yes      | —                           |
| Date of birth                           | `date_of_birth` | Yes      | —                           |
| Home address                            | `address`       | Yes      | —                           |
| Social Security number (last 4 or full) | `ssn`           | No       | 4-9 characters; digits only |

| Returned                                      | Field key             | Required |
| --------------------------------------------- | --------------------- | -------- |
| Name match (exact, partial or none)           | `name_match`          | Yes      |
| Date-of-birth match                           | `date_of_birth_match` | Yes      |
| Address match                                 | `address_match`       | Yes      |
| Number of sources that confirmed the identity | `sources_confirming`  | Yes      |
| Source name                                   | `source_name`         | No       |
| Queried at                                    | `queried_at`          | No       |

#### Uruguay (`URY`)

Source: **Dirección Nacional del Registro de Estado Civil**. This source returns data only, so there is no portrait to face-match against.

| Asked for     | Field key         | Required | Format check                |
| ------------- | ----------------- | -------- | --------------------------- |
| Uruguayan CI  | `personal_number` | Yes      | 7-9 characters; digits only |
| Date of birth | `date_of_birth`   | Yes      | —                           |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

#### Venezuela (`VEN`)

Source: **CNE**. This source returns data only, so there is no portrait to face-match against.

| Asked for         | Field key         | Required | Format check    |
| ----------------- | ----------------- | -------- | --------------- |
| Venezuelan Cédula | `document_number` | Yes      | 7-12 characters |

| Returned      | Field key       | Required |
| ------------- | --------------- | -------- |
| Full name     | `full_name`     | Yes      |
| Date of birth | `date_of_birth` | Yes      |
| Gender        | `gender`        | No       |
| Address       | `address`       | No       |
| Record status | `record_status` | No       |
| Source name   | `source_name`   | No       |
| Queried at    | `queried_at`    | No       |

## Consent

Several sources may only be queried with the person's explicit consent, and the consent regime differs by country — POPIA in South Africa, NDPR in Nigeria, LGPD in Brazil, UK GDPR in the United Kingdom, GLBA permissible purpose in the United States, and so on. The regime that applies to each source is in the coverage table above.

You are the controller for that consent. Collect it in your own flow, or add a [questionnaire](/core-technology/questionnaires/overview) step before the ID step, and keep the record — Didit runs the query you asked for and does not judge whether you had the right to ask for it. Where a country's source requires consent wording of its own, the verification UI shows it before the lookup runs.

## Attempts, outcomes and billing

Each answered lookup counts as one attempt. `max_attempts` is 1 to 5, default 1.

| Outcome           | Counts as an attempt | Billed | What happens next                                                                   |
| ----------------- | -------------------- | ------ | ----------------------------------------------------------------------------------- |
| `match`           | Yes                  | Yes    | The register's record becomes the ID Verification result and the workflow moves on. |
| `partial_match`   | Yes                  | Yes    | Retry while attempts remain, then `on_partial_match`.                               |
| `no_match`        | Yes                  | Yes    | Retry while attempts remain, then `on_no_match`.                                    |
| `provider_error`  | No                   | No     | Retry, then `on_provider_error`.                                                    |
| `format_rejected` | No                   | No     | The user is asked to correct the field. It never reached the register.              |

Each billable answered attempt sums the retail rates of the services that answered with a match, partial match or no match. Retries are new attempts and can add another charge. An attempt that ends in a provider error is not billed. Format rejection is not billed.

The first 500 document-capture checks per organization each month do not cover lookup attempts. If lookup falls back to document capture, the completed document check is billed separately, subject to its remaining document allowance. Disabling fallback declines the session; it does not refund a completed lookup. Sandbox scenarios simulate outcomes without paid registry queries or usage charges.

## What lands on the session

A lookup that matched populates the ID Verification result the same way a document read would — name, date of birth and the national identifier — and adds an `id_lookup` evidence block:

```json theme={null}
{
  "node_id": "feature_ocr_1",
  "status": "Approved",
  "verification_method": "id_lookup",
  "assurance": "data_match",
  "wallet_provider": null,
  "fallback_from": null,
  "id_lookup": {
    "source": "Department of Home Affairs",
    "checked_at": "2026-09-04T09:12:44Z",
    "attempts": 1,
    "max_attempts": 2,
    "outcome": "match",
    "comparison": [
      { "field": "identification_number", "label": "ID number", "provided": "9106155043088", "record": "9106155043088", "result": "match" },
      { "field": "full_name", "label": "Full name", "provided": "Thabo Mokoena", "record": "Thabo Mokoena", "result": "match" },
      { "field": "date_of_birth", "label": "Date of birth", "provided": "1991-06-15", "record": "1991-06-15", "result": "match" }
    ],
    "registry_portrait": "https://<media-host>/registry_portrait.jpg",
    "face_match_score": 96.4,
    "source_errors": []
  },
  "wallet_verification": null
}
```

`comparison` carries one row per comparable field, with `result` of `match`, `partial` or `no_match`, so a reviewer can see exactly which field disagreed. The row names are normalised — `identification_number`, `full_name`, `date_of_birth`, `address` — not the country's request field keys, because a first name and a last name are compared as one name and every identifier alias is compared as one number.

The current staging response keeps source failures in a separate `source_errors` array. Its entries can contain `service_id`, `code`, `message`, `details` and `outcome_detail` when supplied. Treat these as query diagnostics, not identity mismatches. Earlier releases may represent source failures as `comparison` rows with `result: "error"`; confirm the contract deployed in your target environment.

`registry_portrait` and `face_match_score` are present only for the four sources that return a portrait and when the selected response fields retain the portrait.

Full field types are in the [ID verification data model](/reference/data-models#id-verification).

## Retention

The source record that produced a match is stored as the ID Verification result and follows your organization's [data retention](/console/data-retention) settings, exactly like a document read. Deleting a session deletes it; see [Delete session](/sessions-api/delete-session).

<Warning>
  The current staging implementation applies `id_lookup.response_fields` to comparison output, optional gender and retained registry portraits. Required identity fields remain part of the verification record. This is not a guarantee that every intermediate provider payload is excluded from processing. Production rollout has not been verified for this change; confirm the behavior in your target environment before relying on field selection for retention requirements.
</Warning>

## Related

* [ID Verification methods](/core-technology/id-verification/verification-methods) — the three methods, fallback and billing
* [Digital ID wallets](/core-technology/id-verification/digital-id-wallets) — the cryptographic method
* [Database Validation](/core-technology/database-validation/overview) — the standalone feature for checking a document you already captured against a source
* [Workflow feature configs](/management-api/workflows/feature-configs#ocr--id-verification) — the `methods` key reference


# ID Verification Overview
Source: https://docs.didit.me/core-technology/id-verification/overview

Verify identity documents across 220+ countries and 14,000+ types with AI OCR. Pay-per-call $0.15, 500 free/month, sub-2-second inference.

The Academy lesson on reading a verification result reaches ID verification at 3:47 and shows why authenticity checks come before the extracted data.

<VideoEmbed title="ID verification: authenticity before data — Didit Academy" />

Powered by cutting-edge AI, computer vision, and biometric technology, our solution ensures fast, accurate, and secure identity verification at scale. Designed to combat fraud, simplify compliance, and enhance user experience, Didit provides a robust and trustworthy platform that meets the highest industry standards.

<AgentPromptAccordion title="ID Verification Integration Prompt" />

<Frame>
  <img alt="Didit ID verification steps from document capture to AI-powered analysis and decision" />
</Frame>

<Steps>
  <Step title="Intelligent Capture" icon="camera">
    Effortlessly begin the verification process with our intuitive, AI-driven capture system. Users upload or photograph their ID documents with real-time assistance:

    * **Auto-detection** of document type and issuing country
    * **Real-time visual cues** for optimal positioning, lighting, and focus
    * **Automatic capture** when conditions are ideal — no manual retries needed
    * Supports **passports**, **driver's licenses**, **national ID cards**, and **residence permits**

    <Note>
      *Why it matters*: Our intelligent capture reduces user friction and ensures high-quality submissions on the first attempt, boosting conversion rates and trust.
    </Note>
  </Step>

  <Step title="Advanced Data Processing" icon="microchip-ai">
    Extract and validate identity data with unmatched precision.

    **Data Extraction** — State-of-the-art technology processes all key fields:

    | Capability           | Details                                                                              |
    | -------------------- | ------------------------------------------------------------------------------------ |
    | **Field extraction** | Full name, date of birth, document number, issue/expiry dates, nationality, and more |
    | **OCR**              | High-precision text recognition                                                      |
    | **MRZ parsing**      | Machine-Readable Zone decoding                                                       |
    | **Barcode decoding** | Automatic barcode data extraction                                                    |

    **Data Validation**:

    * Cross-references data between visual zones, MRZ, and barcodes for consistency
    * Cryptographic verification of issuer-signed barcodes, where the issuing authority publishes the certificates needed to check them. French national ID cards are covered today: their ANTS 2D-Doc barcode is verified against a signer certificate that chains to the ANTS trust list, so a barcode the authority did not sign is caught even when its contents look consistent
    * Format and pattern matching to detect anomalies
    * Real-time queries against government databases (where permitted) for authoritative verification

    <Note>
      *Why it matters*: Comprehensive data processing ensures accuracy and eliminates errors, giving you confidence in every verification.
    </Note>
  </Step>

  <Step title="Advanced Analysis" icon="shield-check">
    Our AI-powered system performs comprehensive checks to ensure document integrity and authenticity:

    * **Document authenticity** verification
    * **Tamper detection** and image integrity analysis
    * **Document liveness detection** to prevent fraud from:
      * Screen captures of digital documents
      * Photos of documents displayed on screens
      * Printed document copies
      * Manipulated documents with altered portraits
    * **Security feature validation** (holograms, watermarks, etc.)
    * **Template matching** against certified database
  </Step>

  <Step title="Seamless Results & Integration" icon="file-export">
    Get actionable insights instantly with flexible delivery options.

    **Real-Time Results**:

    * Immediate updates via an intuitive dashboard
    * Instant webhook notifications for automated workflows
    * RESTful API for seamless integration into your existing systems

    **Comprehensive Reporting**:

    * Detailed PDF reports with verification outcomes and evidence
    * Audit trails for compliance and record-keeping
    * Customizable options to align with your operational needs

    <Note>
      *Why it matters*: Fast, accessible results empower your team to act quickly while maintaining a secure, auditable process.
    </Note>
  </Step>
</Steps>

***

## Three ways to verify

A photographed document is one of three [ID Verification methods](/core-technology/id-verification/verification-methods). Per country you can also let people prove who they are without a document at all:

* **[Non-document lookup](/core-technology/id-verification/non-doc-lookup)** — the user types their national ID number plus a few personal details and we check them against a government register or another authoritative source, named per country. Where that source returns a portrait, a selfie, passive liveness and a face match are included.
* **[Digital ID wallets](/core-technology/id-verification/digital-id-wallets)** — the user signs in with a government or bank digital identity such as MitID, BankID or itsme, and the wallet shares a signed set of attributes.

Everything on this page describes document capture, which is unchanged: a workflow that says nothing about methods stays document capture only.

***

## Document Requirements

For optimal verification success, documents must meet these standards:

#### General Requirements

* Government-issued and valid within its configured validity period
* Physically intact (no damage, scratches, or stains obscuring details)
* All critical information (full name, date of birth, MRZ, etc.) clearly legible
* Consistent data across all submitted documents

#### Image Requirements

* Original, real-time photo (no screenshots, scans, or digital copies)
* Supported formats: JPG, JPEG, PNG, PDF
* Maximum file size: 5MB
* Full-color image with all document corners visible
* Free from glare, shadows, digital editing, or manipulation
* Physical documents required (digital IDs supported only in select regions where officially recognized)

## Additional Settings by Country & Document Type

Configure fine-grained rules per country and document type directly from the console. These controls let you tailor acceptance criteria and transcription preferences to your compliance needs.

<Frame>
  <img alt="Didit ID verification additional settings panel for per-country expiration and acceptance rules" />
</Frame>

* **Expiration mode**: Choose how to handle documents with past expiration dates.
  * **Reject expired**: If the document's expiration date is earlier than today, mark it as expired and reject.
  * **Allow expired**: Do not flag or block documents with a past expiration date.
* **Preferred character format**: Select how extracted names and fields should be normalized.
  * **Prefer Latin characters (A–Z)**: Example: "Mohammed"
  * **Prefer original script (non‑Latin)**: Example: "محمد"
* **Regional support & subtypes**: Enable documents by region and specify acceptable subtypes when a document type contains many variations.
  * Example: For United States driver's licenses, select the exact subtypes you accept (e.g., Arizona Commercial Driver License, Indiana Operator License (REAL ID), New York Enhanced Driver License, etc.).
  * Use the "Accepted subtypes" control to quickly include/exclude many variants (e.g., "128 selected").

> Tip: These settings apply per country and document type, so you can be strict in some markets while more permissive in others.

## Per-Country Age Restrictions

Enforce minimum and maximum age requirements on a per-country basis during ID verification. The system extracts the user's date of birth from the submitted document and checks it against the age limits configured for the document's issuing country.

### Configuration

Age restrictions are configured as a per-country table directly from the console:

| Column                     | Description                                                                                                                                                                                   |
| -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Country**                | The issuing country of the document (ISO 3166-1 alpha-3). Only countries enabled in your documents allowed list are shown.                                                                    |
| **Min Age**                | Minimum age required. Users younger than this value trigger the configured action (Decline or Review).                                                                                        |
| **Max Age**                | Maximum age allowed. Users older than this value trigger the configured action. Leave empty for no upper limit.                                                                               |
| **State/Region overrides** | For countries with sub-national age variation (e.g., United States, Mexico), open the settings icon to configure per-state minimum and maximum ages that override the country-level defaults. |

### Age of Majority Defaults

The console includes an **"Apply age of majority"** button that auto-fills each country's minimum age with the known legal age of majority (18 in most countries, with exceptions such as 19 in South Korea, 21 in the UAE, 20 in New Zealand, etc.). You can then adjust individual countries or add state-level overrides as needed.

### State/Region Overrides

Some countries have different legal age thresholds depending on the state or region. When a document is scanned, the OCR system extracts the region (e.g., "Mississippi", "Alabama", "Jalisco") from the document. If a state override is configured for that region, it takes precedence over the country-level age setting.

For example, if the United States has a minimum age of 18, but Mississippi has a state override of 21, a user presenting a Mississippi driver's license will be checked against the minimum age of 21.

### Configurable Actions

When a user's age falls outside the configured range for their document's country (or state), you can choose the action:

* **Decline**: The session is automatically declined.
* **Review**: The session is flagged for manual review.

<Note>
  Per-country age restrictions also work with **Adaptive Age Verification** workflows. When a borderline case triggers ID verification fallback, the age check uses these per-country settings to make the final decision based on the document's issuing country and region.
</Note>


# ID verification report
Source: https://docs.didit.me/core-technology/id-verification/report-id-verification

Read Didit's ID Verification report: status, extracted document fields, image-quality scores, cross-session matches, and where data appears in responses.

## Overview

The **ID verification report** captures everything Didit extracted and validated from a government-issued identity document — passports, ID cards, driver's licenses, and residence permits. It bundles the OCR'd biographical and document fields, signed URLs to the captured media, parsed and geolocated address data, per-side image quality scores, MRZ contents, multi-script (Latin / non-Latin) breakdowns, and cross-session document matches.

The report is produced after the user completes the document-capture step in a workflow (or hits the standalone OCR endpoint). Didit identifies the document type, runs OCR, validates the MRZ / barcode / QR code, parses the address, screens for tampering (screen capture, printed copy, portrait manipulation), and compares the document against every other document captured in your application.

Each report carries its own `status` — independent of the overall session status — that reflects how the ID step alone resolved:

* **Approved** — document recognized, all required fields extracted, no decline-routed warning fired.
* **In Review** — one or more warnings fired and your workflow routes them to review.
* **Declined** — an auto-decline condition fired (unsupported document, expired document, portrait missing, blocklist hit, adaptive-age failure) or a warning whose configured action is Decline fired (minimum/maximum age default to Decline).
* **Expired** — the document's `expiration_date` passed **after** the verification. Didit's ongoing expiration monitoring flips the report from `Approved` to `Expired`, appends a `DOCUMENT_EXPIRED` warning, and moves an approved session to the `Kyc Expired` session status.
* **Not Finished** — the user never completed the capture step.

## Where it appears in API responses

The ID report ships inside the `id_verifications[]` array — **always a JSON array**, never a singular `id_verification` object. Multiple entries appear when a workflow runs more than one document step (for example a primary ID plus a step-up).

* **Session decision API** — `GET /v3/session/{sessionId}/decision/` returns `id_verifications[]` at the top level. See [Retrieve session decision](/sessions-api/retrieve-session).
* **Webhooks** — `session.status.updated` payloads include the same `id_verifications[]` array once the step has produced data. See [Webhooks](/integration/webhooks).
* **Standalone OCR API** — direct document submission returns a singular `id_verification` object with the same fields. See [OCR standalone API](/standalone-apis/id-verification).

<Note>
  Read `response.id_verifications[0]` and iterate the array. The singular `id_verification` shape only exists on the standalone OCR API — it does not exist on the v3 decision endpoint.
</Note>

## Schema

The canonical field-by-field schema lives on the [Data models](/reference/data-models#id-verification) reference page. The fields below come straight from `IDVerificationV3Serializer`, which extends `IDVerificationV2Serializer` and adds `node_id` plus the cross-session `matches[]` array — 40 fields in total.

### Top-level fields

| Field                                                                                                             | Type                                                                                                                                                                                                                                                              | Description                                                                                                                                                                                                                                                                                                                                                                                                                |
| ----------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`                                                                                                          | `"Approved" \| "Declined" \| "In Review" \| "Expired" \| "Not Finished"`                                                                                                                                                                                          | ID-step status.                                                                                                                                                                                                                                                                                                                                                                                                            |
| `node_id`                                                                                                         | string \| null                                                                                                                                                                                                                                                    | Workflow graph node that produced this report.                                                                                                                                                                                                                                                                                                                                                                             |
| `document_type`                                                                                                   | `"Passport" \| "Identity Card" \| "Driver's License" \| "Residence Permit" \| "Health Insurance Card" \| "Tax Card" \| "Social Security Card" \| "Work Permit" \| "Visa" \| "Public Service Card" \| "Birth Certificate" \| "Firearm License" \| "Other" \| null` | Recognized top-level document family (human-readable).                                                                                                                                                                                                                                                                                                                                                                     |
| `document_subtype`                                                                                                | string \| null                                                                                                                                                                                                                                                    | Document subtype code from Didit's document registry, filtered to what the workflow's document settings accept. Region-specific documents include the region, for example `QUEENSLAND_DRIVER_LICENSE_GENERIC`. See [Document subtypes](/core-technology/id-verification/document-subtypes-id-verification) for the full code list, including how to tell a US commercial driver's license (CDL) apart from a standard one. |
| `document_number`                                                                                                 | string                                                                                                                                                                                                                                                            | OCR'd document number. On driving licences that print both a licence number and a card number, see the note below the table.                                                                                                                                                                                                                                                                                               |
| `personal_number`                                                                                                 | string                                                                                                                                                                                                                                                            | OCR'd personal / national identification number, when distinct from the document number.                                                                                                                                                                                                                                                                                                                                   |
| `portrait_image`, `front_image`, `front_video`, `back_image`, `back_video`, `full_front_image`, `full_back_image` | string (signed URL)                                                                                                                                                                                                                                               | Captured media. URLs are signed and time-limited — download promptly, never persist the URL.                                                                                                                                                                                                                                                                                                                               |
| `front_image_camera_front`, `back_image_camera_front`                                                             | string (signed URL) \| null                                                                                                                                                                                                                                       | Frames captured by the user's front-facing camera during document capture (used for the cross-camera face check).                                                                                                                                                                                                                                                                                                          |
| `front_image_camera_front_face_match_score`, `back_image_camera_front_face_match_score`                           | float (0–100) \| null                                                                                                                                                                                                                                             | Similarity score between the front-camera frame and the document portrait.                                                                                                                                                                                                                                                                                                                                                 |
| `front_image_quality_score`, `back_image_quality_score`                                                           | object \| null                                                                                                                                                                                                                                                    | Quality assessment per side (see Image quality scores).                                                                                                                                                                                                                                                                                                                                                                    |
| `date_of_birth`, `expiration_date`, `date_of_issue`                                                               | string (YYYY-MM-DD)                                                                                                                                                                                                                                               | Document dates.                                                                                                                                                                                                                                                                                                                                                                                                            |
| `age`                                                                                                             | number                                                                                                                                                                                                                                                            | Holder age in years computed from `date_of_birth`.                                                                                                                                                                                                                                                                                                                                                                         |
| `issuing_state`                                                                                                   | string (ISO 3166-1 alpha-3)                                                                                                                                                                                                                                       | Issuing country code.                                                                                                                                                                                                                                                                                                                                                                                                      |
| `issuing_state_name`                                                                                              | string                                                                                                                                                                                                                                                            | Localized country name.                                                                                                                                                                                                                                                                                                                                                                                                    |
| `first_name`, `last_name`, `full_name`                                                                            | string                                                                                                                                                                                                                                                            | Holder name in the script chosen by `preferred_characters` (see below).                                                                                                                                                                                                                                                                                                                                                    |
| `gender`                                                                                                          | `"M" \| "F" \| "U"`                                                                                                                                                                                                                                               | Gender, when present on the document (`U` = unknown).                                                                                                                                                                                                                                                                                                                                                                      |
| `address`, `formatted_address`                                                                                    | string                                                                                                                                                                                                                                                            | Raw and geocoded/formatted address strings.                                                                                                                                                                                                                                                                                                                                                                                |
| `place_of_birth`                                                                                                  | string                                                                                                                                                                                                                                                            | OCR'd place of birth.                                                                                                                                                                                                                                                                                                                                                                                                      |
| `marital_status`                                                                                                  | `"SINGLE" \| "MARRIED" \| "DIVORCED" \| "WIDOWED" \| "UNKNOWN"`                                                                                                                                                                                                   | Marital status, when present on the document.                                                                                                                                                                                                                                                                                                                                                                              |
| `nationality`                                                                                                     | string (ISO 3166-1 alpha-3)                                                                                                                                                                                                                                       | Holder nationality, when distinct from issuing state.                                                                                                                                                                                                                                                                                                                                                                      |
| `extra_fields`                                                                                                    | object                                                                                                                                                                                                                                                            | Document-specific extras (DL categories, blood group, alternate-script names, …).                                                                                                                                                                                                                                                                                                                                          |
| `mrz`                                                                                                             | object \| null                                                                                                                                                                                                                                                    | Parsed MRZ key/value fields.                                                                                                                                                                                                                                                                                                                                                                                               |
| `parsed_address`                                                                                                  | object \| null                                                                                                                                                                                                                                                    | Structured, geocoded address (`street_1`, `street_2`, `city`, `region`, `country`, `postal_code`, `address_type`, `formatted_address`, `document_location`, `raw_results`, `is_best_match`).                                                                                                                                                                                                                               |
| `extra_files[]`                                                                                                   | array of signed URLs                                                                                                                                                                                                                                              | Additional images attached to this document.                                                                                                                                                                                                                                                                                                                                                                               |
| `matches[]`                                                                                                       | array                                                                                                                                                                                                                                                             | Cross-session document matches (see Cross-session matches).                                                                                                                                                                                                                                                                                                                                                                |
| `warnings[]`                                                                                                      | array                                                                                                                                                                                                                                                             | Module-level warnings — see [ID verification warnings](/core-technology/id-verification/warnings-id-verification).                                                                                                                                                                                                                                                                                                         |

<Note>
  **`issuing_state` is always country-level, never sub-national.** For every
  document type, including driving licences issued by a state or province
  (Australia, the United States, Canada), `issuing_state` and
  `issuing_state_name` report the **country** (for example `AUS` /
  `Australia`), not the state. The sub-national value, when the document
  carries one, is available separately in `parsed_address.region` (falling
  back to `extra_fields.state` on some document types). The **Business
  Console** session overview shows this as a **Region** row underneath
  **Issuing state** when present.
</Note>

<Note>
  **Driver's licences that carry two numbers (Australia).** Australian licences
  print both a licence number, which identifies the holder's driving
  entitlement and stays the same when a card is replaced, and a card number,
  which identifies the physical card and changes with every reissue. For these
  licences Didit always maps the numbers the same way:

  * `personal_number` — the **licence number**
  * `document_number` — the **card number**

  This applies to every Australian state and territory (NSW, VIC, QLD, WA, SA,
  TAS, ACT, NT). On some variants the card number is printed only on the back,
  so it is read only when the back of the licence is captured. When no card
  number can be read, the licence number is reported as **both**
  `document_number` and `personal_number`, so `document_number` always carries
  an identifier once the verification finishes. `personal_number` is the
  licence number either way. On other document types `document_number` remains
  the primary OCR'd number and may itself be a holder-level identifier.
</Note>

### Image quality scores

`front_image_quality_score` and `back_image_quality_score` each return:

| Field                       | Type                                 | What it measures                                                                                                                     |
| --------------------------- | ------------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------ |
| `focus_score`               | number 0–100                         | Sharpness — top-10% local Laplacian variance, robust to uniform backgrounds. Weight 45%.                                             |
| `brightness_score`          | number 0–100                         | Penalizes too-dark or overexposed images. Weight 30%.                                                                                |
| `brightness_issue`          | `"ok" \| "too_dark" \| "too_bright"` | Direction of the brightness problem, when `brightness_score` is low.                                                                 |
| `resolution_score`          | number 0–100                         | Based on total pixel count of the capture. Weight 25%.                                                                               |
| `is_document_fully_visible` | boolean \| null                      | `true` when all four document corners are visible, `false` when any corner is cut off, `null` when corner detection was unavailable. |
| `overall_score`             | number 0–100                         | Weighted composite (focus 45%, brightness 30%, resolution 25%).                                                                      |

<Tip>
  Use `overall_score` as a quick suitability check — scores above **70** generally indicate a capture good enough for reliable verification.
</Tip>

### Cross-session matches

`matches[]` lists up to **5** other documents in your application that match this one — same **date of birth**, same **issuing country**, and a highly similar **full name**. Blocklisted documents additionally require an exact document-number match. Sessions belonging to the same user (same `vendor_data`) are excluded.

Each entry includes `session_id`, `session_number`, `vendor_data`, `verification_date`, `user_details` (`name`, `document_type`, `document_number`), `status`, `is_blocklisted` (`true` when the document was added to your blocklist), `api_service`, and a signed `front_image_url`.

## Status values

| Status         | Meaning                                                                                                                                                                                                         | Downstream effect                                                          |
| -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `Approved`     | Document recognized, required fields extracted, all checks passed at the configured thresholds.                                                                                                                 | Counts as a successful ID check.                                           |
| `In Review`    | One or more warnings fired and the workflow routes them to review.                                                                                                                                              | Session also moves to `In Review` until a reviewer acts.                   |
| `Declined`     | Auto-decline condition fired (unsupported document, expired document, portrait missing, blocklist hit, adaptive-age failure) or a warning configured to Decline fired.                                          | Session is declined unless another approved branch satisfies the workflow. |
| `Expired`      | The document's expiration date passed **after** approval. Set by Didit's ongoing expiration monitoring (respecting per-country `expiration_check_mode` exemptions), together with a `DOCUMENT_EXPIRED` warning. | An approved session moves to `Kyc Expired`.                                |
| `Not Finished` | User abandoned the capture step.                                                                                                                                                                                | The ID branch did not produce a result.                                    |

## Multi-script documents (Latin / non-Latin)

Some documents — Kyrgyz, Kazakh, Russian, Japanese, Korean, Chinese, Arabic, Thai, and others — print the holder's name, address, or place of birth in **both** a Latin transliteration **and** the local script. You choose which script powers the top-level response with the workflow (or standalone-API) setting `preferred_characters`:

| Value               | Populates top-level fields with                   | Opposite script goes to    |
| ------------------- | ------------------------------------------------- | -------------------------- |
| `latin` *(default)* | The Latin transliteration printed on the document | `extra_fields.*_non_latin` |
| `non_latin`         | The local-script values printed on the document   | `extra_fields.*_latin`     |

The alternate-script values live inside `extra_fields` under suffixed keys: `first_name_non_latin`, `last_name_non_latin`, `middle_name_non_latin`, `full_name_non_latin`, `address_non_latin`, `place_of_birth_non_latin` (or the matching `_latin` variants).

### When alternate-script fields appear

* **Only when both scripts are actually present on the document.** If an OCR field nominally labelled "Surname-Kyrgyz (Cyrillic)" is extracted as Latin-script text (homoglyphs or a Latin transliteration), it does **not** qualify as a non-Latin alternate and that key is omitted.
* `full_name_non_latin` (and `full_name_latin`) are always **reconstructed** from the individual first-, middle-, and last-name components when both are available — the raw "Full Name" field from OCR is ignored for consistency.
* When `preferred_characters=latin` but the document carries **only** non-Latin text (so the top-level fields end up non-Latin), Didit runs a transliteration pass and exposes `first_name_latin`, `last_name_latin`, `middle_name_latin`, `full_name_latin`, `place_of_birth_latin`, and `address_latin` as a Latin fallback.

```json theme={null}
{
  "first_name": "John",
  "last_name": "Doe",
  "full_name": "John Doe",
  "extra_fields": {
    "first_name_non_latin": "Айна"
  }
}
```

`last_name_non_latin` is absent because the document's "Surname (Cyrillic)" field came back as Latin characters on this sample — there was no genuine non-Latin surname to extract.

## Examples

### Approved — clean Spanish identity card (all fields)

```json theme={null}
{
  "id_verifications": [
    {
      "status": "Approved",
      "document_type": "Identity Card",
      "document_subtype": "ID_CARD_GENERIC",
      "document_number": "SAMPLE-DOC-12345",
      "personal_number": "SAMPLE-PER-12345",
      "portrait_image": "https://<media-host>/.../portrait.jpg?signature=...",
      "front_image": "https://<media-host>/.../front.jpg?signature=...",
      "front_video": "https://<media-host>/.../front.mp4?signature=...",
      "back_image": "https://<media-host>/.../back.jpg?signature=...",
      "back_video": "https://<media-host>/.../back.mp4?signature=...",
      "full_front_image": "https://<media-host>/.../full_front.jpg?signature=...",
      "full_back_image": "https://<media-host>/.../full_back.jpg?signature=...",
      "front_image_camera_front": null,
      "back_image_camera_front": null,
      "front_image_camera_front_face_match_score": null,
      "back_image_camera_front_face_match_score": null,
      "front_image_quality_score": {
        "focus_score": 85.3,
        "brightness_score": 92.1,
        "brightness_issue": "ok",
        "is_document_fully_visible": true,
        "resolution_score": 72.4,
        "overall_score": 84.6
      },
      "back_image_quality_score": {
        "focus_score": 79.1,
        "brightness_score": 90.5,
        "brightness_issue": "ok",
        "is_document_fully_visible": true,
        "resolution_score": 72.4,
        "overall_score": 81.5
      },
      "date_of_birth": "1990-01-01",
      "age": 35,
      "expiration_date": "2031-06-02",
      "date_of_issue": "2021-06-02",
      "issuing_state": "ESP",
      "issuing_state_name": "Spain",
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "gender": "M",
      "address": "Avda de Madrid 34",
      "formatted_address": "Avda de Madrid 34, Madrid, Madrid 28822, Spain",
      "place_of_birth": "Madrid",
      "marital_status": "SINGLE",
      "nationality": "ESP",
      "extra_fields": {},
      "mrz": {
        "document_number": "SAMPLE-DOC-12345",
        "surname": "DOE",
        "name": "JOHN",
        "birth_date": "900101",
        "expiry_date": "310602"
      },
      "parsed_address": {
        "street_1": "Avda de Madrid 34",
        "street_2": null,
        "city": "Madrid",
        "region": "Madrid",
        "country": "ES",
        "postal_code": "28822",
        "address_type": "Avda",
        "formatted_address": "Avda de Madrid 34, Madrid, Madrid 28822, Spain",
        "document_location": { "latitude": 40.4168, "longitude": -3.7038 },
        "raw_results": {
          "geometry": {
            "location": { "lat": 40.4168, "lng": -3.7038 },
            "location_type": "ROOFTOP"
          }
        },
        "is_best_match": true
      },
      "extra_files": [],
      "warnings": [],
      "node_id": "id_primary",
      "matches": []
    }
  ]
}
```

### In Review — QR not detected on a document that should have one

Abridged — a real response always carries the full field set shown above.

```json theme={null}
{
  "id_verifications": [
    {
      "status": "In Review",
      "node_id": "id_primary",
      "document_type": "Identity Card",
      "document_subtype": "ID_CARD_GENERIC",
      "document_number": "SAMPLE-DOC-12345",
      "first_name": "John",
      "last_name": "Doe",
      "full_name": "John Doe",
      "warnings": [
        {
          "feature": "ID_VERIFICATION",
          "risk": "QR_NOT_DETECTED",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "QR not detected",
          "long_description": "The system couldn't find or read the QR code on the document. This could be due to poor image quality or an unsupported document type.",
          "node_id": "id_primary"
        }
      ]
    }
  ]
}
```

## Security note

The signed URLs returned for document images and videos are temporary — they expire after a limited validity window. Treat them as short-lived: download what you need promptly and do not cache or surface them publicly. Typically your application only needs `status`, a handful of biographical fields, and the warnings — store as little as possible to minimize the surface for any future breach.

## Related

* [ID verification warnings](/core-technology/id-verification/warnings-id-verification) — full warning enum, causes, and remediation.
* [Document monitoring](/core-technology/id-verification/document-monitoring-id-verification) — how Didit screens for tampering and cross-session duplicates.
* [Supported documents](/core-technology/id-verification/supported-documents-id-verification) — which document types and countries are covered.
* [Document subtypes](/core-technology/id-verification/document-subtypes-id-verification) — full `document_subtype` code list, including US commercial vs. standard driver's license detection.
* [Webhooks](/integration/webhooks) — listen for `session.status.updated` to receive the report.
* [Data models — ID verification](/reference/data-models#id-verification) — canonical schema with every field.


# Supported ID Documents
Source: https://docs.didit.me/core-technology/id-verification/supported-documents-id-verification

Browse Didit's full list of supported ID documents by country: passports, national IDs, driver's licenses, and residence permits across 220+ countries.

Our state-of-the-art ID Verification system provides comprehensive global coverage, supporting identity documents from over 230 countries and territories in more than 130 languages. This extensive support ensures reliable and secure identity verification for your users worldwide.

<Note>
  Customize the accepted document types and countries through your [custom workflows](/console/workflows) to align with your business requirements and compliance needs.
</Note>

### Security and Accuracy Standards

We maintain industry-leading standards in ID Verification through:

* **Advanced Template Matching**: Our document database is continuously updated with the latest document formats and security features
* **AI-Powered Verification**: State-of-the-art machine learning algorithms ensure precise document analysis and fraud detection
* **Data Security**: Enterprise-grade encryption and security protocols protect all processed documents
* **Regulatory Compliance**: Full alignment with international KYC/AML regulations and identity verification standards
* **Real-time Updates**: Immediate adaptation to new document formats and security features worldwide

***

## Supported Documents by Country

The table below shows all supported identity documents by country. The **Code** column contains the [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code used across Didit APIs (e.g. in `expected_details`, `issuing_state`, workflow conditions, and list entries).

<SupportedDocumentsTable />

***

## Document Types Explained

| Type                      | Code      | Description                                                                                                                                                                                                                         |
| ------------------------- | --------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Passport**              | `P`       | National passports, e-passports, emergency passports, diplomatic passports                                                                                                                                                          |
| **ID Card**               | `ID`      | National identity cards, citizen cards, voter cards, digital IDs                                                                                                                                                                    |
| **Driver's License**      | `DL`      | Standard driver's licenses, commercial licenses (CDL), learner permits — see [Document subtypes](/core-technology/id-verification/document-subtypes-id-verification) for how to tell a commercial license apart from a standard one |
| **Residence Permit**      | `RP`      | Permanent resident cards, alien/foreigner IDs, border crossing cards                                                                                                                                                                |
| **Health Insurance Card** | `HIC`     | National health insurance cards                                                                                                                                                                                                     |
| **Tax Card**              | `TC`      | National tax identification cards                                                                                                                                                                                                   |
| **Social Security Card**  | `SSC`     | National social security cards                                                                                                                                                                                                      |
| **Work Permit**           | `WP`      | Work and employment authorization documents                                                                                                                                                                                         |
| **Visa**                  | `VISA`    | Visa stickers and visa documents                                                                                                                                                                                                    |
| **Public Service Card**   | `PSC`     | Public service identity cards                                                                                                                                                                                                       |
| **Birth Certificate**     | `BC`      | Birth certificates                                                                                                                                                                                                                  |
| **Firearm License**       | `FIREARM` | Firearm ownership and carry licenses                                                                                                                                                                                                |
| **Other**                 | `OTHER`   | Document types that don't fall into any category above                                                                                                                                                                              |

<Tip>
  Need a document type that isn't listed? [Contact us](mailto:support@didit.me) — we regularly add new document types based on customer needs. The [document subtype reference](/core-technology/id-verification/document-subtypes-id-verification) has the full breakdown of variants within each type.
</Tip>


# ID Verification Methods
Source: https://docs.didit.me/core-technology/id-verification/verification-methods

Verify identity three ways in one feature: document capture, a non-document lookup against an authoritative source, or a digital ID wallet sign-in.

ID Verification is one feature with three methods. You choose which methods a country may use; the end user gets whichever of them apply to the country they pick, and the session records which method actually produced the result.

| Method               | What the user does                                                                                                     | Assurance tier |
| -------------------- | ---------------------------------------------------------------------------------------------------------------------- | -------------- |
| **Document capture** | Photographs their passport, ID card, driver's licence or residence permit                                              | Documentary    |
| **Non-doc lookup**   | Types their national ID number plus a few personal details, checked against a government or other authoritative source | Data match     |
| **Wallet**           | Signs in with a government or bank digital identity such as MitID, BankID or itsme                                     | Cryptographic  |

Document capture is unchanged. Everything you already configure through [`documents_allowed`](/management-api/workflows/feature-configs) — accepted types, subtypes, capture rules, thresholds, warnings — keeps working exactly as before, and a workflow that says nothing about methods stays document capture only.

## How each method works

### Document capture

What the rest of this section documents: the user photographs the document, Didit reads it, checks it for authenticity and returns the extracted fields. Available in every country Didit supports, at \$0.15 per check with the first 500 checks each month free. Start at the [ID Verification overview](/core-technology/id-verification/overview).

### Non-doc lookup

The user types their national ID number and a few personal details, and Didit checks them against the authoritative source for that country. No photograph of a document is involved.

That source is a government register in most countries, but not in all of them: in Canada, France, Indonesia, the Netherlands, Norway, Singapore, the United Kingdom and the United States it is a credit-bureau, financial-services, utility or residential-records file instead. Because provenance and the applicable consent regime differ with it, the exact source is named per country in the table below and on [Non-document lookup](/core-technology/id-verification/non-doc-lookup) — never generalised.

Where the source returns a portrait — South Africa, Nigeria, Argentina and Panama today, all four government registers — the user is also asked for a selfie. Passive liveness runs on that selfie and it is face-matched to the registry portrait, all inside the lookup and all inside the lookup price. Where the source returns data only there is nothing to face-match against, so no selfie is taken; run [Liveness](/core-technology/liveness/overview) and [Face Match](/core-technology/face-match/overview) as their own workflow steps if you need them.

Full per-country request fields, format rules and consent regimes are on [Non-document lookup](/core-technology/id-verification/non-doc-lookup).

### Wallet

The user signs in with a digital identity they already hold — a national eID or a bank identity. The wallet authenticates them, then shares a signed set of attributes with Didit. Nothing is photographed and nothing is typed.

Same-device sign-in hands the user to the wallet app and back; cross-device sign-in shows a QR code they scan with their phone. Per-wallet attributes, assurance levels and failure semantics are on [Digital ID wallets](/core-technology/id-verification/digital-id-wallets).

## Assurance tiers

Every ID Verification result carries an assurance tier derived from the method that produced it. The tier is an honest description of what was actually proven, not a ranking:

| Tier          | Value on the session | What it means                                                                                              |
| ------------- | -------------------- | ---------------------------------------------------------------------------------------------------------- |
| Documentary   | `documentary`        | A physical document was captured, read and checked for authenticity.                                       |
| Data match    | `data_match`         | The details the user gave matched a record held by the source that was queried. No document was inspected. |
| Cryptographic | `cryptographic`      | A digital identity provider authenticated the user and signed the attributes it shared.                    |

<Note>
  Assurance tiers are an admin-facing label. They appear on the session payload, in the console and in exports. End users never see the tier, the price or the name of the source that was queried.
</Note>

## Configuring methods per country

Methods live under the `methods` key on the ID Verification (`OCR`) feature config, keyed by [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code. Omit the key, omit a country, or omit a method inside a country, and that country is document capture only.

```json theme={null}
{
  "feature": "OCR",
  "config": {
    "methods": {
      "ZAF": {
        "document": { "enabled": true },
        "id_lookup": {
          "enabled": true,
          "max_attempts": 2,
          "skip_liveness_and_face_match": true,
          "on_partial_match": "fallback_to_document",
          "on_no_match": "fallback_to_document",
          "on_provider_error": "fallback_to_document"
        },
        "wallet": { "enabled": false, "providers": [], "on_failure": "fallback_to_document" }
      },
      "DNK": {
        "document": { "enabled": true },
        "wallet": { "enabled": true, "providers": ["mitid"], "on_failure": "fallback_to_document" }
      }
    }
  }
}
```

Two rules the API enforces on save:

* **Availability is server-driven.** A method or a wallet that the capability catalog does not mark `available` for that country is rejected. Read the catalog first — through the console's **Countries** tab, or with the [`didit_workflow_get_id_verification_methods_catalog`](/integration/mcp/tools) MCP tool.
* **Wallets are an accept-list, never a ranking.** `providers` says which wallets a country may offer. The order you send has no meaning and is normalised away; the end user picks.

The full field-by-field reference, including defaults and validation, is in [Workflow feature configs](/management-api/workflows/feature-configs#ocr--id-verification).

## Fallback: what happens when a non-document method does not land

Four switches decide what happens next. Each one is either `fallback_to_document` (send the user to document capture) or `decline` (end the session with a declined ID Verification). All four default to `fallback_to_document`.

| Switch                        | Fires when                                             |
| ----------------------------- | ------------------------------------------------------ |
| `id_lookup.on_partial_match`  | The register answered, but some fields did not match.  |
| `id_lookup.on_no_match`       | The register answered and found no matching record.    |
| `id_lookup.on_provider_error` | The register could not be reached or did not answer.   |
| `wallet.on_failure`           | The wallet sign-in was cancelled, timed out or failed. |

`id_lookup.max_attempts` (1 to 5, default 1) is how many answered lookups the user gets before the switch fires. A number that fails the client-side format check never reaches the register, so it does not consume an attempt — the user is simply asked to correct it.

If a switch says `fallback_to_document` but document capture is disabled for that country, the session is declined instead: there is nowhere to fall back to. A decline records `fallback_from` on the declined ID Verification, naming the method that failed and why. The current staging implementation also carries that evidence onto the document verification created after a fallback. Confirm production rollout before depending on that additional evidence.

## What each method costs

| Method           | Price                                                                                                              | Free tier                   |
| ---------------- | ------------------------------------------------------------------------------------------------------------------ | --------------------------- |
| Document capture | \$0.15 per check                                                                                                   | First 500 checks each month |
| Non-doc lookup   | [Public USD rates by country and identifier](/core-technology/id-verification/non-doc-lookup#coverage-and-pricing) | Not included                |
| Wallet           | [Price pending publication, by wallet](/core-technology/id-verification/digital-id-wallets)                        | Not included                |

The 500 free ID Verification checks a month are scoped to document capture. Non-document methods are not part of that allowance. A lookup uses the public Database Validation retail rates for the services it runs; several services can contribute to one attempt. Nigeria selects either NIN or BVN. The [country table](/core-technology/id-verification/non-doc-lookup#coverage-and-pricing) shows the full configured attempt price, with each answered retry billed separately. Wallet prices remain unpublished while the catalog marks them as placeholders.

### Billing rules

* **A register that answered bills the lookup.** Match, partial match and no match all count — the query was run and the answer is the product.
* **A register that never answered is not billed.** A provider error costs nothing.
* **A number that fails the client-side format check is never billed** and never counted against `max_attempts`, because it never reached the register.
* **Document capture bills on top when the user falls back.** A lookup that answered and then fell back to a document is two charges, because two checks ran.
* **An abandoned, cancelled, timed-out or failed wallet sign-in is not billed.** Only a completed sign-in is.

## Coverage

Document capture is available in every country Didit supports and is not repeated below: \$0.15 per check, first 500 a month free. This table lists only the countries where a **non-document** method exists. A country that is not listed, or a cell that reads Not planned, is document capture only.

| Country              | Code  | Non-doc lookup                                                     | Digital ID wallets                                                                             |
| -------------------- | ----- | ------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------- |
| Argentina            | `ARG` | Available — RENAPER                                                | Not planned                                                                                    |
| Austria              | `AUT` | Not planned                                                        | EUDI Wallet (coming soon)                                                                      |
| Belgium              | `BEL` | Not planned                                                        | itsme (coming soon), Smart-ID (coming soon), EUDI Wallet (coming soon)                         |
| Bolivia              | `BOL` | Available — SEGIP                                                  | Not planned                                                                                    |
| Brazil               | `BRA` | Available — Receita Federal                                        | gov.br (coming soon)                                                                           |
| Bulgaria             | `BGR` | Not planned                                                        | EUDI Wallet (coming soon)                                                                      |
| Cambodia             | `KHM` | Available — Ministry of Interior voter register                    | Not planned                                                                                    |
| Canada               | `CAN` | Available — Canadian credit bureau records (FINTRAC dual-process)  | Not planned                                                                                    |
| Chile                | `CHL` | Available — Servicio de Registro Civil e Identificación            | Not planned                                                                                    |
| China                | `CHN` | Available — NCIIC (National Citizen Identity Information Center)   | Not planned                                                                                    |
| Colombia             | `COL` | Available — Registraduría General de la Nación / ANI               | Not planned                                                                                    |
| Costa Rica           | `CRI` | Available — Tribunal Supremo de Elecciones                         | Not planned                                                                                    |
| Croatia              | `HRV` | Not planned                                                        | EUDI Wallet (coming soon)                                                                      |
| Cyprus               | `CYP` | Not planned                                                        | EUDI Wallet (coming soon)                                                                      |
| Czechia              | `CZE` | Not planned                                                        | Bank iD (coming soon), MojeID (coming soon), EUDI Wallet (coming soon)                         |
| Denmark              | `DNK` | Available — CPR register                                           | MitID (coming soon), EUDI Wallet (coming soon)                                                 |
| Dominican Republic   | `DOM` | Available — Junta Central Electoral                                | Not planned                                                                                    |
| Ecuador              | `ECU` | Available — Registro Civil del Ecuador                             | Not planned                                                                                    |
| El Salvador          | `SLV` | Available — RNPN                                                   | Not planned                                                                                    |
| Estonia              | `EST` | Not planned                                                        | Smart-ID (coming soon), Mobile-ID (coming soon), EUDI Wallet (coming soon)                     |
| Finland              | `FIN` | Available — DVV population register                                | Finnish Trust Network (coming soon), EUDI Wallet (coming soon)                                 |
| France               | `FRA` | Available — French residential and utility records                 | FranceConnect (coming soon), EUDI Wallet (coming soon)                                         |
| Germany              | `DEU` | Not planned                                                        | Personalausweis (coming soon), EUDI Wallet (coming soon)                                       |
| Greece               | `GRC` | Not planned                                                        | EUDI Wallet (coming soon)                                                                      |
| Guatemala            | `GTM` | Available — SAT                                                    | Not planned                                                                                    |
| Honduras             | `HND` | Available — CNE                                                    | Not planned                                                                                    |
| Hungary              | `HUN` | Not planned                                                        | EUDI Wallet (coming soon)                                                                      |
| Iceland              | `ISL` | Not planned                                                        | Auðkenni (coming soon), EUDI Wallet (coming soon)                                              |
| India                | `IND` | Available — UIDAI (Aadhaar)                                        | Not planned                                                                                    |
| Indonesia            | `IDN` | Available — Indonesian population register via residential records | Not planned                                                                                    |
| Ireland              | `IRL` | Not planned                                                        | EUDI Wallet (coming soon)                                                                      |
| Italy                | `ITA` | Not planned                                                        | EUDI Wallet (coming soon)                                                                      |
| Kenya                | `KEN` | Available — IPRS (Integrated Population Registration System)       | Not planned                                                                                    |
| Latvia               | `LVA` | Not planned                                                        | Smart-ID (coming soon), Mobile-ID (coming soon), EUDI Wallet (coming soon)                     |
| Liechtenstein        | `LIE` | Not planned                                                        | EUDI Wallet (coming soon)                                                                      |
| Lithuania            | `LTU` | Not planned                                                        | Smart-ID (coming soon), Mobile-ID (coming soon), EUDI Wallet (coming soon)                     |
| Luxembourg           | `LUX` | Not planned                                                        | itsme (coming soon), EUDI Wallet (coming soon)                                                 |
| Malaysia             | `MYS` | Available — JPN (National Registration Department)                 | Not planned                                                                                    |
| Malta                | `MLT` | Not planned                                                        | EUDI Wallet (coming soon)                                                                      |
| Mexico               | `MEX` | Available — RENAPO                                                 | Not planned                                                                                    |
| Netherlands          | `NLD` | Available — Dutch residential records                              | itsme (coming soon), iDIN (coming soon), EUDI Wallet (coming soon)                             |
| Nigeria              | `NGA` | Available — NIMC / NIBSS                                           | Not planned                                                                                    |
| Norway               | `NOR` | Available — Norwegian residential records                          | BankID (coming soon), Vipps (coming soon), Buypass ID (coming soon), EUDI Wallet (coming soon) |
| Panama               | `PAN` | Available — Tribunal Electoral / SIB                               | Not planned                                                                                    |
| Paraguay             | `PRY` | Available — Registro del Estado Civil                              | Not planned                                                                                    |
| Peru                 | `PER` | Available — RENIEC                                                 | Not planned                                                                                    |
| Poland               | `POL` | Not planned                                                        | EUDI Wallet (coming soon)                                                                      |
| Portugal             | `PRT` | Not planned                                                        | EUDI Wallet (coming soon)                                                                      |
| Romania              | `ROU` | Not planned                                                        | EUDI Wallet (coming soon)                                                                      |
| Singapore            | `SGP` | Available — Singapore credit bureau and utility records            | Not planned                                                                                    |
| Slovakia             | `SVK` | Not planned                                                        | EUDI Wallet (coming soon)                                                                      |
| Slovenia             | `SVN` | Not planned                                                        | EUDI Wallet (coming soon)                                                                      |
| South Africa         | `ZAF` | Available — Department of Home Affairs                             | Not planned                                                                                    |
| Spain                | `ESP` | Not planned                                                        | EUDI Wallet (coming soon)                                                                      |
| Sweden               | `SWE` | Available — Skatteverket population register                       | BankID (coming soon), Freja eID (coming soon), EUDI Wallet (coming soon)                       |
| Thailand             | `THA` | Available — DOPA civil registration                                | Not planned                                                                                    |
| Ukraine              | `UKR` | Not planned                                                        | Diia (coming soon)                                                                             |
| United Arab Emirates | `ARE` | Not planned                                                        | UAE PASS (coming soon)                                                                         |
| United Kingdom       | `GBR` | Available — UK credit bureau and financial services records        | OneID (coming soon), GOV.UK Wallet (coming soon)                                               |
| United States        | `USA` | Available — US credit bureau and financial services records        | Not planned                                                                                    |
| Uruguay              | `URY` | Available — Dirección Nacional del Registro de Estado Civil        | Not planned                                                                                    |
| Venezuela            | `VEN` | Available — CNE                                                    | Not planned                                                                                    |

<Note>
  Coverage is generated from the capability catalog the backend serves, so this table is the same source the console and the API validate against. **Coming soon** means the entry is visible in the console and cannot be switched on yet; it is not a live capability and carries no committed date.
</Note>

## What lands on the session

Every ID Verification result carries the method that produced it, its assurance tier, and — when a non-document method ran — a per-method evidence block. Document sessions read exactly as they did before, with the new keys `null`.

| Field                 | Type           | Description                                                                                                                                                                           |
| --------------------- | -------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `verification_method` | string         | `document`, `id_lookup` or `wallet`.                                                                                                                                                  |
| `assurance`           | string         | `documentary`, `data_match` or `cryptographic`.                                                                                                                                       |
| `wallet_provider`     | string \| null | Catalog wallet id when a wallet produced the result.                                                                                                                                  |
| `id_lookup`           | object \| null | Registry evidence: source, checked-at, attempts, per-field comparison, registry portrait.                                                                                             |
| `wallet_verification` | object \| null | Credential evidence: provider, issuing authority, level of assurance, signature validity, shared attributes.                                                                          |
| `fallback_from`       | object \| null | `{ "method": ..., "reason": ..., "action": ... }` when a non-document method failed and the country's switch declined the session; staging also preserves it after document fallback. |

Field-by-field types and examples for all three methods are in the [ID verification data model](/reference/data-models#id-verification), and the same keys arrive on the [`status.updated` webhook](/integration/webhooks).

## Related

* [Non-document lookup](/core-technology/id-verification/non-doc-lookup) — per-country fields, formats, consent and retention
* [Digital ID wallets](/core-technology/id-verification/digital-id-wallets) — per-wallet attributes, assurance and failure semantics
* [ID Verification methods in the console](/console/id-verification-methods) — the Countries tab and the session method chip
* [Workflow feature configs](/management-api/workflows/feature-configs#ocr--id-verification) — the `methods` key reference


# ID verification warnings
Source: https://docs.didit.me/core-technology/id-verification/warnings-id-verification

Every warning Didit's ID verification module emits — auto-decline triggers, configurable risk groups, mismatch and tampering codes — with cause and remediation.

## Overview

Warnings on the ID verification report flag every condition Didit observed while reading and validating the document. They land in the `warnings[]` array on each item of `id_verifications[]` (see [ID verification report](/core-technology/id-verification/report-id-verification)), with the shape described in [Data models — Warning object](/reference/data-models#warning-object): `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`.

Every warning has three layers:

1. **The `risk` code** — a stable identifier you can match on in your code.
2. **The `log_type`** — derived from the action your configuration assigns to the risk at evaluation time: **Decline → `error`**, **Review → `warning`**, anything else → `information`.
3. **The decision impact** — set by the workflow's configurable risk groups. The same `risk` code can be routed to **Approve**, **Review**, or **Decline** depending on how your application is configured.

## Auto-decline conditions

In workflows, the following risks always force the ID report (and the session) to `Declined`. They cannot be configured:

| Risk                                     | Trigger                                                                                                                                                                                                                                                                        |
| ---------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | The submitted document type is not on your application's allowed-documents list. `additional_data` includes `issuing_state`, `document_type`, `document_subtype`, `document_region`, and `document_region_with_subtype` so you can enable the exact document in your workflow. |
| `DOCUMENT_EXPIRED`                       | The document's expiration date has passed at capture time.                                                                                                                                                                                                                     |
| `PORTRAIT_IMAGE_NOT_DETECTED`            | No portrait image could be located on the document.                                                                                                                                                                                                                            |
| `ID_DOCUMENT_IN_BLOCKLIST`               | The document matches an entry on your application's blocklist.                                                                                                                                                                                                                 |
| `AGE_BELOW_MINIMUM`                      | Adaptive age-verification workflows only: extracted age is below the minimum.                                                                                                                                                                                                  |
| `AGE_NOT_DETECTED`                       | Adaptive age-verification workflows only: age could not be extracted from the document.                                                                                                                                                                                        |

For the **standalone OCR API**, the unconditional-decline set is `DOCUMENT_EXPIRED`, `MINIMUM_AGE_NOT_MET`, `PORTRAIT_IMAGE_NOT_DETECTED`, `SCREEN_CAPTURE_DETECTED`, `PRINTED_COPY_DETECTED`, `PORTRAIT_MANIPULATION_DETECTED`, and `PUBLIC_DOCUMENT_IMAGE_DETECTED`. In workflows, minimum age is configurable (default Decline) and the three document-liveness risks are threshold-driven (see below).

## Configurable verification settings

In the Didit console, the remaining ID risks are grouped into settings you can route to **Approve**, **Review**, or **Decline** (per workflow, and per node in graph workflows):

| Group                                           | Risks                                                                                                                                                                                                                     | Default action        |
| ----------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- |
| **Minimum Age**                                 | `MINIMUM_AGE_NOT_MET`                                                                                                                                                                                                     | Decline               |
| **Maximum Age**                                 | `MAXIMUM_AGE_EXCEEDED`                                                                                                                                                                                                    | Decline               |
| **Duplicated User**                             | `POSSIBLE_DUPLICATED_USER` (skipped when the document number is in your document allowlist)                                                                                                                               | Approve (information) |
| **Invalid Code**                                | `QR_NOT_DETECTED`, `BARCODE_NOT_DETECTED`, `QR_VALIDATION_FAILED`, `BARCODE_VALIDATION_FAILED`                                                                                                                            | Approve (information) |
| **Invalid MRZ**                                 | `MRZ_VALIDATION_FAILED`, `MRZ_NOT_DETECTED`                                                                                                                                                                               | Approve (information) |
| **Data Inconsistency**                          | `DATA_INCONSISTENT`, `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME`, `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS`, `DOCUMENT_SIDES_MISMATCH`, `ID_VERIFICATION_DATA_MISMATCH_BETWEEN_DOCUMENTS`                    | Approve (information) |
| **Invalid Validation**                          | `INVALID_DATE`, `COULD_NOT_RECOGNIZE_DOCUMENT`, `DOCUMENT_NUMBER_NOT_DETECTED`, `COULD_NOT_DETECT_DOCUMENT_TYPE`, `NAME_NOT_DETECTED`, `DATE_OF_BIRTH_NOT_DETECTED`                                                       | Review                |
| **Expected Details Mismatch**                   | `FULL_NAME_MISMATCH_WITH_PROVIDED`, `GENDER_MISMATCH_WITH_PROVIDED`, `DOB_MISMATCH_WITH_PROVIDED`, `COUNTRY_MISMATCH_WITH_PROVIDED`, `NATIONALITY_MISMATCH_WITH_PROVIDED`, `IDENTIFICATION_NUMBER_MISMATCH_WITH_PROVIDED` | Review                |
| **Expiration Date Not Detected**                | `EXPIRATION_DATE_NOT_DETECTED`                                                                                                                                                                                            | Approve (information) |
| **Document or Personal Number Format Mismatch** | `DOCUMENT_NUMBER_FORMAT_MISMATCH`, `PERSONAL_NUMBER_FORMAT_MISMATCH` (one shared action)                                                                                                                                  | Approve (information) |
| **Unparsed Address**                            | `UNPARSED_ADDRESS`                                                                                                                                                                                                        | Approve (information) |
| **Image Quality**                               | `IMAGE_TOO_BLURRY`, `IMAGE_TOO_DARK`, `IMAGE_TOO_BRIGHT` (one action per risk)                                                                                                                                            | Approve (information) |
| **Document Without Portrait**                   | `DOCUMENT_HAS_NO_PORTRAIT`                                                                                                                                                                                                | Review                |

Two ID risk families are **threshold-driven** instead of Approve/Review/Decline toggles:

* **Document liveness** — `SCREEN_CAPTURE_DETECTED`, `PRINTED_COPY_DETECTED`, `PORTRAIT_MANIPULATION_DETECTED`. Each fraud type has its own decline and review thresholds: score below the decline threshold → `error` + Declined; below the review threshold → `warning` + In Review; otherwise `information`.
* **Cross-camera face match** — `LOW_FRONT_CAMERA_FACE_MATCH_SIMILARITY`, governed by `document_selfie_portrait_match_decline_threshold` / `document_selfie_portrait_match_review_threshold`.

One ID risk is neither configurable nor threshold-driven: `BARCODE_SIGNATURE_INVALID` always routes to **Review**. It fires only when a barcode carries an issuing-authority signature that fails cryptographic verification, so there is no configuration in which a proven forgery is ignored.

## Warnings produced

Verified against `collect_ocr_logs`, the document-capture flow, and `process_ocr_logs_and_get_status`. Short descriptions below are the exact `short_description` strings returned by the API.

### Document recognition and quality

| Risk                                                       | Short description                                    | Cause                                                                                                                                                                                                                                                                                                                   | Severity                                                          |
| ---------------------------------------------------------- | ---------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `COULD_NOT_RECOGNIZE_DOCUMENT`                             | Could not validate Document                          | The system could not confirm the authenticity or validity of the submitted document — often poor image quality or an unsupported document type. Also used as the fallback for unrecognized processing failures.                                                                                                         | Configurable — Invalid Validation, default Review                 |
| `COULD_NOT_DETECT_DOCUMENT_TYPE`                           | Could not detect document type                       | The OCR engine could not classify the document family (passport vs ID vs DL). When this fires, `DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` is suppressed (the type is unknown, so "not supported" would be contradictory).                                                                                                 | Configurable — Invalid Validation, default Review                 |
| `DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`                   | Document not supported for your application          | The recognized document type is not on the application's allowed list. `additional_data` carries the country, document type, subtype, and region-aware subtype.                                                                                                                                                         | `error` — **auto-decline**                                        |
| `DOCUMENT_EXPIRED`                                         | Document expired                                     | At capture time: the document's expiration date is in the past (`error`, auto-decline). Post-approval: ongoing expiration monitoring appends this warning with `log_type: "warning"` when an approved document's date passes, and the report status becomes `Expired`.                                                  | `error` at capture; `warning` from monitoring                     |
| `DOCUMENT_SIDES_MISMATCH`                                  | Document sides mismatch                              | Front and back images do not belong to the same document.                                                                                                                                                                                                                                                               | Configurable — Data Inconsistency, default information            |
| `PORTRAIT_IMAGE_NOT_DETECTED`                              | Portrait image not detected                          | No portrait could be located on a document that should have one (deferred when the user uploads the non-portrait side first).                                                                                                                                                                                           | `error` — **auto-decline**                                        |
| `DOCUMENT_HAS_NO_PORTRAIT`                                 | Document has no portrait                             | The recognized document family never carries a portrait photo on any side (some residence permits, health cards, registration certificates, tax cards, and a subset of DLs/IDs). This is a catalog-level fact about the document type, not an image-quality issue — re-scanning the document cannot change the outcome. | Configurable — Document Without Portrait, default Review          |
| `IMAGE_TOO_BLURRY` / `IMAGE_TOO_DARK` / `IMAGE_TOO_BRIGHT` | Document image is too blurry / too dark / too bright | The image-quality gate rejected an upload (the user is asked to retake). `additional_data` carries the failing `side`. A successful retake clears the stale warning; the gate is skipped on the user's final allowed attempt so they are never hard-blocked.                                                            | Configurable — per-risk Image Quality action, default information |

<Note>
  The capture flow can also reject an upload with the feedback codes `IMAGE_RESOLUTION_TOO_LOW`, `DOCUMENT_NOT_FULLY_VISIBLE`, `IMAGE_QUALITY_TOO_LOW`, and `DOCUMENT_OCCLUSION_DETECTED` (a finger or object is judged to be physically covering printed text). These prompt a retake in the SDK but are not persisted to the report's `warnings[]` — only the blurry/dark/bright risks are.
</Note>

<Tip>
  If your workflow anchors identity on Face Match rather than the document portrait, consider routing **Document Without Portrait** to Decline — otherwise a portrait-less document family reaches Face Match with nothing to compare against.
</Tip>

### Field extraction

| Risk                              | Short description                        | Cause                                                                                                                                                                                                                                                                               | Severity                                                         |
| --------------------------------- | ---------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------- |
| `NAME_NOT_DETECTED`               | First name and/or last name not detected | First name and last name could not be extracted. Exempt when the holder legitimately has a single name (one-name countries, or the MRZ itself carries a single name) and at least one name value was extracted.                                                                     | Configurable — Invalid Validation, default Review                |
| `DATE_OF_BIRTH_NOT_DETECTED`      | Date of birth not detected               | Date of birth could not be extracted from a document that should have one.                                                                                                                                                                                                          | Configurable — Invalid Validation, default Review                |
| `DOCUMENT_NUMBER_NOT_DETECTED`    | Document number not detected             | Neither the document number nor a personal number could be extracted.                                                                                                                                                                                                               | Configurable — Invalid Validation, default Review                |
| `EXPIRATION_DATE_NOT_DETECTED`    | Expiration date not detected             | Expiration date could not be extracted from a document that should have one.                                                                                                                                                                                                        | Configurable — Expiration Date Not Detected, default information |
| `INVALID_DATE`                    | Invalid Date                             | A date on the document (date of birth or expiry) doesn't parse to a valid date. In the current capture flow this surfaces as a retake prompt during upload rather than a stored warning; the code remains in the Invalid Validation routing group and may appear on older sessions. | Configurable — Invalid Validation, default Review                |
| `DOCUMENT_NUMBER_FORMAT_MISMATCH` | Document number format mismatch          | Document number does not match the expected format configured for this document type. `additional_data` carries `expected_format` and `extracted_value`.                                                                                                                            | Configurable — Format Mismatch, default information              |
| `PERSONAL_NUMBER_FORMAT_MISMATCH` | Personal number format mismatch          | Personal number does not match the expected format configured for this document type.                                                                                                                                                                                               | Configurable — Format Mismatch, default information              |

### MRZ, QR, barcode

All three MRZ risks are skipped for document types with known-unreliable MRZs.

| Risk                                       | Short description                                       | Cause                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | Severity                                                                                               |
| ------------------------------------------ | ------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `MRZ_NOT_DETECTED`                         | MRZ not detected                                        | MRZ could not be located on a document that should have one.                                                                                                                                                                                                                                                                                                                                                                                                               | Configurable — Invalid MRZ, default information                                                        |
| `MRZ_VALIDATION_FAILED`                    | MRZ is not valid                                        | MRZ failed checksum / format validation. Often a low-quality capture; can indicate tampering.                                                                                                                                                                                                                                                                                                                                                                              | Configurable — Invalid MRZ, default information                                                        |
| `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME` | MRZ and data extracted from OCR have some discrepancies | MRZ contents disagree with the VIZ (visible-zone) OCR. Possible alteration.                                                                                                                                                                                                                                                                                                                                                                                                | Configurable — Data Inconsistency, default information                                                 |
| `QR_NOT_DETECTED`                          | QR not detected                                         | QR code could not be located on a document that should have one.                                                                                                                                                                                                                                                                                                                                                                                                           | Configurable — Invalid Code, default information                                                       |
| `QR_VALIDATION_FAILED`                     | QR validation failed                                    | QR contents could not be validated against the rest of the document.                                                                                                                                                                                                                                                                                                                                                                                                       | Configurable — Invalid Code, default information                                                       |
| `BARCODE_NOT_DETECTED`                     | Barcode not detected                                    | Barcode could not be located on a document that should have one.                                                                                                                                                                                                                                                                                                                                                                                                           | Configurable — Invalid Code, default information                                                       |
| `BARCODE_VALIDATION_FAILED`                | Barcode validation failed                               | Barcode contents could not be validated against the rest of the document.                                                                                                                                                                                                                                                                                                                                                                                                  | Configurable — Invalid Code, default information                                                       |
| `BARCODE_SIGNATURE_INVALID`                | Barcode signature invalid                               | The barcode carries a digital signature from the issuing authority, and that signature did not verify - the data in the barcode is not the data the authority signed, which points to a forged or altered document. Currently checked for **French 2D-Doc (ANTS)** barcodes, where a verified signature lets Didit promote fields without needing MRZ corroboration; AAMVA (US/Canada driving licences and IDs) signatures are detected and logged only, not yet enforced. | Fixed - Review (own action group `invalid_barcode_signature_action`; not yet console/API-configurable) |
| `DATA_INCONSISTENT`                        | OCR data in the document is not consistent              | Data extracted from different parts of the document disagrees — typically the front and back sides of the same document.                                                                                                                                                                                                                                                                                                                                                   | Configurable — Data Inconsistency, default information                                                 |

<Note>
  Barcode signature verification currently covers French national ID cards, whose ANTS 2D-Doc barcode is signed by the issuing authority. `BARCODE_SIGNATURE_INVALID` is raised only when the signature check itself rejects the payload. A barcode with no signature, one signed by an authority not yet in Didit's trust store, or one whose signature cannot be decoded is treated as unauthenticated data and validated against the MRZ and printed text as before, without raising this risk.

  US and Canadian driving licence (AAMVA) barcodes are not cryptographically verified: digital signing there is optional and jurisdiction-specific, and no jurisdiction publishes verification keys, so Didit only detects and logs whether a payload carries a signature; the signature itself is never checked. AAMVA signature failures are not a risk signal today. A tampered AAMVA payload only surfaces as `BARCODE_VALIDATION_FAILED`, and only if the tampering also makes the barcode disagree with the MRZ or printed/OCR data - a forged signature on an otherwise internally consistent payload passes with no signal at all.

  The user is never asked to re-capture on `BARCODE_SIGNATURE_INVALID`: a signature that does not match the payload cannot be fixed by taking a better photo.
</Note>

### Identity matching

| Risk                                                    | Short description                                              | Cause                                                                                                                                                                                                                                                               | Severity                                                                                          |
| ------------------------------------------------------- | -------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------- |
| `ID_DOCUMENT_IN_BLOCKLIST`                              | ID document in blocklist                                       | The document matches a blocklisted document (same date of birth, issuing country, and exact document number) or a manually blocklisted document number. `additional_data` carries the blocklisted session reference.                                                | `error` — **auto-decline**                                                                        |
| `ID_DOCUMENT_IN_ALLOWLIST`                              | ID document in allowlist                                       | The document number matches your document allowlist, so the duplicate-user action was skipped. `additional_data` carries the `document_number`.                                                                                                                     | `information`                                                                                     |
| `POSSIBLE_DUPLICATED_USER`                              | Possible duplicated user from other session                    | Another document in your application has the same date of birth, the same issuing country, and a highly similar full name — under a different user (`vendor_data`), regardless of that session's status. `additional_data` carries the duplicate session reference. | Configurable — Duplicated User, default information                                               |
| `DOCUMENT_NAME_DIFFERENT_FROM_OTHER_APPROVED_DOCUMENTS` | Document name differs from other approved documents            | Name on this document differs from previously approved documents for the same user. Only produced for Didit-protocol (UserKYC) accounts, not standard API sessions.                                                                                                 | Configurable — Data Inconsistency, default information                                            |
| `ID_VERIFICATION_DATA_MISMATCH_BETWEEN_DOCUMENTS`       | Data mismatch between ID verification documents                | Two ID documents in the same session disagree on name / date of birth.                                                                                                                                                                                              | Configurable — Data Inconsistency, default information                                            |
| `LOW_FRONT_CAMERA_FACE_MATCH_SIMILARITY`                | Selfie during document capture doesn't match document portrait | The face captured from the user's front camera during document capture does not match the portrait on the document well.                                                                                                                                            | Threshold-driven: `error` below the decline threshold, `warning` at or below the review threshold |

### Document liveness (tampering)

Threshold-driven per fraud type in workflows; unconditionally declining on the standalone OCR API.

| Risk                             | Short description                   | Cause                                                                | Severity                                                                                      |
| -------------------------------- | ----------------------------------- | -------------------------------------------------------------------- | --------------------------------------------------------------------------------------------- |
| `SCREEN_CAPTURE_DETECTED`        | Screen capture of document detected | Document was captured from a screen rather than a physical document. | `error` below the decline threshold, `warning` below the review threshold, else `information` |
| `PRINTED_COPY_DETECTED`          | Printed copy of document detected   | Document appears to be a printed copy rather than the original.      | Same tri-bucket thresholds                                                                    |
| `PORTRAIT_MANIPULATION_DETECTED` | Portrait manipulation detected      | The portrait region appears to have been replaced or altered.        | Same tri-bucket thresholds                                                                    |

### Known public document images

| Risk                             | Short description                             | Cause                                                                                                                                                                                                                                                                                                                                                                                                                                                          | Severity                                                                               |
| -------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `PUBLIC_DOCUMENT_IMAGE_DETECTED` | Known public internet document image detected | The submitted document image matches a known publicly available internet image (for example a specimen, press, or stock photo of a document), so it cannot be a photo of the user's own physical document. Matching uses exact and perceptual (pHash/dHash) fingerprinting against Didit's corpus of known public document images; `additional_data` carries `match_type` (`exact` or `perceptual`), `source`, `source_url`, and a `similarity_score` (0-100). | Fixed - Review in workflows; **auto-decline** on the standalone `/id-verification` API |

### Expected-details mismatches

When you pass `expected_details` to a session, Didit raises a mismatch warning per field that does not match. One grouping (`expected_details_mismatch_action`, default Review) controls routing for all of these:

| Risk                                           | Short description                                        | Cause                                                                                  |
| ---------------------------------------------- | -------------------------------------------------------- | -------------------------------------------------------------------------------------- |
| `FULL_NAME_MISMATCH_WITH_PROVIDED`             | Full name mismatch with provided information             | Provided name scores below the name-match threshold against the document.              |
| `DOB_MISMATCH_WITH_PROVIDED`                   | Date of birth mismatch with provided information         | Provided date of birth does not match.                                                 |
| `GENDER_MISMATCH_WITH_PROVIDED`                | Gender mismatch with provided information                | Provided gender does not match.                                                        |
| `COUNTRY_MISMATCH_WITH_PROVIDED`               | Country mismatch with provided information               | Provided country does not match `issuing_state`.                                       |
| `NATIONALITY_MISMATCH_WITH_PROVIDED`           | Nationality mismatch with provided information           | Provided nationality does not match.                                                   |
| `IDENTIFICATION_NUMBER_MISMATCH_WITH_PROVIDED` | Identification number mismatch with provided information | Provided ID number does not match the document number, personal number, or tax number. |

Each mismatch warning carries the expected and extracted values in `additional_data`.

### Age

| Risk                   | Short description    | Cause                                                                                                                                 | Severity                                                                                               |
| ---------------------- | -------------------- | ------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ |
| `MINIMUM_AGE_NOT_MET`  | Minimum age not met  | Holder is below the configured minimum age (global or per-country/state). `additional_data` carries `min_age_allowed` and `user_age`. | Configurable — Minimum Age, default Decline (`error`); unconditional decline on the standalone OCR API |
| `MAXIMUM_AGE_EXCEEDED` | Maximum age exceeded | Holder is above the configured maximum age. `additional_data` carries `max_age_allowed` and `user_age`.                               | Configurable — Maximum Age, default Decline (`error`)                                                  |
| `AGE_NOT_DETECTED`     | Age not detected     | Adaptive age-verification workflows: age could not be extracted from the document.                                                    | `error` — **auto-decline**                                                                             |
| `AGE_BELOW_MINIMUM`    | Age below minimum    | Adaptive age-verification workflows: extracted age is below the minimum.                                                              | `error` — **auto-decline**                                                                             |

### Address

| Risk               | Short description                    | Cause                                                                                               | Severity                                             |
| ------------------ | ------------------------------------ | --------------------------------------------------------------------------------------------------- | ---------------------------------------------------- |
| `UNPARSED_ADDRESS` | Unable to determine address location | The document defines an address field, but the extracted address could not be parsed or geolocated. | Configurable — Unparsed Address, default information |

## Cross-session document matches

In addition to the warnings above, the V3 ID report ships a `matches[]` array — up to 5 other documents in your application with the same date of birth, the same issuing country, and a highly similar full name (blocklisted documents additionally require an exact document-number match), excluding sessions that belong to the same user. Documents added to your blocklist appear with `is_blocklisted: true`. Documents on your allowlist still appear in matches, but their duplicate-user action is skipped.

Each match includes `session_id`, `session_number`, `vendor_data`, `verification_date`, `user_details` (`name`, `document_type`, `document_number`), `status`, `is_blocklisted`, `api_service`, and a signed `front_image_url`.

## Examples

### Configurable warning at its default routing (information)

```json theme={null}
"warnings": [
  {
    "feature": "ID_VERIFICATION",
    "risk": "QR_NOT_DETECTED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "QR not detected",
    "long_description": "The system couldn't find or read the QR code on the document. This could be due to poor image quality or an unsupported document type.",
    "node_id": "id_primary"
  }
]
```

### Auto-decline on expired document

```json theme={null}
"warnings": [
  {
    "feature": "ID_VERIFICATION",
    "risk": "DOCUMENT_EXPIRED",
    "additional_data": null,
    "log_type": "error",
    "short_description": "Document expired",
    "long_description": "The document's expiration date has passed, rendering it no longer valid for use.",
    "node_id": "id_primary"
  }
]
```

### Expected-details mismatch with payload

```json theme={null}
"warnings": [
  {
    "feature": "ID_VERIFICATION",
    "risk": "DOB_MISMATCH_WITH_PROVIDED",
    "additional_data": {
      "expected_dob": "1990-01-01",
      "extracted_dob": "1991-03-15"
    },
    "log_type": "warning",
    "short_description": "Date of birth mismatch with provided information",
    "long_description": "The provided date of birth in `expected_details` doesn't match the date extracted from the document.",
    "node_id": "id_primary"
  }
]
```

## Warning types

Each risk is assigned a severity based on your application's configuration. The three severities are:

<WarningTypes />

## Related

* [ID verification report](/core-technology/id-verification/report-id-verification) — full report schema and statuses.
* [Document monitoring](/core-technology/id-verification/document-monitoring-id-verification) — how Didit detects tampering and cross-session duplicates.
* [Webhooks](/integration/webhooks) — `session.status.updated` carries the warnings as soon as the ID step finishes.
* [Data models — ID verification](/reference/data-models#id-verification) — canonical field-by-field schema.
* [Data models — Warning object](/reference/data-models#warning-object) — the shape of every entry in `warnings[]`.


# Device & IP Analysis
Source: https://docs.didit.me/core-technology/ip-analysis/overview

Detect duplicate devices, fraud rings, VPNs, proxies, Tor, location mismatches, and suspicious device fingerprints during KYC verification.

Didit's Device & IP Analysis combines device fingerprinting, duplicate-device recovery, IP intelligence, and geolocation checks in the verification flow. It helps detect when the same physical device is trying to access multiple accounts, even when the user changes sessions, clears browser storage, opens an incognito window, or rotates network information.

<AgentPromptAccordion title="Device & IP Analysis Integration Prompt" />

The feature is designed for fraud-prevention decisions where false positives are expensive. Exact duplicate-device matches use stable persistent identifiers. Recovered-device matches use the v2 fingerprint signal vector and high-confidence gates, so Didit can surface suspicious reuse without merging unrelated users too aggressively.

In the Academy lesson on reading a verification result, the 9:49 chapter walks the device and IP analysis signals.

<VideoEmbed title="Device and IP analysis — Didit Academy" />

<Frame>
  <img alt="Didit Device and IP Analysis overview showing geolocation, device fingerprinting, device intelligence and VPN detection" />
</Frame>

<Frame>
  <img alt="Didit Device and IP Analysis architecture diagram cross-checking IP, device fingerprint and declared location" />
</Frame>

## How it works

Device & IP Analysis runs automatically during the verification session and links the device, network, and identity context into one risk surface.

<Steps>
  <Step title="Device fingerprint capture" icon="fingerprint">
    The verification client sends a privacy-safe v2 fingerprint payload with web or mobile device signals:

    | Data Point               | Description                                                                                                      |
    | ------------------------ | ---------------------------------------------------------------------------------------------------------------- |
    | **Persistent device ID** | First-party identifier used for exact same-device detection when storage persists.                               |
    | **Composite hash**       | Stable grouped signal hash used for deterministic duplicate checks with collision safeguards.                    |
    | **Signal vector**        | Device and browser/app attributes vectorized for high-confidence recovery.                                       |
    | **Platform context**     | Browser, OS, app, hardware, WebGL/canvas, media, locale, timezone, and mobile integrity signals where available. |
  </Step>

  <Step title="IP and connection analysis" icon="wifi">
    Didit enriches the observed connection data with network risk information:

    * IP geolocation by country, region, city, and coordinates
    * VPN, proxy, Tor, data center, and private-network detection
    * Expected IP checks when you provide an allowed IP for the session
    * IP blocklist checks configured in your application
  </Step>

  <Step title="Duplicate and recovery matching" icon="code-compare">
    Didit checks whether the current session matches previous sessions from another `vendor_data`:

    | Check                             | Purpose                                                                           |
    | --------------------------------- | --------------------------------------------------------------------------------- |
    | **Duplicated IP**                 | Detects the same IP address across different users.                               |
    | **Duplicated device fingerprint** | Detects exact reuse of the same persistent device identity.                       |
    | **Recovered device**              | Detects a high-confidence v2 fingerprint recovery when the persistent ID changed. |
    | **Collision guard**               | Suppresses low-quality pooled hashes instead of merging unrelated devices.        |
  </Step>

  <Step title="Location cross-checks" icon="map-location-dot">
    Device & IP Analysis compares location context against trusted reference points:

    * Document country and address coordinates
    * Expected session IP address
    * IP country and city
    * Distance and direction between address and IP location
  </Step>

  <Step title="Action and reporting" icon="paper-plane">
    You can configure each risk category independently and consume the result in every Didit output:

    | Channel               | Description                                                                                                               |
    | --------------------- | ------------------------------------------------------------------------------------------------------------------------- |
    | **Workflow actions**  | Approve, review, or decline for VPN/proxy, location mismatch, duplicate IP, exact duplicate device, and recovered device. |
    | **Dashboard**         | Review warnings, matching sessions, device information, and network details in the Didit console.                         |
    | **Webhooks and APIs** | Receive structured warnings and matches in decision payloads.                                                             |
    | **Reports**           | Export Device & IP Analysis details in verification PDFs.                                                                 |
  </Step>
</Steps>

## Matching Model

Device & IP Analysis separates exact matches from recovered matches so you can tune fraud response safely:

| Layer                   | What it detects                                                                                  | False-positive posture                                                                                     |
| ----------------------- | ------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------- |
| **Exact persistent ID** | The same first-party device identity appears in another user's session.                          | Strongest signal. Used for `DUPLICATED_DEVICE_FINGERPRINT`.                                                |
| **Composite hash**      | The same deterministic device hash appears in another user's session.                            | Guarded by collision detection so common WebView/browser pools are suppressed.                             |
| **v2 recovered device** | The persistent ID changed, but rich device signals match a previous device with high confidence. | Conservative. Used for `DEVICE_RECOVERED_HIGH_CONFIDENCE` only after hard gates pass.                      |
| **IP reuse**            | The same IP address appears across users.                                                        | Contextual. Useful for fraud rings, but shared offices, households, and mobile carriers can be legitimate. |

Recovered-device matching uses a dedicated vector recovery index. If that index is not available, Didit continues exact duplicate checks and does not emit fuzzy recovery candidates.

In **Networks**, Didit also highlights residential proxy reuse when the same non-datacenter IP intelligence appears across multiple distinct users or businesses. The graph shows the aggregate risk signal, subject count, connection type, ISP and ASN context; it does not expose the raw IP address or another organization's profile data.

## Fraud Patterns Detected

Device & IP Analysis helps identify and reduce:

* Multi-accounting and duplicate-account creation
* KYC bypass attempts using the same device across different identities
* Fraud rings coordinating many accounts from shared devices or infrastructure
* Bonus abuse, referral abuse, promo abuse, and free-trial abuse
* Synthetic identity onboarding from repeated devices
* Money mule onboarding patterns
* Account takeover risk from unfamiliar or high-risk devices
* Credential stuffing and automated signup attempts
* Card testing, chargeback abuse, and refund abuse supported by repeated device/network patterns
* VPN, proxy, Tor, data center, and residential proxy evasion
* Device tampering, emulator usage, jailbreak/root risk, and app cloning where mobile signals are available
* Location spoofing and mismatches between document, IP, timezone, carrier, and device context
* Bot-driven verification attempts using headless browsers or scripted clients

## Key Capabilities

#### Device fingerprinting and recovery

* **Exact duplicate-device detection**: Detect the same device identity across sessions from different `vendor_data` values.
* **High-confidence recovery**: Recover likely same-device relationships when storage changes or incognito/private browsing changes the persistent ID.
* **Collision protection**: Avoid merging unrelated users when a device hash looks too common across many distinct persistent IDs.
* **Mobile and web coverage**: Use web browser signals and native mobile signals, including integrity-related fields when available.

#### IP and network intelligence

* **VPN and proxy detection**: Identify masked or anonymized connections.
* **Tor and data-center detection**: Flag high-risk infrastructure.
* **Residential proxy reuse**: Detect repeated use of the same residential-looking network across distinct subjects without exposing the raw IP value in the Networks graph.
* **IP blocklists**: Automatically decline when the IP appears in your application blocklist.
* **Expected IP enforcement**: Compare the observed IP to an expected IP supplied during session creation.

#### Geolocation and document comparison

* **Country mismatch detection**: Compare document country and IP country.
* **Geofencing**: Only accept sessions from allowed countries — with per-state/region overrides for countries like the United States — based on the IP geolocation.
* **Address distance checks**: Compare document address coordinates and IP geolocation.
* **Session match context**: Return matching sessions with device and location details for staff review.

## Configure Actions

Use workflow settings to choose the action for each risk. Conservative customers often set `recovered_device_action` to `REVIEW` first, inspect recovered-device warnings for a few weeks, and only move to `DECLINE` after confirming the local false-positive profile.

| Setting                    | Recommended starting action | Why                                                                                                                        |
| -------------------------- | --------------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| `vpn_detection_action`     | `REVIEW` or `DECLINE`       | Depends on whether VPN usage is allowed in your product.                                                                   |
| `ip_mismatch_action`       | `REVIEW`                    | Location mismatch is strong context but can be legitimate.                                                                 |
| `duplicated_ip_action`     | `REVIEW`                    | Shared networks can create false positives.                                                                                |
| `duplicated_device_action` | `REVIEW` or `DECLINE`       | Exact same-device reuse across users is a strong fraud signal.                                                             |
| `recovered_device_action`  | `REVIEW`                    | High-confidence recovery is intentionally conservative, but should be monitored before automatic decline.                  |
| `ip_geofencing_action`     | `DECLINE`                   | Geofencing usually expresses a hard jurisdictional rule; use `REVIEW` if you prefer manual triage of restricted locations. |

See [Device & IP Analysis warnings](/core-technology/ip-analysis/warnings-ip-analysis) for all risk tags and [Workflow Feature Configs](/management-api/workflows/feature-configs#device--ip-analysis) for API fields.


# Device & IP analysis report
Source: https://docs.didit.me/core-technology/ip-analysis/report-ip-analysis

Parse the Device & IP analysis report: geolocation, device fingerprint, VPN/Tor/proxy flags, document-vs-IP distance, and duplicate device matches.

## Overview

Device & IP analysis profiles every session by IP geolocation, device fingerprint, browser/OS, and network type.
Geolocation, network-risk enrichment, device matching, and remote device integrity checks run asynchronously while the user completes verification.
Device and IP observations remain available while analysis is pending; geolocation fields can be empty until results arrive, or when the address is not public.
If your workflow uses these checks to determine the outcome or choose a subsequent step, the session remains `In Progress` until the required results are available.
If required analysis remains unavailable after bounded retries, the session moves to `In Review` for a manual decision.
Optional enrichment failures do not prevent completion, and manual decisions remain authoritative.
It produces:

* An **IP geolocation** block (country, state, city, latitude/longitude, time zone) derived from the public IP.
* **Network-risk flags** — `is_vpn_or_tor` and `is_data_center` — to detect masking attempts (VPN, Tor exit nodes, hosting providers, anonymisers).
* **Cross-document distance calculations** — straight-line km between the IP location, the ID document's location, and the proof-of-address document's location.
* **Cross-session matches** — when the same IP address or device identity appears across sessions belonging to different users (grouped by `vendor_data`).
* **Device fingerprint recovery** — a high-confidence recovery signal that links sessions even after the user clears storage, switches incognito modes, or reinstalls the app.

<Frame>
  <img alt="Didit Device and IP Analysis report screenshot with geolocation, device fingerprint and risk flags" />
</Frame>

## Where it appears in API responses

The decision endpoint returns Device & IP analysis as the plural array **`ip_analyses[]`** in `GET /v3/session/{sessionId}/decision/`. Entries are deduplicated `Location` observations keyed on (`node_id`, `ip_address`, `device_fingerprint`) — a single node can yield multiple entries when the user's IP or device changes mid-session.

```text theme={null}
GET /v3/session/{sessionId}/decision/
  ──▶ { "ip_analyses": [ { status, node_id, ip_address, ip, id_document, poa_document, warnings, matches, … }, … ] }
```

The shape below mirrors the canonical schema — see [Data models](/reference/data-models#ip-analysis).

## Schema

See [Device & IP analysis in the Data Models reference](/reference/data-models#ip-analysis) for the canonical schema.

```typescript theme={null}
interface IPAnalysisV3 {
  status: 'Not Finished' | 'Approved' | 'Declined' | 'In Review' | 'Resub Requested';
  node_id: string | null;

  // Device
  device_brand: string | null;
  device_model: string | null;
  browser_family: string | null;
  os_family: string | null;
  platform: 'mobile' | 'tablet' | 'desktop' | null;
  device_fingerprint: string | null;

  // IP geolocation
  ip_country: string | null;
  ip_country_code: string | null;           // ISO 3166-1 alpha-2
  ip_state: string | null;
  ip_city: string | null;
  latitude: number | null;
  longitude: number | null;
  ip_address: string;
  isp: string | null;
  organization: string | null;
  is_vpn_or_tor: boolean;
  is_data_center: boolean;
  time_zone: string | null;
  time_zone_offset: string | null;

  // Distance blocks — each carries its own location + distances to the other two
  ip: {
    location: { latitude: number; longitude: number } | null;
    distance_from_id_document: number | null;   // km
    distance_from_poa_document: number | null;  // km
  };
  id_document: {
    location: { latitude: number; longitude: number } | null;
    distance_from_ip: number | null;
    distance_from_poa_document: number | null;
  };
  poa_document: {
    location: { latitude: number; longitude: number } | null;
    distance_from_ip: number | null;
    distance_from_id_document: number | null;
  };

  warnings: Warning[];          // see Data Models — Warning object

  // Cross-session matches — up to 5 IP matches + 5 device matches
  matches: IPAnalysisMatch[];
}

interface IPAnalysisMatch {
  session_id: string;                       // matching session UUID
  session_number: number;
  vendor_data: string | null;
  verification_date: string | null;         // "YYYY-MM-DDTHH:MM:SSZ"
  match_type: 'ip_address' | 'device_fingerprint';
  match_source: 'ip_address' | 'persistent_id' | 'legacy_fp' | 'recovered_high';
  matched_value: string | null;             // shared IP, device identifier, or recovered device UUID
  status: string;                           // lifecycle status of the matching session
  is_blocklisted: boolean;                  // currently always false
  api_service: string | null;               // standalone API service; null for workflow sessions
  source: 'session';
  device_info: {
    device_brand: string | null;
    device_model: string | null;
    browser_family: string | null;
    os_family: string | null;
    platform: string | null;
    device_fingerprint: string | null;
  };
  location_info: {
    ip_address: string | null;
    ip_country: string | null;
    ip_country_code: string | null;
    ip_state: string | null;
    ip_city: string | null;
    is_vpn_or_tor: boolean;
    is_data_center: boolean;
  };
  confidence: number;                       // 0–1, = 1 - P(false positive)
  match_mode: 'deterministic' | 'probabilistic' | 'co_occurrence';

  // Present only when match_source = 'recovered_high'
  recovery_similarity?: number;             // cosine similarity, 4 decimals
  tls_ja4_corroborated?: boolean;           // TLS JA4 fingerprints of both observations agree
  recovery_gate_reason?: string;            // e.g. 'hardware_root_match'
}
```

### Match semantics

`match_source` tells you how the match was reached, and `confidence` scores how likely it is to be *wrong* (`confidence = 1 - P(false positive)`):

| `match_source`   | Meaning                                                                 | `confidence`                                                                                           | `match_mode`                       |
| ---------------- | ----------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------ | ---------------------------------- |
| `ip_address`     | Shared IP — network co-location, never a device-identity claim.         | `0.0`                                                                                                  | `co_occurrence`                    |
| `persistent_id`  | Exact stored persistent device identifier.                              | `1.0`                                                                                                  | `deterministic`                    |
| `legacy_fp`      | Legacy `didit-fp-*` device-fingerprint hash.                            | `0.5`                                                                                                  | `probabilistic`                    |
| `recovered_high` | High-confidence fuzzy fingerprint-recovery hit after strict hard gates. | `1.0` when hardware-rooted, otherwise `< 1.0`, boosted when TLS JA4 and IP country independently agree | `deterministic` or `probabilistic` |

Lower-confidence recovery candidates surface as risk warnings only — never in `matches[]`. IP matches and device matches are capped at 5 each, so the array holds at most 10 entries.

## Status values

Statuses are feature-level `FeatureStatusChoices` values. Each fired warning maps to the action configured for it on the workflow node; the strongest action wins.

| Value             | Meaning                                                                                                                                                                     |
| ----------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Not Finished`    | The IP analysis node has not completed for this session (default).                                                                                                          |
| `Approved`        | No warning fired, or every fired warning is configured to No action.                                                                                                        |
| `In Review`       | At least one fired warning is configured to Review (see [warnings](/core-technology/ip-analysis/warnings-ip-analysis)).                                                     |
| `Declined`        | A blocklist warning fired (`IP_ADDRESS_IN_BLOCKLIST` or `DEVICE_FINGERPRINT_IN_BLOCKLIST` — always decline), or a configurable warning is set to Decline for your workflow. |
| `Resub Requested` | A reviewer requested resubmission of this step.                                                                                                                             |

Custom status rules configured on the IP analysis node can further adjust the resulting status.

## VPN, proxy, and Tor detection

`is_vpn_or_tor` and `is_data_center` are independent boolean flags returned for every session. When `is_vpn_or_tor` is `true`, Didit also emits the `PRIVATE_NETWORK_DETECTED` warning so your team can act on it via workflow configuration. Datacenter-only traffic (without VPN/Tor) sets `is_data_center=true` but does not auto-warn — use this as an additional signal in your own scoring.

## Examples

### Approved

```json theme={null}
{
  "ip_analyses": [
    {
      "status": "Approved",
      "node_id": "ip-1",
      "device_brand": "Apple",
      "device_model": "iPhone",
      "browser_family": "Mobile Safari",
      "os_family": "iOS",
      "platform": "mobile",
      "device_fingerprint": "didit-fp-8d2c7a91f4b3e042",
      "ip_country": "Spain",
      "ip_country_code": "ES",
      "ip_state": "Barcelona",
      "ip_city": "Barcelona",
      "latitude": 41.4022,
      "longitude": 2.1407,
      "ip_address": "83.50.226.71",
      "isp": "Telefonica",
      "organization": "Telefonica de Espana",
      "is_vpn_or_tor": false,
      "is_data_center": false,
      "time_zone": "Europe/Madrid",
      "time_zone_offset": "+0100",
      "ip": {
        "location": { "latitude": 41.4022, "longitude": 2.1407 },
        "distance_from_id_document": 23.4,
        "distance_from_poa_document": 12.3
      },
      "id_document": {
        "location": { "latitude": 41.2706, "longitude": 1.9770 },
        "distance_from_ip": 23.4,
        "distance_from_poa_document": 18.7
      },
      "poa_document": {
        "location": { "latitude": 41.3128, "longitude": 2.0540 },
        "distance_from_ip": 12.3,
        "distance_from_id_document": 18.7
      },
      "warnings": [],
      "matches": []
    }
  ]
}
```

### Declined — IP blocklist hit + VPN + duplicate device

```json theme={null}
{
  "ip_analyses": [
    {
      "status": "Declined",
      "node_id": "ip-1",
      "device_brand": null,
      "device_model": null,
      "browser_family": "Chrome",
      "os_family": "Linux",
      "platform": "desktop",
      "device_fingerprint": "didit-fp-a13c0d22e8b94471",
      "ip_country": "Netherlands",
      "ip_country_code": "NL",
      "ip_state": "North Holland",
      "ip_city": "Amsterdam",
      "latitude": 52.3676,
      "longitude": 4.9041,
      "ip_address": "45.61.20.5",
      "isp": "Example Hosting",
      "organization": "Example Hosting BV",
      "is_vpn_or_tor": true,
      "is_data_center": true,
      "time_zone": "Europe/Amsterdam",
      "time_zone_offset": "+0100",
      "ip": {
        "location": { "latitude": 52.3676, "longitude": 4.9041 },
        "distance_from_id_document": 1834.2,
        "distance_from_poa_document": 1822.5
      },
      "id_document": {
        "location": { "latitude": 40.4168, "longitude": -3.7038 },
        "distance_from_ip": 1834.2,
        "distance_from_poa_document": 14.0
      },
      "poa_document": {
        "location": { "latitude": 40.5070, "longitude": -3.6720 },
        "distance_from_ip": 1822.5,
        "distance_from_id_document": 14.0
      },
      "warnings": [
        {
          "feature": "LOCATION",
          "risk": "IP_ADDRESS_IN_BLOCKLIST",
          "additional_data": { "ip_address": "45.61.20.5" },
          "log_type": "error",
          "short_description": "IP address in blocklist",
          "long_description": "The IP address used for this session was found in the application's IP blocklist, indicating a known suspicious or forbidden origin.",
          "node_id": "ip-1"
        },
        {
          "feature": "LOCATION",
          "risk": "PRIVATE_NETWORK_DETECTED",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Private network (VPN/Tor) detected",
          "long_description": "The system detected that the user tried to use a private network (VPN/TOR) to complete the verification process.",
          "node_id": "ip-1"
        },
        {
          "feature": "LOCATION",
          "risk": "COUNTRY_FROM_DOCUMENT_DOES_NOT_MATCH_COUNTRY_FROM_IP",
          "additional_data": { "document_country_code": "ESP", "ip_country_code": "NLD" },
          "log_type": "warning",
          "short_description": "Document country does not match IP country",
          "long_description": "The country from the document does not match the country from the IP address, suggesting a potential mismatch between the document and the user's location.",
          "node_id": "ip-1"
        },
        {
          "feature": "LOCATION",
          "risk": "DUPLICATED_DEVICE_FINGERPRINT",
          "additional_data": {
            "duplicated_session_id": "11111111-2222-3333-4444-555555555555",
            "duplicated_session_number": 1042,
            "api_service": null,
            "match_source": "persistent_id"
          },
          "log_type": "warning",
          "short_description": "Duplicated device fingerprint from another session",
          "long_description": "The same device fingerprint was detected in another session with a different vendor_data, which may indicate multiple identities verified from the same device.",
          "node_id": "ip-1"
        }
      ],
      "matches": [
        {
          "session_id": "11111111-2222-3333-4444-555555555555",
          "session_number": 1042,
          "vendor_data": "user-other",
          "verification_date": "2026-05-28T14:03:21Z",
          "match_type": "device_fingerprint",
          "match_source": "persistent_id",
          "matched_value": "pid_9f1c2b7a8d3e4f50",
          "status": "Declined",
          "is_blocklisted": false,
          "api_service": null,
          "source": "session",
          "device_info": {
            "device_brand": null,
            "device_model": null,
            "browser_family": "Chrome",
            "os_family": "Linux",
            "platform": "desktop",
            "device_fingerprint": "didit-fp-a13c0d22e8b94471"
          },
          "location_info": {
            "ip_address": "45.61.23.99",
            "ip_country": "Netherlands",
            "ip_country_code": "NL",
            "ip_state": "North Holland",
            "ip_city": "Amsterdam",
            "is_vpn_or_tor": true,
            "is_data_center": true
          },
          "confidence": 1.0,
          "match_mode": "deterministic"
        }
      ]
    }
  ]
}
```

## Related

* [Device & IP analysis warnings](/core-technology/ip-analysis/warnings-ip-analysis) — every warning code IP analysis can emit
* [Device & IP analysis overview](/core-technology/ip-analysis/overview) — what each block measures
* [Data models — IP analysis](/reference/data-models#ip-analysis) — canonical schema
* [Webhooks](/integration/webhooks) — `status.updated` carries the same IP analysis payload


# Device & IP analysis warnings
Source: https://docs.didit.me/core-technology/ip-analysis/warnings-ip-analysis

Every Device & IP analysis warning code: VPN/Tor, country mismatch, blocklists, duplicate IP/device, recovered devices, and expected-IP mismatch.

## Overview

Device & IP analysis emits warning tags on `ip_analyses[].warnings[]` whenever it detects suspicious device, network, or location behavior. Six tags have a configurable action (Decline / Review / No action) per workflow node; the two blocklist tags always force `Declined`, and the two allowlist tags are always informational. Each warning's `log_type` mirrors the action that applied: `error` (Decline), `warning` (Review), or `information` (No action). Each risk fires at most once per session.

Every risk below is verified against the live decision pipeline; warnings carry the feature tag `LOCATION` and the standard [warning object](/reference/data-models#warning-object) shape.

The device fingerprint warnings are intentionally split into exact and recovered signals:

* `DUPLICATED_DEVICE_FINGERPRINT` means the same deterministic device identity (`match_source` `persistent_id` or `legacy_fp`) was reused across sessions with different `vendor_data` values.
* `DEVICE_RECOVERED_HIGH_CONFIDENCE` means v2 fingerprint recovery matched the session to a previously seen device **after** the persistent ID changed (storage cleared, incognito mode, app reinstall). The warning only appears when the match passes the high-confidence similarity threshold and hard gates.

<Frame>
  <img alt="Didit Device and IP Analysis warning example with device, VPN, proxy and location-mismatch alerts" />
</Frame>

## Warnings produced

| Risk                                                   | Cause                                                                                                                                                                                                                                                                                                                                                            | `log_type`                | Affects status                                                   | Recommended remediation                                                                                                              |
| ------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | ---------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `PRIVATE_NETWORK_DETECTED`                             | `is_vpn_or_tor` was `true` — the session was opened via VPN, proxy, or Tor exit node. `additional_data` is `null`.                                                                                                                                                                                                                                               | mirrors configured action | Configurable: Decline / Review / No action (default: No action). | Decide whether your risk tolerance allows masked traffic. If you accept it, leave on No action.                                      |
| `COUNTRY_FROM_DOCUMENT_DOES_NOT_MATCH_COUNTRY_FROM_IP` | The ISO country of the ID document differs from the country derived from the IP address. `additional_data` carries both ISO-3 codes: `document_country_code`, `ip_country_code`.                                                                                                                                                                                 | mirrors configured action | Configurable: Decline / Review / No action (default: No action). | Review when the user travels legitimately. Decline when paired with VPN or duplicate-device signals.                                 |
| `EXPECTED_IP_ADDRESS_MISMATCH`                         | The session was created with an expected IP address, and the live IP differs. `additional_data` carries `expected_ip_address` and `actual_ip_address`.                                                                                                                                                                                                           | mirrors configured action | Configurable: Decline / Review / No action (default: No action). | Use when you pre-pin the IP at session creation. Refuse the session or step up auth on mismatch.                                     |
| `IP_ADDRESS_IN_BLOCKLIST`                              | The session's IP address matches an entry in the application's IP blocklist. `additional_data`: `ip_address`.                                                                                                                                                                                                                                                    | always `error`            | Forces `Declined`.                                               | Reject the session. Audit the blocklist source for false positives if needed.                                                        |
| `DEVICE_FINGERPRINT_IN_BLOCKLIST`                      | The session's device fingerprint matches an entry in the device blocklist. `additional_data`: `device_fingerprint`.                                                                                                                                                                                                                                              | always `error`            | Forces `Declined`.                                               | Reject the session.                                                                                                                  |
| `IP_ADDRESS_IN_ALLOWLIST`                              | The session's IP had duplicate matches but is on the application's IP allowlist, so the duplicate-IP warning was skipped. `additional_data`: `ip_address`.                                                                                                                                                                                                       | always `information`      | None.                                                            | Use for trusted corporate NATs, QA networks, or known shared access points.                                                          |
| `DEVICE_FINGERPRINT_IN_ALLOWLIST`                      | The session's device fingerprint had deterministic duplicate matches but is on the device allowlist, so the duplicate-device warning was skipped. `additional_data`: `device_fingerprint`.                                                                                                                                                                       | always `information`      | None.                                                            | Use only for trusted shared devices. Blocklists still take priority.                                                                 |
| `DUPLICATED_IP_ADDRESS`                                | The same IP was used in another session with a different `vendor_data`. `additional_data`: `duplicated_session_id`, `duplicated_session_number`, `api_service`. Skipped when the IP is allowlisted.                                                                                                                                                              | mirrors configured action | Configurable: Decline / Review / No action (default: No action). | Common on corporate or shared NAT. Pair with other signals (duplicate device, country mismatch) before declining.                    |
| `DUPLICATED_DEVICE_FINGERPRINT`                        | The same deterministic device identity was reused across sessions with different `vendor_data`. `additional_data`: `duplicated_session_id`, `duplicated_session_number`, `api_service`, `match_source` (`persistent_id` or `legacy_fp`). Skipped when the fingerprint is allowlisted.                                                                            | mirrors configured action | Configurable: Decline / Review / No action (default: No action). | Strong evidence of multi-account abuse. Review or decline depending on fraud tolerance.                                              |
| `DEVICE_RECOVERED_HIGH_CONFIDENCE`                     | The v2 device recovery model matched the session to a previously seen device with high confidence, even after the persistent ID changed. `additional_data`: `duplicated_session_id`, `duplicated_session_number`, `api_service`, `match_source` (`recovered_high`), `recovery_similarity`, `recovery_match_device_uuid`. Not suppressed by the device allowlist. | mirrors configured action | Configurable: Decline / Review / No action (default: No action). | Start with Review, measure your false-positive rate, then tighten the action. Strong signal for storage-reset or incognito attempts. |
| `IP_LOCATION_NOT_ALLOWED`                              | IP geofencing is enabled and the session IP is located in a country or state/region marked as not allowed. `additional_data`: `ip_country_code` (ISO-3), `ip_country`, `ip_state`, `restricted_by` (`country` or `state`).                                                                                                                                       | mirrors configured action | Configurable: Decline / Review / No action (default: Decline).   | Use to enforce jurisdictional restrictions. Combine with `vpn_detection_action` so masked traffic cannot bypass the fence.           |

When the recovered device has no eligible sibling sessions yet (so nothing lands in `matches[]`), `DEVICE_RECOVERED_HIGH_CONFIDENCE` still fires with a fallback `additional_data` shape: `recovery_match_device_uuid`, `recovery_match_similarity`, `recovery_match_band`, `recovery_gate_reason`.

`IP_LOCATION_NOT_ALLOWED` fires when IP geofencing is enabled (`is_ip_geofencing_enabled`) and the session IP is located in a country or state/region marked as not allowed in `ip_geofencing_by_country`. `additional_data` carries `ip_country_code` (ISO-3), `ip_country`, `ip_state`, and `restricted_by` (`country` or `state`). State/region entries override the country flag and are matched case-insensitively against the IP provider's region name (e.g. `"California"`); countries not listed in the config are allowed.

## Device and runtime integrity

Signals reported by the native SDKs and the web client describing the state of the device the verification ran on. They exist to detect injection attacks: an attacker who can root a device or hook the app process can replace the camera feed before it ever reaches the biometric checks.

Every one is configurable per workflow and defaults to **no action**, so enabling the feature changes no decisions until you opt in.

| Risk                               | Cause                                                                                                                                                             | Config key                        | Default     |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- | ----------- |
| `DEVICE_APP_TAMPERED`              | Platform attestation failed to verify that the request came from a genuine, unmodified build of the application on a genuine device.                              | `device_app_tampered_action`      | `NO_ACTION` |
| `DEVICE_RUNTIME_HOOKING_DETECTED`  | A runtime instrumentation or hooking framework (Frida, Xposed, LSPosed, Substrate) was detected in the application process.                                       | `device_hooking_action`           | `NO_ACTION` |
| `DEVICE_ROOTED_OR_JAILBROKEN`      | The device shows root or jailbreak indicators, which remove the operating-system protections that prevent camera interception.                                    | `device_rooted_action`            | `NO_ACTION` |
| `DEVICE_EMULATOR_DETECTED`         | The session originated from an emulator or simulator rather than a physical device.                                                                               | `device_emulator_action`          | `NO_ACTION` |
| `DEVICE_DEBUGGER_ATTACHED`         | A debugger or process tracer was attached to the application during the verification.                                                                             | `device_debugger_action`          | `NO_ACTION` |
| `AUTOMATION_FRAMEWORK_DETECTED`    | The session was driven by a browser automation framework or headless browser rather than by a person.                                                             | `automation_detected_action`      | `NO_ACTION` |
| `DEVICE_INTEGRITY_SIGNALS_MISSING` | The client reported an SDK version that supports integrity reporting, but no integrity signals arrived — which can indicate the signals were stripped in transit. | `device_integrity_missing_action` | `NO_ACTION` |

<Note>
  Each probe is best-effort. When a check cannot run it reports **not determined** rather than a clean result, so a failing probe never produces a false positive against a legitimate user. Signals are reported from native SDK **4.4.0** onwards; sessions from earlier SDKs legitimately send nothing and never raise `DEVICE_INTEGRITY_SIGNALS_MISSING`.
</Note>

<Warning>
  Root and emulator signals are common among legitimate users on modified but non-fraudulent devices. Start these on Review rather than Decline and watch your own decline rate before tightening.
</Warning>

## Configurable settings

Per-node workflow controls (also configurable globally on the application's verification settings; every action defaults to **No action** unless noted):

| Setting                       | Drives                                                 | Default   |
| ----------------------------- | ------------------------------------------------------ | --------- |
| `vpn_detection_action`        | `PRIVATE_NETWORK_DETECTED`                             | No action |
| `ip_mismatch_action`          | `COUNTRY_FROM_DOCUMENT_DOES_NOT_MATCH_COUNTRY_FROM_IP` | No action |
| `expected_ip_mismatch_action` | `EXPECTED_IP_ADDRESS_MISMATCH`                         | No action |
| `duplicated_ip_action`        | `DUPLICATED_IP_ADDRESS`                                | No action |
| `duplicated_device_action`    | `DUPLICATED_DEVICE_FINGERPRINT`                        | No action |
| `recovered_device_action`     | `DEVICE_RECOVERED_HIGH_CONFIDENCE`                     | No action |
| `ip_geofencing_action`        | `IP_LOCATION_NOT_ALLOWED`                              | Decline   |

IP and device allowlists suppress only the exact duplicate-IP or deterministic duplicate-device warning for the allowlisted value. They do not suppress VPN/proxy, country mismatch, expected-IP mismatch, recovered-device, or blocklist warnings.

Recovered-device warnings are useful for detecting fraud rings that rotate accounts and sessions from the same hardware, but Didit is conservative by design — the system prefers missing some duplicate users over merging unrelated devices when the evidence is not strong enough. **Recommended rollout**: start with Review, watch the volume for two weeks, then tighten the action if your false-positive rate is low.

## Duplicate device vs. recovered device

Treat the two warnings differently — they trigger on different evidence:

| Warning                            | Trigger                                                                                            | Typical meaning                                                                                                                    | Recommended first action                                             |
| ---------------------------------- | -------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------- |
| `DUPLICATED_DEVICE_FINGERPRINT`    | Exact persistent device identity (`persistent_id`) or legacy fingerprint hash (`legacy_fp`) match. | Strong evidence that the same device appears across different users.                                                               | Review or Decline, depending on your fraud tolerance.                |
| `DEVICE_RECOVERED_HIGH_CONFIDENCE` | High-confidence v2 recovery (`recovered_high`) after storage, session, or app identity changed.    | Strong signal for incognito / storage-reset / app-reinstall attempts. Intentionally separated so you can monitor it independently. | Review first, then tighten after measuring your false-positive rate. |

## Cross-session matches

When the same IP address, exact device identity, or recovered device is detected across sessions belonging to **different users**, Didit records these as `matches[]` on `ip_analyses[]`. Sessions are grouped by `vendor_data`: sessions with the same `vendor_data` are treated as the same user and excluded from matches. Without `vendor_data`, every session is treated as a unique user and all potential duplicates are surfaced — we strongly recommend always providing `vendor_data` to reduce noise.

Each match includes:

* `session_id`, `session_number`, `vendor_data`, and `verification_date` of the matching session, plus its lifecycle `status` and `api_service` (`null` for workflow sessions); `source` is always `session`
* `match_type` — `ip_address` or `device_fingerprint`
* `match_source` — `ip_address`, `persistent_id`, `legacy_fp`, or `recovered_high`
* `matched_value` — the shared IP, the device identifier, or (for recovered matches) the recovered device UUID
* `confidence` (0–1, `1 - P(false positive)`) and `match_mode` (`deterministic` / `probabilistic` / `co_occurrence`)
* `device_info` — `device_brand`, `device_model`, `browser_family`, `os_family`, `platform`, `device_fingerprint`
* `location_info` — `ip_address`, `ip_country`, `ip_country_code`, `ip_state`, `ip_city`, `is_vpn_or_tor`, `is_data_center`
* Recovered-device extras when `match_source` is `recovered_high`: `recovery_similarity`, `tls_ja4_corroborated`, `recovery_gate_reason`

IP matches and device matches are capped at 5 each (at most 10 entries). See the [report page](/core-technology/ip-analysis/report-ip-analysis#match-semantics) for the full match schema and confidence model.

## Examples

### VPN + country mismatch (configured to Review)

```json theme={null}
{
  "warnings": [
    {
      "feature": "LOCATION",
      "risk": "PRIVATE_NETWORK_DETECTED",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "Private network (VPN/Tor) detected",
      "long_description": "The system detected that the user tried to use a private network (VPN/TOR) to complete the verification process.",
      "node_id": "ip-1"
    },
    {
      "feature": "LOCATION",
      "risk": "COUNTRY_FROM_DOCUMENT_DOES_NOT_MATCH_COUNTRY_FROM_IP",
      "additional_data": { "document_country_code": "ESP", "ip_country_code": "NLD" },
      "log_type": "warning",
      "short_description": "Document country does not match IP country",
      "long_description": "The country from the document does not match the country from the IP address, suggesting a potential mismatch between the document and the user's location.",
      "node_id": "ip-1"
    }
  ]
}
```

### Blocklist hit (forces decline)

```json theme={null}
{
  "warnings": [
    {
      "feature": "LOCATION",
      "risk": "IP_ADDRESS_IN_BLOCKLIST",
      "additional_data": { "ip_address": "45.61.20.5" },
      "log_type": "error",
      "short_description": "IP address in blocklist",
      "long_description": "The IP address used for this session was found in the application's IP blocklist, indicating a known suspicious or forbidden origin.",
      "node_id": "ip-1"
    }
  ]
}
```

### Recovered-device high confidence (configured to Review)

```json theme={null}
{
  "warnings": [
    {
      "feature": "LOCATION",
      "risk": "DEVICE_RECOVERED_HIGH_CONFIDENCE",
      "additional_data": {
        "duplicated_session_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
        "duplicated_session_number": 5101,
        "api_service": null,
        "match_source": "recovered_high",
        "recovery_similarity": 0.9874,
        "recovery_match_device_uuid": "f47ac10b-58cc-4372-a567-0e02b2c3d479"
      },
      "log_type": "warning",
      "short_description": "Device matches a previously seen device with high confidence",
      "long_description": "A previously seen device matched this session with high confidence through v2 fuzzy fingerprint recovery after passing strict hard gates, indicating the same physical device under a fresh persistent_id.",
      "node_id": "ip-1"
    }
  ]
}
```

## Related

* [Device & IP analysis report](/core-technology/ip-analysis/report-ip-analysis) — full response shape and status semantics
* [Device & IP analysis overview](/core-technology/ip-analysis/overview) — what each block measures
* [Data models — IP analysis](/reference/data-models#ip-analysis) — canonical schema
* [Webhooks](/integration/webhooks) — `status.updated` carries IP analysis warnings

### Warning types

<WarningTypes />


# Cross-organization identity claims
Source: https://docs.didit.me/core-technology/liveness/cross-organization-identity-claims

How Didit reports identity evidence from other organizations without ever labelling a person as fraudulent — separate result dimensions, claim-scoped evidence, and the default-off sharing switch.

## The rule this page exists for

A face is a stable identity. It is not a fraud label, and Didit will not treat it as one.

That distinction matters most in the case that motivated it: a real, consenting person attempts
to verify under an identity that is not theirs. The attempt must be stopped. But three separate
people must be left alone afterwards — that same person when they later verify with their own
valid identity, the person whose identity was borrowed (who is the victim, not the offender),
and anyone whose face merely looks similar.

So fraud meaning is attached to an **identity claim**, which is an event, never to the person
who made it or to the identity they claimed.

## Four dimensions, four fields

A decision is never collapsed into one word chosen on your behalf. Each of these is reported
independently, and you decide what your product does with the combination:

| Dimension                          | What it answers                                                                     | Where it appears                                                         |
| ---------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------------------------------------ |
| **Input integrity**                | Was the capture live, unmodified and from a real camera?                            | Liveness warnings (`LIVENESS_FACE_ATTACK`, `VIRTUAL_CAMERA_DETECTED`, …) |
| **Identity match**                 | Did the person match the identity they claimed, against a trusted reference?        | Face match and duplicate-face warnings on the session                    |
| **Behaviour and network evidence** | Have other organizations seen claim events for this same person that did not match? | `CROSS_ORG_IDENTITY_CLAIM_PATTERN`                                       |
| **Final decision**                 | What the session's status became                                                    | `status` on the decision payload                                         |

A failed liveness check, an identity mismatch and a network pattern are three different
statements about three different things. Reading them as one number is how a bad photo turns
into an accusation.

### Identity match needs a trusted reference

`match` and `mismatch` are only produced when there is something trustworthy to compare a face
against — a government document portrait, or an identity already strongly bound to that face.
An email address or a phone number with no prior strong binding gives you nothing to compare a
face to. In that case the answer is **no reference**, never `mismatch`, and never a `match`
inferred from face history alone.

## What cross-organization evidence can and cannot say

When cross-organization sharing is enabled for your organization, a session can raise
`CROSS_ORG_IDENTITY_CLAIM_PATTERN`. It means:

> Other participating organizations recorded identity-claim events for this same person in
> which the claimed identity did not match the evidence on those sessions.

It does **not** mean the person is fraudulent, and no Didit response will ever say that. Three
guarantees back this up:

* **It is suppressed when your own check passed.** If this session's own identity match is
  `match`, the warning is not raised at all. A person who verifies successfully against their
  own trusted reference is verified — whatever they may have been involved in before belongs
  to those claims, not to this one.
* **It cannot decline.** The action is Review or No action. Setting Decline on
  `cross_org_identity_claim_pattern_action` is downgraded to Review, because history about a
  person may open an investigation into the current claim but may never reject it.
* **It is aggregate only.** The payload carries how many organizations, how many mismatched
  claims, how many distinct identities were claimed and how recent — never who they are, never
  their sessions, never any of their data.

`CROSS_ORG_FRAUD_FACE` is the retired version of this warning and is no longer raised. It is
kept as a value so existing logs and rules keep resolving; historical occurrences are records,
not judgments about a person.

## Face-only lookup: a person id, not a verdict

Recognising the same human being again is a separate capability from deciding anything about
them. A face-only lookup returns a **stable opaque person id** for high-confidence repeat
captures of the same face, and nothing else.

* The id is a random identifier. It is not derived from a face, an embedding, a session, an
  organization or a customer reference, so it discloses nothing beyond "this capture was seen
  before".
* It carries no fraud state. There is no field on it that could.
* A low-confidence or possible match never merges two people. Over-merging fuses two human
  beings into one identity and cannot be undone from the data; under-merging only costs recall.

## Multi-account detection is same-organization and segmented

"Has this face opened several accounts with **us**" is a different product question from
cross-organization evidence, and it is answered inside your own organization only.

Set `multi_account_segment` on session create to give that search an explicit realm. Two
sessions in different segments are never duplicates of each other, which is what lets you run
separate personal and business account bases — or one segment per sub-client — without a person
who legitimately holds one account in each looking like account farming. Omit it and every
session sits in the single default realm, which is exactly today's behaviour.

Blocklist and allowlist matching deliberately ignore segments: a blocklisted face is
blocklisted everywhere in your organization, so a segment can never be used to escape one.

## Privacy

* Faces never cross the organization boundary. The shared fraud index physically cannot hold
  one — the database rejects the write.
* What does cross the boundary is a one-way keyed hash of an exact value (a document number, a
  device, an IP, a phone, an email) that a participating organization labelled as fraud.
* Cross-organization reads answer with counts and recency buckets. The contributing
  organization is never named, and no raw value, image or session ever leaves.
* Sharing is reciprocal and opt-in: an organization that does not contribute does not query.
* Cross-organization **face** intelligence specifically is off by default and stays off until
  the data-protection impact assessment and legal review for the biometric-person identifier
  and the claim-event model are complete.


# Liveness Detection
Source: https://docs.didit.me/core-technology/liveness/overview

Detect deepfakes, masks, and presentation attacks with passive and active liveness. 99.9% accuracy, iBeta-tested, pay-per-call from $0.10.

Didit's Liveness Detection solution provides enterprise-grade biometric verification through advanced computer vision and machine learning algorithms. Our system achieves **99.9% accuracy** with a false acceptance rate (FAR) of less than **0.1%**, ensuring robust protection against spoofing attacks.

<AgentPromptAccordion title="Liveness Integration Prompt" />

The Academy lesson on the hosted user flow reaches the liveness selfie at 8:49, followed at 9:16 by the passive, 3D flash, and 3D action methods.

<VideoEmbed title="The liveness selfie — Didit Academy" />

## Liveness Detection Methods

Our platform implements three distinct anti-spoofing technologies, each tailored to different security needs and user experiences:

<table>
  <thead>
    <tr>
      <th>Method</th>
      <th>Description</th>
      <th>Security Level</th>
      <th>Best For</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td>**`3D Action & Flash`**</td>

      <td>
        • Combines multi-factor biometric verification with a **randomized action sequence** and **dynamic light pattern analysis**.<br />
        • At the start, the user is prompted to perform a simple action—like **blinking** or **nodding**—ensuring real-time interaction.<br />
        • Simultaneously, the system projects a sequence of light patterns onto the face, analyzing the **reflections** to confirm the face's three-dimensional structure.<br />
        • **Deep learning algorithms** examine micro-expressions and the light reflection responses to verify the presence of a live person.<br />
        • Offers the **highest security** by integrating behavioral (action) and physical (light-based depth) cues, making it nearly impossible to spoof with static images, videos, or even advanced masks.
      </td>

      <td>Highest</td>
      <td>Banking, healthcare, government applications</td>
    </tr>

    <tr>
      <td>**`3D Flash`**</td>

      <td>
        • Uses **dynamic light pattern analysis** to validate facial topology without requiring user interaction.<br />
        • Projects a series of light patterns onto the face at over **30 frames per second**, analyzing the reflections to create a **depth map**.<br />
        • This depth map confirms the face's three-dimensional structure, distinguishing it from flat images or 2D spoofs.<br />
        • Provides a **seamless experience** while maintaining **high security** against presentation attacks like photos or screens.<br />
      </td>

      <td>High</td>
      <td>Financial services, account access, identity verification</td>
    </tr>

    <tr>
      <td>**`Passive Liveness`**</td>

      <td>
        • Relies on **single-frame deep learning analysis** to detect signs of liveness.<br />
        • Examines the image for **artifacts**, **texture patterns**, and other subtle indicators that differentiate a real face from a spoof.<br />
        • A **convolutional neural network (CNN)** validates facial features and identifies anomalies, such as those from printed photos or digital screens.<br />
        • Offers **fast and convenient** verification but provides **standard security**, suitable for low-risk use cases.<br />
      </td>

      <td>Standard</td>
      <td>Low-friction scenarios, consumer applications</td>
    </tr>
  </tbody>
</table>

<Note>
  **Advanced Security of 3D Flash and 3D Action & Flash:**

  > * These methods are engineered to defeat **sophisticated spoofing attacks**, such as **high-quality masks**, **deepfakes**, and **video replays**.
  > * By projecting dynamic light patterns and analyzing their reflections, they detect how light interacts with a **real 3D face** versus a flat or artificial surface.
  > * The **3D Action & Flash** method adds an extra layer of security with a randomized action (e.g., blink or nod), requiring **real-time behavioral responses** that pre-recorded media or synthetic identities cannot replicate.
  > * Proven to deliver **high accuracy** and **low false acceptance rates**, these methods are ideal for high-stakes environments.
</Note>

Each method generates a **normalized liveness score (0-100%)** based on our proprietary algorithm, which evaluates multiple security factors in real time.

### Configurable Thresholds

You can customize security levels by setting different thresholds for liveness scores. For example:

<Frame>
  <img alt="Didit liveness detection threshold configuration for passive and active anti-spoofing" />
</Frame>

<Note>
  These thresholds can be adjusted based on your **risk tolerance** and **security requirements**, offering flexibility across use cases.
</Note>

## Retries & actionable feedback

In a Didit session, a liveness capture that fails for a **fixable reason** (poor lighting, face not centered, occlusion, a borderline score) does not immediately decline. The user is asked to **retry with specific guidance**, up to a configurable number of attempts.

* **Attempt budget** — `face_liveness_max_attempts` controls the total number of liveness submissions per session. Default **3** (one initial attempt plus two retries), configurable per workflow node (range 1–3).

* **Retry feedback** — while attempts remain, a retryable failure keeps the user on the liveness step and returns a body carrying actionable `feedback_codes` (the Web and Mobile SDKs surface these as coaching messages automatically):

  ```json theme={null}
  {
    "detail": "Move to a brighter, evenly lit place and try again.",
    "error": "LOW_FACE_LUMINANCE",
    "feedback_codes": ["LOW_FACE_LUMINANCE"],
    "attempts_used": 1,
    "max_attempts": 3
  }
  ```

* **Retryable codes** — `LOW_FACE_LUMINANCE` (too dark), `HIGH_FACE_LUMINANCE` (too bright), `NO_FACE_DETECTED`, `LOW_FACE_QUALITY`, `HIGH_FACE_OCCLUSION`, `LOW_LIVENESS_SCORE`, `MULTIPLE_FACES_DETECTED`, `AGE_NOT_DETECTED`.

* **Guaranteed retry for capture conditions** — `LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE`, `LOW_FACE_QUALITY`, `HIGH_FACE_OCCLUSION` and `NO_FACE_DETECTED` describe the room the user is standing in, not the person. When an attempt fails on those codes alone, the user always gets a second attempt with the coaching message above, even on a workflow configured with `face_liveness_max_attempts: 1`. Every other code still follows the configured budget exactly.

* **Exhaustion & fraud** — once the budget is exhausted the computed status is applied (`Declined` or `In Review`). Confirmed presentation attacks (`LIVENESS_FACE_ATTACK`), blocklist hits and duplicate faces **decline immediately** and are never retried.

<Note>
  Retries apply to the **session flow** only. The standalone `POST /v3/passive-liveness/` endpoint is stateless and single-shot — it returns the result directly with no retry budget.
</Note>

## How It Works

<Steps>
  <Step title="Video Selfie Capture" icon="camera">
    The user is guided through a **simple, intuitive interface** tailored to the selected liveness method.

    | Check                  | Description                                                          |
    | ---------------------- | -------------------------------------------------------------------- |
    | **Real-time feedback** | Ensures proper lighting, positioning, and framing                    |
    | **Quality checks**     | Monitors for blur, glare, and optimal facial visibility              |
    | **Adaptive capture**   | Adjusts to various device capabilities and network conditions        |
    | **Method guidance**    | Shows method-specific instructions (e.g., "Blink now" for 3D Action) |
  </Step>

  <Step title="Liveness Detection Analysis" icon="microchip-ai">
    Advanced algorithms process the captured media in **real time** to detect spoofing attempts. The analysis differs per method:

    <AccordionGroup>
      <Accordion title="3D Action & Flash" icon="shield-check">
        * Verifies the user's action (e.g., **blink** or **nod**) to confirm it's performed correctly and live
        * Analyzes **light pattern reflections** to validate the face's three-dimensional structure
        * Uses deep learning to assess **micro-expressions** and other behavioral cues
        * Combines behavioral + physical signals for the **strongest spoof resistance**
      </Accordion>

      <Accordion title="3D Flash" icon="bolt">
        * Processes a sequence of **light pattern reflections** at 30+ FPS to build a detailed **depth map**
        * Confirms the face's 3D properties, distinguishing it from flat or 2D spoofs
        * No user interaction required — fully **passive from the user's perspective**
      </Accordion>

      <Accordion title="Passive Liveness" icon="image">
        * Applies **deep learning** to a single frame to detect **texture patterns** and **artifacts**
        * A convolutional neural network (CNN) validates facial features and identifies anomalies
        * Fastest method — works with a **single photo capture**
      </Accordion>
    </AccordionGroup>

    Multi-layered detection identifies **presentation attacks** including photos, screens, masks, and deepfakes.
  </Step>

  <Step title="Result Processing & Verification" icon="chart-simple">
    The system compares the liveness score against your **configured thresholds** and delivers results instantly.

    | Output              | Description                                                            |
    | ------------------- | ---------------------------------------------------------------------- |
    | **Liveness score**  | Normalized 0–100% confidence score                                     |
    | **Decision**        | Approved, Declined, or In Review based on your thresholds              |
    | **Method**          | Which liveness method was used (`passive`, `flash`, `action_flash`)    |
    | **Reference image** | Captured frame used for the liveness check                             |
    | **Warnings**        | Any anomalies detected (e.g., low quality, potential spoof indicators) |

    Results are delivered via **API response**, **webhook**, or viewable in the **Business Console** with detailed audit logs for compliance.
  </Step>
</Steps>

<Tip>
  You can configure which liveness method to use per workflow in the [Business Console](/console/workflows). Different workflows can use different methods depending on your risk requirements.
</Tip>


# Liveness report
Source: https://docs.didit.me/core-technology/liveness/report-liveness

Read Didit's Liveness report: status, confidence score, detection method, age estimation, cross-session face matches, and where it appears in responses.

## Overview

The **liveness report** captures everything Didit observed while verifying that a real, live person was in front of the camera — not a printed photo, screen replay, or deepfake. It includes the liveness method, a 0–100 confidence score, the reference selfie and capture video, an optional age estimate, passive-liveness quality metrics, and cross-session face matches against your application's history and blocklist.

The report is produced after the user completes the liveness step in a workflow (or hits the standalone face endpoint). Didit runs one of three liveness methods (active 3D, flashing, or passive), scores the capture, screens for known spoof patterns, and compares the face biometrically against every other face you've seen in your application.

Each report carries its own `status` — independent of the overall session status — that reflects how the liveness step alone resolved:

* **Approved** — face detected, liveness score above the review threshold, no auto-decline warning fired.
* **In Review** — one or more warnings routed to review fired, or the score is at or below the review threshold but above the decline threshold.
* **Declined** — an auto-decline condition fired (`NO_FACE_DETECTED`, `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, or the age risks on age-estimation flows), a configurable warning was routed to decline, or the score is at or below the decline threshold.
* **Not Finished** — the user never completed the liveness step.

## Where it appears in API responses

The liveness report appears as `liveness_checks[]` in `GET /v3/session/{sessionId}/decision/` — **always a JSON array**, never a singular `liveness` object. Multiple entries appear when a workflow runs liveness more than once (for example a primary check plus a re-capture).

* **Session decision API** — `GET /v3/session/{sessionId}/decision/` returns `liveness_checks[]` at the top level. See [Retrieve session decision](/sessions-api/retrieve-session).
* **Webhooks** — `session.status.updated` payloads include the same `liveness_checks[]` array once the step has produced data. See [Webhooks](/integration/webhooks).
* **Standalone liveness API** — see [Liveness standalone API](/standalone-apis/passive-liveness).

<Note>
  Read `response.liveness_checks[0]` and iterate the array — the singular `liveness` shape some older tutorials referenced does not exist on the v3 decision endpoint.
</Note>

## Schema

The canonical field-by-field schema lives on the [Data models](/reference/data-models#liveness-check) reference page. The fields below mirror that canonical schema.

| Field             | Type                                                                             | Description                                                                                                                                                                                                                                                                                |
| ----------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `status`          | `"Approved" \| "Declined" \| "In Review" \| "Not Finished" \| "Resub Requested"` | Liveness-step status (see below).                                                                                                                                                                                                                                                          |
| `node_id`         | string \| null                                                                   | Workflow graph node that produced this report.                                                                                                                                                                                                                                             |
| `method`          | `"ACTIVE_3D" \| "FLASHING" \| "PASSIVE"`                                         | The liveness method that produced this capture.                                                                                                                                                                                                                                            |
| `score`           | number 0–100 \| null                                                             | Liveness confidence score, rounded to 2 decimals.                                                                                                                                                                                                                                          |
| `reference_image` | string (signed URL) \| null                                                      | Reference selfie extracted from the capture. Signed URL with a limited validity window.                                                                                                                                                                                                    |
| `video_url`       | string (signed URL) \| null                                                      | Full liveness capture video (active methods). Signed URL with a limited validity window.                                                                                                                                                                                                   |
| `age_estimation`  | number \| null                                                                   | Estimated age in years of the largest face in the reference image.                                                                                                                                                                                                                         |
| `face_quality`    | number 0–100 \| null                                                             | Passive-liveness face quality, normalized to a percentage. Populated only when `method = "PASSIVE"`.                                                                                                                                                                                       |
| `face_luminance`  | number 0–100 \| null                                                             | Passive-liveness facial luminance, normalized from 0–255 to a percentage. Populated only when `method = "PASSIVE"`.                                                                                                                                                                        |
| `matches[]`       | array                                                                            | Cross-session face matches (see below).                                                                                                                                                                                                                                                    |
| `warnings[]`      | array                                                                            | Module-level warnings — see [Liveness warnings](/core-technology/liveness/warnings-liveness). Each entry follows the [Warning object](/reference/data-models#warning-object) shape (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`). |

### Cross-session face matches

`matches[]` lists the faces in your application's history that exceeded the biometric similarity threshold against this selfie — up to 5 entries, blocklisted and allowlisted faces first, then by descending similarity. Eligible candidates are blocklisted faces, allowlisted faces, faces from `Approved` sessions, and faces imported against your vendor users. Faces belonging to the same user (same `vendor_data`, or the same vendor-user when available) are excluded from the **entire** search — both duplicate detection and blocklist screening.

Each entry includes:

| Field                   | Type                                      | Description                                                                                                                                                                                        |
| ----------------------- | ----------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session_id`            | string (UUID) \| null                     | The matched session. `null` when `source` is `imported` or `list_entry`.                                                                                                                           |
| `session_number`        | number \| null                            | Sequential session number for the matched session. `null` for non-session sources.                                                                                                                 |
| `similarity_percentage` | number 0–100                              | Biometric similarity score, clamped to 0–100.                                                                                                                                                      |
| `vendor_data`           | string \| null                            | Your reference data from the matched session (or vendor user, for imported faces).                                                                                                                 |
| `verification_date`     | string (ISO 8601) \| null                 | When the matched session (or imported face) was created.                                                                                                                                           |
| `user_details`          | object \| null                            | `{ full_name, document_type, document_number }` from the matched session's KYC. Imported faces populate `full_name` only (the two document fields are `null`); `null` when no details are on file. |
| `match_image_url`       | string (signed URL) \| null               | Reference face from the matched session, imported face, or list entry.                                                                                                                             |
| `status`                | string \| null                            | Status of the matched session (e.g. `"Approved"`). `null` for non-session sources.                                                                                                                 |
| `is_blocklisted`        | boolean                                   | `true` when the matched face is on your face blocklist.                                                                                                                                            |
| `is_allowlisted`        | boolean                                   | `true` when the matched face is on your face allowlist (duplicate-face actions are skipped).                                                                                                       |
| `api_service`           | string \| null                            | Set when the matched face came from a standalone API call (e.g. `"PASSIVE_LIVENESS"`); `null` for workflow sessions and non-session sources.                                                       |
| `source`                | `"session" \| "imported" \| "list_entry"` | Where the matched face came from: another verification session, a face uploaded against a vendor user, or an org-managed allow/block list face.                                                    |

## Status values

Statuses come from the shared feature-status enum (`FeatureStatusChoices`).

| Status            | Meaning                                                                                                                                                                                                                                  | Downstream effect                                                          |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| `Approved`        | Face detected, liveness score above the review threshold, no auto-decline warning fired.                                                                                                                                                 | Counts as a successful liveness check.                                     |
| `In Review`       | Score at or below the review threshold but above the decline threshold, or a warning routed to review fired.                                                                                                                             | Session also moves to `In Review` until a reviewer acts.                   |
| `Declined`        | An auto-decline risk fired (`NO_FACE_DETECTED`, `LIVENESS_FACE_ATTACK`, `FACE_IN_BLOCKLIST`, or the age risks on age-estimation flows), a configurable warning was routed to decline, or the score is at or below the decline threshold. | Session is declined unless another approved branch satisfies the workflow. |
| `Not Finished`    | User abandoned the liveness step (or a retryable capture failure is awaiting another attempt).                                                                                                                                           | The liveness branch did not produce a result.                              |
| `Resub Requested` | A reviewer requested resubmission of this step from the console.                                                                                                                                                                         | Transient — replaced once the user re-captures.                            |

## Examples

### Approved — clean active-3D capture

```json theme={null}
{
  "liveness_checks": [
    {
      "status": "Approved",
      "node_id": "liveness_primary",
      "method": "ACTIVE_3D",
      "score": 92.4,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": "https://<media-host>/.../liveness.mp4?signature=...",
      "age_estimation": 24.3,
      "face_quality": null,
      "face_luminance": null,
      "matches": [],
      "warnings": []
    }
  ]
}
```

### In Review — passive liveness, low-quality capture and a possible duplicate

```json theme={null}
{
  "liveness_checks": [
    {
      "status": "In Review",
      "node_id": "liveness_primary",
      "method": "PASSIVE",
      "score": 76.1,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": null,
      "age_estimation": 31.0,
      "face_quality": 12.4,
      "face_luminance": 18.7,
      "matches": [
        {
          "session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
          "session_number": 123,
          "similarity_percentage": 96.8,
          "vendor_data": "user-555",
          "verification_date": "2024-07-15T10:23:45Z",
          "user_details": {
            "full_name": "John Smith",
            "document_type": "Passport",
            "document_number": "SAMPLE-DOC-12345"
          },
          "match_image_url": "https://<media-host>/.../matched.jpg?signature=...",
          "status": "Approved",
          "is_blocklisted": false,
          "is_allowlisted": false,
          "api_service": null,
          "source": "session"
        }
      ],
      "warnings": [
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_QUALITY",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face quality",
          "long_description": "The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "LOW_FACE_LUMINANCE",
          "additional_data": null,
          "log_type": "warning",
          "short_description": "Low face luminance",
          "long_description": "The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.",
          "node_id": "liveness_primary"
        },
        {
          "feature": "LIVENESS",
          "risk": "POSSIBLE_DUPLICATED_FACE",
          "additional_data": {
            "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
            "duplicated_session_number": 123,
            "api_service": null
          },
          "log_type": "warning",
          "short_description": "Possible duplicated face from other approved session",
          "long_description": "The system identified a possible duplicate face from another approved session, requiring further investigation.",
          "node_id": "liveness_primary"
        }
      ]
    }
  ]
}
```

Here the face quality (12.4) sits below the default review threshold (15), the luminance (18.7) sits below the default minimum (20), and the workflow's duplicate-face action is set to Review — so all three warnings carry `log_type: "warning"` and the report resolves to `In Review`.

## Security note

Liveness videos and selfies are biometric data — the signed URLs are temporary and expire (after 4 hours by default). Treat them as short-lived: do not cache or surface them publicly. Typically your application only needs `status`, `score`, and the warnings — store as little as possible to minimize biometric data on your servers.

## Related

* [Liveness warnings](/core-technology/liveness/warnings-liveness) — full warning enum, causes, and remediation.
* [Webhooks](/integration/webhooks) — listen for `session.status.updated` to receive the report.
* [Data models — Liveness check](/reference/data-models#liveness-check) — canonical schema with every field.
* [Face match report](/core-technology/face-match/report-face-match) — the companion 1:1 face match against the document portrait.


# Liveness warnings
Source: https://docs.didit.me/core-technology/liveness/warnings-liveness

Every warning Didit's liveness module emits — face attacks, low-score and quality triggers, blocklist matches, duplicate faces — with cause and remediation.

## Overview

Warnings on the liveness report flag every condition Didit observed while running the liveness check. They land in the `warnings[]` array on each item of `liveness_checks[]` (see [Liveness report](/core-technology/liveness/report-liveness)), with `feature` set to `"LIVENESS"`. Each entry follows the shared [warning object](/reference/data-models#warning-object) shape: `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`.

Every warning has three layers:

1. **The `risk` code** — a stable identifier you can match on in your code (the codes listed below).
2. **The `log_type`** — one of `information`, `warning`, or `error`. Auto-decline risks always carry `error`. For configurable risks it is derived from the configured action: **No action** → `information`, **Review** → `warning`, **Decline** → `error`. For threshold-driven risks (`LOW_LIVENESS_SCORE`, `LOW_FACE_QUALITY`) it is `error` when the value crosses the decline threshold and `warning` when it only crosses the review threshold.
3. **The decision impact** — the same routing drives the liveness report's `status`: a Review action moves it to `In Review`, a Decline action (or any auto-decline risk) to `Declined`, and No action leaves it untouched.

Some risks are emitted only when the liveness method is `PASSIVE` (multiple-faces, quality, and luminance checks). The tables below list the full set of liveness risk codes and their severities — no other liveness risk codes exist.

## Auto-decline conditions

The following risks always force the liveness report (and the session) to `Declined`, with `log_type: "error"`:

| Risk                   | Trigger                                                                                                                     |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `NO_FACE_DETECTED`     | No face was located during the liveness capture, or the user exhausted retry attempts.                                      |
| `LIVENESS_FACE_ATTACK` | The model detected a presentation attack (mask, screen replay, deepfake-class spoof).                                       |
| `FACE_IN_BLOCKLIST`    | The face matched an entry on your application's face blocklist.                                                             |
| `AGE_BELOW_MINIMUM`    | Estimated age below the configured minimum. Only emitted on adaptive age-verification workflows and `AGE_ESTIMATION` nodes. |
| `AGE_NOT_DETECTED`     | Age could not be estimated. Only emitted on age-estimation flows with ID-verification fallback disabled.                    |

When `NO_FACE_DETECTED` fires, `LOW_LIVENESS_SCORE` is suppressed (there is no face to score).

## Configurable verification settings

In the Didit console, liveness risks are grouped under the following workflow settings:

| Group                                                             | Risks                                         | Configuration                                                                                                                                                                                            |
| ----------------------------------------------------------------- | --------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Liveness score thresholds**                                     | `LOW_LIVENESS_SCORE`                          | Review threshold + decline threshold on `score`. At or below review → `In Review`; at or below decline → `Declined`.                                                                                     |
| **Duplicate face action**                                         | `DUPLICATED_FACE`, `POSSIBLE_DUPLICATED_FACE` | One shared setting: No action (default) / Review / Decline. Skipped entirely when the matching face is in your face allowlist.                                                                           |
| **Duplicate face identity mismatch**                              | `DUPLICATED_FACE_NAME_MISMATCH`               | Own setting (`face_liveness_duplicated_face_name_mismatch_action`): No action / Review (default) / Decline. Only evaluated when `DUPLICATED_FACE` also fires — see below.                                |
| **Possible blocklisted face**                                     | `POSSIBLE_FACE_IN_BLOCKLIST`                  | Not configurable in workflows — always routed to Review (`log_type: "warning"`).                                                                                                                         |
| **Multiple faces action** *(passive only)*                        | `MULTIPLE_FACES_DETECTED`                     | No action (default) / Review / Decline.                                                                                                                                                                  |
| **Face quality thresholds** *(passive only)*                      | `LOW_FACE_QUALITY`                            | Review threshold (default 15) + decline threshold (default 0, i.e. decline disabled).                                                                                                                    |
| **Face luminance** *(passive only)*                               | `LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE`   | Min / max thresholds (defaults 20 / 80 on the normalized 0–100 scale) + a per-direction action (default Review).                                                                                         |
| **Age thresholds** *(adaptive workflows / `AGE_ESTIMATION` node)* | `AGE_BELOW_MINIMUM`, `AGE_NOT_DETECTED`       | Minimum and borderline age thresholds; both risks auto-decline the liveness step. With ID-verification fallback enabled, the workflow routes the user to a document check instead of ending the session. |

## Warnings produced

### Core liveness

| Risk                   | Cause                                                                                                    | Severity                                                                            | Affects status?                            | Remediation                                                 |
| ---------------------- | -------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------- |
| `NO_FACE_DETECTED`     | No face located during the capture, or the user exhausted retry attempts (`MAX_ATTEMPTS_REACHED`).       | `error`                                                                             | **Auto-decline**                           | Re-capture in better lighting; ensure the face is centered. |
| `LIVENESS_FACE_ATTACK` | Model detected a presentation attack.                                                                    | `error`                                                                             | **Auto-decline**                           | Treat as fraud. The session is automatically declined.      |
| `LOW_LIVENESS_SCORE`   | `score` at or below the workflow's review threshold. Suppressed when `NO_FACE_DETECTED` is also present. | `warning`; escalates to `error` when the score is at or below the decline threshold | Configurable (review / decline thresholds) | Re-capture; tune thresholds if you observe false positives. |

### Capture channel integrity

Injection-attack signals reported by the client at capture time. Unlike presentation attacks (an artefact held in front of a real camera), these describe the camera feed itself being replaced or intercepted.

Each is configurable per workflow and defaults to **no action**, so enabling the feature changes no decisions until you opt in.

| Risk                               | Cause                                                                                                                                           | Config key                       | Default     |
| ---------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------- | ----------- |
| `VIRTUAL_CAMERA_DETECTED`          | The capture device was identified as a software virtual camera (OBS, ManyCam, Snap Camera, DroidCam and similar) rather than a physical camera. | `virtual_camera_action`          | `NO_ACTION` |
| `EXTERNAL_CAPTURE_DEVICE_DETECTED` | The capture device was an external camera or a capture card rather than a built-in camera.                                                      | `external_capture_device_action` | `NO_ACTION` |
| `FRAME_INJECTION_SUSPECTED`        | The captured frames show indicators of software compositing or injection into the camera pipeline rather than a genuine live capture.           | `frame_injection_action`         | `NO_ACTION` |
| `SCREEN_CAPTURE_DURING_CAPTURE`    | Screen recording or screen sharing was active on the device during the biometric capture.                                                       | `screen_capture_action`          | `NO_ACTION` |

<Note>
  Browsers expose no OS-level camera-source attestation to any vendor, so on web these signals are corroborating evidence rather than proof. On web, a verdict of `null` means **not determined** (device labels are unavailable until camera permission is granted) and never fires a risk.
</Note>

### Recording sanity forensics

`LIVENESS_VIDEO_ANOMALY` is computed **server-side on the stored liveness recording**, independently of the liveness model. It detects a moving sequence repeated across multiple cycles, consistent with a looped feed.

| Risk                     | Cause                                                                                                                                                          | Config key                           | Default     |
| ------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ | ----------- |
| `LIVENESS_VIDEO_ANOMALY` | The recording contains a repeated moving sequence. Camera stalls, repeated still frames, dark lead-ins and slow frame delivery alone do not raise this signal. | `face_liveness_video_anomaly_action` | `NO_ACTION` |

Set the action on your Liveness or Age Estimation node: `NO_ACTION` records an information finding, `REVIEW` can escalate a decided verification to In Review, and `DECLINE` can escalate it to Declined. The check runs asynchronously, so an escalation can arrive after the initial result. A more severe existing decision is not downgraded, and manual review decisions are preserved.

Version 2 findings include `forensics_version: 2`, `repeated_sequence` evidence and `repeated_moving_sequence` in `anomaly_reasons`. Delivery measurements such as `unique_frame_ratio`, `static_pair_ratio`, `decoded_fps_ratio` and `max_frame_gap_seconds` remain diagnostics; they cannot establish a replay on their own. Older findings describe the detector version used at the time and are not retroactively reclassified.

<Note>
  This is a conservative additional signal, not complete detection of synthetic media or injected video. A recording with no anomaly is not proof of liveness. Short or ambiguous captures and captures without usable replay evidence remain unflagged by this check. Missing or unreadable recordings produce no finding from this check; other verification checks still apply.
</Note>

### Cross-session face matching

| Risk                            | Cause                                                                                                                                                                                                                                                                                                                                                                                | Additional data                                                                         | Severity                                                                                                          |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | --------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| `FACE_IN_BLOCKLIST`             | Face matched a blocklisted face.                                                                                                                                                                                                                                                                                                                                                     | `blocklisted_session_id`, `blocklisted_session_number`, `api_service`                   | `error` — **auto-decline**                                                                                        |
| `POSSIBLE_FACE_IN_BLOCKLIST`    | Face matched a blocklisted face at a lower-confidence band.                                                                                                                                                                                                                                                                                                                          | `blocklisted_session_id`, `blocklisted_session_number`, `api_service`                   | `warning` — always routed to Review in workflows                                                                  |
| `FACE_IN_ALLOWLIST`             | Face matched an allowlisted face.                                                                                                                                                                                                                                                                                                                                                    | `allowlisted_session_id`, `allowlisted_session_number`, `api_service`                   | `information` — duplicate-face action skipped                                                                     |
| `POSSIBLE_FACE_IN_ALLOWLIST`    | Face matched an allowlisted face at a lower-confidence band.                                                                                                                                                                                                                                                                                                                         | `allowlisted_session_id`, `allowlisted_session_number`, `api_service`                   | `information` — possible duplicate-face action skipped                                                            |
| `DUPLICATED_FACE`               | Face matched an already-approved face from another user (an `Approved` session with different `vendor_data`, or a face imported against one of your vendor users).                                                                                                                                                                                                                   | `duplicated_session_id`, `duplicated_session_number`, `api_service`                     | Configurable — `information` by default                                                                           |
| `POSSIBLE_DUPLICATED_FACE`      | Face matched another approved or imported face at a lower-confidence band.                                                                                                                                                                                                                                                                                                           | `duplicated_session_id`, `duplicated_session_number`, `api_service`                     | Configurable — `information` by default                                                                           |
| `DUPLICATED_FACE_NAME_MISMATCH` | Emitted alongside `DUPLICATED_FACE` when the matched session's identity does not match this session's resolved name (ID document, `expected_details`, or linked vendor user), using the same name-match scoring and threshold as ID verification. A face reused under a different name is a stronger fraud signal than a plain duplicate, so it carries its own configurable action. | `duplicated_session_id`, `duplicated_session_number`, `api_service`, `name_match_score` | Configurable — `warning` by default. Never relaxes `DUPLICATED_FACE`'s own configured outcome, only escalates it. |

For matches against imported faces or list-entry faces (which have no session), the `*_session_id`, `*_session_number`, and `api_service` values in `additional_data` are `null`.

Faces belonging to the same user (same `vendor_data`, or the same vendor user when available) are excluded from the **entire** index search — both duplicate detection and blocklist screening. Match precedence is: blocklist exact → allowlist exact → duplicate exact → blocklist possible → allowlist possible → duplicate possible — only one of these six mutually exclusive codes appears per report. `DUPLICATED_FACE_NAME_MISMATCH` is not part of that precedence group: it is an additional code emitted **on top of** `DUPLICATED_FACE` when the identity check also fails, never in its place. `additional_data.name_match_score` never carries the names being compared — only ids and a score, so no PII lands in the warning payload.

### Passive liveness quality (only when `method = "PASSIVE"`)

| Risk                      | Cause                                                                                                        | Severity                                                                           | Remediation                                    |
| ------------------------- | ------------------------------------------------------------------------------------------------------------ | ---------------------------------------------------------------------------------- | ---------------------------------------------- |
| `MULTIPLE_FACES_DETECTED` | More than one face was visible during the capture. The largest face is always used for scoring and matching. | Configurable — `information` by default                                            | Recapture solo.                                |
| `LOW_FACE_QUALITY`        | Face quality below the review threshold (default 15).                                                        | `warning`; `error` when below the decline threshold (default 0 — decline disabled) | Better focus / less occlusion / centered face. |
| `LOW_FACE_LUMINANCE`      | Normalized luminance below the minimum threshold (default 20).                                               | Configurable — `warning` by default (action defaults to Review)                    | Better lighting.                               |
| `HIGH_FACE_LUMINANCE`     | Normalized luminance above the maximum threshold (default 80).                                               | Configurable — `warning` by default (action defaults to Review)                    | Reduce lighting; avoid backlight.              |

`LOW_FACE_LUMINANCE` and `HIGH_FACE_LUMINANCE` are mutually exclusive — the luminance is either below the minimum or above the maximum, never both.

### Age estimation (adaptive workflows and `AGE_ESTIMATION` nodes)

| Risk                | Cause                                                                                                          | Severity | Remediation                                             |
| ------------------- | -------------------------------------------------------------------------------------------------------------- | -------- | ------------------------------------------------------- |
| `AGE_BELOW_MINIMUM` | Estimated age below the configured minimum (or borderline threshold when ID-verification fallback is enabled). | `error`  | Workflow falls back to ID verification when configured. |
| `AGE_NOT_DETECTED`  | Age could not be estimated and ID-verification fallback is disabled.                                           | `error`  | Enable fallback or re-capture.                          |

## Exact description strings

The API returns these exact `short_description` and `long_description` strings for each risk:

| `risk`                          | `short_description`                                  | `long_description`                                                                                                                                                                                                                                                                            |
| ------------------------------- | ---------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `NO_FACE_DETECTED`              | No Face Detected in liveness                         | The system couldn't identify a face during the liveness check, which may be due to poor image quality, improper positioning, or technical issues.                                                                                                                                             |
| `LIVENESS_FACE_ATTACK`          | Liveness Face Attack                                 | The system detected a potential attempt to bypass the liveness check.                                                                                                                                                                                                                         |
| `LOW_LIVENESS_SCORE`            | Low liveness score                                   | The liveness check resulted in a low score, indicating potential use of non-live facial representations or poor-quality biometric data.                                                                                                                                                       |
| `LIVENESS_VIDEO_ANOMALY`        | Liveness video stream anomaly                        | The recorded liveness video contains a repeated moving sequence consistent with a looped feed. Camera stalls, repeated still frames and slow frame delivery alone do not raise this signal. This is an independent recording check, not a complete assessment of whether the capture is live. |
| `FACE_IN_BLOCKLIST`             | Face in blocklist                                    | The system identified a face in the blocklist, which means the face is not allowed to be verified.                                                                                                                                                                                            |
| `POSSIBLE_FACE_IN_BLOCKLIST`    | Possible face in blocklist                           | The system identified a possible face in the blocklist, which means the face is not allowed to be verified.                                                                                                                                                                                   |
| `FACE_IN_ALLOWLIST`             | Face in allowlist                                    | The face matched the application's face allowlist, so duplicate-face actions were skipped for this signal.                                                                                                                                                                                    |
| `POSSIBLE_FACE_IN_ALLOWLIST`    | Possible face in allowlist                           | The face possibly matched the application's face allowlist, so possible duplicate-face actions were skipped for this signal.                                                                                                                                                                  |
| `DUPLICATED_FACE`               | Duplicated face from other approved session          | The system identified a duplicated face from another approved session, requiring further investigation.                                                                                                                                                                                       |
| `POSSIBLE_DUPLICATED_FACE`      | Possible duplicated face from other approved session | The system identified a possible duplicate face from another approved session, requiring further investigation.                                                                                                                                                                               |
| `DUPLICATED_FACE_NAME_MISMATCH` | Duplicated face under a different name               | The same face was already approved on another session, but under a different name. The identity behind the duplicate does not match the identity declared on this session, which is a strong indicator of identity fraud.                                                                     |
| `MULTIPLE_FACES_DETECTED`       | Multiple faces detected                              | Multiple faces were detected in the liveness image. The system uses the largest face for liveness verification and face comparison, but the presence of multiple faces may require additional review.                                                                                         |
| `LOW_FACE_QUALITY`              | Low face quality                                     | The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.                                                                                                  |
| `LOW_FACE_LUMINANCE`            | Low face luminance                                   | The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.                                                                                                                                                                |
| `HIGH_FACE_LUMINANCE`           | High face luminance                                  | The facial image is too bright or overexposed, which may affect the accuracy of liveness detection. Reduced lighting or avoiding direct light is recommended.                                                                                                                                 |
| `AGE_BELOW_MINIMUM`             | Age below minimum                                    | The age of the face is below the minimum age threshold for the application.                                                                                                                                                                                                                   |
| `AGE_NOT_DETECTED`              | Age not detected                                     | The system couldn't identify the age of the face, which is necessary for document verification.                                                                                                                                                                                               |

## Standalone passive liveness API

The standalone [Liveness API](/standalone-apis/passive-liveness) reuses the same risk codes with a few behavioral differences:

* `NO_FACE_DETECTED` and `LOW_LIVENESS_SCORE` are mutually exclusive — the score check only runs when a face was found. `LOW_LIVENESS_SCORE` fires against the request's `face_liveness_score_decline_threshold` (default 30) and always carries `log_type: "error"`.
* `POSSIBLE_FACE_IN_BLOCKLIST` is treated as a decline (`log_type: "error"`) instead of review.
* `MULTIPLE_FACES_DETECTED` carries `log_type: "warning"`, while the duplicate-face risks stay informational. Only `error`-level warnings flip the standalone response's `status` to `Declined`.
* Standalone warning entries include `feature` but no `node_id`.

## Examples

### Auto-decline on detected attack

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "LIVENESS_FACE_ATTACK",
    "additional_data": null,
    "log_type": "error",
    "short_description": "Liveness Face Attack",
    "long_description": "The system detected a potential attempt to bypass the liveness check.",
    "node_id": "liveness_primary"
  }
]
```

### Configurable warnings on a passive capture

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "LOW_FACE_QUALITY",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Low face quality",
    "long_description": "The facial image quality is below the acceptable threshold, which may affect the reliability of liveness detection. This could be due to camera resolution, focus, or compression artifacts.",
    "node_id": "liveness_primary"
  },
  {
    "feature": "LIVENESS",
    "risk": "LOW_FACE_LUMINANCE",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "Low face luminance",
    "long_description": "The facial image is too dark, which may affect the accuracy of liveness detection. Better lighting conditions are recommended.",
    "node_id": "liveness_primary"
  },
  {
    "feature": "LIVENESS",
    "risk": "MULTIPLE_FACES_DETECTED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "Multiple faces detected",
    "long_description": "Multiple faces were detected in the liveness image. The system uses the largest face for liveness verification and face comparison, but the presence of multiple faces may require additional review.",
    "node_id": "liveness_primary"
  }
]
```

### Duplicate face with payload

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "api_service": null
    },
    "log_type": "warning",
    "short_description": "Duplicated face from other approved session",
    "long_description": "The system identified a duplicated face from another approved session, requiring further investigation.",
    "node_id": "liveness_primary"
  }
]
```

Here the duplicate-face action is set to Review, so the warning carries `log_type: "warning"` and the liveness report's status is `In Review`. With the default (No action) it would carry `log_type: "information"` instead. `api_service` is `null` because the matched face came from a workflow session, not a standalone API call.

### Duplicate face under a different name

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "api_service": null
    },
    "log_type": "information",
    "short_description": "Duplicated face from other approved session",
    "long_description": "The system identified a duplicated face from another approved session, requiring further investigation.",
    "node_id": "liveness_primary"
  },
  {
    "feature": "LIVENESS",
    "risk": "DUPLICATED_FACE_NAME_MISMATCH",
    "additional_data": {
      "duplicated_session_id": "8d2f1c4e-6b7a-4c8d-9e0f-1a2b3c4d5e6f",
      "duplicated_session_number": 123,
      "api_service": null,
      "name_match_score": 42.5
    },
    "log_type": "warning",
    "short_description": "Duplicated face under a different name",
    "long_description": "The same face was already approved on another session, but under a different name. The identity behind the duplicate does not match the identity declared on this session, which is a strong indicator of identity fraud.",
    "node_id": "liveness_primary"
  }
]
```

`DUPLICATED_FACE` stays at its own configured action (here, No action — `log_type: "information"`) while `DUPLICATED_FACE_NAME_MISMATCH` carries its own action, defaulting to Review (`log_type: "warning"`). The liveness report's status follows the most severe of the two: `In Review` here, even though the plain duplicate-face setting alone would not have flagged it.

### Recording sanity anomaly with its measurements

```json theme={null}
"warnings": [
  {
    "feature": "LIVENESS",
    "risk": "LIVENESS_VIDEO_ANOMALY",
    "additional_data": {
      "forensics_version": 2,
      "duration_seconds": 6.0,
      "repeated_sequence": {
        "period_frames": 6,
        "cycles": 3,
        "matched_pairs": 12
      },
      "anomaly_reasons": ["repeated_moving_sequence"]
    },
    "log_type": "information",
    "short_description": "Liveness video stream anomaly",
    "long_description": "The recorded liveness video contains a repeated moving sequence consistent with a looped feed. Camera stalls, repeated still frames and slow frame delivery alone do not raise this signal. This is an independent recording check, not a complete assessment of whether the capture is live.",
    "node_id": "liveness_primary"
  }
]
```

This example shows the replay evidence from a recording containing three copies of a moving sequence. `log_type` is `information` because the configured action is `NO_ACTION`. The frame-delivery diagnostics, omitted from this example for brevity, do not trigger the finding.

## Warning types

Each risk is assigned a severity based on your application's configuration. The three severities are:

<WarningTypes />

## Related

* [Liveness report](/core-technology/liveness/report-liveness) — full report schema and statuses.
* [Face match warnings](/core-technology/face-match/warnings-face-match) — companion 1:1 face match warnings.
* [Webhooks](/integration/webhooks) — `session.status.updated` carries the warnings as soon as the liveness step finishes.
* [Data models — Liveness check](/reference/data-models#liveness-check) — canonical schema with every field.
* [Data models — Warning object](/reference/data-models#warning-object) — the shape of every entry in `warnings[]`.


# NFC Verification
Source: https://docs.didit.me/core-technology/nfc-verification/overview

Verify e-passports and eIDs via NFC chip reading. Cryptographic validation, tamper-proof checks, highest-security ID auth. Pay-per-call $0.15.

NFC-based authentication lets you verify identity documents by reading the secure chip embedded in modern passports and IDs using a mobile phone's NFC capabilities. This provides the **highest level of security available** for ID Verification.

<AgentPromptAccordion title="NFC Verification Integration Prompt" />

<Frame>
  <img alt="NFC Interaction" />
</Frame>

***

## Key Benefits

| Benefit                | Description                                                           |
| ---------------------- | --------------------------------------------------------------------- |
| **Highest Security**   | Verifies cryptographic signatures directly from government issuers    |
| **Easy to Use**        | Works automatically with any NFC-enabled phone                        |
| **Tamper-Proof**       | Detects document manipulation invisible to the human eye              |
| **Comprehensive Data** | Extracts additional data not available through OCR alone              |
| **Flexible Fallback**  | Gracefully falls back to standard verification if NFC isn't available |

***

## How to Enable NFC Verification

### Native SDK Integration (Recommended)

NFC verification is available through our **native SDKs**, which provide full access to device NFC capabilities:

| Platform    | NFC Support    | Documentation                                                     |
| ----------- | -------------- | ----------------------------------------------------------------- |
| **iOS**     | ✅ Full Support | [iOS SDK Documentation](/integration/native-sdks/ios-sdk)         |
| **Android** | ✅ Full Support | [Android SDK Documentation](/integration/native-sdks/android-sdk) |

The iOS SDK handles all NFC configuration automatically, including:

* ISO7816 application identifiers for ePassports
* Entitlements and capabilities setup
* Real-time chip reading with visual feedback

### Web Integration

> ⚠️ **Browser Limitations**
>
> NFC verification is **not available in web browsers** due to platform restrictions:
>
> | Browser              | NFC Support                                                        |
> | -------------------- | ------------------------------------------------------------------ |
> | **Chrome (Android)** | Experimental Web NFC API - unstable, requires explicit permissions |
> | **Safari (iOS)**     | No Web NFC API support                                             |
> | **Other Browsers**   | No support                                                         |
>
> For web integrations, NFC verification is automatically skipped and users proceed with standard document + selfie verification.

***

## How It Works

<Steps>
  <Step title="Session Initiation" icon="play">
    The user starts the verification process through your app or platform:

    * **Native SDK**: Launch the verification flow directly in your app
    * **Web/Mobile Web**: User is guided to use the Didit App for NFC-enabled verification, or continues with standard verification
  </Step>

  <Step title="Document Photo Capture" icon="camera">
    The user photographs their ID document, capturing:

    * **MRZ** (Machine Readable Zone) — used to derive chip access keys
    * **Document front and back images** — visual data and security features
    * **Visual security features** — holograms, watermarks, microprint
  </Step>

  <Step title="NFC Support Detection" icon="signal">
    The system automatically checks device and document compatibility:

    | Check                 | Description                                |
    | --------------------- | ------------------------------------------ |
    | **Document type**     | Is it an ePassport/eID with an NFC chip?   |
    | **Device capability** | Does the phone support NFC reading?        |
    | **Permissions**       | Are the necessary NFC permissions granted? |

    <Note>
      If NFC is unavailable, verification continues seamlessly with standard document + biometric verification.
    </Note>
  </Step>

  <Step title="NFC Chip Reading" icon="nfc-symbol">
    For compatible devices and documents:

    1. User is guided to position their document near the phone's NFC reader
    2. Visual feedback shows real-time reading progress
    3. Secure communication is established with the chip using PACE/BAC protocols
  </Step>

  <Step title="Data Extraction" icon="database">
    The system extracts comprehensive data from the chip following **ICAO 9303** standards:

    | Data Group  | Contents                 | Description                                      |
    | ----------- | ------------------------ | ------------------------------------------------ |
    | **SOD**     | Document Security Object | Digital signatures for all data groups           |
    | **DG1**     | Personal Data            | Name, ID number, birth date, expiry date         |
    | **DG2**     | Facial Image             | High-resolution digital photo of the holder      |
    | **DG7**     | Signature                | Digital representation of the holder's signature |
    | **DG11-14** | Additional Data          | May include fingerprints, iris scans (if stored) |
  </Step>

  <Step title="Cryptographic Verification" icon="shield-check">
    The extracted data undergoes rigorous cryptographic verification:

    <AccordionGroup>
      <Accordion title="Digital Signature Verification" icon="signature">
        Each data group's hash is verified against the signatures stored in the SOD, ensuring data integrity.
      </Accordion>

      <Accordion title="Certificate Chain Validation" icon="link">
        The chain of trust is validated: **Document Certificate → Country Signing CA → ICAO PKD Root**, checking against CSCA master lists and the ICAO Public Key Directory.
      </Accordion>

      <Accordion title="Certificate Revocation Check" icon="ban">
        Certificates are verified against Certificate Revocation Lists (CRLs) to ensure they haven't been revoked and the document hasn't been reported stolen/compromised.
      </Accordion>

      <Accordion title="Cross-Validation" icon="code-compare">
        NFC-extracted data is cross-validated against OCR data from document photos, facial biometric comparison, and MRZ checksum verification.
      </Accordion>
    </AccordionGroup>
  </Step>

  <Step title="Result & Confidence Score" icon="chart-simple">
    The final verification result includes:

    | Output                      | Description                                                 |
    | --------------------------- | ----------------------------------------------------------- |
    | **NFC verification status** | Success, failed, or skipped                                 |
    | **Data consistency score**  | How well NFC data matches visual data                       |
    | **Certificate validation**  | Full chain verification status                              |
    | **Confidence boost**        | NFC adds significant confidence to the overall verification |
  </Step>
</Steps>

***

## Supported Documents

NFC verification works with **ePassports** and **eIDs** that contain an NFC chip, typically indicated by this symbol on the document:

<Frame>
  <img alt="ePassport Logo" />
</Frame>

Most passports issued after 2006 contain NFC chips. Coverage varies by country for national ID cards. Check all the [supported documents](/core-technology/nfc-verification/supported-documents-nfc-verification).

***

## Integration Examples

### iOS SDK (Available Now)

```swift theme={null}
import DiditSdk

// NFC is automatically enabled when the document supports it
let config = DiditSdk.Configuration(
    // NFC configuration is handled automatically
    // Just ensure your app has the required entitlements
)

let result = try await DiditSdk.shared.startVerification(
    with: sessionId,
    configuration: config
)
```

**[Complete iOS SDK Documentation →](/integration/native-sdks/ios-sdk)**

### Android SDK (Coming Soon)

```kotlin theme={null}
// Coming soon - use WebView integration in the meantime
// See Android SDK documentation for WebView setup
```

**[Android SDK Documentation →](/integration/native-sdks/android-sdk)**

***

## Security Architecture

```
┌─────────────────────────────────────────────────────────────┐
│                    NFC Verification Flow                     │
├─────────────────────────────────────────────────────────────┤
│                                                              │
│  ┌──────────┐    ┌──────────┐    ┌──────────────────────┐  │
│  │ Document │───▶│  Phone   │───▶│   Didit Backend      │  │
│  │ NFC Chip │    │ NFC Read │    │                      │  │
│  └──────────┘    └──────────┘    │  ┌────────────────┐  │  │
│                                   │  │ ICAO PKD       │  │  │
│                                   │  │ Validation     │  │  │
│                                   │  └────────────────┘  │  │
│                                   │  ┌────────────────┐  │  │
│                                   │  │ CSCA Master    │  │  │
│                                   │  │ List Check     │  │  │
│                                   │  └────────────────┘  │  │
│                                   │  ┌────────────────┐  │  │
│                                   │  │ CRL Revocation │  │  │
│                                   │  │ Check          │  │  │
│                                   │  └────────────────┘  │  │
│                                   └──────────────────────┘  │
│                                              │               │
│                                              ▼               │
│                                   ┌──────────────────────┐  │
│                                   │  Verification Result │  │
│                                   │  + Confidence Score  │  │
│                                   └──────────────────────┘  │
└─────────────────────────────────────────────────────────────┘
```

***

## FAQ

<details>
  <summary><strong>What if the user's phone doesn't support NFC?</strong></summary>

  The verification flow automatically detects NFC capability. If unavailable, users proceed with standard document + selfie verification. The verification is still secure, just without the additional NFC confidence boost.
</details>

<details>
  <summary><strong>What if the document doesn't have an NFC chip?</strong></summary>

  Many documents (especially older passports and some national IDs) don't have NFC chips. The system detects this and seamlessly continues with standard verification.
</details>

<details>
  <summary><strong>How much does NFC verification improve accuracy?</strong></summary>

  NFC verification provides cryptographic proof of document authenticity directly from the issuing government. This significantly increases confidence in the verification result and catches sophisticated forgeries that might pass visual inspection.
</details>

<details>
  <summary><strong>Is NFC verification required?</strong></summary>

  No. NFC is an enhancement, not a requirement. Your verification workflow can be configured to require NFC, prefer it when available, or skip it entirely based on your risk tolerance.
</details>

***


# NFC verification report
Source: https://docs.didit.me/core-technology/nfc-verification/report-nfc-verification

How to read Didit's NFC / ePassport report: status, chip data, certificate authenticity, where it appears in API responses, and example payloads.

## Overview

The **NFC verification report** captures what Didit read and validated from a document's NFC chip — an ePassport, an electronic ID card, or another ICAO 9303 e-document. It includes the chip's biographical data, cryptographic integrity checks (SOD and Data Group hashes), and a summary of the Document Signer Certificate (DSC) used by the issuing country.

The report is produced after the user completes the NFC step in a workflow. Didit reads the chip's Data Groups on the user's device, verifies the Document Security Object (SOD) signature against the issuing country's CSCA certificate, checks each Data Group hash against the values the SOD signed, and cross-checks the chip's MRZ against the MRZ that was OCR'd off the visible side of the document.

Each report carries its own `status` — independent of the overall session status — that reflects how the NFC step alone resolved:

* **Approved** — the chip was read and none of the warnings that fired are configured to route the step to review or decline.
* **In Review** — at least one warning fired whose configured action is **Review** (for example `NFC_CHIP_NOT_VERIFIED` or `NFC_TRUST_ANCHOR_MISSING` when the unverified-chip action is set to Review).
* **Declined** — at least one warning fired whose configured action is **Decline** (for example `NFC_AND_OCR_DATA_NOT_SAME` when the data-inconsistency action is set to Decline).
* **Not Finished** — the user never completed the NFC step; the chip read was abandoned or the device did not support NFC.
* **Resub Requested** — a reviewer asked the user to resubmit; the report will be superseded by a new attempt.

## Where it appears in API responses

The NFC report ships inside the `nfc_verifications[]` array — **always a JSON array**, never a singular `nfc` object. Multiple entries appear when a workflow runs NFC more than once (for example a step-up flow); each entry carries its own `node_id`.

* **Session decision API** — appears as `nfc_verifications[]` at the top level of `GET /v3/session/{sessionId}/decision/`. See [Retrieve session decision](/sessions-api/retrieve-session).
* **Webhooks** — `status.updated` payloads include the same `nfc_verifications[]` array once the NFC step has produced data. See [Webhooks](/integration/webhooks).
* **Standalone NFC** — for direct chip submission, see the [NFC overview](/core-technology/nfc-verification/overview).

When your workflow includes an NFC step that was skipped or bypassed, the decision payload also carries a top-level `nfc_skip_reason` field stating exactly why — the document has no chip, the issuing country's certificate is unavailable, the device has no NFC reader, the verification ran without a native SDK (no NFC access from a browser), the chip access key could not be derived from the MRZ, or the user chose to skip. It stays `null` for outcomes outside that taxonomy — most commonly a user who abandoned mid-attempt (report status `Not Finished`) or a session where NFC is still pending. See [Skip reasons](/core-technology/nfc-verification/warnings-nfc-verification#skip-reasons) for the exact values.

<Note>
  Older documentation referenced a singular `nfc` field. That shape does **not** exist on the v3 decision endpoint — it only appears on destinations explicitly pinned to V2 webhooks. Always read `response.nfc_verifications[0]` and iterate the array.
</Note>

## Schema

The canonical field-by-field schema lives on the [Data models](/reference/data-models#nfc-verification) reference page. The fields below mirror that canonical schema.

| Field                        | Type                                                                             | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ---------------------------- | -------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `status`                     | `"Not Finished" \| "Approved" \| "Declined" \| "In Review" \| "Resub Requested"` | NFC-step status (see meanings above).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `node_id`                    | string \| null                                                                   | Workflow graph node that produced this report. Lets you tell two NFC checks apart in a multi-step workflow.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `is_nfc_skipped`             | boolean                                                                          | `true` when this NFC step was explicitly skipped instead of read.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `skip_reason`                | string \| null                                                                   | Why the step was skipped — only set when `is_nfc_skipped` is `true`. Same values as the session-level `nfc_skip_reason`; see [Skip reasons](/core-technology/nfc-verification/warnings-nfc-verification#skip-reasons).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `portrait_image`             | string (signed URL) \| null                                                      | Portrait extracted from the chip (DG2). Short-lived presigned link — download promptly; re-fetch the decision for a fresh URL.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `signature_image`            | string (signed URL) \| null                                                      | Holder's signature image from the chip (DG7), when present. Same short-lived presigned behavior.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `chip_data`                  | object \| null                                                                   | Flat object with the biographical data parsed from the chip. Always present after a successful read: `dgs` (list of Data Groups read), `surname`, `name`, `country`, `nationality`, `birth_date` (`YYYY-MM-DD`), `expiry_date` (`YYYY-MM-DD`), `sex` (`M`/`F`), `document_type` (MRZ document code, e.g. `P`), `document_number`, `optional_data`, the MRZ check digits (`birth_date_hash`, `expiry_date_hash`, `document_number_hash`, `optional_data_hash`, `final_hash`), `mrz_string`, and `mrz_type` (`TD1`/`TD2`/`TD3`). When the chip carries DG11, `place_of_birth` and `address` are added (and `full_name` / `full_name_non_latin` for documents with a non-Latin name); these keys are **absent**, not null, otherwise. `null` when the NFC step was skipped. |
| `authenticity.sod_integrity` | boolean                                                                          | `true` when the SOD signature chains to a valid issuing-country CSCA and the DSC is neither revoked nor expired.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `authenticity.dg_integrity`  | boolean                                                                          | `true` when every Data Group's hash matches the value the SOD signed. A `false` value means the chip data was tampered with or partially read.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `certificate_summary`        | object \| null                                                                   | Summary of the DSC that signed this chip: `issuer`, `subject`, `serial_number`, `not_valid_before`, `not_valid_after` (timestamps as `YYYY-MM-DD HH:MM:SS`), plus a `validation` object with the individual check results (`csca_verified`, `csca_missing`, `dsc_revoked`, `dsc_expired`, `csca_expired`). `csca_missing` is `true` when the DSC's issuing CSCA trust anchor is not available. `null` when the SOD could not be loaded or the step was skipped.                                                                                                                                                                                                                                                                                                          |
| `warnings[]`                 | array                                                                            | Module-level warnings, each with `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, and `node_id` — see [NFC warnings](/core-technology/nfc-verification/warnings-nfc-verification).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |

## Status values

| Status            | Meaning                                                                                                                                                                                        | Downstream effect                                                                    |
| ----------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `Approved`        | Chip read and no warning fired with a Review or Decline action — including the case where warnings fired but their configured action is "No action".                                           | Counts as a successful NFC check; will not, by itself, push the session into review. |
| `In Review`       | A warning fired whose configured action is Review (`SKIPPED_NFC_VALIDATION`, `NFC_CHIP_NOT_VERIFIED`, `NFC_TRUST_ANCHOR_MISSING`, or `NFC_AND_OCR_DATA_NOT_SAME`, depending on your settings). | The session also moves to `In Review` until a reviewer acts.                         |
| `Declined`        | A warning fired whose configured action is Decline.                                                                                                                                            | The session is declined unless another approved branch satisfies the workflow.       |
| `Not Finished`    | User abandoned the NFC step, the device lacked NFC support, or the chip read never completed.                                                                                                  | The NFC branch did not produce a result; check workflow fallbacks.                   |
| `Resub Requested` | A reviewer requested resubmission of this step.                                                                                                                                                | A new attempt replaces this report once the user retries.                            |

<Note>
  The two certificate warnings (`DSC_CERTIFICATE_REVOKED`, `DSC_CERTIFICATE_EXPIRED`) are informational: they appear in `warnings[]` but never change the NFC `status` by themselves. See [NFC warnings](/core-technology/nfc-verification/warnings-nfc-verification) for the full behavior matrix.
</Note>

## Examples

### Approved — chip read and cryptographically valid

```json theme={null}
{
  "nfc_verifications": [
    {
      "status": "Approved",
      "node_id": "nfc_primary",
      "portrait_image": "https://<media-host>/.../epassport/<session-id>_face.jpg?signature=...",
      "signature_image": "https://<media-host>/.../epassport/<session-id>_signature.jpg?signature=...",
      "chip_data": {
        "dgs": ["DG1", "DG2", "DG7", "DG11"],
        "surname": "DOE",
        "name": "JOHN",
        "country": "ESP",
        "nationality": "ESP",
        "birth_date": "1990-05-15",
        "expiry_date": "2030-01-01",
        "sex": "M",
        "document_type": "P",
        "document_number": "AAB000123",
        "optional_data": "",
        "birth_date_hash": "4",
        "expiry_date_hash": "7",
        "document_number_hash": "3",
        "optional_data_hash": "",
        "final_hash": "4",
        "mrz_string": "P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000123ESP9005154M3001017<<<<<<<<<<<<<<04",
        "mrz_type": "TD3",
        "place_of_birth": "MADRID, MADRID",
        "address": "CALLE MAYOR 1, MADRID"
      },
      "is_nfc_skipped": false,
      "skip_reason": null,
      "authenticity": {
        "sod_integrity": true,
        "dg_integrity": true
      },
      "certificate_summary": {
        "issuer": "Common Name: CSCA SPAIN, Serial Number: 3, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "not_valid_before": "2020-11-18 10:21:11",
        "not_valid_after": "2031-02-18 10:21:11",
        "serial_number": 118120836164494130086420187336801405660,
        "validation": {
          "csca_verified": true,
          "dsc_revoked": false,
          "dsc_expired": false,
          "csca_expired": false
        }
      },
      "warnings": []
    }
  ]
}
```

### Declined — OCR / chip mismatch

```json theme={null}
{
  "nfc_verifications": [
    {
      "status": "Declined",
      "node_id": "nfc_primary",
      "portrait_image": "https://<media-host>/.../epassport/<session-id>_face.jpg?signature=...",
      "signature_image": null,
      "chip_data": {
        "dgs": ["DG1", "DG2"],
        "surname": "DOE",
        "name": "JOHN",
        "country": "ESP",
        "nationality": "ESP",
        "birth_date": "1990-05-15",
        "expiry_date": "2030-01-01",
        "sex": "M",
        "document_type": "P",
        "document_number": "AAB000254",
        "optional_data": "",
        "birth_date_hash": "4",
        "expiry_date_hash": "7",
        "document_number_hash": "6",
        "optional_data_hash": "",
        "final_hash": "6",
        "mrz_string": "P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000254ESP9005154M3001017<<<<<<<<<<<<<<06",
        "mrz_type": "TD3"
      },
      "is_nfc_skipped": false,
      "skip_reason": null,
      "authenticity": {
        "sod_integrity": true,
        "dg_integrity": true
      },
      "certificate_summary": {
        "issuer": "Common Name: CSCA SPAIN, Serial Number: 3, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
        "not_valid_before": "2020-11-18 10:21:11",
        "not_valid_after": "2031-02-18 10:21:11",
        "serial_number": 118120836164494130086420187336801405660,
        "validation": {
          "csca_verified": true,
          "dsc_revoked": false,
          "dsc_expired": false,
          "csca_expired": false
        }
      },
      "warnings": [
        {
          "feature": "NFC",
          "risk": "NFC_AND_OCR_DATA_NOT_SAME",
          "additional_data": {
            "ocr_mrz": ["P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<", "AAB000123ESP9005154M3001017<<<<<<<<<<<<<<04"],
            "nfc_mrz": "P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000254ESP9005154M3001017<<<<<<<<<<<<<<06"
          },
          "log_type": "error",
          "short_description": "NFC and OCR data not same",
          "long_description": "The Near Field Communication (NFC) chip data and the OCR data don't match, indicating potential document tampering or data inconsistency.",
          "node_id": "nfc_primary"
        }
      ]
    }
  ]
}
```

## Security note

NFC chip data is signed by the issuing authority, so an Approved report with `sod_integrity: true` and `dg_integrity: true` is the strongest possible identity evidence Didit can produce. Treat the signed image URLs (`portrait_image`, `signature_image`) as short-lived: download them promptly and do not cache them publicly — re-request the decision when you need fresh links.

## Related

* [NFC warnings](/core-technology/nfc-verification/warnings-nfc-verification) — full warning enum, causes, and remediation.
* [Webhooks](/integration/webhooks) — listen for the `status.updated` event to receive the NFC report.
* [Data models — NFC verification](/reference/data-models#nfc-verification) — canonical schema with every field.
* [Supported documents](/core-technology/nfc-verification/supported-documents-nfc-verification) — which e-documents Didit can read over NFC.


# NFC-Supported Documents
Source: https://docs.didit.me/core-technology/nfc-verification/supported-documents-nfc-verification

Browse Didit's full list of NFC-supported identity documents: ePassports, eIDs, and electronic residence permits worldwide. Pay-per-call $0.15.

Our advanced NFC-based verification system supports electronic identity documents (eIDs) from numerous countries and territories worldwide. This comprehensive coverage enables secure, reliable identity verification through NFC chip reading technology.

<Note>
  Customize the accepted document types and countries through your [custom workflows](/console/workflows) to align with your business requirements and compliance needs.
</Note>

### Security and Reliability Features

Our NFC verification system ensures:

* **Chip Authentication**: Verifies the authenticity of the NFC chip
* **Passive Authentication**: Validates the integrity of stored data
* **Active Authentication**: Prevents chip cloning (where supported)
* **Real-time Validation**: Confirms document validity during verification
* **Data Protection**: Implements end-to-end encryption for all NFC communications

### Security and Accuracy Standards

We maintain the highest standards of accuracy and security in NFC-based ID Verification:

* **Regular Updates**: Our NFC-supported document database is continuously updated with new documents and countries
* **Continuous Improvement**: NFC reading and data extraction algorithms are continually refined for accuracy and efficiency
* **Strict Data Protection**: Rigorous data protection and privacy measures safeguard all NFC-extracted information
* **ICAO Compliance**: Verification processes comply with ICAO standards and international guidelines for NFC-based identity verification

***

## Supported NFC Documents by Country

The table below shows all supported NFC documents by country. Each checkmark indicates document type availability.

<NfcDocumentsTable />

<Note>
  This list is regularly updated as we expand our NFC verification capabilities. If a country or document type you need is not listed, please contact our support team for the most current information.
</Note>


# NFC verification warnings
Source: https://docs.didit.me/core-technology/nfc-verification/warnings-nfc-verification

Every warning Didit's NFC module emits — skipped chip read, unverified chip, unavailable trust anchor, OCR/chip mismatch, certificate revoked or expired — with cause, severity, and remediation.

## Overview

Warnings on the NFC report flag every condition Didit observed while reading and validating the chip. They land in the `warnings[]` array on each item of `nfc_verifications[]` (see [NFC report](/core-technology/nfc-verification/report-nfc-verification)), with `feature` set to `"NFC"`. Each entry follows the shared [warning object](/reference/data-models#warning-object) shape: `feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`.

Every warning has three layers:

1. **The `risk` code** — a stable identifier you can match on in your code (the codes listed below).
2. **The `log_type`** — one of `information`, `warning`, or `error`. It is derived from the action your workflow configures for that risk: **No action** → `information`, **Review** → `warning`, **Decline** → `error`.
3. **The decision impact** — the same configured action also drives the NFC report's `status`: a Review action moves it to `In Review`, a Decline action to `Declined`.

Four NFC risks are configurable this way (`SKIPPED_NFC_VALIDATION`, `NFC_CHIP_NOT_VERIFIED`, `NFC_TRUST_ANCHOR_MISSING`, `NFC_AND_OCR_DATA_NOT_SAME`). The two certificate risks (`DSC_CERTIFICATE_REVOKED`, `DSC_CERTIFICATE_EXPIRED`) are **informational only**: they always carry `log_type: "information"` and never change the NFC status by themselves.

The full set of risk codes the NFC module produces is below. No other NFC risk codes exist.

## Warnings produced

| `risk`                      | Cause                                                                                                                                                                                                                                                                                                     | Severity (`log_type`)                                                                                                                                   | Affects status?                               | Remediation                                                                                                                                                                                                                   |
| --------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SKIPPED_NFC_VALIDATION`    | The chip read was skipped — the workflow allows skipping (`allow_nfc_skip`) and the user tapped skip, or the client skipped because it could not read NFC. The exact reason is recorded in `additional_data.skip_reason` (see [Skip reasons](#skip-reasons)) and drives the warning's `long_description`. | Follows the **skip NFC action** setting (`skip_nfc_action`): information / warning / error.                                                             | Configurable — No action, Review, or Decline. | If your policy requires NFC, set the skip action to Decline (or disallow skipping entirely) and instruct the user to retry from an NFC-capable device. Otherwise leave it at No action to fall back to OCR-only verification. |
| `NFC_CHIP_NOT_VERIFIED`     | The chip was read but failed cryptographic verification for a reason other than an explicitly identified missing trust anchor. A Data Group hash, the SOD signature, or another passive-authentication check did not verify.                                                                              | Follows the **unverified chip action** setting (`unverified_chip_action`).                                                                              | Configurable — No action, Review, or Decline. | Treat this as a potentially invalid or altered chip. Inspect `authenticity` and `certificate_summary.validation` to see which check failed.                                                                                   |
| `NFC_TRUST_ANCHOR_MISSING`  | The chip's Document Signer Certificate (DSC) belongs to a Country Signing Certification Authority (CSCA) generation that is not available in Didit's trust store (`certificate_summary.validation.csca_missing` is `true`). Didit therefore cannot establish the SOD's chain of trust.                    | Follows the **unverified chip action** setting (`unverified_chip_action`).                                                                              | Configurable — No action, Review, or Decline. | This is a trust-store coverage gap, not evidence that the chip was altered. Review the document through your fallback checks and contact Didit support with the issuing country so the missing CSCA can be investigated.      |
| `NFC_AND_OCR_DATA_NOT_SAME` | The MRZ read from the chip does not match the MRZ OCR'd from the visible side of the document (compared after normalization, ignoring `<` filler). Strong tampering signal.                                                                                                                               | Follows the **data inconsistency action** setting (`inconsistent_data_action`) — the same setting that governs ID-verification data-consistency checks. | Configurable — No action, Review, or Decline. | Treat as tampering unless proven otherwise; Decline is the typical setting. The `additional_data` payload includes the OCR MRZ lines (`ocr_mrz`, array) and the chip MRZ (`nfc_mrz`, single string) for manual comparison.    |
| `DSC_CERTIFICATE_REVOKED`   | The Document Signer Certificate that signed this chip appears in the issuing country's Certificate Revocation List (CRL).                                                                                                                                                                                 | Always `information`.                                                                                                                                   | No — never changes the NFC status by itself.  | Strong signal that the signing key may have been compromised; route these sessions to manual review via your own logic if needed. Note the chip will usually also fire `NFC_CHIP_NOT_VERIFIED`, which is configurable.        |
| `DSC_CERTIFICATE_EXPIRED`   | The DSC's validity window has passed (`certificate_summary.validation.dsc_expired` is `true`).                                                                                                                                                                                                            | Always `information`.                                                                                                                                   | No — never changes the NFC status by itself.  | Common with older documents. As with revocation, an expired DSC also fails full SOD validation, so `NFC_CHIP_NOT_VERIFIED` fires alongside it and carries your configured action.                                             |

<Note>
  `SKIPPED_NFC_VALIDATION` is mutually exclusive with `NFC_CHIP_NOT_VERIFIED` and `NFC_TRUST_ANCHOR_MISSING`: chip-verification warnings are only evaluated when the chip read was not skipped. The two chip-verification warnings are also mutually exclusive.
</Note>

## Exact description strings

The API returns these exact `short_description` and `long_description` strings for each risk:

| `risk`                      | `short_description`                 | `long_description`                                                                                                                                                                                                                                                      |
| --------------------------- | ----------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `SKIPPED_NFC_VALIDATION`    | Skipped NFC Validation              | Reason-specific — see [Skip reasons](#skip-reasons). Falls back to "The Near Field Communication (NFC) chip validation process was not completed, potentially due to technical issues or lack of NFC support." on legacy sessions recorded before skip reasons existed. |
| `NFC_CHIP_NOT_VERIFIED`     | NFC chip not verified               | The Near Field Communication (NFC) chip failed passive authentication for a reason other than an explicitly identified missing trust anchor. The chip data or signature could be invalid or altered.                                                                    |
| `NFC_TRUST_ANCHOR_MISSING`  | NFC trust anchor unavailable        | The Near Field Communication (NFC) chip could not be verified because the issuing country's Country Signing Certification Authority (CSCA) trust anchor is not available. This is a trust-store coverage gap, not evidence that the chip was altered.                   |
| `NFC_AND_OCR_DATA_NOT_SAME` | NFC and OCR data not same           | The Near Field Communication (NFC) chip data and the OCR data don't match, indicating potential document tampering or data inconsistency.                                                                                                                               |
| `DSC_CERTIFICATE_REVOKED`   | Document Signer Certificate revoked | The Document Signer Certificate (DSC) used to sign the ePassport chip data has been revoked by the issuing country's Certificate Revocation List (CRL), indicating the signing key may have been compromised.                                                           |
| `DSC_CERTIFICATE_EXPIRED`   | Document Signer Certificate expired | The Document Signer Certificate (DSC) used to sign the ePassport chip data has expired, meaning the certificate's validity period has passed.                                                                                                                           |

## Skip reasons

`SKIPPED_NFC_VALIDATION` warnings carry `additional_data.skip_reason`, one of six stable codes stating exactly why NFC did not run (on sessions recorded before skip reasons existed, `additional_data` may be `null` — treat the field as optional when processing historical decisions). The same taxonomy appears at the session level as `nfc_skip_reason` on the decision payload — including for sessions where NFC could never run at all (chipless document, web integration) and therefore no NFC report or warning exists.

| `skip_reason`                    | Meaning                                                                                                                                     | `long_description`                                                                                                                                                                                   |
| -------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `USER_SKIPPED`                   | NFC was offered on a compatible device and the user chose to skip.                                                                          | The NFC chip reading step was offered on a compatible device, but the user chose to skip it (skipping is allowed by the workflow configuration).                                                     |
| `DOCUMENT_WITHOUT_CHIP`          | The document design has no readable NFC chip (not an ICAO 9303 electronic document).                                                        | NFC verification could not be performed because this document does not have a readable NFC chip: it is not an ICAO 9303 electronic document.                                                         |
| `CHIP_CERTIFICATE_UNAVAILABLE`   | The chip exists, but no issuing-country signing certificate (CSCA) covers the document's issue period, so the signature cannot be verified. | NFC verification could not be performed because the issuing country's signing certificate (CSCA) covering this document's issue period is not available, so the chip's signature cannot be verified. |
| `DEVICE_WITHOUT_NFC`             | A native SDK reported the phone has no NFC reader available.                                                                                | NFC verification could not be performed because the user's device reported that it has no NFC reader available.                                                                                      |
| `INTEGRATION_WITHOUT_NFC_ACCESS` | The verification ran without a native SDK (for example in a web browser), which has no access to the phone's NFC reader.                    | NFC verification could not be performed because the verification did not run through a native mobile SDK, so there was no access to the phone's NFC reader (web browsers cannot read NFC chips).     |
| `MRZ_KEY_UNAVAILABLE`            | The chip access key (BAC/PACE seed) could not be derived from the document's MRZ.                                                           | NFC verification could not be performed because the chip access key could not be derived from the document's machine-readable zone (MRZ).                                                            |

<Note>
  An NFC report and its `SKIPPED_NFC_VALIDATION` warning only exist when the client reached the NFC step and explicitly skipped it (typically `USER_SKIPPED`, or `DEVICE_WITHOUT_NFC` when the reader turned out to be unavailable at scan time). When the NFC step was bypassed before it could ever be offered — chipless document, missing certificate, no NFC capability reported, unreadable MRZ key — no report or warning is created and the reason surfaces only in the session-level `nfc_skip_reason` field, without affecting the session status.
</Note>

## Configuration

Three workflow settings control how NFC warnings route. Each can be set to **No action**, **Review**, or **Decline**:

1. **Skip NFC action** (`skip_nfc_action`) — applies to `SKIPPED_NFC_VALIDATION`. Skipping is only offered to users when `allow_nfc_skip` is enabled.
2. **Unverified chip action** (`unverified_chip_action`) — applies to both `NFC_CHIP_NOT_VERIFIED` and `NFC_TRUST_ANCHOR_MISSING`, so the session status behavior remains the same while the risk code explains why verification failed.
3. **Data inconsistency action** (`inconsistent_data_action`) — applies to `NFC_AND_OCR_DATA_NOT_SAME`. This is the same data-inconsistency setting used by ID verification.

The two `DSC_CERTIFICATE_*` risks have no action setting — they are always informational.

## Examples

### In Review — chip could not be verified

```json theme={null}
{
  "warnings": [
  {
    "feature": "NFC",
    "risk": "NFC_CHIP_NOT_VERIFIED",
    "additional_data": null,
    "log_type": "warning",
    "short_description": "NFC chip not verified",
    "long_description": "The Near Field Communication (NFC) chip failed passive authentication for a reason other than an explicitly identified missing trust anchor. The chip data or signature could be invalid or altered.",
    "node_id": "nfc_primary"
  },
  {
    "feature": "NFC",
    "risk": "DSC_CERTIFICATE_EXPIRED",
    "additional_data": null,
    "log_type": "information",
    "short_description": "Document Signer Certificate expired",
    "long_description": "The Document Signer Certificate (DSC) used to sign the ePassport chip data has expired, meaning the certificate's validity period has passed.",
    "node_id": "nfc_primary"
  }
]
}
```

Here the unverified-chip action is set to Review, so `NFC_CHIP_NOT_VERIFIED` carries `log_type: "warning"` and the NFC report's status is `In Review`. The expired-DSC entry is purely informational.

### Declined — chip / OCR mismatch

```json theme={null}
{
  "warnings": [
  {
    "feature": "NFC",
    "risk": "NFC_AND_OCR_DATA_NOT_SAME",
    "additional_data": {
      "ocr_mrz": ["P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<", "AAB000123ESP9005154M3001017<<<<<<<<<<<<<<04"],
      "nfc_mrz": "P<ESPDOE<<JOHN<<<<<<<<<<<<<<<<<<<<<<<<<<<<<AAB000254ESP9005154M3001017<<<<<<<<<<<<<<06"
    },
    "log_type": "error",
    "short_description": "NFC and OCR data not same",
    "long_description": "The Near Field Communication (NFC) chip data and the OCR data don't match, indicating potential document tampering or data inconsistency.",
    "node_id": "nfc_primary"
  }
]
}
```

Here the data-inconsistency action is set to Decline, so the warning carries `log_type: "error"` and the NFC report's status is `Declined`. Note that `ocr_mrz` is an array of MRZ lines while `nfc_mrz` is the chip's single concatenated MRZ string.

## Warning types

Each risk is assigned a severity based on your application's configuration. The three severities are:

<WarningTypes />

## Related

* [NFC report](/core-technology/nfc-verification/report-nfc-verification) — full report schema and statuses.
* [Webhooks](/integration/webhooks) — `status.updated` fires on session status changes; the decision payload (including NFC warnings) is attached when the session reaches Approved, Declined, In Review, or Abandoned.
* [Data models — NFC verification](/reference/data-models#nfc-verification) — canonical field-by-field schema.
* [Data models — Warning object](/reference/data-models#warning-object) — the shape of every entry in `warnings[]`.


# Phone Verification Overview
Source: https://docs.didit.me/core-technology/phone-verification/overview

Verify phone numbers with OTP across SMS, WhatsApp, Telegram, RCS, and voice. Pay-per-call $0.04 + carrier, carrier detection, risk scoring.

Didit's Phone Verification provides a reliable method to verify user phone numbers through one-time passcodes (OTP). This feature adds an essential layer of security to your identity verification process, ensuring legitimate user contact information.

<AgentPromptAccordion title="Phone Verification Integration Prompt" />

In the Academy lesson on reading a verification result, the 8:08 chapter covers phone verification and duplicate detection.

<VideoEmbed title="Phone verification and duplicates — Didit Academy" />

<Frame>
  <img alt="Phone verification flow diagram" />
</Frame>

## How it works

Our Phone Verification solution delivers comprehensive phone number validation through a simple, user-friendly process. The system combines OTP verification with advanced risk assessment to provide reliable phone verification at scale.

<Steps>
  <Step title="Phone Collection" icon="mobile">
    The system securely collects the following information:

    | Data Collected   | Details                                                                                                                                                       |
    | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
    | **Phone Number** | If not provided during session creation, the user enters their phone number in international format. If provided, the user must verify the pre-filled number. |
    | **Country Code** | Automatically suggested based on IP location or user selection.                                                                                               |
    | **Carrier Type** | Detected whether mobile or landline number.                                                                                                                   |
  </Step>

  <Step title="OTP Generation & Delivery" icon="paper-plane">
    Our verification system:

    * Generates a secure, time-limited one-time passcode
    * Delivers the code via SMS to the provided number
    * Ensures optimized delivery through multiple carrier integrations
    * Provides fallback options for delivery challenges
  </Step>

  <Step title="Code Validation" icon="keyboard">
    The user completes verification by:

    * Entering the received code into the verification interface
    * Submitting within the configured timeframe (typically 5–10 minutes)
    * Requesting a new code if needed (with appropriate rate limiting)
  </Step>

  <Step title="Risk Assessment" icon="shield-halved">
    Our system performs advanced checks:

    | Check                  | Description                                               |
    | ---------------------- | --------------------------------------------------------- |
    | **Format & Carrier**   | Verifies the phone number format and carrier information. |
    | **Disposable Numbers** | Checks against known disposable/virtual number databases. |
    | **SIM Swap Detection** | Identifies potential SIM swap risks.                      |
    | **Activity Patterns**  | Detects suspicious activity patterns.                     |
    | **Historical Data**    | Cross-references with historical verification data.       |
  </Step>

  <Step title="Result Delivery" icon="bell">
    Access verification results through multiple channels:

    | Channel       | Description                                                   |
    | ------------- | ------------------------------------------------------------- |
    | **Dashboard** | Real-time dashboard updates.                                  |
    | **Webhooks**  | Instant webhook notifications.                                |
    | **API**       | RESTful API integration.                                      |
    | **Reports**   | Comprehensive reports with detailed verification information. |
  </Step>
</Steps>

## Verification Features

Our Phone Verification service offers several key features to enhance your verification process:

#### OTP Verification

* **Secure Code Generation**: Randomly generated one-time passcodes
* **SMS Delivery**: Fast and reliable delivery to mobile devices
* **Configurable Timeouts**: Set expiration times based on your security requirements
* **Retry Options**: Allow users to request new codes with appropriate rate limiting

#### Phone Number Analysis

* **Format Validation**: Ensure the phone number follows the correct international format
* **Carrier Detection**: Identify the telecommunications provider associated with the number
* **Number Type**: Distinguish between mobile, landline, and VoIP numbers
* **Country Validation**: Verify phone number matches expected country format

#### Risk Assessment

* **Disposable Number Detection**: Identify temporary numbers used to avoid traceability
* **Virtual Number Identification**: Flag numbers that may be virtual or VoIP-based
* **Activity Monitoring**: Track suspicious patterns across verification attempts
* **Blocklist Checking**: Check against internal lists of previously misused numbers

## Pricing

Phone verification is charged **per message sent** with transparent, pay-as-you-go pricing:

| Component       | Cost                          |
| --------------- | ----------------------------- |
| **Didit Fee**   | \$0.04 per verification       |
| **Carrier Fee** | Varies by country and channel |
| **Total**       | \$0.04 + carrier fee          |

We support multiple delivery channels with different pricing (availability varies by country):

| Channel      | Description                           |
| ------------ | ------------------------------------- |
| **SMS**      | Traditional text message delivery     |
| **WhatsApp** | Delivery via WhatsApp messaging       |
| **Telegram** | Delivery via Telegram messaging       |
| **RCS**      | Rich Communication Services messaging |
| **Viber**    | Delivery via Viber messaging          |
| **Zalo**     | Delivery via Zalo messaging (Vietnam) |

<Note>
  You only pay when a message is sent. If the user abandons before OTP delivery, you are not charged.
</Note>

→ [Phone Verification Pricing](/getting-started/phone-verification-pricing)


# Phone Verification Report
Source: https://docs.didit.me/core-technology/phone-verification/report-phone-verification

Parse Phone Verification responses: carrier data, line type, OTP lifecycle, cross-session matches, and risk warnings. Pay-per-OTP from $0.04 + carrier fees.

The Phone Verification report captures the full outcome of a phone OTP challenge: who we sent the code to, which carrier and channel handled it, how many attempts it took, whether the number is disposable or VoIP, and any cross-session matches against your blocklist or other users' sessions.

This page documents the JSON shape returned by the decision endpoint so you can parse OTP outcomes, carrier metadata, and risk flags for each verified number.

<Frame>
  <img alt="Didit phone verification report showing OTP outcome, carrier metadata and risk flags" />
</Frame>

## Overview

A phone report is produced every time a workflow node runs the Phone Verification feature. Each report represents one OTP challenge against one phone number and contains:

* The phone number broken into prefix, national number and full E.164 form, plus ISO country code and country name.
* Carrier metadata (`name`, `type`) resolved from the destination network.
* Boolean risk flags (`is_disposable`, `is_virtual`) derived from line-type analysis.
* The actual delivery channel used (`verification_method`) and the count of OTP send attempts.
* A chronological `lifecycle[]` log of every send, retry, delivery event, and code-check attempt.
* A `matches[]` array surfacing the same number on other sessions — any status, across KYC, KYB and standalone API verifications — or your blocklist.
* A `warnings[]` array — risk events emitted during the verification (see [Phone Verification warnings](/core-technology/phone-verification/warnings-phone-verification)).
* A `node_id` that identifies which workflow graph node produced the report (V3 sessions only).

In hosted verification flows Didit runs the OTP exchange for you. For direct API integrations the same flow is two calls — [`POST /v3/phone/send/`](/standalone-apis/phone-send) to deliver the code and [`POST /v3/phone/check/`](/standalone-apis/phone-check) to validate the user's entry. A pending OTP is valid for **5 minutes from the first send** (retries do not extend the window). In workflow sessions users get 2 OTP send attempts (`phone_max_retries`) and 2 code-entry attempts (`phone_max_check_attempts`) by default — both tunable per workflow node; exhausting either cap finalizes the step as `Declined` with `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`. The standalone phone API allows 3 code-entry attempts per verification.

## Where it appears in API responses

The decision endpoint (`GET /v3/session/{sessionId}/decision/`) returns phone reports under the plural array key **`phone_verifications`**. The array contains one entry per Phone Verification node in the workflow graph — typically one, but step-up flows may produce several.

```json theme={null}
{
  "session_id": "11111111-1111-1111-1111-111111111111",
  "status": "Approved",
  "phone_verifications": [
    { "status": "Approved", "node_id": "feature_phone_1", "...": "..." }
  ]
}
```

A `null` value means no Phone Verification step has run yet. Iterate the array (rather than reading `phone_verifications[0]`) when your workflow can collect more than one phone number.

## Schema

The canonical field-by-field schema lives on the [Data models](/reference/data-models#phone-verification) page.

```typescript theme={null}
interface PhoneVerification {
  status: "Not Finished" | "Approved" | "Declined" | "In Review" | "Expired";
  phone_number_prefix: string;       // E.g. "+34"
  phone_number: string;              // National number, no prefix
  full_number: string;               // Full E.164, e.g. "+34600600600"
  country_code: string;              // ISO 3166-1 alpha-2, e.g. "ES"
  country_name: string;
  carrier: {
    name: string;
    type:                              // From LineTypeChoices
      | "mobile" | "fixed_line" | "voip" | "isp" | "vpn"
      | "toll_free" | "premium_rate" | "shared_cost" | "local_rate"
      | "satellite" | "pager" | "payphone" | "voice_mail"
      | "calling_cards" | "service" | "short_codes_commercial"
      | "universal_access" | "other" | "unknown";
  };
  is_disposable: boolean;            // Temporary / burner number
  is_virtual: boolean;               // true when carrier.type is voip, isp or vpn
  verification_method:               // Actual channel that delivered the OTP
    | "sms" | "whatsapp" | "telegram" | "voice" | "rcs" | "viber" | "zalo";
  verification_attempts: number;     // OTP send attempts (initial send + resends)
  verified_at: string | null;        // ISO 8601, set when a valid OTP was entered
  warnings: Warning[];               // Risk events emitted during verification
  lifecycle: PhoneLifecycleEvent[];  // OTP send/retry/delivery/check timeline
  matches: PhoneMatch[];             // Cross-session / blocklist matches (max 5)
  node_id: string;                   // Workflow graph node that produced this report
}
```

### Status values

| Status         | Meaning                                                                                                                   |
| -------------- | ------------------------------------------------------------------------------------------------------------------------- |
| `Not Finished` | The OTP send has been initiated but the verification has not been finalized yet.                                          |
| `Approved`     | The user entered a valid OTP and no declining risk matched.                                                               |
| `Declined`     | An auto-decline warning fired (blocklist, high-risk, attempts exceeded) or a risk action configured to `DECLINE` matched. |
| `In Review`    | A risk action configured to `REVIEW` routed the step to manual review.                                                    |
| `Expired`      | The 5-minute OTP window elapsed with no valid code — applies to verifications created via the standalone phone API.       |

### Lifecycle event types

`lifecycle[]` is sorted chronologically. Each event has `type`, `timestamp`, `details`, and a billable `fee` (when applicable):

| Event type                              | Emitted when                                                                 |
| --------------------------------------- | ---------------------------------------------------------------------------- |
| `PHONE_VERIFICATION_MESSAGE_SENT`       | First OTP send attempt over the requested channel.                           |
| `PHONE_VERIFICATION_RETRY_MESSAGE_SENT` | Subsequent OTP send after the user requested a resend.                       |
| `PHONE_VERIFICATION_BLOCKED`            | The send was blocked (spam, suspicious, repeated, invalid number).           |
| `PHONE_DELIVERY_DELIVERED`              | Carrier confirmed delivery on the actual channel used.                       |
| `PHONE_DELIVERY_UNDELIVERABLE`          | Carrier reported the message could not be delivered.                         |
| `VALID_CODE_ENTERED`                    | The user submitted the correct OTP code.                                     |
| `INVALID_CODE_ENTERED`                  | The user submitted an incorrect OTP code (counts toward the code-entry cap). |
| `PHONE_VERIFICATION_APPROVED`           | Feature-level status was set to `Approved`.                                  |
| `PHONE_VERIFICATION_DECLINED`           | Feature-level status was set to `Declined`.                                  |
| `PHONE_VERIFICATION_IN_REVIEW`          | Feature-level status was set to `In Review`.                                 |
| `PHONE_VERIFICATION_EXPIRED`            | The OTP window elapsed without a valid code.                                 |

The `details` payload depends on the event family:

* **Send events** (`PHONE_VERIFICATION_MESSAGE_SENT`, `PHONE_VERIFICATION_RETRY_MESSAGE_SENT`, `PHONE_VERIFICATION_BLOCKED`) — `{ status, reason, channel, actual_channel }`. `status` is `Success`, `Retry` or `Blocked`; `reason` is `null` unless the send was blocked (`invalid_phone_number`, `repeated_attempts`, `suspicious`, `spam`, `unknown`); `channel` is the requested channel and `actual_channel` the channel that actually delivered (e.g. a WhatsApp send that fell back to SMS).
* **Delivery events** (`PHONE_DELIVERY_DELIVERED`, `PHONE_DELIVERY_UNDELIVERABLE`) — `{ channel, status }` with `status` `delivered` or `undeliverable`.
* **Check events** (`VALID_CODE_ENTERED`, `INVALID_CODE_ENTERED`) — `{ code_tried, status }` with `status` `Approved`, `Declined`, `Failed` or `Expired or Not Found`.
* **Final status events** — `null`, except `PHONE_VERIFICATION_DECLINED` / `PHONE_VERIFICATION_IN_REVIEW`, which carry `{ "reason": "<risk code>" }` (e.g. `PHONE_NUMBER_IN_BLOCKLIST`).

`fee` on a send event is the estimated price until delivery is confirmed, then the actual billed amount — delivery is billed per delivered message when the verification finalizes, and only `Blocked` sends are guaranteed free. Delivery, check and status events always carry `fee: 0`.

### Cross-session matches

`matches[]` records other sessions in the same application where the same number was seen — across KYC, KYB and standalone API verifications, regardless of their status — plus blocklist hits configured in the [management-api lists](/management-api/lists/overview). Sessions sharing the current session's `vendor_data` are excluded (the same end-user does not match themselves), and the array is capped at **5** entries. When the number is on your blocklist but none of the matched sessions is blocklisted, a synthetic entry with `source: "list_entry"` (all session fields `null`) is prepended to the array.

```typescript theme={null}
interface PhoneMatch {
  session_id: string | null;         // null when source = "list_entry"
  session_number: number | null;
  vendor_data: string | null;
  verification_date: string | null;  // ISO 8601, creation date of the matched session
  phone_number: string;
  status: string | null;             // Status of the matched session
  is_blocklisted: boolean;
  api_service: string | null;        // Set when the matched session came from a standalone API
  source: "session" | "list_entry";  // "list_entry" = manual blocklist hit
}
```

## Examples

### Approved — WhatsApp OTP, mobile carrier

```json theme={null}
{
  "status": "Approved",
  "phone_number_prefix": "+34",
  "phone_number": "600600600",
  "full_number": "+34600600600",
  "country_code": "ES",
  "country_name": "Spain",
  "carrier": { "name": "Orange", "type": "mobile" },
  "is_disposable": false,
  "is_virtual": false,
  "verification_method": "whatsapp",
  "verification_attempts": 1,
  "verified_at": "2025-08-24T09:12:39.684292Z",
  "warnings": [],
  "lifecycle": [
    {
      "type": "PHONE_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2025-08-24T09:12:30.580554Z",
      "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp" },
      "fee": 0.04
    },
    {
      "type": "PHONE_DELIVERY_DELIVERED",
      "timestamp": "2025-08-24T09:12:31.000000Z",
      "details": { "channel": "whatsapp", "status": "delivered" },
      "fee": 0
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2025-08-24T09:12:39.662157Z",
      "details": { "code_tried": "123456", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "PHONE_VERIFICATION_APPROVED",
      "timestamp": "2025-08-24T09:12:39.684292Z",
      "details": null,
      "fee": 0
    }
  ],
  "matches": [],
  "node_id": "feature_phone_1"
}
```

### Declined — blocklisted VoIP number

The user entered a valid OTP, but finalization found the number on the application's blocklist (auto-decline) and flagged its VoIP line type (`voip_number_action` left at `NO_ACTION`, so it logs as `information`). Because no matched session is blocklisted, the blocklist hit appears as a synthetic `list_entry` match.

```json theme={null}
{
  "status": "Declined",
  "phone_number_prefix": "+1",
  "phone_number": "5551234567",
  "full_number": "+15551234567",
  "country_code": "US",
  "country_name": "United States",
  "carrier": { "name": "VoIP Carrier", "type": "voip" },
  "is_disposable": false,
  "is_virtual": true,
  "verification_method": "sms",
  "verification_attempts": 1,
  "verified_at": "2025-08-24T09:11:10.221340Z",
  "warnings": [
    {
      "feature": "PHONE",
      "risk": "PHONE_NUMBER_IN_BLOCKLIST",
      "additional_data": { "blocklisted_session_id": null, "blocklisted_session_number": null, "api_service": null },
      "log_type": "error",
      "short_description": "Phone number in blocklist",
      "long_description": "The system detected that the phone number is in the blocklist, which is not allowed.",
      "node_id": "feature_phone_1"
    },
    {
      "feature": "PHONE",
      "risk": "VOIP_NUMBER_DETECTED",
      "additional_data": null,
      "log_type": "information",
      "short_description": "VoIP number detected",
      "long_description": "The system detected that the phone number is a VoIP number, which is not allowed.",
      "node_id": "feature_phone_1"
    }
  ],
  "lifecycle": [
    {
      "type": "PHONE_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2025-08-24T09:11:00.000000Z",
      "details": { "status": "Success", "reason": null, "channel": "sms", "actual_channel": "sms" },
      "fee": 0.04
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2025-08-24T09:11:10.221340Z",
      "details": { "code_tried": "482917", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "PHONE_VERIFICATION_DECLINED",
      "timestamp": "2025-08-24T09:11:10.350000Z",
      "details": { "reason": "PHONE_NUMBER_IN_BLOCKLIST" },
      "fee": 0
    }
  ],
  "matches": [
    {
      "session_id": null,
      "session_number": null,
      "vendor_data": null,
      "verification_date": null,
      "phone_number": "+15551234567",
      "status": null,
      "is_blocklisted": true,
      "api_service": null,
      "source": "list_entry"
    }
  ],
  "node_id": "feature_phone_1"
}
```

## Related

* [Phone Verification overview](/core-technology/phone-verification/overview) — feature behavior, pricing, supported channels.
* [Phone Verification warnings](/core-technology/phone-verification/warnings-phone-verification) — every risk code, decline triggers and configurable actions.
* [Data models — phone verification](/reference/data-models#phone-verification) — canonical field-by-field schema.
* [Standalone phone API](/standalone-apis/phone-send) — `POST /v3/phone/send/` and [`POST /v3/phone/check/`](/standalone-apis/phone-check) endpoints.
* [Management API — Lists](/management-api/lists/overview) — manage the phone blocklist that feeds `matches[]` with `source: list_entry`.


# Phone Verification Warnings
Source: https://docs.didit.me/core-technology/phone-verification/warnings-phone-verification

Reference for every Phone Verification risk code: HIGH_RISK_PHONE_NUMBER, VOIP_NUMBER_DETECTED, DISPOSABLE_NUMBER_DETECTED, blocklist, and OTP caps.

The Phone Verification feature emits **warnings** whenever a risk signal fires on the OTP flow or the number itself: a known bad number, a VoIP or disposable line, an OTP attempt cap, or a hit against another user's session. This page lists every code, what triggers it, and how to configure the workflow response.

## Overview

Warnings are tagged with feature `PHONE`. They appear under `phone_verifications[].warnings[]` in `GET /v3/session/{sessionId}/decision/` and follow the standard [warning object](/reference/data-models#warning-object) shape (`feature`, `risk`, `additional_data`, `log_type`, `short_description`, `long_description`, `node_id`). Each warning is also routed into the per-session log so it surfaces in the Business Console under the Phone section.

Some warnings are **hard auto-decline** triggers — they always set the feature status to `Declined`. Others map to a **configurable action** (`DECLINE`, `REVIEW`, or `NO_ACTION`, depending on the setting) defined in your workflow settings, so the same risk code may decline one workflow while only flagging another.

## Auto-decline conditions

The following warnings always decline the Phone Verification step regardless of configuration, and always carry `log_type: "error"`:

* `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` — the user exhausted an OTP attempt cap: by default 2 wrong code submissions (`phone_max_check_attempts`) or more than 2 OTP sends (`phone_max_retries`), both tunable per workflow node. The standalone phone API allows 3 code attempts.
* `PHONE_NUMBER_IN_BLOCKLIST` — the number is in your blocklist managed via the [Lists API](/management-api/lists/overview), or it matches a blocklisted session.

`HIGH_RISK_PHONE_NUMBER` — the delivery provider's anti-fraud layer refusing to send the OTP (`Blocked` send) — declines by default but is **no longer unconditional**: see [`high_risk_phone_action`](#blocked-sends) below.

## Configurable risks

Each of the following risks maps to a workflow setting you can configure to `DECLINE`, `REVIEW`, or `NO_ACTION` (the default — the warning is recorded without affecting the status). The configured action also sets the warning's `log_type`: `DECLINE` → `error`, `REVIEW` → `warning`, `NO_ACTION` → `information`.

| Setting                          | Risk code                    | Fires when                                                                                                                  |
| -------------------------------- | ---------------------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `voip_number_action`             | `VOIP_NUMBER_DETECTED`       | The carrier resolves to a `voip`, `isp`, or `vpn` line type.                                                                |
| `disposable_number_action`       | `DISPOSABLE_NUMBER_DETECTED` | The lookup flags the number as a temporary / burner provider.                                                               |
| `duplicated_phone_number_action` | `DUPLICATED_PHONE_NUMBER`    | The number matches another session of any status belonging to a different end-user. Skipped when the number is allowlisted. |

Duplicate detection runs within your application across KYC, KYB, and standalone API phone verifications, and groups sessions by `vendor_data` — sessions sharing the same `vendor_data` are treated as one end-user and are excluded from match results. Leave `vendor_data` empty and every session is treated as a distinct user.

### Blocked sends

`HIGH_RISK_PHONE_NUMBER` follows the same pattern with a narrower choice set, because a send the provider refused cannot be approved:

| Setting                  | Risk code                | Fires when                                                                                                                                        |
| ------------------------ | ------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `high_risk_phone_action` | `HIGH_RISK_PHONE_NUMBER` | The delivery provider's anti-fraud layer refused to send the OTP (`Blocked` send). Accepts only `DECLINE` or `REVIEW`, and defaults to `DECLINE`. |

The setting is applied **only when every high-risk block on the step carries `additional_data.risk_factors` of exactly `["device_attribute"]`** — the provider's "this device looks suspicious" signal, which is what fires on ordinary mobile lines. Any other risk factor, any mix that merely includes `device_attribute`, or a block with no risk factors at all declines regardless of the setting. The blocking reason (`repeated_attempts`, `suspicious`, or `spam`) is a separate field, returned in `additional_data.blocked_reason`.

Independently of the setting, a number on a phone allowlist created via the [Lists API](/management-api/lists/overview) is never auto-declined for a blocked send: the step goes to **In Review**, the warning carries `log_type: "warning"`, and `additional_data.phone_number_in_allowlist` is `true`.

## Verification attempt limits

The Phone Verification feature applies a hard cap on OTP attempts to prevent abuse:

* **Code-entry attempts** — Default **2** wrong submissions (`phone_max_check_attempts`) before the step finalizes as `Declined` with `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`. The standalone phone API allows **3** code attempts per verification.
* **Send attempts** — Default **2** sends in total (`phone_max_retries`): the initial send plus one resend. A further send request finalizes the step and raises `VERIFICATION_CODE_ATTEMPTS_EXCEEDED`.
* **OTP validity** — A pending OTP is valid for **5 minutes from the first send**; retries do not extend the window.

Both caps are tunable per workflow node. Independently of these caps, the delivery provider's anti-fraud layer can block a send outright (reason `repeated_attempts`, `suspicious`, or `spam`) — that raises `HIGH_RISK_PHONE_NUMBER`, not the attempts warning.

## Warnings produced

| Tag                                   | `log_type`                                                      | Description                                                                                                                                                                                                                                                                                                                                        |
| ------------------------------------- | --------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` | `error` (always)                                                | The user exceeded the OTP code-entry or send cap. Auto-declines.                                                                                                                                                                                                                                                                                   |
| `HIGH_RISK_PHONE_NUMBER`              | Follows `high_risk_phone_action`, or `warning` when allowlisted | The delivery provider blocked the OTP send. Declines by default; set `high_risk_phone_action` to `REVIEW` to route a device-signal-only block to In Review instead (see [Blocked sends](#blocked-sends)). A number on a phone allowlist also goes to In Review. `additional_data`: `{ blocked_reason, risk_factors, phone_number_in_allowlist? }`. |
| `PHONE_NUMBER_IN_BLOCKLIST`           | `error` (always)                                                | The number is in a blocklist created via the [Lists API](/management-api/lists/overview), or matches a blocklisted session. Auto-declines. `additional_data`: `{ blocklisted_session_id, blocklisted_session_number, api_service }` (all `null` for a pure list hit).                                                                              |
| `PHONE_NUMBER_IN_ALLOWLIST`           | `information`                                                   | The number matched other sessions but is in an allowlist created via the [Lists API](/management-api/lists/overview), so duplicate-phone actions are skipped. `additional_data`: `{ phone_number }`.                                                                                                                                               |
| `DISPOSABLE_NUMBER_DETECTED`          | Follows `disposable_number_action`                              | The number is a temporary / burner provider often used to evade traceability.                                                                                                                                                                                                                                                                      |
| `VOIP_NUMBER_DETECTED`                | Follows `voip_number_action`                                    | The number resolves to a `voip`, `isp`, or `vpn` line rather than a standard mobile or fixed line.                                                                                                                                                                                                                                                 |
| `DUPLICATED_PHONE_NUMBER`             | Follows `duplicated_phone_number_action`                        | The number matches another session — of any status — belonging to a different end-user (grouped by `vendor_data`). `additional_data`: `{ duplicated_session_id, duplicated_session_number, api_service }`.                                                                                                                                         |

## Cross-session matches

When a number is detected on other sessions or on your blocklist, those hits also appear under `phone_verifications[].matches[]` (capped at 5 entries). Each match carries `session_id`, `session_number`, `vendor_data`, `verification_date`, `phone_number`, `status`, `is_blocklisted`, `api_service`, and a `source` of `session` (another session with the same number, any status) or `list_entry` (a synthetic blocklist hit prepended to the array). If the current number is on your phone allowlist, Didit keeps the match evidence but emits `PHONE_NUMBER_IN_ALLOWLIST` instead of applying the duplicate-phone action. See the [Phone Verification report](/core-technology/phone-verification/report-phone-verification#cross-session-matches) for the full match schema.

## Example

A blocked send (`HIGH_RISK_PHONE_NUMBER`) on a VoIP number, with `voip_number_action` configured to `REVIEW`:

```json theme={null}
{
  "warnings": [
    {
      "feature": "PHONE",
      "risk": "HIGH_RISK_PHONE_NUMBER",
      "additional_data": { "blocked_reason": "suspicious" },
      "log_type": "error",
      "short_description": "High risk phone number",
      "long_description": "The system detected that the phone number is a high risk phone number, which is not allowed.",
      "node_id": "feature_phone_1"
    },
    {
      "feature": "PHONE",
      "risk": "VOIP_NUMBER_DETECTED",
      "additional_data": null,
      "log_type": "warning",
      "short_description": "VoIP number detected",
      "long_description": "The system detected that the phone number is a VoIP number, which is not allowed.",
      "node_id": "feature_phone_1"
    }
  ]
}
```

## Warning types

Each risk is assigned a severity based on your application's configuration. Severities fall into three categories:

<WarningTypes />

## Related

* [Phone Verification overview](/core-technology/phone-verification/overview) — feature behavior, pricing, supported channels.
* [Phone Verification report](/core-technology/phone-verification/report-phone-verification) — full response shape including `lifecycle[]` and `matches[]`.
* [Data models — phone verification](/reference/data-models#phone-verification) — canonical field-by-field schema.
* [Management API — Lists](/management-api/lists/overview) — manage the phone blocklist used by `PHONE_NUMBER_IN_BLOCKLIST`.


# Proof of Address Overview
Source: https://docs.didit.me/core-technology/proof-of-address/overview

Verify residential addresses with AI-powered extraction from utility bills, bank statements, and government documents. Pay-per-call $0.20.

Proof of Address (PoA) verification allows you to verify a user's residential address through official documents. This feature simplifies the address verification process, enabling users to capture or upload documents that confirm their address.

<AgentPromptAccordion title="Proof of Address Integration Prompt" />

The Academy lesson on reading a verification result reaches the proof of address check at 7:20.

<VideoEmbed title="Proof of address — Didit Academy" />

## How it works

Didit's Proof of Address Verification delivers a robust solution for verifying a user's residential address through official documentation. Our solution combines advanced AI, computer vision, and comprehensive security checks to provide fast, reliable address verification at scale.

<Steps>
  <Step title="Intelligent Document Capture" icon="camera">
    Users can verify their address through:

    | Method                 | Description                                                                                                |
    | ---------------------- | ---------------------------------------------------------------------------------------------------------- |
    | **Auto Capture**       | Our AI automatically detects optimal document positioning and captures automatically at the perfect moment |
    | **Upload Option**      | Users can upload existing documents in various formats (PDF, JPG, PNG)                                     |
    | **Multi-Page Support** | Seamlessly handles multi-page documents like bank statements                                               |
  </Step>

  <Step title="Advanced Data Extraction & Verification" icon="file-lines">
    Powerful processing capabilities:

    * High-precision OCR for extracting address information
    * Intelligent document classification to identify document types
    * Name matching with identity documents for cross-verification
    * Issue date extraction and validation against configured requirements
    * Format and pattern matching for all address fields
  </Step>

  <Step title="Comprehensive Validation" icon="shield-check">
    Our AI-powered system performs extensive checks:

    | Check                       | Description                                               |
    | --------------------------- | --------------------------------------------------------- |
    | **Document Authenticity**   | Verification of document legitimacy                       |
    | **Tamper Detection**        | Image integrity analysis to detect manipulation           |
    | **Address Standardization** | Formatting and normalizing address fields                 |
    | **Geocoding**               | Providing location coordinates from the extracted address |
    | **Language Detection**      | Identifying and validating document language              |
  </Step>

  <Step title="Seamless Results Delivery" icon="file-export">
    Access verification results through multiple channels:

    * Real-time dashboard updates
    * Instant webhook notifications
    * RESTful API integration
    * Comprehensive reports with detailed verification session information
  </Step>
</Steps>

## Document Requirements

To ensure successful address verification, documents should meet these criteria:

#### Accepted Document Types

The following table lists the accepted document types and their respective subtypes. All documents must be issued within the last 3 months unless otherwise specified.

| Document Type                  | Subtypes                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| ------------------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Utility Bill**               | Electricity Bill, Water Bill, Gas Bill, Internet Bill, Phone Bill, Cable TV Bill, Satellite TV Bill, Trash Collection Bill, Sewage Bill, Heating Bill, Combined Utilities Bill, Municipal Services Bill                                                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| **Bank Statement**             | Account Statement, Credit Card Statement, Bank Letter Confirming Address, Mortgage Statement, Loan Statement, Savings Account Statement, Checking Account Statement, Investment Account Statement, Business Account Statement, Credit Union Statement, Debit Card Statement, Line of Credit Statement                                                                                                                                                                                                                                                                                                                                                                                 |
| **Government-Issued Document** | Tax Assessment, Voter Registration Card, ID document, Residency Certificate, Government Letter/Notification, Census Letter, Individual Registration Certificate, Property Tax Bill, Vehicle Registration, Social Security Statement, Unemployment Benefits Letter, Disability Benefits Letter, Pension Statement, Court Summons, Jury Duty Notice, Municipal Permit, Immigration Document                                                                                                                                                                                                                                                                                             |
| **Other Proof of Address**     | Lease Agreement, Rental Agreement, Employer Letter Confirming Address, Insurance Policy Document, School Enrollment Letter, Notarized Affidavit of Address, Solicitor Letter Confirming Address, Student Loan Statement, Court Document Confirming Address, Homeowners Insurance Policy, Renters Insurance Policy, Auto Insurance Policy, Health Insurance Statement, Medical Bill, Hospital Bill, Subscription Service Bill, Gym Membership Statement, Property Management Letter, Homeowners Association Statement, University Transcript, College Enrollment Verification, Payroll Stub, Employment Verification Letter, Retirement Account Statement, Brokerage Account Statement |

#### Country availability

By default, Proof of Address supports the same countries and territories as ID Verification, including Turks and Caicos Islands (`TCA`) and Tuvalu (`TUV`). Every supported country offers the four document categories listed above. You can restrict this default coverage in your workflow's Proof of Address settings.

<Note>
  If an existing workflow does not show a newly supported country, open its Proof of Address settings and save them again to refresh the workflow's allowed-country configuration.
</Note>

<Frame>
  <img alt="Didit proof of address accepted document types — utility bills, bank and government statements" />
</Frame>

#### General Requirements

* Valid document within 90 days of issue date
* Physically intact (free from damage, scratches, or stains)
* Complete address information clearly visible
* Document issuer name and logo visible
* Name on document should match the user's verified identity
* Different from ID document (cannot be the same document used for ID verification)

#### Image Requirements

* Original document captured in real-time or high-quality scan
* Supported formats: JPG, JPEG, PNG, TIFF, PDF
* Maximum file size: 15MB
* Full-color image with all corners visible
* No digital editing or manipulation
* All pages included for multi-page documents


# Proof of address report
Source: https://docs.didit.me/core-technology/proof-of-address/report-proof-of-address

Parse the proof-of-address report: extracted address, document type, issuer, dates, name-match scores, PDF overlay-manipulation evidence, and warnings.

## Overview

Proof-of-address (POA) verification accepts a single PDF or image (TIFF, JPG, JPEG, PNG, WEBP, optionally ZIP-compressed) up to 15 MB, runs document-type classification, LLM-based extraction, and PDF/EXIF forensics, and returns:

* The **extracted address** — both raw and structured (`street_1`, `city`, `region`, `postal_code`, lat/lng).
* **Document metadata** — file size, content type, creation and modified dates, EXIF dates, signature info, and any overlay-manipulation evidence from PDF forensics.
* **Name match scores** against the verified ID document and against expected details supplied at session creation.
* **Bank-related extra fields** (account number, IBAN, sort code, routing number, SWIFT/BIC, branch) when the document is a bank statement.

<Frame>
  <img alt="Didit proof of address report screenshot showing extracted address fields and document type" />
</Frame>

<Note>
  POA extraction performs unstructured-text reading, which introduces a **5–15 second** latency per document. Webhooks fire only when the entire workflow step completes — do not poll the decision endpoint faster than every 5 s during this window.
</Note>

## Where it appears in API responses

The decision endpoint returns POA as the plural array **`poa_verifications[]`** in `GET /v3/session/{sessionId}/decision/`. Each entry is one execution of the POA node in your workflow; sessions with multiple POA steps (e.g., bank statement + utility bill) produce one entry per execution with its own `node_id`.

```text theme={null}
GET /v3/session/{sessionId}/decision/
  ──▶ { "poa_verifications": [ { node_id, status, document_type, poa_address, … }, … ] }
```

The shape below mirrors the canonical schema — see [Data models](/reference/data-models#proof-of-address).

## Schema

See [Proof of address in the Data Models reference](/reference/data-models#proof-of-address) for the canonical schema.

```typescript theme={null}
interface POAV3 {
  status: 'Not Finished' | 'Approved' | 'Declined' | 'In Review';
  node_id: string | null;

  issuing_state: string | null;         // ISO 3166-1 alpha-3
  document_type:                        // never null — falls back to 'UNKNOWN'
    | 'UTILITY_BILL'
    | 'BANK_STATEMENT'
    | 'GOVERNMENT_ISSUED_DOCUMENT'
    | 'OTHER_POA_DOCUMENT'
    | 'UNKNOWN';
  document_subtype: string;             // e.g. 'ELECTRICITY_BILL', 'ACCOUNT_STATEMENT';
                                        // never null — falls back to 'UNKNOWN'
  issuer: string | null;
  issue_date: string | null;            // YYYY-MM-DD
  expiration_date: string | null;       // YYYY-MM-DD when present

  // Extracted address
  poa_address: string | null;           // raw, single-line
  poa_formatted_address: string | null; // geocoded/formatted
  poa_parsed_address: {
    address_type?: string;
    street_1?: string;
    street_2?: string;
    city?: string;
    region?: string;
    postal_code?: string;
    country?: string;                   // ISO 3166-1 alpha-2
    raw_results?: object;
    document_location?: { latitude: number; longitude: number };
  } | null;

  document_file: string | null;         // presigned URL, expires after ~4 hours
  document_language: string | null;     // ISO 639-1, e.g. 'en'
  name_on_document: string | null;

  // Expected details (when supplied at session creation)
  expected_details_address: string | null;
  expected_details_formatted_address: string | null;
  expected_details_parsed_address: object | null;

  // Match scores (float, 0-100)
  name_match_score_expected_details: number | null;
  name_match_score_id_verification: number | null;

  // PDF + image forensics
  document_metadata: {
    file_size: number | null;
    content_type: string | null;
    creation_date: string | null;
    modified_date: string | null;
    creator: string | null;
    producer: string | null;
    software: string | null;
    encryption: string | null;
    is_signed: boolean | null;
    is_tampered: boolean | null;
    signature_info: object | null;
    exif_original_date: string | null;
    exif_digitized_date: string | null;
    processed_by_known_editor: boolean | string | null;
    has_different_creation_mod_date: boolean | null;
    overlay_manipulation: {
      detected: boolean;
      analyzed: boolean;
      signals: string[];                // 'duplicate_font_subset', 'glyph_fragmentation'
      duplicate_font_subsets: object[];
      fragmented_fonts: object[];
      manipulated_regions: {
        page: number;
        x: number;
        y: number;
        width: number;
        height: number;
        page_width: number;
        page_height: number;
      }[];
    } | null;                           // null for non-PDF uploads or when not analyzed
  } | null;

  // Bank-related and custom fields
  extra_fields: {
    bank_account_number: string | null;
    bank_iban: string | null;
    bank_sort_code: string | null;
    bank_routing_number: string | null;
    bank_swift_bic: string | null;
    bank_branch_name: string | null;
    bank_branch_address: string | null;
    document_phone_number: string | null;
    additional_names: string[];
    [customField: string]: unknown;
  };

  extra_files: string[];                // presigned URLs for additional uploaded files

  // QR codes and barcodes
  detected_codes: {
    type: string;                       // 'QR_CODE', 'CODE_128', 'EAN_13', 'DATA_MATRIX', 'PDF_417', …
    page_number: number;                // 1-based
    position: [number, number][] | null;
    x: number | null;
    y: number | null;
    width: number | null;
    height: number | null;
    page_width: number;
    page_height: number;
    raw_payload: string;                // base64, empty string when unavailable
    parsed_payload: unknown | null;      // null when located but undecodable
  }[];

  warnings: Warning[];                  // see Data Models — Warning object
}
```

Each entry in `warnings[]` is a [Warning object](/reference/data-models#warning-object): `{ feature, risk, additional_data, log_type, short_description, long_description, node_id }`, with `feature` always `"PROOF_OF_ADDRESS"` for this report.

## Status values

`status` uses the feature-level status enum (`FeatureStatusChoices`).

| Value          | Meaning                                                                                                                                                                                                              |
| -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `Not Finished` | The POA node has not completed for this session (default state).                                                                                                                                                     |
| `Approved`     | The document parsed cleanly and no warning resolved to Decline or Review.                                                                                                                                            |
| `In Review`    | At least one configurable warning is set to **Review** for your workflow (and nothing declined).                                                                                                                     |
| `Declined`     | A hard-decline warning fired (`MISSING_ADDRESS_INFORMATION`, `POA_DOCUMENT_EXPIRED`, `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_VALIDATE_DOCUMENT_AGE`), or a configurable warning is set to **Decline** for your workflow. |

Custom status rules configured on the workflow node can further adjust the computed status; rules combine with precedence Declined > In Review > Approved. See [Proof of address warnings](/core-technology/proof-of-address/warnings-proof-of-address) for the full risk-to-action mapping, including the workflow-only retry behavior of `FUTURE_ISSUE_DATE`.

## PDF overlay-manipulation evidence

When the submitted document is a PDF, `document_metadata.overlay_manipulation` may contain forensic evidence of suspected text overlays:

* `detected` — `true` when the check found manipulation evidence.
* `analyzed` — `true` when the PDF could be analysed at all.
* `signals` — the checks that fired (`duplicate_font_subset`, `glyph_fragmentation`).
* `manipulated_regions` — page-coordinate rectangles around the suspected edited text. Each rectangle uses the PDF page coordinate space (`x`, `y`, `width`, `height`, `page_width`, `page_height`) so reviewers can highlight the affected area in a PDF preview.

The field is `null` when the document is not a PDF or the PDF could not be analysed. When `detected=true`, the system also emits a `SUSPECTED_DOCUMENT_MANIPULATION` warning whose `additional_data` mirrors the signals and rectangles above (unless a stronger signal — modification after digital signing, `is_tampered=true` — took priority, in which case `additional_data` describes the signature tampering instead).

## QR codes and barcodes

Every POA report includes `detected_codes`, covering every processed page. Each item contains:

| Field                       | Description                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------ |
| `type`                      | Detected symbology, such as `QR_CODE`, `CODE_128`, `EAN_13`, `DATA_MATRIX`, or `PDF_417`   |
| `page_number`               | 1-based page number                                                                        |
| `position`                  | Detected polygon in rendered-page pixels, or `null` when no reliable location is available |
| `x`, `y`, `width`, `height` | Bounding box in rendered-page pixels, or `null` when no reliable location is available     |
| `page_width`, `page_height` | Rendered page dimensions used by the coordinates                                           |
| `parsed_payload`            | Decoded string or structured value, or `null` when the code can only be located            |
| `raw_payload`               | Raw decoder payload as a base64 string when available; otherwise an empty string           |

`detected_codes` is an empty array when no supported code is found. Didit never guesses a payload: damaged or unreadable codes may be returned with their location and `parsed_payload: null`, while failures in code detection do not fail the POA verification.

## Examples

### Approved — bank statement

```json theme={null}
{
  "poa_verifications": [
    {
      "status": "Approved",
      "node_id": "feature_poa_1",
      "issuing_state": "USA",
      "document_type": "BANK_STATEMENT",
      "document_subtype": "ACCOUNT_STATEMENT",
      "issuer": "National Bank",
      "issue_date": "2026-04-15",
      "expiration_date": null,
      "document_language": "en",
      "name_on_document": "John A. Smith",
      "poa_address": "123 Main St, Apartment 4B, New York, NY 10001",
      "poa_formatted_address": "123 Main St, Apartment 4B, New York, NY 10001, USA",
      "poa_parsed_address": {
        "address_type": "Street",
        "street_1": "123 Main St",
        "street_2": "Apartment 4B",
        "city": "New York",
        "region": "NY",
        "postal_code": "10001",
        "country": "US",
        "document_location": { "latitude": 40.7128, "longitude": -74.0060 }
      },
      "document_file": "https://<media-host>/.../poa.pdf?X-Amz-Expires=14400",
      "document_metadata": {
        "file_size": 246810,
        "content_type": "application/pdf",
        "creation_date": "2026-04-15",
        "modified_date": "2026-04-15",
        "creator": "PDFKit",
        "producer": "Quartz",
        "software": null,
        "encryption": null,
        "is_signed": false,
        "is_tampered": false,
        "signature_info": null,
        "exif_original_date": null,
        "exif_digitized_date": null,
        "processed_by_known_editor": false,
        "has_different_creation_mod_date": false,
        "overlay_manipulation": null
      },
      "name_match_score_expected_details": 100,
      "name_match_score_id_verification": 98,
      "expected_details_address": null,
      "expected_details_formatted_address": null,
      "expected_details_parsed_address": null,
      "extra_fields": {
        "bank_account_number": "****1234",
        "bank_iban": null,
        "bank_sort_code": null,
        "bank_routing_number": "021000089",
        "bank_swift_bic": "NABNUS33",
        "bank_branch_name": "Manhattan Midtown",
        "bank_branch_address": "111 Wall St, New York, NY",
        "document_phone_number": null,
        "additional_names": []
      },
      "extra_files": [],
      "detected_codes": [
        {
          "type": "QR_CODE",
          "page_number": 1,
          "position": [[820, 1120], [1002, 1120], [1002, 1302], [820, 1302]],
          "x": 820,
          "y": 1120,
          "width": 182,
          "height": 182,
          "page_width": 1190,
          "page_height": 1684,
          "raw_payload": "aHR0cHM6Ly9uYXRpb25hbGJhbmsuZXhhbXBsZS9zdG10Lzk5ODE=",
          "parsed_payload": "https://nationalbank.example/stmt/9981"
        },
        {
          "type": "CODE_128",
          "page_number": 1,
          "position": [[112, 1480], [560, 1480], [560, 1540], [112, 1540]],
          "x": 112,
          "y": 1480,
          "width": 448,
          "height": 60,
          "page_width": 1190,
          "page_height": 1684,
          "raw_payload": "MDAxMjM0NTY3ODk=",
          "parsed_payload": "001234567 89"
        }
      ],
      "warnings": []
    }
  ]
}
```

### Declined — overlay manipulation + name mismatch

```json theme={null}
{
  "poa_verifications": [
    {
      "status": "Declined",
      "node_id": "feature_poa_1",
      "issuing_state": "GBR",
      "document_type": "UTILITY_BILL",
      "document_subtype": "ELECTRICITY_BILL",
      "issuer": "BritishEnergy",
      "issue_date": "2026-03-10",
      "expiration_date": null,
      "document_language": "en",
      "name_on_document": "JOHN B SMYTH",
      "poa_address": "44 King's Road, London, SW3 4UD",
      "poa_formatted_address": "44 King's Road, London, SW3 4UD, United Kingdom",
      "poa_parsed_address": {
        "street_1": "44 King's Road",
        "city": "London",
        "postal_code": "SW3 4UD",
        "country": "GB",
        "document_location": { "latitude": 51.4880, "longitude": -0.1690 }
      },
      "document_file": "https://<media-host>/.../poa.pdf?X-Amz-Expires=14400",
      "document_metadata": {
        "file_size": 412910,
        "content_type": "application/pdf",
        "creation_date": "2026-03-10",
        "modified_date": "2026-05-12",
        "creator": "Adobe Acrobat Pro",
        "producer": "Adobe PDF Library",
        "software": "Adobe Acrobat",
        "encryption": null,
        "is_signed": false,
        "is_tampered": false,
        "signature_info": null,
        "exif_original_date": null,
        "exif_digitized_date": null,
        "processed_by_known_editor": false,
        "has_different_creation_mod_date": true,
        "overlay_manipulation": {
          "detected": true,
          "analyzed": true,
          "signals": ["duplicate_font_subset", "glyph_fragmentation"],
          "duplicate_font_subsets": [{ "page": 1, "base_font": "Helvetica" }],
          "fragmented_fonts": [],
          "manipulated_regions": [
            { "page": 1, "x": 102.4, "y": 318.1, "width": 187.0, "height": 18.0, "page_width": 595, "page_height": 842 }
          ]
        }
      },
      "name_match_score_expected_details": 62,
      "name_match_score_id_verification": 60,
      "expected_details_address": null,
      "expected_details_formatted_address": null,
      "expected_details_parsed_address": null,
      "extra_fields": {
        "bank_account_number": null, "bank_iban": null, "bank_sort_code": null,
        "bank_routing_number": null, "bank_swift_bic": null,
        "bank_branch_name": null, "bank_branch_address": null,
        "document_phone_number": null, "additional_names": []
      },
      "extra_files": [],
      "detected_codes": [],
      "warnings": [
        {
          "feature": "PROOF_OF_ADDRESS",
          "risk": "SUSPECTED_DOCUMENT_MANIPULATION",
          "additional_data": {
            "reason": "Overlay-text manipulation detected: same base font embedded with multiple subset prefixes on 1 page(s).",
            "detection_method": "overlay_text_manipulation",
            "signals": ["duplicate_font_subset", "glyph_fragmentation"],
            "duplicate_font_subsets": [{ "page": 1, "base_font": "Helvetica" }],
            "fragmented_fonts": [],
            "manipulated_regions": [
              { "page": 1, "x": 102.4, "y": 318.1, "width": 187.0, "height": 18.0, "page_width": 595, "page_height": 842 }
            ]
          },
          "log_type": "error",
          "short_description": "Suspected document manipulation",
          "long_description": "The system detected signs of potential document manipulation or editing.",
          "node_id": "feature_poa_1"
        },
        {
          "feature": "PROOF_OF_ADDRESS",
          "risk": "NAME_MISMATCH_ID_VERIFICATION",
          "additional_data": {
            "poa_name": "JOHN B SMYTH",
            "kyc_name": "John A. Smith",
            "match_score": 60
          },
          "log_type": "warning",
          "short_description": "Name mismatch with ID verification",
          "long_description": "The full name on the document does not match the name from the user's verified identity documents.",
          "node_id": "feature_poa_1"
        }
      ]
    }
  ]
}
```

## Related

* [Proof of address warnings](/core-technology/proof-of-address/warnings-proof-of-address) — every warning code POA can emit
* [Proof of address overview](/core-technology/proof-of-address/overview) — accepted document types and verification rules
* [Data models — Proof of address](/reference/data-models#proof-of-address) — canonical schema
* [Webhooks](/integration/webhooks) — `status.updated` carries POA payloads

<Note>
  `document_file` and `extra_files[]` are presigned URLs that expire after about 4 hours. Re-fetch the decision endpoint to refresh URLs. Store only the verification status and parsed address fields on your side — minimise retained document data.
</Note>


# Proof of address warnings
Source: https://docs.didit.me/core-technology/proof-of-address/warnings-proof-of-address

Every proof-of-address warning: name and address mismatches, expired or unsupported documents, overlay manipulation, extraction failures, and configurable actions.

## Overview

Proof-of-address (POA) verification emits warnings on `poa_verifications[].warnings[]` for every quality, authenticity, or matching issue detected during extraction and forensic analysis. Each warning is a [Warning object](/reference/data-models#warning-object) with `feature` set to `"PROOF_OF_ADDRESS"`. A handful of risks always force `Declined`; the rest follow a per-risk action (`DECLINE` / `REVIEW` / `NO_ACTION`) configured on your workflow.

Every risk below is verified against the live decision pipeline; the exact short and long description strings are reproduced verbatim in the tables.

<Note>
  POA extraction introduces a **5–15 second** latency per document. Warnings are written only when the workflow step completes; do not poll faster than every 5 s.
</Note>

## Two production paths

POA warnings are produced on two different paths, and the risk set differs between them:

* **Workflow sessions** (the POA step inside a verification session) — the upload endpoint first runs blocking validation with a retry loop (see [Retry behavior](#retry-behavior-workflow-sessions)), then the final stored warnings are computed by `check_poa_risks` plus the multi-document name check.
* **Standalone API** (`POST /v3/poa/`) — warnings come from `check_poa_risks` only. There is no retry loop, no verified-ID context, and only one document, so `NAME_MISMATCH_ID_VERIFICATION`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS`, `POA_MAX_ATTEMPTS_EXCEEDED`, and `FUTURE_ISSUE_DATE` are **never** produced by the standalone API. The pre-extraction validation errors are discarded on this path.

`POOR_DOCUMENT_QUALITY` is defined in the risk enum and reserved in the action mapping, but **no code path in the POA pipeline produces it** — it never appears in `warnings[]` on either path. Do not branch on it.

## Auto-decline warnings (always force `Declined`)

These risks are in `AUTO_DECLINE_RISKS`; when logged, the POA status is `Declined` regardless of configuration, and `log_type` is always `error`.

| Risk                              | Cause                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Recommended remediation                                                                |
| --------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------- |
| `MISSING_ADDRESS_INFORMATION`     | No address could be extracted from the document.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Ask the user to resubmit a document that clearly shows their address.                  |
| `POA_DOCUMENT_EXPIRED`            | The document is expired by one of two paths: its **printed expiration date** has passed, or it is **older than the configured maximum age** for its type. Defaults: **3 months** for `UTILITY_BILL` and `BANK_STATEMENT`, **12 months** for `GOVERNMENT_ISSUED_DOCUMENT` and `OTHER_POA_DOCUMENT` (a month counts as 30 days; `-1` disables the check). `additional_data` always carries `expiration_reason` (`printed_expiration` or `age_window`), `document_type`, `document_subtype`, and `issue_date`; the `printed_expiration` path adds `expiration_date`, and the `age_window` path adds `max_age_months`. | Ask the user for a valid or more recent document, or raise `age_months` for that type. |
| `INVALID_DOCUMENT_TYPE`           | The document could not be classified into any supported POA type (`document_type` falls back to `UNKNOWN`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | Ask the user to resubmit; check the file is not corrupted.                             |
| `UNABLE_TO_VALIDATE_DOCUMENT_AGE` | The document-age check itself failed (error while computing the expiration from the issue date).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | Ask the user for a document with a clearly readable issue date.                        |

`FUTURE_ISSUE_DATE` is also listed in `AUTO_DECLINE_RISKS`, but it has a single producer in pre-extraction validation (an issue date more than 7 days in the future) whose errors only feed the **workflow retry loop** — it surfaces as a blocking upload error there, is never produced by the standalone API, and is not written to `warnings[]`. See [Retry behavior](#retry-behavior-workflow-sessions).

## Configurable warnings

Each of these follows an action knob on the workflow's POA node (`DECLINE` / `REVIEW` / `NO_ACTION`). The warning's `log_type` mirrors the configured action: `error` for Decline, `warning` for Review, `information` for No action.

| Risk                                         | Cause                                                                                                                                                                                                                                                                                                                 | Action knob                                        | Default     |
| -------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------- | ----------- |
| `NAME_MISMATCH_WITH_PROVIDED`                | The name on the document scores below `poa_name_match_score_threshold` (default 86) against the name supplied at session creation (`expected_details`).                                                                                                                                                               | `poa_name_or_address_mismatch_action`              | Review      |
| `NAME_MISMATCH_ID_VERIFICATION`              | The name on the document scores below the threshold against the verified ID document. `additional_data`: `{ poa_name, kyc_name, match_score }`. Workflow sessions only.                                                                                                                                               | `poa_name_or_address_mismatch_action`              | Review      |
| `ADDRESS_MISMATCH_WITH_PROVIDED`             | The extracted address differs from the address supplied via API, or either address could not be verified as a residential address.                                                                                                                                                                                    | `poa_name_or_address_mismatch_action`              | Review      |
| `POA_COUNTRY_MISMATCH_WITH_PROVIDED`         | The document's country does not match the country supplied via API (ISO-3 normalised). `additional_data`: `{ expected_country, extracted_country }`.                                                                                                                                                                  | `poa_name_or_address_mismatch_action`              | Review      |
| `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS`        | Two or more POA documents in the same session carry different names. `additional_data` includes both node IDs, both names, and the match score. Workflow sessions only.                                                                                                                                               | `poa_name_or_address_mismatch_action`              | Review      |
| `DOCUMENT_METADATA_MISMATCH`                 | The file is empty (`file_size` 0) or its EXIF dates are malformed.                                                                                                                                                                                                                                                    | `poa_document_issues_action`                       | Review      |
| `SUSPECTED_DOCUMENT_MANIPULATION`            | Forensics found manipulation evidence — modification after digital signing (`is_tampered`), overlay-text manipulation (with `additional_data.manipulated_regions` rectangles), a known PDF editor, inconsistent EXIF dates, or a suspicious re-export. `additional_data.detection_method` names the check that fired. | `poa_document_authenticity_action`                 | **Decline** |
| `UNSUPPORTED_DOCUMENT_LANGUAGE`              | The document's language is not in `poa_languages_allowed`.                                                                                                                                                                                                                                                            | `poa_unsupported_language_action`                  | **Decline** |
| `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` | The detected document type is not enabled in `poa_documents_allowed` for the document's country, or its subtype is explicitly disabled.                                                                                                                                                                               | `poa_unsupported_document_type_action`             | **Decline** |
| `ISSUER_NOT_IDENTIFIED`                      | The issuing institution could not be identified from the document.                                                                                                                                                                                                                                                    | `poa_issuer_not_identified_action`                 | Review      |
| `UNABLE_TO_EXTRACT_ISSUE_DATE`               | No valid issue date could be located on the document.                                                                                                                                                                                                                                                                 | `poa_issue_date_not_detected_action`               | Review      |
| `POA_NAME_NOT_DETECTED`                      | No name was detected on the document.                                                                                                                                                                                                                                                                                 | `poa_issue_date_not_detected_action` (shared knob) | Review      |
| `UNPARSABLE_OR_INVALID_ADDRESS`              | An address was extracted but could not be parsed and geocoded into a valid residential address.                                                                                                                                                                                                                       | `poa_unparsable_or_invalid_address_action`         | Review      |
| `POA_MAX_ATTEMPTS_EXCEEDED`                  | The user exhausted `poa_max_retry_attempts` (default 2) in the workflow retry loop. `additional_data`: `{ attempts }`. Workflow sessions only.                                                                                                                                                                        | `poa_max_attempts_exceeded_action`                 | **Decline** |

<Note>
  There is **one shared action** for all name and address mismatches: `poa_name_or_address_mismatch_action` covers both name risks, both address risks, and the cross-document name check — you cannot configure name and address mismatch behavior separately. On the standalone API the same group follows the `poa_address_mismatch_action` request option (the `poa_name_mismatch_action` option is accepted but never read).
</Note>

## Standalone API differences (`POST /v3/poa/`)

The standalone endpoint builds the same risk-to-action mapping but with request-level options that only accept `DECLINE` or `NO_ACTION` (all defaulting to `DECLINE`):

* `UNABLE_TO_EXTRACT_ISSUE_DATE` and `POA_NAME_NOT_DETECTED` are **hard-coded to Decline** on this endpoint.
* `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` and `UNPARSABLE_OR_INVALID_ADDRESS` are **informational** here — their actions default to No action and are not configurable per request.
* `FUTURE_ISSUE_DATE`, `POOR_DOCUMENT_QUALITY`, `NAME_MISMATCH_ID_VERIFICATION`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS`, and `POA_MAX_ATTEMPTS_EXCEEDED` are never produced — a future-dated document is **not** auto-declined on this endpoint.

See the [POST /v3/poa/ API reference](/standalone-apis/proof-of-address) for the request options.

## Retry behavior (workflow sessions)

In a verification session, the POA upload step runs blocking validation before the document is accepted. When it finds a blocking error — `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_EXTRACT_ISSUE_DATE`, `FUTURE_ISSUE_DATE`, `POA_NAME_NOT_DETECTED`, `MISSING_ADDRESS_INFORMATION`, `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`, `UNSUPPORTED_DOCUMENT_LANGUAGE`, or `POA_DOCUMENT_EXPIRED` — the upload is rejected with `400` and the risk code as the message, and the user can try again with a better document.

For `POA_DOCUMENT_EXPIRED`, the `400` body also includes `expiration_reason` (`printed_expiration` or `age_window`) so your UI can show the accurate reason; on the `age_window` path it additionally includes `max_age_months`. On the `printed_expiration` path `max_age_months` is intentionally omitted, because the document was rejected for its printed expiration date rather than an age window.

Once the user has burned `poa_max_retry_attempts` attempts (default 2, configurable 2–5), the submission is accepted anyway: the stored warnings are recomputed from the saved document, `POA_MAX_ATTEMPTS_EXCEEDED` is appended, and the status is resolved from the full risk set. This is why `FUTURE_ISSUE_DATE` can block an upload yet never appears in `warnings[]`.

## Configurable settings

The workflow's POA node exposes these knobs (matching `VerificationSettings` fields):

| Setting                                    | Controls                                                                                                                                                                      | Default                                                                           |
| ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------- |
| `poa_name_or_address_mismatch_action`      | `NAME_MISMATCH_WITH_PROVIDED`, `NAME_MISMATCH_ID_VERIFICATION`, `ADDRESS_MISMATCH_WITH_PROVIDED`, `POA_COUNTRY_MISMATCH_WITH_PROVIDED`, `POA_NAME_MISMATCH_BETWEEN_DOCUMENTS` | Review                                                                            |
| `poa_document_issues_action`               | `DOCUMENT_METADATA_MISMATCH`                                                                                                                                                  | Review                                                                            |
| `poa_document_authenticity_action`         | `SUSPECTED_DOCUMENT_MANIPULATION`                                                                                                                                             | Decline                                                                           |
| `poa_unsupported_language_action`          | `UNSUPPORTED_DOCUMENT_LANGUAGE`                                                                                                                                               | Decline                                                                           |
| `poa_unsupported_document_type_action`     | `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`                                                                                                                                  | Decline                                                                           |
| `poa_issuer_not_identified_action`         | `ISSUER_NOT_IDENTIFIED`                                                                                                                                                       | Review                                                                            |
| `poa_issue_date_not_detected_action`       | `UNABLE_TO_EXTRACT_ISSUE_DATE`, `POA_NAME_NOT_DETECTED`                                                                                                                       | Review                                                                            |
| `poa_unparsable_or_invalid_address_action` | `UNPARSABLE_OR_INVALID_ADDRESS`                                                                                                                                               | Review                                                                            |
| `poa_max_attempts_exceeded_action`         | `POA_MAX_ATTEMPTS_EXCEEDED`                                                                                                                                                   | Decline                                                                           |
| `poa_documents_allowed`                    | Per-country accepted document types, each with `enabled` and `age_months` (`-1` = unlimited); per-subtype overrides via `document_subtypes_config`.                           | Utility bill and bank statement: 3 months; government-issued and other: 12 months |
| `poa_languages_allowed`                    | Accepted document languages.                                                                                                                                                  | All supported languages                                                           |
| `poa_name_match_score_threshold`           | Minimum name-match score (0–100) before the `NAME_MISMATCH*` risks fire.                                                                                                      | 86                                                                                |
| `poa_max_retry_attempts`                   | Upload attempts before the retry loop gives up (2–5).                                                                                                                         | 2                                                                                 |

## Name matching logic

POA name matching tolerates common variations:

* **Middle names and initials** are matched leniently (presence/absence is allowed).
* **Candidate names** — every name detected on the document (`name_on_document` plus `additional_names`) is scored, and the best-scoring candidate is kept.
* **Match threshold** — the default `poa_name_match_score_threshold` is **86**; a score below it fires the relevant `NAME_MISMATCH*` warning.

The numeric scores are exposed on the report as `name_match_score_expected_details` and `name_match_score_id_verification` (0–100). Score values are useful for fine-grained review even when no warning has been raised.

## Examples

### Overlay manipulation (Decline by default)

```json theme={null}
{
  "warnings": [
    {
      "feature": "PROOF_OF_ADDRESS",
      "risk": "SUSPECTED_DOCUMENT_MANIPULATION",
      "additional_data": {
        "reason": "Overlay-text manipulation detected: same base font embedded with multiple subset prefixes on 1 page(s).",
        "detection_method": "overlay_text_manipulation",
        "signals": ["duplicate_font_subset", "glyph_fragmentation"],
        "duplicate_font_subsets": [{ "page": 1, "base_font": "Helvetica" }],
        "fragmented_fonts": [],
        "manipulated_regions": [
          { "page": 1, "x": 102.4, "y": 318.1, "width": 187.0, "height": 18.0, "page_width": 595, "page_height": 842 }
        ]
      },
      "log_type": "error",
      "short_description": "Suspected document manipulation",
      "long_description": "The system detected signs of potential document manipulation or editing.",
      "node_id": "feature_poa_1"
    }
  ]
}
```

### Expired document + missing address (auto-decline)

```json theme={null}
{
  "warnings": [
    {
      "feature": "PROOF_OF_ADDRESS",
      "risk": "POA_DOCUMENT_EXPIRED",
      "additional_data": {
        "expiration_reason": "age_window",
        "max_age_months": 3,
        "document_subtype": "ELECTRICITY_BILL",
        "document_type": "UTILITY_BILL",
        "issue_date": "2025-11-02"
      },
      "log_type": "error",
      "short_description": "Document expired",
      "long_description": "The submitted document is older than the maximum accepted age of 3 months from its issue date, which exceeds the acceptable time period for validity.",
      "node_id": "feature_poa_1"
    },
    {
      "feature": "PROOF_OF_ADDRESS",
      "risk": "MISSING_ADDRESS_INFORMATION",
      "additional_data": null,
      "log_type": "error",
      "short_description": "Missing address information",
      "long_description": "The document does not contain complete or clear address information that can be extracted.",
      "node_id": "feature_poa_1"
    }
  ]
}
```

### Name mismatch (Review by default)

```json theme={null}
{
  "warnings": [
    {
      "feature": "PROOF_OF_ADDRESS",
      "risk": "NAME_MISMATCH_ID_VERIFICATION",
      "additional_data": {
        "poa_name": "JOHN B SMYTH",
        "kyc_name": "John A. Smith",
        "match_score": 60
      },
      "log_type": "warning",
      "short_description": "Name mismatch with ID verification",
      "long_description": "The full name on the document does not match the name from the user's verified identity documents.",
      "node_id": "feature_poa_1"
    }
  ]
}
```

## Related

* [Proof of address report](/core-technology/proof-of-address/report-proof-of-address) — full response shape, overlay-manipulation forensics, status semantics
* [Proof of address overview](/core-technology/proof-of-address/overview) — accepted document types
* [Data models — Proof of address](/reference/data-models#proof-of-address) — canonical schema and Warning object
* [Webhooks](/integration/webhooks) — `status.updated` carries POA warnings

### Warning types

<WarningTypes />


# Questionnaires
Source: https://docs.didit.me/core-technology/questionnaires/overview

Build custom KYC questionnaires with a drag-and-drop builder. Multi-language, conditional logic, manual review routing. Pay-per-call $0.10.

Didit's Questionnaires let you design structured, dynamic forms to collect additional information from users during verification. Use our visual builder to drag and drop elements, organize content into sections, localize text for multiple languages, and route results for manual review when needed.

<AgentPromptAccordion title="Questionnaires Integration Prompt" />

In the Academy lesson on reading a verification result, the 11:54 chapter covers Document AI and questionnaires.

<VideoEmbed title="Document AI and questionnaires — Didit Academy" />

***

## Two Ways to Build Questionnaires

Didit offers **two distinct approaches** to creating questionnaires, allowing you to choose the right level of complexity for your needs:

<Frame>
  <img alt="Didit KYC questionnaire simple and advanced builder modes side by side" />
</Frame>

### 1. Simple Mode: Quick Form Builder

The **Simple Mode** is perfect for creating straightforward forms quickly. Use our intuitive drag-and-drop interface to add elements, set required fields, and publish in minutes.

<Frame>
  <img alt="Didit questionnaire simple mode drag-and-drop form builder interface" />
</Frame>

**Best for:**

* Quick data collection forms
* Simple surveys and attestations
* Teams new to form building
* Single-language questionnaires

**How it works:**

1. Open the Questionnaire Builder
2. Drag elements from the palette onto your form
3. Configure each element (label, required, placeholder)
4. Preview and publish

***

### 2. Advanced Mode: Visual Graph Builder

The **Advanced Mode** unlocks powerful features for complex data collection scenarios using a **visual node-based editor**. Build sophisticated questionnaires with conditional logic, branching paths, and full control over flow.

<Frame>
  <img alt="Didit advanced questionnaire visual node-based graph editor with branching logic" />
</Frame>

**Best for:**

* Multi-language questionnaires
* Complex forms with conditional branching
* Compliance-driven data collection with different paths
* Forms requiring manual review workflows

**Key capabilities:**

* **Visual node editor**: Drag, drop, and connect nodes on an infinite canvas
* **Smart connections**: Drag from a node handle to empty space to instantly create and connect a new node
* **Conditional branching**: Route users to different questions based on previous answers
* **Multi-language support**: Translate all user-facing content
* **Keyboard shortcuts**: Undo (Ctrl/Cmd+Z), Redo (Ctrl/Cmd+Shift+Z), Delete (Delete/Backspace)
* **Zoom and pan**: Navigate complex forms with scroll-to-zoom and drag-to-pan

#### Graph Builder Node Types

| Node Type           | Color  | Description                           | When to Use                                       |
| ------------------- | ------ | ------------------------------------- | ------------------------------------------------- |
| **Question Nodes**  | Blue   | Input elements that collect user data | Text inputs, dropdowns, file uploads, dates, etc. |
| **Text Nodes**      | Green  | Read-only content displayed to users  | Instructions, explanations, legal text            |
| **Branching Nodes** | Orange | Conditional routing based on answers  | "If country is US, show tax form"                 |
| **Section Nodes**   | Gray   | Visual grouping of related elements   | Organize questions into logical sections          |

> **Connection Rules:** Section and Text nodes can connect to Questions and other Text nodes, but not directly to Branching nodes. Branching nodes can connect to any node type.

***

## Questionnaire Templates

Templates help you get started quickly with pre-configured forms for common use cases. You can use them as-is or customize them to fit your needs.

<Frame>
  <img alt="Didit questionnaire pre-built templates for source of funds and KYC compliance" />
</Frame>

### Pre-Built Templates

| Template                 | Description                                         | Typical Elements                          |
| ------------------------ | --------------------------------------------------- | ----------------------------------------- |
| **Source of Funds**      | Capture income sources and supporting documentation | Dropdown, Long Text, File Upload          |
| **Employment Details**   | Collect job title, employer, income range           | Short Text, Dropdown, Number              |
| **Purpose of Account**   | Understand intended account usage                   | Single Choice, Multiple Choice, Long Text |
| **Beneficial Ownership** | Identify UBOs and ownership structure               | Short Text, Number, File Upload           |
| **Tax Residency**        | Collect tax-related declarations                    | Country, Consent, File Upload             |
| **Risk Assessment**      | Gather risk-relevant information                    | Multiple Choice, Dropdown, Long Text      |

***

## How it works

Our questionnaire workflow is designed for flexibility and auditability:

### 1. Build in the Console (No Code)

* Drag and drop elements to create your questionnaire
* Organize content into multiple sections for clarity
* Mark elements as required or optional
* Configure placeholders and helper descriptions
* Add choices (with optional free-text follow-up) for dropdown and single-choice
* Configure file/image upload limits per element

### 2. Localize Content

* Write your content once in the questionnaire's `default_language`
* Define the supported `languages` — when you publish, every title, description, placeholder, choice label, and validation message is **translated automatically** into all of them
* Fine-tune any translation by hand in the builder; manual edits are preserved until the source text changes
* The end-user sees content automatically in the best available language

### 3. Publish and Collect

* Activate the questionnaire and embed it in your verification flow
* End-users complete the sections and submit answers
* File uploads (documents, images) are stored and linked to the response

### 4. Review and Decide

* Responses are saved with a `status`: `Approved`, `In Review`, or `Not Finished`
* You can force all questionnaire responses to go `In Review`, so a person manually approves them
* Review answers and files in the console, then mark as `Approved`

> Note: Questionnaires do not produce risk warnings. Governance is achieved through required fields, validation, and review workflows.

***

## Key capabilities

| Capability                  | Simple Mode | Advanced Mode |
| --------------------------- | ----------- | ------------- |
| Drag-and-drop builder       | ✅           | ✅             |
| Required/optional fields    | ✅           | ✅             |
| Placeholders & descriptions | ✅           | ✅             |
| Multiple sections           | ✅           | ✅             |
| File upload limits          | ✅           | ✅             |
| Visual graph editor         | ❌           | ✅             |
| Conditional branching       | ❌           | ✅             |
| Multi-language translations | ❌           | ✅             |
| Choice logic (require text) | ❌           | ✅             |
| Force manual review         | ❌           | ✅             |
| Undo/Redo support           | ❌           | ✅             |
| Keyboard shortcuts          | ❌           | ✅             |

**Full feature list:**

* **Visual Builder**: Create and manage questionnaires with an intuitive drag-and-drop editor
* **Sections**: Group related questions; add headers and separators to guide users
* **Automatic translations**: Write content in one language — all user-facing text is translated into every other selected language on publish, with manual fine-tuning supported
* **Validation**: Mark fields required; enforce max files per upload element
* **Choice Logic**: For dropdown/single-choice, optionally require additional text per selected option
* **Uploads**: Collect documents and images with file count limits (e.g., up to 3 files)
* **Manual Review**: Optionally force all responses to `In Review` pending human approval
* **Activation Toggle**: Enable or disable the questionnaire per application
* **Workflow Integration**: Add questionnaires to KYC or run them standalone as a Questionnaire Verification workflow
* **APIs & Webhooks**: Read structured results via API and receive updates

***

## Element types

You can add the following element types in the builder (selectable from the console):

### Input Elements

| Element          | Description                 | Configuration Options |
| ---------------- | --------------------------- | --------------------- |
| **SHORT\_TEXT**  | Single-line free text       | Placeholder, required |
| **LONG\_TEXT**   | Multi-line free text        | Placeholder, required |
| **NUMBER**       | Numeric input               | Placeholder, required |
| **EMAIL**        | Email input with validation | Placeholder, required |
| **PHONE**        | Phone number input          | Placeholder, required |
| **ADDRESS**      | Address input               | Placeholder, required |
| **DATE\_PICKER** | Date selection              | Placeholder, required |
| **TIME**         | Time input                  | Placeholder, required |

### Choice Elements

| Element              | Description                  | Configuration Options                     |
| -------------------- | ---------------------------- | ----------------------------------------- |
| **DROPDOWN**         | Single selection from a list | Choices, `requires_text_input` per choice |
| **SINGLE\_CHOICE**   | Radio-style single selection | Choices, `requires_text_input` per choice |
| **MULTIPLE\_CHOICE** | Multi-select checklist       | Choices                                   |
| **COUNTRY**          | Country selector             | Required                                  |
| **CONSENT**          | Checkbox or acknowledgement  | Required, custom label                    |

### Upload Elements

| Element          | Description     | Configuration Options       |
| ---------------- | --------------- | --------------------------- |
| **IMAGE**        | Image upload    | `max_files` (1-5), required |
| **FILE\_UPLOAD** | Document upload | `max_files` (1-5), required |

### Layout Elements

| Element             | Description                | Notes                        |
| ------------------- | -------------------------- | ---------------------------- |
| **PARAGRAPH**       | Read-only explanatory text | Not answerable               |
| **SECTION\_HEADER** | Visual section header      | Not answerable, not required |
| **SEPARATOR**       | Visual divider             | Not answerable, not required |

**Behavioral notes:**

* `SECTION_HEADER` and `SEPARATOR` are presentation-only. They ignore required/placeholder/choices/file limits.
* For choice elements, define choices as `{ label, value, requires_text_input? }`.
* For upload elements, set `max_files` (1–5) to control how many files can be attached.

***

## Forcing manual review

Some compliance workflows require human review of every response. From the console, you can set questionnaires to always result in `In Review`. A reviewer then approves or requests changes, after which the response becomes `Approved`.

**When to use manual review:**

* High-risk customer onboarding
* Sensitive data collection (Source of Funds, UBO declarations)
* Regulatory requirements for human oversight
* Quality assurance during initial rollout

***

## Example use cases

### Source of Funds

Capture income sources, amounts, and upload supporting documents (e.g., payslips, statements). Combine dropdowns, long text, and file uploads.

**Typical structure:**

* Section 1: Employment Status (Dropdown)
* Section 2: Income Sources (Multiple Choice + Long Text)
* Section 3: Supporting Documents (File Upload)
* Section 4: Declaration (Consent)

***

### Association or Membership

Record affiliations, roles, and proof of membership; include consent elements for declarations.

**Typical structure:**

* Organization Name (Short Text)
* Role/Position (Dropdown)
* Duration of Membership (Date Picker)
* Membership Proof (File Upload)
* Declaration (Consent)

***

### Purpose of Relationship & Expected Account Activity

Collect intent, expected transaction volumes, countries of activity, and anticipated counterparties. Use single/multiple choice, number inputs, and paragraphs for context.

**Typical structure:**

* Section 1: Account Purpose (Multiple Choice)
* Section 2: Expected Monthly Volume (Number + Dropdown for currency)
* Section 3: Countries of Activity (Country - multiple)
* Section 4: Transaction Types (Multiple Choice)
* Section 5: Additional Information (Long Text)

***

## Simple vs Advanced Mode: When to Use Each

| Scenario                      | Recommended Mode |
| ----------------------------- | ---------------- |
| Single-language, basic form   | Simple           |
| Multi-language support needed | Advanced         |
| Quick internal survey         | Simple           |
| Compliance questionnaire      | Advanced         |
| One-time data collection      | Simple           |
| Conditional branching paths   | Advanced         |
| Force manual review           | Advanced         |
| Complex multi-section forms   | Advanced         |

***

## Getting Started

1. **New to questionnaires?** Start with **Simple Mode** to learn the builder
2. **Need translations or conditional logic?** Switch to **Advanced Mode** for the visual graph editor

> See how results are structured in the [Questionnaires Report](/core-technology/questionnaires/report-questionnaire) page.


# Questionnaire Report
Source: https://docs.didit.me/core-technology/questionnaires/report-questionnaire

Didit questionnaire report reference covering sections, items, element types, conditional visibility, and per-item answers in V3 decision responses.

The questionnaire report contains the structured form a user was shown, the path they took through any conditional branches, and the answer for each visible item. It is returned per node, so multi-instance workflows (for example, one questionnaire per UBO) carry one entry per occurrence.

<Frame>
  <img alt="Didit KYC questionnaire report showing structured answers, sections and element types" />
</Frame>

## Overview

Each questionnaire response describes:

* The **questionnaire version** the user saw (title, description, languages, version metadata, sections).
* The **visible items** for the path the user actually took through the form's graph — items hidden by conditional logic are dropped from the response.
* The **answer** for every visible interactive item, in the shape that matches its `element_type`.
* A single **status** for the response as a whole.

Layout elements are reshaped rather than answered: each `SECTION_HEADER` becomes a section boundary (its title and description become the section's `title`/`description`), while `HEADING`, `PARAGRAPH`, and `SEPARATOR` stay in `items[]` without an `answer` key so the report keeps the same visual structure the user saw.

## Where it appears

The questionnaire report appears as the plural array **`questionnaire_responses[]`** in `GET /v3/session/{sessionId}/decision/`, for both KYC and KYB sessions, whenever a questionnaire feature ran. The field is `null` until at least one questionnaire instance has started. Each entry carries a `node_id` so multi-instance workflows can disambiguate which graph step produced it.

```text theme={null}
GET /v3/session/{sessionId}/decision/
  ──▶ { "questionnaire_responses": [ { node_id, questionnaire_id, title, status, sections, … }, … ] }
```

## Item shape

See [Questionnaire response in the Data Models reference](/reference/data-models#questionnaire-response) for the canonical schema.

```typescript theme={null}
interface QuestionnaireResponse {
  questionnaire_id: string;          // UUID of the questionnaire version that was answered
  title: string;                     // Questionnaire name, as set in the Console
  description: string | null;
  languages: string[];               // Supported language codes
  default_language: string;          // Default language code
  is_active: boolean;
  is_simple_questionnaire: boolean;  // true = flat list, false = branching graph
  questionnaire_group_id: string;    // UUID shared by all versions of the same questionnaire
  version: number;                   // Version number within the group
  published_at: string | null;       // ISO 8601 — when this version was published
  status: "Approved" | "In Review" | "Not Finished";
  sections: Array<{
    title: string | null;            // From the SECTION_HEADER that opens the section
    description: string | null;
    items: QuestionnaireItem[];
  }>;
  node_id: string | null;            // Workflow graph node that ran this questionnaire
}

interface QuestionnaireItem {
  uuid: string;                      // Form element UUID
  value: string;                     // Stable node id of the element within the questionnaire graph
  element_type:
    | "SHORT_TEXT" | "LONG_TEXT"
    | "DROPDOWN" | "SINGLE_CHOICE" | "MULTIPLE_CHOICE"
    | "NUMBER" | "EMAIL" | "PHONE" | "ADDRESS" | "COUNTRY"
    | "DATE_PICKER" | "TIME"
    | "CONSENT"
    | "FILE_UPLOAD" | "IMAGE"
    | "REPEATABLE_GROUP"
    | "HEADING" | "PARAGRAPH" | "SEPARATOR";   // layout-only — no answer key
  is_required: boolean;
  title: string | null;              // Localized
  description: string | null;        // Only populated on HEADING / PARAGRAPH text blocks
  placeholder: string | null;        // Localized
  choices: Array<{                   // DROPDOWN / SINGLE_CHOICE / MULTIPLE_CHOICE
    label: string;                   // Localized
    value: string;                   // Stable across languages
    requires_text_input?: boolean;   // Selecting this option triggers a free-text follow-up
  }> | null;
  max_files: number | null;          // FILE_UPLOAD / IMAGE upload cap (1–5)
  required_if: {                     // Conditional requirement rule, or null
    rules: Array<{ field: string; operator: string; value?: unknown }>;
    logic: "and" | "or";
  } | null;
  repeatable_config: {               // REPEATABLE_GROUP only, or null
    min_items?: number;
    max_items?: number;
    item_label?: string;             // Localized
    fields: Array<object>;           // Sub-field definitions (value, element_type, title, …)
  } | null;
  answer?: Answer | null;            // Omitted on HEADING / PARAGRAPH / SEPARATOR; null when unanswered
}
```

`SECTION_HEADER` elements never appear in `items[]` — they open a new section and supply its `title` and `description`.

### Element types

| Element type                        | Answer shape                                                               | Notes                                                                                                 |
| ----------------------------------- | -------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
| `SHORT_TEXT`, `LONG_TEXT`           | `{ value: string }`                                                        | Free text.                                                                                            |
| `EMAIL`, `DATE_PICKER`, `TIME`      | `{ value: string }`                                                        | Typed text variants.                                                                                  |
| `NUMBER`                            | `{ value: number }`                                                        | JSON number — validated server-side as numeric.                                                       |
| `COUNTRY`                           | `{ value: string }`                                                        | ISO 3166-1 alpha-3 code (e.g. `"ESP"`), validated server-side.                                        |
| `PHONE`                             | `{ value: { countryCode, callingCode, number } }`                          | Structured phone object.                                                                              |
| `ADDRESS`                           | `{ value: { street, streetExtraInfo, city, state, postalCode, country } }` | Structured address object.                                                                            |
| `DROPDOWN`, `SINGLE_CHOICE`         | `{ value: string, text?: string }`                                         | `value` is the choice value; `text` is filled when the picked choice has `requires_text_input: true`. |
| `MULTIPLE_CHOICE`                   | `{ value: string[], text?: string }`                                       | Array of choice values.                                                                               |
| `CONSENT`                           | `{ value: boolean }`                                                       | JSON boolean.                                                                                         |
| `FILE_UPLOAD`, `IMAGE`              | `{ files: string[] }`                                                      | Each entry is a pre-signed URL.                                                                       |
| `REPEATABLE_GROUP`                  | `{ items: Array<{ [fieldValue]: Answer }> }`                               | One object per repetition, keyed by each sub-field's `value` with its own answer object.              |
| `HEADING`, `PARAGRAPH`, `SEPARATOR` | *(no `answer` key)*                                                        | Pure layout — kept in `items[]` for structure.                                                        |

A visible interactive item the user never answered is returned with `"answer": null`.

### Conditional visibility

When a questionnaire defines a graph (conditional logic), only items on the path the user actually took are included. An item hidden by a branch the user did not follow does **not** appear in `sections[].items` — even if it exists in the template. Sections left with no visible items are dropped entirely.

## Status values

The response-level `status` is one of three values. Internally, the base status (`Approved`, or `In Review` when the workflow forces manual review) is combined with any matching custom status rules using the platform-wide precedence Declined > In Review > Approved; a questionnaire-level `Declined` outcome is then mapped to `In Review` so operators handle the final disposition during review.

| Status         | Meaning                                                                                                              |
| -------------- | -------------------------------------------------------------------------------------------------------------------- |
| `Not Finished` | The user has not submitted the questionnaire yet.                                                                    |
| `In Review`    | Submitted and waiting on manual review (the workflow forces manual review, or a status rule escalated the response). |
| `Approved`     | Submitted and accepted.                                                                                              |

## Warnings

Questionnaires emit a single warning code, produced when a **custom status rule** configured on the questionnaire node matches an answer:

| Tag                            | Description                                                                                            |
| ------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `CUSTOM_STATUS_RULE_TRIGGERED` | A workflow status rule evaluated a questionnaire answer and changed (or confirmed) the feature status. |

The warning's `additional_data` carries `field`, `operator`, `rule_value`, `actual_value`, `target_status`, and `score` when the rule defines one. Its `log_type` follows the rule's target status: `error` for Declined, `warning` for In Review, `information` otherwise.

Unlike other features, the questionnaire entry does not embed a `warnings[]` array — triggered-rule logs are recorded on the session under `feature: "QUESTIONNAIRE"` and surface in the Console review screen (see also the [Business Verification warnings listing](/business-verification/warnings#questionnaire); the same code applies to KYC sessions).

## Example — Source-of-funds questionnaire

```json theme={null}
{
  "questionnaire_responses": [
    {
      "questionnaire_id": "9f7485e0-b00b-4d56-9d3e-7859b68d1213",
      "title": "Source of Funds",
      "description": "Reply to this questionnaire to help us understand the source of funds.",
      "languages": ["en"],
      "default_language": "en",
      "is_active": true,
      "is_simple_questionnaire": true,
      "questionnaire_group_id": "2b6a9d40-13a8-4b1e-9a6c-3f1d2e4b5a60",
      "version": 1,
      "published_at": "2025-11-02T09:14:55.000000Z",
      "status": "Approved",
      "sections": [
        {
          "title": null,
          "description": null,
          "items": [
            {
              "uuid": "618636d9-7d5c-41ce-b8d0-1ab2a4be20db",
              "value": "question_1",
              "element_type": "DROPDOWN",
              "is_required": true,
              "title": "What is your primary source of funds?",
              "description": null,
              "placeholder": null,
              "choices": [
                { "label": "Salary", "value": "salary" },
                { "label": "Business Income", "value": "business_income" },
                { "label": "Savings", "value": "savings" },
                { "label": "Investments", "value": "investments" },
                { "label": "Inheritance/Gift", "value": "inheritance_gift" },
                { "label": "Other", "value": "other", "requires_text_input": true }
              ],
              "max_files": 1,
              "required_if": null,
              "repeatable_config": null,
              "answer": { "value": "salary" }
            },
            {
              "uuid": "2d16b527-72be-42e0-8e96-b164b818386c",
              "value": "question_2",
              "element_type": "LONG_TEXT",
              "is_required": true,
              "title": "Provide details of the primary source.",
              "description": null,
              "placeholder": null,
              "choices": null,
              "max_files": 1,
              "required_if": null,
              "repeatable_config": null,
              "answer": { "value": "Software engineer at Acme Ltd since 2018." }
            },
            {
              "uuid": "1bf8a2a3-14ee-48a8-bb3d-175481aae4aa",
              "value": "question_3",
              "element_type": "SINGLE_CHOICE",
              "is_required": true,
              "title": "Will any funds originate from third parties?",
              "description": null,
              "placeholder": null,
              "choices": [
                { "label": "Yes", "value": "yes", "requires_text_input": true },
                { "label": "No", "value": "no" }
              ],
              "max_files": 1,
              "required_if": null,
              "repeatable_config": null,
              "answer": { "value": "yes", "text": "One-off gift from parents, EUR 8,000." }
            },
            {
              "uuid": "a90a073d-e098-404c-bbce-5130d8b12a13",
              "value": "question_4",
              "element_type": "FILE_UPLOAD",
              "is_required": true,
              "title": "Upload a proof of funds document",
              "description": null,
              "placeholder": null,
              "choices": null,
              "max_files": 3,
              "required_if": null,
              "repeatable_config": null,
              "answer": {
                "files": [
                  "https://<media-host>/.../payslip-jul.pdf",
                  "https://<media-host>/.../payslip-aug.pdf"
                ]
              }
            }
          ]
        }
      ],
      "node_id": "feature_questionnaire"
    }
  ]
}
```

## Example — Not finished

```json theme={null}
{
  "questionnaire_responses": [
    {
      "questionnaire_id": "9f7485e0-b00b-4d56-9d3e-7859b68d1213",
      "title": "Source of Funds",
      "description": "Reply to this questionnaire to help us understand the source of funds.",
      "languages": ["en"],
      "default_language": "en",
      "is_active": true,
      "is_simple_questionnaire": true,
      "questionnaire_group_id": "2b6a9d40-13a8-4b1e-9a6c-3f1d2e4b5a60",
      "version": 1,
      "published_at": "2025-11-02T09:14:55.000000Z",
      "status": "Not Finished",
      "sections": [
        {
          "title": null,
          "description": null,
          "items": [
            {
              "uuid": "618636d9-7d5c-41ce-b8d0-1ab2a4be20db",
              "value": "question_1",
              "element_type": "DROPDOWN",
              "is_required": true,
              "title": "What is your primary source of funds?",
              "description": null,
              "placeholder": null,
              "choices": [
                { "label": "Salary", "value": "salary" },
                { "label": "Other", "value": "other", "requires_text_input": true }
              ],
              "max_files": 1,
              "required_if": null,
              "repeatable_config": null,
              "answer": null
            }
          ]
        }
      ],
      "node_id": "feature_questionnaire"
    }
  ]
}
```

When the user has reached the questionnaire step but not submitted answers yet, the response is returned with `status: "Not Finished"` and `"answer": null` on every visible item. A session that never reached the step produces no entry at all — `questionnaire_responses` stays `null` when no instance exists.

## Notes

* **File URLs expire.** Entries in `answer.files` are pre-signed URLs (4-hour validity by default). Re-fetch the decision endpoint when you need fresh URLs.
* **Localization.** Item `title`, `placeholder`, choice `label`, and section `title`/`description` are returned in English when the questionnaire supports it, otherwise in the questionnaire's `default_language`. The `value` of a choice remains stable across languages so you can key business logic off it safely.
* **Item `description` is layout-only.** It is populated only on `HEADING`/`PARAGRAPH` text blocks; interactive items always return `description: null`.

## Related

<CardGroup>
  <Card title="Questionnaires overview" icon="clipboard-list" href="/core-technology/questionnaires/overview">
    How to build, version, and attach questionnaires to a workflow.
  </Card>

  <Card title="Data models — Questionnaire response" icon="table" href="/reference/data-models#questionnaire-response">
    Canonical field-by-field schema for this object.
  </Card>

  <Card title="Retrieve session" icon="arrow-down" href="/sessions-api/retrieve-session">
    Endpoint reference for the V3 decision payload.
  </Card>
</CardGroup>


# Reusable KYC
Source: https://docs.didit.me/core-technology/reusable-kyc/overview

Let users verify identity once and securely reuse it across multiple apps. Cuts onboarding friction, eliminates repeat KYC. Free with Didit.

Reusable KYC allows users to verify their identity once and securely share that verification across multiple Didit-integrated applications. This reduces onboarding friction while maintaining security and compliance.

<AgentPromptAccordion title="Reusable KYC Integration Prompt" />

This chapter of the Didit Academy KYB lesson picks up at party verification and reusing KYC sessions.

In the KYB Academy lesson, the 7:04 chapter shows party verification reusing an existing KYC session instead of making a UBO verify twice.

<VideoEmbed title="Party verification and reusing KYC sessions — Didit Academy" />

## How it works

<Steps>
  <Step title="Initial verification">
    The user completes a standard KYC process (ID Verification + facial recognition). Verification data is encrypted and stored in the user's Didit ID, compliant with eIDAS2.
  </Step>

  <Step title="Reuse at a new application">
    When the user encounters another Didit-integrated application, they select the option to reuse their existing KYC. A quick facial recognition check confirms their identity, and they consent to share specific data.
  </Step>

  <Step title="Instant onboarding">
    The new application receives the verified KYC information instantly — no document re-upload, no waiting.
  </Step>
</Steps>

## Key Benefits

| For Users                  | For Businesses          | For Compliance                 |
| -------------------------- | ----------------------- | ------------------------------ |
| Verify once, use anywhere  | Faster user onboarding  | Maintains regulatory standards |
| Control over data sharing  | Reduced drop-off rates  | Complete audit trail           |
| Seconds instead of minutes | Higher conversion rates | Cross-jurisdiction support     |

## Security and Compliance

| Area                  | Details                                                   |
| --------------------- | --------------------------------------------------------- |
| **Encryption**        | End-to-end encryption for all stored and transferred data |
| **Biometric re-auth** | Facial recognition required for every reuse               |
| **Regulatory**        | eIDAS2 compliant, supports AML/KYC requirements           |
| **Cross-border**      | Works across jurisdictions                                |

<Frame>
  <img alt="Didit reusable KYC flow letting verified users carry identity across services" />
</Frame>

Reusable KYC is automatically available to users who have completed an initial verification. Users can choose to reuse their KYC or perform a fresh check at any time.


# Share KYC via API
Source: https://docs.didit.me/core-technology/reusable-kyc/share-kyc-via-api

Securely share verification data between trusted partners via API. Eliminate repeat KYC across integrated services with short-lived share tokens.

## How It Works

Let's assume a user `A` passed user verification in `Service X` and is now registering at the partner `Service Y`. If `Service X` agrees to share the information about `A` with `Service Y`, it can be done as follows:

1. **Generate Share Token (`Service X`)**: `Service X` makes an API call to generate a secure, short-lived `share_token` for a specific user's verification session. This token is designated for use by `Service Y` only. See API Reference: [Share Session API](/sessions-api/share-session/share).

2. **Pass Token to Partner (`Service X` -> `Service Y`)**: `Service X` securely transmits the generated `share_token` to `Service Y` through a pre-arranged backend channel.

3. **Import Session (`Service Y`)**: `Service Y` uses the received `share_token` to make an API call to import the user's data. This creates a complete copy of the verification session, including all documents and checks, within `Service Y`'s own environment. See API Reference: [Import Shared Session API](/sessions-api/share-session/import).

### Import Options

When importing a session, `Service Y` has control over how to handle the results:

* **`trust_review`**: This boolean parameter determines if `Service Y` trusts the review and final status (`Approved`/`Declined`) from `Service X`.
  * `true`: The session is copied with the original status. The user is instantly onboarded (or rejected) on `Service Y`.
  * `false`: The session data is copied, but the status is automatically set to `In Review`. This allows `Service Y` to use the collected documents and data but perform its own internal review process to make a final decision.
* **`workflow_id`**: `Service Y` must specify which of its own verification workflows to associate with the imported session.
* **`vendor_data`**: `Service Y` can assign its own internal user identifier to the imported session.

### Important Considerations

* **Finished Sessions Only**: A share token can only be generated for sessions that have a finished status (`Approved`, `Declined`, `In Review`).
* **No Duplicates**: A specific session can only be imported once into a given partner application. Subsequent attempts will be rejected.

***

## Reusable KYC vs. Share KYC via API

While both features facilitate identity reuse, they serve different purposes:

| Feature            | User-Controlled Reusable KYC                                        | Share KYC via API (B2B Sharing)                                                                                                                               |
| ------------------ | ------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Who initiates?** | The end-user, during onboarding.                                    | The business, via a server-to-server API call.                                                                                                                |
| **Consent**        | User explicitly consents to share their data for each reuse.        | Consent is typically handled in the user's terms of service with the initial business. A clear data sharing agreement between partner businesses is required. |
| **Data Flow**      | User's Didit ID facilitates data sharing directly with the new app. | `Service X` shares data with `Service Y` via a secure token.                                                                                                  |
| **Use Case**       | A user wanting to quickly sign up for multiple, unrelated services. | Partner ecosystems, financial services groups, or conglomerates where a user's identity needs to be portable across related platforms.                        |

***

> ## ❗️ Important: Data Sharing Restrictions
>
> Sharing personal user data between different organizations is subject to strict legal and regulatory requirements. Before using this feature, your organization is responsible for ensuring you are fully compliant with all applicable data protection laws, such as GDPR in the European Union and UK GDPR in the United Kingdom.
>
> You must:
>
> 1. **Establish a Legal Basis**: Ensure you have a legitimate legal basis for sharing the data. This often requires a clear data sharing agreement between you and your partner organization.
> 2. **Ensure User Consent**: Confirm that your users have been properly informed and have consented to their data being shared with your partners, as outlined in your terms of service and privacy policy.
> 3. **Handle International Transfers Appropriately**: If data is being transferred across borders (e.g., from the EU to a non-EU country), you must ensure appropriate safeguards are in place as required by law.
>
> Didit provides the technical capability for data sharing, but your organization and your partners are solely responsible for all legal and compliance obligations related to the data you share. We strongly recommend consulting with your legal counsel before implementing this feature.


# Wallet Screening (KYT)
Source: https://docs.didit.me/core-technology/wallet-screening/overview

Screen wallets and transaction hashes for $0.15 per check. Review risk scores, source-of-funds exposure, and network relationships.

This chapter of the Didit Academy fraud rule engine lesson picks up at wallet risk and what the score bands mean.

The rule-engine Academy lesson reaches wallet risk at 3:00: what the score bands mean and how a wallet's exposure feeds the transaction risk score.

<VideoEmbed title="Wallet risk and what the score bands mean — Didit Academy" />

**Wallet Screening** checks blockchain risk for **\$0.15 per wallet or transaction-hash screening**. Screen wallets before a transfer, screen transaction hashes after the fact, and send the results to the [Transaction Monitoring rules engine](/transaction-monitoring/rules).

Wallet Screening is part of Didit's **Monitoring** lifecycle stage — checks that run continuously, post-onboarding, on every flow of funds in or out of your platform.

## How it works

1. **Connect a provider.** In **Transactions → Settings → Provider Preferences** in the [Business Console](https://business.didit.me), choose managed pricing or connect an existing provider API key. The default provider is Crystal.
2. **Submit a transaction with crypto details.** Set `transaction_details.currency_kind: "crypto"` and provide a wallet address in the participant matching the transfer direction. Didit screens the wallet (pre-transfer) or the transaction hash (post-transfer) automatically.
3. **Receive a standardised result.** Risk score 0-100, severity (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`), a source-of-funds breakdown, an exposure table, and a network graph. The result feeds the rules engine and triggers any matching webhooks.

## Risk signals

Every screening produces a standardised payload regardless of which provider sits behind it:

* **Risk score (0-100)** — higher means greater exposure to risky entities.
* **Severity** — `LOW`, `MEDIUM`, `HIGH`, `CRITICAL` derived from the score.
* **Source of funds** — percentage breakdown across 14+ categories (sanctioned, terrorist financing, child exploitation, ransomware, stolen funds, darknet markets, mixers, scams, high-risk exchanges, gambling, regulated exchanges, P2P, unidentified services).
* **Exposure table** — counterparty entities with direct vs. indirect hop distance, received and sent amounts, per-entity risk level.
* **Network graph** — node-edge view of the wallet's transaction relationships with centrality and depth metrics. Visualised in the [Business Console](/transaction-monitoring/console).
* **Sanctions, darknet, and mixer flags** — surfaced as discrete signals so rules can decline instantly.

## Providers

| Provider           | Status      | Managed pricing    | Connected-key pricing  |
| ------------------ | ----------- | ------------------ | ---------------------- |
| **Crystal**        | Available   | \$0.18 / screening | **\$0.02 / screening** |
| **Merkle Science** | Available   | \$0.15 / screening | **\$0.02 / screening** |
| **Chainalysis**    | Coming soon | —                  | \$0.02 / screening     |
| **Elliptic**       | Coming soon | —                  | \$0.02 / screening     |

<Tip>
  **Connecting your provider key** lets you use an existing commercial agreement with a blockchain analytics provider. Didit charges a \$0.02 infrastructure fee for each screening routed through a Didit workflow.
</Tip>

## Pricing

\*\*Wallet Screening starts at $0.15 per check with managed pricing.** If you connect an existing provider key, Didit charges a $0.02 infrastructure fee per screening. No minimums or contracts apply. See the [pricing page](https://didit.me/pricing) for volume pricing.

## Integration

The full API surface — request payloads, direction rules, pre-transfer vs. post-transfer screening, and the rule-engine integration — lives on the [Transaction Monitoring AML Screening page](/transaction-monitoring/aml-screening). Wallet Screening is enabled by setting `currency_kind: "crypto"` on the transaction and toggling the application-level default in the Console.

<CardGroup>
  <Card title="API: crypto screening" icon="code" href="/transaction-monitoring/aml-screening">
    Pre-transfer vs. post-transfer payloads, required fields, response shape.
  </Card>

  <Card title="Rules & scoring" icon="scale-balanced" href="/transaction-monitoring/rules">
    How wallet-screening results feed the real-time rule engine.
  </Card>

  <Card title="Cases & SAR workflow" icon="folder-open" href="/transaction-monitoring/cases">
    Triage high-risk wallet hits, draft SARs, keep an audit trail.
  </Card>

  <Card title="Travel Rule" icon="route" href="/transaction-monitoring/travel-rule">
    FATF Travel Rule support for VASPs and crypto exchanges.
  </Card>
</CardGroup>


# Business Blocklist
Source: https://docs.didit.me/entities/businesses/blocklist

Block Didit Business entities by vendor_data or country, with automatic and manual blocklisting. Pay-per-call KYB fraud and sanctions controls.

Blocklists prevent a business that has failed your compliance checks — or one located in a dangerous jurisdiction — from running new Business Verification (KYB) sessions or transacting on your platform.

## Supported identifier types for Businesses

| Type               | Key                     | Matches when…                                                   |
| ------------------ | ----------------------- | --------------------------------------------------------------- |
| Business           | `BUSINESS`              | A new session or transaction uses the blocklisted `vendor_data` |
| Country            | (configured separately) | Business country matches a dangerous-countries list             |
| IP                 | `IP_ADDRESS`            | The submitter's IP (or CIDR range) matches                      |
| Device fingerprint | `DEVICE_FINGERPRINT`    | Submitter device matches                                        |
| Wallet address     | `WALLET_ADDRESS`        | Crypto wallet tied to the business matches                      |
| Bank account       | `BANK_ACCOUNT`          | IBAN / bank account matches                                     |

<Note>
  Face and document blocklists operate at the **individual** (User) level, not the Business level. To block directors or UBOs, blocklist them as Users — their involvement with any business then flows through to the business's key-people review.
</Note>

## How blocklisting happens

<Steps>
  <Step title="Automatic — on a declined Business Verification (KYB) session">
    When a Business Verification (KYB) session finishes `DECLINED` and auto-blocklist is enabled for your workflow, Didit transitions the Business to `BLOCKED` and adds the `vendor_data` to the System Business Blocklist.
  </Step>

  <Step title="Automatic — on dangerous country">
    If the business country of incorporation appears in your configured dangerous countries list, the Business Verification (KYB) session is auto-declined at creation time with reason `blocked_country`.
  </Step>

  <Step title="Automatic — on sanctioned entity">
    A company AML hit above the decline threshold auto-declines the session and blocklists the business.
  </Step>

  <Step title="Manual — from the console">
    An analyst blocklists a business from *Businesses → \[business] → Actions → Add to blocklist*.
  </Step>

  <Step title="Programmatic — via the Lists API">
    Use the [Lists API](/management-api/lists/overview) to add entries directly to the Business blocklist.
  </Step>
</Steps>

## Dangerous countries

Each application ships with a default **dangerous countries** list (configurable from *Settings → Blocklist → Countries*). Examples of default-included ISO codes: `IRN`, `PRK`, `SYR`, `AFG`, `RUS`, `MMR` (subject to change — the default list follows FATF and OFAC guidance).

When a business is created with a matching `country_code`:

* The Business Verification (KYB) session is auto-declined with reason `blocked_country`.
* No session link is issued.
* The Business entity is created in `BLOCKED` status.

## Adding a business to the blocklist via API

Use the [Lists API](/management-api/lists/overview) to add a blocklist entry programmatically:

1. [List all lists](/management-api/lists/list) filtered by `entry_type=business` and `is_system=true` to find the system Business blocklist.
2. [Create an entry](/management-api/lists/create-entry) on that list with `value` set to the business's `vendor_data`, plus an optional `display_label` and `comment` for audit purposes.

## Enforcement at transaction time

Blocklisted businesses propagate into Transaction Monitoring automatically:

* Transactions with a **blocklisted applicant business** are auto-declined.
* Transactions with a **blocklisted counterparty business** are flagged or declined depending on your rule configuration.

Preset rules like "Sanctioned counterparty" fire on these matches.

## Removing a business from the blocklist

* **Console**: *Blocklist → Businesses → row actions → Remove*.
* **API**: use the [Delete entry](/management-api/lists/delete-entry) endpoint with the list UUID and entry UUID.

Removal does not automatically change the Business's `status`. Use `PATCH /v3/businesses/{vendor_data}/update-status/` to move the business back to `ACTIVE`.

## Audit trail

Every add/remove is logged to the [audit log](/console/audit-logs) with:

* Actor (user email or `'system'`, `'api'`).
* Timestamp.
* Optional comment.
* Reference session if auto-generated.

## Next steps

<CardGroup>
  <Card title="Lists API" icon="list" href="/management-api/lists/overview">
    Full blocklist API reference.
  </Card>

  <Card title="Console blocklist" icon="ban" href="/console/blocklist-users">
    Manage blocklists from the UI.
  </Card>

  <Card title="Operations" icon="gear" href="/entities/businesses/operations">
    Change business status.
  </Card>
</CardGroup>


# Businesses in the Console
Source: https://docs.didit.me/entities/businesses/console

Walkthrough of the Businesses section in the Didit Business Console — list view, detail tabs, bulk actions, and every analyst operation on KYB entities.

The **Businesses** section in the Business Console is where your compliance team manages legal-entity profiles — reviewing KYB history, managing statuses, handling document requests, and running bulk operations.

## Navigating to Businesses

*Console → \[your team] → \[your application] → Businesses*

Route: `/console/[team]/[app]/businesses`.

## List view

Infinite-scroll table with column customization, filters, and bulk actions.

### Columns

Default: `Business ID`, `Legal name`, `Country`, `Status`, `Registration`, `Created`, `Last activity`, `Sessions`, `Risk`.

### Filters

| Filter     | Values                                                                   |
| ---------- | ------------------------------------------------------------------------ |
| Status     | `ACTIVE`, `FLAGGED`, `BLOCKED`                                           |
| Country    | ISO country codes                                                        |
| Time range | Created or last activity window                                          |
| Search     | Matches `vendor_data`, `display_name`, `legal_name`, registration number |
| Tags       | Assigned tag chips                                                       |
| KYB state  | Features present / missing                                               |

### Bulk actions

* **Change status** — bulk move across ACTIVE / FLAGGED / BLOCKED.
* **Add to blocklist** — push to the Business blocklist.
* **Export** — export the selected subset to CSV.
* **Delete** — delete.

## Detail view

Click any business row to open the detail panel. Tabs:

### Overview

* **Header**: `display_name`, `legal_name`, `registration_number`, `country_code`, `status`, primary actions.
* **Company block**: registered address, incorporation date, company type, legal entity identifier.
* **Risk indicators**: AML score, active hits, complexity indicator.
* **Feature matrix**: `kyb_registry`, `kyb_company_aml`, `kyb_documents`, `kyb_key_people` with their latest statuses.
* **Metadata**: custom fields, tags, notes.

### KYB Sessions

* Every Business Verification (KYB) session tied to this business, newest first.
* Row click opens the [session review](/console/manual-review) surface with registry data, officers, UBOs, AML hits, and documents.

### Key People

* Directors, officers, UBOs, beneficial owners extracted during KYB.
* Each row shows name, role, ownership %, source (registry vs user-added), KYC status (if linked to a User), AML status.
* Click a person to see their detail (and, if linked, their User entity).

### Documents

* All documents from Business Verification (KYB) sessions — certificate of incorporation, AoA, POA, shareholder registers, custom.
* Upload document button (analyst-only) to attach additional documents.

### Transactions

* Every transaction where the business is applicant, remitter, beneficiary, or counterparty.
* Filter by direction, status, amount, date, counterparty.
* Open any transaction to see its rule runs, IP enrichment, crypto screening results, and network graph.
* Launch a case from any transaction for deeper investigation.

### Activity

* Chronological log: session events, status changes, transaction events, notes, blocklist additions.

### Chat

* Internal notes for your team with @-mentions.

## Actions available on a business

| Action            | Where                                 | What it does                                             |
| ----------------- | ------------------------------------- | -------------------------------------------------------- |
| Edit profile      | Overview → Edit                       | Update `display_name`, metadata, tags                    |
| Change status     | Overview → Actions → Change status    | Move between ACTIVE / FLAGGED / BLOCKED                  |
| Upload document   | Documents tab                         | Manually attach a document to the business               |
| Manage tags       | Overview → Manage tags                | Add/remove tag chips                                     |
| Add to blocklist  | Overview → Actions → Add to blocklist | Push the business to the blocklist                       |
| Open case         | Overview → Actions → Open case        | Start a compliance case                                  |
| Request more info | KYB Sessions tab → row → Request info | Send a documentation request email to the business admin |
| Delete            | Overview → Actions → Delete           | Delete with confirmation                                 |

## Creating a business from the console

1. *Businesses → Create business*.
2. Enter `vendor_data` (required), `display_name`, `country_code`, metadata.
3. Set initial status.
4. Save. The business appears in the list.

## Role-based visibility

Same matrix as Users — see [Roles & permissions](/console/roles-permissions).

## Related console pages

* [Workflows](/console/workflows) — configure KYB workflows.
* [Verification links](/console/verification-links) — share a KYB link for a specific business.
* [Manual review](/console/manual-review) — review a Business Verification (KYB) session.
* [Blocklist](/console/blocklist-users) — manage application blocklists.
* [Analytics](/console/analytics) — KYB volume and outcome trends.

## Next steps

<CardGroup>
  <Card title="Operations API" icon="code" href="/entities/businesses/operations">
    Programmatic CRUD.
  </Card>

  <Card title="KYB history" icon="clock-rotate-left" href="/entities/businesses/kyb-history">
    Retrieve every Business Verification (KYB) session for a business.
  </Card>

  <Card title="Key people" icon="users" href="/entities/businesses/key-people">
    Officer, UBO, director linking.
  </Card>
</CardGroup>


# Business Data Model
Source: https://docs.didit.me/entities/businesses/data-model

The Didit Business entity model — registry data, UBOs, officers, AML, documents, transactions, KYB session aggregates. From $2.00 per check, priced per country and tier.

This page documents every field on a Business entity and how Didit populates each one.

## Identity fields

| Field                 | Type                        | Description                                                                                                                   |
| --------------------- | --------------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                | UUID                        | Didit-assigned primary key. Stable and unique.                                                                                |
| `didit_internal_id`   | string                      | Human-readable internal identifier.                                                                                           |
| `vendor_data`         | string                      | Your identifier for the business. Unique per application. [Read more](/entities/vendor-data-linking).                         |
| `display_name`        | string                      | Override name shown in the console. Defaults to `legal_name` or `vendor_data`.                                                |
| `legal_name`          | string                      | Legal company name as registered — propagated from the latest approved Business Verification (KYB) session's registry lookup. |
| `registration_number` | string                      | Official company registration number — propagated from registry.                                                              |
| `country_code`        | string (ISO 3166-1 alpha-3) | Country of incorporation.                                                                                                     |

<Note>
  `legal_name`, `registration_number`, and `country_code` are read-only when derived from a verified registry lookup. They can be manually overridden in the console or via `PATCH /v3/businesses/{vendor_data}/`, but overrides are flagged in the audit log.
</Note>

## Status

| Field    | Type | Values                         | Description                                                                                      |
| -------- | ---- | ------------------------------ | ------------------------------------------------------------------------------------------------ |
| `status` | enum | `ACTIVE`, `FLAGGED`, `BLOCKED` | Controls enforcement for future sessions and transactions. See [lifecycle](/entities/lifecycle). |

## Session aggregate fields

| Field             | Type   | Description                                                               |
| ----------------- | ------ | ------------------------------------------------------------------------- |
| `session_count`   | int    | Total Business Verification (KYB) sessions ever created for this business |
| `approved_count`  | int    | Sessions finished with `APPROVED`                                         |
| `declined_count`  | int    | Sessions finished with `DECLINED`                                         |
| `in_review_count` | int    | Sessions currently `IN_REVIEW`                                            |
| `features`        | object | Latest status of each KYB feature across sessions                         |

### The `features` map

```json theme={null}
{
  "kyb_registry": "APPROVED",
  "kyb_company_aml": "APPROVED",
  "kyb_documents": "APPROVED",
  "kyb_key_people": "IN_REVIEW"
}
```

Feature values: `NOT_FINISHED`, `APPROVED`, `DECLINED`, `IN_REVIEW`, `RESUB_REQUESTED`.

Use the `features` map as the fast path to check whether a business is fully verified right now without iterating all sessions.

## Activity timestamps

| Field              | Type          | Updated when                                              |
| ------------------ | ------------- | --------------------------------------------------------- |
| `first_session_at` | ISO timestamp | First Business Verification (KYB) session was created     |
| `last_session_at`  | ISO timestamp | Most recent session was created or updated                |
| `last_activity_at` | ISO timestamp | Any change — session, transaction, status, profile, notes |
| `created_at`       | ISO timestamp | Entity row was created                                    |
| `updated_at`       | ISO timestamp | Entity row was last updated                               |

## Metadata

| Field      | Type          | Description                |
| ---------- | ------------- | -------------------------- |
| `metadata` | object (JSON) | Free-form JSON you control |
| `tags[]`   | array         | Console/API-managed tags   |

## Relations (not stored on the business row)

| Relation                                    | How to access                                                                                                             |
| ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------- |
| Business Verification (KYB) sessions        | `GET /v3/sessions?vendor_data=<value>`                                                                                    |
| Linked users (officers, UBOs, directors)    | Surfaced on the business detail page in the console; derived from the latest approved Business Verification (KYB) session |
| Transactions (as applicant or counterparty) | Filter transactions by business `vendor_data`                                                                             |
| Documents                                   | Via Business Verification (KYB) session decisions                                                                         |
| AML hits                                    | Via Business Verification (KYB) session decisions                                                                         |

## Example response

```json theme={null}
{
  "uuid": "f7a9c1b2-4e6d-4f8a-9c5d-2a1b3c4d5e6f",
  "didit_internal_id": "B-2026-00018",
  "vendor_data": "biz-acme",
  "display_name": "Acme Corp",
  "legal_name": "Acme Corporation Limited",
  "registration_number": "12345678",
  "country_code": "GBR",
  "status": "ACTIVE",
  "session_count": 2,
  "approved_count": 1,
  "declined_count": 0,
  "in_review_count": 1,
  "features": {
    "kyb_registry": "APPROVED",
    "kyb_company_aml": "APPROVED",
    "kyb_documents": "APPROVED",
    "kyb_key_people": "IN_REVIEW"
  },
  "first_session_at": "2025-09-01T12:00:00Z",
  "last_session_at": "2026-04-01T09:00:00Z",
  "last_activity_at": "2026-04-16T10:00:00Z",
  "metadata": { "partner": "Acme Holdings" }
}
```

## Next steps

<CardGroup>
  <Card title="Operations" icon="gear" href="/entities/businesses/operations">
    Create, update, change status, delete.
  </Card>

  <Card title="KYB history" icon="clock-rotate-left" href="/entities/businesses/kyb-history">
    Retrieve every session tied to the business.
  </Card>

  <Card title="API reference" icon="code" href="/management-api/businesses/get">
    GET /v3/businesses// schema.
  </Card>
</CardGroup>


# Import and Export Businesses
Source: https://docs.didit.me/entities/businesses/import-export

Bulk-load Didit Business (KYB) entities from CSV and export the full business table. Available from the Didit Business Console. Pay-per-call billing.

<AgentPromptAccordion title="Bulk Import / Export Businesses Prompt" />

The Business Console supports bulk import and export of Business entities — the same flow available for Users, adapted for business fields.

<Note>
  Bulk import/export here creates or updates Business profiles only. It does not recreate historical KYB sessions, registry reports, officers, beneficial owners, or provider decisions. For a full KYB migration from another provider or registry export, see [Import Data from Another Provider](/sessions-api/import-verifications).
</Note>

## Import businesses from CSV

### When to use it

* **Migration** from another KYB vendor.
* **Partner onboarding** — load a partner's customer list.
* **Metadata backfill** — update tags, tier, or custom fields across many businesses.

### Template columns

Download the template from *Businesses → Import → Download template*:

| Column                | Required | Description                                                          |
| --------------------- | -------- | -------------------------------------------------------------------- |
| `vendor_data`         | Yes      | Your identifier for the business. Unique per application.            |
| `display_name`        | No       | Human-readable name.                                                 |
| `legal_name`          | No       | Legal company name. Will be overwritten by verified registry data.   |
| `registration_number` | No       | Company registration. Will be overwritten by verified registry data. |
| `country_code`        | No       | ISO 3166-1 alpha-3. Triggers dangerous-countries check.              |
| `status`              | No       | `ACTIVE`, `FLAGGED`, or `BLOCKED`. Defaults to `ACTIVE`.             |
| `tags`                | No       | Comma-separated tags.                                                |
| `metadata_json`       | No       | Stringified JSON for custom metadata.                                |

### Running the import

<Steps>
  <Step title="Upload the CSV">
    *Businesses → Import → Upload CSV*.
  </Step>

  <Step title="Review the preview">
    Invalid rows are highlighted. Duplicates (existing `vendor_data`) are flagged as updates.
  </Step>

  <Step title="Start the import">
    Didit processes rows asynchronously; progress is tracked in *Businesses → Import history*.
  </Step>

  <Step title="Review results">
    Download an error report for any skipped rows.
  </Step>
</Steps>

### Update vs create

* New `vendor_data` → creates a new Business.
* Existing `vendor_data` → updates the Business's mutable fields and metadata.
* Registry-derived fields (`legal_name`, `registration_number`, `country_code`) are **not** overwritten by imports after a Business Verification (KYB) session has populated them.

## Export businesses to CSV

### When to use it

* **Compliance audits** and regulator requests.
* **Data warehouse sync** for BI.
* **Partner reporting** — filtered views of businesses by country, tier, or tag.

### Running an export

1. Navigate to *Businesses → Export*.
2. Apply filters (status, country, date range, search, tags).
3. Choose columns.
4. Submit — Didit generates the export asynchronously and emails a signed download link.

Role restrictions apply — see [roles & permissions](/console/roles-permissions).

## Audit trail

All imports and exports are logged with operator, row counts, and timestamps. See [audit logs](/console/audit-logs).

## Next steps

<CardGroup>
  <Card title="Create business API" icon="plus" href="/management-api/businesses/create">
    Programmatic bulk creation.
  </Card>

  <Card title="Data retention" icon="shield-halved" href="/console/data-retention">
    How long imported data persists.
  </Card>

  <Card title="Audit logs" icon="file-lines" href="/console/audit-logs">
    Review import/export history.
  </Card>
</CardGroup>


# Key People (UBOs, Officers, Directors)
Source: https://docs.didit.me/entities/businesses/key-people

Officers, directors, UBOs, and beneficial owners on a Didit Business entity — each one verifiable through KYC as a User entity. From $2.00 per check, priced per country and tier.

Every Business entity has **key people** — the natural persons legally responsible for or beneficially owning the company. Didit identifies them during KYB and lets you link each one to a User entity for individual KYC.

## Who counts as a key person

| Role                                | Description                                                                    |
| ----------------------------------- | ------------------------------------------------------------------------------ |
| **Director**                        | Named in registry as a company director                                        |
| **Officer**                         | Secretary, representative, or other registered officer                         |
| **Shareholder**                     | Registered shareholder (corporate or individual)                               |
| **UBO (Ultimate Beneficial Owner)** | Individual who ultimately owns or controls 10/25/50%+ (threshold configurable) |
| **Authorized signatory**            | Person empowered to act on behalf of the company                               |

See the [KYB Officers](/business-verification/officers) and [Ownership](/business-verification/ownership) pages for the full role taxonomy and ownership-chain computation.

## How key people attach to a Business

<Steps>
  <Step title="Identified from the registry">
    During KYB, Didit queries the company registry and extracts all listed officers and shareholders. Each person becomes a **key-people record** linked to the Business Verification (KYB) session.
  </Step>

  <Step title="User-added (customer-filled)">
    Workflows can include a "Key People" step where the business admin adds people not present in the registry (e.g. UBOs identified by corporate declaration).
  </Step>

  <Step title="Aggregated on the Business entity">
    The Business's key-people list is the union of registry-extracted and user-added parties, de-duplicated by identity.
  </Step>
</Steps>

Each key person has a `source` field:

* `REGISTRY` — extracted from an official registry.
* `USER` — added by the business admin during the KYB flow.

## Linking a key person to a User entity

When KYC is required for a key person (typically UBOs and directors), the party can be linked to a User entity:

```mermaid theme={null}
flowchart LR
    B[Business: biz-acme]
    P1[Key Person: Jane Doe, Director]
    P2[Key Person: John Smith, UBO 40%]
    U1[User: user-jane]
    U2[User: user-john]
    P1 --> B
    P2 --> B
    P1 -.linked.-> U1
    P2 -.linked.-> U2
```

The link is created when:

* A User Verification (KYC) session runs for the party using the same `vendor_data` as the User entity.
* An analyst manually associates a business party with an existing User.

Once linked, the User's KYC status propagates to the key people view on the Business.

## Inspecting key people

From the Business detail page in the console, the **Key People** tab shows:

* Every party's name, role, ownership %, source (registry vs user-added)
* KYC status of linked Users
* AML screening status per person
* Associated documents (director ID, UBO declaration)

Programmatically, key people surface inside the `key_people_checks[]` array of the Business Verification (KYB) session decision, split into two buckets:

```json theme={null}
"key_people_checks": [
  {
    "status": "Approved",
    "node_id": "feature_kyb_key_people",
    "registry": {
      "officers": [
        { "uuid": "...", "name": "Jane Doe", "role": "director", "kyc_status": "Approved", "kyc_session_url": "..." }
      ],
      "beneficial_owners": [
        { "uuid": "...", "name": "John Smith", "roles": ["ubo"], "ownership_min_shares": 40, "kyc_status": "Pending" }
      ]
    },
    "submitted": {
      "parties": [
        { "uuid": "...", "entity_type": "person", "name": "Alice Chen", "role": "ubo", "ownership_percent": 35.0, "source": "USER", "requires_verification": true, "kyc_session_status": "Not Started", "kyc_session_url": "..." }
      ]
    },
    "ubo_kyc_summary": { "total": 2, "approved": 1, "flagged": 0, "pending": 1 }
  }
]
```

* **`registry.officers` / `registry.beneficial_owners`** — parties discovered via the registry check.
* **`submitted.parties`** — parties the business admin added during the Key People flow (`source: USER`).
* **`ubo_kyc_summary`** — aggregate UBO KYC progress.

Legacy flat `officers[]` and `beneficial_owners[]` arrays remain on the response for backward compatibility one more release. New integrations should consume the two-bucket shape above. See the full [KYB response schema](/business-verification/response-schema#key_people_checks) for every field.

## Corporate shareholders

When a shareholder is itself a company (not a person), Didit recursively explores the ownership chain to identify the ultimate beneficial owners. Corporate parties can optionally trigger child Business Verification (KYB) sessions.

See [Ownership structure](/business-verification/ownership) for a worked example of multi-layer ownership chains.

## Key people webhooks

Changes to key people surface through the parent session events:

* `data.updated` (with `session_kind: "business"`) — session data including key people was updated.
* `status.updated` (with `session_kind: "business"`) — the session status changed as a result.

See [KYB webhooks](/business-verification/webhooks) for payloads.

## Next steps

<CardGroup>
  <Card title="Officers" icon="user-tie" href="/business-verification/officers">
    Director identification and role taxonomy.
  </Card>

  <Card title="Ownership" icon="sitemap" href="/business-verification/ownership">
    UBO, corporate shareholders, and chain computation.
  </Card>

  <Card title="Key People flow" icon="users" href="/business-verification/key-people">
    The KYB step that collects key people.
  </Card>
</CardGroup>


# Business KYB History
Source: https://docs.didit.me/entities/businesses/kyb-history

Retrieve every KYB session tied to a Didit Business entity, inspect registry data and AML hits, trigger re-verification, and generate compliance reports.

<AgentPromptAccordion title="KYB History Prompt" />

Every Business Verification (KYB) session a Business has run stays permanently linked to the Business entity. You can retrieve the full history, inspect each session's registry data and AML hits, trigger re-verification, and generate PDF reports for audits.

## Listing all Business Verification (KYB) sessions for a business

Filter the Sessions list by `vendor_data`:

```bash theme={null}
curl -G https://verification.didit.me/v3/sessions/ \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "vendor_data=biz-acme" \
  --data-urlencode "page_size=50"
```

Response includes every Business Verification (KYB) session (regardless of status).

## Understanding KYB features

Business entities track features independently:

| Feature           | What it covers                                                      |
| ----------------- | ------------------------------------------------------------------- |
| `kyb_registry`    | Company registry lookup — existence, status, identity cross-check   |
| `kyb_company_aml` | Company-level AML screening (sanctions, adverse media, watchlists)  |
| `kyb_documents`   | Document collection and OCR cross-referencing                       |
| `kyb_key_people`  | Officers, UBOs, beneficial owners — identification and optional KYC |

The `features` map on the business entity reflects the latest status of each:

```json theme={null}
"features": {
  "kyb_registry": "APPROVED",
  "kyb_company_aml": "APPROVED",
  "kyb_documents": "APPROVED",
  "kyb_key_people": "IN_REVIEW"
}
```

See [KYB feature statuses](/business-verification/statuses) for the full reference.

## Inspecting a single Business Verification (KYB) session

```bash theme={null}
curl https://verification.didit.me/v3/session/{session_id}/decision/ \
  -H "x-api-key: YOUR_API_KEY"
```

The KYB decision includes:

* Company registry data (legal name, registration, status, incorporation date, addresses)
* Officers and UBOs extracted from the registry
* Ownership structure (cap table, beneficial ownership percentages)
* Company AML results (hits, scores)
* Per-person AML for each UBO and officer
* Document results with OCR extracts
* Decision reason codes

See [KYB response schema](/business-verification/response-schema) for the full payload.

## Triggering re-verification

Annual re-KYB, trigger-based re-checks, or remediation flows all start with a new session:

```bash theme={null}
curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wf_kyb_annual",
    "vendor_data": "biz-acme"
  }'
```

The new session attaches to the existing Business entity and updates the `features` map on completion.

## Resubmission vs new Business Verification (KYB) session

| Scenario                                        | Use                                                |
| ----------------------------------------------- | -------------------------------------------------- |
| Registry lookup needs a corrected company name  | Resubmit — analyst edits data and re-runs registry |
| Additional document requested from the business | Resubmit — business uploads the missing document   |
| Annual or trigger-based re-KYB                  | Create a new session                               |

## Exporting a KYB report

Generate a comprehensive PDF for any Business Verification (KYB) session:

```bash theme={null}
curl https://verification.didit.me/v3/session/{session_id}/generate-pdf/ \
  -H "x-api-key: YOUR_API_KEY" \
  -o kyb-report.pdf
```

The PDF includes registry data, ownership structure, AML hits, document images, officer KYC status, and a cover page with decision reason.

## Sharing a Business Verification (KYB) session

For consortium or partner workflows:

* `POST /v3/session/{session_id}/share/` — generate a shareable token.
* `POST /v3/session/import-shared/` — import on the receiving side.

## Ongoing monitoring

Business entities in ongoing monitoring mode get periodic AML rescans. When a new sanctions or adverse media hit is detected, the business's `kyb_company_aml` feature is updated and a `business.data.updated` webhook fires.

Configure ongoing monitoring in the console at *Workflows → \[KYB workflow] → AML → Ongoing monitoring*.

## Next steps

<CardGroup>
  <Card title="KYB overview" icon="building" href="/business-verification/overview">
    How Business Verification (KYB) sessions work end-to-end.
  </Card>

  <Card title="KYB response" icon="file-lines" href="/business-verification/response-schema">
    Full decision payload reference.
  </Card>

  <Card title="Key people" icon="users" href="/entities/businesses/key-people">
    Officers, UBOs, and linked Users.
  </Card>
</CardGroup>


# Business Operations
Source: https://docs.didit.me/entities/businesses/operations

Create, read, update, change status, and delete Didit Business (KYB) entities via the Management API. From $2.00 per check, priced per country and tier, no contracts.

<AgentPromptAccordion title="Business Operations Prompt" />

All Business entity management happens through six public endpoints under `/v3/businesses/`. This page gives you the conceptual walkthrough — see the [API reference](/management-api/businesses/list) for full request / response schemas.

## List businesses

**`GET /v3/businesses/`**

Paginated list of businesses for your application with filters on status, search, country, and date range.

```bash theme={null}
curl -G https://verification.didit.me/v3/businesses/ \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "status=ACTIVE" \
  --data-urlencode "country_code=GBR" \
  --data-urlencode "page_size=50"
```

## Get a business

**`GET /v3/businesses/{vendor_data}/`**

Retrieve a single business by `vendor_data`.

```bash theme={null}
curl https://verification.didit.me/v3/businesses/biz-acme/ \
  -H "x-api-key: YOUR_API_KEY"
```

## Create a business

**`POST /v3/businesses/create/`**

Pre-create a Business before any Business Verification (KYB) session runs:

```bash theme={null}
curl -X POST https://verification.didit.me/v3/businesses/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "biz-acme",
    "display_name": "Acme Corp",
    "country_code": "GBR",
    "metadata": { "partner": "Acme Holdings" }
  }'
```

Returns a conflict error if a business with that `vendor_data` already exists. Use `PATCH` to update an existing business.

## Update a business

**`PATCH /v3/businesses/{vendor_data}/`**

Update mutable profile fields. Fields derived from registry lookups (`legal_name`, `registration_number`, `country_code`) are read-only after verification but can be overridden — overrides are flagged in the audit log.

**Mutable fields:** `display_name`, `metadata`, `tags`.
**Read-only after verification:** all registry-derived fields, aggregate counters, `features` map.

```bash theme={null}
curl -X PATCH https://verification.didit.me/v3/businesses/biz-acme/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "tier": "enterprise" } }'
```

Emits `business.data.updated`.

## Change status

**`PATCH /v3/businesses/{vendor_data}/update-status/`**

Move a business between `ACTIVE`, `FLAGGED`, and `BLOCKED`.

```bash theme={null}
curl -X PATCH https://verification.didit.me/v3/businesses/biz-acme/update-status/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "BLOCKED",
    "reason": "Sanctioned subsidiary detected in ownership chain"
  }'
```

| From → to            | Common trigger                                                                              |
| -------------------- | ------------------------------------------------------------------------------------------- |
| `ACTIVE` → `FLAGGED` | Business Verification (KYB) session moved to `IN_REVIEW`, ongoing AML hit, transaction rule |
| `ACTIVE` → `BLOCKED` | Business Verification (KYB) session `DECLINED` with auto-block, confirmed sanctioned entity |
| `FLAGGED` → `ACTIVE` | Analyst cleared review                                                                      |
| `BLOCKED` → `ACTIVE` | Manual unblock after remediation                                                            |

Emits `business.status.updated`.

## Delete businesses (batch)

**`POST /v3/businesses/delete/`**

Delete one or more businesses. The business records are removed permanently. Their verification sessions are not covered by this endpoint and survive with their link to the business cleared; delete them with [Delete Session](/sessions-api/delete-session). Transactions are not covered either; delete those from the Console.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/businesses/delete/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "vendor_data": ["biz-acme", "biz-alpha", "biz-beta"] }'
```

Idempotent — deleting an already-deleted business is a no-op.

## Permission model

All `/v3/businesses/*` endpoints are scoped by the `businesses` permission resource:

| Role                | list | get | create | update | update-status | delete |
| ------------------- | :--: | :-: | :----: | :----: | :-----------: | :----: |
| OWNER               |   ✅  |  ✅  |    ✅   |    ✅   |       ✅       |    ✅   |
| ADMIN               |   ✅  |  ✅  |    ✅   |    ✅   |       ✅       |    ✅   |
| COMPLIANCE\_OFFICER |   ✅  |  ✅  |    ❌   |    ✅   |       ✅       |    ❌   |
| DEVELOPER           |   ✅  |  ✅  |    ✅   |    ❌   |       ❌       |    ❌   |
| READER              |   ✅  |  ✅  |    ❌   |    ❌   |       ❌       |    ❌   |

See [Roles & permissions](/console/roles-permissions).

## Webhooks fired by these operations

| Operation       | Webhook                                       |
| --------------- | --------------------------------------------- |
| `create`        | `business.data.updated`                       |
| `update`        | `business.data.updated` with `changed_fields` |
| `update-status` | `business.status.updated`                     |
| `delete`        | `business.data.updated` with `deleted_at` set |

## Next steps

<CardGroup>
  <Card title="Data model" icon="database" href="/entities/businesses/data-model">
    Full field reference.
  </Card>

  <Card title="List API" icon="list" href="/management-api/businesses/list">
    GET /v3/businesses/ schema.
  </Card>

  <Card title="Create API" icon="plus" href="/management-api/businesses/create">
    POST /v3/businesses/create/ schema.
  </Card>
</CardGroup>


# Businesses (Vendor Entities)
Source: https://docs.didit.me/entities/businesses/overview

Vendor Businesses are Didit's persistent KYB record — registry data, UBOs, officers, AML status, documents, transactions on one profile. From $2.00 per check, priced per country and tier.

A **Business entity** represents a legal entity (company, LLC, fund, foundation, sole proprietorship, trust) across every KYB verification, transaction, and compliance interaction it has with your platform on Didit.

Like User entities, Business entities are keyed by `vendor_data` and aggregate all linked sessions and transactions into a single profile.

## What lives on a Business

| Category               | Fields / objects                                                                                                           |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------- |
| **Identity**           | `vendor_data`, `uuid`, `display_name`, `legal_name`, `registration_number`, `country_code`                                 |
| **Status**             | `ACTIVE`, `FLAGGED`, `BLOCKED`                                                                                             |
| **Session aggregates** | `session_count`, `approved_count`, `declined_count`, `in_review_count`, `features` map                                     |
| **Activity**           | `first_session_at`, `last_session_at`, `last_activity_at`                                                                  |
| **Key people**         | Linked officers, directors, UBOs, beneficial owners (each may link to a User entity for KYC)                               |
| **Documents**          | Certificates of incorporation, articles of association, shareholder registers, POA, financial statements, custom documents |
| **AML**                | Company-level sanctions / PEP / adverse media screening results                                                            |
| **Metadata**           | Arbitrary JSON for your own data                                                                                           |

See the full [Business data model](/entities/businesses/data-model) for field types and edge cases.

## When a Business is created

<Steps>
  <Step title="Automatically — from a Business Verification (KYB) session">
    When you create a Business Verification (KYB) session with a `vendor_data` Didit has never seen, a Business entity is created in `ACTIVE` status and linked to that session.
  </Step>

  <Step title="Explicitly — via POST /v3/businesses/create/">
    Pre-create the Business before running any Business Verification (KYB) session. Useful for seeding metadata or bulk-onboarding companies.
  </Step>

  <Step title="From the console">
    Your team creates the Business from the Businesses page — for example, when manually onboarding a company verified through an offline process.
  </Step>
</Steps>

## What you can do

| Operation                                                      | How                                                 |
| -------------------------------------------------------------- | --------------------------------------------------- |
| [List businesses](/entities/businesses/operations#list)        | `GET /v3/businesses/` with filters                  |
| [Get business](/entities/businesses/operations#get)            | `GET /v3/businesses/{vendor_data}/`                 |
| [Create business](/entities/businesses/operations#create)      | `POST /v3/businesses/create/`                       |
| [Update profile](/entities/businesses/operations#update)       | `PATCH /v3/businesses/{vendor_data}/`               |
| [Change status](/entities/businesses/operations#change-status) | `PATCH /v3/businesses/{vendor_data}/update-status/` |
| [Delete businesses](/entities/businesses/operations#delete)    | `POST /v3/businesses/delete/` (batch)               |
| [Review KYB history](/entities/businesses/kyb-history)         | `GET /v3/sessions?vendor_data=...`                  |
| [Review transactions](/entities/businesses/transactions)       | `GET /v3/transactions/?vendor_data=...`             |
| [Inspect key people](/entities/businesses/key-people)          | Via Business Verification (KYB) session decisions   |
| [Add to blocklist](/entities/businesses/blocklist)             | Console + Lists API                                 |
| [Import / export](/entities/businesses/import-export)          | Console only (CSV)                                  |
| [Manage in console](/entities/businesses/console)              | Full UI walkthrough                                 |

## Business ↔ User relationships

A Business entity is rarely standalone. During [KYB](/business-verification/overview), Didit identifies every officer, director, UBO, and beneficial owner. Each of those people can be linked to a User entity for individual KYC:

```mermaid theme={null}
flowchart LR
    B[Business: biz-acme]
    U1[User: jane-doe<br/>Director]
    U2[User: john-smith<br/>UBO 40%]
    U3[User: alice-chen<br/>UBO 35%]
    U1 --> B
    U2 --> B
    U3 --> B
```

When one of the linked Users has a failed KYC or AML hit, it propagates to the Business's risk profile. See [Key people](/entities/businesses/key-people) for the linkage pattern.

## Business vs business session

A **business session** is one KYB verification event. A **Business entity** is the durable profile that aggregates all sessions.

A single Business can have many Business Verification (KYB) sessions — initial verification, resubmissions, periodic re-KYB. The Business's `features` map reflects the latest state across all sessions.

## Next steps

<CardGroup>
  <Card title="Data model" icon="database" href="/entities/businesses/data-model">
    Every field, type, and index.
  </Card>

  <Card title="Operations" icon="gear" href="/entities/businesses/operations">
    Create, update, change status, delete.
  </Card>

  <Card title="KYB history" icon="clock-rotate-left" href="/entities/businesses/kyb-history">
    Every Business Verification (KYB) session tied to the business.
  </Card>

  <Card title="Key people" icon="users" href="/entities/businesses/key-people">
    Officers, UBOs, and director linking.
  </Card>

  <Card title="Blocklist" icon="ban" href="/entities/businesses/blocklist">
    Blocking businesses from transactions.
  </Card>

  <Card title="Console" icon="desktop" href="/entities/businesses/console">
    Full Businesses UI walkthrough.
  </Card>
</CardGroup>


# Business Transactions
Source: https://docs.didit.me/entities/businesses/transactions

Retrieve a Didit Business entity's transaction history and see how ongoing activity feeds Transaction Monitoring velocity, behavioral, and screening rules.

Every transaction you submit with a `vendor_data` identifier that matches a Business entity — as applicant, remitter, beneficiary, or counterparty — is linked to that Business profile. The Business becomes a running ledger of its activity, and Transaction Monitoring uses this history to feed velocity, behavioral, and screening rules at the business level.

## Retrieving a business's transactions

Filter the Transactions list by the business's `vendor_data`:

```bash theme={null}
curl -G https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "vendor_data=biz-acme" \
  --data-urlencode "page_size=50"
```

Returns every transaction where the business appears as the applicant. For counterparty-side history, filter in the Business Console (the public list endpoint filters by applicant only).

## How transactions link to businesses

```mermaid theme={null}
flowchart LR
    T["Transaction<br/>txn_id=tx-0042"]
    A["applicant:<br/>vendor_data=biz-acme"]
    C["counterparty:<br/>vendor_data=biz-widgets"]
    B1[Business: biz-acme]
    B2[Business: biz-widgets]
    T --> A
    T --> C
    A -.-> B1
    C -.-> B2
```

Each transaction includes up to four parties (`applicant`, `remitter`, `beneficiary`, `counterparty`). When a party includes `vendor_data` that matches a Business entity in your application, Didit binds the party to that Business. Parties without `vendor_data` are stored as external snapshots (no entity link).

See [submitting transactions](/transaction-monitoring/transactions) for the full party model.

## Mixed party kinds

A single transaction can mix Users and Businesses across parties — for example, an individual user paying a business:

```json theme={null}
{
  "txn_id": "tx-0099",
  "direction": "OUTBOUND",
  "amount": "500.00",
  "currency": "EUR",
  "applicant": { "vendor_data": "user-42" },
  "counterparty": { "vendor_data": "biz-acme" }
}
```

Or a B2B transfer between two businesses:

```json theme={null}
{
  "txn_id": "tx-0100",
  "direction": "OUTBOUND",
  "amount": "120000.00",
  "currency": "USD",
  "applicant": { "vendor_data": "biz-acme" },
  "counterparty": { "vendor_data": "biz-widgets" }
}
```

Didit resolves each party independently based on `vendor_data` — the same transaction flows into the profiles of every matched entity.

## Aggregated risk signals

Transactions feed these business-level signals:

| Signal                                 | Used by                      |
| -------------------------------------- | ---------------------------- |
| Total volume inbound / outbound        | Velocity rules, thresholding |
| Transaction count in a time window     | Velocity rules               |
| Unique counterparties                  | Behavioral rules             |
| High-risk jurisdictions touched        | Geography rules              |
| Sanctioned / PEP counterparty exposure | Screening rules              |
| Payment method variety                 | Fraud rules                  |

These signals are computed in real time and evaluated against your active [transaction rules](/transaction-monitoring/rules). When a rule matches, the Business can be moved to `FLAGGED` or `BLOCKED` automatically depending on the rule's action.

## How rules act on businesses

A transaction rule's `actions` can include:

* `add_score` — increases the transaction's risk score.
* `change_status` — sets the transaction's status (`IN_REVIEW`, `DECLINED`, `AWAITING_USER`).
* `add_tags` — tag the transaction.
* `add_to_list` — add the business's `vendor_data` to a blocklist or custom list.

When a rule adds the business to a blocklist, the Business entity is transitioned to `BLOCKED` and a `business.status.updated` webhook fires.

## Monitoring a business's behavior

Use the Transactions tab on the Business detail page in the Business Console to:

* See every transaction in chronological order.
* Filter by status, amount, direction, counterparty.
* Open any transaction to inspect rule runs, IP enrichment, and crypto screening results.
* Open a case against the business to track an investigation.

## Payment methods owned by a business

Each transaction can attach one or more payment methods (bank cards, bank accounts, e-wallets, crypto wallets). When a payment method is owned by a business, it links back via `vendor_data` — so you see every payment method a business has used historically, right on the Business detail page.

## Historical ingestion

To backfill historical transactions against an existing Business, pass `txn_date` in the past:

```bash theme={null}
curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "txn_id": "legacy-0001",
    "txn_date": "2024-03-15T10:00:00Z",
    "direction": "INBOUND",
    "amount": "25000.00",
    "currency": "EUR",
    "applicant": { "vendor_data": "biz-acme" },
    "counterparty": { "name": "Historic payer" }
  }'
```

<Note>
  Historical transactions still run through the rule engine. If you want to ingest history **without** triggering rules, use the console import flow which supports a "dry ingest" mode.
</Note>

## Next steps

<CardGroup>
  <Card title="Submit transactions" icon="arrow-right-to-bracket" href="/transaction-monitoring/transactions">
    Full payload reference.
  </Card>

  <Card title="Rules" icon="scale-balanced" href="/transaction-monitoring/rules">
    How rules evaluate transactions and act on businesses.
  </Card>

  <Card title="Statuses" icon="list-check" href="/transaction-monitoring/statuses">
    Transaction and remediation status reference.
  </Card>
</CardGroup>


# Entity Lifecycle
Source: https://docs.didit.me/entities/lifecycle

States and transitions for Didit User and Business entities — creation, verification, ACTIVE/FLAGGED/BLOCKED transitions, and deletion. Pay-per-call.

Every User and Business entity in Didit moves through a predictable lifecycle. Understanding this lifecycle is the key to designing your onboarding, ongoing monitoring, and remediation flows.

## Lifecycle diagram

```mermaid theme={null}
stateDiagram-v2
    [*] --> ACTIVE: Created (API, console, or auto from session)
    ACTIVE --> FLAGGED: Rule match / analyst review / suspicious pattern
    FLAGGED --> ACTIVE: Analyst clears / remediation completed
    ACTIVE --> BLOCKED: Session declined / manual block / blocklist match
    FLAGGED --> BLOCKED: Investigation concludes blocked
    BLOCKED --> ACTIVE: Manual unblock (analyst only)
```

## Statuses in detail

| Status    | Meaning                                     | Enforcement                                                                                                                    |
| --------- | ------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `ACTIVE`  | Default — entity is in good standing        | New sessions and transactions run through your configured workflows and rules                                                  |
| `FLAGGED` | Entity has a pending issue requiring review | New sessions still run but default to `IN_REVIEW`; transactions may auto-escalate depending on rules                           |
| `BLOCKED` | Entity is blocked from your platform        | New sessions are auto-declined; new transactions are auto-declined; no new session links can be created for this `vendor_data` |

<Note>
  Changing status via `PATCH /v3/users/{vendor_data}/update-status/` or `PATCH /v3/businesses/{vendor_data}/update-status/` emits a webhook (`user.status.updated` / `business.status.updated`) so downstream systems can react in real time.
</Note>

## Phases of the lifecycle

<Steps>
  <Step title="Creation" icon="plus">
    An entity is created in one of three ways:

    * **Auto-created** when you start a session with a new `vendor_data`. The entity is created in `ACTIVE` status.
    * **Pre-created via API** using `POST /v3/users/create/` or `POST /v3/businesses/create/`. Status defaults to `ACTIVE`.
    * **Created in the console** by a compliance operator — status starts at `ACTIVE` unless the operator specifies otherwise.

    Every entity gets a Didit-generated `uuid` and a customer-owned `vendor_data` identifier.
  </Step>

  <Step title="Verification" icon="shield-check">
    Sessions are attached to the entity via `vendor_data`. Each session runs through your configured [workflow](/console/workflows) — ID verification, liveness, face match, AML, documents, registry lookup for KYB, and so on.

    Completed sessions update the entity's aggregate counters:

    * `session_count`, `approved_count`, `declined_count`, `in_review_count`
    * `features` map — the latest status of each feature across all sessions (e.g. `{ "id_verification": "APPROVED", "aml": "IN_REVIEW" }`)
    * Profile fields propagate from the latest approved session (e.g. `full_name`, `date_of_birth`, `portrait_image`).
  </Step>

  <Step title="Active usage" icon="chart-line">
    Once an entity has one or more approved sessions, you can:

    * **Submit transactions** referencing the entity via `vendor_data` in the transaction payload
    * **Run ongoing AML monitoring** — periodic rescans of sanctions / PEP / adverse media lists
    * **Re-verify on a schedule** — create new sessions for the same `vendor_data` at regular intervals
    * **Aggregate risk signals** across sessions and transactions
  </Step>

  <Step title="Status transitions" icon="arrows-rotate">
    Entity status changes happen automatically or manually.

    **Automatic transitions**

    * `ACTIVE → BLOCKED` when a session is `DECLINED` and your workflow is configured to auto-block.
    * `ACTIVE → FLAGGED` when a transaction crosses the review threshold or a rule adds the entity to a watchlist.
    * `ACTIVE → BLOCKED` when a face biometric matches a blocklist entry.

    **Manual transitions** happen when an analyst changes status from the console or when you call the `update-status` endpoint.

    Every transition emits a `user.status.updated` or `business.status.updated` webhook.
  </Step>

  <Step title="Deletion" icon="trash">
    Entities are deleted via `POST /v3/users/delete/` or `POST /v3/businesses/delete/` (batch). The entity record is removed permanently. Deleting a User also purges every [biometric template](/management-api/biometric-templates/overview) retained for it after session deletion, so the person stops matching in duplicate detection and Face Search.

    Verification sessions are not covered by these endpoints, and neither are transactions. Delete sessions with [Delete Session](/sessions-api/delete-session) or [Batch Delete Sessions](/management-api/sessions/batch-delete); transactions are deleted from the Console.
  </Step>
</Steps>

## Activity timestamps

Entities track activity to help you identify stale or active profiles:

| Timestamp          | Updated when                                                              |
| ------------------ | ------------------------------------------------------------------------- |
| `first_session_at` | The first session was created for this entity                             |
| `last_session_at`  | The most recent session was created or updated                            |
| `last_activity_at` | Any change happened — session, transaction, status change, profile update |

Use these timestamps to filter dormant entities, schedule re-verifications, or trigger ongoing monitoring.

## Events emitted during the lifecycle

| Lifecycle phase              | Webhooks emitted                                                           |
| ---------------------------- | -------------------------------------------------------------------------- |
| Creation (auto from session) | `status.updated` (session), `user.data.updated` or `business.data.updated` |
| Verification                 | `status.updated` (session), `data.updated`, `business_session.*` for KYB   |
| Status change                | `user.status.updated` or `business.status.updated`                         |
| Transaction submitted        | `transaction.created`                                                      |
| Transaction status changed   | `transaction.status.updated`                                               |
| Activity logged              | `activity.created`                                                         |

See [entity webhooks](/entities/webhooks) for payload shapes and delivery semantics.

## Next steps

<CardGroup>
  <Card title="Vendor data linking" icon="link" href="/entities/vendor-data-linking">
    How `vendor_data` ties sessions, transactions, and entities together.
  </Card>

  <Card title="User operations" icon="user-pen" href="/entities/users/operations">
    Create, update, change status, and delete User entities.
  </Card>

  <Card title="Business operations" icon="building-columns" href="/entities/businesses/operations">
    Create, update, change status, and delete Business entities.
  </Card>
</CardGroup>


# Entities Overview
Source: https://docs.didit.me/entities/overview

Users and Businesses are Didit's two first-class entities. Each one aggregates KYC sessions, transactions, documents, biometrics, and risk into one profile.

Didit organizes everything that happens in your application around two first-class entity types:

| Entity       | Represents                                               | Linked to                                                                                                  |
| ------------ | -------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------- |
| **User**     | An individual person                                     | User Verification (KYC) sessions, face biometrics, transactions (as applicant/counterparty), blocklists    |
| **Business** | A legal entity (company, LLC, sole proprietorship, fund) | Business Verification (KYB) sessions, officers, UBOs, transactions (as applicant/counterparty), blocklists |

Every verification session, every transaction, and every blocklist entry can be bound to an entity. Once bound, the entity becomes a durable profile that aggregates history, risk signals, and compliance state across time.

## Entity vs session

An **entity** and a **session** are different things.

| Concept     | Scope                  | Lifespan                                                   | Example                                                                      |
| ----------- | ---------------------- | ---------------------------------------------------------- | ---------------------------------------------------------------------------- |
| **Session** | One verification event | Single flow (minutes to days while in review)              | A single KYC attempt                                                         |
| **Entity**  | A durable profile      | Lives as long as the user/business exists on your platform | The customer "Jane Doe" with 3 User Verification (KYC) sessions over 2 years |

A single entity can have many sessions — re-verifications, resubmissions, add-on checks, periodic ongoing monitoring. The entity aggregates the results.

## Auto-creation vs manual pre-creation

Entities are created in one of three ways:

<Steps>
  <Step title="Auto-created from a session">
    When you create a session with a `vendor_data` identifier and no matching entity exists, Didit creates the entity automatically. This is the most common path.

    ```bash theme={null}
    curl -X POST https://verification.didit.me/v3/session/ \
      -H "x-api-key: YOUR_API_KEY" \
      -d '{ "workflow_id": "wf_kyc_standard", "vendor_data": "user-42" }'
    ```

    A User entity for `user-42` is created the moment the session starts.
  </Step>

  <Step title="Pre-created via the Management API">
    Create the entity first, then start sessions against it. Useful when you want to seed risk signals (status, tags, custom metadata) before the first verification.

    ```bash theme={null}
    curl -X POST https://verification.didit.me/v3/users/create/ \
      -H "x-api-key: YOUR_API_KEY" \
      -d '{ "vendor_data": "user-42", "display_name": "Jane Doe" }'
    ```
  </Step>

  <Step title="Created in the console">
    Your compliance team can create users or businesses directly from the Business Console — useful for manual onboarding, imports, or remediation workflows.
  </Step>
</Steps>

## How entities link everything

The `vendor_data` field is the linking key. When you pass `vendor_data` on any session or transaction, Didit routes it to the matching entity.

```mermaid theme={null}
flowchart LR
    VD["vendor_data:<br/>user-42"] --> U[User entity]
    S1[User Verification (KYC) session #1] --> VD
    S2[User Verification (KYC) session #2] --> VD
    T1[Transaction #1] --> VD
    T2[Transaction #2] --> VD
    F[Face biometric] --> VD
    D[Documents] --> VD
    BL[Blocklist entry] --> VD
```

Learn more in the [`vendor_data` linking guide](/entities/vendor-data-linking).

## What you can do with an entity

For each User or Business entity, you can:

| Operation                      | Purpose                                                                                                |
| ------------------------------ | ------------------------------------------------------------------------------------------------------ |
| **Create / update**            | Set or change the entity's profile data (name, country, custom metadata)                               |
| **Change status**              | Mark as `ACTIVE`, `FLAGGED`, or `BLOCKED` — enforcement propagates to future sessions and transactions |
| **Attach biometrics**          | Upload a face reference for 1:N search, duplicate detection, or blocklisting                           |
| **Review KYC/KYB history**     | Retrieve every session tied to the entity, with per-feature results                                    |
| **Review transaction history** | Retrieve every transaction where the entity is the applicant or counterparty                           |
| **Add to a blocklist**         | Block future sessions or transactions involving this entity                                            |
| **Import / export**            | Bulk upload entities from CSV or export for external compliance tooling                                |
| **Delete**                     | Delete the entity (history is preserved for audit)                                                     |

Detailed walkthroughs live under [Users](/entities/users/overview) and [Businesses](/entities/businesses/overview).

## User ↔ Business relationships

A single User can be linked to one or many Businesses. This happens naturally during KYB:

* A User might be a **director** of one Business and a **UBO** of another.
* A User's User Verification (KYC) session can be linked to a Business's Business Verification (KYB) session via the [Key People](/business-verification/key-people) flow.

Didit preserves these relationships — when you inspect a Business entity, you can see every linked User, and when you inspect a User entity, you can see every Business they are associated with.

## Lifecycle and statuses

Every entity has a status that governs whether Didit enforces blocks on new activity:

| Status    | Effect                                                                                   |
| --------- | ---------------------------------------------------------------------------------------- |
| `ACTIVE`  | Normal — sessions and transactions proceed as configured by workflows and rules          |
| `FLAGGED` | Sessions and transactions are allowed, but automatically routed to manual review         |
| `BLOCKED` | Sessions and transactions are automatically declined, and no new sessions can be created |

See the full [entity lifecycle](/entities/lifecycle) for transitions and webhook events.

## Next steps

<CardGroup>
  <Card title="Lifecycle" icon="arrows-rotate" href="/entities/lifecycle">
    States, transitions, and lifecycle events for every entity.
  </Card>

  <Card title="Vendor data linking" icon="link" href="/entities/vendor-data-linking">
    How `vendor_data` binds sessions, transactions, and entities.
  </Card>

  <Card title="Users" icon="user" href="/entities/users/overview">
    Deep dive on User entities, operations, and console workflows.
  </Card>

  <Card title="Businesses" icon="building" href="/entities/businesses/overview">
    Deep dive on Business entities, operations, and console workflows.
  </Card>

  <Card title="Entity webhooks" icon="bolt" href="/entities/webhooks">
    Real-time events for every entity change.
  </Card>

  <Card title="Blocklist" icon="ban" href="/console/blocklist-users">
    How blocklist entries interact with User and Business entities.
  </Card>
</CardGroup>


# User Blocklist
Source: https://docs.didit.me/entities/users/blocklist

How Didit enforces blocks on User entities — identifier types (face, document, email, phone, vendor_data), automatic blocklisting, manual blocklisting.

Blocklists prevent users who have failed your compliance checks from creating new sessions or running new transactions. Didit supports blocklists by **identifier type**, so you can block the same bad actor across multiple data points (face, document, email, phone, user vendor\_data).

## Supported identifier types for Users

| Type               | Key                  | Matches when…                                                                               |
| ------------------ | -------------------- | ------------------------------------------------------------------------------------------- |
| Face               | `FACE`               | A new session's liveness selfie matches the blocklisted face                                |
| Document number    | `DOCUMENT`           | A new ID submission matches the blocklisted document number                                 |
| Email              | `EMAIL`              | A new session or transaction uses the blocklisted email                                     |
| Phone              | `PHONE`              | A new session or transaction uses the blocklisted phone                                     |
| IP address         | `IP_ADDRESS`         | The submitter's IP matches — supports single IPs (`1.2.3.4`) and CIDR ranges (`10.0.0.0/8`) |
| Device fingerprint | `DEVICE_FINGERPRINT` | The submitter's device fingerprint matches                                                  |
| User               | `USER`               | The session or transaction uses the blocklisted `vendor_data`                               |

Each identifier type is enforced at the natural touchpoint:

* Face and document: enforced during a new session.
* Email and phone: enforced during a session step that collects them, or during a transaction payload.
* IP and device: enforced during Device & IP Analysis in a session.
* User vendor\_data: enforced during session or transaction creation.

## How blocklisting happens

<Steps>
  <Step title="Automatic — on a declined session">
    When a session is declined and your workflow's auto-blocklist setting is enabled, Didit automatically adds relevant identifiers (face, document, email, phone) to the corresponding system blocklists and transitions the user to `BLOCKED`.
  </Step>

  <Step title="Automatic — on blocklist match">
    When an incoming session matches an existing blocklist entry, the session is auto-declined with a reason code like `blocked_face`, `blocked_document`, `blocked_email`, etc.
  </Step>

  <Step title="Manual — from the console">
    An analyst blocklists a user from *Users → \[user] → Actions → Add to blocklist*, choosing one or more identifiers to capture.
  </Step>

  <Step title="Programmatic — via the Lists API">
    Use the [Lists API](/management-api/lists/overview) to add entries programmatically. This is the same API the console uses under the hood.
  </Step>
</Steps>

## System lists vs custom lists

Every application has **system blocklists** — one per identifier type — that Didit auto-manages. You cannot rename or delete them. Custom lists are yours to create, name, and scope.

| List                      | Created by | Description                                               |
| ------------------------- | ---------- | --------------------------------------------------------- |
| System Face Blocklist     | Didit      | Canonical face blocklist for the application              |
| System Document Blocklist | Didit      | Canonical document number blocklist                       |
| System Email Blocklist    | Didit      | Canonical email blocklist                                 |
| System Phone Blocklist    | Didit      | Canonical phone blocklist                                 |
| System User Blocklist     | Didit      | Blocked `vendor_data` identifiers                         |
| Custom blocklists         | You        | Scoped lists, e.g. per region, per partner, per risk tier |

## Adding a user to the blocklist via API

Use the [Lists API](/management-api/lists/overview) to add a blocklist entry. To block a user by `vendor_data`, add a USER-type entry to the corresponding blocklist:

1. [List all lists](/management-api/lists/list) filtered by `entry_type=user` and `is_system=true` to find the system User blocklist.
2. [Create an entry](/management-api/lists/create-entry) on that list with `value` set to the user's `vendor_data`.

To block a user by face, see [Faces & biometrics](/entities/users/faces-and-biometrics#uploading-a-face-to-the-blocklist). To block by email, phone, document, or IP, use the corresponding system blocklist with the appropriate identifier in `value`.

## Enforcement flow

```mermaid theme={null}
sequenceDiagram
    participant Client
    participant Didit
    participant Lists as Blocklist check
    participant Workflow
    Client->>Didit: POST /v3/session/ (vendor_data=user-42)
    Didit->>Lists: Does user-42 match a USER blocklist?
    Lists-->>Didit: Match found
    Didit-->>Client: Session auto-declined (reason: blocked_user)
```

For face and document blocklists, the check happens at the verification step:

```mermaid theme={null}
sequenceDiagram
    participant User
    participant Didit
    participant Lists as Face Blocklist
    User->>Didit: Liveness capture
    Didit->>Lists: Embedding search
    Lists-->>Didit: Match similarity > threshold
    Didit-->>User: Session declined (reason: blocked_face)
```

## Removing from the blocklist

* **Console**: *Blocklist → \[type] → row actions → Remove*.
* **API**: use the [Delete entry](/management-api/lists/delete-entry) endpoint with the list UUID and entry UUID.

Removing the entry does not automatically move the user back to `ACTIVE` — use `PATCH /v3/users/{vendor_data}/update-status/` to change status if you want to allow new sessions.

## Blocklist audit trail

Every add/remove on a blocklist is logged to the [audit log](/console/audit-logs):

* Who added the entry (user email or `'system'`, `'api'`).
* When.
* Optional `comment` explaining the reason.
* Linked session or transaction if the entry was generated automatically.

## Next steps

<CardGroup>
  <Card title="Lists API" icon="list" href="/management-api/lists/overview">
    Full blocklist / allowlist API reference.
  </Card>

  <Card title="Console blocklist" icon="ban" href="/console/blocklist-users">
    Manage blocklists from the UI.
  </Card>

  <Card title="Faces & biometrics" icon="face-viewfinder" href="/entities/users/faces-and-biometrics">
    How face blocklists work.
  </Card>
</CardGroup>


# Users in the Console
Source: https://docs.didit.me/entities/users/console

Walkthrough of the Users section in the Didit Business Console — list view, detail tabs, bulk actions, and analyst operations on vendor User entities.

The Business Console at `business.didit.me` is where your compliance, operations, and customer support teams spend their time. The **Users** section is the primary UI surface for managing User entities.

## Navigating to Users

*Console → \[your team] → \[your application] → Users*

The route is: `/console/[team]/[app]/users`.

## List view

The Users list is an infinite-scroll table with column customization, filters, and bulk actions.

### Columns

Default columns: `User ID`, `Name`, `Email`, `Status`, `Created`, `Last activity`, `Country`, `Sessions`, `Risk`. You can toggle visibility and reorder columns via the column menu.

### Filters

| Filter     | Values                                                           |
| ---------- | ---------------------------------------------------------------- |
| Status     | `ACTIVE`, `FLAGGED`, `BLOCKED`                                   |
| Country    | ISO country codes                                                |
| Time range | Created or last activity window                                  |
| Search     | Matches `vendor_data`, `display_name`, `full_name`, email, phone |
| Tags       | Tag chips you've assigned                                        |
| KYC state  | Features present / missing                                       |

Filters are reflected in the URL, so you can share a saved view with teammates.

### Bulk actions

Select rows to enable:

* **Change status** — bulk move to `ACTIVE`, `FLAGGED`, or `BLOCKED`.
* **Add to blocklist** — push selected users' identifiers into a blocklist.
* **Export** — export the selected subset to CSV.
* **Delete** — delete the selected users.

## Detail view

Click any user row to open the detail panel. Tabs:

### Overview

* **Header**: `display_name`, `vendor_data`, `status`, primary action buttons.
* **Identity block**: full name, DOB, issuing country, portrait image (from latest approved liveness).
* **Risk indicators**: risk score, sanctions match count, active flags.
* **Feature matrix**: every feature's latest status across sessions.
* **Metadata**: custom fields, tags, notes count.

### Documents

* All documents ever captured for this user across all sessions.
* Filter by document type (ID, POA, NFC, selfie).
* Click any document to preview with signed URL; download option available.
* **Upload document** button (analyst-only) for offline documents.

### Verifications

* Every session tied to this user, newest first.
* Each row shows session status, workflow, feature summary, and timestamp.
* Click a row to open the full [session review](/console/manual-review) surface.

### Activity

* Chronological log: session events, transaction events, status changes, notes, tag changes, blocklist additions.
* Filterable by event type.

### Chat

* Internal notes for your team. Not visible to the user.
* Supports @-mentions of teammates.

### Transactions (where applicable)

* Every transaction where the user is applicant or counterparty.
* Filter by direction, status, amount, date, counterparty.

## Actions available on a user

| Action           | Where                                 | What it does                                                                                                            |
| ---------------- | ------------------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| Edit profile     | Overview → Edit                       | Update `display_name`, metadata, tags                                                                                   |
| Change status    | Overview → Actions → Change status    | Move between ACTIVE / FLAGGED / BLOCKED                                                                                 |
| Upload face      | Overview → Actions → Upload face      | Attach a face image; choose search/blocklist enrollment                                                                 |
| Upload document  | Documents tab                         | Manually attach ID, POA, or custom document                                                                             |
| Manage tags      | Overview → Manage tags                | Add/remove tag chips                                                                                                    |
| Add to blocklist | Overview → Actions → Add to blocklist | Push identifiers to face/email/phone/document blocklists                                                                |
| Open case        | Overview → Actions → Open case        | Start a [case-management](/console/transaction-monitoring) investigation tied to this user                              |
| Download PDF     | Overview → Actions → Download PDF     | Export a single PDF bundling every completed session for this user — see [Export to PDF & CSV](/console/export-pdf-csv) |
| Delete           | Overview → Actions → Delete           | Delete with confirmation dialog                                                                                         |

## Creating a user from the console

1. *Users → Create user*.
2. Enter `vendor_data` (required), `display_name`, optional metadata.
3. Set initial status (defaults to `ACTIVE`).
4. Save. The user appears in the list immediately.

Use this for manual onboarding, remediation, or testing without running a session first.

## Role-based visibility

Different roles see different actions:

| Role                | Edit profile | Change status | Upload face | Blocklist | Delete |  Export |
| ------------------- | :----------: | :-----------: | :---------: | :-------: | :----: | :-----: |
| OWNER               |       ✅      |       ✅       |      ✅      |     ✅     |    ✅   |    ✅    |
| ADMIN               |       ✅      |       ✅       |      ✅      |     ✅     |    ✅   |    ✅    |
| COMPLIANCE\_OFFICER |       ✅      |       ✅       |      ✅      |     ✅     |    ❌   |    ✅    |
| DEVELOPER           |       ✅      |       ❌       |      ❌      |     ❌     |    ❌   | Limited |
| READER              |       ❌      |       ❌       |      ❌      |     ❌     |    ❌   | Limited |

See [Roles & permissions](/console/roles-permissions) for the full matrix.

## Related console pages

* [Workflows](/console/workflows) — configure the verification flows users run through.
* [Verification links](/console/verification-links) — share a KYC link for a specific user.
* [Manual review](/console/manual-review) — review a session for a user.
* [Blocklist](/console/blocklist-users) — manage the application blocklists.
* [Analytics](/console/analytics) — volume and outcome trends across all users.

## Next steps

<CardGroup>
  <Card title="Operations API" icon="code" href="/entities/users/operations">
    Programmatic CRUD for the same operations.
  </Card>

  <Card title="Data model" icon="database" href="/entities/users/data-model">
    Field reference.
  </Card>

  <Card title="Manual review" icon="gavel" href="/console/manual-review">
    Reviewing sessions in depth.
  </Card>
</CardGroup>


# User Data Model
Source: https://docs.didit.me/entities/users/data-model

Every field on a Didit User entity, including identity, status, KYC session aggregates, biometrics, activity timestamps, and metadata. Pay-per-use pricing.

This page documents every field on a User entity. Fields fall into five groups: identity, status, session aggregates, activity timestamps, and metadata.

## Identity fields

| Field               | Type            | Description                                                                                        |
| ------------------- | --------------- | -------------------------------------------------------------------------------------------------- |
| `uuid`              | UUID            | Didit-assigned primary key. Stable and unique.                                                     |
| `didit_internal_id` | string          | Human-readable internal identifier (surfaced in API responses).                                    |
| `vendor_data`       | string          | Your identifier for the user. Unique per application. [Read more](/entities/vendor-data-linking).  |
| `display_name`      | string          | Override name shown in the console. Defaults to `full_name` or `vendor_data` when unset.           |
| `full_name`         | string          | Full legal name propagated from the latest approved User Verification (KYC) session's ID document. |
| `date_of_birth`     | date (ISO 8601) | Propagated from the latest approved User Verification (KYC) session.                               |
| `portrait_image`    | URL             | Signed S3 URL for the selfie from the latest approved liveness check.                              |

<Note>
  `full_name`, `date_of_birth`, and `portrait_image` are read-only when derived from a verified session. You can override them via the console or via `PATCH /v3/users/{vendor_data}/`, but manual overrides are flagged in the audit log.
</Note>

## Status

| Field    | Type | Values                         | Description                                                                                      |
| -------- | ---- | ------------------------------ | ------------------------------------------------------------------------------------------------ |
| `status` | enum | `ACTIVE`, `FLAGGED`, `BLOCKED` | Controls enforcement for future sessions and transactions. See [lifecycle](/entities/lifecycle). |

## Session aggregate fields

These fields are computed by Didit and update in real time as sessions complete.

| Field               | Type                       | Description                                                                            |
| ------------------- | -------------------------- | -------------------------------------------------------------------------------------- |
| `session_count`     | int                        | Total sessions ever created for this user                                              |
| `approved_count`    | int                        | Sessions that finished with `APPROVED`                                                 |
| `declined_count`    | int                        | Sessions that finished with `DECLINED`                                                 |
| `in_review_count`   | int                        | Sessions currently `IN_REVIEW`                                                         |
| `issuing_states[]`  | array of ISO country codes | Countries of all ID documents verified across sessions                                 |
| `approved_emails[]` | array of strings           | Emails verified via [Email Verification](/core-technology/email-verification/overview) |
| `approved_phones[]` | array of strings           | Phones verified via [Phone Verification](/core-technology/phone-verification/overview) |
| `features`          | object                     | Latest status of each feature across all sessions                                      |

### The `features` map

Every session runs one or more features (ID verification, liveness, face match, AML, POA, NFC, etc.). The `features` map holds the **latest** status of each feature for this user:

```json theme={null}
{
  "id_verification": "APPROVED",
  "liveness": "APPROVED",
  "face_match": "APPROVED",
  "aml": "IN_REVIEW",
  "proof_of_address": "APPROVED",
  "nfc_verification": "NOT_FINISHED"
}
```

Feature statuses: `NOT_FINISHED`, `APPROVED`, `DECLINED`, `IN_REVIEW`, `EXPIRED`, `ABANDONED`, `RESUB_REQUESTED`.

Use the `features` map as the fast path to answer "is this user fully verified right now?" without iterating all sessions.

## Activity timestamps

| Field              | Type          | Updated when                                                    |
| ------------------ | ------------- | --------------------------------------------------------------- |
| `first_session_at` | ISO timestamp | First session was created                                       |
| `last_session_at`  | ISO timestamp | Most recent session was created or updated                      |
| `last_activity_at` | ISO timestamp | Any change — session, transaction, status, profile, notes, tags |
| `created_at`       | ISO timestamp | Entity row was created                                          |
| `updated_at`       | ISO timestamp | Entity row was last updated                                     |

## Metadata

| Field      | Type          | Description                                                                  |
| ---------- | ------------- | ---------------------------------------------------------------------------- |
| `metadata` | object (JSON) | Free-form JSON you control. Use for internal tags, tier, signup source, etc. |
| `tags[]`   | array         | Console/API-managed tags for filtering and grouping                          |

Metadata has no schema — Didit persists whatever you write.

## Relations (not stored on the user row)

| Relation                           | How to access                                                                          |
| ---------------------------------- | -------------------------------------------------------------------------------------- |
| Sessions                           | `GET /v3/sessions?vendor_data=<value>`                                                 |
| Transactions (as applicant)        | `GET /v3/transactions/?vendor_data=<value>`                                            |
| Transactions (as counterparty)     | Filter transaction list by counterparty vendor\_data in console                        |
| Linked businesses (director / UBO) | Surfaced on the user detail page in the console                                        |
| Face biometrics                    | Console + Lists API                                                                    |
| Blocklist entries                  | [Lists API](/management-api/lists/overview) — filter entries by the user's identifiers |

## Example response

```json theme={null}
{
  "uuid": "9c7d2a30-2f98-4d4f-9d2d-1a7c4b1e5b6a",
  "didit_internal_id": "U-2026-00042",
  "vendor_data": "user-42",
  "display_name": "Jane Doe",
  "full_name": "John Doe",
  "date_of_birth": "1990-01-01",
  "portrait_image": "https://<media-host>/...",
  "status": "ACTIVE",
  "session_count": 3,
  "approved_count": 2,
  "declined_count": 0,
  "in_review_count": 1,
  "issuing_states": ["US", "ES"],
  "approved_emails": ["jane@example.com"],
  "approved_phones": ["+14155550123"],
  "features": {
    "id_verification": "APPROVED",
    "liveness": "APPROVED",
    "face_match": "APPROVED",
    "aml": "IN_REVIEW"
  },
  "first_session_at": "2025-03-01T12:00:00Z",
  "last_session_at": "2026-04-10T09:00:00Z",
  "last_activity_at": "2026-04-16T10:00:00Z",
  "metadata": { "tier": "premium" }
}
```

## Next steps

<CardGroup>
  <Card title="Operations" icon="gear" href="/entities/users/operations">
    Create, update, change status, delete.
  </Card>

  <Card title="KYC history" icon="clock-rotate-left" href="/entities/users/kyc-history">
    Retrieve every session tied to the user.
  </Card>

  <Card title="API reference" icon="code" href="/management-api/users/get">
    GET /v3/users// schema.
  </Card>
</CardGroup>


# User Documents
Source: https://docs.didit.me/entities/users/documents

IDs, proofs of address, and supporting files on Didit User entities — what's collected, how to retrieve them, and how to upload from the console.

<AgentPromptAccordion title="User Documents Prompt" />

Every document a user uploads during verification is permanently linked to their User entity. This page explains what's collected, how to retrieve it, and how to upload additional documents manually.

## What Didit collects

| Document type                                                                 | When collected                                                      | Fields extracted                                                       |
| ----------------------------------------------------------------------------- | ------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| **Government ID** (passport, national ID, driver's license, residence permit) | [ID verification](/core-technology/id-verification/overview) step   | Name, DOB, document number, issuing country, expiry, MRZ where present |
| **Selfie / liveness frames**                                                  | [Liveness](/core-technology/liveness/overview) step                 | Largest face crop, passive liveness score                              |
| **Proof of address (POA)**                                                    | [POA](/core-technology/proof-of-address/overview) step              | Name, address, issuer, document date                                   |
| **NFC chip read**                                                             | [NFC verification](/core-technology/nfc-verification/overview) step | Chip data, ICAO certificate chain, match against OCR                   |
| **Additional documents**                                                      | Analyst request or custom workflow steps                            | OCR when applicable, otherwise stored as-is                            |

[Supported document types](/core-technology/id-verification/supported-documents-id-verification) covers the full country × document matrix (14,000+ documents across 220+ countries).

## Retrieving documents

Documents are associated with the **session** that collected them, not directly with the user. To list all documents for a user:

<Steps>
  <Step title="List the user's sessions">
    ```bash theme={null}
    curl -G https://verification.didit.me/v3/sessions/ \
      -H "x-api-key: YOUR_API_KEY" \
      --data-urlencode "vendor_data=user-42"
    ```
  </Step>

  <Step title="Fetch each session's decision">
    Each session decision includes URLs to the collected documents.

    ```bash theme={null}
    curl https://verification.didit.me/v3/session/{session_id}/decision/ \
      -H "x-api-key: YOUR_API_KEY"
    ```

    Inspect the `id_verification.document_images`, `proof_of_address.document_images`, and `liveness.images` fields in the response.
  </Step>

  <Step title="Use signed URLs">
    Image URLs in the response are short-lived signed URLs. Cache them client-side for the duration of use, or re-fetch the decision when they expire.
  </Step>
</Steps>

## Generating a PDF report

For a human-readable export of everything collected for a session, including all documents, use:

**`GET /v3/session/{session_id}/generate-pdf/`**

Returns a PDF with session details, feature results, and embedded document images. Useful for compliance audits, SAR attachments, and regulatory filings.

## Uploading documents from the console

Compliance operators can upload additional documents against a user or an active session:

1. Navigate to *Users → \[user] → Documents → Upload document*.
2. Choose a document type (ID, POA, custom).
3. Upload a file; OCR runs automatically for supported types.
4. The document attaches to the most recent session (or you can create a remediation session).

<Note>
  The document upload UI is console-only — there is no public API endpoint for directly attaching documents to a user. Use sessions as the entry point for all document capture.
</Note>

## Document cross-referencing

When a session collects multiple document types, Didit cross-references them:

* **ID ↔ Liveness** — face on the ID matches the liveness selfie.
* **ID ↔ POA** — name on the POA matches the name extracted from the ID.
* **ID ↔ NFC** — MRZ / visual data matches the NFC chip data.

Inconsistencies are surfaced as warnings on the session decision and can be configured to trigger manual review.

## Document monitoring and re-verification

For use-cases requiring ongoing document validity (e.g. expired IDs):

* **Document expiry** is tracked on every verified ID. Query the session decision for the `expiry_date` field.
* **Re-verification** — trigger a new session against the same `vendor_data` to refresh documents.
* **Document monitoring** — opt into [document monitoring](/core-technology/id-verification/document-monitoring-id-verification) to be notified when a document is about to expire.

## Document geolocation

The [ID document geolocation](/core-technology/id-verification/document-geolocation-id-verification) check compares the IP location of the submitter against the issuing country of the ID. Results are attached to the session decision.

## Privacy and retention

* All documents are encrypted at rest.
* Image access is via short-lived signed URLs.
* Retention follows the application's [data retention](/console/data-retention) policy.
* Users have the right to request deletion; deletion removes images, OCR extracts, and NFC data.

## Next steps

<CardGroup>
  <Card title="ID verification" icon="id-card" href="/core-technology/id-verification/overview">
    How ID capture and OCR works.
  </Card>

  <Card title="Proof of address" icon="file-invoice" href="/core-technology/proof-of-address/overview">
    POA document collection.
  </Card>

  <Card title="Session decision" icon="file-lines" href="/sessions-api/retrieve-session">
    GET /v3/session//decision/ reference.
  </Card>
</CardGroup>


# Faces and Biometrics
Source: https://docs.didit.me/entities/users/faces-and-biometrics

How Didit attaches face biometrics to vendor User entities — 1:N search, duplicate detection, face blocklist enforcement, and manual upload.

<AgentPromptAccordion title="Face Biometrics Prompt" />

Face biometrics are central to every User entity. Didit captures a face during [liveness detection](/core-technology/liveness/overview), generates a vector embedding, and stores it for four downstream features: **1:N face search**, **duplicate detection**, **blocklist enforcement**, and **biometric re-authentication**.

<Note>
  Stored faces double as the reference for [Biometric Authentication](/core-technology/biometric-auth/overview): create a biometric-auth session with the user's `vendor_data` and omit `portrait_image`, and Didit reuses the stored face automatically (approved liveness face first, then the ePassport chip photo, then the ID document portrait, then a manually enrolled profile face).
</Note>

## How faces attach to a user

<Steps>
  <Step title="Captured during liveness">
    When a User goes through a session with liveness enabled, Didit captures a selfie, runs passive liveness detection, extracts the largest face, and generates a vector embedding for search.
  </Step>

  <Step title="Stored on the user profile">
    The face is linked to the session and the parent User entity. The portrait URL surfaces on the user profile as `portrait_image`.
  </Step>

  <Step title="Indexed for search">
    The embedding is added to the search index. Subsequent sessions can run 1:N searches against this index.
  </Step>
</Steps>

## Face search (1:N)

Face search lets you find a user by uploading an image and matching it against every enrolled face in your application.

Use-cases:

* **Duplicate detection** at onboarding — prevent the same person from creating two accounts.
* **Reverse lookup** — identify the user behind a CCTV frame or an image in a fraud investigation.
* **Repeat customer recognition** — skip KYC for a returning customer.

Face search runs automatically during new sessions when your workflow has duplicate detection enabled. It is also exposed as a standalone API:

* `POST /v3/face-search/` — [standalone face search](/standalone-apis/face-search)

## Duplicate detection

Every new face can be compared against existing enrolled faces to surface duplicates. Didit assigns each face an `approved_duplicate_status`:

| Status           | Meaning                                                       |
| ---------------- | ------------------------------------------------------------- |
| `NOT_DUPLICATED` | No matches found above the similarity threshold               |
| `DUPLICATED`     | Face matches one or more faces on an already-approved session |

Workflows can be configured to:

* **Decline** duplicate-flagged sessions automatically.
* **Flag for review** — route to a human analyst.
* **Warn only** — allow but add a risk tag.

Configure this in the console at *Workflows → \[your workflow] → Face Match / Liveness → Duplicate detection*.

## Face blocklist

When a session is declined (by rule, analyst, or workflow configuration), the associated face is automatically added to the **Face Blocklist** for your application. Future sessions with a matching face are rejected.

## Upload an imported face to a User profile

If you are migrating from another KYC provider, you can create the User first and then attach a trusted face image to that profile. The User is still keyed by your `vendor_data`, but the face upload endpoint uses Didit's internal User id (`didit_internal_id`) so the target is unambiguous.

<Steps>
  <Step title="Create or retrieve the User">
    Call [`POST /v3/users/create/`](/management-api/users/create) with your stable `vendor_data`, or call `GET /v3/users/{vendor_data}/` if the User already exists.
  </Step>

  <Step title="Read didit_internal_id">
    The User response includes `didit_internal_id`. Keep using `vendor_data` in your own system; use `didit_internal_id` only for profile attachment endpoints.
  </Step>

  <Step title="Upload the face">
    Call [`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`](/management-api/users/upload-face) with a base64-encoded face image.
  </Step>
</Steps>

```bash theme={null}
# 1. Create or retrieve the User keyed by your vendor_data
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "previous_provider": "legacy-kyc-vendor" }
  }'

# Response includes:
# { "didit_internal_id": "11111111-2222-3333-4444-555555555555", ... }

# 2. Upload the imported face to the User profile
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/11111111-2222-3333-4444-555555555555/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'
```

Imported profile faces are enrolled into the same face index used for duplicate detection and face search. They are not automatically blocklisted. To block a known bad actor, upload the face to a face-type list instead.

<Warning>
  Only upload faces you are allowed to process under your own privacy notice and migration agreement. Keep source-provider identifiers in `metadata` or `comment` only when they are safe to expose to your compliance operators.
</Warning>

### How blocklisting happens

| Trigger                                             | Action                                                      |
| --------------------------------------------------- | ----------------------------------------------------------- |
| Session `DECLINED` and auto-blocklist enabled       | Face added to the system face list, user status → `BLOCKED` |
| Analyst manually blocklists a face from the console | Face added, user status updated per policy                  |
| Programmatic add via the Lists API                  | Upload the face image to a face-type blocklist              |

### Uploading a face to the blocklist

To block a user by face programmatically, upload the face image to a face-type blocklist via the dedicated [Upload face to list](/management-api/lists/upload-face) endpoint. Didit extracts the biometric embedding and inserts it into the matching index — any future session whose liveness selfie matches is auto-declined.

<Note>
  Profile face upload and face blocklist upload are different operations. Use profile upload to attach a trusted imported face to a User for evidence, duplicate detection, and face search. Use the [Lists API](/management-api/lists/overview) to block a face so future matching sessions are rejected.
</Note>

### Removing a face from the blocklist

Remove the entry from the console at *Blocklist → Faces → row actions → Remove*, or use the [Delete entry](/management-api/lists/delete-entry) endpoint.

## Retained biometric templates after session deletion

Deleting a session deletes the face image and, by default, the face embedding, so the person drops out of duplicate detection and Face Search. If you delete sessions soon after approval but still need to catch repeat sign-ups, enable [biometric-template retention](/console/data-retention#biometric-template-retention) on the application, or send `retain_face_embeddings: true` on the delete call.

Didit then deletes the session and all of its data as usual and keeps one separately managed, image-free face biometric template anchored to the User:

* It contains the numeric face template plus retention metadata only. It never contains the face image, liveness video, document data, extracted identity fields, the decision, or the deleted session's id.
* It takes part in duplicate detection, Face Search, biometric authentication, and your face lists exactly like a live session face. Hits are reported with `source: "retained_template"`, the User's `vendor_user_id` and `vendor_data`, and a `biometric_template_id`.
* It is biometric data with a finite `expires_at`. It is purged when the User is deleted, when any session of that User is deleted with `deletion_instruction: "privacy_erasure"`, when it expires, or when you purge it in **Lists → Biometric templates** or through the [Biometric Templates API](/management-api/biometric-templates/overview).
* A session created without `vendor_data` has no User to anchor a template to; deleting it reports `ineligible_no_vendor_user` and the embedding is deleted with the session.
* Retained templates are never blocklisted. A face blocklist entry created from the deleted session keeps its own independent biometric entry and lifecycle.

Templates anchored to a User appear on the User profile under **Biometric templates**, with a purge action.

## Face lifecycle summary

```mermaid theme={null}
stateDiagram-v2
    [*] --> Enrolled: Face captured during liveness
    Enrolled --> Approved: Session approved
    Enrolled --> Declined: Session declined
    Declined --> Blocklisted: Auto-blocklist enabled
    Enrolled --> Duplicated: 1:N search finds match
    Duplicated --> Approved: Allowed by workflow
    Duplicated --> Declined: Rejected by workflow
    Blocklisted --> [*]: Manually removed
    Approved --> [*]: Session deleted (default)
    Approved --> RetainedTemplate: Session deleted with retention enabled
    RetainedTemplate --> [*]: Expiry, User deletion, privacy erasure, or purge
```

## Upload a face from the console

Compliance operators can upload faces manually:

1. Navigate to *Users → \[user] → Actions → Upload face*.
2. Select an image; Didit extracts the largest face and stores a new Face record linked to the user.
3. The face is enrolled for profile evidence, duplicate detection, and face search. Use the Blocklist area when the goal is to reject future matching sessions.

This is useful when:

* You have a known portrait of a customer verified through an offline channel.
* You want to pre-seed a blocklist with known bad actors from your fraud database.

## Privacy and retention

* Face embeddings are numerical vectors, not images. Images themselves are stored in encrypted object storage with signed-URL access. A face embedding is biometric data.
* Retention follows your application's [data retention](/console/data-retention) policy. Retained biometric templates follow the stricter, finite [biometric-template retention](/console/data-retention#biometric-template-retention) period.
* Deleting a session deletes the image and, by default, the embedding. If your application has opted in to biometric-template retention, deleting a session keeps an image-free template until it expires or is purged.
* For a GDPR / CCPA right-to-be-forgotten request, delete the person's sessions with `deletion_instruction: "privacy_erasure"` or delete the User: both purge every retained template as well. Face blocklist entries you manage stay until you remove them.

## Next steps

<CardGroup>
  <Card title="Face Search" icon="magnifying-glass" href="/core-technology/face-search/overview">
    How 1:N face search works.
  </Card>

  <Card title="Liveness" icon="face-viewfinder" href="/core-technology/liveness/overview">
    Liveness detection that captures the face.
  </Card>

  <Card title="Blocklist API" icon="ban" href="/management-api/lists/upload-face">
    Upload a face to a blocklist.
  </Card>

  <Card title="Biometric templates" icon="fingerprint" href="/management-api/biometric-templates/overview">
    Templates retained after session deletion.
  </Card>

  <Card title="User blocklist" icon="user-slash" href="/entities/users/blocklist">
    How blocklisting a user works.
  </Card>
</CardGroup>


# Import and Export Users
Source: https://docs.didit.me/entities/users/import-export

Bulk-load Didit vendor User entities from CSV and export the full user table for external compliance tooling. Available from the Business Console.

<AgentPromptAccordion title="Bulk Import / Export Users Prompt" />

The Business Console lets your team bulk-manage User entities without writing code. Two flows are supported: **CSV import** (create or update users at scale) and **CSV export** (extract the user table for external tooling).

<Note>
  Bulk import/export here creates or updates User profiles only. It does not recreate historical KYC sessions, document warnings, liveness evidence, or provider decisions. For a full migration from Sumsub, MetaMap, Veriff, Onfido, Persona, or another provider, see [Import Data from Another Provider](/sessions-api/import-verifications).
</Note>

## Import users from CSV

### When to use it

* **Day-one migration** from another KYC vendor — bring your existing user roster over.
* **Provider face migration** — attach trusted face images to the imported User profiles after the rows are created.
* **Bulk onboarding** of a partner's customer list.
* **Metadata backfill** — update tags, tier, or internal identifiers on many users at once.

### Template columns

Download the template from *Users → Import → Download template*. Columns:

| Column          | Required | Description                                                   |
| --------------- | -------- | ------------------------------------------------------------- |
| `vendor_data`   | Yes      | Your identifier for the user. Must be unique per application. |
| `display_name`  | No       | Human-readable name shown in the console.                     |
| `full_name`     | No       | Legal name. Will be overwritten by verified session data.     |
| `email`         | No       | Known contact email.                                          |
| `phone`         | No       | Known contact phone (E.164 format).                           |
| `country`       | No       | ISO 3166-1 alpha-3 country code.                              |
| `status`        | No       | `ACTIVE`, `FLAGGED`, or `BLOCKED`. Defaults to `ACTIVE`.      |
| `tags`          | No       | Comma-separated tags.                                         |
| `metadata_json` | No       | Stringified JSON for custom metadata.                         |

### Running the import

<Steps>
  <Step title="Upload the CSV">
    Navigate to *Users → Import → Upload CSV* and select your file.
  </Step>

  <Step title="Review the preview">
    The console validates each row. Invalid rows are highlighted with error reasons (e.g. duplicate `vendor_data`, invalid country code).
  </Step>

  <Step title="Start the import">
    Didit processes the rows asynchronously. You can close the tab — progress is tracked in *Users → Import history*.
  </Step>

  <Step title="Review results">
    When the import finishes, the history view shows counts of created, updated, and skipped rows, plus a downloadable error report.
  </Step>
</Steps>

### Update vs create

* If a `vendor_data` does not exist, a new User is created.
* If a `vendor_data` already exists, the row updates the existing User (profile fields and metadata).
* Aggregate counters and verified fields (`full_name`, `date_of_birth` from approved sessions) are **never overwritten** by imports.

### Import faces after user creation

CSV import creates or updates the User row. It does not include face images in the CSV. To bring over face biometrics from another provider, upload each face after the target User exists:

<Steps>
  <Step title="Create or import the User">
    Use the console CSV import, or call [`POST /v3/users/create/`](/management-api/users/create) in a loop.
  </Step>

  <Step title="Read didit_internal_id">
    Fetch the User with [`GET /v3/users/{vendor_data}/`](/management-api/users/get). The response includes `didit_internal_id`.
  </Step>

  <Step title="Upload the face">
    Call [`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`](/management-api/users/upload-face) with a raw base64 face image.
  </Step>
</Steps>

```bash theme={null}
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'
```

The face must be a valid image, max 2 MB decoded, and contain a detectable face. Didit stores it on the profile and indexes it for duplicate detection and face search. It is not added to a face blocklist unless you separately use the [Upload face to list](/management-api/lists/upload-face) endpoint.

## Export users to CSV

### When to use it

* **Compliance audits** — deliver the full user table to auditors.
* **Data warehouse sync** — periodic dump into your BI tooling.
* **SAR / regulator requests** — extract filtered subsets of users.

### Running an export

1. Navigate to *Users → Export*.
2. Apply filters (status, country, date range, search).
3. Choose columns (the default is every field; you can drop columns you don't need).
4. Submit. Didit generates the export asynchronously and emails a signed download link to the requesting operator.

<Note>
  Exports include only data your role is allowed to read. COMPLIANCE\_OFFICER and above can export the full table; DEVELOPER and READER roles have restricted exports.
</Note>

## Performance characteristics

| Operation | Typical scale        | Notes                                                              |
| --------- | -------------------- | ------------------------------------------------------------------ |
| Import    | Up to 100,000 rows   | Larger files are chunked server-side; progress is polled by the UI |
| Export    | Up to 1,000,000 rows | Larger exports are streamed to S3 and delivered via signed URL     |

## Audit trail

Every import and export is logged in the [audit log](/console/audit-logs):

* The operator who triggered it.
* Row counts (imports) / filter snapshot (exports).
* Timestamps and success/failure state.

## Next steps

<CardGroup>
  <Card title="Create user API" icon="plus" href="/management-api/users/create">
    Programmatic creation for scripted imports.
  </Card>

  <Card title="Upload user face" icon="face-viewfinder" href="/management-api/users/upload-face">
    Attach imported face images to User profiles.
  </Card>

  <Card title="Data retention" icon="shield-halved" href="/console/data-retention">
    How long imported data persists.
  </Card>

  <Card title="Audit logs" icon="file-lines" href="/console/audit-logs">
    Review import/export history.
  </Card>
</CardGroup>


# User KYC History
Source: https://docs.didit.me/entities/users/kyc-history

Retrieve every Didit verification session tied to a User entity, inspect feature-level results, trigger re-verification, and export compliance reports.

<AgentPromptAccordion title="KYC History Prompt" />

Every User Verification (KYC) session a user has ever run stays permanently linked to their User entity. You can retrieve the full history, inspect individual session results, trigger re-verification, and export compliance reports.

## Listing all sessions for a user

Filter the Sessions list by `vendor_data`:

```bash theme={null}
curl -G https://verification.didit.me/v3/sessions/ \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "vendor_data=user-42" \
  --data-urlencode "page_size=50"
```

Response includes every session (regardless of status) — approved, declined, in review, abandoned, or expired.

## Understanding the feature aggregates

The User entity's `features` map reflects the **latest** status of each feature across all sessions:

```json theme={null}
"features": {
  "id_verification": "APPROVED",
  "liveness": "APPROVED",
  "face_match": "APPROVED",
  "aml": "IN_REVIEW"
}
```

Use this as the fast path to answer "is the user verified right now?". For the historical record — all sessions, all features, all results — list sessions and inspect each decision.

## Inspecting a single session

```bash theme={null}
curl https://verification.didit.me/v3/session/{session_id}/decision/ \
  -H "x-api-key: YOUR_API_KEY"
```

The decision includes:

* Per-feature results (ID, liveness, face match, AML, POA, NFC, etc.)
* Extracted document data and images (signed URLs)
* AML hits with match/risk scores
* Device & IP Analysis and device context
* Reviewer notes and manual actions

See [retrieve session](/sessions-api/retrieve-session) for the full schema.

## Triggering re-verification

When you need a user to re-verify (e.g. annual re-KYC, document expiry, trigger-based re-check):

```bash theme={null}
curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wf_reverification",
    "vendor_data": "user-42"
  }'
```

The new session attaches to the same User entity. On completion, the entity's `features` map updates to reflect the new results.

## Resubmission vs new session

| Scenario                                                                     | Use                                                                                  |
| ---------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| User's session was declined due to a fixable issue (blurry ID, bad lighting) | [Resubmit](/console/manual-review) — same session, new upload                        |
| Full re-verification or periodic re-KYC                                      | Create a brand new session                                                           |
| Remediation triggered by a transaction rule                                  | The transaction creates a remediation session automatically (`AWAITING_USER` status) |

## Exporting a compliance report

For audits, SARs, or regulator requests, generate a PDF for any session:

```bash theme={null}
curl https://verification.didit.me/v3/session/{session_id}/generate-pdf/ \
  -H "x-api-key: YOUR_API_KEY" \
  -o session-report.pdf
```

For bulk exports across many sessions, use the console's CSV/PDF export from *Users → \[user] → Verifications* or the app-wide export at *Review & Operations → Export PDF/CSV*.

## Sharing a session with a third party

When you need to share a user's verification with a partner app (e.g. a reusable KYC scenario), use:

* `POST /v3/session/{session_id}/share/` — generate a shareable token.
* `POST /v3/session/import-shared/` — import a shared session on the receiving side.

See [reusable KYC](/core-technology/reusable-kyc/overview) for the full pattern.

## History-driven workflows

Use session history to drive smarter compliance decisions:

* **Skip steps** if the user already has an approved liveness within N days.
* **Require additional checks** if the user's most recent session was declined.
* **Flag** when a user's session count spikes unexpectedly.
* **Monitor** ongoing AML rescans via the [continuous monitoring](/core-technology/aml-screening/continuous-monitoring-aml-screening) feature.

## Next steps

<CardGroup>
  <Card title="Data model" icon="database" href="/entities/users/data-model">
    How the features map and counters are computed.
  </Card>

  <Card title="Retrieve session" icon="file-lines" href="/sessions-api/retrieve-session">
    Full session decision schema.
  </Card>

  <Card title="Reusable KYC" icon="arrows-rotate" href="/core-technology/reusable-kyc/overview">
    Reuse verified data across applications.
  </Card>
</CardGroup>


# User Operations
Source: https://docs.didit.me/entities/users/operations

Create, read, update, change status, and delete Didit vendor User entities via the Management API. Pay-per-use pricing, no contracts.

<AgentPromptAccordion title="User Operations Prompt" />

Core User entity management happens through public endpoints under `/v3/users/`. Profile attachments, such as imported face upload, use the organization/application path with `didit_internal_id`. This page gives you the conceptual walkthrough — see the [API reference](/management-api/users/list) for full request / response schemas.

## List users

**`GET /v3/users/`**

Returns a paginated list of users for your application. Supports filters on status, search, date range, and more.

```bash theme={null}
curl -G https://verification.didit.me/v3/users/ \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "status=ACTIVE" \
  --data-urlencode "search=jane" \
  --data-urlencode "page_size=50"
```

Use-cases:

* Sync a subset of users to your data warehouse each day.
* Find flagged users for an analyst queue.
* Search users by display name.

## Get a user

**`GET /v3/users/{vendor_data}/`**

Retrieve a single user by `vendor_data`. Returns the full [data model](/entities/users/data-model) including aggregated counters.

```bash theme={null}
curl https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY"
```

<Note>
  `vendor_data` in the URL is case-sensitive. Always pass the exact value you used on session creation.
</Note>

## Create a user

**`POST /v3/users/create/`**

Create a User entity before any session runs. Useful for:

* Seeding metadata or custom fields before the customer verifies.
* Setting an initial status (e.g. `FLAGGED` while your onboarding team reviews manual documents).
* Pre-loading users from an existing database so you have a complete roster from day one.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "tier": "premium", "signup_source": "web" }
  }'
```

If a user with that `vendor_data` already exists, the call returns a conflict error — use `PATCH` to update instead.

## Upload an imported face

**`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`**

Attach a trusted face image to an existing User profile. This is the right follow-up when you import users from another provider and want Didit to carry their face evidence before the first Didit session.

```bash theme={null}
# First create or retrieve the User and read didit_internal_id from the response.
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'
```

See [Upload User Face](/management-api/users/upload-face) for request fields, limits, list/delete endpoints, and the blocklist distinction.

## Update a user

**`PATCH /v3/users/{vendor_data}/`**

Update mutable profile fields. Most fields derived from verified sessions are read-only — attempting to change them via PATCH will either be ignored or flagged in the audit log.

**Mutable fields:** `display_name`, `metadata`, `tags`.
**Read-only after verification:** `full_name`, `date_of_birth`, `portrait_image`, all aggregate counters, `features` map.

```bash theme={null}
curl -X PATCH https://verification.didit.me/v3/users/user-42/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "metadata": { "tier": "enterprise" } }'
```

Emits a `user.data.updated` webhook with the `changed_fields` array.

## Change status

**`PATCH /v3/users/{vendor_data}/update-status/`**

Move a user between `ACTIVE`, `FLAGGED`, and `BLOCKED`. Status changes propagate to future sessions and transactions.

```bash theme={null}
curl -X PATCH https://verification.didit.me/v3/users/user-42/update-status/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "status": "BLOCKED",
    "reason": "Chargeback fraud pattern detected"
  }'
```

| From → to            | Common trigger                                                     |
| -------------------- | ------------------------------------------------------------------ |
| `ACTIVE` → `FLAGGED` | Transaction rule, analyst review, ongoing AML hit                  |
| `ACTIVE` → `BLOCKED` | Confirmed fraud, session declined with auto-block, blocklist match |
| `FLAGGED` → `ACTIVE` | Analyst cleared review                                             |
| `BLOCKED` → `ACTIVE` | Manual unblock by an analyst                                       |

Emits a `user.status.updated` webhook.

## Delete users (batch)

**`POST /v3/users/delete/`**

Delete one or more users. The user records are removed permanently, together with every [biometric template](/management-api/biometric-templates/overview) retained for them after session deletion. Their verification sessions are not covered by this endpoint and survive with their link to the user cleared; delete them with [Delete Session](/sessions-api/delete-session) or [Batch Delete Sessions](/management-api/sessions/batch-delete). Transactions are not covered either; delete those from the Console.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/users/delete/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data_list": ["user-42", "user-43", "user-44"]
  }'
```

Select users by `vendor_data_list`, by `didit_internal_id_list`, or by both at once; or
pass `delete_all: true` to remove every user in the application. The Console's `filter_*`
batch params are rejected here with a `400` rather than ignored, so a narrowed intent can
never turn into a full wipe.

Returns a count, `{"deleted": <int>}`, not a per-item result. Identifiers that matched nothing are skipped silently, so send a de-duplicated list if you want to compare `deleted` against the number of identifiers you sent.

## Permission model

Didit API keys are **application-scoped, not role-scoped**. An active API key for an
application can call every `/v3/users/*` endpoint for that application, including
`delete`; there is no per-role narrowing on this path.

Roles are a Console concept: the `users` permission resource and its `list` / `read` /
`create` / `update` / `update-status` / `delete` claims decide what a *person* can do in
the Console, and they are not evaluated for Management API traffic. See
[Roles & permissions](/console/roles-permissions) for that matrix.

Treat the key itself as the control: issue a separate application for anything that must
not be able to delete users, and restrict who can read each application's key.

## Rate limits and idempotency

* All `/v3/users/*` endpoints are subject to the standard [rate limits](/integration/rate-limiting).
* `create` is **not** idempotent — retrying with the same `vendor_data` returns a conflict. De-dupe on your side, or always `GET` first.
* `delete` is idempotent — deleting an already-deleted user is a no-op.

## Webhooks fired by these operations

| Operation       | Webhook                                                                                                                     |
| --------------- | --------------------------------------------------------------------------------------------------------------------------- |
| `create`        | none for the create call itself — the first `user.data.updated` arrives when a session or an update first fills the profile |
| `update`        | `user.data.updated` (with `changed_fields`)                                                                                 |
| `update-status` | `user.status.updated`                                                                                                       |
| `delete`        | none — record the deletion on your own side if you need to react to it                                                      |

## Next steps

<CardGroup>
  <Card title="Data model" icon="database" href="/entities/users/data-model">
    Full field reference.
  </Card>

  <Card title="List API" icon="list" href="/management-api/users/list">
    GET /v3/users/ schema.
  </Card>

  <Card title="Create API" icon="plus" href="/management-api/users/create">
    POST /v3/users/create/ schema.
  </Card>

  <Card title="Upload face" icon="face-viewfinder" href="/management-api/users/upload-face">
    Attach imported face images to User profiles.
  </Card>
</CardGroup>


# Users (Vendor Entities)
Source: https://docs.didit.me/entities/users/overview

Vendor Users are Didit's persistent identity record — KYC history, biometrics, documents, transactions, and blocklist status, all on one profile.

A **User entity** represents a single individual (your customer, end-user, or applicant) across every verification, transaction, and compliance interaction they have with your platform on Didit.

Once a User exists, all activity tied to the same `vendor_data` flows into the same profile — you get a single pane of glass for identity, risk, and compliance for each person.

## What lives on a User

| Category               | Fields / objects                                                                              |
| ---------------------- | --------------------------------------------------------------------------------------------- |
| **Identity**           | `vendor_data`, `uuid`, `display_name`, `full_name`, `date_of_birth`, `portrait_image`         |
| **Status**             | `ACTIVE`, `FLAGGED`, `BLOCKED`                                                                |
| **Session aggregates** | `session_count`, `approved_count`, `declined_count`, `in_review_count`, `features` map        |
| **Verified contact**   | `approved_emails[]`, `approved_phones[]`                                                      |
| **Geography**          | `issuing_states[]` (from verified ID documents)                                               |
| **Activity**           | `first_session_at`, `last_session_at`, `last_activity_at`                                     |
| **Biometrics**         | Attached face records (for search / duplicate detection / blocklist)                          |
| **Documents**          | ID documents, proofs of address, selfies from sessions                                        |
| **Relations**          | Linked Business entities (if the user is a director / UBO of businesses verified on your app) |
| **Metadata**           | Arbitrary JSON for your own data                                                              |

See the full [User data model](/entities/users/data-model) for types, indexes, and edge cases.

## When a User is created

<Steps>
  <Step title="Automatically — on first session with a new vendor_data">
    The typical case. You call `POST /v3/session/` with a `vendor_data` value Didit has never seen. A User entity is created in `ACTIVE` status and linked to that session.
  </Step>

  <Step title="Explicitly — via POST /v3/users/create/">
    You pre-create the User before any session runs. Useful for seeding metadata, setting initial status, or bulk-onboarding customers from an existing database.
  </Step>

  <Step title="From the console">
    A compliance operator creates the User from the Users page — for example, when onboarding a manually verified customer.
  </Step>
</Steps>

## What you can do

| Operation                                                     | How                                                   |
| ------------------------------------------------------------- | ----------------------------------------------------- |
| [List users](/entities/users/operations#list)                 | `GET /v3/users/` with filters (status, date, country) |
| [Get user](/entities/users/operations#get)                    | `GET /v3/users/{vendor_data}/`                        |
| [Create user](/entities/users/operations#create)              | `POST /v3/users/create/`                              |
| [Update profile](/entities/users/operations#update)           | `PATCH /v3/users/{vendor_data}/`                      |
| [Change status](/entities/users/operations#change-status)     | `PATCH /v3/users/{vendor_data}/update-status/`        |
| [Delete users](/entities/users/operations#delete)             | `POST /v3/users/delete/` (batch)                      |
| [Attach / search faces](/entities/users/faces-and-biometrics) | Console + Lists API for blocklists                    |
| [View documents](/entities/users/documents)                   | Via session decisions                                 |
| [Add to blocklist](/entities/users/blocklist)                 | Console + Lists API                                   |
| [Review KYC history](/entities/users/kyc-history)             | `GET /v3/sessions?vendor_data=...`                    |
| [Review transactions](/entities/users/transactions)           | `GET /v3/transactions/?vendor_data=...`               |
| [Import / export](/entities/users/import-export)              | Console only (CSV)                                    |
| [Manage in console](/entities/users/console)                  | Full UI walkthrough                                   |

## Users and Businesses

A single User can be linked to one or more Businesses — for example, when the same person is a director of one company and a UBO of another. Didit preserves these links automatically when [KYB](/business-verification/overview) identifies people from company registries.

## User ↔ session relationship

```mermaid theme={null}
flowchart LR
    U[User entity<br/>vendor_data = user-42]
    S1["User Verification (KYC) session #1<br/>(approved 2025-01)"]
    S2["User Verification (KYC) session #2<br/>(resubmit, in review)"]
    S3["User Verification (KYC) session #3<br/>(re-verification 2026-01)"]
    S1 --> U
    S2 --> U
    S3 --> U
```

The User aggregates the **latest** state of each feature across all sessions. A failed `aml` check on the most recent session will show up in the User's `features.aml` field even if older sessions approved.

## Next steps

<CardGroup>
  <Card title="Data model" icon="database" href="/entities/users/data-model">
    Every field, type, and index.
  </Card>

  <Card title="Operations" icon="gear" href="/entities/users/operations">
    Create, update, change status, delete.
  </Card>

  <Card title="Faces & biometrics" icon="face-viewfinder" href="/entities/users/faces-and-biometrics">
    Attach a face for search and blocklisting.
  </Card>

  <Card title="Blocklist" icon="ban" href="/entities/users/blocklist">
    How blocklisting works for users.
  </Card>

  <Card title="KYC history" icon="clock-rotate-left" href="/entities/users/kyc-history">
    Every session tied to the user.
  </Card>

  <Card title="Console" icon="desktop" href="/entities/users/console">
    Full Users UI walkthrough.
  </Card>
</CardGroup>


# User Transactions
Source: https://docs.didit.me/entities/users/transactions

Retrieve a User entity's full transaction history and see how Didit aggregates ongoing activity into Transaction Monitoring rules. Pay-per-call from $0.02.

Every transaction you submit with a `vendor_data` identifier (either as applicant or counterparty) is linked to the corresponding User entity. The User profile becomes a running ledger of the person's activity, and Transaction Monitoring uses this history to feed velocity and behavioral rules.

## Retrieving a user's transactions

Filter the Transactions list by `vendor_data`:

```bash theme={null}
curl -G https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  --data-urlencode "vendor_data=user-42" \
  --data-urlencode "page_size=50"
```

Returns every transaction where the user is the applicant. For counterparty-side history, filter in the Business Console (the public list endpoint filters by applicant only).

## How transactions link to users

```mermaid theme={null}
flowchart LR
    T["Transaction<br/>txn_id=tx-0001"]
    A["applicant:<br/>vendor_data=user-42"]
    C["counterparty:<br/>vendor_data=user-99"]
    U1[User: user-42]
    U2[User: user-99]
    T --> A
    T --> C
    A -.-> U1
    C -.-> U2
```

Every transaction includes up to four parties (applicant, remitter, beneficiary, counterparty). When a party includes `vendor_data`, Didit binds it to that User. Parties without `vendor_data` are stored as external snapshots (no entity link).

See [submitting transactions](/transaction-monitoring/transactions) for the full party model.

## Aggregated risk signals

Transactions feed the following user-level signals:

| Signal                                 | Used by                      |
| -------------------------------------- | ---------------------------- |
| Total volume inbound / outbound        | Velocity rules, thresholding |
| Transaction count in a time window     | Velocity rules               |
| Unique counterparties                  | Behavioral rules             |
| High-risk jurisdictions touched        | Geography rules              |
| Sanctioned / PEP counterparty exposure | Screening rules              |
| Payment method variety                 | Fraud rules                  |

These signals are computed in real time and evaluated against your active [transaction rules](/transaction-monitoring/rules). When a rule matches, the user can be moved to `FLAGGED` or `BLOCKED` automatically depending on the rule's action.

## How rules act on users

A transaction rule's `actions` can include:

* `add_score` — increases the transaction's risk score.
* `change_status` — sets the transaction's status (`IN_REVIEW`, `DECLINED`, `AWAITING_USER`).
* `add_tags` — tag the transaction.
* `add_to_list` — add the user's `vendor_data` to a blocklist or custom list.

When a rule adds the user to a blocklist, their User entity is transitioned to `BLOCKED` and a `user.status.updated` webhook fires.

## Monitoring a user's behavior

Use the Transactions tab on the User detail page in the Business Console to:

* See every transaction in chronological order.
* Filter by status, amount, direction, counterparty.
* Open any transaction to inspect rule runs, IP enrichment, and crypto screening results.
* Open a case against the user to track an investigation.

## Remediation sessions

When a transaction enters `AWAITING_USER`, Didit creates a linked **remediation session** that requires the user to complete additional verification (for example, source of funds documentation, refreshed ID). The remediation session is tied to the same `vendor_data` — on completion, the transaction's status updates automatically.

See [transaction statuses](/transaction-monitoring/statuses) for the full state machine.

## Historical ingestion

To backfill historical transactions against an existing User entity, pass `txn_date` in the past:

```bash theme={null}
curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "txn_id": "legacy-0001",
    "txn_date": "2024-03-15T10:00:00Z",
    "direction": "INBOUND",
    "amount": "2500.00",
    "currency": "EUR",
    "applicant": { "vendor_data": "user-42" },
    "counterparty": { "name": "Historic payer" }
  }'
```

<Note>
  Historical transactions still run through the rule engine. If you want to ingest history **without** triggering rules, use the console import flow which supports a "dry ingest" mode.
</Note>

## Next steps

<CardGroup>
  <Card title="Submit transactions" icon="arrow-right-to-bracket" href="/transaction-monitoring/transactions">
    Full payload reference.
  </Card>

  <Card title="Rules" icon="scale-balanced" href="/transaction-monitoring/rules">
    How rules evaluate transactions and act on users.
  </Card>

  <Card title="Statuses" icon="list-check" href="/transaction-monitoring/statuses">
    Transaction and remediation status reference.
  </Card>
</CardGroup>


# Vendor Data Linking
Source: https://docs.didit.me/entities/vendor-data-linking

The vendor_data identifier links your system to Didit — binding sessions, transactions, and User/Business entities into one profile. Pay-per-call.

<AgentPromptAccordion title="Vendor Data Linking Prompt" />

`vendor_data` is the identifier you supply on every session and transaction to link it to a [User](/entities/users/overview) or [Business](/entities/businesses/overview) entity. It is the single most important field for entity aggregation — get it right and every downstream feature (profile history, transaction monitoring, blocklist enforcement, ongoing AML) works seamlessly.

## What it is

`vendor_data` is a **string** you choose. Didit treats it as an opaque identifier and does not interpret its contents. Typical values:

| Your system            | Good `vendor_data` values                  |
| ---------------------- | ------------------------------------------ |
| Internal user database | `user_1234`, `uuid-v4` of the user         |
| Customer-facing ID     | `CUST-2026-00042`, hashed email            |
| Multi-tenant SaaS      | `tenant_acme:user_1234`                    |
| B2B platform           | `company-hq-global`, `tax-id-US-123456789` |

<Warning>
  Do **not** put PII (emails, phone numbers, raw tax IDs) directly in `vendor_data`. Hash or prefix them. `vendor_data` appears in webhook payloads and is persisted indefinitely while the entity exists.
</Warning>

## How it binds things together

```mermaid theme={null}
flowchart TD
    subgraph YourSystem["Your system"]
      Customer["Customer record: user-42"]
    end
    subgraph Didit["Didit platform"]
      Entity["User entity (vendor_data = user-42)"]
      S1[Session #1]
      S2[Session #2]
      T1[Transaction #1]
      T2[Transaction #2]
      F[Face biometric]
    end
    Customer -.vendor_data.-> Entity
    S1 --> Entity
    S2 --> Entity
    T1 --> Entity
    T2 --> Entity
    F --> Entity
```

When you submit a session or transaction with a `vendor_data` value:

1. Didit looks up the entity in your application with that `vendor_data`.
2. If it exists, the new object is linked to that entity.
3. If it does not exist, Didit creates the entity (with `status: ACTIVE`) and links the new object.

This is true for:

* `POST /v3/session/` — KYC and Business Verification (KYB) sessions
* `POST /v3/transactions/` — transactions (for both applicant and counterparty)
* The `applicant.vendor_data` / `counterparty.vendor_data` fields inside transaction payloads

## Uniqueness and scope

`vendor_data` is **unique per application**, not globally across Didit:

| Scope                                    | Uniqueness guarantee                                                                          |
| ---------------------------------------- | --------------------------------------------------------------------------------------------- |
| Within one application                   | `vendor_data` is unique per entity type (User and Business are separate namespaces)           |
| Across applications in your organization | `vendor_data` is **not** shared — the same value in two apps refers to two different entities |
| Across organizations                     | Not shared — every organization has its own entity tables                                     |

This means you can use the same `vendor_data` in a staging app and a production app without collisions, and you can have a User `user-42` and a Business `user-42` without collision (though this is discouraged for clarity).

## What happens if you omit `vendor_data`

You can create a session without `vendor_data`. In that case:

* No entity is created for the session.
* The session is orphaned — it won't appear in any User or Business profile.
* You cannot later look up the session by `vendor_data` — only by `session_id`.

Use this pattern only for anonymous or one-off verifications where no entity aggregation is needed. For every integration that involves re-verification, transactions, or ongoing monitoring, always provide `vendor_data`.

## Example: pre-create an entity, then run sessions

```bash theme={null}
# 1. Pre-create the User with initial metadata
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "tier": "premium", "signup_date": "2026-04-01" }
  }'

# 2. Create a User Verification (KYC) session for the same user
curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "wf_kyc_standard",
    "vendor_data": "user-42"
  }'

# 3. Later, submit a transaction tied to the same user
curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "txn_id": "tx-0001",
    "direction": "OUTBOUND",
    "amount": "500.00",
    "currency": "EUR",
    "applicant": { "vendor_data": "user-42" },
    "counterparty": { "name": "Acme Corp" }
  }'
```

All three calls are linked to the same User entity. When you later `GET /v3/users/user-42/`, you'll see the session count, approved/declined counters, linked transactions, and latest profile data.

## Migrating external IDs

If you're adopting Didit after an existing KYC vendor, pass your existing stable user IDs as `vendor_data` from day one. This makes it easy to:

* Reconcile Didit data with your internal database.
* Bulk-load historical users via console CSV import before running any sessions.
* Preserve relationships when you later migrate to Didit for transaction monitoring.

## Rules, conventions, and best practices

| Rule                                                               | Why                                                                |
| ------------------------------------------------------------------ | ------------------------------------------------------------------ |
| Choose one canonical identifier per entity and never change it     | Changes create a new entity and orphan history                     |
| Prefix `vendor_data` values by entity type (`user_...`, `biz_...`) | Prevents accidental collisions between namespaces in your own code |
| Keep `vendor_data` case-sensitive stable                           | Didit does not normalize case                                      |
| Keep `vendor_data` length under 128 chars                          | Fits comfortably in database indexes                               |
| Never expose raw PII                                               | `vendor_data` appears in webhooks, audit logs, and API responses   |

## Next steps

<CardGroup>
  <Card title="Users overview" icon="user" href="/entities/users/overview">
    Deep dive on User entities and operations.
  </Card>

  <Card title="Businesses overview" icon="building" href="/entities/businesses/overview">
    Deep dive on Business entities and operations.
  </Card>

  <Card title="Create session" icon="play" href="/sessions-api/create-session">
    Start a verification for a vendor\_data.
  </Card>

  <Card title="Create transaction" icon="arrow-right-to-bracket" href="/management-api/transactions/create">
    Submit a transaction linked to an entity.
  </Card>
</CardGroup>


# Entity Webhooks
Source: https://docs.didit.me/entities/webhooks

Real-time webhooks for Didit User and Business entity changes — status transitions, profile updates, and activity log events. Pay-per-call.

<AgentPromptAccordion title="Entity Webhooks Prompt" />

Every change to a User or Business entity emits a webhook so your system can react in real time. Use entity webhooks to sync profile data, propagate blocks to other systems, or trigger downstream compliance flows.

## Event catalog

| Event                     | Trigger                                                                                        |
| ------------------------- | ---------------------------------------------------------------------------------------------- |
| `user.status.updated`     | A User entity's status changes (`ACTIVE` ↔ `FLAGGED` ↔ `BLOCKED`)                              |
| `user.data.updated`       | A User entity's profile fields change (name, DOB, portrait, aggregate counters, metadata)      |
| `business.status.updated` | A Business entity's status changes                                                             |
| `business.data.updated`   | A Business entity's profile fields change (legal name, registration number, country, counters) |
| `activity.created`        | A new activity is logged against an entity (manual action, automated check, note)              |

Didit also emits session, transaction, and business-session events that reference entity fields. See:

* [KYB webhooks](/business-verification/webhooks) — business session events
* [Transaction Monitoring webhooks](/transaction-monitoring/webhooks) — transaction events
* [Webhooks reference](/integration/webhooks) — signature verification, retries, destinations

## Payload shapes

All entity webhooks share a common envelope:

```json theme={null}
{
  "event": "user.status.updated",
  "application_id": "app_abc123",
  "timestamp": "2026-04-16T10:00:00Z",
  "data": {
    "vendor_data": "user-42",
    "uuid": "9c7d2a30-2f98-4d4f-9d2d-1a7c4b1e5b6a",
    "status": "BLOCKED",
    "previous_status": "ACTIVE",
    "reason": "session_declined",
    "actor": "system",
    "metadata": { ... }
  }
}
```

### `user.status.updated` / `business.status.updated`

Fires on every status change. The `reason` field tells you why the change happened:

| Reason               | Description                                                               |
| -------------------- | ------------------------------------------------------------------------- |
| `manual`             | An analyst changed the status from the console                            |
| `api`                | The status was changed via `PATCH /v3/users/{vendor_data}/update-status/` |
| `session_declined`   | Linked session was declined and auto-block is enabled                     |
| `blocklist_match`    | Entity matched a blocklist entry (face, document, email, phone)           |
| `transaction_rule`   | A transaction rule action moved the entity to FLAGGED or BLOCKED          |
| `ongoing_monitoring` | Periodic AML rescan surfaced a new hit                                    |

### `user.data.updated` / `business.data.updated`

Fires when profile fields change. The payload includes the full updated entity:

```json theme={null}
{
  "event": "user.data.updated",
  "application_id": "app_abc123",
  "timestamp": "2026-04-16T10:00:00Z",
  "data": {
    "vendor_data": "user-42",
    "uuid": "9c7d2a30-2f98-4d4f-9d2d-1a7c4b1e5b6a",
    "display_name": "Jane Doe",
    "full_name": "John Doe",
    "date_of_birth": "1990-01-01",
    "status": "ACTIVE",
    "session_count": 3,
    "approved_count": 2,
    "declined_count": 0,
    "in_review_count": 1,
    "features": {
      "id_verification": "APPROVED",
      "liveness": "APPROVED",
      "face_match": "APPROVED",
      "aml": "IN_REVIEW"
    },
    "changed_fields": ["full_name", "session_count", "in_review_count", "features"]
  }
}
```

Use `changed_fields` to efficiently sync only the fields that changed.

### `activity.created`

Fires whenever an activity record is created about a User or Business entity. Activities form the entity's timeline — the backend writes one for every material event, across five source categories:

| Source         | Examples                                                                                |
| -------------- | --------------------------------------------------------------------------------------- |
| `CUSTOMER`     | End-user actions (profile edits, Key People submissions)                                |
| `SYSTEM`       | Backend automation (status transitions, ongoing-monitoring rescans, threshold triggers) |
| `VERIFICATION` | KYC / KYB session lifecycle (session created, feature finished, decision rendered)      |
| `TRANSACTION`  | Transaction monitoring events (rule triggers, severity shifts, case openings)           |
| `REVIEW`       | Console reviewer actions (notes, tag changes, status overrides)                         |

Example payload:

```json theme={null}
{
  "event": "activity.created",
  "application_id": "app_abc123",
  "timestamp": "2026-04-18T10:05:00Z",
  "data": {
    "subject_kind": "USER",
    "subject_vendor_data": "user-42",
    "activity_type": "note_added",
    "source": "REVIEW",
    "status": null,
    "title": "Analyst note",
    "description": "Requested additional proof of address",
    "metadata": {},
    "custom_values": {},
    "occurred_at": "2026-04-18T10:05:00Z",
    "session_id": null,
    "business_session_id": null,
    "transaction_id": null
  }
}
```

Key fields:

* `subject_kind` — `USER`, `BUSINESS`, or `EXTERNAL` (a counterparty not registered as one of your entities).
* `subject_vendor_data` — the entity's `vendor_data` when applicable.
* `source` — one of the five categories above.
* `activity_type` — machine-readable type tag (e.g. `note_added`, `status_changed`, `session_completed`, `rule_triggered`).
* `title` / `description` — human-readable summary; safe to render in your timeline UI.
* `session_id`, `business_session_id`, `transaction_id` — FK identifiers when the activity is tied to a specific session or transaction.

Use `activity.created` to mirror the Didit timeline into your own audit / compliance log, trigger follow-up workflows on specific activity types, or power a customer-facing timeline view.

## Delivery, retries, and signing

All entity webhooks follow the standard delivery contract:

* **Signed** with HMAC-SHA256 via the `X-Didit-Signature` header (secret shared key on your destination).
* **Retried** with exponential backoff on non-2xx responses (1s → 2s → 4s → ... up to 5 retries over \~24 hours).
* **Idempotent** — every webhook has a unique `event_id` in the payload; de-dupe on your side.

See [Webhooks reference](/integration/webhooks) for destination setup and signature verification code samples.

## Subscribing

Subscribe to entity events on a webhook destination via the Management API or Business Console:

```bash theme={null}
curl -X POST https://verification.didit.me/v3/webhook/destinations/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "Entity sync",
    "url": "https://yourapp.com/webhooks/didit",
    "subscribed_events": [
      "user.status.updated",
      "user.data.updated",
      "business.status.updated",
      "business.data.updated",
      "activity.created"
    ]
  }'
```

## Next steps

<CardGroup>
  <Card title="Webhooks reference" icon="bolt" href="/integration/webhooks">
    Destinations, signatures, retries, and verification.
  </Card>

  <Card title="Create destination" icon="plus" href="/management-api/webhook/create-destination">
    Register a new webhook endpoint.
  </Card>

  <Card title="User operations" icon="user-pen" href="/entities/users/operations">
    Changes that trigger user webhooks.
  </Card>
</CardGroup>


# AI Agent Skills
Source: https://docs.didit.me/getting-started/agent-skills

Integrate Didit KYC and identity verification into AI agents, Cursor, Claude Code, and ClawHub via single-prompt SDK skills. Agent-native, MCP-ready.

## What are Agent Skills?

Agent Skills are pre-built instruction sets that allow AI coding assistants (like Cursor, GitHub Copilot, Claude, etc.) to integrate Didit's identity verification APIs into your codebase with a single command.

Each skill contains:

* Complete API documentation and endpoint details
* Authentication setup instructions
* Request/response schemas with examples
* Ready-to-use code snippets
* Error handling patterns

***

## Available Skills

| Skill                         | Description                                                                | Install                                     |
| ----------------------------- | -------------------------------------------------------------------------- | ------------------------------------------- |
| **didit-sessions**            | Full session management, workflows, blocklist, and webhooks (11 endpoints) | `clawhub install didit-sessions`            |
| **didit-id-verification**     | ID document verification with OCR and authenticity checks                  | `clawhub install didit-id-verification`     |
| **didit-passive-liveness**    | Deepfake and spoof detection from selfie images                            | `clawhub install didit-passive-liveness`    |
| **didit-face-match**          | 1:1 face comparison between selfie and document photo                      | `clawhub install didit-face-match`          |
| **didit-face-search**         | 1:N face search across previous verifications                              | `clawhub install didit-face-search`         |
| **didit-age-estimation**      | Age estimation from selfie photo                                           | `clawhub install didit-age-estimation`      |
| **didit-aml-screening**       | AML, PEP, and sanctions screening                                          | `clawhub install didit-aml-screening`       |
| **didit-database-validation** | Government database cross-validation                                       | `clawhub install didit-database-validation` |
| **didit-email-verification**  | Email ownership verification via OTP                                       | `clawhub install didit-email-verification`  |
| **didit-phone-verification**  | Phone number verification via SMS/WhatsApp                                 | `clawhub install didit-phone-verification`  |
| **didit-proof-of-address**    | Proof of address document extraction and validation                        | `clawhub install didit-proof-of-address`    |

***

## Quick Install

### Via ClawHub (Recommended)

Install all skills at once:

```bash theme={null}
clawhub install didit-sessions didit-id-verification didit-passive-liveness didit-face-match didit-aml-screening
```

If `clawhub` is not installed globally, use:

```bash theme={null}
npx clawhub@latest install didit-sessions didit-id-verification didit-passive-liveness didit-face-match didit-aml-screening
```

### Via Cursor IDE

Copy skills directly into your project:

```bash theme={null}
# Clone the skills repo
git clone https://github.com/didit-protocol/skills.git

# Copy the skills you need into your project
cp -r didit-agent-skills/skills/didit-sessions .cursor/skills/
cp -r didit-agent-skills/skills/didit-id-verification .cursor/skills/
```

### Via GitHub

Browse and download individual skills from the repository:

<Card title="didit-agent-skills" icon="github" href="https://github.com/didit-protocol/skills">
  All 11 Didit AI Agent Skills — open source on GitHub
</Card>

***

## Setup

All skills require a `DIDIT_API_KEY` environment variable. Some skills require additional variables:

```bash theme={null}
# Required for all skills
export DIDIT_API_KEY="your-api-key-here"

# Required for session-based workflows
export DIDIT_WORKFLOW_ID="your-workflow-id-here"

# Required for webhook signature verification
export DIDIT_WEBHOOK_SECRET="your-webhook-secret-here"
```

Get your API key from the [Business Console](https://business.didit.me) → **API & Webhooks** in the sidebar.

***

## How It Works

Once installed, simply ask your AI assistant to perform verification tasks:

> "Create a verification session for a new user signup"

> "Add ID verification to my Express.js backend"

> "Set up webhook handling for verification status updates"

> "Screen this user against AML/PEP watchlists"

The AI will read the skill documentation and generate production-ready code using Didit's APIs.


# API Authentication
Source: https://docs.didit.me/getting-started/api-authentication

Authenticate Didit identity verification requests with scoped API keys. Pass your secret key via HTTP header. Missing or invalid keys return 401.

<AgentPromptAccordion title="API Authentication Prompt" />

## Finding Your API Key

In Didit, API keys are scoped to a specific **Application** within your account. An Application is a workspace where you can configure workflows and manage verifications for a particular project or environment.

An API key is generated automatically for each Application you create. To find your key:

<Steps>
  <Step title="Log in to the Business Console">
    Go to the [**Didit Business Console**](https://business.didit.me) and sign in.
  </Step>

  <Step title="Select your Application">
    Choose the **Application** you want to work with from the dropdown menu at the top.
  </Step>

  <Step title="Open API & Webhooks">
    Navigate to **API & Webhooks** in the left-hand sidebar.
  </Step>

  <Step title="Copy your keys">
    Your **API Key** and **Webhook Secret Key** will be displayed here. Copy them as needed.
  </Step>
</Steps>

<Warning>
  **Your API Key is a Secret — treat it like a password.**

  It provides full access to the API on behalf of your Application. Never expose it in frontend code, public repositories, or client-side bundles. Always keep it server-side only.
</Warning>

## Find your organization ID

Your **Organization ID** is the UUID that identifies your organization. You use it in organization-scoped API paths such as `/auth/v2/organizations/me/{org_id}/applications/`. You can copy it directly from the Business Console, with no API call needed:

<Steps>
  <Step title="Open organization settings">
    In the [**Didit Business Console**](https://business.didit.me), go to **Organization Settings**.
  </Step>

  <Step title="Copy the organization ID">
    The **Organization ID** field shows your org's UUID next to the organization name, with a copy-to-clipboard button.
  </Step>
</Steps>

***

## Making Authenticated Requests

To authenticate an API request, include your secret API key in the `x-api-key` HTTP header.

Here is an example of an authenticated request to the `Create Session` endpoint:

```shell cURL theme={null}
curl --request POST \
     --url https://verification.didit.me/v3/session/ \
     --header 'accept: application/json' \
     --header 'content-type: application/json' \
     --header 'x-api-key: YOUR_API_KEY' \
     --data '
{
  "workflow_id": "WORKFLOW_ID",
  "vendor_data": "USER_ID",
  "callback": "CALLBACK_URL"
}
'
```

***

## Error Handling

If your API key is missing or invalid, the API returns a `401 Unauthorized` response:

```json theme={null}
{
  "detail": "Invalid or missing API key"
}
```

| Status Code | Meaning                                                |
| ----------- | ------------------------------------------------------ |
| **401**     | API key is missing, invalid, or revoked                |
| **403**     | API key does not have access to the requested resource |

<Tip>
  If you receive a `401` error, double-check that you are using the correct API key for the right Application and that it has not been regenerated.
</Tip>


# Certifications & attestations
Source: https://docs.didit.me/getting-started/certifications

Every certification, audit, and regulatory attestation Didit holds: SOC 2 Type 2, ISO 27001, iBeta Level 1, FSM youth protection, Spain's Tesoro/SEPBLAC validation, EBA/MiCA legal opinion, and GDPR.

Didit's security and compliance posture is verified by independent auditors, accredited laboratories, and financial regulators — not self-declared. This page lists every credential we hold today. Reports and certificates are available from the [Security & Compliance center](https://didit.me/security-compliance/), directly in this page's cards, or from your Didit representative.

## At a glance

| Credential                    | Framework / issuer                             | Status                                                    |
| ----------------------------- | ---------------------------------------------- | --------------------------------------------------------- |
| SOC 2 Type 2                  | AICPA Trust Services Criteria                  | Issued July 30, 2026 (March–July 2026 observation period) |
| SOC 2 Type 1                  | AICPA Trust Services Criteria                  | Issued April 9, 2026                                      |
| ISO/IEC 27001:2022            | Accredited certification body                  | Valid through June 3, 2027                                |
| ISO/IEC 27017 & 27018         | Cloud security & cloud privacy extensions      | Active                                                    |
| iBeta Level 1 PAD             | ISO/IEC 30107-3, NIST-accredited lab           | Passed — zero successful attacks                          |
| FSM Jugendschutz geprüft      | FSM (Germany), Section 4(2) JMStV              | Certified June 29, 2026                                   |
| Regulator attestation (Spain) | Tesoro Público, Banco de España, SEPBLAC, CNMV | Concluded July 2025                                       |
| EBA / MiCA compatibility      | Independent legal opinion                      | Current                                                   |
| GDPR (EU 2016/679)            | Data processor, Article 32 measures            | Compliant                                                 |

## Audits & certifications

<CardGroup>
  <Card title="SOC 2 Type 2" icon="shield-halved">
    **Controls proven in operation.** An independent audit under the AICPA Trust Services Criteria confirmed that Didit's security, availability, and confidentiality controls **operated effectively over the March–July 2026 observation period** — not just that they exist on paper. Issued July 30, 2026. Report available under NDA.
  </Card>

  <Card title="SOC 2 Type 1" icon="shield">
    **Control design verified.** The point-in-time audit of the design of Didit's security, availability, and confidentiality controls that preceded the Type 2 observation period. Issued April 9, 2026.
  </Card>

  <Card title="ISO/IEC 27001:2022" icon="shield-check">
    **Certified information-security management.** Didit's Information Security Management System covers the verification platform end to end — design, development, and operation. Valid through June 3, 2027; certificate excerpts available on request.
  </Card>

  <Card title="ISO/IEC 27017 & 27018" icon="cloud">
    **Cloud security and cloud privacy.** Extended cloud-specific controls (27017) and dedicated protections for personally identifiable information in cloud environments (27018) that build on the ISO 27001 certification.
  </Card>

  <Card title="iBeta Level 1 — ISO/IEC 30107-3" icon="face-smile">
    **Biometric anti-spoofing, lab-tested.** A NIST-accredited laboratory ran 360 presentation attacks across six attack categories against Didit's liveness detection — printed photos, screen replays, masks, and more. **Zero got through.**
  </Card>

  <Card title="FSM Jugendschutz geprüft" icon="child-reaching">
    **German youth-protection certification.** Germany's youth-protection self-regulator (FSM) certified that Didit's Age Verification System reliably establishes a **closed user group under Section 4(2) JMStV** — so only verified adults reach age-restricted content. Certified June 29, 2026.
  </Card>

  <Card title="Spanish regulator attestation" icon="landmark">
    **Safer than in-person, per financial regulators.** After a year-long supervised test (November 2024 – July 2025), Spain's Tesoro Público, Banco de España, SEPBLAC, and CNMV concluded Didit's NFC + liveness verification is **at least as safe as in-person ID checks** under anti-money-laundering rules — the only provider with this validation.
  </Card>

  <Card title="EBA / MiCA compatibility" icon="scale-balanced">
    **Remote onboarding, regulator-grade.** An independent legal opinion confirms Didit's remote onboarding meets the EBA Remote Customer Onboarding Guidelines (EBA/GL/2022/15) and is compatible with the EU AML Single Rulebook and MiCA. Memo available on request.
  </Card>

  <Card title="GDPR" icon="lock">
    **EU data protection, processor role.** Didit operates as your data processor with Article 32 technical and organizational measures: AES-256 at rest, TLS 1.3 in transit, EU-default data residency, configurable retention, and erasure via API. DPA and TOMs available on request.
  </Card>
</CardGroup>

<Info>
  We add new certifications all the time. If your compliance team needs a specific certification, framework, or attestation that isn't listed here, [book a demo](https://didit.me/get-a-demo/) and tell us — we'll walk you through our roadmap and what we can provide today.
</Info>

## Related resources

<CardGroup>
  <Card title="Security & Compliance" icon="shield-check" href="/getting-started/security-compliance">
    The full security posture: encryption, data protection, fraud signals, and the security FAQ.
  </Card>

  <Card title="Security & Compliance center" icon="globe" href="https://didit.me/security-compliance/">
    Download reports, certificates, and assessments from the public trust center.
  </Card>
</CardGroup>


# Platform Comparison
Source: https://docs.didit.me/getting-started/competition-analysis

Feature and pricing comparison: Didit vs Sumsub, Veriff, Onfido, Persona. Pay-per-use pricing, 500 free checks/month, no contracts, no minimums.

This page provides a factual comparison between Didit and other identity verification providers. All pricing data is sourced from public pages where available.

***

## Feature Comparison

| Feature                         |     Didit     | Sumsub |  Veriff |  Persona |  Onfido  |  Others |
| ------------------------------- | :-----------: | :----: | :-----: | :------: | :------: | :-----: |
| ID Verification                 |       ✅       |    ✅   |    ✅    |     ✅    |     ✅    |    ✅    |
| NFC Verification                |       ✅       |    ✅   |    ✅    |    ⚠️    |     ✅    |    ❌    |
| Passive Liveness                |       ✅       |    ✅   |    ✅    |     ✅    |     ✅    |    ✅    |
| Active Liveness                 |       ✅       |    ✅   |    ✅    |     ✅    |     ✅    |    ⚠️   |
| Reusable KYC                    |       ✅       |    ✅   |    ❌    |     ❌    |     ❌    |    ❌    |
| Face Match 1:1                  |       ✅       |    ✅   |    ✅    |     ✅    |     ✅    |    ✅    |
| AML Screening                   |       ✅       |    ✅   |    ✅    |     ✅    |     ✅    |    ⚠️   |
| AML Ongoing Monitoring          |       ✅       |    ✅   |    ✅    |     ✅    |     ✅    |    ⚠️   |
| Proof of Address                |       ✅       |    ✅   |    ✅    |     ✅    |     ✅    |    ❌    |
| Age Estimation                  |       ✅       |    ✅   |    ✅    |     ✅    |     ❌    |    ❌    |
| Phone Verification              |       ✅       |    ✅   |    ❌    |     ✅    |     ✅    |    ❌    |
| Device & IP Analysis            |       ✅       |    ✅   |    ✅    |     ✅    |     ✅    |    ❌    |
| White Label                     |       ✅       |    ✅   |    ✅    |     ❌    |     ❌    |    ❌    |
| Blocklisting / Duplicated Faces |       ✅       |    ✅   |    ✅    |    ⚠️    |     ✅    |    ❌    |
| Database Validation             |       ✅       |    ✅   |    ⚠️   |    ⚠️    |    ⚠️    |    ❌    |
| Data Retention                  | **Unlimited** |   N/A  | 90 days | 180 days | 365 days | 90 days |
| Instant Sandbox Access          |       ✅       |   ⚠️   |    ⚠️   |    ⚠️    |     ❌    |    ❌    |
| Public API Docs                 |       ✅       |   ⚠️   |    ❌    |     ❌    |     ❌    |    ❌    |
| Public Pricing                  |       ✅       |   ⚠️   |    ⚠️   |     ❌    |     ❌    |    ❌    |

<Tip>
  ✅ = Fully supported · ⚠️ = Partial / limited / requires upgrade · ❌ = Not available
</Tip>

***

## Pricing Comparison

All prices are per verification. Data from public pricing pages.

| Metric                |  Didit  | Sumsub | Veriff | Ondato | Persona | Others |
| --------------------- | :-----: | :----: | :----: | :----: | :-----: | :----: |
| **Annual Commitment** |  **No** |   Yes  |   Yes  |   Yes  |   Yes   |   Yes  |
| **Minimum Monthly**   | **\$0** |  \$149 |  \$209 |  \$666 |  \$500¹ | \$250¹ |

**Price per verification:**

| Verification Type                                |    Didit    | Sumsub |  Veriff | Ondato | Persona |  Others |
| ------------------------------------------------ | :---------: | :----: | :-----: | :----: | :-----: | :-----: |
| ID + Passive Liveness + Face Match + IP Analysis | **\$0.33**² | \$1.35 |  \$1.39 | \$1.64 | \$1.50¹ | \$1.50¹ |
| AML + Ongoing Monitoring                         | **\$0.27**² | \$0.57 |  \$1.03 | \$0.90 | \$0.57¹ | \$0.57¹ |
| Phone Verification                               | **\$0.10**² | \$0.28 | \$0.28¹ | \$0.33 | \$0.28¹ | \$0.28¹ |
| Proof of Address                                 | **\$0.20**² | \$1.35 | \$1.35¹ | \$0.70 | \$1.35¹ | \$1.35¹ |

<Note>
  ¹ Estimated when official pricing is not publicly available.

  ² Didit offers a **Free Tier**: 500 free checks/month per feature for ID Verification, Passive Liveness, Face Match, and Device & IP Analysis. Prices shown apply after the free tier is exhausted.

  "Others" represents the average of smaller or regional providers (Ondato, Truora, Trulioo, iDWall, UniCo, etc.).
</Note>

***

## Key Differentiators

| Area                 | Didit                                                                                                                                               | Legacy Providers                                       |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------ |
| **Pricing model**    | Prepaid credits, pay-per-success, no expiry, no minimums                                                                                            | Annual contracts, tiered plans, volume commitments     |
| **Core KYC cost**    | **Free tier**: 500 checks/month per feature for IDV, Passive Liveness, Face Match, Device & IP Analysis. After free tier: \$0.33 per full KYC check | Bundled in paid plans starting at \$1.35+/verification |
| **Flexibility**      | Modular no-code workflow builder, use only what you need                                                                                            | Predefined bundles, limited per-feature control        |
| **Developer access** | Instant sandbox, public API docs, self-service onboarding                                                                                           | Often requires sales contact for sandbox access        |
| **Data retention**   | Unlimited, configurable from 1 month to indefinite                                                                                                  | Typically 90–365 days                                  |
| **Open APIs**        | Full public API documentation, standalone APIs for each feature                                                                                     | Often gated behind sales, limited standalone access    |

***

**Sources:**
[Didit](https://didit.me/pricing) |
[Sumsub](https://sumsub.com/pricing/) |
[Veriff](https://www.veriff.com/plans/self-serve) |
[Persona](https://withpersona.com/pricing) |
[Ondato](https://ondato.com/identity-verification-pricing/)

<Card title="Detailed Pricing" icon="money-bill" href="/getting-started/pricing">
  See feature-by-feature pricing, free tier details, and credit packages.
</Card>


# Database Validation Pricing
Source: https://docs.didit.me/getting-started/database-validation-pricing

Verify identity against government databases by country. Transparent per-query pricing for 1x1 and 2x2 matching. Pay-per-call, no contracts or minimums.

Database Validation verifies user data against **government and authoritative databases**. Each country exposes one or more **services**, and pricing is set per service.

<Note>
  You are charged for each **successful query** based on the selected country and service. Pricing below is the default per-query rate; volume discounts available.
</Note>

<Warning>
  **Database Validation is not covered by the free tier.** The [500 free checks per month](/getting-started/pricing) apply to ID Verification, Passive Liveness, Face Match 1:1 and Device & IP Analysis only. Every successful Database Validation query is billed from the first one, inside a workflow and through the standalone API alike.
</Warning>

The table below is the authoritative rate for every service. Rates are set **per service**, not per country, and they follow what the underlying source charges — most services cost under **\$1.00**, but some authoritative registries cost considerably more (Kenya National ID, `ken_national_id`, is **\$3.15**, and the most expensive specialist sources reach **\$7.00**). Budget a country from its own row rather than from a headline range.

## What counts as a billable query

You are charged once per **service**, per query the source actually answered — not per session, and not per country. A session that runs two services against the same person is two charges.

The rule behind the table: **you pay for the registry answering, not for the answer being the one you hoped for.** The only free queries are the ones that never reached the source, and the ones the source never answered. Every row below is keyed on the `outcome_code` the service returns.

| Outcome                                                                                                                                                                                                                                                   | Billed?                                                                                                                                                                                                                                                                            |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `MATCH`, `PARTIAL_MATCH`, `DOCUMENT_SUPERSEDED`                                                                                                                                                                                                           | Yes — the registry found the record and answered on the data you submitted.                                                                                                                                                                                                        |
| `NO_MATCH`, `DOCUMENT_NOT_FOUND`, `BIOMETRIC_NO_MATCH`, `DECEASED`, `MINOR_BLOCKED`                                                                                                                                                                       | Yes. "No record" is a real answer, and it is the answer you are paying the registry for.                                                                                                                                                                                           |
| `INCONCLUSIVE`, `BIOMETRIC_IMAGE_UNUSABLE`                                                                                                                                                                                                                | Yes — the registry answered, even though the answer confirms nothing about the person.                                                                                                                                                                                             |
| `INVALID_DOCUMENT_FORMAT`, `INVALID_INPUT`                                                                                                                                                                                                                | Yes — as an `outcome_code`, these mean the **registry itself** rejected the data it was sent (Argentina RENAPER detail `300` / `303`, Brazil's `CPF inválido`). The query went out and came back. Input rejected *before* a query is sent is the next-to-last row, and it is free. |
| `REGISTRY_UNAVAILABLE`, `REGISTRY_ERROR`                                                                                                                                                                                                                  | **No** — the source never answered, so there is nothing to charge for.                                                                                                                                                                                                             |
| Nothing was sent to the registry: `POST /v3/database-validation/` rejected the request with `400` because it failed the country format rules, or a workflow service was skipped for missing or malformed fields (`COULD_NOT_PERFORM_DATABASE_VALIDATION`) | **No** — no query is sent, so no `outcome_code` is produced either.                                                                                                                                                                                                                |
| Service skipped because the document does not carry the identifier (`DATABASE_VALIDATION_NOT_APPLICABLE`)                                                                                                                                                 | **No** — no query is sent.                                                                                                                                                                                                                                                         |

See [Outcome Codes](/core-technology/database-validation/database-validation-outcome-codes) for the full taxonomy and [Warnings](/core-technology/database-validation/database-validation-warnings) for the skip cases.

## Pricing by Country

<DbValidationPricingTable />

***

## Need a Country Not Listed?

We're continuously expanding our coverage. [Contact us](https://didit.me/contact) if you need database validation for a country not listed above.

→ Back to [Main Pricing Page](/getting-started/pricing)


# Features
Source: https://docs.didit.me/getting-started/features

Authentication, KYC, KYB, and post-onboarding monitoring on one programmable platform. 22 metered modules, pay-per-success, 500 free checks/month.

Didit is **infrastructure for identity and fraud**. Every module below maps to one of three lifecycle stages — **Authentication** (is this user real and present right now), **Verification** (are they who they say they are), and **Monitoring** (stay on top of risk after onboarding). Use any module standalone, or compose them into a workflow in the [Workflow Orchestrator](/console/workflows).

This chapter of the Didit Academy introduction picks up at the three products in one customer lifecycle.

The first Academy lesson explains at 2:11 how the product lines share one customer lifecycle. That map is the context for the full feature list below.

<VideoEmbed title="The three products, one customer lifecycle — Didit Academy" />

<SectionHeader label="Authentication" title={<>Is this user <span>real and present</span> right now?</>} description="Biometric checks that confirm the person behind the screen is alive, present, and the same human you verified the first time." />

<FeatureGrid>
  <FeatureCard icon="video" title="Passive Liveness" description="Frictionless anti-spoofing from a single selfie. Detects printed photos, screen replay, and deepfakes. iBeta Level 1 PAD." href="/core-technology/liveness/overview" />

  <FeatureCard icon="hand" title="Active Liveness" description="3D Action or Flashing challenges for the highest assurance level. Stops sophisticated presentation attacks." href="/core-technology/liveness/overview" />

  <FeatureCard icon="user-check" title="Face Match (1:1)" description="Compare a live selfie to the portrait on the ID document. Returns a similarity score with anti-spoofing." href="/core-technology/face-match/overview" />

  <FeatureCard icon="users" title="Face Search (1:N)" description="Search a face against your entire database of verified users. Detect duplicate accounts and blocklisted faces." href="/core-technology/face-search/overview" />

  <FeatureCard icon="fingerprint" title="Biometric Authentication" description="Passwordless re-authentication using face biometrics. Match a live selfie against a stored template — sign-in, step-up, recovery." href="/core-technology/biometric-auth/overview" />

  <FeatureCard icon="cake-candles" title="Age Estimation" description="Estimate user age from a selfie with built-in passive liveness. Ideal for age-restricted content and UK OSA compliance." href="/core-technology/age-estimation/overview" />
</FeatureGrid>

<SectionHeader label="Verification" title={<>Are they <span>who they say they are</span>?</>} description="One-time onboarding checks for individuals (KYC) and businesses (KYB). Both are forms of verification — the same lifecycle stage, the same workflow surface." />

### KYC — User Verification

<FeatureGrid>
  <FeatureCard icon="id-card" title="ID Verification" description="AI-powered OCR across 14,000+ document types in 220+ countries. Extracts personal data, validates authenticity, and detects tampering." href="/core-technology/id-verification/overview" />

  <FeatureCard icon="microchip" title="NFC Reading" description="Read cryptographic data directly from e-passport and e-ID chips for the highest assurance level." href="/core-technology/nfc-verification/overview" />

  <FeatureCard icon="house" title="Proof of Address" description="Verify utility bills, bank statements, and government letters with AI-powered document analysis." href="/core-technology/proof-of-address/overview" />

  <FeatureCard icon="database" title="Database Validation" description="Validate identity data against government registries and credit bureaus in 60+ countries, including biometric face-match via national databases." href="/core-technology/database-validation/overview" />

  <FeatureCard icon="clipboard-list" title="Custom Questionnaires" description="Build custom KYC questionnaires with drag-and-drop. Multi-language, conditional logic, file uploads, scoring." href="/core-technology/questionnaires/overview" />
</FeatureGrid>

### KYB — Business Verification

<FeatureGrid>
  <FeatureCard icon="building" title="Company Registry" description="Pull authoritative company data — legal name, registration number, status, addresses — from official registries worldwide." href="/business-verification/company-data" />

  <FeatureCard icon="shield-check" title="KYB Company AML" description="Screen the entity against global sanctions, PEP, and adverse media lists. Risk score with audit trail." href="/business-verification/aml" />

  <FeatureCard icon="file-lines" title="KYB Documents" description="Collect, OCR, and validate articles of incorporation, proof of registry, and supporting compliance documents." href="/business-verification/documents" />

  <FeatureCard icon="people-arrows" title="KYB Key People" description="Resolve UBOs and officers, then trigger a linked KYC session for each one — closed-loop, unique, no duplicates." href="/business-verification/key-people" />
</FeatureGrid>

### Shared signals — apply to KYC and KYB

<FeatureGrid>
  <FeatureCard icon="scale-balanced" title="AML Screening" description="Real-time screening against 1,300+ global sanctions, PEP, adverse media, and watchlist databases with two-score risk." href="/core-technology/aml-screening/overview" />

  <FeatureCard icon="envelope" title="Email Verification" description="Send OTP codes to email, check for data breaches, disposable providers, and deliverability issues." href="/core-technology/email-verification/overview" />

  <FeatureCard icon="phone" title="Phone Verification" description="Send OTP codes via SMS, WhatsApp, Telegram, RCS, or voice. Detect virtual numbers and disposable phones." href="/core-technology/phone-verification/overview" />
</FeatureGrid>

<SectionHeader label="Monitoring" title={<>Stay on top of <span>risk after onboarding</span></>} description="Continuous checks once the user is in. Transactions are scored in real time, wallets are screened on every flow, and AML status is rechecked daily." />

<FeatureGrid>
  <FeatureCard icon="chart-line" title="Transaction Monitoring" description="Real-time rule engine with 11 seeded bundles, fiat + crypto, case management, SAR workflow, and AWAITING_USER auto-remediation." href="/transaction-monitoring/overview" />

  <FeatureCard icon="link" title="Wallet Screening (KYT)" description="Screen each wallet or transaction hash for $0.15. Review the risk score, source-of-funds exposure, and network relationships." href="/core-technology/wallet-screening/overview" />

  <FeatureCard icon="rotate" title="Ongoing AML" description="Daily re-screening of every onboarded user against global watchlists. $0.07 per user per year." href="/core-technology/aml-screening/continuous-monitoring-aml-screening" />

  <FeatureCard icon="globe" title="Device & IP Analysis" description="Analyse IP addresses for VPN/proxy usage, geolocation mismatch, ASN risk, and Tor exit-node detection." href="/core-technology/ip-analysis/overview" />
</FeatureGrid>

<SectionHeader label="Platform" title={<>Cross-cutting <span>infrastructure</span></>} description="The orchestration, distribution, and AI-agent surface that ties every module together. Free or low-cost extensions of the modules above." />

<FeatureGrid>
  <FeatureCard icon="diagram-project" title="Workflow Orchestrator" description="Visual no-code builder. Conditional branching, A/B testing, nested decisions, one-click module activation. Free." href="/console/workflows" />

  <FeatureCard icon="folder-open" title="Case Management" description="Compliance officer workspace for transaction alerts and AML hits. Notes, SAR drafts, audit trail, role-based access." href="/transaction-monitoring/cases" />

  <FeatureCard icon="palette" title="White Label" description="Ship the verification flow under your own brand. Custom domain, colours, logo, and copy. $0.20 per session." href="/console/white-label" />

  <FeatureCard icon="recycle" title="Reusable KYC" description="Share verification results across partners and applications — users verify once, reuse everywhere. Free." href="/core-technology/reusable-kyc/overview" />

  <FeatureCard icon="robot" title="MCP Server" description="Model Context Protocol server so AI agents can trigger and inspect verifications directly. Free." href="/integration/ai-agent-integration" />
</FeatureGrid>


# Introduction
Source: https://docs.didit.me/getting-started/introduction

Infrastructure for identity and fraud. Pay-per-use pricing, 500 free verifications/month, sub-2s inference, no contracts or minimums.

## The Problem with Legacy Identity Verification

Before Didit, identity verification was built for banks in 2012, not for the internet in 2026:

<FeatureGrid>
  <FeatureCard icon="dollar-sign" title="Punitive pricing models" description="$1–$3 per check, annual contracts, and minimum commitments that crush experimentation and margins." />

  <FeatureCard icon="user" title="Human-in-the-loop by default" description="Manual reviews slow everything down, introduce inconsistency, and don't scale." />

  <FeatureCard icon="eye-slash" title="Opaque pricing & sales-gated access" description="You can't test, benchmark, or ship without going through weeks of sales calls." />

  <FeatureCard icon="code" title="Developer-hostile tooling" description="Poor documentation, fragile SDKs, and integrations that take weeks instead of hours." />

  <FeatureCard icon="box" title="Bundled, inflexible products" description="Forced to buy bloated 'KYC packages' instead of the exact signals you actually need." />

  <FeatureCard icon="robot" title="Not designed for AI-era fraud" description="Legacy systems struggle with deepfakes, replay attacks, synthetic identities, and automated abuse." />
</FeatureGrid>

***

<SectionHeader label="The Solution" title={<>One API for <span>identity and fraud</span></>} />

Didit takes a different shape: infrastructure for identity and fraud that you compose, scale, and control. Every check is a module with a published price. You pick the exact signals you need, wire them into a workflow, and pay only for what runs. You see every price up front and choose every module yourself.

The first Academy lesson is the fastest tour of the whole platform. It walks the real console: the dashboard, the credit model, the product lines, the review queue, and how everything is also reachable over the API and MCP.

<VideoEmbed title="What Is Didit? — Didit Academy" />

<SectionHeader label="Our Principles" title={<>Built for the <span>AI era</span></>} description="Four testable pillars that separate Didit from pre-AI legacy providers." />

<FeatureGrid>
  <FeatureCard icon="building-columns" title="Government-attested security" description="Attested by Spain's Treasury and SEPBLAC after a year-long test alongside the Bank of Spain and CNMV. The only provider with that attestation. 200+ signals analyzed per verification." />

  <FeatureCard icon="gauge-high" title="Sub-2-second inference" description="p99 real-time inference under 2 seconds. A full KYC flow completes end-to-end in under 30 seconds, about 3× faster than the market average of 90+ seconds." />

  <FeatureCard icon="code" title="Developer-first & agent-native" description="Self-serve from minute one, 60-second sandbox, SDKs for every platform, and integration with a single prompt in Claude Code or any AI agent. A hosted MCP server with 115 tools covers agentic identity flows." />

  <FeatureCard icon="money-bill" title="$0.33 full KYC · volume discounts" description="The full KYC bundle (ID, passive liveness, face match, and IP analysis) costs $0.33 per verification, with transparent per-module prices below that. 500 free verifications a month. No minimums, no contracts, no sales calls." />
</FeatureGrid>

***

<SectionHeader label="Product lines" title={<>From onboarding to <span>continuous trust</span></>} description="One platform covering the entire identity lifecycle: onboard, verify, monitor, and screen." />

<FeatureGrid>
  <FeatureCard icon="user-plus" title="User Verification (KYC)" description="Customer onboarding (KYC/AML), revalidation and re-verification, employee lifecycle (CV, interview, right-to-work), and biometric 2FA. 14,000+ document types, 220+ countries." href="/sessions-api/overview" />

  <FeatureCard icon="building" title="Business Verification (KYB)" description="Company registry lookup, UBO and ownership, officers and directors, entity and person-level AML, and document collection, all from a single workflow. From $2.00 per check, priced per country and tier." href="/business-verification/overview" />

  <FeatureCard icon="arrow-right-arrow-left" title="Transaction Monitoring" description="Real-time transaction screening with rule-based scoring, velocity checks, AML screening, case management, travel rule messaging, and automated remediation. $0.02 per transaction." href="/transaction-monitoring/overview" />

  <FeatureCard icon="link" title="Wallet Screening (KYT)" description="Crypto screening at $0.15 per check: wallet risk scoring, source-of-funds analysis, exposure graphs, sanctions and mixer exposure." href="/core-technology/wallet-screening/overview" />
</FeatureGrid>

Didit unifies these four product lines on the same Sessions API and the same workflow engine, so you can combine them without touching integration code twice.

***

<SectionHeader label="Competitive" title={<>Why Didit <span>wins</span></>} description="How Didit compares to legacy identity verification providers built before the AI era." />

|                | Didit                                     | Legacy                             |
| -------------- | ----------------------------------------- | ---------------------------------- |
| **Security**   | Gov-attested, 200+ signals, +20 AI models | Self-certified, pre-AI era         |
| **Inference**  | \<2 seconds (p99), real-time              | 5–15 seconds                       |
| **Full KYC**   | \<30 seconds end-to-end                   | 90+ seconds                        |
| **Coverage**   | 220+ countries, 14K+ docs, 48+ languages  | 100 to 190 countries               |
| **Pricing**    | \$0.33 full KYC bundle, volume discounts  | $1.00 to $2.00/check               |
| **Free tier**  | 500/month                                 | None                               |
| **Self-serve** | Instant sandbox, 1-prompt integration     | Enterprise-gated, weeks to onboard |
| **AI era**     | Built for it, +20 proprietary models      | Retrofitting legacy systems        |
| **Fraud loop** | Real-time detect + fix                    | Batch, quarterly updates           |

***

## Getting started

<Steps>
  <Step title="Create your account">
    Free and instant at [business.didit.me](https://business.didit.me). No sales call, no credit card.
  </Step>

  <Step title="Configure your workflow">
    Use the visual node-based builder or the API to compose custom identity flows in clicks: ID verification, liveness, AML, branching logic, and actions.
  </Step>

  <Step title="Integrate the SDK">
    One line of code, or one prompt in Claude Code or any AI agent. Most teams go live in under a week.
  </Step>
</Steps>

<CardGroup>
  <Card title="Quick Start Guide" icon="rocket" href="/getting-started/quick-start">
    Go from zero to first live verification in 3 simple steps.
  </Card>

  <Card title="All Features" icon="grid-2" href="/getting-started/features">
    Explore every verification module available on the platform.
  </Card>
</CardGroup>

<Note>
  Migrating from Onfido, Jumio, Veriff, or Sumsub? Ping us on [WhatsApp](https://wa.me/+19544659728) for the fastest response, or email [hello@didit.me](mailto:hello@didit.me) and we'll put together a drop-in migration plan.
</Note>


# KYB Registry Pricing
Source: https://docs.didit.me/getting-started/kyb-registry-pricing

Business verification registry prices by country: Lite, Shareholders and UBO tiers, manual company entry and continuous registry monitoring. Pay per selected company, no contracts.

<Note>
  The table below reflects the **staging retail catalog**, checked September 7, 2026. The production pricing feed does not yet expose this catalog. Confirm rollout and your application settings before using these rates for a production integration.
</Note>

A registry check is billed once per **selected company**, at the price of the data tier delivered for the company's country. Hosted workflow searches have no separate search fee.
Standalone API searches can incur a \$0.50 fee per successful request; see [search billing](/standalone-apis/kyb-registry-search).

| Tier             | What you get                                                                                                                                                                      |
| ---------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Lite**         | Company profile: legal name, registration and VAT numbers, legal form, status, incorporation date, registered address, activity, headcount and contact details, plus the officers |
| **Shareholders** | Lite plus the direct shareholders (natural persons and corporate entities) with their ownership bands                                                                             |
| **UBOs**         | Shareholders plus the ultimate beneficial owners resolved through the ownership chain                                                                                             |

<Note>
  **You pay for the tier delivered.** Where the registry holds no ownership record for a company, a Shareholders or UBO check is delivered and billed as Lite. A company that cannot be found and is typed in manually is billed a flat **\$0.75**.
</Note>

Hosted workflows pick the tier per country in the console (*Workflows → KYB Registry Check → Countries*); every country starts at Lite. The standalone API sells one endpoint per tier: [`select`](/standalone-apis/kyb-registry-select) (Lite), [`shareholders`](/standalone-apis/kyb-registry-shareholders) and [`ubo`](/standalone-apis/kyb-registry-ubo).

## Continuous registry monitoring

<Note>
  Registry monitoring is **coming soon**. No country in the staging retail catalog checked on September 7, 2026 has monitoring enabled. The configured rate is USD 2.00 per company per year; a price does not mean the feature is available. The behavior below describes the planned service after rollout.
</Note>

Companies verified at the Shareholders or UBO tier can be kept under **continuous registry monitoring** for **\$2.00 per company per year**: the registry pushes changes of status, officers, ownership and address, the business session goes back to review and a `kyb_registry_change` webhook fires. It is available only in the countries marked below, is enabled per workflow, and can be cancelled at any time from the business page. When the wallet cannot cover the yearly renewal, monitoring stops rather than running unpaid. See [ownership monitoring](/business-verification/ownership#monitoring-shareholders-and-ubos).

## Pricing by Country

<KybRegistryPricingTable />

***

## Need a Country Not Listed?

Countries without a registry source are not offered for registry checks: the applicant enters the company manually and the step is billed the manual entry price. [Contact us](https://didit.me/contact) if you need registry coverage for a country not listed above.

→ Back to [Main Pricing Page](/getting-started/pricing)


# Phone Verification Pricing
Source: https://docs.didit.me/getting-started/phone-verification-pricing

Per-message phone verification pricing across 230+ countries via SMS, WhatsApp, Telegram, RCS, Viber, and Zalo. Pay-per-message, no contracts.

Phone verification is charged **per message sent**. The total price varies by destination country and delivery channel.

<Note>
  Supported channels include **SMS**, **WhatsApp**, **Telegram**, **RCS**, **Viber**, and **Zalo** (availability varies by country). The table below shows the total price per message for each country and channel.
</Note>

## Pricing by Country & Channel

<PhonePricingTable />

***

→ Back to [Main Pricing Page](/getting-started/pricing)


# Pricing
Source: https://docs.didit.me/getting-started/pricing

Pay only for what you use with prepaid USD credits. From $0.33 per full KYC check, 500 free checks/month, no contracts, no minimums, no expiry.

At Didit, our mission is Humanizing the Internet — which is why we offer a generous free tier for core KYC.

This Didit Academy lesson walks the pricing page for real: the three plans, what the free plan actually includes, how a workflow's price is assembled check by check, and how billing and top-ups work.

<VideoEmbed title="How much does Didit cost? — Didit Academy" />

You get <span>500 free checks per feature, every month</span> for:
ID Verification, Passive Liveness, Face Match 1:1, and Device & IP Analysis.

<Note>
  You only pay for **optional premium features** — and **only when a feature is fully completed**.
  No contracts, no minimums — just radical transparency.
</Note>

→ View full pricing: [Pricing](https://didit.me/pricing)
→ Calculate your potential savings: [ROI Calculator](https://didit.me/roi-calculator)

### Verification Links / Workflow Pricing Model

You can design your own custom verification flow in the **[Workflows](/console/workflows) section**.
Each flow is modular — you drag & drop features, and you're only charged for the features you enable **(and only if the feature finishes)**.

The **total workflow price = sum of each enabled feature** used in that session.

<p>
  Free tier: <strong>500 free checks/month per eligible core KYC feature</strong> (per organization): document capture, passive liveness, face match and Device & IP Analysis. Lookup, wallets, Database Validation and KYB are excluded. After the allowance, pay-as-you-go.
</p>

<table>
  <thead>
    <tr>
      <th>Feature</th>
      <th>Description</th>
      <th>Price</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>`ID Verification`</code></td>
      <td>Verify ID documents from over 220 countries and territories</td>

      <td>
        <div>
          <div>500 free / month</div>

          <div>
            then \$0.15 / verification
          </div>
        </div>
      </td>
    </tr>

    <tr>
      <td><code>`ID Verification — non-doc lookup`</code></td>
      <td>Check a national ID number against a government register or another authoritative source instead of photographing a document. The exact source is named per country. Selfie, liveness and face match are included where that source returns a portrait</td>

      <td>
        <div>
          <div>Per country</div>

          <div>
            <a href="/core-technology/id-verification/non-doc-lookup#coverage-and-pricing">Country rates in USD</a>
          </div>
        </div>
      </td>
    </tr>

    <tr>
      <td><code>`ID Verification — wallet`</code></td>
      <td>Sign-in with a government or bank digital identity such as MitID, BankID or itsme</td>

      <td>
        <div>
          <div>Per wallet</div>

          <div>
            <a href="/core-technology/id-verification/digital-id-wallets">Price pending publication</a>
          </div>
        </div>
      </td>
    </tr>

    <tr>
      <td><code>`Face Match 1:1`</code></td>
      <td>Accurate facial match comparison between two faces</td>

      <td>
        <div>
          <div>500 free / month</div>

          <div>
            then \$0.05 / match
          </div>
        </div>
      </td>
    </tr>

    <tr>
      <td><code>`Passive Liveness`</code></td>
      <td>Detect liveness to prevent spoofing and verify genuine users</td>

      <td>
        <div>
          <div>500 free / month</div>

          <div>
            then \$0.10 / check
          </div>
        </div>
      </td>
    </tr>

    <tr>
      <td><code>`Active Liveness`</code></td>
      <td>Enhanced liveness detection for more secure verification</td>
      <td>\$0.15</td>
    </tr>

    <tr>
      <td><code>`Device & IP Analysis`</code></td>
      <td>Analyze user IP addresses to verify their location and detect potential risks</td>

      <td>
        <div>
          <div>500 free / month</div>

          <div>
            then \$0.03 / check
          </div>
        </div>
      </td>
    </tr>

    <tr>
      <td><code>`NFC Verification`</code></td>
      <td>Enhance security with NFC-based authentication for ID documents</td>
      <td>\$0.15</td>
    </tr>

    <tr>
      <td><code>`Biometric Authentication`</code></td>
      <td>Re-verify returning users who have previously completed verification</td>
      <td>\$0.10</td>
    </tr>

    <tr>
      <td><code>`Phone Verification`</code></td>
      <td>Verify user phone numbers to prevent fraud and ensure secure communication</td>

      <td>
        <a href="/getting-started/phone-verification-pricing">
          \$0.04 + carrier fee
        </a>
      </td>
    </tr>

    <tr>
      <td><code>`Email Verification`</code></td>
      <td>Verify user email addresses to protect against high-risk and compromised emails</td>
      <td>\$0.03</td>
    </tr>

    <tr>
      <td><code>`Age Estimation`</code></td>
      <td>Estimate the age of users based on their facial features and optional ID Verification fallback</td>
      <td>\$0.10</td>
    </tr>

    <tr>
      <td><code>`AML Screening`</code></td>
      <td>Screen users against watchlists and PEP databases</td>
      <td>\$0.20</td>
    </tr>

    <tr>
      <td><code>`AML Monitoring`</code></td>
      <td>Ongoing monitoring of users against AML databases</td>
      <td>\$0.07 / year</td>
    </tr>

    <tr>
      <td><code>`Proof of Address`</code></td>
      <td>Verify a user's residential address through official documents</td>
      <td>\$0.20</td>
    </tr>

    <tr>
      <td><code>`Document AI`</code></td>
      <td>Collect custom documents (proof of funds, payslips, tax statements) and extract the fields you define, per document</td>
      <td>\$0.20</td>
    </tr>

    <tr>
      <td><code>`Questionnaire`</code></td>
      <td>Collect structured attestations and supporting documents via customizable forms</td>
      <td>\$0.10</td>
    </tr>

    <tr>
      <td><code>`Database Validation`</code></td>
      <td>Verify user data against government and other authoritative databases</td>

      <td>
        <a href="/getting-started/database-validation-pricing">
          Varies by country
        </a>
      </td>
    </tr>

    <tr>
      <td><code>`Reusable KYC`</code></td>
      <td>Streamline user onboarding with reusable KYC data across multiple services</td>

      <td>
        Free
      </td>
    </tr>

    <tr>
      <td><code>`Whitelabel`</code></td>
      <td>Custom branding of the verification interface</td>
      <td>\$0.20</td>
    </tr>
  </tbody>
</table>

#### How ID Verification methods are billed

ID Verification is one feature with [three methods](/core-technology/id-verification/verification-methods). The \$0.15 price and the 500 free checks a month are **document capture**: a non-document method is priced per country or per wallet and is not drawn from that allowance.

* A register that answered bills the lookup. A match, a partial match and a no match all count, because the query ran either way.
* A register that never answered is not billed, so an outage costs you nothing.
* A number that fails the format check never reaches the register: not counted, not billed.
* When a user falls back to document capture, that capture bills on top — two checks ran.
* An abandoned, cancelled, timed-out or failed wallet sign-in is not billed. Only a completed sign-in is.

### Business Verification (KYB)

Verify companies and legal entities with automated registry lookups, UBO identification, officer screening, AML checks, and document collection.

<table>
  <thead>
    <tr>
      <th>Feature</th>
      <th>Description</th>
      <th>Price</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>`Registry Check - Lite`</code></td>
      <td>Company registry lookup: profile, identifiers, status, registered address, activity and officers. <a href="/getting-started/kyb-registry-pricing">Prices by country</a></td>
      <td>\$2.00</td>
    </tr>

    <tr>
      <td><code>`Registry Check - Shareholders`</code></td>
      <td>Lite plus the direct shareholders with their ownership bands. $4.00-$22.00 by country; billed as Lite where the registry holds no ownership record</td>
      <td>from \$4.00</td>
    </tr>

    <tr>
      <td><code>`Registry Check - UBOs`</code></td>
      <td>Shareholders plus the ultimate beneficial owners resolved through the ownership chain. $5.00-$96.00 by country</td>
      <td>from \$5.00</td>
    </tr>

    <tr>
      <td><code>`Manual Company Entry`</code></td>
      <td>Company not found in the registry and typed in by the applicant</td>
      <td>\$0.75</td>
    </tr>

    <tr>
      <td><code>`Registry Monitoring`</code></td>
      <td>Coming soon: continuous registry monitoring of a company verified at the Shareholders or UBO tier: status, officer, ownership and address changes, <a href="/getting-started/kyb-registry-pricing#continuous-registry-monitoring">where available</a></td>
      <td>\$2.00 / company / year</td>
    </tr>

    <tr>
      <td><code>`Company AML Screening`</code></td>
      <td>Screen the company entity against sanctions, regulatory enforcement, and adverse media databases</td>
      <td>\$0.20</td>
    </tr>

    <tr>
      <td><code>`Person AML (per UBO/officer)`</code></td>
      <td>Individual AML screening for each identified beneficial owner and officer</td>
      <td>\$0.20</td>
    </tr>

    <tr>
      <td><code>`KYC per person`</code></td>
      <td>Individual identity verification for UBOs and officers (standard workflow pricing applies)</td>
      <td>Standard rates</td>
    </tr>
  </tbody>
</table>

### Transaction Monitoring (KYT)

Screen transactions in real time against configurable rules for AML/CTF, fraud detection, and compliance.

<table>
  <thead>
    <tr>
      <th>Feature</th>
      <th>Description</th>
      <th>Price</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>`Transaction Screening`</code></td>
      <td>Real-time rule evaluation, scoring, velocity checks, case management, and alerts</td>
      <td>\$0.02</td>
    </tr>

    <tr>
      <td><code>`AML Transaction Screening`</code></td>
      <td>Counterparty sanctions screening and crypto wallet risk analysis via blockchain analytics providers, transaction-coupled or <a href="/transaction-monitoring/wallet-screening">on-demand</a></td>

      <td>
        <div>
          <div>
            <a href="/transaction-monitoring/aml-screening#supported-providers">from \$0.15</a>
          </div>

          <div>
            \$0.02 with an existing provider key
          </div>
        </div>
      </td>
    </tr>

    <tr>
      <td><code>`Travel Rule`</code></td>
      <td>Managed FATF / EU TFR originator-beneficiary exchange for virtual asset transfers: rail routing, counterparty VASP resolution, and wallet-ownership proofs</td>

      <td>
        <div>
          <div>\$0.02</div>

          <div>
            per outbound transfer
          </div>
        </div>
      </td>
    </tr>
  </tbody>
</table>

<Note>
  A Travel Rule transfer is billed on its own \$0.02 line item instead of the standard Transaction Screening fee - never both.
  When Travel Rule routing needs a blockchain-analytics wallet lookup to identify the counterparty VASP, that lookup is billed once at the AML Transaction Screening rate and is never double-charged when crypto monitoring already screened the same wallet on the transaction.
  See [Travel Rule pricing](/transaction-monitoring/travel-rule#pricing) for the full breakdown.
</Note>

### Standalone API Pricing (Server-to-Server)

For server-to-server integrations, we offer the following APIs:

<table>
  <thead>
    <tr>
      <th>Standalone API</th>
      <th>Description</th>
      <th>Price</th>
    </tr>
  </thead>

  <tbody>
    <tr>
      <td><code>`Face Match`</code></td>
      <td>Accurate facial match comparison between two faces</td>
      <td>\$0.05</td>
    </tr>

    <tr>
      <td><code>`Face Search`</code></td>
      <td>Search for users by their face against a database of verified users</td>
      <td>\$0.05</td>
    </tr>

    <tr>
      <td><code>`Age Estimation`</code></td>
      <td>Estimate the age of users based on their facial features</td>
      <td>\$0.10</td>
    </tr>

    <tr>
      <td><code>`ID Verification`</code></td>
      <td>Verify ID documents from over 220 countries and territories</td>
      <td>\$0.20</td>
    </tr>

    <tr>
      <td><code>`Proof of Address`</code></td>
      <td>Verify a user's residential address through official documents</td>
      <td>\$0.20</td>
    </tr>

    <tr>
      <td><code>`Document AI`</code></td>
      <td>Extract the fields you define from any document (PDF or image), with name matching and tampering checks</td>
      <td>\$0.20</td>
    </tr>

    <tr>
      <td><code>`AML Screening`</code></td>
      <td>Screen users against watchlists and PEP databases</td>
      <td>\$0.20</td>
    </tr>

    <tr>
      <td><code>`KYB Registry Search`</code></td>
      <td>Find company candidates. One fee per successful request returning paid-source results; empty results and failures are not charged. <a href="/standalone-apis/kyb-registry-search">Search billing</a></td>
      <td>\$0.50</td>
    </tr>

    <tr>
      <td><code>`KYB Registry Select (Lite)`</code></td>
      <td>Retrieve a company's registry profile and officers. Profile retrieval is billed per selected company, separately from any search fee. <a href="/getting-started/kyb-registry-pricing">Prices by country</a></td>
      <td>\$2.00</td>
    </tr>

    <tr>
      <td><code>`KYB Registry Shareholders`</code></td>
      <td>Lite plus the direct shareholders. Billed as Lite where the registry holds no ownership record</td>
      <td>$4.00 - $22.00</td>
    </tr>

    <tr>
      <td><code>`KYB Registry UBOs`</code></td>
      <td>Shareholders plus the ultimate beneficial owners resolved through the ownership chain</td>
      <td>$5.00 - $96.00</td>
    </tr>

    <tr>
      <td><code>`Passive Liveness`</code></td>
      <td>Detect if a real, live person is present without requiring user interaction</td>
      <td>\$0.05</td>
    </tr>

    <tr>
      <td><code>`Phone Verification`</code></td>
      <td>Verify user phone numbers to prevent fraud and ensure secure communication</td>
      <td>[\$0.04 + carrier fee](/getting-started/phone-verification-pricing)</td>
    </tr>

    <tr>
      <td><code>`Email Verification`</code></td>
      <td>Verify user email addresses to protect against high-risk and compromised emails</td>
      <td>\$0.03</td>
    </tr>

    <tr>
      <td><code>`Database Validation`</code></td>
      <td>Verify user data against government and other authoritative databases</td>
      <td>[Varies by country](/getting-started/database-validation-pricing)</td>
    </tr>
  </tbody>
</table>

***

## Frequently Asked Questions

<AccordionGroup>
  <Accordion title="Is the free tier really free? What's the catch?">
    Yes — it's genuinely free. Our Workflows include a **free monthly tier of 500 checks per feature**, per organization, for our core KYC capabilities: **ID Verification, Passive Liveness, Face Match 1:1, and Device & IP Analysis**. Once you exceed the free tier, usage is simply pay-as-you-go at the rates shown above. There are no hidden conditions.
  </Accordion>

  <Accordion title="How do prepaid credits work?">
    You purchase credits in USD, which are added to your account balance. Each time you use a paid feature, its cost is deducted from that balance. Credits **never expire**, so you can use them whenever you need without time pressure.
  </Accordion>

  <Accordion title="Do I need to sign a long-term contract or commit to monthly minimums?">
    No. There are **no contracts, no minimum usage requirements, and no lock-ins**. You stay in full control of when and how much you spend.
  </Accordion>

  <Accordion title="What does &#x22;pay only for completed features&#x22; mean?">
    You're only charged when a feature finishes successfully and returns a final result (**Approved, Declined, or In Review**). If a user abandons the flow or a feature doesn't complete, **you don't pay for it**.
  </Accordion>

  <Accordion title="How do prepaid-credit discounts work?">
    You buy the exact amount of credits you want and receive a discount on the charge: **4% at $250**, **7% at $1,000**, and **10% at $2,000**. Self-serve top-ups range from **$50 to \$2,000**. Contact sales for higher volumes. The same discount tiers apply to eligible auto-recharge purchases.
  </Accordion>

  <Accordion title="What happens if an auto-recharge payment fails?">
    We email your organization contacts every time an automatic recharge is declined, and the failed attempt appears in **Settings → Billing → Billing history** with the reason the payment method gave.

    After **two consecutive failed payments** auto-recharge pauses: no further charge is attempted, and your balance keeps decreasing until it runs out and verifications stop. The Billing page shows a warning while auto-recharge is paused. Update your payment method and auto-recharge resumes within a few minutes: if your balance is already below your threshold it recharges then and there, otherwise it waits for the balance to cross it as usual. A successful manual top-up resumes it too.
  </Accordion>

  <Accordion title="What's the difference between the Free tier and the Enterprise plan?">
    The **Free tier** gives you full access to the self-serve platform plus the monthly free tier for core KYC features. The **Enterprise plan** is designed for high-volume or complex use cases and includes benefits like a dedicated Account Manager, integration support, custom SLAs, and tailored commercial terms.
  </Accordion>

  <Accordion title="Is pricing different for Standalone APIs vs Workflows?">
    Yes. **Workflows** are optimized for end-to-end user verification and include a monthly free tier for core checks. **Standalone APIs** are server-to-server calls priced per successful request and do not include the free workflow tier. Prices for each integration type are listed separately above.
  </Accordion>

  <Accordion title="Are there setup fees, integration fees, or hidden costs?">
    No. There are **no setup fees, no integration fees, no monthly minimums, and no surprises**. What you see in the pricing tables is exactly what you pay.
  </Accordion>
</AccordionGroup>

***

### Get Started

<CardGroup>
  <Card title="Create Free Account" icon="rocket" href="https://business.didit.me">
    Sign up in seconds — no credit card required
  </Card>

  <Card title="Calculate Your Savings" icon="calculator" href="https://didit.me/roi-calculator">
    See how much you can save vs legacy providers
  </Card>
</CardGroup>


# Quick start: launch your first KYC verification flow
Source: https://docs.didit.me/getting-started/quick-start

Go from zero to live KYC verification in minutes. Create an account, build a workflow, launch a session, and receive webhooks. 500 free verifications/month.

This page pairs with the Academy lesson below: a 19-minute screen recording that builds a verification workflow in the real console, from template to published flow, including rules, branching, pricing, and the shareable link.

<VideoEmbed title="Build Your First Verification Flow — Didit Academy" />

<AgentPromptAccordion title="Quick Start Prompt" />

<Steps>
  <Step title="Create your Didit account">
    1. Go to [business.didit.me](https://business.didit.me)
    2. Sign up with SSO or email and password
    3. Create your **Organization** — this is where your team manages workflows, API keys, and verification activity
  </Step>

  <Step title="Build a verification workflow">
    Navigate to **Workflows** in the sidebar and click **Create New**. Choose a workflow type:

    | Type                    | Description                                                                      |
    | ----------------------- | -------------------------------------------------------------------------------- |
    | **Simple Workflow**     | Steps run in a defined order — ideal for standard onboarding flows               |
    | **Node-Based Workflow** | Flexible branching logic — build conditional paths based on verification results |

    Pick a template to get started:

    | Template                      | Use case                          |
    | ----------------------------- | --------------------------------- |
    | **KYC**                       | Standard user onboarding          |
    | **Adaptive Age Verification** | Selfie age check with ID fallback |
    | **Biometric Authentication**  | Passwordless selfie re-auth       |
    | **Address Verification**      | Proof of address flow             |

    Customize by toggling blocks: Liveness, Face Match, AML, NFC, Phone, Email, and more.

    The clip below picks up the Academy lesson at 2:50, where a new workflow is created from a template and configured node by node.

    <VideoEmbed title="Creating a new workflow from a template — Didit Academy" />
  </Step>

  <Step title="Configure webhook and copy API key">
    Go to **API & Webhooks** in the sidebar:

    1. Add your **Webhook URL** — Didit sends status updates here
    2. Copy your **API Key** — keep it server-side only, never expose in frontend code
    3. Save the destination's **signing secret** as `DIDIT_WEBHOOK_SECRET` in your `.env` — it's required to verify the `X-Signature-V2` HMAC on incoming webhooks

    <Tip>
      You can **test webhooks directly** from this page with different data and statuses — no need to run a full verification. This lets you validate your integration is working correctly before going live.
    </Tip>
  </Step>

  <Step title="Start a verification session">
    **Option A — Hosted sessions** (recommended)

    Our preferred integration method. Didit A/B tests the hosted flow continuously, so completion rate, speed, and fraud resistance keep improving without you shipping any UI.

    In the Console, click **"+"** → select a workflow → generate a link or QR code. Or create sessions programmatically:

    ```bash theme={null}
    curl -X POST https://verification.didit.me/v3/session/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"workflow_id": "your-workflow-id"}'
    ```

    <Note>
      Find your `workflow_id` under **Workflows** in the sidebar.
    </Note>

    In the integration Academy lesson, this is the 3:36 mark: the create-session call with its one required field, then vendor data and the callback URL.

    <VideoEmbed title="Create session: the one required field — Didit Academy" />

    **Option B — Standalone APIs** (advanced)

    Call endpoints directly from your backend — no session required. Best for server-to-server or custom flows:

    | Endpoint                     | Purpose            |
    | ---------------------------- | ------------------ |
    | `POST /v3/id-verification/`  | Document check     |
    | `POST /v3/face-match/`       | Selfie vs ID       |
    | `POST /v3/aml/`              | Sanctions & PEP    |
    | `POST /v3/passive-liveness/` | Deepfake detection |

    See the full list in [API Reference](/standalone-apis/id-verification).
  </Step>

  <Step title="Receive real-time results">
    Didit sends webhook events to your endpoint — no polling needed.

    | Event                        | Trigger                                               |
    | ---------------------------- | ----------------------------------------------------- |
    | `status.updated`             | User-session or business-session status changes       |
    | `data.updated`               | Session or business-session verification data changes |
    | `user.status.updated`        | Vendor user status changes                            |
    | `user.data.updated`          | Vendor user profile or aggregate data changes         |
    | `business.status.updated`    | Vendor business status changes                        |
    | `business.data.updated`      | Vendor business profile or aggregate data changes     |
    | `activity.created`           | Activity event recorded                               |
    | `transaction.created`        | Transaction created                                   |
    | `transaction.status.updated` | Transaction status changes                            |

    See [Webhooks](/integration/webhooks) for payload format and signature verification.
  </Step>

  <Step title="Manage and monitor">
    Use the Console to:

    * View session progress in real time
    * Download PDF/CSV reports for compliance
    * Blocklist suspicious IDs or faces
    * Manually update or reject sessions

    The Academy lesson on reading results walks a real session check by check: warnings, scores, the event log, webhook deliveries, and the PDF export your compliance team will ask for.

    <VideoEmbed title="How to Read a Verification Result — Didit Academy" />
  </Step>
</Steps>

## Need help?

<CardGroup>
  <Card title="WhatsApp" icon="comments" href="https://wa.me/+19544659728">
    Fastest response — reach us directly.
  </Card>

  <Card title="Email" icon="envelope" href="mailto:hello@didit.me">
    [hello@didit.me](mailto:hello@didit.me)
  </Card>
</CardGroup>


# Security & compliance
Source: https://docs.didit.me/getting-started/security-compliance

Didit security and compliance posture: SOC 2 Type 2, ISO 27001, GDPR, iBeta Level 1, FSM youth protection, EU AI Act ready, and validated by Spain's Treasury and SEPBLAC.

Didit is built from the ground up with security as a first-class principle. Every layer of the platform — from infrastructure to AI models — is designed to meet the highest international standards for information security, data privacy, and biometric accuracy.

<StatGrid>
  <StatCard label="Type 2 Certified" />

  <StatCard label="27001 Certified" />

  <StatCard label="Compliant" />

  <StatCard label="Level 1 Certified" />

  <StatCard label="Youth Protection" />

  <StatCard label="Ready" />
</StatGrid>

***

<SectionHeader label="Government-validated" title={<>More secure than <span>in-person</span></>} description="Validated by the Spanish Treasury, SEPBLAC, and CNMV — the first and only provider to receive this validation." />

<Info>
  **"Didit's NFC + active liveness verification offers security equivalent to or greater than in-person verification."**
  — Official report, Spanish Treasury ([tesoro.es](https://www.tesoro.es/sites/default/files/publicaciones/Informe%20Conclusiones%20DIDIT.pdf))
</Info>

After a year-long test by Spanish financial regulators — the Spanish Treasury (Tesoro Público), SEPBLAC (the financial intelligence unit), Banco de España, and CNMV (the securities and markets commission) — Didit was recognized as the only provider whose NFC + active liveness flow meets or exceeds the security level of in-person identity verification.

<FeatureGrid>
  <FeatureCard icon="award" title="Only provider with this validation" description="First and only vendor to pass the year-long financial-regulator test in Spain. Independent, adversarial, and repeatable." />

  <FeatureCard icon="chart-network" title="200+ signals per verification" description="Biometric, document, behavioral, and database signals cross-checked in real time on every session." />

  <FeatureCard icon="database" title="Connected to government data sources" description="Integrated one-by-one with authoritative government databases worldwide to confirm identity against source-of-truth records." />

  <FeatureCard icon="file-certificate" title="Global licenses & compliance" description="SOC 2 Type 2 certified, ISO 27001, ISO 27017, ISO 27018, GDPR, iBeta Level 1 (ISO 30107-3), and FSM youth-protection certified. Licensed and compliant in every country we operate." />
</FeatureGrid>

***

<SectionHeader label="Certifications" title={<>Certified for <span>enterprise trust</span></>} description="Our platform meets the highest international standards for information security, data privacy, and biometric accuracy." />

<CardGroup>
  <Card title="SOC 2 Type 2" icon="shield-halved">
    **Service Organization Controls — Type 2.** An independent audit against the AICPA Trust Services Criteria confirmed Didit's security, availability, and confidentiality controls **operated effectively over the March 9 – July 1, 2026 observation period**. Issued July 2026 (Type 1 issued April 2026). Report available to enterprise customers under NDA.
  </Card>

  <Card title="FSM Jugendschutz geprüft" icon="child-reaching">
    **German youth-protection certification.** Germany's youth-protection self-regulator (FSM) certified that Didit's Age Verification System reliably establishes a closed user group under **Section 4(2) JMStV**, so only verified adults reach age-restricted content.
  </Card>

  <Card title="ISO/IEC 27001" icon="shield-check">
    **Information security management.** Didit maintains a certified Information Security Management System (ISMS) covering the design, development, and operation of the identity verification platform. Certificate excerpts available on request.
  </Card>

  <Card title="ISO/IEC 27017" icon="cloud">
    **Cloud security controls.** Extended cloud-specific security controls that complement our ISO 27001 certification, ensuring robust protection for cloud-based verification services.
  </Card>

  <Card title="ISO/IEC 27018" icon="user-shield">
    **Cloud privacy protection.** Dedicated controls for protecting personally identifiable information (PII) in cloud environments, going beyond general data protection requirements.
  </Card>

  <Card title="GDPR Compliant" icon="scale-balanced">
    **Full EU data protection compliance.** Didit is fully compliant with the General Data Protection Regulation. We act as a data processor — you remain the data controller. DPA and TOMs available on request.
  </Card>

  <Card title="iBeta Level 1 — ISO 30107-3" icon="face-smile">
    **Biometric presentation attack detection.** Our liveness detection technology is iBeta Level 1 certified under the ISO 30107-3 standard, ensuring reliable detection of spoofing attempts including printed photos, screen replays, and 3D masks.
  </Card>

  <Card title="EU AI Act Ready" icon="robot">
    **Responsible AI compliance.** Didit's AI-powered verification systems are designed in alignment with the EU AI Act requirements for high-risk AI systems, including transparency, human oversight mechanisms, data governance, and bias monitoring.
  </Card>

  <Card title="EBA / MiCA compatibility" icon="scale-balanced">
    **Remote onboarding, regulator-grade.** An independent legal opinion confirms Didit's remote onboarding meets the EBA Remote Customer Onboarding Guidelines (EBA/GL/2022/15) and is compatible with the EU AML Single Rulebook and MiCA.
  </Card>
</CardGroup>

<Card title="See every certification" icon="badge-check" href="/getting-started/certifications">
  The complete, always-current list — SOC 2 Type 2 and Type 1, ISO 27001/27017/27018, iBeta Level 1, FSM, the Spanish regulator attestation, EBA/MiCA, and GDPR — with dates and how to get each report. We add more all the time; if you need a specific certification, [book a demo](https://didit.me/get-a-demo/) and tell us.
</Card>

***

<SectionHeader label="Security Infrastructure" title={<>How we protect <span>your data</span></>} />

<FeatureGrid>
  <FeatureCard icon="lock" title="End-to-end encryption" description="All data is encrypted in transit (TLS 1.3) and at rest (AES-256). Industry-standard cryptographic protocols protect sensitive information at every stage." />

  <FeatureCard icon="users" title="Role-based access control" description="Granular permissions and role-based access ensure only authorized personnel can access verification data and system configurations." />

  <FeatureCard icon="clipboard-list" title="Complete audit logs" description="Every action is logged with timestamps, user IDs, and IP addresses. Audit logs are retained for 365 days and can be exported for compliance reviews." />

  <FeatureCard icon="eye" title="24/7 security monitoring" description="Continuous monitoring and automated threat detection across our entire infrastructure with real-time alerts for suspicious activity." />

  <FeatureCard icon="server" title="EU-based infrastructure" description="Data is processed and stored in the EU on AWS servers by default. Enterprise customers can enable in-country processing with local data residency options." />

  <FeatureCard icon="clock" title="Configurable data retention" description="Set retention policies from 1 month to 10 years, or delete sessions on demand via API. Process-and-purge patterns supported for minimal data footprint. Any biometric template you choose to retain after a session deletion carries its own finite expiry." />
</FeatureGrid>

***

<SectionHeader label="Fraud signals" title={<>200+ signals, <span>real-time fraud loop</span></>} description="Fully integrated fraud loop — detect, analyze, and fix in real time. Every verification is scored against 200+ signals across biometric, document, behavioral, and database sources." />

| Signal type            | Capability                                                                                                                                   |
| ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------- |
| **Deepfakes**          | +20 proprietary AI models, built in-house for the generative AI era. [Liveness →](/core-technology/liveness/overview)                        |
| **Injection attacks**  | Camera stream tampering prevention — catches replay and video injection. [Liveness →](/core-technology/liveness/overview)                    |
| **Document forgery**   | Hologram, reprint, screenshot, and digital alteration detection. [ID Verification →](/core-technology/id-verification/overview)              |
| **Synthetic IDs**      | Cross-reference against authoritative government databases worldwide. [Database Validation →](/core-technology/database-validation/overview) |
| **Behavioral signals** | Device & IP Analysis, device fingerprinting, and replay detection. [Device & IP Analysis →](/core-technology/ip-analysis/overview)           |
| **Face Search 1:N**    | Duplicate and multi-account detection across all verified users. [Face Search →](/core-technology/face-search/overview)                      |

<Tip>
  Our expert fraud team responds to new attack vectors within hours, not quarters. Models and rules are updated continuously as the threat landscape shifts.
</Tip>

***

<SectionHeader label="AI Act Compliance" title={<>Responsible AI — <span>by design</span></>} description="As an AI-native identity platform, Didit takes the EU AI Act seriously. Our systems are built to meet the requirements for high-risk AI applications." />

Identity verification using biometrics is classified as **high-risk** under the EU AI Act. Didit proactively addresses these requirements:

| Requirement               | How Didit complies                                                                                                       |
| ------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Risk management**       | Continuous risk assessment across all AI models with documented mitigation strategies.                                   |
| **Data governance**       | Training data is curated for quality, relevance, and representativeness. Bias testing across demographics.               |
| **Transparency**          | Clear documentation of AI capabilities and limitations. Users are informed when AI processes their data.                 |
| **Human oversight**       | Manual review workflows allow human operators to override AI decisions at any point.                                     |
| **Accuracy & robustness** | iBeta-certified liveness detection. Regular model evaluation against adversarial attacks (deepfakes, injection, replay). |
| **Record-keeping**        | Comprehensive audit logs and session records maintained for regulatory review.                                           |
| **Non-discrimination**    | Bias monitoring and testing across age, gender, ethnicity, and document types to ensure equitable treatment.             |

<Info>
  Didit continuously updates its compliance posture as the EU AI Act implementing measures are finalized. Contact your Didit representative for the latest AI Act readiness documentation.
</Info>

***

<SectionHeader label="Data Protection" title={<>Your data protection <span>partner</span></>} />

Didit acts as a **data processor** — you remain the **data controller**. The platform is designed to support GDPR and local data-protection regimes out of the box.

| Aspect                  | Detail                                                                                                                                                                                                                                                                                                                                                      |
| ----------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Processor role**      | Didit processes personal data strictly on your behalf and under your instructions.                                                                                                                                                                                                                                                                          |
| **Processing region**   | EU by default (AWS). Enterprise customers can enable in-country processing.                                                                                                                                                                                                                                                                                 |
| **Data minimization**   | Process-and-purge patterns let you retain only the fields your business requires.                                                                                                                                                                                                                                                                           |
| **Data portability**    | Export session data via the Console or API at any time.                                                                                                                                                                                                                                                                                                     |
| **Right to erasure**    | Delete individual sessions on demand via the Console or the [Delete Session](/sessions-api/delete-session) API. Send `deletion_instruction: "privacy_erasure"` to also purge any retained biometric template for that person.                                                                                                                               |
| **Biometric templates** | Face embeddings are deleted with the session by default. An application can opt in to retain an image-free biometric template for duplicate detection; it remains biometric data, has a finite expiry, and is purged on User deletion, privacy erasure, expiry, or explicit purge. See [Biometric templates](/management-api/biometric-templates/overview). |
| **Retention controls**  | Configure retention from 1 month to 10 years in **Console → App Settings → Data**.                                                                                                                                                                                                                                                                          |

## Customer responsibilities in verification flows

When you use Didit in your own onboarding, authentication, or verification experience, you remain responsible for the **controller-side disclosures and legal basis** for that flow.

| Requirement                                    | What you need to do                                                                                                                                                                                                                               |
| ---------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Tell the user who is involved**              | Make clear that your company is requesting the verification and that Didit is the verification provider / processor powering the flow.                                                                                                            |
| **Show your privacy notice**                   | Link to your own privacy notice or equivalent disclosure before the user starts verification.                                                                                                                                                     |
| **Link Didit's legal documents**               | Link to Didit's [Verification Privacy Notice](https://didit.me/terms/verification-privacy-notice), [End User Terms for Identity Verification](https://didit.me/terms/identity-verification), and any other Didit policy your legal team requires. |
| **Collect explicit consent where required**    | If your flow captures documents, selfies, liveness video, or biometrics, use an unchecked checkbox or another affirmative control wherever applicable law requires explicit consent.                                                              |
| **Handle white-label and custom UI correctly** | If you use a custom domain, white-label flow, or API-driven UI, you must render these disclosures in your own product because the branding alone does not disclose Didit's role.                                                                  |
| **Keep your own records**                      | If your legal team requires proof of notice or consent, store the text version, timestamp, and related metadata in your own systems.                                                                                                              |

<Warning>
  Didit provides the verification infrastructure, but it does not decide whether your specific user journey satisfies the consent, disclosure, or biometric-law requirements that apply to your business. Review your implementation with legal counsel before going live.
</Warning>

<Note>
  Need a DPA, TOMs, sub-processor list, or other compliance attestations? Contact your Didit representative or email [hello@didit.me](mailto:hello@didit.me).
</Note>

***

<SectionHeader label="Operational Security" title={<>Continuous <span>protection</span></>} />

<FeatureGrid>
  <FeatureCard icon="bug" title="Penetration testing" description="Periodic third-party penetration tests with tracked remediation. Reports available to enterprise customers under NDA." />

  <FeatureCard icon="lock" title="No known breaches" description="No security breaches reported to date. Incident response procedures tested and documented." />

  <FeatureCard icon="user-shield" title="Internal security team" description="Dedicated cybersecurity team with least-privilege access and strict environment separation across all systems." />

  <FeatureCard icon="key" title="API key security" description="Separate Sandbox and Live API keys. Keys can be rotated at any time via the Business Console." />
</FeatureGrid>

***

## Security FAQ

<AccordionGroup>
  <Accordion title="What certifications does Didit hold?">
    Didit is **SOC 2 Type 2 certified** (July 2026, covering the March 9 – July 1, 2026 observation period; Type 1 issued April 2026), ISO 27001 certified for information security management, ISO 27017 and ISO 27018 certified for cloud security and privacy, fully GDPR compliant, iBeta Level 1 certified (ISO 30107-3) for biometric presentation attack detection, and **FSM Jugendschutz geprüft** in Germany for age verification under Section 4(2) JMStV. Didit is also the only provider attested by Spanish financial regulators (Tesoro, Banco de España, SEPBLAC, CNMV) as at least as safe as in-person verification, and holds an independent legal opinion confirming EBA/MiCA compatibility. See the complete list on the [Certifications page](/getting-started/certifications). We add more all the time — if you need a specific certification, [book a demo](https://didit.me/get-a-demo/) and tell us.
  </Accordion>

  <Accordion title="Is my data encrypted?">
    Yes. All data is encrypted in transit using TLS 1.3 and at rest using AES-256 encryption. We use industry-standard cryptographic protocols across our entire infrastructure.
  </Accordion>

  <Accordion title="Where is data stored and processed?">
    By default, all data is processed and stored in the EU on AWS infrastructure. Enterprise customers can request in-country processing with local data residency options, subject to availability.
  </Accordion>

  <Accordion title="How do I configure data retention?">
    Navigate to **Business Console → App Settings → Data** to set your retention window (1 month to 10 years). You can also delete sessions on demand via the Console or [Delete Session API](/sessions-api/delete-session). See the [Data Retention](/console/data-retention) page for details.
  </Accordion>

  <Accordion title="Can I delete verification data?">
    Yes. Delete individual sessions through the Console or programmatically via the [Delete Session API](/sessions-api/delete-session). For maximum data minimization, use the process-and-purge pattern to delete each session as soon as you have received its webhook results.
  </Accordion>

  <Accordion title="Does deleting a session delete biometric data?">
    By default, yes: the face image, liveness video, and the face embedding used for duplicate detection are deleted with the session. If your application has opted in to [biometric-template retention](/console/data-retention#biometric-template-retention), Didit keeps one image-free face biometric template anchored to the User after an operational session deletion. That template remains biometric data, is used only for your tenant-scoped duplicate detection, has a finite expiry, and is purged on User deletion, a privacy-erasure request, expiry, or an explicit purge through the [Biometric Templates API](/management-api/biometric-templates/overview). Face blocklist entries you manage are separate and stay until you remove them.
  </Accordion>

  <Accordion title="How do you handle security incidents?">
    We maintain a documented incident response plan with defined severity levels, escalation procedures, and communication protocols. Any material incidents are reported to affected customers within the timeframes required by GDPR and applicable regulations.
  </Accordion>

  <Accordion title="Is Didit compliant with the EU AI Act?">
    Didit proactively aligns with the EU AI Act requirements for high-risk AI systems, including risk management, data governance, transparency, human oversight, accuracy testing, and non-discrimination. We continuously update our compliance posture as implementing measures are finalized.
  </Accordion>

  <Accordion title="Can I get security documentation?">
    Yes. We provide DPAs, TOMs, sub-processor lists, penetration test summaries (under NDA), and ISO certificate excerpts. Contact your Didit representative or email [hello@didit.me](mailto:hello@didit.me).
  </Accordion>

  <Accordion title="How are audit logs handled?">
    Every API call and Console action is recorded with timestamps, user IDs, and IP addresses. Audit logs are retained for 365 days and can be exported at any time. See the [Audit Logs](/console/audit-logs) page for details.
  </Accordion>
</AccordionGroup>

***

## Related resources

<CardGroup>
  <Card title="Certifications & attestations" icon="badge-check" href="/getting-started/certifications">
    Every credential Didit holds, with dates and how to get each report.
  </Card>

  <Card title="Data Retention" icon="clock" href="/console/data-retention">
    Configure retention policies and implement privacy-first patterns.
  </Card>

  <Card title="Audit Logs" icon="clipboard-list" href="/console/audit-logs">
    Track every action with complete audit trails.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/integration/webhooks">
    Receive real-time notifications for verification events.
  </Card>

  <Card title="API Authentication" icon="key" href="/getting-started/api-authentication">
    Secure API key management and authentication.
  </Card>
</CardGroup>


# User Flow
Source: https://docs.didit.me/getting-started/user-verification-journey

End-to-end Didit verification UX: ID capture, biometric liveness, smart retries, real-time feedback. Optimized to drive industry-leading completion rates.

<AgentPromptAccordion title="Session Lifecycle Prompt" />

This guide explains what a typical end-user experiences during an **ID Document Check + Liveness Test** session, and highlights the UX optimizations that drive high completion rates.

This Didit Academy lesson follows the hosted flow exactly as a user sees it: the first screen, document capture, the liveness selfie, and every outcome screen from approved to declined.

<VideoEmbed title="What your users actually see — Didit Academy" />

## Flow Overview

<Frame>
  <img alt="Didit identity verification user journey from start screen through ID and selfie capture to result" />
</Frame>

<Steps>
  <Step title="Start screen">
    The user lands on a clean, branded screen that sets expectations (e.g., "You'll need your ID and your face"). This reduces drop-off by removing uncertainty.
  </Step>

  <Step title="Country and document selection">
    The user selects their country and document type (Passport, ID Card, etc.).

    <Note>
      If your workflow is configured for a **single document type**, this screen is **automatically skipped** — taking the user straight to capture.
    </Note>
  </Step>

  <Step title="ID capture with intelligent retries">
    The user photographs the front of their document.
    **On-device quality check** — Before submitting, the SDK checks for glare, blur, and cutoff edges. If a problem is detected, the user is prompted to retake.

    **Backend validation with guided retry** — Once submitted:

    * **Pass** → proceed to liveness
    * **Fail** → the user sees specific instructions (e.g., "Document expired", "MRZ unreadable — retake in stronger light") rather than a generic error

    This self-serve retry loop significantly increases pass-through rates. See the full list of validation outcomes under [ID Verification Warnings](/core-technology/id-verification/warnings-id-verification).
  </Step>

  <Step title="Liveness + face match">
    A selfie liveness check ensures the user is physically present and prevents replay/deepfake attacks. If the user doesn't respond in time, the process **retries once automatically** instead of hard-failing.
  </Step>

  <Step title="Final outcome">
    After all checks complete, the user sees one of three results:

    | Result        | Description                                                         |
    | ------------- | ------------------------------------------------------------------- |
    | **Approved**  | All checks passed. Data is extracted and available via API/webhook. |
    | **Declined**  | The system determined the verification cannot be approved.          |
    | **In Review** | Automated checks were inconclusive — requires manual review.        |
  </Step>
</Steps>

By combining smart UX, progressive validation, actionable feedback, and graceful retries, the Didit verification journey keeps good users moving and keeps bad actors out — without manual intervention.


# Didit Documentation
Source: https://docs.didit.me/index

One API for KYC, KYB, transaction monitoring, and wallet screening across 220+ countries and 14,000+ documents, with 500 free verifications/month.

## The best way to integrate identity and fraud checks into your app

<VideoEmbed title="Didit in 5 minutes: one API for identity and fraud" />

Didit is infrastructure for identity and fraud. One API and one console cover User Verification (KYC), Business Verification (KYB), Transaction Monitoring, and Wallet Screening (KYT), so you can verify a person, verify a company, and keep watching the money after onboarding without stitching vendors together. Every account gets 500 free verifications a month; after that you pay per use, and the full KYC bundle (ID, passive liveness, face match, and IP analysis) costs \$0.33. The five-minute video above walks the whole arc: build a workflow, run a verification, read the verdict, keep monitoring.

<StatGrid>
  <StatCard label="Countries & territories" />

  <StatCard label="Document types" />

  <StatCard label="Languages" />

  <StatCard label="Real-time inference (p99)" />
</StatGrid>

<SectionHeader label="Outcomes" title={<>Companies integrating Didit <span>achieve</span></>} description="Real results from production customers, improving every day." />

<StatGrid>
  <StatCard label="False positives & manual reviews" />

  <StatCard label="Fraud reduction" />

  <StatCard label="Faster time to verify" />

  <StatCard label="Identity verification costs" />
</StatGrid>

<SectionHeader label="Built for the AI era" title={<>Identity verification for the <span>AI era</span></>} description="Four pillars that separate Didit from pre-AI legacy providers." />

<FeatureGrid>
  <FeatureCard icon="building-columns" title="Government-attested security" description="Attested by Spain's Treasury and SEPBLAC, after a year-long test alongside the Bank of Spain and CNMV, as safer than in-person verification. No other provider has that." />

  <FeatureCard icon="gauge-high" title="Sub-2-second inference" description="p99 real-time inference under 2 seconds. A full KYC flow completes in under 30 seconds, about 3× faster than the market." />

  <FeatureCard icon="code" title="Developer-first & agent-native" description="Self-serve sandbox, one-prompt SDK integration via Claude Code or any AI agent, and a hosted MCP server with 115 tools for agentic flows." />

  <FeatureCard icon="money-bill" title="$0.33 full KYC · 500 free/month" description="ID, passive liveness, face match, and IP analysis together cost $0.33 per verification, with volume discounts. No minimums, no sales calls, no contracts." />
</FeatureGrid>

<SectionHeader label="How you integrate" title={<>Open, programmable, and <span>transparent</span></>} description="Pick the surface that fits your stack and go from sandbox to production in minutes." />

<FeatureGrid>
  <FeatureCard icon="user" title="Self-serve from minute one" description="No sales calls, no contracts, no minimums." href="https://business.didit.me" />

  <FeatureCard icon="cube" title="60-second sandbox" description="Live at business.didit.me instantly." href="/getting-started/quick-start" />

  <FeatureCard icon="wand-magic-sparkles" title="Integration with one prompt" description="Claude Code or any AI agent wires Didit in a single prompt." href="/integration/integration-prompt" />

  <FeatureCard icon="plug" title="MCP server" description="115 hosted tools over OAuth. Build workflows and query sessions from Claude or ChatGPT." href="/integration/mcp/overview" />

  <FeatureCard icon="code-branch" title="SDKs for every platform" description="Web, iOS, Android, React Native, Flutter." href="/integration/sdks" />

  <FeatureCard icon="palette" title="White-label customization" description="Full UI to match your brand and custom domain." href="/console/white-label" />
</FeatureGrid>

<CardGroup>
  <Card title="Quick Start" icon="rocket" href="/getting-started/quick-start">
    Go from zero to first live verification in 3 simple steps.
  </Card>

  <Card title="API Authentication" icon="key" href="/getting-started/api-authentication">
    Learn how to authenticate your API requests with x-api-key.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/integration/webhooks">
    Receive real-time verification status updates.
  </Card>

  <Card title="SDKs" icon="code" href="/integration/sdks">
    Web, iOS, Android, auth engines, and platform integrations.
  </Card>
</CardGroup>

<SectionHeader label="Didit Academy" title={<>Learn the platform on <span>video</span></>} description="Ten screen-recorded lessons on YouTube, filmed inside the real console. Chapters from these lessons are embedded throughout the docs, cued to the section you are reading." />

<FeatureGrid>
  <FeatureCard icon="circle-play" title="What Is Didit? (11 min)" description="The console, the credit model, and how the product lines share one customer lifecycle." href="https://www.youtube.com/watch?v=skV9iUR2UhQ" />

  <FeatureCard icon="circle-play" title="What Your Users Actually See (15 min)" description="The hosted verification flow end to end: branding, capture, liveness, and every outcome screen." href="https://www.youtube.com/watch?v=LzGe-dMWjUw" />

  <FeatureCard icon="circle-play" title="Build Your First Verification Flow (19 min)" description="Workflows from template to publish: nodes, rules, branching, pricing, and white-labelling." href="https://www.youtube.com/watch?v=7-nJ3JE20i4" />

  <FeatureCard icon="circle-play" title="Use Didit with MCP (11 min)" description="Connect the hosted MCP server to Claude or ChatGPT and build a KYC workflow from one prompt." href="https://www.youtube.com/watch?v=I3UkFIhW548" />

  <FeatureCard icon="circle-play" title="How to Read a Verification Result (14 min)" description="Every check in a real session: warnings, scores, and what to trust when you review." href="https://www.youtube.com/watch?v=7htTWCWsl60" />

  <FeatureCard icon="circle-play" title="Verify a Business (KYB) (11 min)" description="A business verification start to finish: registry check, UBOs, AML, and linked KYC sessions." href="https://www.youtube.com/watch?v=JEnW_sEe35Y" />

  <FeatureCard icon="circle-play" title="Catch Fraud in Real Time (13 min)" description="The transaction rule engine: triggers, conditions, velocity rules, back-testing, and crypto monitoring." href="https://www.youtube.com/watch?v=Yhm63_n7HuU" />

  <FeatureCard icon="circle-play" title="The Complete Integration Guide (8 min)" description="SDK, API, and webhooks wired up in one sitting, including the AI setup prompt and the signing secret." href="https://www.youtube.com/watch?v=fX03-WEu_EI" />

  <FeatureCard icon="circle-play" title="Analytics, Teams & Roles (7 min)" description="Where analytics live, the audit log, applications and environments, and the five built-in roles." href="https://www.youtube.com/watch?v=sRcOBxjRYag" />

  <FeatureCard icon="circle-play" title="How Much Does Didit Cost? (9 min)" description="The free plan, pay-per-use pricing, and how a workflow's price adds up." href="https://www.youtube.com/watch?v=aTWy1rfChhI" />
</FeatureGrid>

<SectionHeader label="Product lines" title={<>From onboarding to <span>continuous trust</span></>} description="One platform covering the entire identity lifecycle: onboard, verify, monitor, and screen." />

<FeatureGrid>
  <FeatureCard icon="user-plus" title="User Verification (KYC)" description="Customer onboarding (KYC/AML), revalidation and re-verification, employee lifecycle, and biometric 2FA. 14,000+ document types, 220+ countries." href="/sessions-api/overview" />

  <FeatureCard icon="building" title="Business Verification (KYB)" description="Company registry lookup, UBO and ownership, officers and directors, entity and person-level AML, and document collection, all from a single workflow. From $2.00 per check, priced per country and tier." href="/business-verification/overview" />

  <FeatureCard icon="arrow-right-arrow-left" title="Transaction Monitoring" description="Real-time transaction screening with rule-based scoring, velocity checks, AML screening, case management, travel rule messaging, and automated remediation. $0.02 per transaction." href="/transaction-monitoring/overview" />

  <FeatureCard icon="link" title="Wallet Screening (KYT)" description="Crypto screening at $0.15 per check: wallet risk scoring, source-of-funds analysis, exposure graphs, and sanctions and mixer exposure." href="/core-technology/wallet-screening/overview" />
</FeatureGrid>

<SectionHeader label="Sessions" title={<>Hosted verification <span>flows</span></>} description="Our preferred integration method. Didit A/B tests the hosted flow continuously, so completion rate, speed, and fraud resistance improve without you shipping UI." />

<FeatureGrid>
  <FeatureCard icon="play" title="Create Session" description="Start a verification session programmatically and get a unique URL for your users." href="/sessions-api/create-session" />

  <FeatureCard icon="diagram-project" title="Workflow Builder" description="Design no-code verification flows with drag-and-drop. Combine ID, liveness, AML, and more." href="/console/workflows" />

  <FeatureCard icon="magnifying-glass" title="Retrieve Session" description="Get the full verification result including all decisions and extracted data." href="/sessions-api/retrieve-session" />

  <FeatureCard icon="bell" title="Webhooks" description="Receive real-time notifications when verification status changes." href="/integration/webhooks" />
</FeatureGrid>

<SectionHeader label="Standalone APIs" title={<>Call any check <span>directly</span></>} description="No session required. Send a request, get a result. Perfect for backend-to-backend integrations." />

<FeatureGrid>
  <FeatureCard icon="id-card" title="ID Verification" description="Verify identity documents across 220+ countries and 14,000+ document types with AI-powered OCR." href="/standalone-apis/id-verification" />

  <FeatureCard icon="face-smile" title="Passive Liveness" description="Detect deepfakes, masks, and spoofing attacks with a single selfie. No user interaction needed." href="/standalone-apis/passive-liveness" />

  <FeatureCard icon="user-check" title="Face Match (1:1)" description="Compare a selfie to an ID photo and get a similarity score in milliseconds." href="/standalone-apis/face-match" />

  <FeatureCard icon="shield-check" title="AML Screening" description="Screen against global sanctions, PEP, watchlists, and adverse media databases in real time." href="/standalone-apis/aml-screening" />

  <FeatureCard icon="cake-candles" title="Age Estimation" description="Estimate a user's age from a selfie with built-in liveness check." href="/standalone-apis/age-estimation" />

  <FeatureCard icon="house" title="Proof of Address" description="Verify residential address documents with automatic data extraction." href="/standalone-apis/proof-of-address" />
</FeatureGrid>

<SectionHeader label="Core Technology" title={<>Deep-dive into each <span>module</span></>} description="Understand how each verification technology works, what data it returns, and how to interpret results." />

<FeatureGrid>
  <FeatureCard icon="passport" title="ID Verification" description="14,000+ document types, 48+ languages, AI-powered OCR and authenticity checks." href="/core-technology/id-verification/overview" />

  <FeatureCard icon="video" title="Liveness Detection" description="Active and passive liveness detection to prevent spoofing and presentation attacks." href="/core-technology/liveness/overview" />

  <FeatureCard icon="magnifying-glass" title="AML Screening" description="Sanctions, PEP, adverse media, and continuous monitoring with risk scoring." href="/core-technology/aml-screening/overview" />

  <FeatureCard icon="microchip" title="NFC Verification" description="Read cryptographic data directly from e-passport and e-ID NFC chips." href="/core-technology/nfc-verification/overview" />

  <FeatureCard icon="database" title="Database Validation" description="Validate identity data against authoritative government and commercial databases." href="/core-technology/database-validation/overview" />

  <FeatureCard icon="recycle" title="Reusable KYC" description="Share verification results across partners, with no re-verification needed." href="/core-technology/reusable-kyc/overview" />
</FeatureGrid>

***

## Need Help?

Our team is available to help you get up and running.

<CardGroup>
  <Card title="WhatsApp Support" icon="comments" href="https://wa.me/+19544659728">
    Fastest response: reach us directly on WhatsApp.
  </Card>

  <Card title="Email" icon="envelope" href="mailto:hello@didit.me">
    Send us an email at [hello@didit.me](mailto:hello@didit.me).
  </Card>
</CardGroup>


# API Full Flow
Source: https://docs.didit.me/integration/api-full-flow

End-to-end Didit REST API integration: get credentials, create a session, share the link, handle webhooks, and retrieve KYC decisions in minutes.

This guide walks you through the complete flow for integrating Didit identity verification via the REST API: get credentials, create a session, present it to the user, and receive results.

***

## Step 1: Get Your Credentials

You have two ways to obtain an `api_key`:

### Option A: Programmatic registration (no browser)

Best for CI/CD and AI agents. Two API calls — `POST /programmatic/register/` then `POST /programmatic/verify-email/` — return the `api_key` inline.

→ See [Programmatic Registration](/integration/programmatic-registration) for the full flow, password rules, JWT lifetime, and lockout policy.

### Option B: From the Didit Console

1. Go to the [Didit Console](https://business.didit.me).
2. Create or select your organization.
3. Navigate to **Settings** → **API & Webhooks**.
4. Copy:
   * **API Key** — used as the `x-api-key` header on every verification call.
   * **Webhook Secret Key** — used to verify webhook HMAC signatures.

### Environment variables

```bash theme={null}
# Required
DIDIT_API_KEY=your_api_key_here
DIDIT_WEBHOOK_SECRET=your_webhook_secret_here

# Your workflow ID (from the Console)
DIDIT_WORKFLOW_ID=your_workflow_id_here
```

***

## Step 2: Create a Workflow

Before creating sessions, you need a verification workflow. Workflows define what verification steps users go through.

### Create in Console

1. Go to [Didit Console](https://business.didit.me) → **Workflows**
2. Click **Create Workflow**
3. Choose a base template:

| Template                      | Best For                                    |
| ----------------------------- | ------------------------------------------- |
| **KYC**                       | Full identity verification with ID document |
| **Adaptive Age Verification** | Age verification with optional ID backup    |
| **Biometric Authentication**  | Re-verifying returning users                |
| **Address Verification**      | Proof of address verification               |

4. Add optional features:

| Feature              | Description                         |
| -------------------- | ----------------------------------- |
| NFC Verification     | Read passport/ID chip data          |
| Liveness Detection   | Prevent spoofing with selfie video  |
| Face Matching        | Match selfie to document photo      |
| Phone Verification   | Verify phone number via SMS         |
| Email Verification   | Verify email address                |
| AML Screening        | Check against sanctions/PEP lists   |
| Database Validation  | Verify against government databases |
| Device & IP Analysis | Detect VPNs, proxies, geolocation   |

5. Copy your **Workflow ID**

<Note>
  See [Workflows Documentation](/console/workflows) for detailed
  configuration options.
</Note>

***

## Step 3: Create a Verification Session

Call the API to create a session for your user.

### Request

```bash theme={null}
curl -X POST https://verification.didit.me/v3/session/ \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "workflow_id": "your-workflow-id",
    "callback": "https://yourapp.com/verification-complete",
    "vendor_data": "user-123"
  }'
```

### Request Parameters

| Parameter          | Required    | Description                                                                                                                                                                                                                                                                                                                                                      |
| ------------------ | ----------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `workflow_id`      | Yes         | Your workflow UUID from the Console.                                                                                                                                                                                                                                                                                                                             |
| `callback`         | No          | URL the user is sent to after verification. Didit appends `verificationSessionId` and `status` as query parameters. Supports custom schemes (e.g. `myapp://`). Falls back to the workflow's configured callback URL when omitted.                                                                                                                                |
| `callback_method`  | No          | Which device handles the redirect: `initiator`, `completer`, or `both`. Default: `initiator`.                                                                                                                                                                                                                                                                    |
| `vendor_data`      | No          | Your internal user identifier — echoed in webhooks for correlation.                                                                                                                                                                                                                                                                                              |
| `metadata`         | No          | Arbitrary JSON object stored with the session and echoed back in webhooks.                                                                                                                                                                                                                                                                                       |
| `language`         | No          | UI language hint (ISO 639-1, e.g. `en`, `es`). Browser language is auto-detected when omitted.                                                                                                                                                                                                                                                                   |
| `contact_details`  | No          | User's email/phone for prefill and email notifications.                                                                                                                                                                                                                                                                                                          |
| `expected_details` | No          | Expected user details for cross-validation against verified data.                                                                                                                                                                                                                                                                                                |
| `portrait_image`   | Conditional | Base64-encoded face image (max 2MB; JPEG, PNG, WebP, or TIFF). Reference face for Biometric Authentication / Face-Match-first workflows. Optional when the `vendor_data` user already has a stored face (approved liveness face, ePassport photo, ID document portrait, or enrolled profile face): Didit reuses it automatically; `400` if neither is available. |
| `sandbox_scenario` | No          | Sandbox-only scenario slug (e.g. `approve`, `decline_aml_hit`) that auto-populates the session with magic inputs.                                                                                                                                                                                                                                                |

### Full Example with All Options

```bash theme={null}
curl -X POST https://verification.didit.me/v3/session/ \
  -H "Content-Type: application/json" \
  -H "x-api-key: YOUR_API_KEY" \
  -d '{
    "workflow_id": "11111111-2222-3333-4444-555555555555",
    "callback": "https://yourapp.com/verification-complete",
    "vendor_data": "user-123",
    "metadata": {
      "plan": "premium",
      "signup_source": "mobile-app"
    },
    "contact_details": {
      "email": "alex.sample@example.com",
      "email_lang": "en",
      "send_notification_emails": true,
      "phone": "+15550101000"
    },
    "expected_details": {
      "first_name": "John",
      "last_name": "Doe",
      "date_of_birth": "1990-01-01",
      "expected_document_types": ["P", "ID"]
    }
  }'
```

<Note>
  `expected_details.expected_document_types` restricts the ID verification step
  to specific document types — the document selection screen only shows the
  requested types. Allowed values: `P` (passport), `ID` (national ID), `DL`
  (driver's licence), `RP` (residence permit), `HIC` (health insurance card),
  `TC` (tax card), `SSC` (social security card). Values are case-insensitive
  and deduplicated; unknown values return `400`. See the
  [Create Session reference](/sessions-api/create-session) for the full schema.
</Note>

### Response

`201 Created`:

```json theme={null}
{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_number": 43762,
  "session_token": "3FaJ9wLqX2Mz",
  "url": "https://verify.didit.me/session/3FaJ9wLqX2Mz",
  "vendor_data": "user-123",
  "metadata": {
    "plan": "premium",
    "signup_source": "mobile-app"
  },
  "status": "Not Started",
  "workflow_id": "11111111-2222-3333-4444-555555555555",
  "workflow_version": 3,
  "callback": "https://yourapp.com/verification-complete"
}
```

### Key Response Fields

| Field              | Description                                                                                                                                                                                                                                                     |
| ------------------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session_id`       | Unique UUID for this session. Use it for `GET /v3/session/{sessionId}/decision/` and webhooks.                                                                                                                                                                  |
| `session_number`   | Human-readable sequence number shown in the Didit console.                                                                                                                                                                                                      |
| `session_token`    | 12-character URL-safe token that authorizes the end user to open the hosted flow, and initialises the native SDKs (the web SDK takes `url` instead). Treat it as a secret.                                                                                      |
| `url`              | Hosted verification URL to redirect the user to, or embed in an iframe. (Field name is `url`, not `verification_url`.) When the request includes `language`, the URL contains a language path segment — e.g. `https://verify.didit.me/en/session/3FaJ9wLqX2Mz`. |
| `status`           | Current status — `"Not Started"` for a newly created session.                                                                                                                                                                                                   |
| `workflow_id`      | Stable workflow identifier the session runs on.                                                                                                                                                                                                                 |
| `workflow_version` | Published workflow version the session was pinned to at creation.                                                                                                                                                                                               |

<Note>
  **Idempotency.** When `vendor_data` is provided and an unfinished session
  (`Not Started`, `In Progress`, `Resubmitted`, or `Awaiting User`) with the
  same `vendor_data` already exists on the workflow's latest published version,
  that existing session is returned (still `201`) instead of creating a
  duplicate — with its `callback` and `metadata` updated to the new values, and
  `status` reflecting the existing session.
</Note>

<Note>
  **Auth errors are `403`, never `401`.** A missing, malformed, or expired
  `x-api-key` returns `403` with
  `{"detail": "You do not have permission to perform this action."}` — the
  same body as a valid key without permission. Insufficient credits return
  `400`. See [Create Session API Reference](/sessions-api/create-session) for
  complete documentation.
</Note>

***

## Step 4: Present Verification to User

Choose how to present the verification flow to your user:

### Option A: Native SDK (recommended for mobile)

Use the `session_token` with the native SDKs for camera, NFC, and biometric integration.

→ [iOS SDK](/integration/native-sdks/ios-sdk) · [Android SDK](/integration/native-sdks/android-sdk) · [React Native](/integration/native-sdks/react-native-sdk) · [Flutter](/integration/native-sdks/flutter-sdk)

### Option B: InContext iframe (recommended for web)

Embed the verification in your page using the `url` returned in Step 3.

```html theme={null}
<iframe
  src="{url}"
  style="width: 100%; height: 700px; border: none;"
  allow="camera; microphone; fullscreen; autoplay; encrypted-media"
></iframe>
```

→ [InContext iframe](/integration/web-sdks/incontext-iframe)

### Option C: Redirect

Redirect the user to the verification URL.

```javascript theme={null}
window.location.href = session.url;
```

→ [Web redirect](/integration/web-sdks/web-redirect)

### Option D: Mobile WebView

For mobile apps without a native SDK.

```jsx theme={null}
// React Native
<WebView source={{ uri: session.url }} />
```

→ [WebView in iOS/Android](/integration/web-sdks/webview-in-ios-android)

***

## Step 5: Receive Results

### Via Webhook (Recommended)

Webhooks notify your server in real-time when verification status changes.

**Setup:**

1. Create a webhook destination in the [Console](https://business.didit.me) (**API & Webhooks**) or via [`POST /v3/webhook/destinations/`](/management-api/webhook/create-destination) with `webhook_version: "v3"` and a `subscribed_events` array (e.g. `["status.updated"]`)
2. Store the `secret_shared_key` returned on creation — it is the HMAC secret for all signature variants
3. Implement a webhook endpoint on your server

**Example webhook payload:**

Inside `decision`, every per-feature result is delivered as a **plural array** (`id_verifications[]`, `nfc_verifications[]`, `liveness_checks[]`, `face_matches[]`, …) — one entry per node in the workflow. This is the V3 contract and is sacred: never code against a singular `nfc` / `id_verification` / `liveness` key.

```json theme={null}
{
  "event_id": "9c0c8b8a-1111-4222-9333-444444444444",
  "webhook_type": "status.updated",
  "timestamp": 1774970000,
  "created_at": 1774969994,
  "application_id": "11111111-2222-3333-4444-555555555555",
  "environment": "live",
  "session_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "status": "Approved",
  "workflow_id": "22222222-3333-4444-5555-666666666666",
  "workflow_version": 4,
  "vendor_data": "user-123",
  "metadata": { "plan": "premium" },
  "decision": {
    "session_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "status": "Approved",
    "id_verifications": [
      { "node_id": "id_verification_1", "status": "Approved", "document_type": "Passport", "warnings": [] }
    ],
    "liveness_checks": [
      { "node_id": "liveness_1", "status": "Approved", "method": "PASSIVE", "score": 95.4, "warnings": [] }
    ],
    "face_matches": [
      { "node_id": "face_match_1", "status": "Approved", "score": 96.1, "warnings": [] }
    ],
    "reviews": []
  }
}
```

The `decision` object is only present when `status` is `Approved`, `Declined`, `In Review`, or `Abandoned` (a `Resubmitted` event carries `resubmit_info` instead). Didit reuses the same `event_id` across retries and fan-out destinations — key your idempotency on it. See [Data models](/reference/data-models) for every plural array and field.

**Verify the signature (X-Signature-V2, recommended):**

`X-Signature-V2` is HMAC-SHA256 over a canonical re-encoding of the JSON body: whole-valued floats shortened to ints, keys sorted recursively, compact separators, Unicode preserved.

```javascript theme={null}
const crypto = require("crypto");

// Match Didit's float normalisation: whole-valued floats serialise as ints.
function shortenFloats(data) {
  if (Array.isArray(data)) return data.map(shortenFloats);
  if (data !== null && typeof data === "object") {
    return Object.fromEntries(
      Object.entries(data).map(([key, value]) => [key, shortenFloats(value)])
    );
  }
  return data;
}

// Sort object keys recursively before re-stringifying.
function sortKeys(obj) {
  if (Array.isArray(obj)) return obj.map(sortKeys);
  if (obj !== null && typeof obj === "object") {
    return Object.keys(obj).sort().reduce((acc, key) => {
      acc[key] = sortKeys(obj[key]);
      return acc;
    }, {});
  }
  return obj;
}

function verifyWebhook(rawBody, signatureV2, timestamp, secret) {
  // 1. Reject anything older than 5 minutes
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestamp, 10)) > 300) return false;

  // 2. Recompute HMAC-SHA256 against the canonical JSON Didit signs
  const canonical = JSON.stringify(sortKeys(shortenFloats(JSON.parse(rawBody))));
  const expected = crypto.createHmac("sha256", secret).update(canonical, "utf8").digest("hex");

  // 3. Constant-time compare
  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(signatureV2, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}
```

→ [Full webhooks documentation](/integration/webhooks), including the raw-bytes `X-Signature`, the deprecated envelope-only `X-Signature-Simple`, and how to pick. Didit retries failed deliveries (`5xx`, `404`, timeout) up to 2 times (\~1 min, then \~4 min) and times out after **5 seconds** — return `2xx` fast.

### Via API (optional)

Fetch the same decision payload at any time:

```bash theme={null}
curl https://verification.didit.me/v3/session/{session_id}/decision/ \
  -H "x-api-key: YOUR_API_KEY"
```

The response shape (plural arrays) is identical to the `decision` object inside the webhook payload, and the endpoint can be called at any point in the session lifecycle. Use webhooks for real-time updates and reserve API calls for backfill, audit, and rebuilds — the `/decision/` endpoint is rate-limited to 600 GET requests/min per API key (see [Rate limiting](/integration/rate-limiting)). Error semantics: an unknown `session_id` returns `404` with `{"detail": "Not found."}`; authentication failures surface as `403` — this endpoint never returns `401`. Media URLs in the response are short-lived presigned links — fetch them promptly rather than persisting them.

→ [Retrieve session API reference](/sessions-api/retrieve-session)

***

## Complete Code Examples

### Node.js / Express

```javascript theme={null}
const express = require("express");
const crypto = require("crypto");
const app = express();

// Create verification session
app.post("/api/verify", async (req, res) => {
  const { userId } = req.body;

  const response = await fetch("https://verification.didit.me/v3/session/", {
    method: "POST",
    headers: {
      "x-api-key": process.env.DIDIT_API_KEY,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      workflow_id: process.env.DIDIT_WORKFLOW_ID,
      callback: `${process.env.APP_URL}/verification-complete`,
      vendor_data: userId,
    }),
  });

  const session = await response.json();

  // Store session_id associated with user
  await db.users.update({
    where: { id: userId },
    data: { verificationSessionId: session.session_id },
  });

  res.json({
    verificationUrl: session.url,             // hosted verification URL
    sessionToken: session.session_token,      // for native/web SDKs
  });
});

// Handle webhook — uses verifyWebhook / shortenFloats / sortKeys from Step 5
app.post(
  "/api/webhook",
  express.raw({ type: "application/json" }),
  (req, res) => {
    const signature = req.get("X-Signature-V2");
    const timestamp = req.get("X-Timestamp");

    if (
      !verifyWebhook(
        req.body.toString("utf8"),
        signature,
        timestamp,
        process.env.DIDIT_WEBHOOK_SECRET,
      )
    ) {
      return res.status(401).json({ error: "Invalid signature" });
    }

    const payload = JSON.parse(req.body);
    const { event_id, session_id, status, vendor_data } = payload;

    // Idempotency: the same event_id is reused on retries and fan-out.
    // Skip events you have already processed (e.g. a processed_events table).

    // Update user's verification status (status values are case-sensitive strings)
    if (status === "Approved") {
      db.users.update({
        where: { id: vendor_data },
        data: { isVerified: true, verifiedAt: new Date() },
      });
    }

    // Return 2xx quickly (Didit's delivery timeout is 5s); do heavy work asynchronously
    res.json({ received: true });
  },
);

app.listen(3000);
```

### Python / FastAPI

```python theme={null}
from fastapi import FastAPI, Request, HTTPException
import httpx
import hashlib
import hmac
import json
import os
import time

app = FastAPI()

@app.post("/api/verify")
async def create_verification(user_id: str):
    async with httpx.AsyncClient() as client:
        response = await client.post(
            "https://verification.didit.me/v3/session/",
            headers={
                "x-api-key": os.environ["DIDIT_API_KEY"],
                "Content-Type": "application/json"
            },
            json={
                "workflow_id": os.environ["DIDIT_WORKFLOW_ID"],
                "callback": f"{os.environ['APP_URL']}/verification-complete",
                "vendor_data": user_id
            }
        )

    session = response.json()
    return {
        "verification_url": session["url"],            # hosted verification URL
        "session_token": session["session_token"],     # for native/web SDKs
    }

def shorten_floats(data):
    """Match Didit: whole-valued floats serialise as ints."""
    if isinstance(data, dict):
        return {k: shorten_floats(v) for k, v in data.items()}
    if isinstance(data, list):
        return [shorten_floats(x) for x in data]
    if isinstance(data, float) and data.is_integer():
        return int(data)
    return data

@app.post("/api/webhook")
async def handle_webhook(request: Request):
    payload = await request.json()
    signature = request.headers.get("X-Signature-V2")
    timestamp = request.headers.get("X-Timestamp")

    # Verify timestamp freshness
    if not signature or not timestamp or abs(int(time.time()) - int(timestamp)) > 300:
        raise HTTPException(status_code=401, detail="Request too old")

    # Recompute Didit's V2 canonical JSON: shortened floats, sorted keys,
    # compact separators, Unicode preserved (ensure_ascii=False)
    canonical = json.dumps(
        shorten_floats(payload),
        sort_keys=True,
        separators=(",", ":"),
        ensure_ascii=False,
    )
    expected = hmac.new(
        os.environ["DIDIT_WEBHOOK_SECRET"].encode("utf-8"),
        canonical.encode("utf-8"),
        hashlib.sha256
    ).hexdigest()

    if not hmac.compare_digest(signature, expected):
        raise HTTPException(status_code=401, detail="Invalid signature")

    # Idempotency: dedupe on payload["event_id"] (reused on retries)

    if payload["status"] == "Approved":
        # Update user in database
        pass

    return {"received": True}
```

***

## Session statuses

These are the 10 possible values of `status` — exact, case-sensitive strings (note `Kyc Expired` uses a single capital `K`):

| Status          | Description                                                   |
| --------------- | ------------------------------------------------------------- |
| `Not Started`   | Session created but user hasn't opened the link yet.          |
| `In Progress`   | User is currently completing verification.                    |
| `In Review`     | Verification flagged for human review.                        |
| `Approved`      | All checks passed.                                            |
| `Declined`      | One or more checks failed.                                    |
| `Resubmitted`   | Reviewer requested specific steps to be redone.               |
| `Awaiting User` | KYB parent session waiting for child KYC parties to finish.   |
| `Abandoned`     | User started but didn't finish in the allotted time.          |
| `Expired`       | Session timed out before the user opened the link.            |
| `Kyc Expired`   | Previously approved session passed its KYC expiration policy. |

See [Verification statuses](/integration/verification-statuses) for the full lifecycle, transitions, and Mermaid diagram.

***

## Next steps

1. **Choose your integration method**:
   * Mobile apps → [Native SDKs](/integration/native-sdks/overview)
   * Web apps → [Web SDKs](/integration/web-sdks/overview)
2. **Configure webhooks**: [Webhooks](/integration/webhooks)
3. **Plan capacity**: [Rate limiting](/integration/rate-limiting)
4. **Handle every status**: [Verification statuses](/integration/verification-statuses)
5. **Customize your workflow**: [Workflows](/console/workflows)
6. **Verify the API is reachable**: [Healthcheck](/api-reference/healthcheck)

## Need help?

* **Support**: [support@didit.me](mailto:support@didit.me)
* **Programmatic onboarding**: [Programmatic registration](/integration/programmatic-registration)


# Live Demos
Source: https://docs.didit.me/integration/demos

Try Didit identity verification live in your browser: KYC, AML, biometric liveness, face authentication, age estimation, and proof of address. Free to test.

<SectionHeader label="Demo Center" title={<>Experience <span>Identity Verification</span></>} description="With Didit, you can build any verification workflow — from simple checks to complex node-based flows with your own custom logic. Mix and match features to fit your needs." />

<div>
  <StatCard label="KYC Plan" />

  <StatCard label="Countries" />

  <StatCard label="Verification" />

  <StatCard label="27001 Certified" />
</div>

<div>
  <StatCard label="Certified" />

  <StatCard label="Languages" />

  <StatCard label="Developer APIs" />

  <StatCard label="Uptime SLA" />
</div>

Explore our most popular pre-built workflows below. Each demo runs on [demos.didit.me](https://demos.didit.me) and gives you a fully interactive preview — **no sign-up required**.

<Note>
  The demo runs the **production** verification engine end to end (document capture, liveness, face match, AML, etc.) — the only differences from a real integration are that the workflow is pre-built and the results are not stored against a customer account. To inspect the API payloads and webhooks behind any workflow, recreate it on your own [test workflow](/console/workflows) and call the [Create Session](/sessions-api/create-session) endpoint with the same `features`.
</Note>

***

## Verification Workflows

<FeatureGrid>
  <FeatureCard icon="id-card" title="Core KYC" description="Standard user onboarding for any industry. ID document verification with liveness detection and face matching." href="https://demos.didit.me" />

  <FeatureCard icon="shield-halved" title="KYC + AML" description="Full compliance workflow for Fintech, Banking, and Crypto Exchanges. Combines identity verification with sanctions & PEP screening." href="https://demos.didit.me" />

  <FeatureCard icon="face-viewfinder" title="Liveness Detection" description="Anti-spoofing liveness check ideal for securing password resets, high-risk transactions, and sensitive account actions." href="https://demos.didit.me" />

  <FeatureCard icon="fingerprint" title="Face Authentication" description="Passwordless biometric login and securing existing user accounts using facial recognition." href="https://demos.didit.me" />

  <FeatureCard icon="lock" title="MFA — Multi-Factor Auth" description="Prevent fake accounts and add a biometric second factor to your authentication flow." href="https://demos.didit.me" />

  <FeatureCard icon="cake-candles" title="Age Check" description="Privacy-preserving age estimation for Social Media, iGaming, and age-restricted E-commerce platforms." href="https://demos.didit.me" />

  <FeatureCard icon="file-invoice" title="Proof of Address (PoA)" description="Enhanced due diligence with document-based address verification for Banking and Fintech." href="https://demos.didit.me" />

  <FeatureCard icon="diagram-project" title="Custom Workflows" description="Build your own complex, node-based verification flows with conditional logic directly from the Business Console." href="/console/workflows" />
</FeatureGrid>

***

## What to expect in each demo

Every demo walks through the same three stages a real user sees in production:

1. **Capture** — Camera permission, ID document upload or photo, and short liveness clip.
2. **Verification** — Real-time OCR, biometric comparison, AML / PEP screening (where applicable), and decision logic.
3. **Result** — Pass / fail / in-review screen. Sample sessions are non-billable and decay after a few minutes.

For technical detail on what runs under the hood, see [Feature Behavior](/core-technology/id-verification/overview) and the [Sessions API reference](/sessions-api/create-session).

***

## Run it locally

Clone the full demo repository to inspect the integration code (Next.js, hosted flow, webhook handler) and run it in your own environment.

<CardGroup>
  <Card title="GitHub repository" icon="github" href="https://github.com/didit-protocol/didit-full-demo">
    Reference Next.js implementation of every workflow on this page — clone, set `DIDIT_API_KEY`, and run.
  </Card>

  <Card title="Demo Center" icon="globe" href="https://demos.didit.me">
    Try all workflows live in your browser — no sign-up required.
  </Card>
</CardGroup>

***

## Next steps

<CardGroup>
  <Card title="Quick start" icon="rocket" href="/getting-started/quick-start">
    Create a workflow, grab an API key, and start your first real session in under five minutes.
  </Card>

  <Card title="SDKs & libraries" icon="code" href="/integration/sdks">
    Web, mobile, and backend SDKs that wrap the demos shown here.
  </Card>
</CardGroup>


# Okta & Auth0 Identity Verification
Source: https://docs.didit.me/integration/engines/okta-auth0-idv

Delegate identity verification to Didit from Okta Identity Engine (BYO IDV) or Auth0, using OpenID Connect with Pushed Authorization Requests.

Didit exposes an OpenID Connect authorization server purpose-built for delegated identity verification.
It implements the contract Okta's "bring your own identity verification vendor" (BYO IDV) framework expects: Pushed Authorization Requests (PAR, RFC 9126), the authorization code flow with PKCE, and an ID token carrying an OpenID Connect `verified_claims` object.

The same endpoints work for any relying party that speaks this profile, including Auth0 post-login Actions.

## Endpoints

Every endpoint lives under the identity verification bridge base URL.

| Environment | Base URL                                |
| ----------- | --------------------------------------- |
| Production  | `https://apx.didit.me/auth/idv`         |
| Sandbox     | `https://apx.staging.didit.me/auth/idv` |

The discovery document at `{base}/.well-known/openid-configuration` advertises all of them:

| Purpose                      | Endpoint                                      |
| ---------------------------- | --------------------------------------------- |
| Pushed Authorization Request | `POST {base}/par`                             |
| Authorization                | `GET {base}/authorize`                        |
| Token                        | `POST {base}/token`                           |
| JWKS                         | `GET {base}/jwks`                             |
| Discovery                    | `GET {base}/.well-known/openid-configuration` |

Client authentication uses `client_secret_basic` or `client_secret_post`.
The authorization code flow requires PKCE with `code_challenge_method=S256`.
ID tokens are signed with RS256; verify them against the JWKS endpoint.

## Flow

1. The relying party pushes the authorization request to `POST /par`, including the PKCE challenge, `state`, `nonce`, its registered `redirect_uri`, the scopes `openid profile identity_assurance`, and the claims it wants verified.
   Didit returns a single-use `request_uri` that is valid for 60 seconds.
2. The relying party redirects the user's browser to `GET /authorize?request_uri=...`.
   Didit creates a verification session and sends the user into the hosted verification flow.
3. When the user finishes, Didit evaluates the verification decision, compares the extracted identity against the claims that were pushed, and returns the user to the relying party's `redirect_uri` with a one-time `code` and the original `state`.
4. The relying party exchanges the code at `POST /token` with its `code_verifier` and receives a signed ID token.

## Requesting claims

Send the claims to compare inside the standard OpenID Connect `claims` parameter of the PAR request.
Both `given_name` and `family_name` are supported, and both are always compared fuzzily.
`verified_claims` is an array, matching Okta's BYO IDV profile and the ID token response below.

```json theme={null}
{
  "id_token": {
    "verified_claims": [
      {
        "verification": {
          "trust_framework": { "value": "IDV-DELEGATED" },
          "assurance_level": { "value": "VERIFIED" }
        },
        "claims": {
          "given_name": { "value": "Lucas", "fuzzy": true },
          "family_name": { "value": "Fraggioli", "fuzzy": true }
        }
      }
    ]
  }
}
```

## The ID token

The ID token carries a `verified_claims` array. `assurance_level` is `VERIFIED` only when the verification session was approved **and** every requested claim matched the verified document.
Otherwise it is `FAILED`.

```json theme={null}
{
  "iss": "https://apx.didit.me/auth/idv",
  "sub": "eea9c5ca-63e6-437b-8e94-131c33f5dce8",
  "aud": "<your client id>",
  "nonce": "<your nonce>",
  "verified_claims": [
    {
      "verification": {
        "trust_framework": "IDV-DELEGATED",
        "assurance_level": "VERIFIED",
        "time": "2026-07-09T11:59:33Z",
        "verification_process": "eea9c5ca-63e6-437b-8e94-131c33f5dce8"
      },
      "claims": {
        "given_name": { "value": "Lucas Agustin", "fuzzy": true },
        "family_name": { "value": "Fraggioli", "fuzzy": true }
      }
    }
  ]
}
```

`verification_process` is the Didit session id, so you can look the verification up in the console or through the sessions API.

<Note>
  Treat the user as verified only when `trust_framework` is `IDV-DELEGATED` **and** `assurance_level` is `VERIFIED`.
  Any other combination means the verification did not succeed.
</Note>

## Configure Okta

In the Okta Admin Console, add a custom identity verification vendor and fill in the values below.
Okta creates the integration as an identity provider of type `IDV_STANDARD` with protocol `ID_PROOFING`, and you then reference it from an Account Management Policy rule.

| Field                     | Value                                     |
| ------------------------- | ----------------------------------------- |
| Issuer                    | `https://apx.didit.me/auth/idv`           |
| PAR request URL           | `https://apx.didit.me/auth/idv/par`       |
| Authorize URL             | `https://apx.didit.me/auth/idv/authorize` |
| Token URL                 | `https://apx.didit.me/auth/idv/token`     |
| JWKS URL                  | `https://apx.didit.me/auth/idv/jwks`      |
| Scopes                    | `openid`, `profile`, `identity_assurance` |
| Client ID / Client secret | Provided by Didit                         |

Give Didit your callback URL so it can be registered on your client.
Okta builds it as `{yourOktaOrgUrl}/idp/identity-verification/callback`.

## Configure Auth0

Auth0 has no native IDV vendor slot, so verification runs from a post-login Action that redirects the user into the same flow.
Store `DIDIT_IDV_BASE`, `DIDIT_CLIENT_ID` and `DIDIT_CLIENT_SECRET` as Action secrets, and register `https://{yourAuth0Domain}/continue` as the redirect URI with Didit.

<Note>
  Auth0 appends its own `state` to the `/authorize` redirect so it can resume the login. Didit adopts that `state` and echoes it back to `/continue`, which is what lets Auth0 complete the transaction - you don't thread Auth0's state through the PAR body (it isn't generated until the redirect).
</Note>

```javascript theme={null}
const crypto = require("crypto");

// Correlate each login's PKCE verifier with its own transaction so a retried
// or overlapping login can't overwrite it (which would fail the token exchange).
const txKey = (event) =>
  event.transaction?.id || event.request?.query?.state || "default";

const basicAuth = (event) =>
  Buffer.from(
    `${event.secrets.DIDIT_CLIENT_ID}:${event.secrets.DIDIT_CLIENT_SECRET}`
  ).toString("base64");

exports.onExecutePostLogin = async (event, api) => {
  if (event.user.app_metadata?.idv_status === "verified") return;

  const verifier = crypto.randomBytes(48).toString("base64url");
  const challenge = crypto.createHash("sha256").update(verifier).digest("base64url");

  const pending = { ...event.user.app_metadata?.idv_pkce };
  pending[txKey(event)] = verifier;
  api.user.setAppMetadata("idv_pkce", pending);

  const params = {
    response_type: "code",
    client_id: event.secrets.DIDIT_CLIENT_ID,
    redirect_uri: `https://${event.request.hostname}/continue`,
    scope: "openid profile identity_assurance",
    code_challenge: challenge,
    code_challenge_method: "S256",
    login_hint: event.user.email ?? "",
  };

  // Ask Didit to match the scanned document against this user's known name, so an
  // approved session for a different person can't mark this account verified.
  if (event.user.given_name && event.user.family_name) {
    params.claims = JSON.stringify({
      id_token: {
        verified_claims: [
          {
            verification: { trust_framework: { value: "IDV-DELEGATED" } },
            claims: {
              given_name: { value: event.user.given_name, fuzzy: true },
              family_name: { value: event.user.family_name, fuzzy: true },
            },
          },
        ],
      },
    });
  }

  const res = await fetch(`${event.secrets.DIDIT_IDV_BASE}/par`, {
    method: "POST",
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
      Authorization: `Basic ${basicAuth(event)}`,
    },
    body: new URLSearchParams(params).toString(),
  });
  if (!res.ok) return api.access.deny("Identity verification is unavailable.");

  const { request_uri } = await res.json();
  api.redirect.sendUserTo(`${event.secrets.DIDIT_IDV_BASE}/authorize`, {
    query: { request_uri, client_id: event.secrets.DIDIT_CLIENT_ID },
  });
};

exports.onContinuePostLogin = async (event, api) => {
  const code = event.request.query.code;
  const pending = { ...event.user.app_metadata?.idv_pkce };
  const key = txKey(event);
  const verifier = pending[key];

  // Consume the verifier so it can't be reused.
  if (key in pending) {
    delete pending[key];
    api.user.setAppMetadata("idv_pkce", pending);
  }
  if (!code || !verifier) return api.access.deny("Identity verification was not completed.");

  const res = await fetch(`${event.secrets.DIDIT_IDV_BASE}/token`, {
    method: "POST",
    headers: {
      "Content-Type": "application/x-www-form-urlencoded",
      Authorization: `Basic ${basicAuth(event)}`,
    },
    body: new URLSearchParams({
      grant_type: "authorization_code",
      code,
      code_verifier: verifier,
      redirect_uri: `https://${event.request.hostname}/continue`,
    }).toString(),
  });
  if (!res.ok) return api.access.deny("Identity verification could not be confirmed.");

  const { id_token } = await res.json();
  // This token comes directly from Didit's token endpoint over TLS with client
  // authentication (the trusted back-channel), so decoding is sufficient here.
  // For defense-in-depth, verify the RS256 signature against the JWKS endpoint
  // (plus iss / aud / exp / nonce) before trusting it.
  const payload = JSON.parse(Buffer.from(id_token.split(".")[1], "base64url").toString());
  const verification = payload.verified_claims?.[0]?.verification ?? {};

  if (verification.trust_framework === "IDV-DELEGATED" && verification.assurance_level === "VERIFIED") {
    api.user.setAppMetadata("idv_status", "verified");
    api.user.setAppMetadata("idv_session", verification.verification_process ?? null);
  } else {
    api.access.deny("Identity verification failed.");
  }
};
```

<Note>
  Store the PKCE `code_verifier` per login transaction (keyed by `event.transaction.id`), not in a single `app_metadata` field.
  If a user retries or runs an overlapping login, a single shared field gets overwritten and the token exchange fails with `invalid_grant`.
</Note>

## Errors

Errors follow RFC 6749 and RFC 9126.
Failed client authentication returns `401` with `{"error": "invalid_client"}`; an expired or replayed `request_uri` or authorization code returns `400` with `invalid_request` or `invalid_grant`.

Authorization codes, `request_uri` values, and verification sessions are all single use.


# No-Code Engine Integrations
Source: https://docs.didit.me/integration/engines/overview

Connect Didit identity verification to no-code automation engines like Zapier — trigger KYC sessions and react to results across 6,000+ apps, no code needed.

This section covers Didit's **no-code engine integrations** — pre-built apps for automation platforms that let you trigger verifications and listen to results without writing backend code.

If you already write code against the [Sessions API](/sessions-api/create-session) or use one of the [SDKs](/integration/sdks), you do not need an engine — engines are designed for teams that want to wire Didit into operations tools (CRM, forms, spreadsheets, Slack) through drag-and-drop automation.

## Supported engines

<CardGroup>
  <Card title="Zapier" icon="bolt" href="/integration/engines/zapier">
    Connect Didit to **6,000+ apps** through Zapier. Create verification sessions, listen for status changes, and retrieve results — all through Zaps. **Available today.**
  </Card>

  <Card title="More engines" icon="hourglass-half" href="https://wa.me/+19544659728">
    Make.com, n8n, Workato, and Power Automate are on the roadmap. Need one urgently? Ping us on WhatsApp and we will prioritise it.
  </Card>
</CardGroup>

<Note>
  **Zapier is the only fully maintained engine integration today.** Until more engines ship, the recommended path for non-Zapier automation platforms is to use [Webhooks](/integration/webhooks) plus a generic "HTTP" or "Webhook" step in your tool of choice.
</Note>

## When to choose an engine integration

| You want to…                                                           | Best fit                                                            |
| ---------------------------------------------------------------------- | ------------------------------------------------------------------- |
| Trigger a KYC session from a Google Form, Typeform, or HubSpot contact | **Zapier**                                                          |
| Push verification results into a spreadsheet, CRM, or Slack channel    | **Zapier**                                                          |
| Email a custom message when a session is `Approved` or `Declined`      | **Zapier**                                                          |
| Embed verification inside your own product UI                          | [Web SDKs](/integration/sdks)                                       |
| Call the API directly from a backend service                           | [Sessions API](/sessions-api/create-session)                        |
| Get raw webhook events into a no-code tool that has no Didit app       | [Webhooks](/integration/webhooks) + the tool's generic HTTP trigger |

## How engine integrations work

All engine apps wrap the same public REST API under the hood — there is no separate engine-only feature surface:

1. The engine authenticates with your **Didit API Key** (Console → **API & Webhooks**).
2. The engine's **action** steps call `POST /v3/session/` or `GET /v3/session/{sessionId}/decision/` on your behalf.
3. The engine's **trigger** steps subscribe to your Didit [webhooks](/integration/webhooks) — when a session status changes, the engine receives the event and starts your downstream Zap / scenario.

Because engines share the same surface as direct integrations, anything you can do in a Zap, you can also do by calling the API yourself — and the [pricing](/getting-started/quick-start), rate limits, and webhook signature rules are identical.

## Pricing

Engine integrations are **free to use** — there is no Didit surcharge for routing through Zapier or any future engine. You only pay the standard [pay-per-call price](https://didit.me/pricing) for whatever features the underlying session uses (ID verification, AML, liveness, etc.). Your automation tool's own subscription costs (e.g. Zapier tasks) are separate and billed by them.

## Next steps

<CardGroup>
  <Card title="Zapier setup guide" icon="bolt" href="/integration/engines/zapier">
    End-to-end walkthrough: connect your account, build your first Zap, react to results.
  </Card>

  <Card title="Webhooks reference" icon="webhook" href="/integration/webhooks">
    The event payloads and signature scheme every engine subscribes to under the hood.
  </Card>
</CardGroup>


# Zapier
Source: https://docs.didit.me/integration/engines/zapier

Automate identity verification workflows with the Didit Zapier app. Trigger verifications and listen to results in 6,000+ apps. Pay-per-use pricing.

Connect Didit to **6,000+ apps** through Zapier — no code required. Automatically create verification sessions, react to status changes, and sync results with your CRM, database, or communication tools.

<Card title="Open Didit on Zapier" icon="bolt" href="https://zapier.com/apps/didit/integrations">
  Browse triggers, actions, and ready-made templates on the Zapier marketplace.
</Card>

<VideoEmbed title="Didit Zapier Integration" />

***

## What You Get

<CardGroup>
  <Card title="Create Sessions" icon="plus">
    Trigger verification sessions from form submissions, CRM events, or any Zapier-connected app.
  </Card>

  <Card title="Real-Time Webhooks" icon="bell">
    Receive instant status updates (Approved, Declined, In Review, etc.) as Zapier triggers.
  </Card>

  <Card title="Retrieve Results" icon="magnifying-glass">
    Fetch full session details — ID data, liveness scores, AML hits — on demand.
  </Card>
</CardGroup>

***

## Prerequisites

| Requirement        | Where to get it                                                                                                      |
| ------------------ | -------------------------------------------------------------------------------------------------------------------- |
| **Didit account**  | Sign up at [business.didit.me](https://business.didit.me) — Free KYC plan is enough to test.                         |
| **API Key**        | Console → **API & Webhooks** → copy the production key. The Zapier app authenticates with this key for every action. |
| **Workflow ID**    | Console → **Workflows** → pick the workflow you want to launch (or [create one](/console/workflows)).                |
| **Zapier account** | Free or paid — [zapier.com](https://zapier.com). The free plan handles 100 tasks / month, enough for small pilots.   |

***

## How It Works

<Steps>
  <Step title="Connect Didit to Zapier" icon="plug">
    In Zapier, search for **Didit** in the app directory (or open the [marketplace listing](https://zapier.com/apps/didit/integrations) directly) and connect your account using the **API Key** from Console → **API & Webhooks**.

    <Tip>
      Your API Key authenticates all Didit actions in Zapier. You only need to connect once — all your Zaps share the same connection, and rotating the key in Console invalidates the Zapier connection until you reconnect.
    </Tip>
  </Step>

  <Step title="Set Up a Trigger" icon="bolt">
    Choose what starts your Zap. This can be a **Didit trigger** or any other app:

    | Trigger Source    | Example                                             |
    | ----------------- | --------------------------------------------------- |
    | **Didit webhook** | Session status changes to "Approved"                |
    | **Google Forms**  | New form submission → create a verification session |
    | **HubSpot**       | New contact created → trigger KYC                   |
    | **Stripe**        | New customer → verify identity before payout        |
    | **Typeform**      | Onboarding form completed → start verification      |
  </Step>

  <Step title="Add a Didit Action" icon="play">
    Use one of the available Didit actions (names match the [Zapier marketplace listing](https://zapier.com/apps/didit/integrations)):

    **Create Verification Session** — wraps `POST /v3/session/`

    * Provide the **Workflow ID** of the verification flow to execute.
    * Optionally set a **Callback URL** for the post-verification redirect.
    * Pass **Vendor Data** (e.g. user email or your internal ID) to link the session back to your records.
    * The action returns the new `session_id`, the user-facing `url`, and the initial `status` — use the `url` to send the user to the verification flow.

    **Retrieve Verification Session** — wraps `GET /v3/session/{sessionId}/decision/`

    * Pass a `session_id` to fetch the full verification result.
    * Access ID data, liveness scores, AML results, the final `status`, and any uploaded media URLs.
  </Step>

  <Step title="React to Results" icon="arrows-split-up-and-left">
    Add downstream actions based on the verification outcome:

    | Status        | Suggested Action                                          |
    | ------------- | --------------------------------------------------------- |
    | `"Approved"`  | Update CRM, grant platform access, send welcome email     |
    | `"Declined"`  | Flag in database, notify compliance, send rejection email |
    | `"In Review"` | Create task for compliance team, send Slack notification  |
    | `"Abandoned"` | Send reminder email with a fresh verification link        |
  </Step>
</Steps>

<Frame>
  <img alt="Creating a Didit identity verification session from a Zapier action step" />
</Frame>

***

## Popular Zap Templates

<CardGroup>
  <Card title="Google Forms → Didit → Gmail" icon="envelope">
    User fills onboarding form → verification session created → result emailed to user and admin.
  </Card>

  <Card title="HubSpot → Didit → HubSpot" icon="address-book">
    New contact → trigger KYC → update contact properties with verification status and ID data.
  </Card>

  <Card title="Stripe → Didit → Slack" icon="credit-card">
    New customer → verify identity → notify your team on Slack with the result.
  </Card>

  <Card title="Webhook → Didit → Airtable" icon="table">
    Custom trigger → verify user → log session results in Airtable for compliance records.
  </Card>
</CardGroup>

***

## Available Triggers & Actions

The names below match the current Didit Zapier app on the [marketplace](https://zapier.com/apps/didit/integrations). If you ever see a label that differs slightly inside Zapier itself, trust the Zapier UI — the underlying behavior is the same.

### Triggers (start a Zap)

| Trigger                    | Underlying event                                  | Description                                                                                                                                    |
| -------------------------- | ------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------- |
| **Session Status Updated** | [`status.updated` webhook](/integration/webhooks) | Fires every time a verification session changes status (`Approved`, `Declined`, `In Review`, `Resubmitted`, `Abandoned`, `Kyc Expired`, etc.). |

### Actions (do something)

| Action                            | Underlying endpoint                     | Description                                                                                                                        |
| --------------------------------- | --------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Create Verification Session**   | `POST /v3/session/`                     | Starts a new session with your workflow, optional callback URL, and `vendor_data`. Returns the session URL to share with the user. |
| **Retrieve Verification Session** | `GET /v3/session/{sessionId}/decision/` | Fetches the full decision payload — ID data, liveness, AML hits, and final status — for a given `session_id`.                      |

***

## Things to know

<Warning>
  The Didit Zapier app is intentionally scoped to the **highest-value automation surface**: launching sessions and reacting to status updates. The following are **not** currently exposed through Zapier and require a direct API call:

  * Uploading a document image, video, or POA asset from a Zap step.
  * Decision overrides via [`PATCH /v3/session/{sessionId}/update-status/`](/sessions-api/update-status).
  * KYB-specific endpoints (registries, key people).
  * Webhook event types other than session-level status changes (e.g. `transaction.status.updated`, `user.status.updated`).

  If you need any of these from a no-code tool, drop into the [Sessions API](/sessions-api/create-session) via a Zapier **Webhooks by Zapier** step with your API Key.
</Warning>

***

## Tips & Best Practices

<AccordionGroup>
  <Accordion title="Use Vendor Data to link sessions" icon="link">
    Always pass a unique identifier (email, user ID, or UUID) in the **Vendor Data** field when creating sessions. This lets you match verification results back to the correct user in your system.
  </Accordion>

  <Accordion title="Handle all status outcomes" icon="list-check">
    Build Zap paths (using Zapier's Paths feature) to handle different statuses differently — Approved, Declined, In Review, Resubmitted, Abandoned, and Expired each deserve a tailored response.
  </Accordion>

  <Accordion title="Use Filters to reduce noise" icon="filter">
    Add Zapier Filters to only trigger downstream actions for specific statuses. For example, only send a welcome email when status is `"Approved"`.
  </Accordion>

  <Accordion title="Test before going live" icon="flask">
    Use Zapier's test feature along with Didit's **Try Webhook** button (in Console → API & Webhooks) to validate your Zap end-to-end before processing real users.
  </Accordion>
</AccordionGroup>

***

## Next Steps

<CardGroup>
  <Card title="Quick Start Guide" icon="rocket" href="/getting-started/quick-start">
    Set up your Didit account, create a workflow, and get your API key.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/integration/webhooks">
    Learn about webhook payloads and signature verification for server-side integrations.
  </Card>
</CardGroup>


# Integration Prompt
Source: https://docs.didit.me/integration/integration-prompt

One copy-paste prompt that integrates Didit end-to-end — account creation, SDK install, workflows, Session API, and HMAC webhook verification.

This chapter of the Didit Academy integration lesson picks up at the AI setup prompt.

In the integration Academy lesson, the 1:48 chapter shows the AI setup prompt this page documents, taken straight from the console's integrate tab.

<VideoEmbed title="The AI setup prompt — Didit Academy" />

## One prompt. End-to-end Didit integration.

The fastest way to integrate Didit into any application is to hand this prompt to an AI coding agent. It walks the agent through programmatic account creation, SDK install, workflow setup, session creation, webhooks with HMAC-SHA256 signature verification, and decision handling — every endpoint, header, package name, and price has been cross-checked against the canonical docs on this site.

**How to use:**

1. Open **Claude Code**, **Codex**, **Cursor**, **GitHub Copilot**, **Devin**, or any AI coding agent that can run shell commands.
2. Click **Copy Prompt** below.
3. Paste into your agent's chat.
4. Fill in the `<my_stack>` block with your framework / language / use case.
5. Hit enter.

The agent registers your Didit account, picks the right SDK for your stack, ships the session-creation route, builds the webhook receiver with signature verification + idempotent dedupe, and wires decision-handling logic into your database — usually in one session.

<AgentPromptAccordion title="Didit Integration Prompt (copy and paste)" />

## What the prompt covers

| Step               | What the agent does                                                                                                                                                                                                                                                       |
| ------------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1. Register        | Two API calls to `https://apx.didit.me/auth/v2/programmatic/{register,verify-email}/` — returns the `api_key` (used as `x-api-key` for every verification API call)                                                                                                       |
| 2. Choose approach | Sessions API + SDK (recommended for any user-facing flow) or Standalone APIs (server-to-server, custom UI)                                                                                                                                                                |
| 3. Create workflow | `POST /v3/workflows/` with the canonical body shape: `{workflow_label, features: [{feature: "OCR"}, ...]}` using UPPERCASE feature enums (`face_liveness_method` for LIVENESS: `PASSIVE` / `ACTIVE_3D` / `FLASHING`)                                                      |
| 4. Install SDK     | Picks the right package for your stack: `@didit-protocol/sdk-web`, the iOS SDK via Swift Package Manager (`github.com/didit-protocol/sdk-ios`), `me.didit:didit-sdk` (custom Maven repo, not Maven Central), `@didit-protocol/sdk-react-native`, or `didit_sdk` (Flutter) |
| 5. Create session  | `POST /v3/session/` with `workflow_id`, `vendor_data`, `callback` — frontend opens the returned `url` via SDK / iframe / redirect. Auth failures are uniformly `HTTP 403 {"detail": "..."}`                                                                               |
| 6. Set up webhook  | Registers a `webhook_version: "v3"` destination, builds the receiver with the canonical X-Signature-V2 pipeline (`shortenFloats` → `sortKeys` → `JSON.stringify` → HMAC-SHA256 → constant-time compare) and 5-second response budget                                      |
| 7. Apply decision  | Database-update logic for all 10 session statuses (`Not Started`, `In Progress`, `Awaiting User`, `In Review`, `Approved`, `Declined`, `Resubmitted`, `Abandoned`, `Expired`, `Kyc Expired`) + idempotent dedupe on `event_id` + V3 plural-array decision parsing         |

The prompt also bundles a **module catalogue with public per-feature pricing**, an **operational APIs table** (decision retrieval, status updates, PDF generation, billing, webhook destinations, and more), and the **MCP server install JSON** for `.cursor/mcp.json` / `claude_desktop_config.json`.

## Why this works as a one-prompt integration

* **Self-sufficient.** Every step has a runnable cURL or code snippet — the agent never has to leave the prompt to look up a body shape, header, or endpoint.
* **Canonical.** Each endpoint, header, status literal, and feature-array name is verified against [`openapi-25.json`](/openapi-25.json), [`openapi-auth.json`](/openapi-auth.json), and the live `.mdx` reference pages on this site (linked at the bottom of the prompt).
* **V3 plural-array contract.** The prompt names every `decision.*` array explicitly (`id_verifications[]`, `nfc_verifications[]`, `liveness_checks[]`, `face_matches[]`, `aml_screenings[]`, …) and warns agents off the legacy V2 singular fields, so the integration handles multi-instance workflows (e.g. two ID checks in a step-up flow) from day one.
* **Bounded.** A few thousand tokens — fits in any modern agent context with room left for your stack description and the agent's planning notes.
* **Idempotent.** Tells the agent to dedupe on `event_id` — Didit reuses the **same** `event_id` across retries and fan-out destinations, which is exactly what makes it a stable idempotency key — with `session_id + status + webhook_type` as a fallback compound key.
* **Status-machine complete.** The agent's database-update logic handles every status the production fleet emits — including the KYB-only `Awaiting User` state, the `Resubmitted` flow with `resubmit_info`, and the post-onboarding `Kyc Expired` state most integrators miss.

## See also

* [Programmatic Registration](/integration/programmatic-registration) — the 2-call register / verify-email flow used at the top of the prompt
* [AI Agent Integration (MCP)](/integration/mcp/overview) — full MCP tool catalogue (115 tools) referenced at the bottom of the prompt
* [SDKs Overview](/integration/sdks) — pick the right SDK for your stack
* [Webhooks](/integration/webhooks) — canonical X-Signature-V2 implementation + retry policy
* [Create Session](/sessions-api/create-session) — the request shape the agent uses in step 5
* [Retrieve Session Decision](/sessions-api/retrieve-session) — the V3 plural-array decision shape returned to the agent
* [Verification Statuses](/integration/verification-statuses) — the literal status strings the agent compares against
* [Data Models](/reference/data-models) — canonical per-feature schema for every `decision.*` array
* [Pricing](/getting-started/pricing) — the public per-module prices the prompt references


# Advanced & troubleshooting
Source: https://docs.didit.me/integration/mcp/advanced

Scopes and roles, cross-app/org behavior, the V3 response contract, webhook handling, troubleshooting, security notes, and self-hosting the Didit MCP server.

## Scopes & role permissions

The hosted connector requests two coarse scopes — `didit:management` (workspace operations) and `didit:verification` (running checks). Both boundaries are enforced server-side on every call: the token carries the scopes you approved, and **within them your console role decides what you can do**. Effective access is the intersection, so approving only `didit:verification` keeps the management surface closed even for an `OWNER`:

| Role                 | Can do                                                         |
| -------------------- | -------------------------------------------------------------- |
| `OWNER` / `ADMIN`    | Everything the scopes allow (reads, writes, deletes, billing). |
| `COMPLIANCE_OFFICER` | Reads + compliance writes (reviews, cases, lists).             |
| `DEVELOPER`          | Developer resources (workflows, webhooks, API keys, sessions). |
| `READER`             | Reads only — writes return `403`.                              |

The MCP never escalates beyond your role. A `403` on one tool means your role lacks that permission, not that the whole connection failed.

***

## Cross-app & org resolution

The Didit management API is scoped per application (`/organization/{org}/application/{app}/…`). The MCP resolves scope for you:

* **Single org + app** → resolved automatically; you never pass IDs.
* **Multiple apps** → the cross-app tools (`didit_session_search`, `didit_transaction_search`, `didit_case_search`, `didit_vendor_user_search`, `didit_vendor_business_search`, `didit_analytics`) aggregate over **all** of them in one call, each row tagged with its `organization_id` / `application_id`.
* The per-app list tools (`didit_session_list`, `didit_transaction_list`, …) **auto-span every app** when you don't specify one, so a plain "list my sessions" works even with many apps. Pass `organization_id` + `application_id` to narrow to a single app.

Use `didit_context_get` to see all your organizations and applications (and their IDs) in a single call.

***

## Branching workflows

Simple workflows are a flat list of features. For **conditional logic** — decline on a status, route on an extracted field, gate a step on a match, add a Document-AI request — the MCP drives Didit's **node graph** (the same structure as the console's visual builder). A graph is `{ start_node, nodes }`; each node is a `feature`, `branch`, `status` (terminal), `action`, or `webhook`. Branch rules support operators including **`fuzzy_match`** (string fields, with a `score` 0–100 similarity threshold) on extracted fields like `kyc.extra_fields.profession`, and a `DOCUMENT_AI` feature node requests documents (e.g. proof of funds).

### Editing an existing workflow (recommended)

Real workflows carry **large** feature configs — an OCR `documents_allowed` allow-list can be 150 KB+, plus POA lists and phone-country lists. So **don't** read the whole graph and resend it. Instead edit with small **operations**:

<Steps>
  <Step title="Locate & inspect">
    `didit_workflow_search { workflow_id }` finds it across all your apps. `didit_workflow_get_graph` returns the structure with big configs **summarized** (it never overflows); `didit_workflow_get_field_definitions` lists branchable fields + valid operators.
  </Step>

  <Step title="Edit with ops">
    `didit_workflow_edit_graph` takes a few small ops — `set_next`, `set_node`, `set_branches`, `merge_node_config` — and the MCP fetches the **full graph server-side**, applies them, validates, auto-creates a **draft**, and saves. Your allow-lists are preserved byte-for-byte and never pass through the request. A validation failure returns `applied: false` (nothing saved).
  </Step>

  <Step title="Review & publish">
    It stays a reviewable draft until you `publish` (in the console or via `didit_workflow_publish`). The live version is never touched.
  </Step>
</Steps>

For example, to insert a branch after ID verification that **rejoins your existing pipeline**, you only send: rewire the OCR node's `next` to a new branch, and add the branch + a terminal `Declined` node + a `DOCUMENT_AI` step (whose `next` points back at the original next step). The other 10 nodes — and their allow-lists — are untouched.

> *"After ID verification, if it was declined, decline; if profession ≈ 'Software Engineer' (≥80%), request proof of funds; then continue."* → one `branch` node: `kyc.status == Declined` → a `Declined` status node; `kyc.extra_fields.profession` `fuzzy_match` "Software Engineer" score 80 → a `DOCUMENT_AI` proof-of-funds node → and an **else** path back into the pipeline.

<Note>
  **A branch always needs an explicit else.** The catch-all (the path taken when no condition matches) must be a branch with empty `rules` — e.g. `{ "id": "else", "rules": [], "goto": "<liveness>" }` — not the branch node's bare `next`. The MCP (and the backend) auto-convert a branch node's `next` into an else branch, so a branch never renders as an ambiguous edge with no visible else.
</Note>

To build a **new** workflow from scratch, use `didit_workflow_validate_graph` then `didit_workflow_set_graph` (full graph). Even a plain `didit_workflow_create` is saved as this same node graph — the MCP assembles your `features` list into chained feature nodes ending in an auto-decide status, so the features actually run (it publishes by default; pass `status: "draft"` to keep it unpublished). See [Create Workflow → branching & node-based workflows](/management-api/workflows/create) for the full JSON shape.

### NFC skip-reason branches with MCP

For a new graph, ask:

> *"Create a draft workflow with ID verification followed by NFC. If `nfc.skip_reason` is `DEVICE_WITHOUT_NFC` or `DOCUMENT_WITHOUT_CHIP`, send the session to In Review; otherwise approve it. Keep an explicit else branch and validate the graph before saving."*

The agent should call `didit_workflow_get_field_definitions`, `didit_workflow_validate_graph`, then `didit_workflow_set_graph`. For an existing workflow, ask:

> *"Edit workflow `26d33c04…`: after its NFC node, route any of the six known `nfc.skip_reason` values to In Review and preserve the existing successful-NFC path as the explicit else. Save a draft; do not publish it."*

The agent should call `didit_workflow_search`, `didit_workflow_get_graph`, `didit_workflow_get_field_definitions`, then `didit_workflow_edit_graph`. The edit tool applies small operations server-side, so it preserves unrelated nodes and large allow-lists. See [Create Workflow → Branch on why NFC did not run](/management-api/workflows/create#branch-on-why-nfc-did-not-run) for the six values, `equals`/`in` rules, null behavior, and a complete ordered graph.

### Feature configs and allow-lists

A feature node's `config` restricts what it accepts. The canonical OCR allow-list is per-country → per-document → object: `{ "<ISO3>": { "<CODE>": { "enabled": 1 } } }` (e.g. `{ "ESP": { "P": { "enabled": 1 } } }`). The MCP **normalizes friendlier shapes** for you before validating, so you don't have to hand-write that structure:

| You can pass                                                                                                                                   | Normalized to                                                 |
| ---------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| A doc-type array — `["PASSPORT"]`                                                                                                              | that document for **every** country (passport-only worldwide) |
| Document **names** or **codes** — `PASSPORT`/`P`, `NATIONAL_ID`/`ID`, `DRIVER_LICENSE`/`DL`, `RESIDENCE_PERMIT`/`RP` (also `SSC`, `HIC`, `TC`) | the canonical code                                            |
| An `"ALL"` country key — `{ "ALL": { "P": 1 } }`                                                                                               | applied to every country                                      |
| Scalar flags — `{ "ESP": { "P": 1 } }`                                                                                                         | `{ "ESP": { "P": { "enabled": 1 } } }`                        |
| Omitted entirely                                                                                                                               | all documents, all countries                                  |

`PROOF_OF_ADDRESS`'s `poa_languages_allowed` is the same idea — pass a language array (`["es"]`) or a map (`{ "es": 1 }`). These conveniences apply wherever you give the MCP a feature config: `didit_workflow_create` features, and the node `config`s in `set_graph` / `edit_graph` / `validate_graph`.

***

## Response shape (V3 contract)

Every tool returns the verbatim JSON of the underlying REST endpoint. Two things to know:

* **Synchronous tools** (workflows, billing, standalone `verify_*`, list management) return their final result inline — act on it the same turn.
* **Session creation is asynchronous** — `didit_session_create` returns a `url` the user must complete; the decision arrives by webhook or `didit_session_get_decision`.

Decision keys are **always plural arrays** with a `node_id` per entry (`id_verifications[]`, `liveness_checks[]`, `face_matches[]`, `aml_screenings[]`, `poa_verifications[]`, `phone_verifications[]`, `email_verifications[]`, `database_validations[]`, `reviews[]`, plus KYB `registry_checks[]`, `document_verifications[]`, `key_people_checks[]`). See [Data models](/reference/data-models) and [Verification statuses](/integration/verification-statuses).

***

## Handling webhooks

Let a webhook deliver the final decision to your backend rather than polling from the agent:

1. The agent calls `didit_webhook_create` once with your public HTTPS endpoint, `webhook_version: "v3"`, and `subscribed_events` (typically `["status.updated", "data.updated"]`). The response includes a `secret_shared_key` — store it as `DIDIT_WEBHOOK_SECRET`.
2. Your backend verifies the canonical **X-Signature-V2** header on every delivery: `shortenFloats` → `sortKeys` → `JSON.stringify` (unescaped unicode) → HMAC-SHA256 → `timingSafeEqual`. Reject if `abs(now − X-Timestamp) > 300` seconds.
3. Deduplicate on `event_id`. Return `2xx` within **5 seconds**; move heavy work to a queue.
4. Didit retries on `5xx` / `404` up to **2 times** (\~1 min, then \~4 min), then drops the delivery — replay failed ones from the **Deliveries** tab in the console.

The agent only needs to *wire* the receiver; it doesn't listen itself. Full contract: [Webhooks](/integration/webhooks).

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="The agent calls a tool and gets a 403">
    Re-authenticate: reconnect / re-run *Log in with Didit*. If only *one* tool 403s, your **role** lacks that permission (e.g. a `READER` attempting a write). (Note: the MCP is Bearer/OAuth only — an `x-api-key` is rejected by every tool, so an API key won't fix a 403.)
  </Accordion>

  <Accordion title="A write or delete didn't run">
    Destructive tools require confirmation in your client. Approve the call, or check that the tool's confirmation prompt isn't being auto-denied. `didit_org_reveal_application_api_key`, `didit_session_delete`, and `didit_session_batch_delete` additionally need `confirm: true` in the tool arguments - without it the call is rejected before anything runs.
  </Accordion>

  <Accordion title="'organization_id is required' or no results">
    You likely have multiple apps. Use a `*_search` tool (which spans everything) or run `didit_context_get` and pass the `organization_id` / `application_id` you want.
  </Accordion>

  <Accordion title="Browser didn't open for sign-in (hosted)">
    Some clients (Windsurf, Zed) connect through the `mcp-remote` bridge — make sure `npx -y mcp-remote@latest https://mcp.didit.me/mcp` is in the config. Re-open the client to retrigger the OAuth handshake.
  </Accordion>

  <Accordion title="Tools don't appear in the client">
    Confirm the server connected (most clients show a status dot) and that you completed *Log in with Didit*. Restart the MCP host after editing its config.
  </Accordion>

  <Accordion title="VS Code (or another client) can't discover OAuth / never opens a browser">
    Make sure you're pointed at `https://mcp.didit.me/mcp`, not the bare `https://mcp.didit.me` origin — the resource metadata some clients probe for is served at `/.well-known/oauth-protected-resource/mcp`, scoped to that path. If you're self-hosting, this usually means `MCP_RESOURCE_URI` is set to the origin instead of the full transport URL; see [Self-hosting](#self-hosting).
  </Accordion>
</AccordionGroup>

***

## Security

The MCP acts with your real permissions and can mutate live resources. Keep **"review tool calls before running"** enabled in your client — especially for **Write** and **Destructive** tools (deletes, `org_top_up`, `org_reveal_application_api_key`). The MCP itself stores **no secret** in your config (it uses **Log in with Didit**); and if a tool returns an application API key (a REST credential), don't paste it into a shared chat.

***

## Self-hosting

The server is open source (MIT) — [github.com/didit-protocol/mcp](https://github.com/didit-protocol/mcp). Clone it and run with **Docker** or Node; it always authenticates as a Didit **user** (there is no API-key mode), in either transport:

```bash theme={null}
git clone https://github.com/didit-protocol/mcp.git && cd mcp

# Docker (recommended) — serves /mcp + /healthz on port 3000
docker build -t didit-mcp . && docker run -p 3000:3000 --env-file .env didit-mcp

# …or with Node
npm install && npm run build
node dist/http.js                                          # hosted HTTP/OAuth
DIDIT_ACCESS_TOKEN=<user-access-token> node dist/index.js  # stdio (headless)
```

Base URLs and OAuth endpoints are environment variables with public defaults (`verification.didit.me`, `apx.didit.me`, `business.didit.me`) — override them for a private deployment. See the repository's `README` and `ARCHITECTURE` for the full environment-variable reference and the resource-server / authorization-server split.

`MCP_RESOURCE_URI` must match your deployment's actual Streamable HTTP transport endpoint, including the path — for example `https://your-host.example.com/mcp`, not just the bare origin. The server derives its RFC 9728 protected-resource metadata URL from this value, so a mismatch breaks OAuth discovery for clients (such as VS Code) that request the path-specific metadata document.

***

<CardGroup>
  <Card title="Tools reference" icon="wrench" href="/integration/mcp/tools">
    Every tool, grouped by area.
  </Card>

  <Card title="Examples" icon="comments" href="/integration/mcp/examples">
    Prompts and end-to-end conversations.
  </Card>
</CardGroup>


# Authentication
Source: https://docs.didit.me/integration/mcp/authentication

How the Didit MCP authenticates: Log in with Didit (OAuth 2.1 + PKCE). Enforced scopes, roles, multi-org access, and disconnecting an app.

The Didit MCP authenticates with **Log in with Didit** (OAuth 2.1). It acts as a Didit **user** with your console role's permissions — **there is no API-key mode**.

***

## Log in with Didit

The hosted server (`https://mcp.didit.me/mcp`) is an OAuth 2.1 **resource server**. The **Didit Business Console** (`business.didit.me`) is the **authorization server** that hosts the consent screen and issues tokens. Your MCP client drives the standard flow automatically:

<Steps>
  <Step title="Discover">
    The client connects, gets a `401` with the protected-resource metadata, and discovers the authorization server.
  </Step>

  <Step title="Authorize (PKCE)">
    The client opens `business.didit.me/authorize` with a PKCE challenge. You sign in (or register) and see exactly which permissions are requested.
  </Step>

  <Step title="Consent">
    You approve. The console mints a **separate session for that app** — bound to the app and to the scopes you approved — and returns an authorization code, which the client exchanges for that session's access token (and a refresh token).
  </Step>

  <Step title="Call tools">
    The client sends the access token with every request. The MCP validates it and acts as **you**.
  </Step>
</Steps>

Clients that support **Dynamic Client Registration** (RFC 7591) register themselves automatically — there is nothing to pre-provision on your side. This covers both local clients using a loopback or native callback (Cursor, Windsurf, Gemini CLI, MCP Inspector) and cloud-hosted clients using one of Didit's reviewed callback URLs (Claude, ChatGPT, Grok, VS Code for the Web, Docker MCP Gateway, Mistral, Cloudflare). An unreviewed remote callback is refused with `invalid_redirect_uri` — that client needs an operator to register it first.

### Scopes

The connector requests two coarse scopes, shown in plain language on the consent screen:

| Scope                | Grants                                                                                     |
| -------------------- | ------------------------------------------------------------------------------------------ |
| `didit:management`   | Manage your workspace — workflows, sessions, lists, webhooks, members, billing, analytics. |
| `didit:verification` | Run verifications — KYC, KYB, AML, biometrics, OCR, and the standalone APIs.               |

The scopes you approve are **carried on the token and enforced server-side**, so an app connected with `didit:verification` alone is refused on the management surface even when your own role would allow it. A connection that requests no scope gets identity only (`openid profile email`): it can tell who you are and nothing else.

An app's effective permissions are the **intersection** of the approved scopes and your console role — never the wider of the two. An MCP token also never carries staff privileges, even when the underlying account has them.

### Multi-organization & roles

The hosted token represents **you**, so the agent can work across **every organization you belong to** in a single connection — cross-app tools (`didit_session_search`, `didit_analytics`, `didit_context_get`) aggregate over all of them automatically.

Your **role is always enforced** server-side. A `READER` can list and read but write calls return a permission error; an `OWNER`/`ADMIN` can write. The MCP never grants more than your console role already allows.

### Token lifetime

An approved app gets its **own session**, separate from the browser session you approved it from. Access tokens last 24 hours and the client silently refreshes them with the refresh token, which keeps the app's scopes and stays bound to that app. If a refresh fails (for example after you disconnect the app), the client re-runs **Log in with Didit** on the next call.

Because the app's session is its own, signing out of the console — or logging a device out under **Active sessions** — leaves connected apps working, and disconnecting an app never signs you out anywhere.

### Disconnecting an app

<Steps>
  <Step title="From the console">
    **Settings → Authentication → Connected apps** lists every app you have approved, with its registered name and the permissions it was granted. **Disconnect** ends that app's access immediately: both its access token and its refresh token stop working, and nothing else is affected.
  </Step>

  <Step title="From the app (RFC 7009)">
    A client can hand its own access back by posting the token to the authorization server's `revocation_endpoint`, advertised at `https://business.didit.me/.well-known/oauth-authorization-server`. As RFC 7009 requires, a successful call answers `200` whether or not the token was still live — so the response never tells you whether a token was valid.

    A `503` means the revocation could **not** be applied: treat the token as still valid and retry. Anything else (`400`) is a malformed request or an unregistered `client_id`, and retrying will not help.
  </Step>
</Steps>

```bash theme={null}
curl -X POST https://business.didit.me/api/auth/oauth-revoke \
  -H "Content-Type: application/json" \
  -d '{"token": "<refresh-or-access-token>", "token_type_hint": "refresh_token", "client_id": "<your-client-id>"}'
```

<Note>
  **Why no API key?** Every MCP tool calls the user-scoped console endpoints (`/organization/{org}/application/{app}/…`), which authorize a Bearer token with per-role privileges and **reject `x-api-key`**. An application API key is for calling the [REST API](/openapi-25.json) directly from your own backend (e.g. creating sessions) — not for this MCP. Tools like `didit_org_reveal_application_api_key` manage those REST keys; they are not how the MCP itself authenticates.
</Note>

***

## Auth failures

A `403` means re-authenticate — **reconnect / re-run Log in with Didit**:

```text theme={null}
HTTP 403
{ "detail": "You do not have permission to perform this action." }
```

A `403` on a *specific* tool usually means either your **role** lacks that permission (e.g. a `READER` attempting a write) or the connection was approved **without the scope** that tool needs — not that the whole connection is broken. Reconnecting and approving both scopes fixes the second case; the first needs a role change.

If every tool fails, check **Settings → Authentication → Connected apps** in the console: an app that was disconnected there has to be approved again.

***

<CardGroup>
  <Card title="Tools reference" icon="wrench" href="/integration/mcp/tools">
    What each tool does and which are write/destructive.
  </Card>

  <Card title="Advanced" icon="gear" href="/integration/mcp/advanced">
    Scopes, cross-app behavior, and self-hosting.
  </Card>
</CardGroup>


# Connect Claude to Didit
Source: https://docs.didit.me/integration/mcp/claude

Add the Didit MCP server to Claude in one click. The connector link pre-fills the dialog; you sign in with Didit over OAuth. No API keys, 115 tools.

Claude connects to the hosted Didit MCP server with one link. Click it, confirm the pre-filled dialog, and sign in with your Didit account. There is no API key to copy and nothing to install.

<Card title="Add Didit to Claude" icon="wand-magic-sparkles" href="https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Didit&connectorUrl=https://mcp.didit.me/mcp">
  Opens claude.ai with the Add custom connector dialog pre-filled: name Didit, URL mcp.didit.me/mcp. Confirm, sign in with Didit, done.
</Card>

The full connector link, if you want to share it or put it behind your own button:

```text theme={null}
https://claude.ai/customize/connectors?modal=add-custom-connector&connectorName=Didit&connectorUrl=https://mcp.didit.me/mcp
```

This is the same link the [Business Console](https://business.didit.me) shows on its integrate page.

In the MCP Academy lesson, the 1:42 chapter shows this exact flow: adding the connector in Claude, the OAuth sign-in, and the tools appearing in the chat.

<VideoEmbed title="Adding the connector in Claude — Didit Academy" />

***

## Set up by surface

<Tabs>
  <Tab title="Claude web">
    1. Click [**Add Didit to Claude →**](https://claude.ai/customize/connectors?modal=add-custom-connector\&connectorName=Didit\&connectorUrl=https://mcp.didit.me/mcp). The **Add custom connector** dialog opens with every field filled in.
    2. Confirm the dialog.
    3. Complete **Log in with Didit** in the browser and approve the permissions.

    The Didit tools then show up in the chat's tool menu. If you prefer the manual path: **Settings → Connectors → Add custom connector**, name `Didit`, URL `https://mcp.didit.me/mcp`.
  </Tab>

  <Tab title="Claude Desktop">
    1. **Settings → Connectors → Add custom connector**.
    2. Name it `Didit` and set the URL to:

    ```text theme={null}
    https://mcp.didit.me/mcp
    ```

    3. Click **Connect** and complete **Log in with Didit** in the browser.
  </Tab>

  <Tab title="Claude Code">
    Add the server with the CLI, then trigger the sign-in:

    ```bash theme={null}
    claude mcp add --transport http didit https://mcp.didit.me/mcp
    ```

    Start Claude Code and run `/mcp` — it opens the browser for **Log in with Didit**. After you approve, the `didit` tools are available.
  </Tab>
</Tabs>

<Info>
  **No API key anywhere.** The hosted server uses OAuth 2.1 with PKCE and acts as **you**: every organization you belong to, with your role's permissions, under the `didit:management` and `didit:verification` scopes. See [Authentication](/integration/mcp/authentication).
</Info>

***

## What Claude can do once connected

The hosted server exposes **115 tools** across sessions, workflows, transactions, cases, analytics, and more. Prompts that work on day one:

* "Create a KYC workflow with ID verification, passive liveness, and AML screening, then give me a verification link."
* "Show me the sessions waiting in my review queue and summarize the warnings on each."
* "Write a transaction monitoring rule that flags more than 3 transfers over \$1,000 in an hour, and back-test it against the last 90 days."
* "Which country generated the most declined sessions this month?"

The [MCP Academy lesson](https://www.youtube.com/watch?v=I3UkFIhW548) runs each of these against a live account.

***

## Troubleshooting

* **The dialog opens empty.** You followed a link that lost its query string. Paste the full connector link from this page, or add the connector manually with URL `https://mcp.didit.me/mcp`.
* **Sign-in loops or fails.** Log in at [business.didit.me](https://business.didit.me) first, then reconnect. The MCP server authenticates against the same account.
* **Tools are missing.** Your role in the organization limits which tools appear. An owner or admin sees all 115; narrower roles see fewer. See [Authentication](/integration/mcp/authentication).

***

## Next steps

<CardGroup>
  <Card title="Tools reference" icon="wrench" href="/integration/mcp/tools">
    Everything Claude can call, tool by tool.
  </Card>

  <Card title="Example prompts" icon="comments" href="/integration/mcp/examples">
    Longer worked examples with real payloads.
  </Card>

  <Card title="Other clients" icon="plug" href="/integration/mcp/installation">
    Cursor, VS Code, Windsurf, Zed, and self-hosting.
  </Card>

  <Card title="Authentication" icon="lock" href="/integration/mcp/authentication">
    OAuth flow, scopes, and roles.
  </Card>
</CardGroup>


# Examples
Source: https://docs.didit.me/integration/mcp/examples

Example prompts and end-to-end agent conversations with the Didit MCP — set up a KYC workflow, run cross-app analytics, create sessions, and wire webhooks.

A few patterns that show what the Didit MCP is good at. Phrase things in plain language — the agent picks the tools.

***

## Quick prompts

**Operations & monitoring (cross-app)**

* *"Show me the last 5 in-review sessions across all my apps."* → `didit_session_search`
* *"How many people tried phone verification but dropped off in the last 15 days?"* → `didit_analytics` (one call; reads the feature funnel)
* *"Find the customer with vendor\_data `user_8842` and tell me which app and status."* → `didit_vendor_user_search`
* *"What's my credit balance and this month's conversion rate?"* → `didit_org_get_balance` + `didit_analytics`

**Configuration**

* *"Create a KYC workflow with ID scan + liveness and give me a verification link."* → `didit_workflow_create` → `didit_session_create`
* *"Create an ID-verification workflow that only accepts passports, then a selfie liveness."* → `didit_workflow_create` — just say `documents_allowed: ["PASSPORT"]`; the MCP expands it to passport-only for every country (see [Advanced → feature configs](/integration/mcp/advanced#feature-configs-and-allow-lists)).
* *"New workflow: scan a passport; if the ID is declined, decline the session; if the stated profession is ≈ 'Software Engineer' (≥60%), run a liveness check; otherwise ask for proof of address in Spanish; then auto-decide."* → `didit_workflow_get_field_definitions` → `didit_workflow_validate_graph` → `didit_workflow_set_graph` (a branch on `kyc.status` plus a `fuzzy_match` on `kyc.extra_fields.profession`, with an else path to a POA step)
* *"In workflow `26d33c04…`, after ID verification: if it's declined, decline the session; if the profession is ≥80% similar to 'Software Engineer', add a proof-of-funds Document-AI step; then continue."* → `didit_workflow_search` → `didit_workflow_get_graph` → `didit_workflow_edit_graph` (small ops, saved as a reviewable draft — preserves the existing pipeline + allow-lists)
* *"Create a draft ID + NFC workflow. If NFC did not run because the device has no reader or the document has no chip, send it to review; otherwise approve."* → `didit_workflow_get_field_definitions` → `didit_workflow_validate_graph` → `didit_workflow_set_graph` (`nfc.skip_reason` with `in`, plus an explicit else)
* *"Edit workflow `26d33c04…` so every known NFC skip reason goes to review, while successful NFC keeps its current path. Save a draft only."* → `didit_workflow_search` → `didit_workflow_get_graph` → `didit_workflow_get_field_definitions` → `didit_workflow_edit_graph` (preserves the existing graph and adds an explicit else)
* *"Register a webhook for status updates and show me the signing secret."* → `didit_webhook_create`

**Compliance**

* *"Screen this wallet for AML and add it to the blocklist if it hits."* → `didit_transaction_screen_wallet` + `didit_blocklist_add`
* *"Open a case for session `…` and assign it to me."* → `didit_case_create` → `didit_case_manage`

***

## End-to-end: stand up verification

> **You:** "Set up Didit identity verification for my app with ID scan and liveness."
>
> **Agent:** I'll create the workflow. *(calls `didit_workflow_create` with ID scan + passive liveness)* — Published **"Standard KYC"**, `workflow_id = 6f2c…`. Here's how to create a session from your backend:
>
> ```bash theme={null}
> curl -X POST https://verification.didit.me/v3/session/ \
>   -H "x-api-key: $DIDIT_API_KEY" \
>   -H "Content-Type: application/json" \
>   -d '{ "workflow_id": "6f2c...", "vendor_data": "internal-user-id", "callback": "https://myapp.com/done" }'
> ```
>
> Redirect the user to `response.url`. (That `x-api-key` is your application's **REST API key**, used by your backend to create sessions — it's separate from how you signed in to this MCP, which uses *Log in with Didit*.) Want me to register the webhook destination too?
>
> **You:** "Yes — my endpoint is `https://myapp.com/webhooks/didit`."
>
> **Agent:** *(calls `didit_webhook_create` with `webhook_version: "v3"`, `subscribed_events: ["status.updated"]`)* — Done. Store this signing secret as `DIDIT_WEBHOOK_SECRET`: `whsec_…`. Verify the `X-Signature-V2` header on each delivery before trusting it.

***

## Session results are asynchronous

`didit_session_create` returns a `session_id`, a `session_token`, and a hosted `url` — but the verification hasn't happened yet. The user opens `url` and completes the flow. The final decision arrives via:

1. A `status.updated` **webhook** (recommended), or
2. `didit_session_get_decision` (polling, as a fallback).

Both share the same shape — **always plural arrays** with a `node_id` per entry:

```json theme={null}
{
  "session_id": "uuid",
  "status": "Approved",
  "session_kind": "user",
  "id_verifications":  [ { "node_id": "first_id", "status": "Approved", "first_name": "Jane" } ],
  "liveness_checks":   [ { "node_id": "first_liveness", "status": "Approved", "score": 95.4 } ],
  "face_matches":      [ { "node_id": "first_face_match", "status": "Approved", "score": 96.1 } ],
  "aml_screenings":    [ { "node_id": "first_aml", "status": "Approved", "total_hits": 0, "hits": [] } ],
  "reviews": []
}
```

Never read singular V2 keys (`id_verification`, `liveness`) — they only ship when a destination is explicitly pinned to `webhook_version: "V2"`. See [Data models](/reference/data-models) for the per-feature field reference and [Advanced → Webhooks](/integration/mcp/advanced#handling-webhooks) for verification and retry rules.

***

## Pair it with the one-prompt integration

The MCP is great for *running* Didit. To have an agent *write* a full integration (backend route + frontend SDK + webhook handler + DB schema), hand it the [Integration Prompt](/integration/integration-prompt) — it walks the seven steps and calls MCP tools to create the workflow, session, and webhook live.

***

<CardGroup>
  <Card title="Tools reference" icon="wrench" href="/integration/mcp/tools">
    Everything the agent can call.
  </Card>

  <Card title="Advanced & troubleshooting" icon="gear" href="/integration/mcp/advanced">
    Scopes, cross-app behavior, webhooks, self-hosting.
  </Card>
</CardGroup>


# Install the Didit MCP
Source: https://docs.didit.me/integration/mcp/installation

Connect the Didit MCP server to Claude, Cursor, VS Code, Windsurf, Zed, or any MCP client. One URL, Log in with Didit (OAuth) — no API keys.

Pick your client below. The **hosted** server (`https://mcp.didit.me/mcp`) needs no API key — on first connect your client opens a browser and you **[Log in with Didit](/integration/mcp/authentication)** and approve the permissions.

<Tip>
  **Using Claude?** The [Connect Claude](/integration/mcp/claude) page has the one-click connector link that opens the **Add custom connector** dialog with the name and URL pre-filled, so you only have to confirm and sign in.
</Tip>

<Note>
  Clients that don't yet speak remote/HTTP MCP (Windsurf, Zed) connect through the `mcp-remote` bridge, which forwards stdio to the hosted URL and handles the OAuth handshake for you.
</Note>

***

## Hosted server (recommended)

<Tabs>
  <Tab title="Claude Code">
    Add the server with the CLI, then trigger the sign-in:

    ```bash theme={null}
    claude mcp add --transport http didit https://mcp.didit.me/mcp
    ```

    Start Claude Code and run `/mcp` — it opens the browser for **Log in with Didit**. After you approve, the `didit` tools are available.
  </Tab>

  <Tab title="Claude Desktop">
    1. **Settings → Connectors → Add custom connector**.
    2. Name it `Didit` and set the URL to:

    ```text theme={null}
    https://mcp.didit.me/mcp
    ```

    3. Click **Connect** and complete **Log in with Didit** in the browser.

    The Didit tools then appear in the chat's tool menu.
  </Tab>

  <Tab title="Grok">
    1. Open [grok.com/connectors](https://grok.com/connectors) and click **New Connector → Custom**.
    2. Set the MCP server URL to:

    ```text theme={null}
    https://mcp.didit.me/mcp
    ```

    3. Save and complete **Log in with Didit** in the browser window Grok opens.

    Grok registers itself through Dynamic Client Registration, so there is no client ID or API key to paste.
  </Tab>

  <Tab title="Cursor">
    Add to `~/.cursor/mcp.json` (global) or `.cursor/mcp.json` (per-project):

    ```json theme={null}
    {
      "mcpServers": {
        "didit": {
          "url": "https://mcp.didit.me/mcp"
        }
      }
    }
    ```

    Or use **Settings → Tools & Integrations → New MCP Server**. Cursor opens the browser for sign-in on first use.
  </Tab>

  <Tab title="VS Code">
    With GitHub Copilot agent mode, add `.vscode/mcp.json`:

    ```json theme={null}
    {
      "servers": {
        "didit": {
          "type": "http",
          "url": "https://mcp.didit.me/mcp"
        }
      }
    }
    ```

    Or run **MCP: Add Server** from the command palette and choose **HTTP**. Sign in when prompted.
  </Tab>

  <Tab title="Windsurf">
    Windsurf connects through the `mcp-remote` bridge. Add to `~/.codeium/windsurf/mcp_config.json`:

    ```json theme={null}
    {
      "mcpServers": {
        "didit": {
          "command": "npx",
          "args": ["-y", "mcp-remote@latest", "https://mcp.didit.me/mcp"]
        }
      }
    }
    ```

    Open **Settings → Cascade → MCP Servers → Manage** to confirm it loaded, then sign in via the browser.
  </Tab>

  <Tab title="Zed">
    Add a context server in Zed's `settings.json`:

    ```json theme={null}
    {
      "context_servers": {
        "didit": {
          "source": "custom",
          "command": "npx",
          "args": ["-y", "mcp-remote@latest", "https://mcp.didit.me/mcp"]
        }
      }
    }
    ```

    Zed launches the bridge and opens the browser for **Log in with Didit**.
  </Tab>
</Tabs>

<Info>
  **No API key in the config.** The hosted server authenticates you in the browser and acts as **you** — every organization you belong to, with your role's permissions. See [Authentication](/integration/mcp/authentication).
</Info>

***

## Self-hosting

Want to run the server yourself? It's open source (MIT) — [github.com/didit-protocol/mcp](https://github.com/didit-protocol/mcp). Clone the repo and run it with Docker or Node — host the HTTP/OAuth server or run it over stdio for headless use. It still authenticates as a Didit **user** — there's no API-key mode. See [Advanced → self-hosting](/integration/mcp/advanced#self-hosting).

***

## Next steps

<CardGroup>
  <Card title="Authentication" icon="lock" href="/integration/mcp/authentication">
    Sign-in, scopes, and roles.
  </Card>

  <Card title="Tools reference" icon="wrench" href="/integration/mcp/tools">
    Everything the agent can call.
  </Card>
</CardGroup>


# Didit MCP Server
Source: https://docs.didit.me/integration/mcp/overview

Connect Claude, Cursor, VS Code, Windsurf, and any MCP client to Didit identity verification. Agent-native KYC, KYB, and AML over natural language — hosted (Log in with Didit) or self-hosted.

This Didit Academy lesson connects the hosted MCP server to Claude over OAuth, then builds a KYC workflow from one prompt, queries the review queue, and back-tests transaction rules against 90 days of history.

<VideoEmbed title="Use Didit with MCP — Didit Academy" />

The **Didit MCP server** connects any [Model Context Protocol](https://modelcontextprotocol.io) client — Claude, Cursor, VS Code, Windsurf, Zed, and more — directly to the Didit identity platform. Once connected, an agent can run KYC, KYB, AML screening, transaction monitoring, and full workspace operations (workflows, sessions, lists, webhooks, billing) through natural-language commands.

<Note>
  The Didit MCP is **read-and-write**: agents can create sessions, configure workflows, update statuses, and move credits on your behalf. Every client asks you to review tool calls before they run — keep that on, especially for write and delete actions.
</Note>

***

## Get started in 30 seconds

The fastest path is the **hosted server** — one URL, no API key. Your client opens a browser, you **Log in with Didit**, approve the permissions, and you're connected.

```text Hosted endpoint theme={null}
https://mcp.didit.me/mcp
```

<Tip>
  **On Claude for web**, [**Add Didit to Claude →**](https://claude.ai/customize/connectors?modal=add-custom-connector\&connectorName=Didit\&connectorUrl=https://mcp.didit.me/mcp) pre-fills the connector dialog — confirm, sign in with Didit, done. Full walkthrough on [Connect Claude](/integration/mcp/claude). Source is on [GitHub](https://github.com/didit-protocol/mcp) (MIT).
</Tip>

<CardGroup>
  <Card title="Install in your client" icon="download" href="/integration/mcp/installation">
    Copy-paste setup for Claude, Cursor, VS Code, Windsurf, and Zed.
  </Card>

  <Card title="How sign-in works" icon="key" href="/integration/mcp/authentication">
    "Log in with Didit" (OAuth 2.1) — no API keys, no secrets in config.
  </Card>

  <Card title="Browse the tools" icon="wrench" href="/integration/mcp/tools">
    115 tools across sessions, workflows, AML, Travel Rule, marketplace, lists, webhooks, and billing.
  </Card>

  <Card title="See it in action" icon="comments" href="/integration/mcp/examples">
    Example prompts and end-to-end agent conversations.
  </Card>
</CardGroup>

***

## How it works

The hosted MCP is an OAuth 2.1 **resource server**; the Didit console is the **authorization server**. You connect with one URL, **Log in with Didit** in the browser, and the MCP then acts as **you** — across every organization you belong to, with your console role's permissions.

<Note>
  **The MCP acts as a Didit user, not an application — there is no API-key mode.** Every tool calls the user-scoped console endpoints, which only accept your Bearer token. (To call the raw REST API with an application API key — e.g. creating sessions from your own backend — use the [REST API](/openapi-25.json) directly; that's separate from this MCP.)
</Note>

Prefer to run the server yourself? You can — see [Advanced → self-hosting](/integration/mcp/advanced#self-hosting). It still authenticates the user via OAuth (or a user Bearer for headless runs).

The tools return the verbatim JSON of the underlying Didit endpoints. See [Authentication](/integration/mcp/authentication) for the full picture.

***

## What can you do with it?

Ask in plain language. A few things the agent can do across **all of your apps at once**:

* *"Show me the last 5 in-review sessions across all my apps."*
* *"How many people tried phone verification but dropped off in the last 15 days?"*
* *"Create a KYC workflow with an ID scan and liveness, then give me a verification link."*
* *"Find the customer with vendor\_data `user_8842` — which app are they in and what's their status?"*
* *"Add this wallet to the blocklist and screen it for AML."*
* *"Register a webhook for status updates and show me the signing secret."*
* *"What's my credit balance and conversion rate this month?"*

***

## Built for the agentic era

Most verification platforms require manual console setup. Didit lets an agent do the whole thing — **self-register** an account (no browser, no 2FA on programmatic accounts), **configure workflows**, **create and review sessions**, **wire webhooks**, and **monitor billing** — end to end. Pair the MCP with the [one-prompt integration](/integration/integration-prompt) and an agent can ship a complete integration (backend route + frontend SDK + webhook handler) while calling MCP tools to create the workflow and session live.

<CardGroup>
  <Card title="Installation" icon="download" href="/integration/mcp/installation">
    Per-client setup for Claude, Cursor, VS Code, Windsurf, Zed.
  </Card>

  <Card title="Authentication" icon="lock" href="/integration/mcp/authentication">
    OAuth sign-in, scopes, and roles.
  </Card>

  <Card title="Tools reference" icon="wrench" href="/integration/mcp/tools">
    Every tool, grouped by area.
  </Card>

  <Card title="Advanced & troubleshooting" icon="gear" href="/integration/mcp/advanced">
    Scopes, cross-app behavior, webhooks, self-hosting.
  </Card>
</CardGroup>


# Tools reference
Source: https://docs.didit.me/integration/mcp/tools

Every tool the Didit MCP exposes — sessions, workflows, KYB, AML, transaction monitoring, biometrics, lists, cases, reports, webhooks, billing — grouped by area, with read/write/destructive markers.

The Didit MCP exposes **150 tools** to ordinary users over the hosted OAuth endpoint (156 in the full local catalogue). Together they cover verification, workspace management, transaction monitoring, and reporting operations from the [verification API](/openapi-25.json) and [auth API](/openapi-auth.json). Tool availability still follows your OAuth scopes and console role.

Tools are typed so your client can group and gate them:

| Badge           | Meaning                                                                                      |
| --------------- | -------------------------------------------------------------------------------------------- |
| **Read**        | Safe, read-only.                                                                             |
| **Write**       | Creates or mutates a resource.                                                               |
| **Destructive** | Deletes data, reveals a secret, or moves money — your client asks for explicit confirmation. |

<Note>
  The `didit_verify_*` standalone tools are **billable POST actions** — they consume credits even though some read like a query (e.g. `face_search`, `kyb_search`).
</Note>

***

## Discovery & cross-app

Start here. These span **every organization and application** you can access in a single call, each result tagged with its org/app.

| Tool                           | Type | Description                                                                                                        |
| ------------------------------ | ---- | ------------------------------------------------------------------------------------------------------------------ |
| `didit_context_get`            | Read | List all your organizations and applications in one call. Call this first to discover IDs.                         |
| `didit_session_search`         | Read | Search KYC/KYB sessions across all apps; newest first.                                                             |
| `didit_transaction_search`     | Read | Search transaction-monitoring records across all apps.                                                             |
| `didit_case_search`            | Read | Search investigation/compliance cases across all apps.                                                             |
| `didit_vendor_user_search`     | Read | Find an end customer (by name/email/`vendor_data`) across all apps.                                                |
| `didit_vendor_business_search` | Read | Find a KYB business across all apps.                                                                               |
| `didit_analytics`              | Read | Aggregate analytics over a date window — request breakdown, **feature funnel**, conversion rate — across all apps. |

***

## Sessions (KYC & KYB)

| Tool                            | Type        | Description                                                                                                                                                                                                                                                                                                          |
| ------------------------------- | ----------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `didit_session_create`          | Write       | Create a verification session; returns `session_id`, `session_token`, and a hosted `url`.                                                                                                                                                                                                                            |
| `didit_session_list`            | Read        | List sessions with filters (auto-spans all apps when unscoped).                                                                                                                                                                                                                                                      |
| `didit_session_get_decision`    | Read        | Full decision and extracted data (V3 plural arrays).                                                                                                                                                                                                                                                                 |
| `didit_session_update_status`   | Write       | Approve, decline, or request resubmission.                                                                                                                                                                                                                                                                           |
| `didit_session_update_data`     | Write       | Override extracted document (KYC) data.                                                                                                                                                                                                                                                                              |
| `didit_session_update_poa_data` | Write       | Override extracted proof-of-address data.                                                                                                                                                                                                                                                                            |
| `didit_session_add_review`      | Write       | Add a reviewer note (optionally change status).                                                                                                                                                                                                                                                                      |
| `didit_session_list_reviews`    | Read        | Manual-review audit trail.                                                                                                                                                                                                                                                                                           |
| `didit_session_generate_pdf`    | Read        | Generate a compliance PDF report.                                                                                                                                                                                                                                                                                    |
| `didit_session_share`           | Write       | Mint a Reusable KYC share token.                                                                                                                                                                                                                                                                                     |
| `didit_session_import_shared`   | Write       | Redeem a Reusable KYC share token.                                                                                                                                                                                                                                                                                   |
| `didit_session_delete`          | Destructive | Permanently delete a single session - its verification data and stored media (requires `confirm: true`; irreversible); previously issued media URLs stop resolving. Blocklist entries, issued share tokens, already-queued webhook deliveries, consumed credits, and the parent user/business are not affected.      |
| `didit_session_batch_delete`    | Destructive | Permanently delete many KYC sessions at once by `session_numbers`, or every KYC session in the application with `delete_all` (requires `confirm: true`; irreversible). KYB sessions are never touched - delete those individually. Each deleted session follows the same erasure boundary as `didit_session_delete`. |

**Bulk import**

| Tool                                | Type  | Description                                |
| ----------------------------------- | ----- | ------------------------------------------ |
| `didit_session_create_import`       | Write | Start a bulk import from a CSV/NDJSON URL. |
| `didit_session_get_import_template` | Read  | Download the import CSV template.          |
| `didit_session_get_import`          | Read  | Check import job status.                   |
| `didit_session_get_import_errors`   | Read  | List per-row import failures.              |

***

## Workflows & questionnaires

| Tool                         | Type        | Description                                                                                     |
| ---------------------------- | ----------- | ----------------------------------------------------------------------------------------------- |
| `didit_workflow_list`        | Read        | List verification workflows (auto-spans all apps).                                              |
| `didit_workflow_search`      | Read        | Find a workflow by id or label **across all apps** in one call (returns which org/app owns it). |
| `didit_workflow_get`         | Read        | Read one workflow version.                                                                      |
| `didit_workflow_create`      | Write       | Create a SIMPLE (linear) workflow from a feature list.                                          |
| `didit_workflow_update`      | Write       | Update a simple workflow's settings or feature list.                                            |
| `didit_workflow_delete`      | Destructive | Delete a workflow version.                                                                      |
| `didit_questionnaire_list`   | Read        | List custom questionnaires.                                                                     |
| `didit_questionnaire_get`    | Read        | Get questionnaire details.                                                                      |
| `didit_questionnaire_create` | Write       | Create a questionnaire (`form_elements`).                                                       |
| `didit_questionnaire_update` | Write       | Update a questionnaire.                                                                         |
| `didit_questionnaire_delete` | Destructive | Delete a questionnaire.                                                                         |

**Branching / graph workflows** — for conditional routing, Document-AI steps, and decline/decision nodes (see [Advanced → Branching workflows](/integration/mcp/advanced#branching-workflows)):

| Tool                                                 | Type  | Description                                                                                                                                                                                                                                                                                                                                                                                         |
| ---------------------------------------------------- | ----- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `didit_workflow_get_graph`                           | Read  | Get a workflow's node graph + status / editability. Big feature configs (`documents_allowed`, …) are **summarized** by default so it never overflows; `include_config:true` for raw.                                                                                                                                                                                                                |
| `didit_workflow_get_field_definitions`               | Read  | List branchable fields + valid operators (e.g. `kyc.extra_fields.profession` → `fuzzy_match`).                                                                                                                                                                                                                                                                                                      |
| `didit_workflow_get_branch_fields`                   | Read  | Fields available at a specific branch point in a candidate graph.                                                                                                                                                                                                                                                                                                                                   |
| `didit_workflow_validate_graph`                      | Read  | Dry-run validate a full graph (no save).                                                                                                                                                                                                                                                                                                                                                            |
| `didit_workflow_edit_graph`                          | Write | **Modify an existing workflow** with small ops (`set_next`/`set_node`/`set_branches`/`merge_node_config`). Fetches the full graph **server-side**, so huge allow-lists are preserved and never resent. Auto-drafts; publish opt-in. **Prefer this for edits.**                                                                                                                                      |
| `didit_workflow_set_graph`                           | Write | Replace the **entire** graph — only for building a small/new workflow from scratch (you'd otherwise resend every node). Auto-drafts; publish opt-in.                                                                                                                                                                                                                                                |
| `didit_workflow_create_draft`                        | Write | Create an editable draft from a published workflow.                                                                                                                                                                                                                                                                                                                                                 |
| `didit_workflow_publish`                             | Write | Publish a draft version (live for new sessions).                                                                                                                                                                                                                                                                                                                                                    |
| `didit_workflow_get_id_verification_methods_catalog` | Read  | The [ID Verification methods](/core-technology/id-verification/verification-methods) capability and pricing catalog: per country, whether non-doc lookup is offered and which digital ID wallets are, their availability (`available` can be enabled, `coming_soon` cannot), the plain-language request and response fields, and catalog prices. Pass `country` (ISO3) to narrow it to one country. |

<Note>
  Read the catalog **before** writing the `methods` key on an ID Verification (`OCR`) node with `didit_workflow_edit_graph` or `didit_workflow_set_graph`. A method or a wallet the catalog does not mark `available` for that country is rejected on save, wallets are an accept-list with no ordering, and every non-document price in the catalog is a placeholder until the pricing catalog is published. The [`methods` reference](/management-api/workflows/feature-configs#methods-per-country) has the full shape.
</Note>

***

## Verification APIs (standalone)

No session required — single billable calls. Great for one-off checks and pipelines.

| Tool                            | Type  | Description                                                  |
| ------------------------------- | ----- | ------------------------------------------------------------ |
| `didit_verify_id`               | Write | Document OCR + authenticity.                                 |
| `didit_verify_poa`              | Write | Proof-of-address extraction + validation.                    |
| `didit_verify_database`         | Write | Validate identity against authoritative databases.           |
| `didit_verify_kyb_search`       | Write | Search company registries.                                   |
| `didit_verify_kyb_select`       | Write | Resolve a candidate to a full company record.                |
| `didit_verify_passive_liveness` | Write | Liveness from a single image.                                |
| `didit_verify_face_match`       | Write | 1:1 face comparison.                                         |
| `didit_verify_face_search`      | Write | 1:N face search against a verified database.                 |
| `didit_verify_age`              | Write | Age estimation from a facial image.                          |
| `didit_verify_aml`              | Write | AML / sanctions / PEP / adverse-media screening.             |
| `didit_verify_email_send`       | Write | Send an email verification code.                             |
| `didit_verify_email_check`      | Write | Verify an email OTP code.                                    |
| `didit_verify_phone_send`       | Write | Send a phone code (SMS / WhatsApp / voice / RCS / Telegram). |
| `didit_verify_phone_check`      | Write | Verify a phone OTP code.                                     |

***

## Transaction monitoring (AML)

| Tool                                  | Type        | Description                                                                                               |
| ------------------------------------- | ----------- | --------------------------------------------------------------------------------------------------------- |
| `didit_transaction_list`              | Read        | List monitored transactions.                                                                              |
| `didit_transaction_get`               | Read        | One transaction — verdict, hits, score.                                                                   |
| `didit_transaction_create`            | Write       | Submit a transaction for rules + AML evaluation.                                                          |
| `didit_transaction_screen_wallet`     | Write       | Screen a crypto wallet (no session created).                                                              |
| `didit_transaction_sdk_token`         | Write       | Mint a scoped token for [client-side SDK submission](/transaction-monitoring/sdk-transaction-submission). |
| `didit_transaction_rule_list`         | Read        | List KYT rules with source/category/mode filters and performance ordering.                                |
| `didit_transaction_rule_get`          | Read        | One rule - full configuration plus execution counters.                                                    |
| `didit_transaction_rule_create`       | Write       | Create a custom rule (conditions, velocity, actions). Prefer TEST mode first.                             |
| `didit_transaction_rule_update`       | Write       | Tune a custom rule; switch any rule's mode (presets: mode only).                                          |
| `didit_transaction_rule_delete`       | Destructive | Delete a custom rule. Permanent.                                                                          |
| `didit_transaction_rule_backtest`     | Read        | Evaluate a hypothetical rule against transaction history.                                                 |
| `didit_transaction_rule_library_list` | Read        | Browse the 150+ preset library with install status.                                                       |
| `didit_transaction_rule_install`      | Write       | Install presets by library key or bundle.                                                                 |
| `didit_transaction_rule_uninstall`    | Destructive | Remove installed presets (reinstallable anytime).                                                         |

***

## Travel Rule

The [FATF / EU TFR managed exchange](/transaction-monitoring/travel-rule): settings, the VASP directory, the wallet address book, transfer actions, and wallet-ownership proofs.

| Tool                                      | Type        | Description                                                                                    |
| ----------------------------------------- | ----------- | ---------------------------------------------------------------------------------------------- |
| `didit_travel_rule_get_settings`          | Read        | Settings + VASP profile, network modes, your travel address.                                   |
| `didit_travel_rule_update_settings`       | Write       | Enable Travel Rule, tune policy, opt out of networks (partial update).                         |
| `didit_travel_rule_search_vasps`          | Read        | Search the VASP directory (due-diligence scores, reachable rails).                             |
| `didit_travel_rule_list_wallet_addresses` | Read        | List the wallet address book with ownership state.                                             |
| `didit_travel_rule_add_wallet_address`    | Write       | Register a wallet (optionally pre-verified by self-declaration).                               |
| `didit_travel_rule_update_wallet_address` | Write       | Update holder metadata / travel address on an entry.                                           |
| `didit_travel_rule_delete_wallet_address` | Destructive | Delete an entry (stops matching immediately).                                                  |
| `didit_travel_rule_transfer_action`       | Write       | Finish (report on-chain hash), cancel, or resend a transfer.                                   |
| `didit_travel_rule_confirm_ownership`     | Write       | Confirm or deny wallet ownership on a pending transfer.                                        |
| `didit_travel_rule_register_inbound`      | Write       | Register an already-settled deposit (sunrise flow).                                            |
| `didit_travel_rule_create_widget_session` | Write       | Mint a hosted [wallet-ownership widget](/transaction-monitoring/wallet-ownership-widget) link. |

***

## Marketplace

| Tool                                    | Type  | Description                                                                                                                        |
| --------------------------------------- | ----- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `didit_marketplace_list_catalog`        | Read  | Provider catalog: crypto monitoring, AML screening, phone verification, and Travel Rule networks with provider credential schemas. |
| `didit_marketplace_list_connections`    | Read  | Your connected providers and network memberships (secrets never returned).                                                         |
| `didit_marketplace_request_integration` | Write | Request an on-request integration (CODE, TRISA, Notabene, Veriscope, or any provider).                                             |

***

## Vendor users & businesses

| Tool                                  | Type        | Description                                     |
| ------------------------------------- | ----------- | ----------------------------------------------- |
| `didit_vendor_user_list`              | Read        | List verified users (grouped by `vendor_data`). |
| `didit_vendor_user_get`               | Read        | Get a user by `vendor_data`.                    |
| `didit_vendor_user_create`            | Write       | Create a user record.                           |
| `didit_vendor_user_update`            | Write       | Update user metadata.                           |
| `didit_vendor_user_update_status`     | Write       | Set `ACTIVE` / `FLAGGED` / `BLOCKED`.           |
| `didit_vendor_user_delete`            | Destructive | Batch-delete users.                             |
| `didit_vendor_business_list`          | Read        | List verified businesses.                       |
| `didit_vendor_business_get`           | Read        | Get a business by `vendor_data`.                |
| `didit_vendor_business_create`        | Write       | Create a business record.                       |
| `didit_vendor_business_update`        | Write       | Update business metadata.                       |
| `didit_vendor_business_update_status` | Write       | Set `ACTIVE` / `FLAGGED` / `BLOCKED`.           |
| `didit_vendor_business_delete`        | Destructive | Batch-delete businesses.                        |

***

## Lists, blocklist & allowlist

| Tool                            | Type        | Description                                        |
| ------------------------------- | ----------- | -------------------------------------------------- |
| `didit_lists_list`              | Read        | List all blocklists, allowlists, and custom lists. |
| `didit_lists_get`               | Read        | Get one list.                                      |
| `didit_lists_create`            | Write       | Create an allowlist or custom list.                |
| `didit_lists_update`            | Write       | Rename / update a list.                            |
| `didit_lists_delete`            | Destructive | Delete a list.                                     |
| `didit_lists_entries_list`      | Read        | List entries in a list.                            |
| `didit_lists_entry_create`      | Write       | Add an entry (by value or from a session).         |
| `didit_lists_entry_upload_face` | Write       | Add a face from an image (no session).             |
| `didit_lists_entry_delete`      | Destructive | Remove an entry.                                   |
| `didit_blocklist_get`           | Read        | List blocklist entries (legacy helper).            |
| `didit_blocklist_add`           | Write       | Add to the blocklist (legacy helper).              |
| `didit_allowlist_add`           | Write       | Add to the allowlist (legacy helper).              |
| `didit_blocklist_remove`        | Destructive | Remove from the blocklist (legacy helper).         |

***

## Cases (investigations)

| Tool                    | Type        | Description                                            |
| ----------------------- | ----------- | ------------------------------------------------------ |
| `didit_case_list`       | Read        | List cases.                                            |
| `didit_case_get`        | Read        | Get a case.                                            |
| `didit_case_statistics` | Read        | Case counts by status.                                 |
| `didit_case_create`     | Write       | Open a case.                                           |
| `didit_case_manage`     | Destructive | Act on a case (assign / resolve / escalate / comment). |

***

## Reports, audit & alerts

| Tool                            | Type  | Description                                                     |
| ------------------------------- | ----- | --------------------------------------------------------------- |
| `didit_report_list`             | Read  | List export jobs.                                               |
| `didit_report_get`              | Read  | Check an export job's status.                                   |
| `didit_report_get_download_url` | Read  | Get a signed download URL.                                      |
| `didit_report_export`           | Write | Start an export (sessions / transactions / users / businesses). |
| `didit_audit_log_list`          | Read  | List audit-log entries.                                         |
| `didit_alert_list`              | Read  | List configured alerts.                                         |
| `didit_alert_configure`         | Write | Configure an alert.                                             |

***

## Webhooks

| Tool                   | Type        | Description                                       |
| ---------------------- | ----------- | ------------------------------------------------- |
| `didit_webhook_list`   | Read        | List webhook destinations.                        |
| `didit_webhook_get`    | Read        | Read a destination (incl. signing secret).        |
| `didit_webhook_create` | Write       | Create a destination; returns the signing secret. |
| `didit_webhook_update` | Write       | Update URL / version / subscribed events.         |
| `didit_webhook_delete` | Destructive | Delete a destination.                             |

***

## Workspace: account, organization & billing

<Note>
  The `didit_account_*` tools are available only on the local stdio server (`npx @didit-protocol/mcp-server`), where they bootstrap your first credentials. The hosted connector authenticates with OAuth, so it never asks for account credentials in the conversation and does not expose these four tools.
</Note>

| Tool                                   | Type        | Description                                                            |
| -------------------------------------- | ----------- | ---------------------------------------------------------------------- |
| `didit_account_register`               | Write       | Register a new account; emails a verification code. Local server only. |
| `didit_account_verify_email`           | Write       | Verify the code; returns `api_key` + tokens. Local server only.        |
| `didit_account_resend_otp`             | Write       | Resend the verification code. Local server only.                       |
| `didit_account_login`                  | Write       | Log in to an existing account. Local server only.                      |
| `didit_context_get`                    | Read        | All organizations + applications in one call.                          |
| `didit_org_list`                       | Read        | List organizations.                                                    |
| `didit_org_list_applications`          | Read        | List applications in an organization.                                  |
| `didit_org_get_application`            | Read        | Application details (API key redacted).                                |
| `didit_org_get_balance`                | Read        | Credit balance.                                                        |
| `didit_org_list_members`               | Read        | List organization members.                                             |
| `didit_org_list_roles`                 | Read        | List available roles.                                                  |
| `didit_org_list_api_keys`              | Read        | List API keys.                                                         |
| `didit_org_invite_member`              | Write       | Invite a member by email.                                              |
| `didit_org_update_member`              | Write       | Change a member's role.                                                |
| `didit_org_remove_member`              | Destructive | Remove a member.                                                       |
| `didit_org_top_up`                     | Destructive | Create a Stripe checkout to add credits (moves money).                 |
| `didit_org_reveal_application_api_key` | Destructive | Reveal a live application API key (requires `confirm: true`).          |
| `didit_branding_get`                   | Read        | Get current branding.                                                  |
| `didit_branding_update`                | Write       | Upload logos / favicon.                                                |

***

<CardGroup>
  <Card title="Examples" icon="comments" href="/integration/mcp/examples">
    Prompts and end-to-end conversations.
  </Card>

  <Card title="Advanced" icon="gear" href="/integration/mcp/advanced">
    Scopes, cross-app behavior, response shape, webhooks.
  </Card>
</CardGroup>


# Android SDK
Source: https://docs.didit.me/integration/native-sdks/android-sdk

Native Android Kotlin SDK for KYC, KYB, biometric liveness, and AML. Jetpack Compose, NFC, on-device capture. Pay-per-use pricing, 500 free/month.

<AgentPromptAccordion title="Android SDK Integration Prompt" />

A lightweight, server-driven Android SDK for identity verification with minimal configuration required.

<Card title="GitHub Repository" icon="github" href="https://github.com/didit-protocol/sdk-android">
  View source code and examples on GitHub
</Card>

<Note>
  ### **Native SDK**: This is the recommended approach for Android apps. Native SDKs provide the best user experience, optimized camera handling, and full NFC support.
</Note>

***

## Requirements

| Requirement     | Minimum Version                                                                |
| --------------- | ------------------------------------------------------------------------------ |
| Android API     | 23+ (Android 6.0 Marshmallow). ML auto-detection requires API 24+ (see below). |
| Kotlin          | 1.9+                                                                           |
| Jetpack Compose | Included as a transitive dependency                                            |

<Info>
  **Feature availability by API level**: Document and face auto-detection require API 24+ (using either the bundled ML runtime or the Google Play services runtime - see SDK variants). On API 23 devices the SDK falls back to manual capture with a timed shutter button. All other features work across the full API 23+ range.
</Info>

***

## Installation

### Step 1: Add the Repository

Add the Didit Maven repository to the `repositories` block in your `settings.gradle.kts`:

```kotlin theme={null}
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url = uri("https://raw.githubusercontent.com/didit-protocol/sdk-android/main/repository") }
    }
}
```

Or if using `settings.gradle` (Groovy):

```groovy theme={null}
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url "https://raw.githubusercontent.com/didit-protocol/sdk-android/main/repository" }
    }
}
```

### Step 2: Add the Dependency

Add the SDK dependency to your app's `build.gradle.kts`:
(!) Regarding the version ensure you check the [GitHub repository](https://github.com/didit-protocol/sdk-android) for the latest version.

```kotlin theme={null}
dependencies {
    implementation("me.didit:didit-sdk:4.7.6")
}
```

Or if using `build.gradle` (Groovy):

```groovy theme={null}
dependencies {
    implementation "me.didit:didit-sdk:4.7.6"
}
```

#### SDK variants

The Android SDK ships as **five separate artifacts**, so your app only pays the binary cost of the
features it uses. `me.didit:didit-sdk` above is the full bundle. Pick exactly one - with a single
exception: the two auto-detection artifacts may be installed together, as described below:

| Artifact                                | Auto-detection (ML) | NFC chip reading | Use when                                                                                                                        |
| --------------------------------------- | :-----------------: | :--------------: | ------------------------------------------------------------------------------------------------------------------------------- |
| `me.didit:didit-sdk-core`               |          –          |         –        | smallest build; manual document capture only                                                                                    |
| `me.didit:didit-sdk-autodetection`      |          ✓          |         –        | auto capture, no passport/ID chip reading                                                                                       |
| `me.didit:didit-sdk-autodetection-play` |          ✓          |         –        | auto capture via the Play services ML runtime; \~9.85 MB less installed per device (arm64) than the bundled runtime (see below) |
| `me.didit:didit-sdk-nfc`                |          –          |         ✓        | chip reading without the ML auto-capture runtime                                                                                |
| `me.didit:didit-sdk`                    |          ✓          |         ✓        | every feature (full bundle)                                                                                                     |

##### Smaller ML runtime via Google Play services (opt-in, since 4.7.0)

`me.didit:didit-sdk-autodetection-play` provides the same document and face auto-capture as
`didit-sdk-autodetection`, but runs inference on the ML runtime Google Play services already
provides on the device instead of bundling one into your APK.
Detection behavior is identical - the two engines were verified frame-by-frame against each other
on a physical-device matrix before release - and inference is typically faster on the Play runtime.

To opt in, replace the artifact:

```kotlin theme={null}
// before
implementation("me.didit:didit-sdk-autodetection:4.7.6")
// after
implementation("me.didit:didit-sdk-autodetection-play:4.7.6")
```

What it changes:

* **Size**: about **9.85 MB less installed native code per device (arm64)**, because the ML
  runtime is no longer inside your app. (An unminified, 4-ABI universal APK comparison shows a
  larger \~43 MB delta, but that figure double-counts architectures no single device installs -
  the per-device number above is what your users actually see.)
* **Requirement**: Google Play services. On devices without it (for example Huawei devices
  without GMS), or if the Play runtime fails to initialize, the SDK automatically falls back -
  to the bundled runtime when `didit-sdk-autodetection` is also installed, or to manual capture
  otherwise. It never crashes because of an unavailable runtime.
* **Coverage choice**: ship only `-play` for the smallest app (non-GMS users get manual
  capture), or ship both artifacts to keep ML auto-capture on non-GMS devices at the original
  size.

Both artifacts require `didit-sdk-core` 4.7.0 or newer.

<Note>
  `didit-sdk-autodetection-play` is currently opt-in. Didit tracks its field performance against
  the bundled runtime for a release cycle after launch; once that data confirms parity, the Play
  artifact is expected to become the recommended way to install auto-detection, and
  `didit-sdk-autodetection` (bundled) remains the default recommendation until then.
</Note>

Since `4.6.0`, native WalletConnect wallet-signing ships as its own optional add-on, `me.didit:didit-sdk-wallet`.
The full `me.didit:didit-sdk` bundle already includes it, so nothing changes if you install the bundle.
If you use one of the slimmer artifacts and want wallet-ownership confirmation to run natively inside your app, add `me.didit:didit-sdk-wallet` next to it; without the add-on the SDK completes wallet ownership through a secure browser flow instead, so the feature keeps working either way.
Moving WalletConnect out of `didit-sdk-core` also removed several megabytes of wallet dependencies from every build that does not need them.

All artifacts are published at the same version, so keep them on `4.7.6`.

#### Keeping the download small

The detection models used for auto-capture are downloaded at runtime and cached, so they never count against your app's size.
What auto-capture adds to your app is the ML runtime's native library, and that cost is per CPU architecture: roughly 10 MB for `arm64-v8a`, 7 MB for `armeabi-v7a`, and 13 MB for each of the two x86 emulator architectures.

To pay that cost only once:

1. **Publish an Android App Bundle (AAB).** Google Play delivers only the device's own architecture and languages, so an arm64 phone installs roughly 10 MB of native code (about 4 MB of compressed download). A universal APK instead packs all four architectures — over 40 MB — which is the most common cause of unexpectedly large size measurements.

2. **If you distribute a single APK** and your audience is ARM phones and tablets, restrict the bundled architectures:

   ```kotlin theme={null}
   android {
       defaultConfig {
           ndk { abiFilters += listOf("arm64-v8a", "armeabi-v7a") }
       }
   }
   ```

   Keep every ABI your users actually run — add `x86_64` if you target Chromebooks or other x86 devices, or publish per-ABI APK splits so no device loses support.

3. **Enable R8** — `isMinifyEnabled = true` and `isShrinkResources = true` in your release build type (`minifyEnabled true` / `shrinkResources true` if you use Groovy `build.gradle`). The SDK ships its own consumer rules, so unused SDK code is stripped with no extra configuration.

4. **Limit bundled languages** with `resConfigs(...)` if you do not need all 48 SDK locales in an APK build; AAB language splits handle this automatically on Google Play.

### Step 3: Add Packaging Exclusion

Add this to your app's `android` block to avoid build conflicts:

```kotlin theme={null}
android {
    packaging {
        resources {
            excludes += "META-INF/versions/9/OSGI-INF/MANIFEST.MF"
        }
    }
}
```

That's it! Gradle will automatically resolve all transitive dependencies.

***

## Permissions

The SDK requires the following permissions. These are declared in the SDK's `AndroidManifest.xml` and will be merged automatically into your app's manifest:

| Permission             | Source AAR       | Description                             | Required                                                                         |
| ---------------------- | ---------------- | --------------------------------------- | -------------------------------------------------------------------------------- |
| `INTERNET`             | `didit-sdk-core` | Network access for API communication    | Yes                                                                              |
| `ACCESS_NETWORK_STATE` | `didit-sdk-core` | Detect network availability             | Yes                                                                              |
| `CAMERA`               | `didit-sdk-core` | Document scanning and face verification | Yes                                                                              |
| `NFC`                  | `didit-sdk-nfc`  | Read NFC chips in passports/ID cards    | Auto-merged from `didit-sdk-nfc` (transitive dependency of `me.didit:didit-sdk`) |

### Camera and NFC Features

The SDK declares `android.hardware.camera` and `android.hardware.nfc` as optional features (`android:required="false"`). This ensures your app can be installed on devices without a camera or NFC hardware — the SDK will gracefully handle missing hardware at runtime.

***

## Quick Start

### Step 1: Initialize the SDK

Initialize the SDK in your `Application.onCreate()`:

```kotlin theme={null}
import me.didit.sdk.DiditSdk

class MyApp : Application() {
    override fun onCreate() {
        super.onCreate()
        DiditSdk.initialize(this)
    }
}
```

### Step 2: Start Verification and Handle Results

```kotlin theme={null}
import me.didit.sdk.DiditSdk
import me.didit.sdk.DiditSdkState
import me.didit.sdk.VerificationResult

class MainActivity : ComponentActivity() {
    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Observe SDK state to launch UI when ready
        lifecycleScope.launch {
            DiditSdk.state.collect { state ->
                when (state) {
                    is DiditSdkState.Ready -> DiditSdk.launchVerificationUI(this@MainActivity)
                    is DiditSdkState.Error -> Log.e("Didit", "Error: ${state.message}")
                    else -> { /* Loading, Idle, CreatingSession */ }
                }
            }
        }
    }

    private fun startVerification() {
        // Method 1: UniLink (no backend required)
        DiditSdk.startVerification(
            workflowId = "your-workflow-id",
            vendorData = "user-123"
        ) { result ->
            handleResult(result)
        }

        // Method 2: Backend Session (recommended for production)
        // DiditSdk.startVerification(
        //     token = "your-session-token"
        // ) { result ->
        //     handleResult(result)
        // }
    }

    private fun handleResult(result: VerificationResult) {
        when (result) {
            is VerificationResult.Completed -> {
                Log.d("Didit", "Session: ${result.session.sessionId}")
                Log.d("Didit", "Status: ${result.session.status}")
            }
            is VerificationResult.Cancelled -> {
                Log.d("Didit", "User cancelled")
            }
            is VerificationResult.Failed -> {
                Log.e("Didit", "Failed: ${result.error.message}")
            }
        }
    }
}
```

***

## Integration Methods

The SDK supports two integration methods:

### Method 1: UniLink (Simplest)

No backend required. The SDK creates the session directly using your workflow ID from the Didit Console. Limited to `vendorData` only.

```kotlin theme={null}
DiditSdk.startVerification(
    workflowId = "your-workflow-id",
    vendorData = "user-123"
) { result ->
    handleResult(result)
}
```

### Method 2: Backend Session (Recommended for Production)

Your backend creates the session via the [Create Verification Session API](/sessions-api/create-session) (`POST /v3/session/`) with full parameter support (`contact_details`, `expected_details`, `metadata`, `callback`, etc.), then passes the `session_token` to the SDK.

```kotlin theme={null}
// Your backend creates a session and returns the token
val sessionToken = yourBackend.createVerificationSession(userId = currentUser.id)

// Pass the token to the SDK
DiditSdk.startVerification(
    token = sessionToken
) { result ->
    handleResult(result)
}
```

This approach gives you full control over:

* Associating sessions with your users (`vendor_data`)
* Setting custom metadata
* Configuring callbacks per session
* Providing contact details and expected details for cross-validation

***

## Configuration

Customize the SDK behavior:

```kotlin theme={null}
import me.didit.sdk.Configuration
import me.didit.sdk.core.localization.SupportedLanguage

val configuration = Configuration(
    languageLocale = SupportedLanguage.SPANISH,  // Force Spanish language
    fontFamily = "my_custom_font",                // Custom font (must be in res/font/)
    loggingEnabled = true                         // Enable debug logging
)

DiditSdk.startVerification(
    token = "your-session-token",
    configuration = configuration
) { result ->
    handleResult(result)
}
```

### Configuration Options

| Property               | Type                 | Default       | Description                                                                             |
| ---------------------- | -------------------- | ------------- | --------------------------------------------------------------------------------------- |
| `languageLocale`       | `SupportedLanguage?` | Device locale | Force a specific language                                                               |
| `fontFamily`           | `String?`            | System font   | Custom font resource name (from `res/font/`)                                            |
| `loggingEnabled`       | `Boolean`            | `false`       | Enable SDK debug logging                                                                |
| `showCloseButton`      | `Boolean`            | `true`        | Show close (X) button on verification step screens                                      |
| `showExitConfirmation` | `Boolean`            | `true`        | Show confirmation dialog when user attempts to exit                                     |
| `closeOnComplete`      | `Boolean`            | `false`       | Auto-dismiss verification UI when complete (Web SDK equivalent: `closeModalOnComplete`) |

<Info>
  Options `showCloseButton`, `showExitConfirmation`, and `closeOnComplete` match the Web SDK's `DiditSdkConfiguration`. Mobile-specific options `languageLocale` and `fontFamily` exist because the mobile SDK renders the full verification UI natively (unlike the Web SDK which delegates to the hosted frontend inside an iframe).
</Info>

<Info>
  **Theming & Colors**: Colors, backgrounds, and intro screen settings are configured through your [White Label settings](https://business.didit.me) in the Didit Console, not in the SDK configuration. This ensures consistent branding across all platforms.
</Info>

***

## Language Support

The SDK supports **53 languages**. If no language is specified, the SDK uses the device locale with English as fallback.

```kotlin theme={null}
// Use device locale (default)
val config = Configuration()

// Force specific language
val config = Configuration(languageLocale = SupportedLanguage.FRENCH)
```

**[View All Supported Languages →](/integration/supported-languages)**

***

## Advanced Options

For advanced session parameters (`contact_details`, `expected_details`, `metadata`, `callback`), use the **Backend Session** method. Your backend calls the [Create Verification Session API](/sessions-api/create-session) with full parameters, then passes the `session_token` to the SDK.

***

## Handling Results

The `VerificationResult` sealed class provides the outcome of the verification:

### Result Cases

| Case                     | Description                                                     |
| ------------------------ | --------------------------------------------------------------- |
| `Completed(session)`     | Verification flow completed (check `session.status` for result) |
| `Cancelled(session)`     | User cancelled the verification flow                            |
| `Failed(error, session)` | An error occurred during verification                           |

### SessionData Properties

| Property    | Type                 | Description                          |
| ----------- | -------------------- | ------------------------------------ |
| `sessionId` | `String`             | Unique session identifier            |
| `status`    | `VerificationStatus` | `APPROVED`, `PENDING`, or `DECLINED` |

### Error Types

All errors are sealed subclasses of `me.didit.sdk.VerificationError`:

| Error                | Description                                                     |
| -------------------- | --------------------------------------------------------------- |
| `SessionExpired`     | The session has expired                                         |
| `NetworkError`       | Network connectivity issue                                      |
| `CameraAccessDenied` | Camera permission not granted                                   |
| `NotInitialized`     | SDK not initialized — call `DiditSdk.initialize(context)` first |
| `ApiError`           | Backend returned an error response                              |
| `RetryBlocked`       | Verification cannot be retried (e.g., max attempts reached)     |
| `Unknown(message)`   | Other error with message                                        |

### Complete Result Handling Example

```kotlin theme={null}
DiditSdk.startVerification(token = "your-token") { result ->
    when (result) {
        is VerificationResult.Completed -> {
            when (result.session.status) {
                VerificationStatus.APPROVED -> {
                    Log.d("Didit", "Approved! Session: ${result.session.sessionId}")
                    // User is verified - grant access
                }
                VerificationStatus.PENDING -> {
                    Log.d("Didit", "Under review. Session: ${result.session.sessionId}")
                    // Show "verification in progress" UI
                }
                VerificationStatus.DECLINED -> {
                    Log.d("Didit", "Declined. Session: ${result.session.sessionId}")
                    // Handle declined verification
                }
            }
        }
        is VerificationResult.Cancelled -> {
            Log.d("Didit", "Cancelled: ${result.session?.sessionId ?: "unknown"}")
            // User chose to cancel - maybe show retry option
        }
        is VerificationResult.Failed -> {
            Log.e("Didit", "Error: ${result.error.message}")
            // Handle error - show retry or contact support
        }
    }
}
```

***

## Observing SDK State

You can observe the SDK state for custom loading UI:

```kotlin theme={null}
lifecycleScope.launch {
    DiditSdk.state.collect { state ->
        when (state) {
            is DiditSdkState.Idle -> {
                // Ready to start verification
            }
            is DiditSdkState.CreatingSession -> {
                // Show "Creating session..." progress
            }
            is DiditSdkState.Loading -> {
                // Show loading indicator
            }
            is DiditSdkState.Ready -> {
                // Verification UI is ready - launch it
                DiditSdk.launchVerificationUI(this@MainActivity)
            }
            is DiditSdkState.Error -> {
                // Show error message
                Log.e("Didit", "Error: ${state.message}")
            }
        }
    }
}
```

***

## ProGuard / R8

The SDK includes its own consumer ProGuard rules. No additional configuration is needed.

If you use R8 full mode, you may need to add this to your `gradle.properties`:

```properties theme={null}
android.enableR8.fullMode=false
```

***

## End-to-End Example (Backend Session → Android SDK → Result)

This pattern is the production-ready integration. Your backend creates the session, your Android app receives the `session_token`, and the SDK runs the flow.

### 1. Backend — create the session

```ts theme={null}
// Node.js / Express example. Run on your server. NEVER ship DIDIT_API_KEY to the device.
import express from "express";

const app = express();
app.use(express.json());

app.post("/api/verification/start", async (req, res) => {
  const response = await fetch("https://verification.didit.me/v3/session/", {
    method: "POST",
    headers: {
      "x-api-key": process.env.DIDIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      workflow_id: process.env.DIDIT_WORKFLOW_ID,
      vendor_data: req.body.userId, // your stable user id
    }),
  });

  if (!response.ok) {
    return res.status(500).json({ error: `Didit ${response.status}` });
  }

  const { session_id, session_token } = await response.json();
  // Persist session_id <-> userId so you can match the webhook later.
  res.json({ session_id, session_token });
});
```

### 2. Android — exchange and start the SDK

```kotlin theme={null}
import android.app.Activity
import androidx.lifecycle.lifecycleScope
import kotlinx.coroutines.Dispatchers
import kotlinx.coroutines.launch
import kotlinx.coroutines.withContext
import me.didit.sdk.DiditSdk
import me.didit.sdk.VerificationResult
import me.didit.sdk.VerificationStatus
import okhttp3.OkHttpClient
import okhttp3.Request
import okhttp3.RequestBody.Companion.toRequestBody
import okhttp3.MediaType.Companion.toMediaType
import org.json.JSONObject

class VerificationFlow(private val activity: ComponentActivity) {
    private val http = OkHttpClient()
    private val json = "application/json".toMediaType()

    fun start(userId: String) {
        activity.lifecycleScope.launch {
            val token = withContext(Dispatchers.IO) {
                val body = JSONObject().put("userId", userId).toString().toRequestBody(json)
                val req = Request.Builder()
                    .url("https://your-backend.example.com/api/verification/start")
                    .post(body)
                    .build()
                http.newCall(req).execute().use { resp ->
                    JSONObject(resp.body!!.string()).getString("session_token")
                }
            }

            DiditSdk.startVerification(token = token) { result ->
                when (result) {
                    is VerificationResult.Completed -> when (result.session.status) {
                        VerificationStatus.APPROVED -> { /* optimistic UI; rely on webhook for source of truth */ }
                        VerificationStatus.PENDING  -> { /* show "under review" */ }
                        VerificationStatus.DECLINED -> { /* show retry/contact support */ }
                    }
                    is VerificationResult.Cancelled -> { /* user cancelled */ }
                    is VerificationResult.Failed    -> { /* show error: result.error.message */ }
                }
            }
        }
    }
}
```

### 3. Backend — receive the final decision via webhook

The SDK result is convenient for UI feedback, but the authoritative outcome arrives via webhook. See the [Webhooks guide](/integration/webhooks) for HMAC verification.

```ts theme={null}
app.post("/api/webhooks/didit", express.raw({ type: "application/json" }), (req, res) => {
  // 1. Verify the X-Signature header (see Webhooks docs)
  // 2. Parse the body
  const event = JSON.parse(req.body.toString());
  if (event.webhook_type === "status.updated") {
    // event.session_id, event.status ("Approved" | "Declined" | "In Review" | ...)
    // Look up the user by session_id and update their verification state.
  }
  res.sendStatus(200);
});
```

***

## Complete Example

```kotlin theme={null}
import android.os.Bundle
import android.util.Log
import androidx.activity.ComponentActivity
import androidx.lifecycle.lifecycleScope
import kotlinx.coroutines.launch
import me.didit.sdk.Configuration
import me.didit.sdk.DiditSdk
import me.didit.sdk.DiditSdkState
import me.didit.sdk.VerificationResult
import me.didit.sdk.VerificationStatus
import me.didit.sdk.core.localization.SupportedLanguage

class MainActivity : ComponentActivity() {

    override fun onCreate(savedInstanceState: Bundle?) {
        super.onCreate(savedInstanceState)

        // Observe SDK state
        lifecycleScope.launch {
            DiditSdk.state.collect { state ->
                when (state) {
                    is DiditSdkState.Ready -> DiditSdk.launchVerificationUI(this@MainActivity)
                    is DiditSdkState.Error -> Log.e("Didit", "Error: ${state.message}")
                    else -> { /* Idle, Loading, CreatingSession */ }
                }
            }
        }
    }

    fun startVerification() {
        val config = Configuration(
            languageLocale = SupportedLanguage.ENGLISH,
            loggingEnabled = true
        )

        // Method 1: UniLink (no backend required)
        DiditSdk.startVerification(
            workflowId = "your-workflow-id",
            vendorData = "user-123",
            configuration = config
        ) { result ->
            handleResult(result)
        }

        // Method 2: Backend Session (recommended for production)
        // DiditSdk.startVerification(
        //     token = "your-session-token",
        //     configuration = config
        // ) { result ->
        //     handleResult(result)
        // }
    }

    private fun handleResult(result: VerificationResult) {
        when (result) {
            is VerificationResult.Completed -> {
                when (result.session.status) {
                    VerificationStatus.APPROVED -> {
                        Log.d("Didit", "Approved! Session: ${result.session.sessionId}")
                    }
                    VerificationStatus.PENDING -> {
                        Log.d("Didit", "Under review")
                    }
                    VerificationStatus.DECLINED -> {
                        Log.d("Didit", "Declined")
                    }
                }
            }
            is VerificationResult.Cancelled -> {
                Log.d("Didit", "Cancelled: ${result.session?.sessionId ?: "unknown"}")
            }
            is VerificationResult.Failed -> {
                Log.e("Didit", "Error: ${result.error.message}")
            }
        }
    }
}
```

***


# Flutter SDK
Source: https://docs.didit.me/integration/native-sdks/flutter-sdk

Flutter Dart SDK for KYC, KYB, biometric liveness, and AML. Native iOS and Android, NFC e-passport reading. Pay-per-use pricing, 500 free/month.

<AgentPromptAccordion title="Flutter SDK Integration Prompt" />

A cross-platform Flutter plugin that wraps the native iOS and Android SDKs, providing a unified Dart API for identity verification.

<Card title="GitHub Repository" icon="github" href="https://github.com/didit-protocol/sdk-flutter">
  View source code and examples on GitHub
</Card>

<Card title="pub.dev Package" icon="box" href="https://pub.dev/packages/didit_sdk">
  didit\_sdk
</Card>

<Note>
  ### **Native SDK**: This is the recommended approach for Flutter apps. The SDK wraps the native iOS and Android SDKs via platform channels for the best user experience, optimized camera handling, and full NFC support.
</Note>

***

## Requirements

| Requirement | Minimum Version |
| ----------- | --------------- |
| Flutter     | 3.3+            |
| Dart        | 3.11+           |

### Platform Requirements

| Platform | Minimum Version | Notes                                   |
| -------- | --------------- | --------------------------------------- |
| iOS      | 13.0+           | NFC passport reading requires iOS 15.0+ |
| Android  | API 23+ (6.0)   | Java 17+                                |

***

## Installation

```bash theme={null}
flutter pub add didit_sdk
```

Or add it manually to your `pubspec.yaml`:

```yaml theme={null}
dependencies:
  didit_sdk: ^4.7.6
```

Then run:

```bash theme={null}
flutter pub get
```

### Native SDK variants

`didit_sdk` bundles the complete native SDK.
To ship a smaller binary, depend on a variant package instead - it exposes exactly the same Dart API and pins the matching native SDK on both platforms:

| Package                   | Automatic capture | NFC passport reading | Minimum iOS |
| ------------------------- | ----------------- | -------------------- | ----------- |
| `didit_sdk` (default)     | Yes               | Yes                  | 15.0        |
| `didit_sdk_core`          | No                | No                   | 13.0        |
| `didit_sdk_autodetection` | Yes               | No                   | 13.0        |
| `didit_sdk_nfc`           | No                | Yes                  | 15.0        |

```yaml theme={null}
dependencies:
  didit_sdk_core: ^4.7.6
```

Depend on exactly one of these packages and import from the one you chose, for example `package:didit_sdk_core/sdk_flutter.dart`.

### iOS Setup

The plugin supports both of Flutter's iOS dependency managers: Swift Package Manager and CocoaPods.

#### Swift Package Manager

If your Flutter version has Swift Package Manager support enabled (opt in with `flutter config --enable-swift-package-manager` on Flutter 3.24+), the plugin is consumed as a Swift package automatically.
No Podfile configuration is needed - the native DiditSDK dependency resolves from GitHub on its own.
Set your app's iOS deployment target in Xcode (Runner target and project) to the minimum for your chosen package: 15.0 for `didit_sdk` and `didit_sdk_nfc`, 13.0 for `didit_sdk_core` and `didit_sdk_autodetection`.

#### CocoaPods

With `didit_sdk`, the plugin selects the native iOS SDK variant from `$DiditSdkIosVariant`, a Ruby global you set in your app's `ios/Podfile` (the DiditSDK pod is not on CocoaPods trunk):

```ruby theme={null}
# Pick one: 'all', 'core', 'autodetection', 'nfc'
$DiditSdkIosVariant = 'all'

didit_sdk_ios_deployment_target = ['all', 'nfc'].include?($DiditSdkIosVariant) ? '15.0' : '13.0'
platform :ios, didit_sdk_ios_deployment_target

didit_sdk_ios_pod = case $DiditSdkIosVariant
                    when 'all' then 'DiditSDK/All'
                    when 'core' then 'DiditSDK/Core'
                    when 'autodetection' then 'DiditSDK/AutoDetection'
                    when 'nfc' then 'DiditSDK/NFC'
                    end
didit_sdk_ios_podspec = 'https://raw.githubusercontent.com/didit-protocol/sdk-ios/4.7.6/DiditSDK.podspec'

target 'Runner' do
  use_frameworks!

  pod didit_sdk_ios_pod, :podspec => didit_sdk_ios_podspec

  flutter_install_all_ios_pods File.dirname(File.realpath(__FILE__))
end

post_install do |installer|
  installer.pods_project.targets.each do |target|
    flutter_additional_ios_build_settings(target)
    target.build_configurations.each do |config|
      config.build_settings['IPHONEOS_DEPLOYMENT_TARGET'] = didit_sdk_ios_deployment_target
    end
  end
end
```

If you use a variant package (`didit_sdk_core`, `didit_sdk_autodetection`, `didit_sdk_nfc`), it pins its native subspec directly and ignores `$DiditSdkIosVariant` - keep your Podfile's `pod` line and deployment target matched to that variant (for example `pod 'DiditSDK/Core', :podspec => ...` with `platform :ios, '13.0'`).

<Note>
  The `all` and `nfc` variants require a deployment target of iOS 15.0+; `core` and `autodetection` can target iOS 13.0. When switching variants, clean CocoaPods first (`rm -rf Pods Podfile.lock`) so the previous SDK variant is not reused.
</Note>

<Warning>
  The tag in the podspec URL must match the native iOS SDK version your `didit_sdk` release pins
  (`4.7.6` pins native `4.7.6`). If the URL points at an older tag, `pod install` fails to resolve —
  CocoaPods finds a podspec declaring that older version while the plugin requires an exact match.
  When you upgrade `didit_sdk`, bump the tag in this URL to the same version.
</Warning>

### Android Setup

By default the plugin depends on the full Android SDK including NFC. To build without NFC, add this to `android/gradle.properties`:

```properties theme={null}
diditSdkAndroidNfcEnabled=false
```

This switches the dependency from `me.didit:didit-sdk` to `me.didit:didit-sdk-core`, removing the NFC reader module and its JMRTD/SCUBA/BouncyCastle dependencies.

When NFC is enabled (default), add this packaging rule to `android/app/build.gradle.kts` to resolve a duplicate metadata file from BouncyCastle:

```kotlin theme={null}
android {
    packaging {
        resources {
            pickFirsts += "META-INF/versions/9/OSGI-INF/MANIFEST.MF"
        }
    }
}
```

Without this rule the build fails with a `mergeDebugJavaResource` error. The rule is not needed when `diditSdkAndroidNfcEnabled=false`.

<Note>
  The Android native SDK resolves from a remote GitHub Maven repository (since plugin 3.4.0) — no manual Maven configuration is needed in your app.
</Note>

***

## Permissions

### iOS

Add the following keys to your app's `Info.plist`:

| Permission    | Info.plist Key                        | Description                             | Required     |
| ------------- | ------------------------------------- | --------------------------------------- | ------------ |
| Camera        | `NSCameraUsageDescription`            | Document scanning and face verification | Yes          |
| Microphone    | `NSMicrophoneUsageDescription`        | Video recording for liveness checks     | Yes          |
| Photo Library | `NSPhotoLibraryUsageDescription`      | Upload documents from device gallery    | Yes          |
| NFC           | `NFCReaderUsageDescription`           | Read NFC chips in passports/ID cards    | If using NFC |
| Location      | `NSLocationWhenInUseUsageDescription` | Geolocation for fraud prevention        | Optional     |

<Warning>
  If any required iOS privacy key is missing, iOS terminates the app as soon as the SDK tries to access that protected resource. For example, missing `NSCameraUsageDescription` causes a crash when the user taps the document camera's take photo button.
</Warning>

#### NFC Configuration

To enable NFC reading for passports and ID cards with chips:

1. **Add NFC Capability** in Xcode:
   * Select your target > **Signing & Capabilities** > **+ Capability** > **Near Field Communication Tag Reading**

2. **Add ISO7816 Identifiers** to `Info.plist`:

```xml theme={null}
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
    <string>D23300000045737445494420763335</string>
    <string>A0000002471001</string>
    <string>A0000002472001</string>
    <string>00000000000000</string>
</array>
```

3. **Add an entitlements file** with NFC tag reading enabled:

```xml theme={null}
<key>com.apple.developer.nfc.readersession.formats</key>
<array>
    <string>TAG</string>
</array>
```

Make sure the app's provisioning profile includes the NFC Tag Reading capability. If the bundle ID is not configured for NFC in your Apple Developer account, Xcode will fail signing with a missing `com.apple.developer.nfc.readersession.formats` entitlement.

This NFC configuration is not needed for the `core` or `autodetection` variants (`$DiditSdkIosVariant`), or for the `didit_sdk_core` / `didit_sdk_autodetection` packages — none of them read chips.

### Android

The following permissions are declared in the SDK's `AndroidManifest.xml` and merged automatically:

| Permission             | Description                             | Required     |
| ---------------------- | --------------------------------------- | ------------ |
| `INTERNET`             | Network access for API communication    | Yes          |
| `ACCESS_NETWORK_STATE` | Detect network availability             | Yes          |
| `CAMERA`               | Document scanning and face verification | Yes          |
| `NFC`                  | Read NFC chips in passports/ID cards    | If using NFC |

Camera and NFC hardware features are declared as optional (`android:required="false"`), so your app can be installed on devices without these features. When `diditSdkAndroidNfcEnabled=false`, the Android NFC permission and feature are not added by the SDK.

#### Runtime Permissions

The SDK handles Android runtime permission requests automatically. When the user reaches a step that requires camera access:

1. The SDK prompts for camera permission if not already granted
2. If the user **denies** the permission, an error message is displayed with a **Try Again** button
3. If the user **grants** the permission, the verification flow continues

You do not need to request camera permission in your app code before calling `startVerification()` — the SDK manages this internally.

***

## Quick Start

```dart theme={null}
import 'package:didit_sdk/sdk_flutter.dart';

// Start verification with a session token from your backend
final result = await DiditSdk.startVerification('your-session-token');

switch (result) {
  case VerificationCompleted(:final session):
    if (session.status == VerificationStatus.approved) {
      print('Identity verified!');
    }
  case VerificationCancelled():
    print('User cancelled');
  case VerificationFailed(:final error):
    print('Error: ${error.message}');
}
```

***

## Integration Methods

The SDK supports two integration methods:

### Method 1: Session Token (Recommended for Production)

Create a session on your backend using the [Create Verification Session API](/sessions-api/create-session), then pass the token to the SDK:

```dart theme={null}
import 'package:didit_sdk/sdk_flutter.dart';

// Your backend creates a session and returns the token
final sessionToken = await yourBackend.createVerificationSession(userId);

// Pass the token to the SDK
final result = await DiditSdk.startVerification(sessionToken);
```

This approach gives you full control over:

* Associating sessions with your users (`vendor_data`)
* Setting custom metadata
* Configuring callbacks per session

### Method 2: Workflow ID (Simpler Integration)

For simpler integrations, the SDK can create sessions directly using your workflow ID — no backend needed:

```dart theme={null}
import 'package:didit_sdk/sdk_flutter.dart';

final result = await DiditSdk.startVerificationWithWorkflow(
  'your-workflow-id',
  vendorData: 'user-123',
  config: const DiditConfig(loggingEnabled: true),
);
```

<Note>
  Advanced session parameters (`contact_details`, `expected_details`, `metadata`) are **only** supported through the Session Token method, where your backend calls the [Create Session API](/sessions-api/create-session) with full parameter support. Pass the returned `session_token` to `DiditSdk.startVerification()`.
</Note>

***

## Configuration

Customize the SDK behavior by passing a `DiditConfig` object:

```dart theme={null}
final result = await DiditSdk.startVerification(
  'your-session-token',
  config: const DiditConfig(
    languageCode: 'es',       // Force Spanish language
    fontFamily: 'Avenir',     // Custom font
    loggingEnabled: true,     // Enable debug logging
  ),
);
```

For `startVerificationWithWorkflow`, pass `config` as a named parameter:

```dart theme={null}
final result = await DiditSdk.startVerificationWithWorkflow(
  'your-workflow-id',
  vendorData: 'user-123',
  config: const DiditConfig(
    languageCode: 'es',
    loggingEnabled: true,
  ),
);
```

### Configuration Options

| Property         | Type      | Default       | Description                                           |
| ---------------- | --------- | ------------- | ----------------------------------------------------- |
| `languageCode`   | `String?` | Device locale | ISO 639-1 language code (e.g. `"en"`, `"fr"`, `"ar"`) |
| `fontFamily`     | `String?` | System font   | Custom font family name (must be registered natively) |
| `loggingEnabled` | `bool`    | `false`       | Enable SDK debug logging                              |

<Info>
  **Theming & Colors**: Colors, backgrounds, and intro screen settings are configured through your [White Label settings](https://business.didit.me) in the Didit Console, not in the SDK configuration. This ensures consistent branding across all platforms.
</Info>

***

## Language Support

The SDK supports **53 languages**. If no language is specified, the SDK uses the device locale with English as fallback.

```dart theme={null}
// Use device locale (default)
await DiditSdk.startVerification(token);

// Force specific language
await DiditSdk.startVerification(token,
  config: const DiditConfig(languageCode: 'fr'),
);
```

**[View All Supported Languages →](/integration/supported-languages)**

***

## Advanced Session Parameters

Parameters like `contact_details`, `expected_details`, and `metadata` are **only** supported through the Session Token method. Your backend calls [`POST /v3/session/`](/sessions-api/create-session) with full parameter support, then passes the returned `session_token` to the SDK.

```dart theme={null}
// Your backend handles the full session creation:
// POST /v3/session/ with contact_details, expected_details, metadata, etc.
final sessionToken = await yourBackend.createSession(userId);

// The SDK only needs the token
final result = await DiditSdk.startVerification(sessionToken);
```

<Note>
  The Dart `startVerificationWithWorkflow` method only accepts `workflowId`, `vendorData`, and `config`. Pre-3.4.0 versions exposed `contactDetails`, `expectedDetails`, and `metadata` parameters, but these were removed because the Unilink endpoint does not honour them.
</Note>

***

## Handling Results

Both `startVerification` and `startVerificationWithWorkflow` return a `Future<VerificationResult>`. The result is a sealed class — use pattern matching to determine the outcome.

### Result Cases

| Case                    | Description                                                     |
| ----------------------- | --------------------------------------------------------------- |
| `VerificationCompleted` | Verification flow completed (check `session.status` for result) |
| `VerificationCancelled` | User cancelled the verification flow                            |
| `VerificationFailed`    | An error occurred during verification                           |

### SessionData Properties

| Property    | Type                 | Description                          |
| ----------- | -------------------- | ------------------------------------ |
| `sessionId` | `String`             | Unique session identifier            |
| `status`    | `VerificationStatus` | `approved`, `pending`, or `declined` |

### Error Types

The `VerificationErrorType` enum exposes the following cases:

| Error                | Description                                          |
| -------------------- | ---------------------------------------------------- |
| `sessionExpired`     | The session has expired                              |
| `networkError`       | Network connectivity issue                           |
| `cameraAccessDenied` | Camera permission not granted                        |
| `notInitialized`     | SDK not initialized (Android only)                   |
| `apiError`           | API request failed                                   |
| `retryBlocked`       | Maximum retry attempts exceeded for the current step |
| `unknown`            | Other error — inspect `error.message` for details    |

### Complete Result Handling Example

```dart theme={null}
import 'package:didit_sdk/sdk_flutter.dart';

Future<void> verify(String token) async {
  final result = await DiditSdk.startVerification(token);

  switch (result) {
    case VerificationCompleted(:final session):
      switch (session.status) {
        case VerificationStatus.approved:
          print('Approved! Session: ${session.sessionId}');
          // User is verified — grant access
        case VerificationStatus.pending:
          print('Under review. Session: ${session.sessionId}');
          // Show "verification in progress" UI
        case VerificationStatus.declined:
          print('Declined. Session: ${session.sessionId}');
          // Handle declined verification
      }

    case VerificationCancelled(:final session):
      print('User cancelled.');
      if (session != null) {
        print('Session: ${session.sessionId}');
      }
      // Maybe show retry option

    case VerificationFailed(:final error):
      print('Error [${error.type}]: ${error.message}');
      // Handle error — show retry or contact support
  }
}
```

***

## End-to-End Example (Backend Session → Flutter SDK → Webhook)

The production-ready integration: your backend creates the session, your Flutter app receives the `session_token`, and the SDK runs the flow. The final decision is delivered to your backend via webhook — never trust the client-side result alone.

### 1. Backend — create the session

```ts theme={null}
// Node.js / Express example. Run on your server. NEVER ship DIDIT_API_KEY to the device.
import express from "express";

const app = express();
app.use(express.json());

app.post("/api/verification/start", async (req, res) => {
  const response = await fetch("https://verification.didit.me/v3/session/", {
    method: "POST",
    headers: {
      "x-api-key": process.env.DIDIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      workflow_id: process.env.DIDIT_WORKFLOW_ID,
      vendor_data: req.body.userId, // your stable user id
    }),
  });

  if (!response.ok) {
    return res.status(500).json({ error: `Didit ${response.status}` });
  }

  const { session_id, session_token } = await response.json();
  // Persist session_id <-> userId so you can match the webhook later.
  res.json({ session_id, session_token });
});
```

### 2. Flutter — exchange and start the SDK

```dart theme={null}
import 'dart:convert';
import 'package:flutter/material.dart';
import 'package:http/http.dart' as http;
import 'package:didit_sdk/sdk_flutter.dart';

class VerifyButton extends StatefulWidget {
  const VerifyButton({super.key, required this.userId});
  final String userId;

  @override
  State<VerifyButton> createState() => _VerifyButtonState();
}

class _VerifyButtonState extends State<VerifyButton> {
  bool _loading = false;

  Future<void> _verify() async {
    setState(() => _loading = true);
    try {
      final resp = await http.post(
        Uri.parse('https://your-backend.example.com/api/verification/start'),
        headers: const {'Content-Type': 'application/json'},
        body: jsonEncode({'userId': widget.userId}),
      );
      final sessionToken = (jsonDecode(resp.body) as Map)['session_token'] as String;

      final result = await DiditSdk.startVerification(sessionToken);

      switch (result) {
        case VerificationCompleted(:final session):
          if (session.status == VerificationStatus.approved) {
            // Optimistic UI; rely on the webhook delivered to your backend as the source of truth.
          }
        case VerificationCancelled():
          // User dismissed the flow
          break;
        case VerificationFailed(:final error):
          // Show retry — error.type / error.message
          break;
      }
    } finally {
      if (mounted) setState(() => _loading = false);
    }
  }

  @override
  Widget build(BuildContext context) {
    return ElevatedButton(
      onPressed: _loading ? null : _verify,
      child: Text(_loading ? 'Starting...' : 'Verify identity'),
    );
  }
}
```

### 3. Backend — receive the final decision via webhook

```ts theme={null}
app.post("/api/webhooks/didit", express.raw({ type: "application/json" }), (req, res) => {
  // 1. Verify the X-Signature header (see Webhooks docs)
  // 2. Parse the body
  const event = JSON.parse(req.body.toString());
  if (event.webhook_type === "status.updated") {
    // event.session_id, event.status ("Approved" | "Declined" | "In Review" | ...)
    // Look up the user by session_id and update their verification state.
  }
  res.sendStatus(200);
});
```

See the [Webhooks guide](/integration/webhooks) for HMAC signature verification details.

***

## Complete Example

```dart theme={null}
import 'package:flutter/material.dart';
import 'package:didit_sdk/sdk_flutter.dart';

void main() {
  runApp(const MyApp());
}

class MyApp extends StatelessWidget {
  const MyApp({super.key});

  @override
  Widget build(BuildContext context) {
    return MaterialApp(
      title: 'Didit SDK Example',
      theme: ThemeData(
        colorScheme: ColorScheme.fromSeed(seedColor: const Color(0xFF1A1A1A)),
        useMaterial3: true,
      ),
      home: const VerificationScreen(),
    );
  }
}

class VerificationScreen extends StatefulWidget {
  const VerificationScreen({super.key});

  @override
  State<VerificationScreen> createState() => _VerificationScreenState();
}

class _VerificationScreenState extends State<VerificationScreen> {
  final _tokenController = TextEditingController();
  bool _loading = false;

  @override
  void dispose() {
    _tokenController.dispose();
    super.dispose();
  }

  Future<void> _startVerification() async {
    final token = _tokenController.text.trim();
    if (token.isEmpty) {
      _showAlert('Error', 'Please enter a session token.');
      return;
    }

    setState(() => _loading = true);

    try {
      final result = await DiditSdk.startVerification(
        token,
        config: const DiditConfig(loggingEnabled: true),
      );

      switch (result) {
        case VerificationCompleted(:final session):
          _showAlert(
            'Verification Complete',
            'Status: ${session.status.name}\nSession: ${session.sessionId}',
          );
        case VerificationCancelled():
          _showAlert('Cancelled', 'The user cancelled the verification.');
        case VerificationFailed(:final error):
          _showAlert('Failed', '${error.type.name}: ${error.message}');
      }
    } catch (e) {
      _showAlert('Error', 'Unexpected error: $e');
    } finally {
      setState(() => _loading = false);
    }
  }

  void _showAlert(String title, String message) {
    showDialog(
      context: context,
      builder: (ctx) => AlertDialog(
        title: Text(title),
        content: Text(message),
        actions: [
          TextButton(
            onPressed: () => Navigator.pop(ctx),
            child: const Text('OK'),
          ),
        ],
      ),
    );
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      body: SafeArea(
        child: Padding(
          padding: const EdgeInsets.all(24),
          child: Column(
            mainAxisAlignment: MainAxisAlignment.center,
            crossAxisAlignment: CrossAxisAlignment.stretch,
            children: [
              TextField(
                controller: _tokenController,
                decoration: InputDecoration(
                  hintText: 'Enter session token...',
                  border: OutlineInputBorder(
                    borderRadius: BorderRadius.circular(8),
                  ),
                ),
                autocorrect: false,
              ),
              const SizedBox(height: 16),
              ElevatedButton(
                onPressed: _loading ? null : _startVerification,
                style: ElevatedButton.styleFrom(
                  backgroundColor: const Color(0xFF1A1A1A),
                  foregroundColor: Colors.white,
                  padding: const EdgeInsets.symmetric(vertical: 16),
                  shape: RoundedRectangleBorder(
                    borderRadius: BorderRadius.circular(8),
                  ),
                ),
                child: _loading
                    ? const SizedBox(
                        height: 20,
                        width: 20,
                        child: CircularProgressIndicator(
                          strokeWidth: 2,
                          color: Colors.white,
                        ),
                      )
                    : const Text(
                        'Start Verification',
                        style: TextStyle(fontWeight: FontWeight.w600),
                      ),
              ),
            ],
          ),
        ),
      ),
    );
  }
}
```

***


# iOS SDK
Source: https://docs.didit.me/integration/native-sdks/ios-sdk

Native iOS Swift SDK for KYC, KYB, biometric liveness, and AML. NFC passport reading, on-device capture. Pay-per-use pricing, 500 free/month.

<AgentPromptAccordion title="iOS SDK Integration Prompt" />

A lightweight, server-driven iOS SDK for identity verification with minimal configuration required. **Latest version: 4.7.6.**

<Card title="GitHub Repository" icon="github" href="https://github.com/didit-protocol/sdk-ios">
  View source code, releases, and the complete changelog on GitHub
</Card>

<Note>
  ### **Native SDK**: This is the recommended approach for iOS apps. Native SDKs provide the best user experience, optimized camera handling, and full NFC support.
</Note>

***

## Requirements

| Requirement | Minimum Version |
| ----------- | --------------- |
| iOS         | 13.0+           |
| Xcode       | 15.0+           |
| Swift       | 5.9+            |

### iOS Version Compatibility

| iOS Version     | Features Available                           |
| --------------- | -------------------------------------------- |
| iOS 13.0 - 14.x | All features **except** NFC passport reading |
| iOS 15.0+       | All features including NFC passport reading  |

***

## Installation

Since `4.0.0` the SDK ships in **four installable variants**, so your app only pays the binary cost of the features it uses. Pick exactly one variant — one CocoaPods subspec and one SwiftPM library product:

| Variant           | CocoaPods                | SwiftPM product         | NFC | Auto-detection | OpenSSL         | Minimum iOS |
| ----------------- | ------------------------ | ----------------------- | :-: | :------------: | --------------- | ----------- |
| **Core**          | `DiditSDK/Core`          | `DiditSDKCore`          |  –  |        –       | none            | iOS 13.0+   |
| **AutoDetection** | `DiditSDK/AutoDetection` | `DiditSDKAutoDetection` |  –  |        ✓       | none            | iOS 13.0+   |
| **NFC**           | `DiditSDK/NFC`           | `DiditSDKNFC`           |  ✓  |        –       | `3.3.3` bundled | iOS 15.0+   |
| **All** (default) | `DiditSDK/All`           | `DiditSDK`              |  ✓  |        ✓       | `3.3.3` bundled | iOS 15.0+   |

* **Core** — smallest footprint, manual capture only. No `OpenSSL.xcframework`, no CoreNFC runtime, no ML runtime.
* **AutoDetection** — ML-based document/face auto-capture, but no NFC chip reading.
* **NFC** — NFC passport/eID chip reading without the auto-capture ML runtime.
* **All** — every feature. This is the default when you install `DiditSDK` without naming a subspec/product.

What each variant adds to your app bundle (device-slice framework, measured against `4.7.6`): **Core** \~13.5 MB, **NFC** \~14.5 MB plus \~4 MB of OpenSSL, **AutoDetection** \~18.3 MB, **All** \~19.4 MB plus OpenSSL.
The detection models themselves are downloaded at runtime and cached, so they never count against your app's download size.

Since `4.7.1` the **AutoDetection** and **All** variants run auto-capture inference on a leaner ML runtime in place of the MediaPipe runtime used through `4.6.0`. This is a cutover, not an opt-in variant - it applies unconditionally to anyone on `4.7.1` or later, so there is no separate "previous engine" variant to install instead. Measured on the release artifacts: **-3.4 MB (-28%)** off the compressed App Store download payload and **-8.5 MB (-35%)** off the arm64 binary shipped inside your app (the uncompressed device-slice framework itself is about 12 MB smaller). Detection behavior is verified frame-by-frame identical to the previous engine on a physical-device matrix before release, and document inference is measurably faster.

<Note>
  **Rolling back the runtime change**: because this is a cutover rather than a variant, reverting it means pinning your dependency to `4.6.0` (SwiftPM: select version `4.6.0` instead of "Up to Next Major"; CocoaPods: point `podspec_url` at the `4.6.0` tag), not switching a flag. Didit tracks this runtime's field performance for a release cycle after launch; if a regression surfaces, the response is a pin-back advisory plus a patch release on the current runtime - never a variant switch, since none exists.
</Note>

Since `4.6.0` the shipped frameworks no longer carry Swift ABI descriptors (build metadata Xcode copied into every app but never read) or tutorial videos the variant cannot play — upgrading from `4.5.4` or earlier shrinks your app by roughly 7-8 MB on its own, with no code changes.
The App Store compresses binaries for delivery, so the over-the-air cost is lower — check App Store Connect's app size report for the exact per-device delta.

<Note>
  The **NFC** and **All** variants bundle `OpenSSL.xcframework` (**OpenSSL 3.3.3**, shipped as `OpenSSL-Universal 3.3.3001` via `NFCPassportReader`), which is required for NFC chip authentication and needs iOS 15.0+. Releases **up to and including 4.0.6** bundled OpenSSL `1.1.1s`; **4.0.7 and later** ship OpenSSL 3.3.3 with its own privacy manifest and code signature — always install **4.0.7 or later**. Note that upgrading aligns OpenSSL *versions* but does not remove *embed* collisions: if another dependency in your app also embeds an `OpenSSL.framework` (same filename, same `com.github.krzyzanowskim.OpenSSL` bundle id), the two copies collide at the embed step regardless of version. Keep exactly one copy — for example, override the other package by SPM identity to use the Didit-published `OpenSSL.xcframework`, so the binary in the bundle is the one this SDK was built against. The **Core** and **AutoDetection** variants link no OpenSSL at all.
</Note>

`import DiditSDK` is the same in your app code regardless of the variant you install.

### Swift Package Manager (Recommended)

Add the package to your project using Xcode:

1. Go to **File > Add Package Dependencies**
2. Enter the repository URL:

```
https://github.com/didit-protocol/sdk-ios.git
```

3. Select the version (or **Up to Next Major** from `4.7.6`) and click **Add Package**
4. When prompted to choose a product, pick exactly one library product for your variant (see the table above)

Or in your `Package.swift`:

```swift theme={null}
dependencies: [
    .package(url: "https://github.com/didit-protocol/sdk-ios.git", from: "4.7.6")
]
```

Then add exactly one of these products to your target:

```swift theme={null}
// All (default — NFC + auto-detection)
.product(name: "DiditSDK", package: "DiditSDK")

// Core (no NFC, no auto-detection, no OpenSSL)
.product(name: "DiditSDKCore", package: "DiditSDK")

// AutoDetection (auto-capture, no NFC)
.product(name: "DiditSDKAutoDetection", package: "DiditSDK")

// NFC (NFC passport reading, no auto-detection)
.product(name: "DiditSDKNFC", package: "DiditSDK")
```

<Warning>
  **Swift Package Manager does not enforce the iOS 15 floor for you.** `Package.swift` declares
  `platforms: [.iOS(.v13)]` for the whole package, so Xcode will let you add `DiditSDK` or
  `DiditSDKNFC` to an iOS 13 or 14 target without complaint — but both bundle `OpenSSL.xcframework`
  and read chips through `NFCPassportReader`, which need **iOS 15.0+**. Set your target's deployment
  target to 15.0 yourself when using the `All` or `NFC` product. CocoaPods enforces this
  automatically via the subspec's `deployment_target`.
</Warning>

### CocoaPods

`DiditSDK` is distributed as a binary podspec hosted in the repo (it is not on the public CocoaPods Trunk), so you must reference the podspec URL. Pick exactly one subspec:

```ruby theme={null}
podspec_url = 'https://raw.githubusercontent.com/didit-protocol/sdk-ios/4.7.6/DiditSDK.podspec'

# All (NFC + auto-detection, iOS 15.0+):
platform :ios, '15.0'
pod 'DiditSDK/All', :podspec => podspec_url

# Core (no NFC, no auto-detection, iOS 13.0+):
# pod 'DiditSDK/Core', :podspec => podspec_url

# AutoDetection (auto-capture, no NFC, iOS 13.0+):
# pod 'DiditSDK/AutoDetection', :podspec => podspec_url

# NFC (NFC passport reading, iOS 15.0+):
# pod 'DiditSDK/NFC', :podspec => podspec_url
```

`Core` and `AutoDetection` deploy down to iOS 13; `NFC` and `All` require iOS 15 because of `NFCPassportReader`.

Then run:

```bash theme={null}
pod install
```

<Note>
  After `pod install`, open the generated `.xcworkspace` (not `.xcodeproj`).
</Note>

<Note>
  **Xcode 15+ rsync errors**: If you see `Operation not permitted` rsync errors during build, set **Build Settings → User Script Sandboxing** (`ENABLE_USER_SCRIPT_SANDBOXING`) to **No** on the project for both Debug and Release.
</Note>

### Manual (XCFramework)

Each release publishes one XCFramework per variant. Download the zips for your variant from the [GitHub Releases](https://github.com/didit-protocol/sdk-ios/releases) page, then drag the `.xcframework` folders into Xcode and set **Embed & Sign**.

| Variant           | Download                                                   |
| ----------------- | ---------------------------------------------------------- |
| **Core**          | `DiditSDK-Core.xcframework.zip`                            |
| **AutoDetection** | `DiditSDK-AutoDetection.xcframework.zip`                   |
| **NFC**           | `DiditSDK-NFC.xcframework.zip` + `OpenSSL.xcframework.zip` |
| **All**           | `DiditSDK.xcframework.zip` + `OpenSSL.xcframework.zip`     |

***

## Permissions

The SDK requires the following permissions. Add these to your app's `Info.plist`:

| Permission    | Info.plist Key                        | Description                             | Required         |
| ------------- | ------------------------------------- | --------------------------------------- | ---------------- |
| Camera        | `NSCameraUsageDescription`            | Document scanning and face verification | ✅ Yes            |
| Microphone    | `NSMicrophoneUsageDescription`        | Video recording for liveness checks     | ✅ Yes            |
| Photo Library | `NSPhotoLibraryUsageDescription`      | Upload documents from device gallery    | ✅ Yes            |
| NFC           | `NFCReaderUsageDescription`           | Read NFC chips in passports/ID cards    | ⚠️ Full SDK only |
| Location      | `NSLocationWhenInUseUsageDescription` | Geolocation for fraud prevention        | ❌ Optional       |

### Example Info.plist Entries

```xml theme={null}
<key>NSCameraUsageDescription</key>
<string>Camera access is required to scan your identity documents for verification.</string>

<key>NSMicrophoneUsageDescription</key>
<string>Microphone access is required to record video for liveness verification.</string>

<key>NSPhotoLibraryUsageDescription</key>
<string>Photo library access is required to upload document images.</string>

<key>NFCReaderUsageDescription</key>
<string>NFC access is required to read the chip in your identity document.</string>

<key>NSLocationWhenInUseUsageDescription</key>
<string>Location access helps verify your identity and prevent fraud.</string>
```

### NFC Configuration

Required only when installing the **NFC** or **All** variant. Skip this section if you installed the **Core** or **AutoDetection** variant.

To enable NFC reading for passports and ID cards with chips:

1. **Add NFC Capability** in Xcode:
   * Select your target → **Signing & Capabilities** → **+ Capability** → **Near Field Communication Tag Reading**

2. **Add ISO7816 Identifiers** to `Info.plist`:

```xml theme={null}
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
    <string>D23300000045737445494420763335</string>
    <string>A0000002471001</string>
    <string>A0000002472001</string>
    <string>00000000000000</string>
</array>
```

3. **Add Entitlements** (in your `.entitlements` file):

```xml theme={null}
<key>com.apple.developer.nfc.readersession.formats</key>
<array>
    <string>TAG</string>
</array>
```

<Warning>
  **Simulator Limitation (NFC and All variants)**: These variants link CoreNFC, and since Xcode 12 `libnfshared.dylib` is missing from simulators. See [this Stack Overflow thread](https://stackoverflow.com/questions/63915728/xcode12-corenfc-simulator-library-not-loaded) for a workaround. This does **not** apply to the **Core** or **AutoDetection** variant. Test NFC features on physical devices only.
</Warning>

<Note>
  ### **App Store Review (NFC and All variants)**: If you install the **NFC** or **All** variant, Apple may request a demo video during review because NFC-related code is part of the SDK binary — even if your workflow does not use NFC. Download our NFC demo video to submit to Apple: [Download NFC Demo Video](https://business.didit.me/videos/passport-nfc.mp4). This does not apply to the **Core** or **AutoDetection** variant.
</Note>

***

## Quick Start

### SwiftUI Integration

```swift theme={null}
import SwiftUI
import DiditSDK

struct ContentView: View {
    var body: some View {
        Button("Verify Identity") {
            // Method 1: UniLink — no backend required
            DiditSdk.shared.startVerification(workflowId: "your-workflow-id")
            
            // Method 2: Backend Session — full parameter control
            // DiditSdk.shared.startVerification(token: "your-session-token")
        }
        .diditVerification { result in
            handleResult(result)
        }
    }
    
    private func handleResult(_ result: VerificationResult) {
        switch result {
        case .completed(let session):
            print("Completed: \(session.status)")
        case .cancelled(let session):
            print("Cancelled")
        case .failed(let error, _):
            print("Failed: \(error.localizedDescription)")
        }
    }
}
```

### UIKit Integration

```swift theme={null}
import UIKit
import DiditSDK

class VerificationViewController: UIViewController {
    override func viewDidLoad() {
        super.viewDidLoad()
        
        // Start verification when ready
        DiditSdk.shared.startVerification(token: "your-session-token")
    }
}
```

***

## Integration Methods

The SDK supports two integration methods:

### Method 1: UniLink (Simplest)

No backend required. The SDK creates the session directly using your workflow ID from the [Didit Console](https://business.didit.me). The UniLink method (`startVerification(workflowId:)`) only supports `vendorData`; for any other session parameters use Method 2.

<Note>
  For `vendorData` to be attached to the session via UniLink, enable the **Vendor Data** option in the [Didit Console](https://business.didit.me).
</Note>

```swift theme={null}
DiditSdk.shared.startVerification(
    workflowId: "your-workflow-id",
    vendorData: "user-123"
)
```

### Method 2: Backend Session (Recommended for Production)

Your backend creates the session via the [Create Verification Session API](/sessions-api/create-session) (`POST /v3/session/`) with full parameter support (`contact_details`, `expected_details`, `metadata`, `callback`, etc.), then passes the `session_token` to the SDK.

```swift theme={null}
// Your backend creates a session and returns the token
let sessionToken = await yourBackend.createVerificationSession(userId: currentUser.id)

// Pass the token to the SDK
DiditSdk.shared.startVerification(token: sessionToken)
```

This approach gives you full control over:

* Associating sessions with your users (`vendor_data`)
* Setting contact details and expected details for cross-validation
* Setting custom metadata
* Configuring callbacks per session
  This data (contact details, expected details, metadata, callback) is sent to the [Create Verification Session API](/sessions-api/create-session).

***

## Configuration

Customize the SDK behavior with `DiditSdk.Configuration`:

```swift theme={null}
let configuration = DiditSdk.Configuration(
    languageLocale: .spanish,      // Force Spanish language
    fontFamily: "Avenir",          // Custom font (must be registered in your app)
    loggingEnabled: true,          // Enable debug logging
    showCloseButton: true,         // Show close (X) button on step screens
    showExitConfirmation: true,    // Show confirmation dialog when user taps close
    closeOnComplete: false         // Don't auto-dismiss on completion
)

DiditSdk.shared.startVerification(
    token: "your-session-token",
    configuration: configuration
)
```

### Configuration Options

| Property               | Type                 | Default       | Description                                                                               |
| ---------------------- | -------------------- | ------------- | ----------------------------------------------------------------------------------------- |
| `languageLocale`       | `SupportedLanguage?` | Device locale | Force a specific language                                                                 |
| `fontFamily`           | `String?`            | System font   | Custom font family name (must be registered in your app via `UIAppFonts` in `Info.plist`) |
| `loggingEnabled`       | `Bool`               | `false`       | Enable SDK debug logging                                                                  |
| `showCloseButton`      | `Bool`               | `true`        | Show close (X) button on verification step screens                                        |
| `showExitConfirmation` | `Bool`               | `true`        | Show confirmation dialog when user attempts to exit                                       |
| `closeOnComplete`      | `Bool`               | `false`       | Auto-dismiss verification UI when complete (Web SDK equivalent: `closeModalOnComplete`)   |

<Info>
  **Theming & Colors**: Colors, backgrounds, and intro screen settings are configured through your [White Label settings](https://business.didit.me) in the Didit Console, not in the SDK configuration. This ensures consistent branding across all platforms.
</Info>

<Info>
  Options `showCloseButton`, `showExitConfirmation`, and `closeOnComplete` match the Web SDK's `DiditSdkConfiguration`. Mobile-specific options `languageLocale` and `fontFamily` exist because the mobile SDK renders the full verification UI natively (unlike the Web SDK which delegates to the hosted frontend inside an iframe).
</Info>

***

## Language Support

The SDK supports **53 languages**. If no language is specified, the SDK uses the device locale with English as fallback.

```swift theme={null}
// Use device locale (default)
let config = DiditSdk.Configuration()

// Force specific language
let config = DiditSdk.Configuration(languageLocale: .french)

// Detect device locale programmatically
let deviceLanguage = SupportedLanguage.fromDeviceLocale()
```

**[View All Supported Languages →](/integration/supported-languages)**

***

## Advanced Session Parameters

For advanced session parameters (`contact_details`, `expected_details`, `metadata`, `callback`), use the **Backend Session** method. Your backend calls the [Create Verification Session API](/sessions-api/create-session) with full parameters, then passes the `session_token` to the SDK.

***

## Handling Results

The `VerificationResult` enum provides the outcome of the verification:

### Result Cases

| Case                      | Description                                                     |
| ------------------------- | --------------------------------------------------------------- |
| `.completed(session:)`    | Verification flow completed (check `session.status` for result) |
| `.cancelled(session:)`    | User cancelled the verification flow                            |
| `.failed(error:session:)` | An error occurred during verification                           |

### SessionData Properties

| Property       | Type                 | Description                             |
| -------------- | -------------------- | --------------------------------------- |
| `sessionId`    | `String`             | Unique session identifier               |
| `status`       | `VerificationStatus` | `.approved`, `.pending`, or `.declined` |
| `country`      | `String?`            | Country code (ISO 3166-1 alpha-3)       |
| `documentType` | `String?`            | Document type used for verification     |

### Error Types

| Error                 | Description                   |
| --------------------- | ----------------------------- |
| `.sessionExpired`     | The session has expired       |
| `.networkError`       | Network connectivity issue    |
| `.cameraAccessDenied` | Camera permission not granted |
| `.unknown(String)`    | Other error with message      |

### Complete Result Handling Example

```swift theme={null}
.diditVerification { result in
    switch result {
    case .completed(let session):
        switch session.status {
        case .approved:
            print("✅ Approved! Session: \(session.sessionId)")
            // User is verified - grant access
            
        case .pending:
            print("⏳ Under review. Session: \(session.sessionId)")
            // Show "verification in progress" UI
            
        case .declined:
            print("❌ Declined. Session: \(session.sessionId)")
            // Handle declined verification
        }
        
    case .cancelled(let session):
        if let session = session {
            print("🚫 Cancelled session: \(session.sessionId)")
        }
        // User chose to cancel - maybe show retry option
        
    case .failed(let error, let session):
        print("⚠️ Error: \(error.localizedDescription)")
        // Handle error - show retry or contact support
    }
}
```

***

## Dismissing the Verification Programmatically

<Note>
  Available in DiditSDK **3.6.0+**.
</Note>

The host app can end an active verification programmatically with `DiditSdk.shared.dismiss()`. This is the recommended way to tear down the verification when the host needs to take over the screen — for example, when the app moves to the background.

```swift theme={null}
DiditSdk.shared.dismiss()
```

`dismiss()` goes through the SDK's normal completion pipeline: it dismisses the presented UI, resets internal state, and invokes the `.diditVerification` handler with `.cancelled(session:)` carrying the current `sessionId` if a session was created. It is a no-op when no verification is active.

### Example: dismiss when the app backgrounds

```swift theme={null}
NotificationCenter.default.addObserver(
    forName: UIApplication.didEnterBackgroundNotification,
    object: nil,
    queue: .main
) { _ in
    DiditSdk.shared.dismiss()
}
```

<Warning>
  Do **not** set `DiditSdk.shared.isPresented = false` to dismiss — the flag only triggers presentation on its rising edge and setting it to `false` is a no-op. Likewise, calling UIKit's `dismiss(animated:)` on the topmost view controller is not supported: it bypasses the SDK's completion pipeline so your `.diditVerification` handler is never fired.
</Warning>

***

## Observing SDK State

You can observe the SDK state for custom loading UI:

```swift theme={null}
struct CustomView: View {
    @ObservedObject private var sdk = DiditSdk.shared
    
    var body: some View {
        VStack {
            switch sdk.state {
            case .idle:
                Text("Ready to verify")
            case .creatingSession:
                ProgressView("Creating session...")
            case .loading:
                ProgressView("Loading...")
            case .ready:
                Text("Verification in progress")
            case .error(let message):
                Text("Error: \(message)")
            }
        }
    }
}
```

***

## End-to-End Example (Backend Session → iOS SDK → Result)

This pattern is the production-ready integration. Your backend creates the session, your iOS app receives the `session_token`, and the SDK runs the flow.

### 1. Backend — create the session

```ts theme={null}
// Node.js / Express example. Run on your server. NEVER ship DIDIT_API_KEY to the device.
import express from "express";

const app = express();
app.use(express.json());

app.post("/api/verification/start", async (req, res) => {
  const response = await fetch("https://verification.didit.me/v3/session/", {
    method: "POST",
    headers: {
      "x-api-key": process.env.DIDIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      workflow_id: process.env.DIDIT_WORKFLOW_ID,
      vendor_data: req.body.userId, // your stable user id
    }),
  });

  if (!response.ok) {
    return res.status(500).json({ error: `Didit ${response.status}` });
  }

  const { session_id, session_token } = await response.json();
  // Persist session_id <-> userId so you can match the webhook later.
  res.json({ session_id, session_token });
});
```

### 2. iOS — exchange and start the SDK

```swift theme={null}
import SwiftUI
import DiditSDK

struct VerifyButton: View {
    let userId: String
    @State private var error: String?

    var body: some View {
        Button("Verify Identity") {
            Task { await start() }
        }
        .diditVerification { result in
            switch result {
            case .completed(let session) where session.status == .approved:
                // Optimistically reflect success in the UI; rely on the webhook
                // delivered to your backend as the source of truth.
                break
            case .completed(let session):
                print("Terminal status: \(session.status.rawValue)")
            case .cancelled:
                print("User cancelled")
            case .failed(let err, _):
                error = err.localizedDescription
            }
        }
    }

    private func start() async {
        do {
            var req = URLRequest(url: URL(string: "https://your-backend.example.com/api/verification/start")!)
            req.httpMethod = "POST"
            req.setValue("application/json", forHTTPHeaderField: "Content-Type")
            req.httpBody = try JSONEncoder().encode(["userId": userId])

            let (data, _) = try await URLSession.shared.data(for: req)
            struct Payload: Decodable { let session_token: String }
            let payload = try JSONDecoder().decode(Payload.self, from: data)

            await MainActor.run {
                DiditSdk.shared.startVerification(token: payload.session_token)
            }
        } catch {
            self.error = error.localizedDescription
        }
    }
}
```

### 3. Backend — receive the final decision via webhook

The SDK result is convenient for UI feedback, but the authoritative outcome arrives via webhook. See the [Webhooks guide](/integration/webhooks) for HMAC verification.

```ts theme={null}
app.post("/api/webhooks/didit", express.raw({ type: "application/json" }), (req, res) => {
  // 1. Verify the X-Signature header (see Webhooks docs)
  // 2. Parse the body
  const event = JSON.parse(req.body.toString());
  if (event.webhook_type === "status.updated") {
    // event.session_id, event.status ("Approved" | "Declined" | "In Review" | ...)
    // Look up the user by session_id and update their verification state.
  }
  res.sendStatus(200);
});
```

***

## Complete SwiftUI Example

```swift theme={null}
import SwiftUI
import DiditSDK

struct HomeView: View {
    @State private var resultMessage: String?
    @State private var isVerified = false
    
    var body: some View {
        VStack(spacing: 24) {
            if isVerified {
                Image(systemName: "checkmark.circle.fill")
                    .font(.system(size: 64))
                    .foregroundColor(.green)
                Text("Identity Verified")
                    .font(.title2)
            } else {
                Button("Verify Identity") {
                    startVerification()
                }
                .font(.headline)
                .padding(.horizontal, 32)
                .padding(.vertical, 16)
                .background(Color.blue)
                .foregroundColor(.white)
                .cornerRadius(12)
            }
            
            if let message = resultMessage {
                Text(message)
                    .foregroundColor(.secondary)
                    .multilineTextAlignment(.center)
                    .padding()
            }
        }
        .diditVerification { result in
            handleResult(result)
        }
    }
    
    private func startVerification() {
        let config = DiditSdk.Configuration(
            languageLocale: .english
        )
        
        // Method 1: UniLink — no backend required
        DiditSdk.shared.startVerification(
            workflowId: "your-workflow-id",
            vendorData: "user-123",
            configuration: config
        )
        
        // Method 2: Backend Session — full parameter control
        // DiditSdk.shared.startVerification(
        //     token: "your-session-token",
        //     configuration: config
        // )
    }
    
    private func handleResult(_ result: VerificationResult) {
        switch result {
        case .completed(let session):
            if session.status == .approved {
                isVerified = true
            }
            resultMessage = """
                Status: \(session.status.rawValue)
                Session: \(session.sessionId)
                Country: \(session.country ?? "N/A")
                Document: \(session.documentType ?? "N/A")
                """
                
        case .cancelled(let session):
            resultMessage = "Cancelled - Session: \(session?.sessionId ?? "unknown")"
            
        case .failed(let error, _):
            resultMessage = "Failed: \(error.localizedDescription)"
        }
    }
}
```

***


# Native SDKs
Source: https://docs.didit.me/integration/native-sdks/overview

Integrate Didit identity verification natively on iOS, Android, React Native, and Flutter. NFC, camera, and biometric support. Pay-per-use pricing.

Integrate Didit verification natively into your mobile applications with our official SDKs. Native SDKs provide a **seamless user experience**, **better performance**, and **full access to device capabilities** compared to WebView-based integrations.

<Note>
  ### **Recommended Approach**: For the best user experience, use our native SDKs instead of WebView integration. Native SDKs handle all the complexity of camera permissions, NFC reading, and liveness detection out of the box.
</Note>

***

## SDK Availability

| Platform     | Distribution                                    | Latest |     NFC     | Minimum Version                                          | Documentation                                                       |
| ------------ | ----------------------------------------------- | ------ | :---------: | -------------------------------------------------------- | ------------------------------------------------------------------- |
| iOS          | Swift Package Manager, CocoaPods                | 4.7.6  | ✅ (iOS 15+) | iOS 13.0+ (core), iOS 15.0+ (NFC)                        | [iOS SDK Guide](/integration/native-sdks/ios-sdk)                   |
| Android      | Maven (custom repo, `me.didit:didit-sdk`)       | 4.7.6  |      ✅      | API 23+ (Android 6.0)                                    | [Android SDK Guide](/integration/native-sdks/android-sdk)           |
| React Native | npm / yarn (`@didit-protocol/sdk-react-native`) | 4.7.7  |      ✅      | RN 0.76+ (New Architecture), iOS 13.0+ / Android API 24+ | [React Native SDK Guide](/integration/native-sdks/react-native-sdk) |
| Flutter      | pub.dev (`didit_sdk`)                           | 4.7.6  |      ✅      | Flutter 3.3+, Dart 3.11+, iOS 13.0+ / Android API 23+    | [Flutter SDK Guide](/integration/native-sdks/flutter-sdk)           |
| Web (JS)     | npm (`@didit-protocol/sdk-web`)                 | 0.3.1  |      —      | Any modern browser                                       | [Web SDK Guide](/integration/web-sdks/javascript-sdk)               |

<Note>
  ### **Alternative**: If a native SDK isn't available for your platform yet, you can use [WebView Integration](/integration/web-sdks/webview-in-ios-android) as a fallback.
</Note>

***

## How a verification session flows

Every native SDK consumes the same Didit verification session. The flow is:

1. **Your backend** calls [`POST /v3/session/`](/sessions-api/create-session) with `workflow_id` plus any optional context (`vendor_data`, `contact_details`, `expected_details`, `metadata`, `callback`).
2. Didit returns a `session_id`, a short-lived `session_token`, and a hosted `url`.
3. **Your mobile app** receives the `session_token` from your backend and passes it to the SDK (`startVerification(token: …)`).
4. The native SDK opens the verification UI, the user completes the steps, and the SDK returns a result with the session's terminal `status` (`Approved`, `Declined`, `In Review`, etc.).
5. **Your backend** receives the full decision via a [webhook](/integration/webhooks) (`webhook_type: "status.updated"`) and persists it.

<Info>
  The SDK result tells you the workflow outcome (status). The complete decision — document fields, face match scores, AML hits, NFC data, warnings — is delivered to your server via webhook and can also be fetched from the [Retrieve Session Decision](/sessions-api/retrieve-session) endpoint. Never trust the client-side result alone for authorisation decisions.
</Info>

All native SDKs also support a **UniLink** mode (workflow ID only, no backend required). Use UniLink for quick prototypes and the session-token method for production.

***

## iOS SDK

**When to use**: native Swift / SwiftUI / UIKit apps targeting iOS 13+.

A lightweight, server-driven iOS SDK for identity verification with minimal configuration required.

<Card title="GitHub Repository" icon="github" href="https://github.com/didit-protocol/sdk-ios">
  View source code and examples on GitHub
</Card>

**Key Features:**

* SwiftUI and UIKit support
* NFC passport/ID reading (iOS 15+; the no-NFC `Core` and `AutoDetection` variants strip NFC and OpenSSL, and deploy to iOS 13+)
* 53 languages supported
* Customizable UI theming
* Session token or workflow ID integration

**Quick Start:**

```swift theme={null}
import DiditSDK

// Start verification
DiditSdk.shared.startVerification(token: "your-session-token")

// Handle result
.diditVerification { result in
    switch result {
    case .completed(let session):
        print("Status: \(session.status)")
    case .cancelled:
        print("Cancelled")
    case .failed(let error, _):
        print("Error: \(error)")
    }
}
```

→ [**Full iOS SDK Documentation**](/integration/native-sdks/ios-sdk)

***

## Android SDK

**When to use**: native Kotlin / Jetpack Compose / Java apps targeting Android 6.0 (API 23) or higher.

A lightweight, server-driven Android SDK for identity verification with minimal configuration required.

<Card title="GitHub Repository" icon="github" href="https://github.com/didit-protocol/sdk-android">
  View source code and examples on GitHub
</Card>

**Key Features:**

* Kotlin and Jetpack Compose support
* NFC passport/ID reading (opt-in `me.didit:didit-sdk-core` artifact strips NFC dependencies)
* ML-based document and face auto-detection on API 24+ (graceful manual-capture fallback on API 23)
* 53 languages supported
* Customizable UI theming
* Session token or workflow ID integration

**Quick Start:**

```kotlin theme={null}
import me.didit.sdk.DiditSdk
import me.didit.sdk.VerificationResult

// Initialize in Application.onCreate()
DiditSdk.initialize(this)

// Start verification
DiditSdk.startVerification(token = "your-session-token") { result ->
    when (result) {
        is VerificationResult.Completed -> Log.d("Didit", "Status: ${result.session.status}")
        is VerificationResult.Cancelled -> Log.d("Didit", "Cancelled")
        is VerificationResult.Failed -> Log.e("Didit", "Error: ${result.error.message}")
    }
}
```

→ [**Full Android SDK Documentation**](/integration/native-sdks/android-sdk)

***

## React Native SDK

**When to use**: cross-platform React Native or Expo apps that need a single TypeScript API across iOS and Android (RN 0.76+, New Architecture).

A cross-platform React Native SDK that wraps the native iOS and Android SDKs with a unified TypeScript API.

<Card title="GitHub Repository" icon="github" href="https://github.com/didit-protocol/sdk-react-native">
  View source code and examples on GitHub
</Card>

**Key Features:**

* Single TypeScript API for both iOS and Android
* Expo support with zero-config config plugin (development build required — no Expo Go)
* React Native CLI support
* NFC passport/ID reading (toggle off with `DIDIT_SDK_IOS_NFC_ENABLED=false` / `diditSdkAndroidNfcEnabled=false`)
* 53 languages supported (inherited from native SDKs)
* Session token or workflow ID integration

**Quick Start:**

```tsx theme={null}
import { startVerification, VerificationStatus } from '@didit-protocol/sdk-react-native';

const result = await startVerification('your-session-token');

switch (result.type) {
  case 'completed':
    console.log('Status:', result.session.status);
    break;
  case 'cancelled':
    console.log('Cancelled');
    break;
  case 'failed':
    console.log('Error:', result.error.message);
    break;
}
```

→ [**Full React Native SDK Documentation**](/integration/native-sdks/react-native-sdk)

***

## Flutter SDK

**When to use**: cross-platform Flutter apps that need a single Dart API across iOS and Android (Flutter 3.3+, Dart 3.11+).

A cross-platform Flutter SDK that wraps the native iOS and Android SDKs with a unified Dart API.

<Card title="pub.dev Package" icon="flutter" href="https://pub.dev/packages/didit_sdk">
  View package on pub.dev
</Card>

**Key Features:**

* Single Dart API for both iOS and Android
* Platform channel integration with native SDKs
* NFC passport/ID reading (toggle off with `DIDIT_SDK_IOS_NFC_ENABLED=false` / `diditSdkAndroidNfcEnabled=false`)
* 53 languages supported (inherited from native SDKs)
* Session token or workflow ID integration

**Quick Start:**

```dart theme={null}
import 'package:didit_sdk/sdk_flutter.dart';

final result = await DiditSdk.startVerification('your-session-token');

switch (result) {
  case VerificationCompleted(:final session):
    print('Status: ${session.status}');
  case VerificationCancelled():
    print('Cancelled');
  case VerificationFailed(:final error):
    print('Error: ${error.message}');
}
```

→ [**Full Flutter SDK Documentation**](/integration/native-sdks/flutter-sdk)

***

## Web SDK (JavaScript)

**When to use**: browser-based apps and web frameworks (React, Vue, Angular, Next.js, Nuxt, Svelte, vanilla JS). The Web SDK opens the hosted verification flow in a modal or inline iframe — for mobile apps, prefer the native SDKs above.

A JavaScript SDK for web applications with React, Vue, Angular, Next.js, Nuxt, Svelte, and vanilla JS support.

<Card title="NPM Package" icon="npm" href="https://www.npmjs.com/package/@didit-protocol/sdk-web">
  View package on npm
</Card>

**Key Features:**

* Programmatic session management and event callbacks
* React, Vue, Angular, Next.js, Nuxt, Svelte, and vanilla JS support
* Full TypeScript support
* Modal & inline (embedded) modes
* State management for custom UI

**Quick Start:**

```typescript theme={null}
import { DiditSdk } from '@didit-protocol/sdk-web';

DiditSdk.shared.onComplete = (result) => {
  switch (result.type) {
    case 'completed':
      console.log('Status:', result.session?.status);
      break;
    case 'cancelled':
      console.log('Cancelled');
      break;
    case 'failed':
      console.error('Error:', result.error?.message);
      break;
  }
};

DiditSdk.shared.startVerification({
  url: 'https://verify.didit.me/session/session-token'
});
```

→ [**Full JavaScript SDK Documentation**](/integration/web-sdks/javascript-sdk) | [**All Web SDKs**](/integration/web-sdks/overview)

***

## Choosing an integration

Native SDKs are the best fit when you need NFC e-passport reading, the lowest-latency camera capture, and an in-app experience indistinguishable from your other native screens. Use **WebView Integration** as a fallback when you cannot ship a native SDK update (for example, brownfield apps you cannot rebuild, or platforms without a Didit native SDK).

| Feature                              |                 Native SDKs                |                   WebView                   |
| ------------------------------------ | :----------------------------------------: | :-----------------------------------------: |
| User experience                      |    Native screens, full gesture support    | Hosted web flow in a system browser/WebView |
| Camera capture                       |   On-device, SDK-tuned for ID and selfie   |              Browser-dependent              |
| NFC e-passport reading               | ✅ Supported (iOS 15+, NFC-capable Android) |               ❌ Not available               |
| Liveness performance                 |             Native ML pipeline             |             Browser ML pipeline             |
| White-label theming                  |              ✅ Console-driven              |               ✅ Console-driven              |
| App Store / Play Store review impact |    Adds NFC entitlement and binary size    |           None — just opens a URL           |
| When to use                          |   Production apps, NFC workflows, best UX  | Quick integration, web-only stack, fallback |


# React Native SDK
Source: https://docs.didit.me/integration/native-sdks/react-native-sdk

React Native and Expo SDK for KYC, KYB, biometric liveness, and AML. TypeScript API, native iOS and Android, NFC. Pay-per-use pricing, 500 free/month.

<AgentPromptAccordion title="React Native SDK Integration Prompt" />

A cross-platform React Native SDK that wraps the native iOS and Android SDKs, providing a unified TypeScript API for identity verification.

<Card title="GitHub Repository" icon="github" href="https://github.com/didit-protocol/sdk-react-native">
  View source code and examples on GitHub
</Card>

<Card title="npm Package" icon="npm" href="https://www.npmjs.com/package/@didit-protocol/sdk-react-native">
  @didit-protocol/sdk-react-native
</Card>

<Note>
  ### **Native SDK**: This is the recommended approach for React Native and Expo apps. The SDK wraps the native iOS and Android SDKs for the best user experience, optimized camera handling, and full NFC support.
</Note>

***

## Requirements

| Requirement  | Minimum Version                         |
| ------------ | --------------------------------------- |
| React Native | 0.76+ (New Architecture / TurboModules) |
| Node.js      | 20+                                     |
| TypeScript   | 5+                                      |

### Platform Requirements

| Platform | Minimum Version | Notes                                   |
| -------- | --------------- | --------------------------------------- |
| iOS      | 13.0+           | NFC passport reading requires iOS 15.0+ |
| Android  | API 24+ (7.0)   | Kotlin 1.9+, Java 17+                   |

***

## Installation

### Expo (Recommended)

```bash theme={null}
npx expo install @didit-protocol/sdk-react-native
```

Then add the config plugin to your `app.json` (or `app.config.js`). NFC is enabled by default:

```json theme={null}
{
  "expo": {
    "plugins": ["@didit-protocol/sdk-react-native"]
  }
}
```

That's it. The plugin automatically configures both platforms:

* **Android:** Adds the Didit Maven repository to Gradle, sets the `diditSdkAndroidNfcEnabled` Gradle property, and applies BouncyCastle dependency/packaging rules
* **iOS:** Adds the DiditSDK podspec to the Podfile (pinned to iOS 15 when NFC is enabled)

#### Disabling NFC dependencies

To build without NFC support (smaller binary, no NFC capability required), pass plugin options:

```json theme={null}
{
  "expo": {
    "plugins": [
      [
        "@didit-protocol/sdk-react-native",
        { "iosNfcEnabled": false, "androidNfcEnabled": false }
      ]
    ]
  }
}
```

When NFC is disabled, you do not need the iOS NFC capability, NFC entitlements, or NFC-related provisioning setup.

<Warning>
  This SDK uses native modules (camera, NFC) that are **not available in Expo Go**. You must use a [development build](https://docs.expo.dev/develop/development-builds/introduction/) or run `npx expo prebuild` to generate the native projects.
</Warning>

### React Native CLI

```bash theme={null}
npm install @didit-protocol/sdk-react-native
# or
yarn add @didit-protocol/sdk-react-native
```

#### iOS Setup

Add the DiditSDK pod to your `Podfile` (it's not on CocoaPods trunk). The block below honours an `DIDIT_SDK_IOS_NFC_ENABLED` environment variable so you can toggle the no-NFC subspec (`DiditSDK/Core`) at install time:

```ruby theme={null}
# In your ios/Podfile — at the top, before the target block:
didit_sdk_ios_nfc_enabled = ENV.fetch('DIDIT_SDK_IOS_NFC_ENABLED', 'true').downcase != 'false'

def max_ios_version(*versions)
  versions.map(&:to_s).max_by { |version| Gem::Version.new(version) }
end

platform :ios, didit_sdk_ios_nfc_enabled ? max_ios_version(min_ios_version_supported, '15.0') : min_ios_version_supported

# Inside your app target:
didit_sdk_ios_pod = didit_sdk_ios_nfc_enabled ? 'DiditSDK' : 'DiditSDK/Core'
pod didit_sdk_ios_pod, :podspec => 'https://raw.githubusercontent.com/didit-protocol/sdk-ios/4.7.6/DiditSDK.podspec'
```

<Warning>
  The tag in the podspec URL must match `diditNativeSdkVersions.ios` in the installed package version.
  React Native `4.7.7` pins native iOS `4.7.6` and native Android `4.7.6`. Do not point the podspec
  at `main`: the package depends on that exact native iOS version, so as soon as `main` moves ahead CocoaPods sees two incompatible requirements for
  `DiditSDK` and every `pod install` fails. The Expo config plugin derives this URL for you; only the
  bare React Native CLI path needs it written out by hand.
</Warning>

Then install dependencies:

```bash theme={null}
cd ios
bundle exec pod install
```

To rebuild without NFC dependencies, clean CocoaPods and re-run with the env var set:

```bash theme={null}
cd ios
rm -rf Pods Podfile.lock
DIDIT_SDK_IOS_NFC_ENABLED=false bundle exec pod install
```

#### Android Setup

Add the Didit Maven repository to your project-level `settings.gradle`:

```groovy theme={null}
dependencyResolutionManagement {
    repositories {
        google()
        mavenCentral()
        maven { url "https://raw.githubusercontent.com/didit-protocol/sdk-android/main/repository" }
    }
}
```

Add the following to your app's `android/app/build.gradle` (inside the `android { ... }` block) to resolve BouncyCastle duplicate-class conflicts and the OSGI `MANIFEST.MF` duplicate that the DiditSDK transitive dependencies can trigger:

```groovy theme={null}
android {
    configurations.configureEach {
        exclude group: 'org.bouncycastle', module: 'bcprov-jdk15to18'
        exclude group: 'org.bouncycastle', module: 'bcutil-jdk15to18'
        exclude group: 'org.bouncycastle', module: 'bcpkix-jdk15to18'
        exclude group: 'org.bouncycastle', module: 'bcprov-jdk15on'
    }
    packaging {
        resources {
            pickFirsts += ['org/bouncycastle/**']
            excludes += 'META-INF/versions/9/OSGI-INF/MANIFEST.MF'
        }
    }
}
```

To build without Android NFC dependencies (uses the `me.didit:didit-sdk-core` artifact instead of `me.didit:didit-sdk`), add this to `android/gradle.properties`:

```properties theme={null}
diditSdkAndroidNfcEnabled=false
```

Remove that property, or set it to `true`, to use the full Android SDK with NFC.

***

## Permissions

### iOS

Add the following keys to your app's `Info.plist`. Missing required iOS privacy keys will cause iOS to terminate the app as soon as the SDK accesses that protected resource.

| Permission    | Info.plist Key                        | Description                             | Required     |
| ------------- | ------------------------------------- | --------------------------------------- | ------------ |
| Camera        | `NSCameraUsageDescription`            | Document scanning and face verification | Yes          |
| Microphone    | `NSMicrophoneUsageDescription`        | Liveness video recording                | Yes          |
| Photo Library | `NSPhotoLibraryUsageDescription`      | Upload document images                  | Yes          |
| Location      | `NSLocationWhenInUseUsageDescription` | Geolocation for fraud prevention        | Yes          |
| NFC           | `NFCReaderUsageDescription`           | Read NFC chips in passports/ID cards    | If using NFC |

```xml theme={null}
<key>NSCameraUsageDescription</key>
<string>Camera access is required to scan your identity documents for verification.</string>
<key>NSMicrophoneUsageDescription</key>
<string>Microphone access is required to record video for liveness verification.</string>
<key>NSPhotoLibraryUsageDescription</key>
<string>Photo library access is required to upload document images.</string>
<key>NFCReaderUsageDescription</key>
<string>NFC is used to read passport chip data for identity verification.</string>
<key>NSLocationWhenInUseUsageDescription</key>
<string>Location access is used to detect your country for identity verification.</string>
```

#### NFC Configuration

To enable NFC reading for passports and ID cards with chips:

1. **Add NFC Capability** in Xcode:
   * Select your target > **Signing & Capabilities** > **+ Capability** > **Near Field Communication Tag Reading**

2. **Add ISO7816 Identifiers** to `Info.plist`:

```xml theme={null}
<key>com.apple.developer.nfc.readersession.iso7816.select-identifiers</key>
<array>
    <string>D23300000045737445494420763335</string>
    <string>A0000002471001</string>
    <string>A0000002472001</string>
    <string>00000000000000</string>
</array>
```

3. **Add an entitlements file** with NFC tag reading enabled:

```xml theme={null}
<key>com.apple.developer.nfc.readersession.formats</key>
<array>
    <string>TAG</string>
</array>
```

Make sure the app's provisioning profile includes the NFC Tag Reading capability. This NFC configuration is not needed when NFC is disabled.

### Android

The following permissions are declared in the SDK's `AndroidManifest.xml` and merged automatically:

| Permission             | Description                             | Required     |
| ---------------------- | --------------------------------------- | ------------ |
| `INTERNET`             | Network access for API communication    | Yes          |
| `ACCESS_NETWORK_STATE` | Detect network availability             | Yes          |
| `CAMERA`               | Document scanning and face verification | Yes          |
| `NFC`                  | Read NFC chips in passports/ID cards    | If using NFC |

Camera and NFC hardware features are declared as optional (`android:required="false"`), so your app can be installed on devices without these features.

***

## Quick Start

```tsx theme={null}
import { startVerification, VerificationStatus } from '@didit-protocol/sdk-react-native';

// Start verification with a session token from your backend
const result = await startVerification('your-session-token');

switch (result.type) {
  case 'completed':
    if (result.session.status === VerificationStatus.Approved) {
      console.log('Identity verified!');
    }
    break;
  case 'cancelled':
    console.log('User cancelled');
    break;
  case 'failed':
    console.log('Error:', result.error.message);
    break;
}
```

***

## Integration Methods

The SDK supports two integration methods:

### Method 1: Session Token (Recommended for Production)

Create a session on your backend using the [Create Verification Session API](/sessions-api/create-session), then pass the token to the SDK:

```tsx theme={null}
import { startVerification } from '@didit-protocol/sdk-react-native';

// Your backend creates a session and returns the token
const sessionToken = await yourBackend.createVerificationSession(userId);

// Pass the token to the SDK
const result = await startVerification(sessionToken);
```

This approach gives you full control over:

* Associating sessions with your users (`vendor_data`)
* Setting custom metadata
* Configuring callbacks per session

### Method 2: Workflow ID (Simpler Integration)

For simpler integrations, the SDK can create sessions directly using your workflow ID:

```tsx theme={null}
import { startVerificationWithWorkflow } from '@didit-protocol/sdk-react-native';

const result = await startVerificationWithWorkflow('your-workflow-id', {
  vendorData: 'user-123',
  contactDetails: { email: 'user@example.com' },
  config: { loggingEnabled: true },
});
```

***

## Configuration

Customize the SDK behavior by passing a `DiditConfig` object:

```tsx theme={null}
const result = await startVerification('your-session-token', {
  languageCode: 'es',           // Force Spanish language
  fontFamily: 'Avenir',         // Custom font (must be registered natively)
  loggingEnabled: true,         // Enable debug logging
  showCloseButton: true,        // Show close (X) button on step screens
  showExitConfirmation: true,   // Confirm before exit
  closeOnComplete: false,       // Auto-dismiss UI on completion
});
```

For `startVerificationWithWorkflow`, pass config inside `options.config`:

```tsx theme={null}
const result = await startVerificationWithWorkflow('your-workflow-id', {
  vendorData: 'user-123',
  config: {
    languageCode: 'es',
    loggingEnabled: true,
    showCloseButton: true,
    showExitConfirmation: true,
  },
});
```

### Configuration Options

| Property               | Type      | Default       | Description                                           |
| ---------------------- | --------- | ------------- | ----------------------------------------------------- |
| `languageCode`         | `string`  | Device locale | ISO 639-1 language code (e.g. `"en"`, `"fr"`, `"ar"`) |
| `fontFamily`           | `string`  | System font   | Custom font family name (must be registered natively) |
| `loggingEnabled`       | `boolean` | `false`       | Enable SDK debug logging                              |
| `showCloseButton`      | `boolean` | `true`        | Show close (X) button on verification step screens    |
| `showExitConfirmation` | `boolean` | `true`        | Show confirmation dialog when user attempts to exit   |
| `closeOnComplete`      | `boolean` | `false`       | Automatically dismiss verification UI when complete   |

<Info>
  **Theming & Colors**: Colors, backgrounds, and intro screen settings are configured through your [White Label settings](https://business.didit.me) in the Didit Console, not in the SDK configuration. This ensures consistent branding across all platforms.
</Info>

***

## Language Support

The SDK supports **53 languages**. If no language is specified, the SDK uses the device locale with English as fallback.

```tsx theme={null}
// Use device locale (default)
await startVerification(token);

// Force specific language
await startVerification(token, { languageCode: 'fr' });
```

**[View All Supported Languages →](/integration/supported-languages)**

***

## Advanced Options

These options are only available with `startVerificationWithWorkflow`, where the SDK creates the session on your behalf.

### Contact Details (Prefill & Notifications)

Provide contact details to prefill verification forms and enable email notifications:

```tsx theme={null}
const result = await startVerificationWithWorkflow('your-workflow-id', {
  contactDetails: {
    email: 'user@example.com',
    sendNotificationEmails: true,  // Send status update emails
    emailLang: 'en',               // Email language (ISO 639-1)
    phone: '+14155552671',         // E.164 format
  },
});
```

### Expected Details (Cross-Validation)

Provide expected user details for automatic cross-validation with extracted document data:

```tsx theme={null}
const result = await startVerificationWithWorkflow('your-workflow-id', {
  expectedDetails: {
    firstName: 'John',
    lastName: 'Doe',
    dateOfBirth: '1990-05-15',     // YYYY-MM-DD format
    gender: 'M',
    nationality: 'USA',            // ISO 3166-1 alpha-3
    country: 'USA',
    address: '1 Market St, San Francisco, CA',
    identificationNumber: 'A1234567',
    ipAddress: '203.0.113.42',
    portraitImage: 'https://...',  // URL or base64 reference image
  },
});
```

All `ExpectedDetails` fields are optional. See [`src/types.ts`](https://github.com/didit-protocol/sdk-react-native/blob/main/src/types.ts) for the full type.

### Custom Metadata

Store custom JSON metadata with the session (not displayed to user):

```tsx theme={null}
const result = await startVerificationWithWorkflow('your-workflow-id', {
  vendorData: 'user-123',
  metadata: '{"internalId": "abc123", "source": "mobile-app"}',
});
```

***

## Handling Results

Both `startVerification` and `startVerificationWithWorkflow` return a `Promise<VerificationResult>`. The result is a discriminated union — use the `type` field to determine the outcome.

### Result Cases

| Case        | Description                                                     |
| ----------- | --------------------------------------------------------------- |
| `completed` | Verification flow completed (check `session.status` for result) |
| `cancelled` | User cancelled the verification flow                            |
| `failed`    | An error occurred during verification                           |

### SessionData Properties

| Property    | Type                 | Description                          |
| ----------- | -------------------- | ------------------------------------ |
| `sessionId` | `string`             | Unique session identifier            |
| `status`    | `VerificationStatus` | `Approved`, `Pending`, or `Declined` |

### Error Types

| Error                | Description                        |
| -------------------- | ---------------------------------- |
| `sessionExpired`     | The session has expired            |
| `networkError`       | Network connectivity issue         |
| `cameraAccessDenied` | Camera permission not granted      |
| `notInitialized`     | SDK not initialized (Android only) |
| `apiError`           | API request failed                 |
| `unknown`            | Other error with message           |

### Complete Result Handling Example

```tsx theme={null}
import {
  startVerification,
  VerificationStatus,
  type VerificationResult,
} from '@didit-protocol/sdk-react-native';

async function verify(token: string) {
  const result: VerificationResult = await startVerification(token);

  switch (result.type) {
    case 'completed':
      switch (result.session.status) {
        case VerificationStatus.Approved:
          console.log('Approved! Session:', result.session.sessionId);
          // User is verified — grant access
          break;
        case VerificationStatus.Pending:
          console.log('Under review. Session:', result.session.sessionId);
          // Show "verification in progress" UI
          break;
        case VerificationStatus.Declined:
          console.log('Declined. Session:', result.session.sessionId);
          // Handle declined verification
          break;
      }
      break;

    case 'cancelled':
      console.log('User cancelled the verification.');
      // Maybe show retry option
      break;

    case 'failed':
      console.log(`Error [${result.error.type}]: ${result.error.message}`);
      // Handle error — show retry or contact support
      break;
  }
}
```

***

## End-to-End Example (Backend Session → React Native SDK → Webhook)

The production-ready integration: your backend creates the session, your RN app receives the `session_token`, and the SDK runs the flow. The final decision is delivered to your backend via webhook — never trust the client-side result alone.

### 1. Backend — create the session

```ts theme={null}
// Node.js / Express example. Run on your server. NEVER ship DIDIT_API_KEY to the device.
import express from "express";

const app = express();
app.use(express.json());

app.post("/api/verification/start", async (req, res) => {
  const response = await fetch("https://verification.didit.me/v3/session/", {
    method: "POST",
    headers: {
      "x-api-key": process.env.DIDIT_API_KEY!,
      "Content-Type": "application/json",
    },
    body: JSON.stringify({
      workflow_id: process.env.DIDIT_WORKFLOW_ID,
      vendor_data: req.body.userId, // your stable user id
    }),
  });

  if (!response.ok) {
    return res.status(500).json({ error: `Didit ${response.status}` });
  }

  const { session_id, session_token } = await response.json();
  // Persist session_id <-> userId so you can match the webhook later.
  res.json({ session_id, session_token });
});
```

### 2. React Native — exchange and start the SDK

```tsx theme={null}
import { useCallback, useState } from 'react';
import { Button, View } from 'react-native';
import {
  startVerification,
  VerificationStatus,
  type VerificationResult,
} from '@didit-protocol/sdk-react-native';

export function VerifyButton({ userId }: { userId: string }) {
  const [loading, setLoading] = useState(false);

  const onPress = useCallback(async () => {
    setLoading(true);
    try {
      const r = await fetch('https://your-backend.example.com/api/verification/start', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ userId }),
      });
      const { session_token } = await r.json();

      const result: VerificationResult = await startVerification(session_token);

      switch (result.type) {
        case 'completed':
          if (result.session.status === VerificationStatus.Approved) {
            // Optimistic UI; rely on the webhook delivered to your backend as the source of truth.
          }
          break;
        case 'cancelled':
          // User dismissed the flow
          break;
        case 'failed':
          // Show retry — result.error.type / result.error.message
          break;
      }
    } finally {
      setLoading(false);
    }
  }, [userId]);

  return (
    <View>
      <Button title={loading ? 'Starting...' : 'Verify identity'} onPress={onPress} disabled={loading} />
    </View>
  );
}
```

### 3. Backend — receive the final decision via webhook

```ts theme={null}
app.post("/api/webhooks/didit", express.raw({ type: "application/json" }), (req, res) => {
  // 1. Verify the X-Signature header (see Webhooks docs)
  // 2. Parse the body
  const event = JSON.parse(req.body.toString());
  if (event.webhook_type === "status.updated") {
    // event.session_id, event.status ("Approved" | "Declined" | "In Review" | ...)
    // Look up the user by session_id and update their verification state.
  }
  res.sendStatus(200);
});
```

See the [Webhooks guide](/integration/webhooks) for HMAC signature verification details.

***

## Complete Example

```tsx theme={null}
import { useState, useCallback } from 'react';
import {
  Text,
  View,
  TextInput,
  TouchableOpacity,
  Alert,
  ActivityIndicator,
  SafeAreaView,
} from 'react-native';
import {
  startVerification,
  VerificationStatus,
  type VerificationResult,
} from '@didit-protocol/sdk-react-native';

export default function App() {
  const [token, setToken] = useState('');
  const [loading, setLoading] = useState(false);

  const handleVerify = useCallback(async () => {
    if (!token.trim()) {
      Alert.alert('Error', 'Please enter a session token.');
      return;
    }

    setLoading(true);
    try {
      const result = await startVerification(token.trim(), {
        loggingEnabled: true,
      });

      switch (result.type) {
        case 'completed':
          Alert.alert(
            'Verification Complete',
            `Status: ${result.session.status}\nSession: ${result.session.sessionId}`
          );
          break;
        case 'cancelled':
          Alert.alert('Cancelled', 'The user cancelled the verification.');
          break;
        case 'failed':
          Alert.alert('Failed', `${result.error.type}: ${result.error.message}`);
          break;
      }
    } catch (error) {
      Alert.alert('Error', `Unexpected error: ${error}`);
    } finally {
      setLoading(false);
    }
  }, [token]);

  return (
    <SafeAreaView style={{ flex: 1, padding: 24, justifyContent: 'center' }}>
      <TextInput
        placeholder="Enter session token..."
        value={token}
        onChangeText={setToken}
        autoCapitalize="none"
        style={{
          borderWidth: 1,
          borderColor: '#ccc',
          borderRadius: 8,
          padding: 12,
          marginBottom: 16,
        }}
      />
      <TouchableOpacity
        onPress={handleVerify}
        disabled={loading}
        style={{
          backgroundColor: '#1a1a1a',
          borderRadius: 8,
          padding: 16,
          alignItems: 'center',
          opacity: loading ? 0.6 : 1,
        }}
      >
        {loading ? (
          <ActivityIndicator color="#fff" />
        ) : (
          <Text style={{ color: '#fff', fontWeight: '600' }}>
            Start Verification
          </Text>
        )}
      </TouchableOpacity>
    </SafeAreaView>
  );
}
```

***


# Programmatic Registration for AI Agents
Source: https://docs.didit.me/integration/programmatic-registration

Register and get Didit API credentials in 2 API calls — no browser, no 2FA. The most agent-native identity verification platform for Cursor, Claude, Devin.

## Overview

Didit is the **most agent-friendly identity verification platform**. AI coding agents (Cursor, Claude Code, GitHub Copilot, Devin, OpenHands, Codex) can register, configure workflows, and start verifying identities — all programmatically, without ever opening a browser.

**Why agents love Didit:**

* **2 API calls** from zero to credentials (register + verify-email).
* **No browser required** — fully headless, perfect for CI/CD and agent workflows.
* **No 2FA friction** for API accounts — tokens are returned immediately after email verification.
* **Auto-provisioned** organization and application with `api_key` in the verify response.
* **Full management API** — configure workflows, questionnaires, lists, billing, all via API.
* **MCP server** available — agents can discover and use Didit tools natively.

The full contract is published as [openapi-auth.json](/openapi-auth.json); the endpoints below are audited against it.

## Base URL

All endpoints in this guide live on the **auth host**:

```
https://apx.didit.me/auth/v2
```

This is a different host from the verification API (`https://verification.didit.me/v3`). The auth host issues JWT access tokens and manages applications. The verification host runs sessions, AML, workflows, etc., authenticated with the long-lived `api_key` you get from this flow.

## Quick start

<Warning>
  **Use a real, deliverable email address.** The endpoint sends the verification code synchronously, so reserved test domains (`@example.com`, `@example.org`, `@*.test`, `@*.example`, `@*.invalid`) get rejected by mail delivery and the call returns a `500`. Substitute the `you@yourdomain.com` placeholder below with an inbox you can read.
</Warning>

### Step 1: Register

```bash theme={null}
curl -X POST https://apx.didit.me/auth/v2/programmatic/register/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourdomain.com", "password": "MyStr0ng!Pass"}'
```

**Response** (`201 Created`):

```json theme={null}
{
  "message": "Registration successful. Check your email for the verification code.",
  "email": "you@yourdomain.com"
}
```

A 6-character alphanumeric verification code (e.g. `A3K9F2`) is emailed to the address. **The code expires 10 minutes after it is sent** — if it lapses, call this endpoint again with the same email and password: for a still-unverified account it returns `200` with `"A new verification code has been sent to your email."` and a fresh code. A dedicated `POST /programmatic/resend-otp/` endpoint (body: `{"email", "password"}`) also re-sends the code, with a 60-second cooldown between sends; both routes share the registration rate limit below.

### Step 2: Verify the code and get credentials

```bash theme={null}
curl -X POST https://apx.didit.me/auth/v2/programmatic/verify-email/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourdomain.com", "code": "A3K9F2"}'
```

**Response** (`200 OK`):

```json theme={null}
{
  "access_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "refresh_token": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
  "expires_in": 86400,
  "organization": {
    "uuid": "a1b2c3d4-5678-90ab-cdef-111111111111",
    "name": "developer"
  },
  "application": {
    "uuid": "b2c3d4e5-6789-01bc-defg-222222222222",
    "name": "developer",
    "client_id": "S9LIYGSoWNuGMLHsvEt9dQ",
    "api_key": "05mHcOWL8GathLZlz8oIDawYj9qFAcoSHtz-75PAkuo"
  }
}
```

You now have everything you need. Persist `application.api_key` securely and send it as the `x-api-key` header on every verification API call.

<Note>
  Tokens are **RS256-signed JWTs**. `expires_in` defaults to **86400 seconds (24 hours)**. The access token is only needed for the management endpoints on `apx.didit.me/auth/v2` — verification API traffic on `verification.didit.me/v3` is authenticated with the long-lived `api_key`, not the JWT.
</Note>

### Step 3: Use the API

```bash theme={null}
curl https://verification.didit.me/v3/sessions/ \
  -H "x-api-key: 05mHcOWL8GathLZlz8oIDawYj9qFAcoSHtz-75PAkuo"
```

## Subsequent logins

From any future machine, exchange your email and password for a fresh JWT:

```bash theme={null}
curl -X POST https://apx.didit.me/auth/v2/programmatic/login/ \
  -H "Content-Type: application/json" \
  -d '{"email": "you@yourdomain.com", "password": "MyStr0ng!Pass"}'
```

Returns `access_token` + `refresh_token` directly — no browser. From there, hit `GET /organizations/me/` to discover your `org_id` (the organization's `uuid`), then `GET /organizations/me/{org_id}/applications/` to list the organization's applications (each entry's `uuid` is an `app_id`), and finally `GET /organizations/me/{org_id}/applications/{app_id}/` to recover the `api_key`.

<Note>
  Console-created email/password accounts can also use `POST /programmatic/login/` after the email is verified. OAuth-only console accounts need to set a password before using this headless login endpoint.
</Note>

## Password requirements

Enforced server-side, **one rule at a time** — the first failure short-circuits with a bare-array error like `["Password must contain at least one uppercase letter."]`. (Other validation errors on this endpoint use the field-keyed `{"password": [...]}` envelope. The bare-array shape on password-strength rules is a known server-side inconsistency; treat it as `{"password": [...]}` in client code.)

| Rule              | Detail                                        |
| ----------------- | --------------------------------------------- |
| Minimum length    | 8 characters                                  |
| Uppercase letter  | At least one `A–Z`                            |
| Lowercase letter  | At least one `a–z`                            |
| Digit             | At least one `0–9`                            |
| Special character | At least one of `!@#$%^&*()_+-=[]{}\|;:,.<>?` |

## Rate limits and lockouts

Three independent controls protect the auth host. Any of them can trigger a `429` response; the `Retry-After` response header tells you how long to back off.

| Surface       | Limit                                                                                                                                      |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------------------ |
| Registration  | **5** attempts per **IP** per **hour** (shared with `POST /programmatic/resend-otp/`).                                                     |
| Verify-email  | **10** code attempts per **email** per **hour**, plus exponential backoff between attempts (30 s, doubling per failure, capped at 1 hour). |
| Login (IP)    | **20** attempts per **IP** per **minute**, and **100** per **IP** per **hour**.                                                            |
| Login (email) | Progressive lockout on the account: **5** consecutive failures → 15 min lockout; **10** → 1 hour; **20** → 24 hours.                       |

A `429` body looks like this:

```json theme={null}
{ "detail": "Too many login attempts from this IP address. Please wait before trying again." }
```

Verification API rate limits (e.g. 600 sessions/min) are independent and documented in [Rate limiting](/integration/rate-limiting).

## Managing applications

Once authenticated, you can retrieve, create, or update applications inside your organization.

This is a perfect fit for **resellers** that want one application per customer. Each application has its own `client_id`, `api_key`, metadata, and settings. It is also useful when your organization has different products, brands, regions, environments, or use cases you want to keep separate.

```bash theme={null}
# 1. Discover your org_id
curl https://apx.didit.me/auth/v2/organizations/me/ \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 2. List the organization's applications (each entry's uuid is an app_id)
curl "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 3. Create an application for a customer, product, or environment
curl -X POST "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Customer App",
    "website_url": "https://acme.example",
    "redirect_uris": ["https://acme.example/callback"],
    "terms_url": "https://acme.example/terms",
    "privacy_url": "https://acme.example/privacy"
  }'

# 4. Recover credentials (client_id + api_key) for an existing application
curl "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/$APP_ID/" \
  -H "Authorization: Bearer $ACCESS_TOKEN"

# 5. Update application metadata (PATCH — uuid, client_id, api_key never change)
curl -X PATCH "https://apx.didit.me/auth/v2/organizations/me/$ORG_ID/applications/$APP_ID/" \
  -H "Authorization: Bearer $ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Acme Production App",
    "website_url": "https://app.acme.example"
  }'
```

Listing, creating, or updating applications requires the user to be an **owner** or **admin** of the target organization; otherwise the response is `403`.

## What can agents do after registration?

With the `api_key`, agents have full access to the verification API. Audited paths on `https://verification.didit.me/v3`:

| API                              | What it does                                                   |
| -------------------------------- | -------------------------------------------------------------- |
| `POST /v3/session/`              | Create a verification session.                                 |
| `GET /v3/sessions/`              | List sessions.                                                 |
| `GET /v3/session/{id}/decision/` | Get the V3 decision (plural arrays — see Data models).         |
| `GET /v3/workflows/`             | List verification workflows.                                   |
| `GET /v3/questionnaires/`        | List custom questionnaires.                                    |
| `GET /v3/users/`                 | List end users (indexed by `vendor_data`).                     |
| `GET /v3/billing/balance/`       | Check credit balance.                                          |
| `POST /v3/billing/top-up/`       | Top up credits.                                                |
| `GET /v3/webhook/destinations/`  | Manage webhook destinations (list / create / update / delete). |

See the [Management API reference](/sessions-api/management-api) for the full surface.

## MCP server integration

For the best agent experience, use the Didit MCP server. Most coding agents (Cursor, Claude Code, Windsurf, etc.) accept this MCP server entry:

```json theme={null}
{
  "mcpServers": {
    "didit": {
      "command": "npx",
      "args": ["@didit-protocol/mcp-server"],
      "env": { "DIDIT_API_KEY": "your_api_key" }
    }
  }
}
```

See the [AI agent integration guide](/integration/ai-agent-integration) for details.

## Error envelope reference

All `apx.didit.me/auth/v2` endpoints share the same three response shapes (see `openapi-auth.json`):

* **Field-level validation** — `{"field": ["message", ...]}` with HTTP `400`.
* **Form-level validation** (notably password strength and verification-code errors) — bare array `["Invalid or expired verification code."]` with HTTP `400`.
* **Authentication / business rule** — `{"detail": "..."}` with `400`, `401`, `403`, `404`, or `429`. `429` responses carry a `Retry-After` response header telling you how long to back off (the body has only `detail`).

The verification host returns errors as `{"detail": "..."}` and 429s include `X-RateLimit-*` and `Retry-After` — see [Rate limiting](/integration/rate-limiting).


# Rate Limiting
Source: https://docs.didit.me/integration/rate-limiting

Didit API rate limits, X-RateLimit headers, Retry-After backoff, per-endpoint scopes, and 429 handling. Plan production traffic with confidence.

Didit enforces multiple layers of rate limiting to keep the API stable while still allowing healthy bursts of traffic. Limits are applied **per identifier** — your `x-api-key` or, if no API key is sent, your client IP. Each scope keeps an independent counter with a 60-second sliding window.

## Identifier and exemptions

The middleware picks a rate-limit identifier in this order in this order:

1. `x-api-key` header → key-scoped counter.
2. `X-Forwarded-For` first hop → IP-scoped counter.
3. `REMOTE_ADDR` → IP-scoped counter.

The following calls **bypass** rate limiting entirely:

* The internal `DIDIT_WEBAPP_API_KEY` (used only by the Didit console).
* Endpoints protected by the `IsValidSession` permission (the embedded/SDK session traffic).
* `GET /system/healthcheck` (served by `HealthMiddleware` before this stack).
* Provider webhooks: Stripe, AML screening, face verification callbacks, KYC list mutation.

## Global limits

Every authenticated request is also bucketed by HTTP method into a generic scope, so any new route inherits a sane default:

| Scope           | HTTP method(s)            | Limit     | Window |
| --------------- | ------------------------- | --------- | ------ |
| `generic-get`   | `GET`                     | 600 / min | 60 s   |
| `generic-write` | `POST`, `PATCH`, `DELETE` | 300 / min | 60 s   |

Endpoint-specific limits (next section) apply **in addition** to the global limit. The first scope to exceed its counter is the one that returns `429`.

## Endpoint-specific limits

The middleware defines stricter scopes for the highest-impact routes:

| Scope                  | Endpoint(s)                                                                | Limit     | Source constant                 |
| ---------------------- | -------------------------------------------------------------------------- | --------- | ------------------------------- |
| `session-v2-create`    | `POST /v2/session/`, `POST /v3/session/`                                   | 600 / min | `SESSION_CREATE_RATE_LIMIT`     |
| `session-decision`     | `GET /v1/session/<id>/decision/`, `GET /v2/session/<id>/decision/`         | 100 / min | `SESSION_DECISION_RATE_LIMIT`   |
| `session-generate-pdf` | `GET /v1/session/<id>/generate-pdf/`, `GET /v3/session/<id>/generate-pdf/` | 50 / min  | `SESSION_PDF_RATE_LIMIT`        |
| `session-add-images`   | `POST`/`PATCH /session/<id>/add-images/`                                   | 10 / min  | `SESSION_ADD_IMAGES_RATE_LIMIT` |
| `session-update-kyc`   | `POST`/`PATCH /session/<id>/update-data/`                                  | 10 / min  | `SESSION_UPDATE_KYC_RATE_LIMIT` |
| `session-update-poa`   | `POST`/`PATCH /session/<id>/update-poa-data/`                              | 10 / min  | `SESSION_UPDATE_POA_RATE_LIMIT` |

<Note>
  `GET /v3/session/<id>/decision/` is served by `SessionV3RetrieveView` and is **not** in the `session-decision` scope. It is governed only by the `generic-get` 600/min ceiling. The 100/min decision throttle applies to the v1 and v2 decision paths.
</Note>

<Warning>
  The codebase also defines `FREE_SESSION_RATE_LIMIT = 10` and `PAID_SESSION_RATE_LIMIT = 600`. These constants are **not currently applied** to `POST /v3/session/` — that endpoint uses the single `session-v2-create` limit of 600/min for every application. Do not plan capacity around a per-workflow free-tier throttle until it is documented as live.
</Warning>

## 429 response shape

When you exceed any scope you get an HTTP `429` with this body and headers:

```http theme={null}
HTTP/1.1 429 Too Many Requests
Content-Type: application/json
X-RateLimit-Limit: 600
X-RateLimit-Remaining: 0
X-RateLimit-Reset: 1762534870
Retry-After: 37

{
  "detail": "Session creation rate limit exceeded. You can make up to 600 requests per minute."
}
```

| Header                  | Meaning                                                                                             |
| ----------------------- | --------------------------------------------------------------------------------------------------- |
| `X-RateLimit-Limit`     | Max requests permitted in the current window for the scope that tripped.                            |
| `X-RateLimit-Remaining` | Remaining requests before the window resets. Clamped to `0` once you cross the limit.               |
| `X-RateLimit-Reset`     | Unix epoch seconds when the counter resets to zero.                                                 |
| `Retry-After`           | Seconds to wait before the next attempt. Present **only on `429` responses**, not on every request. |

`X-RateLimit-*` headers are only emitted on the `429` response — successful responses do not include them today. Use the `Retry-After` value (or `X-RateLimit-Reset - now`) as your delay before the next attempt.

## Client guidance

* **Respect `Retry-After`** as the floor for your backoff. On top of it, layer exponential backoff with jitter (`5s → 10s → 20s → 40s ± random`) so two clients that hit `429` at the same time do not synchronise.
* **Stop retrying** after a small ceiling (e.g. 5 attempts). Surface the error to your caller and alert your team — sustained 429s usually mean a runaway loop, not a transient spike.
* **Use one identifier per workload.** Sharing an `x-api-key` across many backends collapses them into the same counter, which can cause one noisy neighbour to starve the rest. Issue a separate application (and therefore a separate `api_key`) per environment, brand, or customer — see [Programmatic registration](/integration/programmatic-registration#managing-applications).
* **Cache decision reads.** The `/decision/` endpoints are not designed for tight polling loops; if you need real-time updates, use [Webhooks](/integration/webhooks) and only call `GET /v3/session/<id>/decision/` for back-fill or audit.
* **Generate PDFs offline.** PDF rendering is CPU-bound (50/min cap). Trigger it from a queue after the session reaches a terminal status, not on every page view.

## Sample 429-aware client

```javascript theme={null}
async function postSession(body) {
  for (let attempt = 0; attempt < 5; attempt++) {
    const res = await fetch("https://verification.didit.me/v3/session/", {
      method: "POST",
      headers: {
        "x-api-key": process.env.DIDIT_API_KEY,
        "Content-Type": "application/json",
      },
      body: JSON.stringify(body),
    });

    if (res.status !== 429) return res;

    const retryAfter = Number(res.headers.get("Retry-After") ?? "1");
    const jitter = Math.random() * 1000;
    await new Promise((r) => setTimeout(r, retryAfter * 1000 + jitter));
  }
  throw new Error("Didit: too many 429s, giving up");
}
```

```python theme={null}
import os
import random
import time

import httpx

def post_session(body: dict) -> httpx.Response:
    with httpx.Client(timeout=15) as client:
        for _ in range(5):
            resp = client.post(
                "https://verification.didit.me/v3/session/",
                headers={
                    "x-api-key": os.environ["DIDIT_API_KEY"],
                    "Content-Type": "application/json",
                },
                json=body,
            )
            if resp.status_code != 429:
                return resp
            wait_s = float(resp.headers.get("Retry-After", "1")) + random.random()
            time.sleep(wait_s)
    raise RuntimeError("Didit: too many 429s, giving up")
```

## Need more headroom?

If 600 sessions per minute is not enough — for example, a marketing launch or a backfill — email [support@didit.me](mailto:support@didit.me) with your `application` UUID and the expected sustained and burst rates. Overrides are configured per application.


# Sandbox & Test Data
Source: https://docs.didit.me/integration/sandbox-testing

Didit sandbox reference: lookup, wallet, review, and KYB scenarios, magic values, the arm endpoint, sample documents, OTP codes and email opt-in. Drive deterministic verification outcomes with no real providers, PII, or billing.

Didit's **sandbox** is the equivalent of Stripe's test cards or Sumsub's document templates: it lets you reproduce any verification outcome deterministically, without touching real providers, real PII, or your balance.

<Note>
  The source of truth for this data is `serialize_catalog()` in the verification service, served live at `GET /v1/sandbox/scenarios/`. A drift-tested copy is generated into `docs/sandbox/SANDBOX_REFERENCE.md` in the `service-didit-verification` repo via `pipenv run python scripts/generate_sandbox_reference.py`. This page mirrors that reference — always trust the live catalog endpoint if anything here looks stale. The catalog endpoint is authenticated: send your API key (`x-api-key`) the same way you would on any other call, or a session token if you are reading it from inside a running session.
</Note>

## Environment model

Sandbox is a **per-application mode** (`ApplicationDetail.mode == SANDBOX`), the same idea as Stripe test mode. While a session runs under a sandbox application:

* Every external provider (OCR, AML, face match, liveness, NFC, phone, email, IP, POA, database validation, document AI) is **mocked** — no third party is ever called.
* Sessions are **never billed** and the balance check is bypassed.
* A per-application quota of **500 session creates / 24h** is enforced.
* Webhooks carry `"environment": "sandbox"` (live sessions carry `"environment": "live"`).
* The hosted flow exposes the session environment so the UI can warn users not to upload real PII.
* **Outcomes never depend on the pixels**: extracted data and statuses come from the scenario / magic value. The captured media itself (documents, selfie, video, POA files) is stored for real, exactly like a live session.

## Transaction Monitoring in sandbox

Sandbox is **session-shaped**: it mocks the providers a verification session would
call. Transaction Monitoring has no provider to mock, so a sandbox application takes
the other route: the transaction is stored, but **nothing that decides, screens,
notifies or charges ever runs over it**.

A transaction created on a sandbox application is persisted and returned as usual,
and none of the following happens to it:

* **No rule evaluation.** `rule_runs` is empty and `rules_matched_count` is `0`, whatever mode your rules are in. An `ACTIVE` rule on a sandbox application never fires, so the transaction stays `APPROVED` with score `0` and no alert or case is opened.
* **No AML / wallet screening.** `provider_results` is empty even for crypto transactions on an application with monitoring enabled.
* **No webhooks.** Neither `transaction.created` nor `transaction.status.updated` is delivered for a sandbox transaction.
* **No billing.** A usage event is recorded at price `0.0000` and your balance is untouched.

Every transaction response carries an `environment` field (`"live"` or `"sandbox"`)
so an empty `rule_runs` is never ambiguous: `"sandbox"` means the rules were not
evaluated, not that none of them matched. The Business Console says the same thing
in the transaction's *Risk & decision* card instead of a bare "No rules
evaluated".

<Note>
  **Travel Rule is the one exception to "nothing runs".** On an application with
  Travel Rule enabled, a sandbox `travelRule` transaction still runs the exchange
  engine: the transfer record is created and moves through its statuses. What sandbox
  never does is talk to anyone - no compliance message reaches a counterparty VASP
  over any rail (platform network memberships, BYOK, email, or `INTERNAL`),
  counterparty VASP attribution screening is skipped, cancellations are a no-op, and
  `travel_rule.status.updated` webhooks are not delivered. The two directions then
  behave differently, because only one of them dispatches:

  **Outbound** - a `travelRule` transaction you submit. The `threshold_amount` and
  self-hosted-wallet checks apply as normal, then dispatch is **simulated**: no rail
  is selected, so the transfer parks at `AWAITING_COUNTERPARTY`, exactly like a real
  send whose rail callbacks have not arrived yet. Nothing advances it from there, so
  a full two-sided rail loop can only be exercised between live applications.

  **Inbound** - `POST /v3/travel-rule/inbound/`. Registration never dispatches over a
  rail, so nothing about it is simulated: sandbox resolves the deposit against your
  wallet address book and settles synchronously, exactly as live does. It resolves to
  a real outcome rather than `AWAITING_COUNTERPARTY` - `ON_HOLD` (no address
  book match), `UNCONFIRMED_OWNERSHIP` (matched entry is not ownership-verified),
  `COUNTERPARTY_MISMATCHED_DATA` (beneficiary name does not match the wallet holder),
  or `COMPLETED` then `FINISHED` (matched a verified entry). This makes inbound
  registration the one Travel Rule flow you can exercise end to end in sandbox.
</Note>

<Note>
  **How to exercise a rule before it goes live.** Use
  [Backtest](/transaction-monitoring/rules-api#create-backtest-activate): it replays
  the rule against your real transaction history and reports `evaluated` /
  `matched` / `affected_entities` without touching any transaction's status. Pair it
  with `TEST` mode on the live application - a `TEST` rule evaluates on every new
  live transaction and records what it would have matched, without changing the
  score or status - and switch to `ACTIVE` once the selectivity looks right.
</Note>

## How to switch between live and sandbox

Live and sandbox are **separate applications**, so test traffic and production data never mix. Each application has a `mode` of `live` or `sandbox`:

* Use a **sandbox-mode** application's API key to get mocked, unbilled, simulatable sessions.
* Use a **live-mode** application's API key for real verifications.

The `sandbox_scenario` field (on session create and on the standalone AML API) and the simulate endpoints are only accepted on sandbox applications; they are rejected on live applications.

## Sandbox in the hosted verification flow

Sessions created under a sandbox application render extra UI in the hosted verification flow (the `url` returned by `POST /v3/session/`):

* **In-card sandbox banner.** Every screen shows a banner inside the card - "Test data only - no real calls" - so it is always obvious the session never calls real providers and never touches your balance. Captured media is stored like any session, so use the sample documents and test data rather than real identity documents or personal information.
* **Pre-flow scenario picker.** Before capture starts, an in-card picker walks the user through choosing a test result: pick an outcome, then a trigger for that outcome. Confirming calls `POST /v3/session/{session_id}/sandbox/arm/` (see [Arm (or re-arm) the session before the flow starts](#3-arm-or-re-arm-the-session-before-the-flow-starts) below), then continues into the flow with that scenario's magic values already applied.
* **Sample documents strip.** A single row of sandbox sample documents (up to 3) sits directly below the document upload/capture component. Tap one to use it instead of a real upload.

Sandbox sessions store the **real** captured media - documents, selfie, liveness video, and proof-of-address files are uploaded and retained exactly as they would be for a live session. The *extracted* data (ID verification fields, face match scores, liveness results, and similar) and the session outcome itself (Approved / In Review / Declined) are simulated by the scenario or magic value - never derived from the captured media. The Business Console marks the extracted-data sections of a sandbox session with a **Simulated data** chip, so reviewers can tell at a glance which parts of the session are the real capture and which are scenario-driven.

## Scenarios

Each scenario is a named bundle of magic values. Pass its slug as `sandbox_scenario` on session create (or to the simulate endpoint) to reproduce the outcome.

| Slug                                   | Title                                              | Default status | Description                                                                                                                                                                                                                                                                                                                                                                             |
| -------------------------------------- | -------------------------------------------------- | -------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `approve`                              | Happy path — all features approve                  | Approved       | Default sandbox behaviour: every mocked feature returns its clean APPROVED outcome. Session status ends as APPROVED.                                                                                                                                                                                                                                                                    |
| `decline_aml_hit`                      | AML — politically exposed person                   | Declined       | AML mock returns one hit and the session declines on the AML feature. The hit uses the same [Hit schema](/core-technology/aml-screening/report-aml-screening#per-hit-fields) as live AML providers — `url`, `match_score`, `risk_score`, `review_status`, `properties`, `pep_matches[]`, and `score_breakdown` are all populated — and a POSSIBLE\_MATCH\_FOUND warning Log is written. |
| `decline_document_expired`             | ID Verification — document expired                 | Declined       | The ID verification mock returns a passport whose expiry date is in the past. The session declines on ID verification with a DOCUMENT\_EXPIRED warning Log.                                                                                                                                                                                                                             |
| `decline_minimum_age`                  | ID Verification — under the minimum age policy     | Declined       | The ID verification mock returns a DOB making the user roughly 10 years old. Production age check emits MINIMUM\_AGE\_NOT\_MET and the workflow declines.                                                                                                                                                                                                                               |
| `decline_mrz_validation`               | ID Verification — MRZ checksum failure             | Declined       | The ID verification mock returns a passport with a corrupted MRZ checksum. Production MRZ validator emits MRZ\_VALIDATION\_FAILED and the session declines.                                                                                                                                                                                                                             |
| `decline_could_not_recognize_document` | ID Verification — unreadable document              | Declined       | The ID verification mock returns an empty response. Production raises COULD\_NOT\_RECOGNIZE\_DOCUMENT and surfaces it to the SDK.                                                                                                                                                                                                                                                       |
| `decline_face_match_low_similarity`    | Face match — similarity below decline threshold    | Declined       | Face match mock returns a low score. Production emits LOW\_FACE\_MATCH\_SIMILARITY and the workflow node action mapping declines.                                                                                                                                                                                                                                                       |
| `decline_database_no_match`            | Database validation — no match across all services | Declined       | Every selected database service returns NO\_MATCH. Production emits DATABASE\_VALIDATION\_NO\_MATCH and the workflow declines.                                                                                                                                                                                                                                                          |
| `decline_phone_high_risk`              | Phone — reserved high-risk test number             | Declined       | The phone verification mock blocks the verification (reserved test range). Phone verification ends as BLOCKED and emits HIGH\_RISK\_PHONE\_NUMBER.                                                                                                                                                                                                                                      |
| `decline_email_breach`                 | Email — breach-database hit                        | Declined       | The email breach mock returns one breach hit on the address. Email verification emits BREACHED\_EMAIL\_DETECTED.                                                                                                                                                                                                                                                                        |
| `decline_ip_blocklist`                 | IP analysis — IP address in blocklist              | Declined       | IP analysis mock declines the location with IP\_ADDRESS\_IN\_BLOCKLIST. Session declines on IP analysis.                                                                                                                                                                                                                                                                                |
| `decline_poa_address_mismatch`         | POA — address mismatch with provided               | Declined       | POA mock declines the proof-of-address with ADDRESS\_MISMATCH\_WITH\_PROVIDED. Session declines on POA.                                                                                                                                                                                                                                                                                 |
| `decline_liveness_attack`              | Liveness — face attack detected                    | Declined       | Passive liveness mock detects a face-attack signal and emits LIVENESS\_FACE\_ATTACK. Session declines on liveness.                                                                                                                                                                                                                                                                      |
| `decline_nfc_chip_not_verified`        | NFC — ePassport chip not verified                  | Declined       | ePassport mock returns a chip whose SOD/DG signature fails integrity. Production emits NFC\_CHIP\_NOT\_VERIFIED and the session declines on NFC when the workflow declines on unverified chips.                                                                                                                                                                                         |
| `decline_nfc_trust_anchor_missing`     | NFC — issuing trust anchor unavailable             | Declined       | ePassport mock returns a chip signed by a DSC whose issuing CSCA is absent from the trust store. Production emits NFC\_TRUST\_ANCHOR\_MISSING and the session declines when the workflow declines on unverified chips.                                                                                                                                                                  |
| `decline_document_ai_unreadable`       | Document AI — unreadable document                  | Declined       | Document AI mock returns no readable fields. Production emits DOCUMENT\_AI\_UNREADABLE\_DOCUMENT and the document settles as declined once the retry budget is exhausted.                                                                                                                                                                                                               |
| `review_aml_possible_match`            | AML — possible match needs review                  | In Review      | AML mock returns a lower-confidence hit. The session lands In Review with a warning-level POSSIBLE\_MATCH\_FOUND Log for an analyst to resolve.                                                                                                                                                                                                                                         |
| `review_face_match_borderline`         | Face match — borderline similarity                 | In Review      | Face match mock returns a score between the review and decline thresholds. The session lands In Review on face match.                                                                                                                                                                                                                                                                   |
| `review_document_borderline_age`       | ID Verification - underage sent to review          | In Review      | The ID verification mock returns a DOB under the workflow's configured minimum age. The workflow's minimum\_age\_action is set to REVIEW rather than DECLINE, so the session lands In Review on ID verification instead of declining.                                                                                                                                                   |
| `review_poa_partial_match`             | POA — partial address match                        | In Review      | POA mock returns an address that only partially matches the provided one. The session lands In Review on proof of address.                                                                                                                                                                                                                                                              |
| `review_database_partial_match`        | Database validation — partial match                | In Review      | Database services return partial matches on name and date of birth. The session lands In Review on database validation.                                                                                                                                                                                                                                                                 |
| `decline_kyb_registry_mismatch`        | KYB - registry data mismatch                       | Declined       | Registry mock returns a company whose registration data mismatches the expected details. The business session declines on the registry check.                                                                                                                                                                                                                                           |
| `review_kyb_registry_partial`          | KYB - registry data partially matches              | In Review      | Registry mock returns a company whose name only partially matches. The business session lands In Review on the registry check.                                                                                                                                                                                                                                                          |

`review_*` scenarios exist so you can test manual-review UX (the console review queue, `In Review` webhooks, reviewer approve/decline actions) without needing a decline-grade input. The two `kyb_*` scenarios above set `expected_details.registration_number` instead of `expected_details.first_name`: they only apply to Business Verification (KYB) sessions.

## Magic values

A magic value is a specific input that makes one mocked feature emit a specific risk. Set the input field to the magic value (directly, or via a scenario) to trigger it.

| Feature              | Input field                            | Magic value                                                | Risk                                            | Description                                                                                                                                                                        |
| -------------------- | -------------------------------------- | ---------------------------------------------------------- | ----------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| AML                  | `user_email`                           | `sandbox+aml_hit@didit.test`                               | `POSSIBLE_MATCH_FOUND`                          | AML — politically exposed person; AML mock returns one hit, session declines on AML.                                                                                               |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_DOCUMENT_EXPIRED`                             | `DOCUMENT_EXPIRED`                              | OCR — document expired; session declines on ID verification.                                                                                                                       |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_MINIMUM_AGE_NOT_MET`                          | `MINIMUM_AGE_NOT_MET`                           | OCR — date of birth makes the user below the configured minimum age; session declines.                                                                                             |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_MAXIMUM_AGE_EXCEEDED`                         | `MAXIMUM_AGE_EXCEEDED`                          | OCR — extracted DOB exceeds the configured maximum age policy.                                                                                                                     |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_DOCUMENT_NUMBER_FORMAT_MISMATCH`              | `DOCUMENT_NUMBER_FORMAT_MISMATCH`               | OCR — extracted document number does not match the document's expected format regex from the document registry.                                                                    |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_PERSONAL_NUMBER_FORMAT_MISMATCH`              | `PERSONAL_NUMBER_FORMAT_MISMATCH`               | OCR — extracted personal number fails the document registry's format check.                                                                                                        |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`       | `DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION`        | OCR — extracted document type is outside the application's `documents_allowed` policy.                                                                                             |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_FULL_NAME_MISMATCH_WITH_PROVIDED`             | `FULL_NAME_MISMATCH_WITH_PROVIDED`              | OCR — name on the document doesn't match the name the customer prefilled in `expected_details` above the name-match threshold.                                                     |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_GENDER_MISMATCH_WITH_PROVIDED`                | `GENDER_MISMATCH_WITH_PROVIDED`                 | OCR — extracted gender disagrees with `expected_details.gender`.                                                                                                                   |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_DOB_MISMATCH_WITH_PROVIDED`                   | `DOB_MISMATCH_WITH_PROVIDED`                    | OCR — extracted date of birth disagrees with `expected_details.date_of_birth`.                                                                                                     |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_COUNTRY_MISMATCH_WITH_PROVIDED`               | `COUNTRY_MISMATCH_WITH_PROVIDED`                | OCR — issuing state disagrees with `expected_details.country` (or `id_country`).                                                                                                   |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_NATIONALITY_MISMATCH_WITH_PROVIDED`           | `NATIONALITY_MISMATCH_WITH_PROVIDED`            | OCR — extracted nationality disagrees with `expected_details.nationality`.                                                                                                         |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_IDENTIFICATION_NUMBER_MISMATCH_WITH_PROVIDED` | `IDENTIFICATION_NUMBER_MISMATCH_WITH_PROVIDED`  | OCR — extracted document/personal/tax number doesn't match `expected_details.identification_number`.                                                                               |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_COULD_NOT_RECOGNIZE_DOCUMENT`                 | `COULD_NOT_RECOGNIZE_DOCUMENT`                  | OCR pipeline returns empty / unrecognizable; production raises COULD\_NOT\_RECOGNIZE\_DOCUMENT.                                                                                    |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_MRZ_NOT_DETECTED`                             | `MRZ_NOT_DETECTED`                              | OCR — document expects an MRZ but the pipeline could not locate one.                                                                                                               |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_MRZ_VALIDATION_FAILED`                        | `MRZ_VALIDATION_FAILED`                         | OCR — MRZ was found but failed checksum / format validation.                                                                                                                       |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME`     | `MRZ_AND_DATA_EXTRACTED_FROM_OCR_NOT_SAME`      | OCR — MRZ identity fields disagree with VIZ-extracted fields.                                                                                                                      |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_BARCODE_NOT_DETECTED`                         | `BARCODE_NOT_DETECTED`                          | OCR — document expects a barcode but none was found.                                                                                                                               |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_BARCODE_VALIDATION_FAILED`                    | `BARCODE_VALIDATION_FAILED`                     | OCR — barcode was decoded but failed cross-field validation.                                                                                                                       |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_QR_NOT_DETECTED`                              | `QR_NOT_DETECTED`                               | OCR — document expects a QR code but none was found.                                                                                                                               |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_QR_VALIDATION_FAILED`                         | `QR_VALIDATION_FAILED`                          | OCR — QR code was decoded but failed cross-field validation.                                                                                                                       |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_DATA_INCONSISTENT`                            | `DATA_INCONSISTENT`                             | OCR — internal consistency checks on VIZ fields disagree.                                                                                                                          |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_DOCUMENT_SIDES_MISMATCH`                      | `DOCUMENT_SIDES_MISMATCH`                       | OCR — front and back document\_name do not pair as the same document.                                                                                                              |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_NAME_NOT_DETECTED`                            | `NAME_NOT_DETECTED`                             | OCR — neither first nor last name could be extracted from the document.                                                                                                            |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_DATE_OF_BIRTH_NOT_DETECTED`                   | `DATE_OF_BIRTH_NOT_DETECTED`                    | OCR — document class expects a DOB but extraction returned none.                                                                                                                   |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_EXPIRATION_DATE_NOT_DETECTED`                 | `EXPIRATION_DATE_NOT_DETECTED`                  | OCR — document class expects an expiry date but extraction returned none.                                                                                                          |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_DOCUMENT_NUMBER_NOT_DETECTED`                 | `DOCUMENT_NUMBER_NOT_DETECTED`                  | OCR — neither document number nor personal number could be extracted.                                                                                                              |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_COULD_NOT_DETECT_DOCUMENT_TYPE`               | `COULD_NOT_DETECT_DOCUMENT_TYPE`                | OCR — classifier could not map the capture to a supported document type.                                                                                                           |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_PORTRAIT_IMAGE_NOT_DETECTED`                  | `PORTRAIT_IMAGE_NOT_DETECTED`                   | OCR — pipeline could not isolate a portrait region on the document.                                                                                                                |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_UNPARSED_ADDRESS`                             | `UNPARSED_ADDRESS`                              | OCR — document has an address field but geocoding / parsing returned nothing usable.                                                                                               |
| DATABASE\_VALIDATION | `expected_details.first_name`          | `SANDBOX_DB_NO_MATCH`                                      | `DATABASE_VALIDATION_NO_MATCH`                  | Database validation — every government/registry service returns NO\_MATCH; session declines on database validation.                                                                |
| FACEMATCH            | `expected_details.first_name`          | `SANDBOX_FACE_LOW_MATCH`                                   | `LOW_FACE_MATCH_SIMILARITY`                     | Face match — similarity score below the decline threshold; session declines on face match.                                                                                         |
| PHONE                | `phone_number`                         | `+15005550009`                                             | `HIGH_RISK_PHONE_NUMBER`                        | Phone — reserved undeliverable / high-risk test number; phone verification mock returns failure.                                                                                   |
| EMAIL                | `user_email`                           | `sandbox+breach@didit.test`                                | `BREACHED_EMAIL_DETECTED`                       | Email — the breach database returns a hit on this address.                                                                                                                         |
| LOCATION             | `expected_details.first_name`          | `SANDBOX_IP_BLOCKLIST`                                     | `IP_ADDRESS_IN_BLOCKLIST`                       | IP analysis — caller IP appears in the application blocklist; session declines on IP analysis.                                                                                     |
| PROOF\_OF\_ADDRESS   | `expected_details.first_name`          | `SANDBOX_POA_ADDRESS_MISMATCH`                             | `ADDRESS_MISMATCH_WITH_PROVIDED`                | POA — address on uploaded document disagrees with the address the customer prefilled in `expected_details`; session declines on POA.                                               |
| LIVENESS             | `expected_details.first_name`          | `SANDBOX_LIVENESS_ATTACK`                                  | `LIVENESS_FACE_ATTACK`                          | Liveness — passive liveness mock detects a face-attack signal; session declines on liveness.                                                                                       |
| NFC                  | `expected_details.first_name`          | `SANDBOX_NFC_CHIP_NOT_VERIFIED`                            | `NFC_CHIP_NOT_VERIFIED`                         | NFC — ePassport mock returns a chip whose SOD/DG signature fails integrity; production emits NFC\_CHIP\_NOT\_VERIFIED and declines when the workflow declines on unverified chips. |
| NFC                  | `expected_details.first_name`          | `SANDBOX_NFC_TRUST_ANCHOR_MISSING`                         | `NFC_TRUST_ANCHOR_MISSING`                      | NFC — the DSC chains to a CSCA absent from the trust store; production emits NFC\_TRUST\_ANCHOR\_MISSING and applies the configured unverified-chip action.                        |
| DOCUMENT\_AI         | `expected_details.first_name`          | `SANDBOX_DOCUMENT_AI_UNREADABLE`                           | `DOCUMENT_AI_UNREADABLE_DOCUMENT`               | Document AI — extraction returns no readable fields; production emits DOCUMENT\_AI\_UNREADABLE\_DOCUMENT and the document settles as declined once the retry budget is exhausted.  |
| AML                  | `user_email`                           | `sandbox+aml_review@didit.test`                            | `POSSIBLE_MATCH_FOUND`                          | AML — possible match that needs manual resolution; session lands In Review.                                                                                                        |
| FACEMATCH            | `expected_details.first_name`          | `SANDBOX_FACE_BORDERLINE_MATCH`                            | `LOW_FACE_MATCH_SIMILARITY`                     | Face match — borderline similarity between review and decline thresholds; session lands In Review.                                                                                 |
| ID\_VERIFICATION     | `expected_details.first_name`          | `SANDBOX_OCR_BORDERLINE_AGE`                               | `MINIMUM_AGE_NOT_MET`                           | OCR — date of birth is below the minimum age but the workflow reviews rather than declines minimum-age failures; session lands In Review.                                          |
| DATABASE\_VALIDATION | `expected_details.first_name`          | `SANDBOX_DB_PARTIAL_MATCH`                                 | `DATABASE_VALIDATION_PARTIAL_MATCH`             | Database validation — identification matches but name/DOB only partially; session lands In Review.                                                                                 |
| PROOF\_OF\_ADDRESS   | `expected_details.first_name`          | `SANDBOX_POA_PARTIAL_MATCH`                                | `ADDRESS_MISMATCH_WITH_PROVIDED`                | POA — address on uploaded document partially matches the provided address; session lands In Review.                                                                                |
| KYB\_REGISTRY        | `expected_details.registration_number` | `SANDBOX-KYB-MISMATCH`                                     | `KYB_REGISTRY_DATA_MISMATCH_WITH_EXPECTED`      | KYB - registry company data mismatches the expected details; session declines.                                                                                                     |
| KYB\_REGISTRY        | `expected_details.registration_number` | `SANDBOX-KYB-REVIEW`                                       | `KYB_REGISTRY_DATA_PARTIAL_MATCH_WITH_EXPECTED` | KYB - registry company data partially matches; session lands In Review.                                                                                                            |

## Non-doc lookup and identity wallets

Sandbox applications can enable every identity wallet in the country catalog, including wallets that are unavailable on live applications.
The default `approve` scenario simulates a verified identity without signing in to an external wallet.
The result is stored in the session and follows the workflow's normal next step.
Sandbox does not validate a real wallet credential or charge for simulated attempts.

Lookup requests still validate the entered fields and use the configured attempt limit, which defaults to one.
Use the following scenarios to exercise retries and fallback rules:

| Scenario                | Simulated result                                                   |
| ----------------------- | ------------------------------------------------------------------ |
| `lookup_partial_match`  | Partial registry match; counts toward the attempt limit.           |
| `lookup_no_match`       | Registry answers without a match; counts toward the attempt limit. |
| `lookup_provider_error` | Registry returns no answer; follows the provider-error fallback.   |
| `wallet_cancelled`      | User cancels wallet sign-in.                                       |
| `wallet_timeout`        | Wallet sign-in expires.                                            |
| `wallet_provider_error` | Wallet cannot complete sign-in.                                    |

Wallet failures follow the country setting to fall back to document capture or decline.
Completed lookup attempts are recorded separately, so two allowed attempts produce two results before fallback.
All sandbox usage remains free.

## The sample documents

<Warning>
  Never upload real identity documents in sandbox. Use the built-in sample documents instead.
</Warning>

The hosted flow offers three sample documents, one per document type:

| Country   | Document type    |
| --------- | ---------------- |
| Spain     | National ID card |
| Argentina | Passport         |
| Poland    | Driver's license |

Tap a sample in the strip to use it instead of a real capture. The extracted data and the session outcome always come from the selected scenario or magic value, so any sample works with any scenario.

## Sample identity: testing `expected_details`

Every sandbox document is fabricated from one **pinned** identity.
The extracted values are the same on every session and are never derived from the current date, so you can prefill `expected_details` with them and check your field-comparison and warning handling end to end.
Pass the values below and the comparison checks pass; pass anything else and the matching `*_MISMATCH_WITH_PROVIDED` warning fires on purpose.

Dates are shared by every sample document:

| Field           | Value        |
| --------------- | ------------ |
| `date_of_birth` | `1990-06-15` |
| Date of issue   | `2025-06-15` |
| Date of expiry  | `2035-06-15` |

The rest of the identity depends on which document you use:

| `sandbox_sample`                | Document                | `first_name`     | `last_name`         | `gender`             | `nationality` | `id_country` | `identification_number` |
| ------------------------------- | ----------------------- | ---------------- | ------------------- | -------------------- | ------------- | ------------ | ----------------------- |
| *(default, no sample selected)* | Brazil ePassport        | `GUSTAVO`        | `MATSUMOTO`         | `M`                  | `BRA`         | `BRA`        | `YC531181`              |
| `spain-id-card-2021`            | Spain national ID card  | `CARMEN`         | `ESPAÑOLA ESPAÑOLA` | `F`                  | `ESP`         | `ESP`        | `CAA000000`             |
| `argentina-passport-2009`       | Argentina passport      | `MARIA VICTORIA` | `VILLAREAL`         | `F`                  | `ARG`         | `ARG`        | `AAF794880`             |
| `poland-driving-license-2019`   | Poland driver's license | `JAN`            | `KOWALSKI`          | not on this document | `POL`         | `POL`        | `SP005/89/5`            |

```json theme={null}
{
  "workflow_id": "<your-workflow-uuid>",
  "expected_details": {
    "date_of_birth": "1990-06-15",
    "gender": "M",
    "nationality": "BRA",
    "identification_number": "YC531181"
  }
}
```

`first_name` and `last_name` are the exception: the sandbox echoes the names you send in `expected_details` onto the fabricated document, so name matching passes with any name.
Use the `SANDBOX_OCR_FULL_NAME_MISMATCH_WITH_PROVIDED` magic value to exercise a name mismatch, and `SANDBOX_OCR_DOB_MISMATCH_WITH_PROVIDED` for a date-of-birth mismatch.

<Note>
  If your workflow restricts `documents_allowed` to a country or document type that excludes the Brazil ePassport, the sandbox fabricates a document from the first allowed country instead, so `nationality`, `id_country`, and the document name follow that country. The dates above stay the same.
</Note>

## OTP codes and email opt-in

* **Phone OTP:** the sandbox phone check accepts any well-formed code (4-8 digits; `123456` included). Malformed input still returns `400`.
* **Email OTP:** the sandbox email check accepts any well-formed code (`123456` included). Malformed input still returns `400`.

By default sandbox sessions do **not** send emails (review alerts, status change, OTP, resubmit, new-session-link, etc.). To deliver an email anyway, use one of these opt-in patterns on the recipient address:

| Opt-in pattern             | Example                     |
| -------------------------- | --------------------------- |
| `<local>+sandbox@<domain>` | `alice+sandbox@example.com` |
| `*@didit.test`             | `alice@didit.test`          |

## Driving outcomes: scenarios, magic values, arming, and the simulate endpoint

There are five ways to control a sandbox outcome.

### 1. `sandbox_scenario` at session create

Set the scenario slug when creating the session (`POST /v3/session/`). The create flow expands the scenario's bundled magic values into the session's input fields, so the mocked providers emit the intended outcome through the real workflow pipeline.

```json theme={null}
{
  "workflow_id": "<your-workflow-uuid>",
  "sandbox_scenario": "decline_document_expired"
}
```

### 2. Magic values typed by hand

Set the individual input fields yourself (for example `expected_details.first_name = "SANDBOX_OCR_DOCUMENT_EXPIRED"`, or `user_email = "sandbox+aml_hit@didit.test"`). See the magic values table above for the full registry.

### 3. Arm (or re-arm) the session before the flow starts

Set or replace the armed scenario on a session that already exists, as long as it hasn't progressed past `Not Started`. This is the endpoint the [pre-flow scenario picker](#sandbox-in-the-hosted-verification-flow) calls, and you can call it yourself to build a custom picker or test harness:

```
POST /v3/session/{session_id}/sandbox/arm/
Session-Token: <session_token>
```

```json theme={null}
{
  "scenario": "decline_document_expired"
}
```

200 response:

```json theme={null}
{
  "session_id": "<session_id>",
  "scenario": "decline_document_expired",
  "status": "Not Started"
}
```

* Authenticate with the session's own `Session-Token` (returned as `session_token` from session create), not your application API key: this is a client-facing endpoint.
* Returns `400` for an unknown scenario slug, and `400` once the session has moved past `Not Started` (`"Scenario can only be armed before the verification starts."`).
* Returns `404` when the `Session-Token` belongs to a live (non-sandbox) application, or doesn't match the `session_id` in the path.
* **Re-arming replaces the previous scenario.** It clears only the magic values the previous scenario wrote, and leaves anything the user already typed by hand (email, first name, etc.) untouched. For example: arm `decline_phone_high_risk`, then arm `approve` - the phone number reverts to unset, but a customer-entered email survives both calls.

### 4. The simulate endpoint

Force a terminal status after the fact:

* Console / API key (requires the `write:sessions` privilege): `POST /v3/session/{session_id}/simulate/`
* Hosted flow (`Session-Token` header): `POST /v3/session/{session_id}/sandbox/simulate/`

Body fields: `new_status`, `scenario`, `risk`, `comment`, `node_id` — all optional, but at least one of `new_status`, `scenario`, or `risk` is required. When only `scenario` or `risk` is given, `new_status` defaults to that scenario's / risk's default status, and the matching warning Log is written.

```json theme={null}
{
  "scenario": "decline_aml_hit"
}
```

### 5. `sandbox_scenario` on the standalone AML API

Back-end AML screening has no end user and no session to arm, so the slug goes on the screening request itself (`POST /v3/aml/`):

```json theme={null}
{
  "full_name": "Ada Lovelace",
  "save_api_request": true,
  "sandbox_scenario": "decline_aml_hit"
}
```

* `decline_aml_hit` returns one production-shaped hit and settles the screening as `Declined`; `review_aml_possible_match` settles it `In Review`. A scenario that arms no AML outcome leaves the screening clean.
* With `save_api_request: true` (the default) the screening is persisted exactly as it is on a live key, so the returned `request_id` resolves through `GET /v3/session/{request_id}/decision/` and `GET /v3/session/{request_id}/generate-pdf/`.
* Returns `400` for an unknown scenario slug, and `400` when the API key belongs to a live application.

## Where `sandbox_scenario` appears

The armed scenario slug (`null` if none is armed) is echoed back on some surfaces and intentionally left off others:

| Surface                                                                                   | Exposed?                                                                        |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------- |
| Current step payload (KYC and KYB)                                                        | Yes, as `sandbox_scenario`                                                      |
| `GET /v1/session/{id}/decision/`                                                          | Yes, as `sandbox_scenario`                                                      |
| `GET /v3/session/{id}/decision/` (see [Retrieve Session](/sessions-api/retrieve-session)) | Yes, top-level `sandbox_scenario` (null when unarmed)                           |
| Session webhooks (`status.updated`, `data.updated`)                                       | Yes, as `sandbox_scenario`, `null` on live sessions or unarmed sandbox sessions |

If your integration needs to branch on the armed scenario server-side, read it from the webhook envelope or either decision endpoint (`v1` or `v3`).

## Usage and billing

Sandbox usage is tracked, never charged:

* Every mocked call still records a usage event (`is_sandbox: true`, priced at `0.0000`) so sandbox volume is visible for debugging, but it is never added to your usage totals, never decremented from balance, and never appears on an invoice.
* The Business Console's balance, top-up, and live-usage surfaces filter sandbox usage out by default. The top-up usage endpoints accept an `environment` parameter (`live`, the default, or `sandbox`) so sandbox volume can be inspected separately - always at zero cost and with no free-tier consumption.
* Email and phone verification bill per request rather than per session outcome, and sandbox has no way to fully mirror that at the webhook layer. Sandbox email/phone checks still record a usage event per request at price `0.0000`, same as every other mocked feature: this is an accepted, known divergence from live billing behavior, not a bug.
* Database validation's response shape in sandbox intentionally diverges from the live per-provider shape, since there is no real provider to mirror. Treat sandbox database-validation payloads as a stand-in for the outcome (status and warning code), not a byte-for-byte preview of a live provider response.


# SDKs & Integrations
Source: https://docs.didit.me/integration/sdks

Integrate Didit KYC into web, mobile, and backend with SDKs for React, Vue, iOS, Android, Flutter, React Native, plus Zapier and WordPress plugins.

<AgentPromptAccordion />

Choose how you want to integrate Didit based on your platform and use case.

<Note>
  ### Recommended: SDK integration via sessions

  For user-facing verification (KYC onboarding, age verification, identity checks), we recommend **SDK integration through hosted sessions**. The verification flows are A/B tested and optimized for the highest completion rates, fastest speed, and best security. All SDKs — web, iOS, Android, React Native, and Flutter — are **available now**.

  For server-to-server operations (batch processing, custom pipelines), use the **standalone APIs** directly. See the [standalone API documentation](/standalone-apis/id-verification) for individual verification endpoints.
</Note>

<Warning>
  If you launch a Didit session from your own product, you are still responsible for the controller-side notice and consent layer. Before the user starts verification, disclose that Didit powers the workflow, link your own privacy notice, and collect explicit consent where required for document, selfie, liveness, or biometric capture. See [Security & compliance](/getting-started/security-compliance), [White Label](/console/white-label), and [Create Session](/sessions-api/create-session).
</Warning>

This Didit Academy lesson wires up a complete integration in one sitting: the SDK, API keys per environment, the create-session call, and a webhook handler that verifies the signing secret.

<VideoEmbed title="The complete integration guide — Didit Academy" />

***

## Web

Integrate verification into your web app with JavaScript, iframe, or redirect.

<CardGroup>
  <Card title="Web SDKs" icon="globe" href="/integration/web-sdks/overview">
    JavaScript SDK, iframe embed, or redirect. React, Vue, Angular, vanilla JS.
  </Card>

  <Card title="JavaScript SDK" icon="code" href="/integration/web-sdks/javascript-sdk">
    Full programmatic control with event callbacks and TypeScript.
  </Card>

  <Card title="InContext Iframe" icon="square" href="/integration/web-sdks/incontext-iframe">
    Embed verification in your page. No backend required with UniLink.
  </Card>

  <Card title="Redirect" icon="arrow-right" href="/integration/web-sdks/web-redirect">
    Redirect to Didit-hosted flow. Cross-device support.
  </Card>
</CardGroup>

***

## Mobile

Native SDKs for the best camera, NFC, and liveness experience on device.

<CardGroup>
  <Card title="Native SDKs" icon="mobile" href="/integration/native-sdks/overview">
    iOS, Android, React Native, Flutter. Full NFC and biometric support.
  </Card>

  <Card title="iOS SDK" icon="apple" href="/integration/native-sdks/ios-sdk">
    SwiftUI and UIKit. NFC passport reading. Available now.
  </Card>

  <Card title="Android SDK" icon="android" href="/integration/native-sdks/android-sdk">
    Kotlin and Jetpack Compose. NFC support. Available now.
  </Card>

  <Card title="React Native" icon="react" href="/integration/native-sdks/react-native-sdk">
    Cross-platform TypeScript API wrapping native iOS and Android SDKs. NFC support. Available now.
  </Card>

  <Card title="Flutter" icon="feather" href="/integration/native-sdks/flutter-sdk">
    Cross-platform Dart API wrapping native iOS and Android SDKs. NFC support. Available now.
  </Card>

  <Card title="WebView Fallback" icon="tablet" href="/integration/web-sdks/webview-in-ios-android">
    Fallback for platforms without a native SDK. Prefer native SDKs when available.
  </Card>
</CardGroup>

***

## Integrations

Plugins and no-code tools for popular platforms.

<CardGroup>
  <Card title="Zapier" icon="bolt" href="/integration/engines/zapier">
    Automate verification with no-code triggers and actions.
  </Card>

  <Card title="WordPress & WooCommerce" icon="plug" href="/integration/web-sdks/wordpress-woocommerce">
    Plugin for WordPress and WooCommerce sites.
  </Card>

  <Card title="Shopify" icon="bag-shopping" href="/integration/web-sdks/shopify">
    Verify shoppers and gate age-restricted products on Shopify.
  </Card>

  <Card title="Salesforce" icon="cloud" href="/integration/web-sdks/salesforce">
    Trigger Didit verifications from Salesforce flows and records.
  </Card>
</CardGroup>

***

## Quick Comparison

| Platform     | Method           | Status      | NFC | Camera    | Best For                            |
| ------------ | ---------------- | ----------- | :-: | --------- | ----------------------------------- |
| Web          | JavaScript SDK   | ✅ Available |  —  | Browser   | Full control, React / Vue / Angular |
| Web          | InContext Iframe | ✅ Available |  —  | Browser   | Quick embed, no backend needed      |
| Web          | Redirect         | ✅ Available |  —  | Browser   | Cross-device, simple setup          |
| iOS          | Native SDK       | ✅ Available |  ✅  | Optimized | Best UX, NFC chip reading           |
| Android      | Native SDK       | ✅ Available |  ✅  | Optimized | Best UX, NFC chip reading           |
| React Native | Native SDK       | ✅ Available |  ✅  | Optimized | Best UX, NFC chip reading           |
| Flutter      | Native SDK       | ✅ Available |  ✅  | Optimized | Best UX, NFC chip reading           |
| No-Code      | Zapier           | ✅ Available |  —  | —         | Automated workflows                 |
| CMS          | WordPress        | ✅ Available |  —  | —         | WP / WooCommerce sites              |
| Commerce     | Shopify          | ✅ Available |  —  | —         | Shopify stores                      |
| CRM          | Salesforce       | ✅ Available |  —  | —         | Salesforce flows and records        |

## Next Steps

<CardGroup>
  <Card title="API Full Flow" icon="diagram-project" href="/integration/api-full-flow">
    End-to-end session integration: create sessions, webhooks, results.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/integration/webhooks">
    Receive real-time verification status updates.
  </Card>
</CardGroup>

***


# Supported Languages
Source: https://docs.didit.me/integration/supported-languages

Didit supports 54 languages for the verification UI and email notifications, with browser auto-detection and a single source of truth for accepted codes.

This page is the **live source of truth** for the language codes accepted by the Didit API. It is referenced from the OpenAPI specs for both the session-level `language` field and the `contact_details.email_lang` field on [Create Session](/sessions-api/create-session).

## Where these codes apply

The same set of codes is accepted everywhere a language is configurable:

| Field                        | Where                                        | What it controls                                                             |
| ---------------------------- | -------------------------------------------- | ---------------------------------------------------------------------------- |
| `language`                   | `POST /v3/session/` body                     | Language of the **verification UI** shown to the end user.                   |
| `contact_details.email_lang` | `POST /v3/session/` body                     | Language of **email notifications** (invitation, reminders, status updates). |
| `email_language`             | `PATCH /v3/session/{id}/update-status/` body | Language of the status-change email when `send_email=true`.                  |

If the user's browser locale is supported, the verification UI auto-detects it; otherwise it falls back to **English** (`en`). If you do not pass `email_lang`, emails fall back to `en`. All values are case-sensitive — use the exact codes from the table below.

## All supported languages

The set below mirrors the keys of `EMAIL_TRANSLATIONS` in the service — both the verification UI and email-localization layers read from the same dictionary, so any code in this table works for both `language` and `email_lang`.

| #  | Language              | Native name        | Code    | Direction |
| -- | --------------------- | ------------------ | ------- | --------- |
| 1  | Albanian              | Shqip              | `sq`    | LTR       |
| 2  | Arabic                | العربية            | `ar`    | **RTL**   |
| 3  | Armenian              | Հայերեն            | `hy`    | LTR       |
| 4  | Bengali               | বাংলা              | `bn`    | LTR       |
| 5  | Bosnian               | Bosanski           | `bs`    | LTR       |
| 6  | Bulgarian             | Български          | `bg`    | LTR       |
| 7  | Catalan               | Català             | `ca`    | LTR       |
| 8  | Chinese (generic)     | 中文                 | `zh`    | LTR       |
| 9  | Chinese (Simplified)  | 简体中文               | `zh-CN` | LTR       |
| 10 | Chinese (Traditional) | 繁體中文               | `zh-TW` | LTR       |
| 11 | Croatian              | Hrvatski           | `hr`    | LTR       |
| 12 | Czech                 | Čeština            | `cs`    | LTR       |
| 13 | Danish                | Dansk              | `da`    | LTR       |
| 14 | Dutch                 | Nederlands         | `nl`    | LTR       |
| 15 | English               | English            | `en`    | LTR       |
| 16 | Estonian              | Eesti              | `et`    | LTR       |
| 17 | Finnish               | Suomi              | `fi`    | LTR       |
| 18 | French                | Français           | `fr`    | LTR       |
| 19 | Georgian              | ქართული            | `ka`    | LTR       |
| 20 | German                | Deutsch            | `de`    | LTR       |
| 21 | Greek                 | Ελληνικά           | `el`    | LTR       |
| 22 | Hebrew                | עברית              | `he`    | **RTL**   |
| 23 | Hindi                 | हिन्दी             | `hi`    | LTR       |
| 24 | Hungarian             | Magyar             | `hu`    | LTR       |
| 25 | Indonesian            | Bahasa Indonesia   | `id`    | LTR       |
| 26 | Italian               | Italiano           | `it`    | LTR       |
| 27 | Japanese              | 日本語                | `ja`    | LTR       |
| 28 | Kazakh                | Қазақ тілі         | `kk`    | LTR       |
| 29 | Korean                | 한국어                | `ko`    | LTR       |
| 30 | Kyrgyz                | Кыргызча           | `ky`    | LTR       |
| 31 | Latvian               | Latviešu           | `lv`    | LTR       |
| 32 | Lithuanian            | Lietuvių           | `lt`    | LTR       |
| 33 | Macedonian            | Македонски         | `mk`    | LTR       |
| 34 | Malay                 | Bahasa Melayu      | `ms`    | LTR       |
| 35 | Mongolian             | Монгол             | `mn`    | LTR       |
| 36 | Montenegrin           | Crnogorski         | `cnr`   | LTR       |
| 37 | Norwegian             | Norsk              | `no`    | LTR       |
| 38 | Persian (Farsi)       | فارسی              | `fa`    | **RTL**   |
| 39 | Polish                | Polski             | `pl`    | LTR       |
| 40 | Portuguese            | Português          | `pt`    | LTR       |
| 41 | Portuguese (Brazil)   | Português (Brasil) | `pt-BR` | LTR       |
| 42 | Romanian              | Română             | `ro`    | LTR       |
| 43 | Russian               | Русский            | `ru`    | LTR       |
| 44 | Serbian               | Српски / Srpski    | `sr`    | LTR       |
| 45 | Slovak                | Slovenčina         | `sk`    | LTR       |
| 46 | Slovenian             | Slovenščina        | `sl`    | LTR       |
| 47 | Somali                | Soomaali           | `so`    | LTR       |
| 48 | Spanish               | Español            | `es`    | LTR       |
| 49 | Swedish               | Svenska            | `sv`    | LTR       |
| 50 | Thai                  | ไทย                | `th`    | LTR       |
| 51 | Turkish               | Türkçe             | `tr`    | LTR       |
| 52 | Ukrainian             | Українська         | `uk`    | LTR       |
| 53 | Uzbek                 | Oʻzbekcha          | `uz`    | LTR       |
| 54 | Vietnamese            | Tiếng Việt         | `vi`    | LTR       |

Three languages render right-to-left in both the verification UI and emails: **Arabic** (`ar`), **Hebrew** (`he`), and **Persian / Farsi** (`fa`).

<Tip>
  The validators that accept these codes are `BaseSessionSerializer.validate_language` and `ContactDetailsSerializer.validate_email_lang`. Both raise `400` with the message `"Invalid language. Supported languages are: ..."` (or `"Invalid email language..."`) for any value outside the table above.
</Tip>

## Picking a language for a session

The verification UI **auto-detects** the user's browser language. When the browser language is one of the codes above, the interface and emails are served in that language. Otherwise the UI falls back to **English**.

You can also set the language explicitly when creating a session:

```json theme={null}
{
  "workflow_id": "your-workflow-id",
  "language": "es",
  "contact_details": {
    "email": "user@example.com",
    "send_notification_emails": true,
    "email_lang": "es"
  }
}
```

If you only set `language`, emails still default to English unless you also pass `email_lang`. Conversely, setting `email_lang` does not change the in-browser UI language — the two fields are independent.

## Country variants

Three codes are **regional variants** that you should prefer when you know your audience:

* `pt-BR` — Brazilian Portuguese (use instead of generic `pt` for Brazilian users).
* `zh-CN` — Simplified Chinese (mainland China, Singapore).
* `zh-TW` — Traditional Chinese (Taiwan, Hong Kong, Macau).

The generic codes `pt` and `zh` are also accepted; the variant you choose only affects vocabulary and characters, not the underlying verification logic.

## Requesting a new language

If you need a language that is not listed above, contact our support team. We can typically add a new language to `EMAIL_TRANSLATIONS` and the verification UI **within 24 hours** of your request — once added, this page is updated and the new code is immediately accepted by the API.

Contact us via [WhatsApp](https://wa.me/+19544659728) or your usual support channel to request additional language support.

## Related references

<CardGroup>
  <Card title="Create Session API" icon="play" href="/sessions-api/create-session">
    Where `language` and `email_lang` are passed when starting a verification.
  </Card>

  <Card title="Update Session Status" icon="pen-to-square" href="/sessions-api/update-status">
    Sets `email_language` for the status-change notification email.
  </Card>

  <Card title="Webhooks" icon="webhook" href="/integration/webhooks">
    Receive verification results — payloads include the chosen `language`.
  </Card>

  <Card title="Data Models" icon="database" href="/reference/data-models">
    Canonical schema for sessions, contact details, and statuses.
  </Card>
</CardGroup>


# Verification Statuses
Source: https://docs.didit.me/integration/verification-statuses

Every Didit session status explained: Approved, Declined, In Review, Expired, Resubmitted, Abandoned, KYC Expired. Handle decisions, retries, and webhooks.

Every verification session moves through a series of statuses. Understanding them helps you monitor user progress, automate compliance decisions, and optimize conversion.

This enum is the single source of truth for the strings returned by `GET /v3/session/<id>/decision/` and every Didit webhook.

***

## All Status Values

<Note>
  Every status is an **exact string** returned by the Didit API and webhooks. Always use strict string matching (e.g., `=== "In Review"`) in your code — these values are case-sensitive and include spaces. The `Kyc Expired` value also uses a single capital `K` (not `KYC`).
</Note>

| Status        | String Value      | Description                                                          |
| ------------- | ----------------- | -------------------------------------------------------------------- |
| Not Started   | `"Not Started"`   | Session created, user hasn't opened the link                         |
| In Progress   | `"In Progress"`   | User is actively completing verification                             |
| Approved      | `"Approved"`      | All checks passed — identity verified                                |
| Declined      | `"Declined"`      | One or more checks failed                                            |
| In Review     | `"In Review"`     | Flagged for manual compliance review                                 |
| Awaiting User | `"Awaiting User"` | Waiting for one or more parties to complete their verification (KYB) |
| Resubmitted   | `"Resubmitted"`   | User asked to redo specific steps                                    |
| Expired       | `"Expired"`       | Session timed out before user opened the link                        |
| Abandoned     | `"Abandoned"`     | User started but didn't finish in time                               |
| KYC Expired   | `"Kyc Expired"`   | Previously approved session exceeded KYC expiration                  |

***

## Session Statuses

<AccordionGroup>
  <Accordion title="Not Started — &#x22;Not Started&#x22;" icon="circle-dot">
    **API value:** `"Not Started"`

    The session has been created via the API but the user **has not opened the verification link yet**.

    * **What to do:** Wait for the user to begin, or send a reminder if too much time passes.
    * **Transitions to:** `"In Progress"`, `"Expired"`
  </Accordion>

  <Accordion title="In Progress — &#x22;In Progress&#x22;" icon="spinner">
    **API value:** `"In Progress"`

    The user has opened the link and is **actively completing verification steps** (document capture, liveness, etc.).

    * **What to do:** No action needed — the user is working through the flow.
    * **Transitions to:** `"Approved"`, `"Declined"`, `"In Review"`, `"Abandoned"`
  </Accordion>

  <Accordion title="Approved — &#x22;Approved&#x22;" icon="circle-check">
    **API value:** `"Approved"`

    All verification checks **passed successfully**. The user's identity has been verified.

    * **What to do:** Grant the user access, update their profile, and store the decision data.
    * **Webhook includes:** Full `decision` object with all feature results.
    * **Transitions to:** `"Kyc Expired"` (if a KYC expiration policy is configured)
  </Accordion>

  <Accordion title="Declined — &#x22;Declined&#x22;" icon="circle-xmark">
    **API value:** `"Declined"`

    One or more verification checks **failed**. The user did not pass verification.

    * **What to do:** Notify the user. Optionally request a resubmission if the issue is fixable.
    * **Webhook includes:** Full `decision` object with warnings explaining the failure.
    * **Transitions to:** `"Resubmitted"` (if a reviewer requests it)
  </Accordion>

  <Accordion title="In Review — &#x22;In Review&#x22;" icon="magnifying-glass">
    **API value:** `"In Review"`

    Automated checks flagged **warnings that need human review**. A compliance reviewer must make the final decision.

    * **What to do:** A reviewer should open the session in the Console and approve, decline, or request resubmission.
    * **Webhook includes:** Full `decision` object with warnings.
    * **Transitions to:** `"Approved"`, `"Declined"`, `"Resubmitted"`
  </Accordion>

  <Accordion title="Awaiting User — &#x22;Awaiting User&#x22;" icon="users">
    **API value:** `"Awaiting User"`

    Used in **KYB (business verification) sessions** when the Key People step has submitted the list of parties and spawned child KYC / KYB sessions. The parent session waits until **all required parties complete their individual verification**.

    * **What to do:** Monitor the child KYC session statuses. Once all required parties finish (approved, declined, or expired), the parent session automatically re-aggregates to its final status.
    * **Webhook includes:** The current list of parties and their child session statuses.
    * **Transitions to:** `"Approved"`, `"Declined"`, `"In Review"` (once all child sessions are terminal)
    * **Transitions from:** `"In Progress"` (after the Key People step is submitted)
    * **Note:** If a child KYC session is resubmitted, the parent returns to `"Awaiting User"` until the resubmitted session completes. A `"Declined"` KYB Registry Check takes precedence over `"Awaiting User"`.
  </Accordion>

  <Accordion title="Resubmitted — &#x22;Resubmitted&#x22;" icon="rotate">
    **API value:** `"Resubmitted"`

    A reviewer has requested that the user **redo specific verification steps** (e.g., retake a blurry document photo).

    * **What to do:** Wait for the user to complete the resubmitted steps. The system will automatically re-evaluate.
    * **Webhook includes:** `resubmit_info` object with the list of features to redo and reasons.
    * **Transitions to:** `"Approved"`, `"Declined"`, `"In Review"`
  </Accordion>

  <Accordion title="Expired — &#x22;Expired&#x22;" icon="clock">
    **API value:** `"Expired"`

    The session **timed out before the user opened the verification link**.

    * **What to do:** Create a new session and send the user a fresh link.
    * **Terminal status** — no further transitions.
  </Accordion>

  <Accordion title="Abandoned — &#x22;Abandoned&#x22;" icon="person-walking-arrow-right">
    **API value:** `"Abandoned"`

    The user **started but did not finish** the verification within the allowed timeframe.

    * **What to do:** Send a reminder or create a new session.
    * **Terminal status** — no further transitions.
  </Accordion>

  <Accordion title="KYC Expired — &#x22;Kyc Expired&#x22;" icon="hourglass-end">
    **API value:** `"Kyc Expired"`

    A previously approved session has **exceeded the configured KYC expiration period** (e.g., 12 months).

    * **What to do:** Request the user to re-verify by creating a new session.
    * **Terminal status** — no further transitions.
  </Accordion>
</AccordionGroup>

***

## Status Transitions

| From                        | To                             | Trigger                                                           |
| --------------------------- | ------------------------------ | ----------------------------------------------------------------- |
| `"Not Started"`             | `"In Progress"`                | User opens the verification link                                  |
| `"Not Started"`             | `"Expired"`                    | Session TTL elapses before the user opens the link                |
| `"In Progress"`             | `"Approved"`                   | All automated checks pass                                         |
| `"In Progress"`             | `"Declined"`                   | One or more checks fail                                           |
| `"In Progress"`             | `"In Review"`                  | Checks flag warnings requiring human review                       |
| `"In Progress"`             | `"Awaiting User"`              | KYB Key People step submitted; parent waits for child KYC parties |
| `"In Progress"`             | `"Abandoned"`                  | User doesn't finish within the timeframe                          |
| `"Awaiting User"`           | `"Approved"`                   | All required KYB parties finish and aggregated checks pass        |
| `"Awaiting User"`           | `"Declined"`                   | A required party is declined or the KYB registry check fails      |
| `"Awaiting User"`           | `"In Review"`                  | Aggregated KYB result requires manual review                      |
| `"In Review"`               | `"Approved"`                   | Reviewer manually approves                                        |
| `"In Review"`               | `"Declined"`                   | Reviewer manually declines                                        |
| `"In Review"`               | `"Resubmitted"`                | Reviewer requests specific steps to be redone                     |
| `"Declined"`                | `"Resubmitted"`                | Reviewer requests specific steps to be redone                     |
| `"Resubmitted"`             | `"Approved"`                   | Resubmitted steps pass all checks                                 |
| `"Resubmitted"`             | `"Declined"`                   | Resubmitted steps fail                                            |
| `"Resubmitted"`             | `"In Review"`                  | Resubmitted steps flag new warnings                               |
| `"Resubmitted"` (KYB child) | `"Awaiting User"` (KYB parent) | Parent re-enters waiting state until child completes              |
| `"Approved"`                | `"Kyc Expired"`                | KYC expiration policy triggers                                    |

### Lifecycle diagram

```mermaid theme={null}
flowchart LR
    NS["Not Started"] --> IP["In Progress"]
    NS --> EX["Expired"]
    IP --> AP["Approved"]
    IP --> DC["Declined"]
    IP --> IR["In Review"]
    IP --> AU["Awaiting User<br/>(KYB only)"]
    IP --> AB["Abandoned"]
    AU --> AP
    AU --> DC
    AU --> IR
    IR --> AP
    IR --> DC
    IR --> RS["Resubmitted"]
    DC --> RS
    RS --> AP
    RS --> DC
    RS --> IR
    AP --> KE["Kyc Expired"]
```

***

## Terminal vs Non-Terminal

| Category         | Statuses                                                             | Meaning                                                                                                                  |
| ---------------- | -------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
| **Terminal**     | `"Approved"`, `"Declined"`, `"Kyc Expired"`                          | Final decision — session won't change again, except `"Approved"` → `"Kyc Expired"` when a KYC expiration policy applies. |
| **Non-Terminal** | `"Not Started"`, `"In Progress"`, `"Resubmitted"`, `"Awaiting User"` | Still active — awaiting user action, child sessions, or processing.                                                      |
| **Actionable**   | `"In Review"`                                                        | Requires manual intervention from your team.                                                                             |
| **Inactive**     | `"Expired"`, `"Abandoned"`                                           | Ended without a verification decision.                                                                                   |

***

## Handling Statuses in Your Code

Use webhooks or the [Retrieve Session API](/sessions-api/retrieve-session) to react to status changes.

<Warning>
  Statuses are **exact, case-sensitive strings with spaces**. For example, `"In Review"` (not `"in_review"` or `"IN_REVIEW"`). Always use strict equality (`===`) when matching.
</Warning>

```javascript theme={null}
// All ten possible status string values (StatusChoices, source of truth):
// "Not Started"  | "In Progress" | "Approved"     | "Declined" |
// "In Review"    | "Resubmitted" | "Awaiting User"|
// "Expired"      | "Abandoned"   | "Kyc Expired"

async function handleWebhook(webhook) {
  const { status, vendor_data: vendorData } = webhook;

  switch (status) {
    case "Not Started":
      // Session created but user hasn't opened the link yet
      break;

    case "In Progress":
      // User is actively completing verification steps
      break;

    case "Approved":
      // All checks passed — grant access
      await db.users.update(vendorData, {
        verified: true,
        verifiedAt: new Date(),
        decision: webhook.decision,
      });
      break;

    case "Declined":
      // Verification failed — notify user
      await db.users.update(vendorData, {
        verificationStatus: "declined",
        declineReasons: webhook.decision?.warnings,
      });
      break;

    case "In Review":
      // Needs manual review by compliance team
      await db.users.update(vendorData, {
        verificationStatus: "pending_review",
      });
      break;

    case "Awaiting User":
      // KYB parent waiting for all child KYC parties to finish
      await db.users.update(vendorData, {
        verificationStatus: "awaiting_kyb_parties",
      });
      break;

    case "Resubmitted":
      // User will redo specific steps
      await db.users.update(vendorData, {
        verificationStatus: "resubmission_pending",
        resubmitInfo: webhook.resubmit_info,
      });
      break;

    case "Abandoned":
      // User started but didn't finish — send reminder
      await sendReminderEmail(vendorData);
      break;

    case "Expired":
    case "Kyc Expired":
      // Session expired — create a new one
      await createNewSession(vendorData);
      break;
  }
}
```

***

## Resubmission

The **Resubmitted** status lets your compliance team give users a second chance without creating a new session.

<Steps>
  <Step title="Reviewer initiates resubmission">
    From the Console, open an `In Review` or `Declined` session and click **Request Resubmission**. Select which steps need to be redone.
  </Step>

  <Step title="Previous data is archived">
    The system resets the selected features and marks prior data as `previous_attempt` — preserving the full audit trail.
  </Step>

  <Step title="User is notified">
    If an email is available, the user receives a localized email with a direct link to resume.
  </Step>

  <Step title="User redoes specific steps">
    The user only repeats the steps that were flagged — not the entire verification.
  </Step>

  <Step title="System re-evaluates">
    Once complete, the session automatically transitions to `"Approved"`, `"Declined"`, or `"In Review"`.
  </Step>
</Steps>

### Resubmission Webhook Payload

```json theme={null}
{
  "session_id": "uuid-of-the-session",
  "status": "Resubmitted",
  "resubmit_info": {
    "nodes_to_resubmit": [
      { "node_id": "feature_ocr", "feature": "OCR" },
      { "node_id": "feature_liveness", "feature": "LIVENESS" }
    ],
    "reasons": {
      "feature_ocr": "Document image is blurry or unreadable",
      "feature_liveness": "Liveness check score below threshold"
    }
  }
}
```

### Which Features Can Be Resubmitted?

Any feature with a non-approved status: **Declined**, **In Review**, **Not Finished**, **Not Started**, or **Expired**.

<Tip>
  You can request resubmission multiple times on the same session. Each cycle archives the previous attempt data, giving you complete visibility into the user's verification history.
</Tip>

***

## Best Practices

<CardGroup>
  <Card title="Monitor In Review" icon="bell">
    Set up alerts (email or Slack) in your Didit Console to get notified when sessions need manual review.
  </Card>

  <Card title="Prefer Resubmission" icon="rotate">
    If the issue is fixable (blurry photo, wrong document side), request a resubmission instead of declining. This improves conversion.
  </Card>

  <Card title="Track Drop-offs" icon="chart-line">
    High Abandoned or Expired rates may indicate UX friction. Consider adjusting session TTL or improving user guidance.
  </Card>

  <Card title="Idempotent Handlers" icon="shield">
    Webhooks may be retried. Use `session_id` as a unique key to ensure you process each status change only once.
  </Card>
</CardGroup>

<Warning>
  Always verify webhook signatures before processing payloads. Didit provides three methods: `X-Signature`, `X-Signature-V2` (recommended), and the deprecated `X-Signature-Simple`, which authenticates the envelope only and never the `decision` body. See [Webhooks](/integration/webhooks#signature-verification) for details.
</Warning>


# InContext (Iframe)
Source: https://docs.didit.me/integration/web-sdks/incontext-iframe

Embed Didit identity verification in your site with an iframe in under 1 minute. UniLink or API sessions, React and Vue examples. Pay-per-use pricing.

<AgentPromptAccordion title="Iframe Integration Prompt" />

Embed the Didit verification flow directly within your application using an iframe. This provides a seamless experience without redirecting users away from your site.

## Overview

| Feature              | UniLink (No Backend) | API Session (With Backend) |
| -------------------- | -------------------- | -------------------------- |
| Setup Time           | \< 1 minute          | 5-10 minutes               |
| Backend Required     | ❌ No                 | ✅ Yes                      |
| Custom `vendor_data` | ❌ No                 | ✅ Yes                      |
| Custom `metadata`    | ❌ No                 | ✅ Yes                      |
| Per-session Callback | ❌ No                 | ✅ Yes                      |
| Session Tracking     | ❌ No                 | ✅ Yes                      |

***

## UniLink Iframe (No Backend Required)

The fastest way to get started – just copy and paste your UniLink URL.

### What You Need

1. A Didit workflow (created in the [Didit Console](https://business.didit.me))
2. Your UniLink URL (click **Copy Link** on your workflow)

### Implementation

```html theme={null}
<iframe 
  src="https://verify.didit.me/u/YOUR_WORKFLOW_ID_BASE64"
  style="width: 100%; height: 700px; border: none;" 
  allow="camera; microphone; fullscreen; autoplay; encrypted-media"
></iframe>
```

> ⚠️ **Required**: The `allow` attribute is mandatory for camera access during liveness detection.

### Key Benefits

* **Less than 1 minute setup** — No backend, no API keys
* **Zero configuration** — Callback URL set in workflow settings
* **Ideal for MVPs** — Get started immediately

***

## API Session Iframe (With Backend)

For advanced integrations that need per-session customization.

### When to Use

* Pass custom `vendor_data` or `metadata` per session
* Set different callback URLs per session
* Track sessions server-side before verification starts
* Associate sessions with your user IDs

### Implementation

**Step 1: Create a session (backend)**

The session-create response uses a field named **`url`** — use that as the iframe `src`.

```javascript theme={null}
// Node.js / Express
app.post('/api/create-verification', async (req, res) => {
  const { userId } = req.body;

  const response = await fetch('https://verification.didit.me/v3/session/', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.DIDIT_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      workflow_id: process.env.DIDIT_WORKFLOW_ID,
      vendor_data: userId,
      callback: 'https://yourapp.com/verification-callback',
      metadata: { source: 'web-app', timestamp: Date.now() },
    }),
  });

  if (!response.ok) {
    return res.status(response.status).send(await response.text());
  }

  // 201 per OpenAPI: { session_id, session_number, session_token, url, vendor_data,
  //                    metadata, status, workflow_id, workflow_version, callback }
  const session = await response.json();
  res.json({ sessionId: session.session_id, verificationUrl: session.url });
});
```

**Step 2: Embed in iframe (frontend)**

```html theme={null}
<iframe 
  id="didit-verification"
  src="" <!-- Set dynamically from API response -->
  style="width: 100%; height: 650px; border: none;" 
  allow="camera; microphone; fullscreen; autoplay; encrypted-media"
></iframe>

<script>
  async function startVerification() {
    const response = await fetch('/api/create-verification', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ userId: 'user-123' })
    });
    
    const { verificationUrl } = await response.json();
    document.getElementById('didit-verification').src = verificationUrl;
  }
</script>
```

***

## Listening for Events (postMessage)

The verification page posts events to the parent window. Every message has this envelope:

```typescript theme={null}
{
  type: 'didit:<event>',   // e.g. 'didit:completed'
  data: { /* payload */ }, // event-specific; may be undefined
  timestamp: 1718000000000 // ms epoch
}
```

The payload is **nested** — read `event.data.data.sessionId`, not `event.data.sessionId`:

```javascript theme={null}
window.addEventListener('message', (event) => {
  // Use your white-label domain here if you have one configured
  if (event.origin !== 'https://verify.didit.me') return;

  const { type, data } = event.data || {};

  if (type === 'didit:ready') {
    console.log('Session ID:', data.sessionId); // available as soon as the page loads
  }
  if (type === 'didit:completed') {
    console.log('Done:', data.sessionId, data.status); // e.g. "Approved" | "Declined" | "In Review"
    // UI hint only — the canonical decision arrives on your backend via webhook
  }
});
```

Key events: `didit:ready` (`{ sessionId }`), `didit:started`, `didit:step_started` / `didit:step_completed` / `didit:step_changed` (`{ step, ... }`), `didit:status_updated` (`{ status }`), `didit:completed` (`{ sessionId, status }`), `didit:cancelled`, `didit:error` (`{ error, step? }`), and `didit:close_request`. See the full table in the [JavaScript SDK event reference](/integration/web-sdks/javascript-sdk#event-reference) — the [JavaScript SDK](/integration/web-sdks/javascript-sdk) wraps this same contract in typed callbacks if you'd rather not handle raw messages.

***

## Modal Implementation

For a polished modal experience that overlays your page:

### HTML/CSS/JS

```html theme={null}
<!DOCTYPE html>
<html>
<head>
  <style>
    .didit-modal-overlay {
      display: none;
      position: fixed;
      inset: 0;
      background: rgba(0, 0, 0, 0.6);
      z-index: 9999;
      backdrop-filter: blur(4px);
    }
    
    .didit-modal-container {
      position: absolute;
      top: 50%;
      left: 50%;
      transform: translate(-50%, -50%);
      width: 90%;
      max-width: 480px;
      height: 85vh;
      max-height: 750px;
      background: white;
      border-radius: 16px;
      overflow: hidden;
      box-shadow: 0 25px 50px -12px rgba(0, 0, 0, 0.25);
    }
    
    .didit-modal-close {
      position: absolute;
      top: 12px;
      right: 12px;
      z-index: 10;
      width: 32px;
      height: 32px;
      border: none;
      background: rgba(0, 0, 0, 0.1);
      border-radius: 50%;
      cursor: pointer;
      font-size: 18px;
      display: flex;
      align-items: center;
      justify-content: center;
    }
    
    .didit-modal-close:hover {
      background: rgba(0, 0, 0, 0.2);
    }
    
    .didit-iframe {
      width: 100%;
      height: 100%;
      border: none;
    }
  </style>
</head>
<body>
  <button onclick="openVerification()">Verify Identity</button>

  <div id="didit-modal" class="didit-modal-overlay">
    <div class="didit-modal-container">
      <button class="didit-modal-close" onclick="closeVerification()">✕</button>
      <iframe 
        id="didit-iframe"
        class="didit-iframe"
        allow="camera; microphone; fullscreen; autoplay; encrypted-media"
      ></iframe>
    </div>
  </div>

  <script>
    const UNILINK_URL = 'https://verify.didit.me/u/YOUR_WORKFLOW_ID_BASE64';
    
    function openVerification() {
      document.getElementById('didit-iframe').src = UNILINK_URL;
      document.getElementById('didit-modal').style.display = 'block';
      document.body.style.overflow = 'hidden';
    }
    
    function closeVerification() {
      document.getElementById('didit-iframe').src = '';
      document.getElementById('didit-modal').style.display = 'none';
      document.body.style.overflow = '';
    }
    
    // Close on escape key
    document.addEventListener('keydown', (e) => {
      if (e.key === 'Escape') closeVerification();
    });
    
    // Close on overlay click
    document.getElementById('didit-modal').addEventListener('click', (e) => {
      if (e.target.id === 'didit-modal') closeVerification();
    });
  </script>
</body>
</html>
```

***

## React Component

A reusable React component for modal-based verification:

```tsx theme={null}
import { useState, useEffect } from 'react';

interface DiditInContextProps {
  /**
   * Either the `url` returned by POST /v3/session/ (API session)
   * or your UniLink URL copied from the Console (Workflows → Copy Link).
   * Don't derive the UniLink yourself — the path segment is a 22-character
   * base64url encoding of the workflow UUID's raw bytes, not btoa(workflowId).
   */
  verificationUrl: string;
  isOpen: boolean;
  onClose: () => void;
  onComplete?: (sessionId: string, status: string) => void;
}

export function DiditInContext({ 
  verificationUrl, 
  isOpen, 
  onClose,
  onComplete 
}: DiditInContextProps) {
  const [iframeSrc, setIframeSrc] = useState<string>('');

  useEffect(() => {
    if (isOpen) {
      setIframeSrc(verificationUrl);
      document.body.style.overflow = 'hidden';
    } else {
      setIframeSrc('');
      document.body.style.overflow = '';
    }
  }, [isOpen, verificationUrl]);

  // Listen for postMessage from iframe
  // Messages look like: { type: 'didit:<event>', data: {...}, timestamp }
  useEffect(() => {
    const handleMessage = (event: MessageEvent) => {
      // Use your white-label domain here if you have one configured
      if (event.origin !== 'https://verify.didit.me') return;

      if (event.data?.type === 'didit:completed' && onComplete) {
        onComplete(event.data.data?.sessionId, event.data.data?.status);
        onClose();
      }
    };

    window.addEventListener('message', handleMessage);
    return () => window.removeEventListener('message', handleMessage);
  }, [onComplete, onClose]);

  // Handle escape key
  useEffect(() => {
    const handleEscape = (e: KeyboardEvent) => {
      if (e.key === 'Escape' && isOpen) onClose();
    };
    
    document.addEventListener('keydown', handleEscape);
    return () => document.removeEventListener('keydown', handleEscape);
  }, [isOpen, onClose]);

  if (!isOpen) return null;

  return (
    <div 
      className="fixed inset-0 bg-black/60 backdrop-blur-sm z-50 flex items-center justify-center"
      onClick={(e) => e.target === e.currentTarget && onClose()}
    >
      <div className="relative w-[90%] max-w-[480px] h-[85vh] max-h-[750px] bg-white rounded-2xl overflow-hidden shadow-2xl">
        <button 
          onClick={onClose}
          className="absolute top-3 right-3 z-10 w-8 h-8 rounded-full bg-black/10 hover:bg-black/20 flex items-center justify-center"
          aria-label="Close"
        >
          ✕
        </button>
        <iframe 
          src={iframeSrc}
          className="w-full h-full border-0"
          allow="camera; microphone; fullscreen; autoplay; encrypted-media"
          title="Didit Verification"
        />
      </div>
    </div>
  );
}
```

### Usage

```tsx theme={null}
import { useState } from 'react';
import { DiditInContext } from './DiditInContext';

function App() {
  const [isVerificationOpen, setIsVerificationOpen] = useState(false);
  
  return (
    <>
      <button onClick={() => setIsVerificationOpen(true)}>
        Verify Identity
      </button>
      
      <DiditInContext
        verificationUrl="https://verify.didit.me/u/YOUR_WORKFLOW_ID_BASE64" // UniLink from Console, or the API session `url`
        isOpen={isVerificationOpen}
        onClose={() => setIsVerificationOpen(false)}
        onComplete={(sessionId, status) => {
          console.log(`Verification ${status}: ${sessionId}`);
          if (status === 'Approved') {
            // Navigate to success page
          }
        }}
      />
    </>
  );
}
```

***

## Vue Component

```vue theme={null}
<template>
  <Teleport to="body">
    <div 
      v-if="isOpen"
      class="fixed inset-0 bg-black/60 backdrop-blur-sm z-50 flex items-center justify-center"
      @click.self="$emit('close')"
    >
      <div class="relative w-[90%] max-w-[480px] h-[85vh] max-h-[750px] bg-white rounded-2xl overflow-hidden shadow-2xl">
        <button 
          @click="$emit('close')"
          class="absolute top-3 right-3 z-10 w-8 h-8 rounded-full bg-black/10 hover:bg-black/20 flex items-center justify-center"
        >
          ✕
        </button>
        <iframe 
          :src="iframeSrc"
          class="w-full h-full border-0"
          allow="camera; microphone; fullscreen; autoplay; encrypted-media"
        />
      </div>
    </div>
  </Teleport>
</template>

<script setup lang="ts">
import { computed, watch, onMounted, onUnmounted } from 'vue';

const props = defineProps<{
  isOpen: boolean;
  // The `url` from POST /v3/session/, or your UniLink URL copied from the
  // Console (Workflows → Copy Link). Don't derive the UniLink with btoa() —
  // its path segment is base64url of the workflow UUID's raw bytes.
  verificationUrl: string;
}>();

const emit = defineEmits<{
  close: [];
  complete: [sessionId: string, status: string];
}>();

const iframeSrc = computed(() => (props.isOpen ? props.verificationUrl : ''));

// Handle escape key
const handleEscape = (e: KeyboardEvent) => {
  if (e.key === 'Escape' && props.isOpen) emit('close');
};

// Handle postMessage — messages look like { type: 'didit:<event>', data: {...}, timestamp }
const handleMessage = (event: MessageEvent) => {
  // Use your white-label domain here if you have one configured
  if (event.origin !== 'https://verify.didit.me') return;
  if (event.data?.type === 'didit:completed') {
    emit('complete', event.data.data?.sessionId, event.data.data?.status);
  }
};

onMounted(() => {
  document.addEventListener('keydown', handleEscape);
  window.addEventListener('message', handleMessage);
});

onUnmounted(() => {
  document.removeEventListener('keydown', handleEscape);
  window.removeEventListener('message', handleMessage);
});

// Lock body scroll when open
watch(() => props.isOpen, (isOpen) => {
  document.body.style.overflow = isOpen ? 'hidden' : '';
});
</script>
```

***

## Configuration

### Required Permissions

Always include these permissions for camera and media access:

```html theme={null}
allow="camera; microphone; fullscreen; autoplay; encrypted-media"
```

| Permission        | Purpose                                |
| ----------------- | -------------------------------------- |
| `camera`          | Document scanning and face capture     |
| `microphone`      | Video recording for liveness detection |
| `fullscreen`      | Optimal capture experience             |
| `autoplay`        | Immediate camera activation            |
| `encrypted-media` | Secure media handling                  |

### Responsive Design

```css theme={null}
.didit-container {
  position: relative;
  width: 100%;
  max-width: 500px;
  margin: 0 auto;
}

.didit-iframe {
  width: 100%;
  height: 80vh;
  min-height: 600px;
  max-height: 800px;
  border: none;
  border-radius: 12px;
}

/* Mobile adjustments */
@media (max-width: 640px) {
  .didit-iframe {
    height: 100vh;
    min-height: unset;
    max-height: unset;
    border-radius: 0;
  }
}
```

### Content Security Policy (CSP)

If you use CSP, add Didit to your `frame-src` directive:

```
Content-Security-Policy: frame-src https://verify.didit.me;
```

***

## Cross-Device Verification

The InContext iframe automatically supports cross-device verification:

1. User starts verification on desktop
2. If camera is unavailable, a QR code is shown
3. User scans QR code on mobile
4. User completes verification on mobile
5. Desktop iframe automatically updates with result

This happens automatically – no additional configuration needed.

***

## Troubleshooting

### Camera Not Working

1. Ensure `allow="camera; microphone"` is set on the iframe
2. Check that your site is served over HTTPS
3. Verify the user has granted camera permissions to your domain
4. Try the [Redirect](/integration/web-sdks/web-redirect) method if iframe camera access fails

### Iframe Not Loading

1. Check for Content Security Policy (CSP) issues
2. Add `https://verify.didit.me` to your `frame-src` directive
3. Check browser console for errors

### postMessage Not Received

1. Verify you're listening for the correct origin (`https://verify.didit.me`, or your white-label domain)
2. Check that the event listener is added before opening the iframe
3. Check the event name and shape: types are prefixed (`didit:completed`, not `verification_complete`) and the payload is nested under `event.data.data`

***

## Example Repository

<Card title="GitHub Repository" icon="github" href="https://github.com/didit-protocol/iframe-example">
  View source code and examples on GitHub
</Card>

***


# JavaScript SDK
Source: https://docs.didit.me/integration/web-sdks/javascript-sdk

Integrate Didit identity verification into any web app with our JavaScript SDK. Embedded, redirect, or iframe modes. Pay-per-use pricing, 500 free/month.

<AgentPromptAccordion title="JavaScript SDK Integration Prompt" />

The Didit JavaScript SDK provides a programmatic way to integrate verification into your web application with full control over the user experience.

***

## Features

* **Simple API** - Singleton pattern with easy-to-use methods
* **Flexible Integration** - Use UniLink URL directly or create sessions via backend
* **Responsive** - Works on desktop and mobile browsers
* **Customizable** - Configuration options for styling and behavior
* **Multiple Formats** - ESM, CommonJS, and UMD builds
* **TypeScript Support** - Full type definitions included
* **Modal & Inline Modes** - Choose between modal overlay or inline embedding
* **Event Callbacks** - Real-time events for verification progress (started, step completed, finished)
* **State Management** - Observe SDK state for custom UI

***

## Installation

### NPM/Yarn

```bash theme={null}
npm install @didit-protocol/sdk-web
# or
yarn add @didit-protocol/sdk-web
```

### CDN (UMD)

```html theme={null}
<script src="https://unpkg.com/@didit-protocol/sdk-web/dist/didit-sdk.umd.min.js"></script>
```

<Note>
  The latest published npm release is `0.3.1`. Upgrade from `0.3.0` for correct modal sizing on short and landscape viewports, embedded mode that fills its own container, and an accurate `SDK_VERSION` export.
</Note>

### Check the installed version

Your package manager remains authoritative for the installed release:

```bash theme={null}
npm list @didit-protocol/sdk-web
npm view @didit-protocol/sdk-web version
```

You can also inspect the runtime export:

```typescript theme={null}
const { SDK_VERSION } = await import('@didit-protocol/sdk-web');

console.log(SDK_VERSION);
```

From `0.3.1` this export is generated from the package version in every JavaScript format (ESM, CommonJS, UMD, minified UMD) and in the TypeScript declaration, so it always matches the installed release.

`0.3.0` and earlier report `0.2.1` from this export regardless of the installed version. On those releases, use `npm list` or your lockfile instead.

***

## Vanilla JavaScript

### ES Modules / TypeScript

```typescript theme={null}
import { DiditSdk } from '@didit-protocol/sdk-web';

// Set up completion callback
DiditSdk.shared.onComplete = (result) => {
  switch (result.type) {
    case 'completed':
      console.log('Verification completed!');
      console.log('Session ID:', result.session?.sessionId);
      console.log('Status:', result.session?.status);
      break;
    case 'cancelled':
      console.log('User cancelled verification');
      break;
    case 'failed':
      console.error('Verification failed:', result.error?.message);
      break;
  }
};

// Start verification with the `url` returned by POST /v3/session/ (or your UniLink)
DiditSdk.shared.startVerification({
  url: 'https://verify.didit.me/session/3FaJ9wLqX2Mz'
});
```

### Script Tag (UMD)

```html theme={null}
<script src="https://unpkg.com/@didit-protocol/sdk-web/dist/didit-sdk.umd.min.js"></script>
<script>
  const { DiditSdk } = DiditSDK;

  DiditSdk.shared.onComplete = (result) => {
    if (result.type === 'completed') {
      alert('Verification completed: ' + result.session.status);
    }
  };

  function startVerification() {
    DiditSdk.shared.startVerification({
      // You can get this link by clicking on "copy link" in the workflows view
      url: 'https://verify.didit.me/u/WORKFLOW_ID_IN_BASE_64'
    });
  }
</script>

<button onclick="startVerification()">Verify Identity</button>
```

***

## Framework Examples

<Card title="SDK Web Examples" icon="github" href="https://github.com/didit-protocol/sdk-web-examples">
  React, Angular, Svelte, Next.js, Nuxt, Vue, and more — with examples and documentation for each framework.
</Card>

***

## Integration Methods

There are two ways to integrate the SDK:

### Method 1: UniLink URL (Simplest)

Use your workflow's UniLink URL directly from the Didit Console. No backend required.

```typescript theme={null}
DiditSdk.shared.startVerification({
  // You can get this link by clicking on "copy link" in the workflows view
  url: 'https://verify.didit.me/u/WORKFLOW_ID_IN_BASE_64'
});
```

Get your UniLink URL from the [Didit Console](https://business.didit.me) → Your Workflow → Copy Link.

**The session\_id generated will be sent to you by an event.**
**[Check event reference here](#event-reference)**

### Method 2: Backend session (recommended for production)

Your backend creates a session via the Didit API and returns the hosted verification URL. This gives you control over `vendor_data`, per-session `callback`, `metadata`, and lets you create sessions before the user reaches the frontend.

Read more in the [Create Session API reference](/sessions-api/create-session).

**Backend (Node.js / Express)**

```javascript theme={null}
import express from 'express';
const app = express();
app.use(express.json());

app.post('/api/create-session', async (req, res) => {
  const response = await fetch('https://verification.didit.me/v3/session/', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.DIDIT_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      workflow_id: process.env.DIDIT_WORKFLOW_ID,
      vendor_data: req.body.userId,             // links the session to your user
      callback: 'https://yourapp.com/verified', // optional — overrides workflow default
    }),
  });

  if (!response.ok) {
    return res.status(response.status).send(await response.text());
  }

  // 201 response fields (per OpenAPI): session_id, session_number, session_token, url,
  // vendor_data, metadata, status, workflow_id, workflow_version, callback
  const session = await response.json();
  res.json({ session_id: session.session_id, url: session.url });
});
```

**Frontend**

```typescript theme={null}
import { DiditSdk } from '@didit-protocol/sdk-web';

const res = await fetch('/api/create-session', {
  method: 'POST',
  headers: { 'Content-Type': 'application/json' },
  body: JSON.stringify({ userId: 'user-123' }),
});
const { url } = await res.json();

DiditSdk.shared.startVerification({
  url,
  configuration: {
    loggingEnabled: true,
  },
});
```

<Note>
  The session-create response field is named `url` (see the [Create Session OpenAPI schema](/sessions-api/create-session)). Pass it directly to `startVerification({ url })`.
</Note>

***

## Configuration

| Option                 | Type          | Default         | Description                                                                 |
| ---------------------- | ------------- | --------------- | --------------------------------------------------------------------------- |
| `loggingEnabled`       | `boolean`     | `false`         | Enable SDK logging for debugging                                            |
| `containerElement`     | `HTMLElement` | `document.body` | Custom container element to mount the modal                                 |
| `zIndex`               | `number`      | `9999`          | Z-index for the modal overlay                                               |
| `showCloseButton`      | `boolean`     | `true`          | Show close button on modal                                                  |
| `showExitConfirmation` | `boolean`     | `true`          | Show exit confirmation dialog when closing                                  |
| `closeModalOnComplete` | `boolean`     | `false`         | Automatically close modal when verification completes                       |
| `embedded`             | `boolean`     | `false`         | Render verification inline instead of modal overlay                         |
| `embeddedContainerId`  | `string`      | —               | Container element ID for embedded mode (required when `embedded` is `true`) |

<Tip>See the full [TypeScript type definitions](#typescript-types) below for the complete `DiditSdkConfiguration` interface.</Tip>

***

## Modal sizing and scrolling

<Note>The sizing behavior below requires **0.3.1** or later. **0.3.0** and earlier can clip the verification flow on short desktop and landscape viewports.</Note>

Modal mode uses a maximum width of 500px and a maximum height of 700px. On shorter desktop and landscape viewports, the iframe tracks 90% of the visible viewport. The verification flow scrolls inside the iframe, so every step remains reachable while the page behind the modal stays locked.

The SDK uses `dvh` on browsers that support dynamic viewport units and falls back to `vh` on older supported browsers. At widths of 540px and below, the modal fills the visible viewport. The close button and exit confirmation stay inside the modal.

***

## Embedded mode

Embedded mode does not use the modal's 500px by 700px cap. The SDK fills the host element's content box, so give that element an explicit or otherwise resolved height:

```html theme={null}
<div id="verification-container" style="width: 500px; height: 700px;"></div>
```

```typescript theme={null}
DiditSdk.shared.startVerification({
  url: 'https://verify.didit.me/u/...',
  configuration: {
    embedded: true,
    embeddedContainerId: 'verification-container'
  }
});
```

If the host has no resolved height, the embedded iframe also has no usable height. Resize the host when your layout changes; the SDK continues to fill it automatically.

***

## Verification Results

The SDK returns three types of results:

### Completed

Verification flow finished (approved, pending, or declined).

```typescript theme={null}
{
  type: 'completed',
  session: {
    sessionId: 'session-uuid',
    status: 'Approved' | 'Pending' | 'Declined'
  }
}
```

<Note>
  The TypeScript type declares `'Approved' | 'Pending' | 'Declined'`, but the value is passed through from the hosted flow's session status — you can also receive other statuses such as `In Review`. `Pending` is the SDK's fallback when the flow reported no status. Treat `status` as a hint and rely on the [webhook](/integration/webhooks) for the canonical decision.
</Note>

### Cancelled

User closed the verification modal. `session` is included when a `sessionId` was already known (it can be `undefined` if the user cancelled before the iframe reported one).

```typescript theme={null}
{
  type: 'cancelled',
  session: {
    sessionId: 'session-uuid',
    status: 'Pending'
  }
}
```

### Failed

An error occurred during verification.

```typescript theme={null}
{
  type: 'failed',
  error: {
    type: 'sessionExpired' | 'networkError' | 'cameraAccessDenied' | 'unknown',
    message: 'Your verification session has expired.'
  }
}
```

***

## State Management

You can observe the SDK state for custom UI:

```typescript theme={null}
DiditSdk.shared.onStateChange = (state, error) => {
  switch (state) {
    case 'idle':
      // Ready to start
      break;
    case 'loading':
      // Loading verification iframe
      showLoadingSpinner();
      break;
    case 'ready':
      // Verification in progress
      hideLoadingSpinner();
      break;
    case 'error':
      // Error occurred
      showError(error);
      break;
  }
};

// Check current state
console.log(DiditSdk.shared.state);

// Check if verification is presented
console.log(DiditSdk.shared.isPresented);
```

***

## API Reference

### DiditSdk.shared

The singleton SDK instance.

### Methods

| Method                       | Description                                   |
| ---------------------------- | --------------------------------------------- |
| `startVerification(options)` | Start the verification flow                   |
| `close()`                    | Programmatically close the verification modal |
| `destroy()`                  | Destroy the SDK instance and clean up         |

### Properties

| Property        | Type                                 | Description                                                    |
| --------------- | ------------------------------------ | -------------------------------------------------------------- |
| `state`         | `DiditSdkState`                      | Current SDK state                                              |
| `configuration` | `DiditSdkConfiguration \| undefined` | Active configuration (set while a verification is in progress) |
| `isPresented`   | `boolean`                            | Whether verification modal is open                             |
| `errorMessage`  | `string \| undefined`                | Error message (set when state is `error`)                      |

### Callbacks

| Callback        | Parameters                               | Description                            |
| --------------- | ---------------------------------------- | -------------------------------------- |
| `onComplete`    | `(result: VerificationResult)`           | Called when verification finishes      |
| `onStateChange` | `(state: DiditSdkState, error?: string)` | Called on state changes                |
| `onEvent`       | `(event: VerificationEvent)`             | Called on granular verification events |

***

## Granular Events

Track verification progress with the `onEvent` callback:

```typescript theme={null}
DiditSdk.shared.onEvent = (event) => {
  console.log('Event:', event.type, event.data);
};
```

### Event Reference

| Event                          | Description                                      | Data Payload                                       |
| ------------------------------ | ------------------------------------------------ | -------------------------------------------------- |
| `didit:ready`                  | The page is ready and the sessionId is available | `{ sessionId }`                                    |
| `didit:started`                | User started verification                        | `{ sessionId? }`                                   |
| `didit:step_started`           | A verification step began                        | `{ step, sessionId? }`                             |
| `didit:step_completed`         | A step finished successfully                     | `{ step, nextStep?, sessionId? }`                  |
| `didit:step_changed`           | Current step changed                             | `{ step, previousStep?, sessionId? }`              |
| `didit:media_started`          | Camera/media capture started                     | `{ step, mediaType }`                              |
| `didit:media_captured`         | Photo/video captured                             | `{ step, isAuto }`                                 |
| `didit:document_selected`      | User selected document type and country          | `{ documentType, country }`                        |
| `didit:verification_submitted` | Data submitted for processing                    | `{ step, sessionId? }`                             |
| `didit:code_sent`              | OTP code sent                                    | `{ step, channel?, codeSize?, sessionId? }`        |
| `didit:code_verified`          | OTP code verified                                | `{ step, sessionId? }`                             |
| `didit:status_updated`         | Session status changed                           | `{ status, previousStep?, sessionId? }`            |
| `didit:completed`              | Verification flow completed                      | `{ sessionId?, status?, country?, documentType? }` |
| `didit:cancelled`              | User cancelled verification                      | `{ sessionId? }`                                   |
| `didit:error`                  | An error occurred                                | `{ error: string, step?, sessionId? }`             |
| `didit:close_request`          | User requested to close modal                    | (no data)                                          |

### Step Values

The `step` field can be one of:

* `document_selection` - Document type selection
* `document_front` - Front side of document
* `document_back` - Back side of document
* `face` - Face/liveness verification
* `email` - Email verification
* `phone` - Phone verification
* `poa` - Proof of address
* `questionnaire` - Questionnaire step

### Channel Values

The `channel` field in `code_sent` can be:

* `email` - Code sent via email
* `sms` - Code sent via SMS
* `whatsapp` - Code sent via WhatsApp

### Code Size

The `codeSize` field in `code_sent` indicates the OTP code length (e.g., 4 or 6 digits).

***

## TypeScript Types

```typescript theme={null}
// Configuration types
interface DiditSdkConfiguration {
  /**
   * Enable SDK logging for debugging
   * @default false
   */
  loggingEnabled?: boolean;

  /**
   * Custom container element to mount the modal
   * @default document.body
   */
  containerElement?: HTMLElement;

  /**
   * Z-index for the modal overlay
   * @default 9999
   */
  zIndex?: number;

  /**
   * Show close button on modal
   * @default true
   */
  showCloseButton?: boolean;

  /**
   * Show exit confirmation dialog when closing
   * @default true
   */
  showExitConfirmation?: boolean;

  /**
   * Automatically close modal when verification completes
   * @default false
   */
  closeModalOnComplete?: boolean;

  /**
   * Render verification inline instead of modal overlay
   * @default false
   */
  embedded?: boolean;

  /**
   * Container element ID for embedded mode
   * Required when embedded is true
   */
  embeddedContainerId?: string;
}

// Session + error types
type VerificationStatus = 'Approved' | 'Pending' | 'Declined';

interface SessionData {
  sessionId: string;
  status: VerificationStatus;
}

type VerificationErrorType =
  | 'sessionExpired'
  | 'networkError'
  | 'cameraAccessDenied'
  | 'unknown';

interface VerificationError {
  type: VerificationErrorType;
  message: string;
}

// Verification result — `session` and `error` are both optional fields
// on every result; which one is populated depends on `type`.
type VerificationResultType = 'completed' | 'cancelled' | 'failed';

interface VerificationResult {
  type: VerificationResultType;
  session?: SessionData;
  error?: VerificationError;
}

// State types
type DiditSdkState = 'idle' | 'loading' | 'ready' | 'error';

// Event types
type VerificationEventType =
  | 'didit:ready'
  | 'didit:started'
  | 'didit:step_started'
  | 'didit:step_completed'
  | 'didit:step_changed'
  | 'didit:media_started'
  | 'didit:media_captured'
  | 'didit:document_selected'
  | 'didit:verification_submitted'
  | 'didit:code_sent'
  | 'didit:code_verified'
  | 'didit:status_updated'
  | 'didit:completed'
  | 'didit:cancelled'
  | 'didit:error'
  | 'didit:close_request';

interface VerificationEventData {
  sessionId?: string;
  status?: string;
  step?: string;
  nextStep?: string;
  previousStep?: string;
  error?: string;
  country?: string;
  documentType?: string;
  isAuto?: boolean;
  mediaType?: string;
  channel?: string;
  codeSize?: number;
  [key: string]: unknown;
}

interface VerificationEvent {
  type: VerificationEventType;
  data?: VerificationEventData;
  timestamp?: number;
}

// Start verification options
interface StartVerificationOptions {
  url: string;
  configuration?: DiditSdkConfiguration;
}
```


# Web SDKs
Source: https://docs.didit.me/integration/web-sdks/overview

Integrate Didit identity verification on the web with JavaScript SDK, iframe embed, or redirect. Pay-per-use pricing, 500 free verifications/month.

Integrate Didit verification into your web application. We offer seven integration methods to fit your architecture and user experience requirements — pick the one that matches your stack.

<Note>
  **Choose your integration method**: From quick no-code iframes to full programmatic control with our JavaScript SDK, or drop-in plugins for WordPress, Shopify, and Salesforce.
</Note>

***

## Integration Methods

| Method                                                                 | Setup Time  | Backend? | Best For                                                     |
| ---------------------------------------------------------------------- | ----------- | -------- | ------------------------------------------------------------ |
| [JavaScript SDK](/integration/web-sdks/javascript-sdk)                 | 3 minutes   | Optional | Full control — React/Vue/Angular/Next.js/Nuxt/Svelte/vanilla |
| [InContext (Iframe)](/integration/web-sdks/incontext-iframe)           | \< 1 minute | Optional | Embedded experience without redirect                         |
| [Redirect](/integration/web-sdks/web-redirect)                         | 5 minutes   | Yes      | Maximum compatibility, cross-device flows                    |
| [WebView (iOS/Android)](/integration/web-sdks/webview-in-ios-android)  | 15 minutes  | Yes      | Mobile fallback when no native SDK is available              |
| [WordPress + WooCommerce](/integration/web-sdks/wordpress-woocommerce) | 5 minutes   | No-code  | WordPress sites, WooCommerce stores                          |
| [Shopify](/integration/web-sdks/shopify)                               | 5 minutes   | No-code  | Shopify stores — checkout or account verification            |
| [Salesforce](/integration/web-sdks/salesforce)                         | 10 minutes  | No-code  | Salesforce CRM — Contact/Lead record verification            |

<Note>
  **Recommendation**: For production web apps, use the **JavaScript SDK** for the best UX and full programmatic control. Use **InContext iframe** for the quickest setup, **Redirect** when cross-device verification is needed, and the dedicated **WordPress / Shopify / Salesforce** integrations if you live on those platforms.
</Note>

***

## JavaScript SDK

The Didit JavaScript SDK provides a programmatic way to integrate verification with full control over the user experience.

**Key Features:**

* Session management and event callbacks
* React, Vue, Angular, NextJS, Nuxt, Svelte and vanilla JS support
* Full TypeScript support
* Modal & inline modes

**Quick Start:**

```javascript theme={null}
import { DiditSdk } from '@didit-protocol/sdk-web';

DiditSdk.shared.onComplete = (result) => {
  switch (result.type) {
    case 'completed':
      console.log('Verification completed!');
      console.log('Session ID:', result.session?.sessionId);
      console.log('Status:', result.session?.status);
      break;
    case 'cancelled':
      console.log('User cancelled verification');
      break;
    case 'failed':
      console.error('Verification failed:', result.error?.message);
      break;
  }
};

// Start verification with the `url` returned by POST /v3/session/ (or your UniLink)
DiditSdk.shared.startVerification({
  url: 'https://verify.didit.me/session/3FaJ9wLqX2Mz'
});
```

→ [**Full JavaScript SDK Documentation**](/integration/web-sdks/javascript-sdk)

***

## InContext (Iframe)

Embed the verification flow directly within your application using an iframe. Seamless experience without redirecting users away from your site.

**Key Features:**

* UniLink (no backend required) - setup in \< 1 minute
* API Session (with backend) - full customization
* Modal and inline implementations
* React component examples

**Quick Start:**

```html theme={null}
<iframe 
  src="https://verify.didit.me/u/YOUR_WORKFLOW_ID_BASE64"
  style="width: 100%; height: 700px; border: none;" 
  allow="camera; microphone; fullscreen; autoplay; encrypted-media"
></iframe>
```

→ [**Full InContext Documentation**](/integration/web-sdks/incontext-iframe)

***

## Redirect

Redirect users to the Didit-hosted verification page. After completion, users return to your callback URL.

**Key Features:**

* Maximum browser compatibility
* Cross-device verification support
* Simple integration
* Works when iframe camera access is problematic

**Quick Start:**

```javascript theme={null}
// After creating a session via your backend
window.location.href = verificationUrl;
```

→ [**Full Redirect Documentation**](/integration/web-sdks/web-redirect)

***

## Comparison

| Feature                   | JavaScript SDK | InContext (Iframe) | Redirect      |
| ------------------------- | -------------- | ------------------ | ------------- |
| Setup time                | 3 min          | \< 1 min           | 5 min         |
| Backend required          | Optional       | Optional           | Yes           |
| Stays on your domain      | Yes            | Yes                | No            |
| Cross-device support      | Yes            | Yes                | Yes           |
| Full programmatic control | Yes            | Limited            | Callback only |
| Event callbacks           | Real-time      | `postMessage`      | Callback only |
| White-label               | Yes            | Yes                | Yes           |
| Browser compatibility     | All            | All                | All           |

<Note>
  All three methods deliver final, signed results via [webhooks](/integration/webhooks) — the comparison above describes the in-browser UX, not how you receive the verification decision.
</Note>

***

## Configuration

### Required Iframe Permissions

For InContext iframe integrations, always include these permissions:

```html theme={null}
allow="camera; microphone; fullscreen; autoplay; encrypted-media"
```

***

## Example Repositories

<CardGroup>
  <Card title="SDK Web Examples" icon="github" href="https://github.com/didit-protocol/sdk-web-examples">
    React, Vue, Angular, Next.js, Nuxt, Svelte, and vanilla JS examples
  </Card>

  <Card title="Iframe Example" icon="github" href="https://github.com/didit-protocol/iframe-example">
    UniLink and API-session iframe examples
  </Card>

  <Card title="Full Next.js Demo" icon="github" href="https://github.com/didit-protocol/didit-full-demo">
    End-to-end Next.js integration
  </Card>

  <Card title="NPM Package" icon="npm" href="https://www.npmjs.com/package/@didit-protocol/sdk-web">
    `@didit-protocol/sdk-web` on npm
  </Card>
</CardGroup>

## Related

* [Webhooks](/integration/webhooks) — receive signed verification results on your backend
* [Create Session API](/sessions-api/create-session) — the endpoint behind every web SDK
* [Native SDKs](/integration/native-sdks/overview) — iOS, Android, React Native, Flutter


# Salesforce
Source: https://docs.didit.me/integration/web-sdks/salesforce

Add Didit identity verification to Salesforce with our managed package. No-code setup for KYC and KYB. Pay-per-use pricing, 500 free verifications/month.

Add Didit identity verification to Salesforce Sales Cloud / Service Cloud with our managed package. The component drops onto Contact and Lead record pages, creates sessions through your org via Apex (your Didit API key stays inside Salesforce), and writes results back to standard fields on the record so Flows and Reports can act on them. A built-in **Invocable Action** lets Flow Builder trigger verifications automatically — for example, when a new lead is created.

## Prerequisites

* A Salesforce org (Enterprise edition or higher; Developer Edition for testing)
* A [Didit Console](https://business.didit.me) account with a configured workflow
* Permission to install managed packages and create Sites in Setup

***

### Step 1: Install the app

1. Open the install link: <a href="https://login.salesforce.com/packaging/installPackage.apexp?p0=04tg50000003q0TAAQ">[https://login.salesforce.com/packaging/installPackage.apexp?p0=04tg50000003q0TAAQ](https://login.salesforce.com/packaging/installPackage.apexp?p0=04tg50000003q0TAAQ)</a>
2. Select **Install for all users**

<Frame>
  <img alt="Install Didit app in salesforce" />
</Frame>

3. Click **Install**

***

### Step 2: Get Your Didit Credentials

#### Get Your API Key (for API mode)

1. Log in to the [Didit Business Console](https://business.didit.me)
2. Navigate to **API & Webhooks** in the left-hand sidebar
3. Copy your API key

<Frame>
  <img alt="How to get the API key from the Didit Business Console" />
</Frame>

#### Get Your Workflow ID

1. In the Didit Business Console, go to **Workflows**
2. Select the workflow you want to use (or create a new one)
3. Copy the **Workflow ID** (a UUID like `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)

<Frame>
  <img alt="How to get the Workflow ID from the Didit Business Console" />
</Frame>

***

### Step 3: Configure Didit Settings

1. Click the **App Launcher** (grid icon, top-left) and search for **"Didit"**

<Frame>
  <img alt="how to enter in didit app" />
</Frame>

2. Open the **Didit** app — you'll land on the **Didit Settings** tab
3. Fill in your credentials and preferences:

| Field                      | Description                                                                                                                                             | Default                  |
| -------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------ |
| **Mode**                   | `api` (recommended) or `unilink`                                                                                                                        | `api`                    |
| **Didit API Key**          | Your Didit API key (API mode only)                                                                                                                      | —                        |
| **Workflow ID**            | Your Didit workflow ID (API mode only)                                                                                                                  | —                        |
| **Webhook Secret**         | HMAC secret from Didit Console → API & Webhooks. Required to receive real-time verification updates. If left empty, all incoming webhooks are rejected. | —                        |
| **UniLink URL**            | Fixed verification URL (UniLink mode only)                                                                                                              | —                        |
| **Display Mode**           | `modal` (popup) or `embedded` (inline)                                                                                                                  | `embedded`               |
| **Vendor Data**            | `record_id`, `record_email`, `custom prefix + record id`, or `none`                                                                                     | `record_id`              |
| **Language**               | Language code (e.g., `en`, `es`, `fr`)                                                                                                                  | `Auto detect by browser` |
| **Auto Send Contact Data** | Prefill verification with record data                                                                                                                   | `true`                   |
| **Show Close Button**      | Show X button on modal                                                                                                                                  | `true`                   |
| **Exit Confirmation**      | Confirm before closing modal                                                                                                                            | `true`                   |
| **Auto-close on Complete** | Auto-close modal after completion                                                                                                                       | `false`                  |
| **Debug Logging**          | Enable browser console logging                                                                                                                          | `false`                  |
| **Button Text**            | Verify button label                                                                                                                                     | `Verify Identity`        |
| **Button Success Text**    | Label after verification                                                                                                                                | `Identity Verified`      |
| **Button Color**           | Button background hex color                                                                                                                             | `#2667ff`                |

4. Click **Save Settings**

### Step 4: Add the Component to Record Pages

1. Navigate to a **Contact** or **Lead** record

<Frame>
  <img alt="contact page view" />
</Frame>

2. Click the **gear icon → Edit Page** (or Setup → Object Manager → Contact/Lead → Lightning Record Pages)

<Frame>
  <img alt="contact details view" />
</Frame>

3. In Lightning App Builder, drag **Didit Identity Verification** from the Components panel

<Frame>
  <img alt="Drag didit component" />
</Frame>

4. Click **Save** and **Activate** the page, select "Assign as Org Default" when activating, check the video:

<Frame>
  <img alt="Save and activate page with the didit component" />
</Frame>

5. The example above uses a Contact record page — the steps are identical for Lead record pages.

## How It Works

### API Mode (Recommended)

1. User clicks **Verify Identity** on a Contact/Lead record
2. Apex creates a session via the Didit API (API key stays server-side)
3. The Didit SDK opens the verification flow — as a modal overlay or inline embedded view depending on your Display Mode setting
4. On completion, the record is updated automatically:
   * `Verification Status` → the session result (`Approved`, `Declined`, `In Review`, etc.)
   * `Identity Verified` → `true` on Approved; `false` on Declined
   * `Verified At` timestamp and `Didit Session ID`
   * `Verified Document Type`, `Document Expiry Date`, `AML Check Status` (populated via webhook — see below)
5. The component shows the verified status, document type, expiry date, and AML result inline — no page layout configuration needed

### UniLink Mode

1. User clicks **Verify Identity**
2. A fixed UniLink URL opens in modal or iframe (no API call needed)
3. On completion, result is saved to the record

### Automatic Verification Updates (Webhooks)

When a verification session completes (whether the agent is watching the page or not), Didit sends a webhook to your Salesforce org to automatically update the Contact/Lead record. This requires a one-time Salesforce Site setup.

#### Why is this needed?

Salesforce does not accept incoming HTTP requests from external services without a public endpoint. A Salesforce Site creates this endpoint so Didit can push verification results directly to your org in real-time.

#### Step 1: Go to Setup > Sites

In Salesforce, click the **gear icon > Setup**. In the Quick Find box, type **Sites** and click on it under **Sites and Domains**.

<Frame>
  <img alt="Step 1 - Sites search" />
</Frame>

If this is your first time, check **"I have read and accepted the Salesforce Site Terms of Use"** and click **Register My Salesforce Site Domain**.

<Frame>
  <img alt="Step 1 - Sites page with domain registered" />
</Frame>

#### Step 2: Create a new Site

Click the **New** button in the Sites list. Fill in:

* **Site Label**: `DiditWebhook`
* **Site Name**: auto-fills as `DiditWebhook`
* **Default Web Address**: `didit`
* **Active**: checked
* **Active Site Home Page**: `InMaintenance`

Leave all other fields as defaults and click **Save**.

<Frame>
  <img alt="Step 2 - New Site form" />
</Frame>

#### Step 3: Verify the Site was created

After saving, you'll see the Site detail page. Note the **Site URL** — it will look like `https://your-org.develop.my.salesforce-sites.com/didit`. You'll need this later.

<Frame>
  <img alt="Step 3 - Site created" />
</Frame>

#### Step 4: Grant Guest User access to the webhook class

On the Site detail page, click **Public Access Settings**. This opens the Guest User profile. Scroll down to **Enabled Apex Class Access** and click **Edit**. Select **DiditWebhookReceiver** from the Available list and click **Add** to move it to the Enabled list. Click **Save**.

<Frame>
  <img alt="Step 4 - Apex Class Access" />
</Frame>

#### Step 5: Configure the webhook in Didit Console

1. Go to [business.didit.me](https://business.didit.me) > **API & Webhooks**
2. Set your **Webhook URL** to: `https://your-org.develop.my.salesforce-sites.com/didit/services/apexrest/didit/webhook/`

> **Note:** The exact domain format depends on your org type. Developer Edition orgs include `.develop` in the URL. Production orgs use `https://your-org.my.salesforce-sites.com/didit/services/apexrest/didit/webhook/`. Always copy the URL from your Site detail page (Step 3) to be sure.

3. Copy the **Webhook Secret Key**
4. In Salesforce, go to **Didit Settings** and paste the secret into the **Webhook Secret** field
5. Click **Save Settings**

That's it. From now on, every verification result will automatically update the Contact/Lead record — even if nobody has the Salesforce page open.

#### What the webhook saves

When Didit sends a webhook, the Contact or Lead is updated automatically.

**Always updated — regardless of workflow type:**

| Field                   | What it stores                                                  |
| ----------------------- | --------------------------------------------------------------- |
| **Verification Status** | `Approved`, `Declined`, `In Review`, `In Progress`, `Abandoned` |
| **Identity Verified**   | `true` on Approved; `false` on Declined or Abandoned            |
| **Verified At**         | Timestamp of the Approved result                                |
| **Didit Session ID**    | The session UUID                                                |

**Only updated when the feature is part of your workflow:**

| Field                            | Requires                         |
| -------------------------------- | -------------------------------- |
| **Verified Document Type**       | ID Verification in your workflow |
| **Document Expiry Date**         | ID Verification in your workflow |
| **AML Check Status**             | AML screening in your workflow   |
| **Verification Decline Reasons** | ID Verification in your workflow |

If a feature is not enabled in your Didit workflow, the corresponding fields are simply left blank — nothing breaks.

A **Didit Verification** child record (`Didit_Verification__c`) is also created for every session, giving you a full audit trail with additional detail (document number, issuing country, name on document, date of birth, face match score, liveness score, AML hit count) — again, only for the features included in the workflow.

You can add the **Didit Verifications** related list to your Contact/Lead page layout to view history.

### Flow Automation (Invocable Action)

The plugin includes an Invocable Apex action that Salesforce Flows can call to trigger verification automatically:

1. In Flow Builder, add an **Action** element
2. Search for **"Create Didit Verification Session"**
3. Pass a Contact or Lead record ID
4. The action returns `url`, `sessionId`, `success`, and `error`
5. Use the URL in a **Send Email** or **Send Notification** action to deliver it to the customer

**Example use cases:**

* **On Lead creation** — automatically send a verification link to every new lead
* **Document expiry monitoring** — build a Scheduled Flow that runs daily, finds all Contacts where `Document Expiry Date ≤ TODAY + 90 days`, and sends a re-verification link — this works out of the box using the `Document Expiry Date` field populated by the webhook

## Troubleshooting

### Button does nothing when clicked

* Make sure you've saved your API Key and Workflow ID in Didit Settings
* Check that the Workflow ID belongs to the same application as your API Key
* Enable **Debug Logging** in Didit Settings and check the browser console for errors

### "Received a non-JSON response from the Didit API"

* Verify the Remote Site Setting for `https://verification.didit.me` is active: Setup → Remote Site Settings
* Check that your API Key is valid and has not expired in the [Didit Business Console](https://business.didit.me)

### Webhook returns 401 — "Webhook secret not configured"

* Go to **Didit Settings** and paste your Webhook Secret Key (copied from Didit Console → API & Webhooks) into the **Webhook Secret** field, then click **Save Settings**

### Webhook returns 401 — "Invalid signature" or "Request timestamp is stale"

* Invalid signature: make sure the Webhook Secret in Didit Settings exactly matches the one in the Didit Console — no extra spaces or characters
* Stale timestamp: webhooks must arrive within 5 minutes of being sent. If your Salesforce org's clock is out of sync this can trigger false positives, but this is very rare

### Verification window does not open (CSP error in browser console)

* The CSP Trusted Site for `https://verify.didit.me` is included in the managed package and is deployed automatically. If you are deploying from source, make sure `cspTrustedSites/Didit_Verify_Frontend.cspTrustedSite-meta.xml` is included in your deployment

## Support (24/7)

Our team is available to help you get up and running.

<CardGroup>
  <Card title="WhatsApp Support" icon="comments" href="https://wa.me/+19544659728">
    Fastest response — reach us directly on WhatsApp.
  </Card>

  <Card title="Email" icon="envelope" href="mailto:hello@didit.me">
    Send us an email at [hello@didit.me](mailto:hello@didit.me).
  </Card>
</CardGroup>


# Shopify
Source: https://docs.didit.me/integration/web-sdks/shopify

Add identity verification and age gating to your Shopify store with the Didit app. No-code setup, pay-per-use pricing, 500 free verifications/month.

Add Didit identity verification and age gating to your Shopify store in minutes. The **Didit Verify** Shopify app installs a theme block you can drop onto any page (account, checkout, custom landing pages) and creates verification sessions server-side — your API key stays inside the embedded app, never exposed to the storefront. Verification results appear directly inside the app's **Verifications** tab in your Shopify admin — no separate backend required — and are also available via [webhooks](/integration/webhooks) and the [Didit API](/sessions-api/retrieve-session) for merchants who run their own backend. You do not need to log in to the Didit Business Console to access verification data collected through Shopify.

## Prerequisites

* A Shopify store (any plan)
* A [Didit Console](https://business.didit.me) account with at least one workflow

***

### Step 1: Install the app

1. Open the install link:

   <a href="https://admin.shopify.com/oauth/install?client_id=091c43ccd91f610a1e647b0067e03ac1">[https://admin.shopify.com/oauth/install?client\_id=091c43ccd91f610a1e647b0067e03ac1](https://admin.shopify.com/oauth/install?client_id=091c43ccd91f610a1e647b0067e03ac1)</a>

2. Select your store (if you have multiple stores)

3. Click **Install** to add the app to your store

<Note>
  The app requests a single permission scope — `read_customers` — used to prefill and cross-check the logged-in customer's details when **Auto-send Customer Data** is enabled.
</Note>

***

### Step 2: Configure Your Didit Credentials

After installation, you'll be redirected to the **Didit Verify Preferences** page. Here you'll connect the app to your Didit account.

#### Get Your API Key

1. Log in to the [Didit Business Console](https://business.didit.me)
2. Navigate to **API & Webhooks** in the left-hand sidebar
3. Copy your API key

<Frame>
  <img alt="How to get the API key from the Didit Business Console" />
</Frame>

4. Paste the API key into the **Didit API Key** field in the Shopify preferences

#### Get Your Workflow ID

1. In the Didit Business Console, go to **Workflows**
2. Select the workflow you want to use (or create a new one)
3. Copy the **Workflow ID** (a UUID like `xxxxxxxx-xxxx-xxxx-xxxx-xxxxxxxxxxxx`)

<Frame>
  <img alt="How to get the Workflow ID from the Didit Business Console" />
</Frame>

4. Paste the Workflow ID into the **Didit Workflow ID** field

#### Save Your Settings

Click **Save Settings**. You should see a success message:

<Frame>
  <img alt="Shopify settings saved successfully" />
</Frame>

***

### Step 3: Add the Verify Button to Your Theme

1. In your Shopify admin, go to **Online Store** → **Themes**
2. Click **Customize** on your active theme
3. Navigate to the page where you want the verification button (e.g., Account page, a custom page)
4. Click **Add section** or **Add block**
5. Go to the **Apps** tab
6. Select **Didit Verify**

The verification button will appear in your theme. You can drag it to reposition it within the section.

***

## Accessing verification data

Shopify's app review (requirement 5.1.5) requires that data collected through a Shopify-hosted flow be accessible to the merchant **within the Shopify admin or app context** — not only on an external dashboard. The Didit Verify app satisfies this out of the box: no backend, webhook receiver, or custom UI is required.

### The Verifications tab (default, no-code)

Open **Apps** → **Didit Verify** → **Verifications** in your Shopify admin to see every verification session collected through your storefront — status, customer, country, and timestamp — scoped to your shop. Select a session to view its full decision details (document type, identity fields, and the complete decision payload).

<Note>
  The Verifications tab only loads data when you open the app from your Shopify admin. If you see a message asking you to reopen the page, navigate back to **Apps** → **Didit Verify** from the Shopify admin sidebar.
</Note>

The Didit Business Console (`business.didit.me`) is a separate admin surface for configuration (API keys, workflows, webhook destinations). Do not instruct merchants to use it to view verification data collected through Shopify — that does not satisfy Shopify's data-access requirement. The Console is only needed for initial setup and credential retrieval.

### For merchants running their own backend (optional)

If you have your own backend and want a copy of the verification data there — for example to trigger fulfillment logic — Didit also delivers results via webhook and on-demand API, in addition to the Verifications tab above.

<Steps>
  <Step title="Verification session created">
    The Shopify app creates a session server-side using your Didit API key. The customer completes the verification flow in the theme block (modal or embedded).
  </Step>

  <Step title="Result delivered via webhook">
    When the session reaches a terminal status, Didit sends a signed `status.updated` webhook to the destination you configured in the Didit Business Console under **API & Webhooks**. The webhook body includes the full [decision object](/integration/webhooks#decision-object-v3) — the same schema returned by `GET /v3/session/{id}/decision/` — for `Approved`, `Declined`, `In Review`, and `Abandoned` statuses. Other terminal statuses (e.g. `Expired`, `Kyc Expired`) deliver the status change without a decision payload; call the API to inspect the session state.
  </Step>

  <Step title="Retrieve on demand (optional)">
    Your backend can also call [`GET /v3/session/{sessionId}/decision/`](/sessions-api/retrieve-session) at any time to fetch the full decision payload (identity fields, liveness, AML, face match, etc.).
  </Step>
</Steps>

#### Configuring webhooks for Shopify

1. In the [Didit Business Console](https://business.didit.me), navigate to **API & Webhooks** → **Webhooks**
2. Create a webhook destination pointing to your backend endpoint (HTTPS, publicly reachable)
3. Subscribe to at least `status.updated` and `data.updated` events
4. Store the returned `secret_shared_key` to verify HMAC-SHA256 signatures on incoming webhooks

See the [Webhooks guide](/integration/webhooks) for the full contract, signature verification examples in Node.js/Python/PHP, and retry behavior.

#### Retrieving a session decision via API

```bash theme={null}
curl https://verification.didit.me/v3/session/<SESSION_ID>/decision/ \
  -H "x-api-key: <YOUR_API_KEY>"
```

The response includes `session_kind`, `status`, and all feature arrays (`id_verifications`, `liveness_checks`, `face_matches`, `aml_screenings`, etc.). See [Retrieve Session](/sessions-api/retrieve-session) for the full response schema and field reference.

***

## Configuration Options

### Preferences Page Settings

These settings are configured in the app preferences (accessible from **Apps** → **Didit Verify** in your Shopify admin):

| Setting                     | Description                                                                                                                                                                                                                                              |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **API Key**                 | Your Didit API key (required)                                                                                                                                                                                                                            |
| **Workflow ID**             | The verification workflow to use (required)                                                                                                                                                                                                              |
| **Vendor Data**             | How sessions are linked to users in your Didit Console: **Customer ID** (sent as `shopify-<customer-id>`), **Customer Email**, **Shop + Customer ID** (sent as `<shop-domain>-<customer-id>`), or **None**. Only applied when the customer is logged in. |
| **Callback URL**            | Optional URL where users are redirected after verification. Didit appends `verificationSessionId` and `status` as query parameters.                                                                                                                      |
| **Callback Method**         | Which device handles the redirect: **Default (initiator)**, **Initiator**, **Completer**, or **Both**                                                                                                                                                    |
| **Language**                | Verification UI language (auto-detect or specific language)                                                                                                                                                                                              |
| **Require Customer Login**  | If enabled, only logged-in customers can verify                                                                                                                                                                                                          |
| **Auto-send Customer Data** | Prefill verification with the logged-in customer's name, email, phone, and country, and cross-check them against the verified document                                                                                                                   |

### Theme Block Settings

These settings are configured in the Shopify theme editor when you select the Didit Verify block:

#### Connection

| Setting         | Description                                                                                                                        |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| **Mode**        | **API Session** (recommended) — creates unique sessions per user. **UniLink** — uses a fixed verification URL (no backend needed). |
| **UniLink URL** | Only used in UniLink mode. Paste your UniLink URL from the Didit Console.                                                          |

#### Display

| Setting                      | Description                                                                                                   |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------- |
| **Display Mode**             | **Modal** — opens verification in a popup overlay. **Embedded** — shows verification inline below the button. |
| **Show close button**        | Show/hide the X button to close the verification modal                                                        |
| **Exit confirmation dialog** | Ask users to confirm before closing verification                                                              |
| **Auto-close on completion** | Automatically close the modal when verification completes                                                     |
| **Debug logging**            | Enable browser console logs for troubleshooting                                                               |

#### Button Appearance

| Setting                | Description                                                               |
| ---------------------- | ------------------------------------------------------------------------- |
| **Button text**        | Text shown on the button (default: "Verify your Identity")                |
| **Success text**       | Text shown after successful verification (default: "Identity Verified ✓") |
| **Background color**   | Button background color                                                   |
| **Text color**         | Button text color                                                         |
| **Border radius**      | Button corner roundness (0–50px)                                          |
| **Vertical padding**   | Top/bottom padding (0–40px)                                               |
| **Horizontal padding** | Left/right padding (0–60px)                                               |
| **Font size**          | Button text size (10–32px)                                                |

***

## Recommended Setup

For most stores, we recommend:

* **Mode:** API Session (creates unique verification sessions, better tracking)
* **Display Mode:** Modal (works everywhere, no layout issues)
* **Require Customer Login:** Enabled (links verification to customer accounts)
* **Auto-send Customer Data:** Enabled (prefills customer info, faster verification)

***

## Testing

1. Preview your theme or visit your store
2. Navigate to the page with the Didit Verify button
3. Click **Verify your Identity**
4. Complete the verification flow
5. Check your backend for the webhook delivery, or call [GET /v3/session//decision/](/sessions-api/retrieve-session) to retrieve the verification result

<Note>
  Didit includes 500 free verifications per month — more than enough to test the full flow at no cost.
</Note>

***

## Troubleshooting

### Button does nothing when clicked

* Make sure you've saved your API Key and Workflow ID in the preferences
* Check that the Workflow ID belongs to the same application as your API Key
* Enable **Debug logging** in the block settings and check the browser console for errors

### "Didit credentials not configured" error

* The app has no saved API Key or Workflow ID for this store. Open **Apps** → **Didit Verify**, fill in both fields, and click **Save Settings**

### "You must be logged in to verify your identity"

* **Require Customer Login** is enabled (the default). The customer needs to log in to their store account first — or disable the setting in the app preferences if you need guest verification

### Settings won't save

* "API key validation failed" — re-copy the API key from the [Didit Business Console](https://business.didit.me) and make sure there are no extra spaces
* "This workflow does not belong to your application" — the Workflow ID belongs to a different Didit application than your API key; copy both from the same application

## Support (24/7)

Our team is available to help you get up and running.

<CardGroup>
  <Card title="WhatsApp Support" icon="comments" href="https://wa.me/+19544659728">
    Fastest response — reach us directly on WhatsApp.
  </Card>

  <Card title="Email" icon="envelope" href="mailto:hello@didit.me">
    Send us an email at [hello@didit.me](mailto:hello@didit.me).
  </Card>
</CardGroup>


# Web Redirect
Source: https://docs.didit.me/integration/web-sdks/web-redirect

Redirect users to Didit's hosted KYC page. Simple callback URLs, cross-device support, full browser compatibility. Pay-per-use pricing, 500 free/month.

<AgentPromptAccordion title="Redirect Integration Prompt" />

The Redirect method sends users to a Didit-hosted page for verification, then returns them to your app via a callback URL.

| Feature               | Description                                                          |
| --------------------- | -------------------------------------------------------------------- |
| Setup Time            | 5 minutes                                                            |
| Backend Required      | ✅ Yes (to create sessions)                                           |
| Stays on Your Domain  | ❌ No (redirects to verify.didit.me or your whitelabel custom domain) |
| Cross-Device Support  | ✅ Yes                                                                |
| Browser Compatibility | ✅ All browsers                                                       |

***

## When to Use Redirect

* **Cross-device verification**: Start on desktop, complete on mobile
* **Maximum compatibility**: Works in all browsers, including older ones
* **Simple integration**: No iframe configuration needed
* **Camera issues**: When iframe camera access is problematic

***

## Implementation

### Step 1: Create a session (backend)

The session-create response uses a field named **`url`** — pass that value to the browser.

```javascript theme={null}
// Node.js / Express
app.post('/api/create-verification', async (req, res) => {
  const { userId } = req.body;

  const response = await fetch('https://verification.didit.me/v3/session/', {
    method: 'POST',
    headers: {
      'x-api-key': process.env.DIDIT_API_KEY,
      'Content-Type': 'application/json',
    },
    body: JSON.stringify({
      workflow_id: process.env.DIDIT_WORKFLOW_ID,
      vendor_data: userId,
      callback: 'https://yourapp.com/verification-complete',
      callback_method: 'both', // most reliable across desktop ↔ mobile handoffs
    }),
  });

  if (!response.ok) {
    return res.status(response.status).send(await response.text());
  }

  const session = await response.json();
  // 201 per OpenAPI: { session_id, session_number, session_token, url, vendor_data,
  //                    metadata, status, workflow_id, workflow_version, callback }
  res.json({ sessionId: session.session_id, verificationUrl: session.url });
});
```

### Step 2: Redirect the User (Frontend)

**HTML:**

```html theme={null}
<button onclick="startVerification()">Verify Identity</button>

<script>
  async function startVerification() {
    const response = await fetch('/api/create-verification', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ userId: 'user-123' })
    });
    
    const { verificationUrl } = await response.json();
    window.location.href = verificationUrl;
  }
</script>
```

**React:**

```tsx theme={null}
function VerifyButton() {
  const [loading, setLoading] = useState(false);

  const startVerification = async () => {
    setLoading(true);
    
    const response = await fetch('/api/create-verification', {
      method: 'POST',
      headers: { 'Content-Type': 'application/json' },
      body: JSON.stringify({ userId: 'user-123' })
    });
    
    const { verificationUrl } = await response.json();
    window.location.assign(verificationUrl);
  };

  return (
    <button onClick={startVerification} disabled={loading}>
      {loading ? 'Loading...' : 'Verify Identity'}
    </button>
  );
}
```

**Vue:**

```vue theme={null}
<template>
  <button @click="startVerification" :disabled="loading">
    {{ loading ? 'Loading...' : 'Verify Identity' }}
  </button>
</template>

<script setup>
import { ref } from 'vue';

const loading = ref(false);

async function startVerification() {
  loading.value = true;
  
  const response = await fetch('/api/create-verification', {
    method: 'POST',
    headers: { 'Content-Type': 'application/json' },
    body: JSON.stringify({ userId: 'user-123' })
  });
  
  const { verificationUrl } = await response.json();
  window.location.href = verificationUrl;
}
</script>
```

***

## Handling the Callback

When verification completes, Didit redirects to your callback URL with query parameters:

```
https://yourapp.com/verification-complete?verificationSessionId=abc123&status=Approved
```

| Parameter               | Description                            |
| ----------------------- | -------------------------------------- |
| `verificationSessionId` | Unique session identifier              |
| `status`                | `Approved`, `Declined`, or `In Review` |

### Next.js Example

```tsx theme={null}
// pages/verification-complete.tsx
import { useRouter } from 'next/router';
import { useEffect, useState } from 'react';

export default function VerificationComplete() {
  const router = useRouter();
  const { verificationSessionId, status } = router.query;
  const [message, setMessage] = useState('Processing...');

  useEffect(() => {
    if (!router.isReady) return;

    async function handleResult() {
      // Optionally verify the result with your backend
      await fetch('/api/verify-session', {
        method: 'POST',
        headers: { 'Content-Type': 'application/json' },
        body: JSON.stringify({ 
          sessionId: verificationSessionId, 
          status 
        })
      });

      // Redirect based on status
      switch (status) {
        case 'Approved':
          setMessage('Verification successful! Redirecting...');
          setTimeout(() => router.push('/dashboard'), 2000);
          break;
        case 'Declined':
          setMessage('Verification was not successful.');
          setTimeout(() => router.push('/verification-failed'), 2000);
          break;
        case 'In Review':
          setMessage('Your verification is under review.');
          setTimeout(() => router.push('/verification-pending'), 2000);
          break;
        default:
          setMessage('Unknown status. Please contact support.');
      }
    }

    handleResult();
  }, [router.isReady, verificationSessionId, status]);

  return (
    <div className="flex flex-col items-center justify-center min-h-screen">
      <div className="animate-spin w-8 h-8 border-4 border-blue-500 border-t-transparent rounded-full mb-4" />
      <p className="text-lg">{message}</p>
    </div>
  );
}
```

### Express.js Example

```javascript theme={null}
// routes/verification.js
app.get('/verification-complete', async (req, res) => {
  const { verificationSessionId, status } = req.query;
  
  // Optionally verify with Didit API
  // const session = await diditApi.getSession(verificationSessionId);
  
  // Update your database
  await db.users.update({
    where: { verificationSessionId },
    data: { verificationStatus: status }
  });
  
  // Redirect based on status
  switch (status) {
    case 'Approved':
      res.redirect('/dashboard?verified=true');
      break;
    case 'Declined':
      res.redirect('/verification-failed');
      break;
    case 'In Review':
      res.redirect('/verification-pending');
      break;
    default:
      res.redirect('/error');
  }
});
```

### Vue Router Example

```typescript theme={null}
// router/index.ts
{
  path: '/verification-complete',
  component: () => import('@/views/VerificationComplete.vue'),
  beforeEnter: async (to, from, next) => {
    const { verificationSessionId, status } = to.query;
    
    // Store result and redirect
    await store.dispatch('verification/handleResult', { 
      sessionId: verificationSessionId, 
      status 
    });
    
    if (status === 'Approved') {
      next('/dashboard');
    } else if (status === 'Declined') {
      next('/verification-failed');
    } else {
      next('/verification-pending');
    }
  }
}
```

***

## Open in New Tab

If you prefer to keep your app open while the user verifies:

```javascript theme={null}
// Open in new tab
window.open(verificationUrl, '_blank');

// Poll for completion or use webhooks
```

<Tip>
  When using new tabs, combine with [webhooks](/integration/webhooks) to know when verification completes.
</Tip>

***

## Security Best Practices

### Verify the callback server-side

Treat the `verificationSessionId` and `status` query parameters as untrusted UI hints. Always confirm the final decision on your backend — either by handling the [webhook](/integration/webhooks) (preferred) or by re-fetching the decision via the API:

```javascript theme={null}
// Backend: re-fetch the canonical decision before granting access
app.get('/verification-complete', async (req, res) => {
  const { verificationSessionId } = req.query;

  const response = await fetch(
    `https://verification.didit.me/v3/session/${verificationSessionId}/decision/`,
    {
      headers: { 'x-api-key': process.env.DIDIT_API_KEY },
    }
  );

  if (!response.ok) {
    return res.status(response.status).send(await response.text());
  }

  const decision = await response.json();

  // decision.status uses the canonical enum:
  // Not Started | In Progress | Awaiting User | In Review | Approved |
  // Declined   | Resubmitted | Expired | Kyc Expired | Abandoned
  if (decision.status === 'Approved') {
    // Grant access. Per-feature reports are plural arrays:
    //   decision.id_verifications[], decision.face_matches[], decision.aml_screenings[], ...
  }

  res.redirect('/dashboard');
});
```

### Use Webhooks

For the most reliable integration, use [webhooks](/integration/webhooks) to receive verification results directly to your backend, regardless of how the user's browser behaves.

***

## Cross-Device Flow

The redirect method naturally supports cross-device verification:

1. User clicks "Verify" on desktop
2. User is redirected to verification page
3. If needed, user can scan QR code to continue on mobile
4. After completion, the user is redirected to your callback URL — which device redirects is controlled by `callback_method` (`initiator`, `completer`, or `both`)

***

## Troubleshooting

### Callback Not Received

1. Verify the callback URL is correctly set when creating the session
2. Ensure your callback URL is accessible from the internet
3. Check that the URL doesn't have typos or encoding issues

### Status Always "Declined"

1. Check your workflow settings in the Didit Console
2. Verify the test documents you're using are valid
3. Review the session details via API for specific decline reasons

### Redirect Loop

1. Ensure your callback handler doesn't redirect back to verification
2. Check for caching issues on your callback page
3. Clear browser cache and try again

***

## Example Repository

<Card title="GitHub Repository" icon="github" href="https://github.com/didit-protocol/didit-full-demo">
  View source code and examples on GitHub
</Card>


# WebView Integration
Source: https://docs.didit.me/integration/web-sdks/webview-in-ios-android

Integrate Didit identity verification via WebView in iOS, Android, React Native, and Flutter apps. Camera permissions handled. Pay-per-use pricing.

<AgentPromptAccordion title="WebView Integration Prompt" />

This guide covers how to embed the **Didit web verification flow** inside a native mobile **WebView** component. It is **not** the same as the native iOS/Android/React Native/Flutter SDKs — it is a fallback for platforms that cannot use a native SDK.

<Warning>
  ### Always prefer native SDKs

  Native SDKs are available for **iOS**, **Android**, **React Native**, and **Flutter**. They provide significantly better performance, camera handling, NFC passport/ID reading, biometric integration, and user experience. **Use WebView only if no native SDK is available for your platform.**

  <CardGroup>
    <Card title="iOS SDK" icon="apple" href="/integration/native-sdks/ios-sdk">
      Native Swift SDK for iOS 13+
    </Card>

    <Card title="Android SDK" icon="android" href="/integration/native-sdks/android-sdk">
      Native Kotlin SDK for Android 6.0+
    </Card>

    <Card title="React Native SDK" icon="react" href="/integration/native-sdks/react-native-sdk">
      Cross-platform TypeScript API. Expo compatible.
    </Card>

    <Card title="Flutter SDK" icon="feather" href="/integration/native-sdks/flutter-sdk">
      Cross-platform Dart API. pub.dev package.
    </Card>
  </CardGroup>
</Warning>

| Platform        | Preferred Integration                                                        | WebView                 |
| --------------- | ---------------------------------------------------------------------------- | ----------------------- |
| iOS             | [iOS Native SDK](/integration/native-sdks/ios-sdk) — **Use this**            | Not recommended         |
| Android         | [Android Native SDK](/integration/native-sdks/android-sdk) — **Use this**    | Not recommended         |
| React Native    | [React Native SDK](/integration/native-sdks/react-native-sdk) — **Use this** | Not recommended         |
| Flutter         | [Flutter SDK](/integration/native-sdks/flutter-sdk) — **Use this**           | Not recommended         |
| Other platforms | N/A                                                                          | Use WebView as fallback |

***

## When to Use WebView

Use WebView integration **only** when:

* You're building on a platform without a native SDK (e.g., Xamarin, Cordova, or other niche frameworks)
* You need a quick prototype or proof of concept before integrating the native SDK
* You're migrating from web and want a temporary bridge to a native integration

***

## How It Works

<Steps>
  <Step title="Create a session">
    Your backend calls the [Create Session API](/sessions-api/create-session) and receives a hosted `url`.
  </Step>

  <Step title="Open in WebView">
    Your app loads the `url` in a WebView component.
  </Step>

  <Step title="User completes verification">
    The user goes through the verification flow inside the WebView.
  </Step>

  <Step title="Intercept callback">
    When done, the WebView navigates to your callback URL. Your app intercepts this navigation and extracts the result.
  </Step>

  <Step title="Get full results via webhook">
    Your backend receives the complete decision data via [webhook](/integration/webhooks).
  </Step>
</Steps>

***

## Creating a Session

Before opening the verification flow, create a session from your backend:

```bash theme={null}
curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_id": "your-workflow-id",
    "vendor_data": "user-123",
    "callback": "https://yourapp.com/callback"
  }'
```

Response (`201` — the `url` embeds the 12-character `session_token`, not the `session_id`):

```json theme={null}
{
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_number": 43762,
  "session_token": "3FaJ9wLqX2Mz",
  "url": "https://verify.didit.me/session/3FaJ9wLqX2Mz",
  "vendor_data": "user-123",
  "metadata": null,
  "status": "Not Started",
  "workflow_id": "11111111-2222-3333-4444-555555555555",
  "workflow_version": 3,
  "callback": "https://yourapp.com/callback"
}
```

Load the `url` field in the WebView — never build it from `session_token` by hand.

***

## React Native

Install the WebView package:

```bash theme={null}
npm install react-native-webview
# or with Expo
npx expo install react-native-webview
```

### Implementation

```javascript theme={null}
import React from 'react';
import { WebView } from 'react-native-webview';

const VerificationScreen = ({ sessionUrl, onComplete }) => {
  return (
    <WebView
      source={{ uri: sessionUrl }}
      // Required: generic mobile user agent
      userAgent="Mozilla/5.0 (Linux; Android 10; Mobile) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36"
      // Required for camera/media
      mediaPlaybackRequiresUserAction={false}
      allowsInlineMediaPlayback={true}
      // Android-specific
      domStorageEnabled={true}
      // Performance
      androidHardwareAccelerationDisabled={false}
      androidLayerType="hardware"
      // Intercept callback
      onNavigationStateChange={(navState) => {
        if (navState.url.includes('yourapp.com/callback')) {
          const url = new URL(navState.url);
          const sessionId = url.searchParams.get('verificationSessionId');
          const status = url.searchParams.get('status');
          onComplete({ sessionId, status });
        }
      }}
    />
  );
};

export default VerificationScreen;
```

<Card title="React Native Demo" icon="github" href="https://github.com/didit-protocol/expo-didit-verification-webview">
  Expo + WebView verification example
</Card>

***

## Flutter

Add the required packages to `pubspec.yaml`:

```yaml theme={null}
dependencies:
  webview_flutter: ^4.4.0
  webview_flutter_wkwebview: ^3.9.0
  webview_flutter_android: ^3.12.0
```

### Implementation

```dart theme={null}
import 'package:flutter/material.dart';
import 'package:webview_flutter/webview_flutter.dart';
import 'package:webview_flutter_wkwebview/webview_flutter_wkwebview.dart';
import 'package:webview_flutter_android/webview_flutter_android.dart';

class VerificationScreen extends StatefulWidget {
  final String sessionUrl;
  
  const VerificationScreen({super.key, required this.sessionUrl});

  @override
  State<VerificationScreen> createState() => _VerificationScreenState();
}

class _VerificationScreenState extends State<VerificationScreen> {
  late final WebViewController _controller;

  @override
  void initState() {
    super.initState();
    _setupWebView();
  }

  void _setupWebView() {
    late final PlatformWebViewControllerCreationParams params;
    
    if (WebViewPlatform.instance is WebKitWebViewPlatform) {
      params = WebKitWebViewControllerCreationParams(
        allowsInlineMediaPlayback: true,
        mediaTypesRequiringUserAction: const {},
      );
    } else {
      params = const PlatformWebViewControllerCreationParams();
    }

    _controller = WebViewController.fromPlatformCreationParams(params)
      ..setJavaScriptMode(JavaScriptMode.unrestricted)
      ..setUserAgent(
        'Mozilla/5.0 (Linux; Android 10; Mobile) AppleWebKit/537.36 '
        '(KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36'
      )
      ..setNavigationDelegate(
        NavigationDelegate(
          onNavigationRequest: (NavigationRequest request) {
            if (request.url.contains('yourapp.com/callback')) {
              _handleResult(request.url);
              return NavigationDecision.prevent;
            }
            return NavigationDecision.navigate;
          },
        ),
      )
      ..loadRequest(Uri.parse(widget.sessionUrl));

    // Grant camera/microphone permissions
    final platform = _controller.platform;
    platform.setOnPlatformPermissionRequest((request) {
      request.grant();
    });

    // Android-specific
    if (platform is AndroidWebViewController) {
      platform.setMediaPlaybackRequiresUserGesture(false);
    }
  }

  void _handleResult(String callbackUrl) {
    final uri = Uri.parse(callbackUrl);
    final sessionId = uri.queryParameters['verificationSessionId'];
    final status = uri.queryParameters['status'];
    
    Navigator.of(context).pop({
      'sessionId': sessionId,
      'status': status,
    });
  }

  @override
  Widget build(BuildContext context) {
    return Scaffold(
      appBar: AppBar(title: const Text('Identity Verification')),
      body: WebViewWidget(controller: _controller),
    );
  }
}
```

<Card title="Flutter Demo" icon="github" href="https://github.com/didit-protocol/flutter-didit-verification-webview">
  Flutter WebView verification example
</Card>

***

## Critical Configuration

### User Agent (Required)

You **must** set a generic mobile user agent for the WebView to work correctly:

```
Mozilla/5.0 (Linux; Android 10; Mobile) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/120.0.0.0 Mobile Safari/537.36
```

This ensures proper camera access, correct UI rendering, and optimal media playback.

### Media Settings (Required)

| Setting                            | Purpose                          |
| ---------------------------------- | -------------------------------- |
| `allowsInlineMediaPlayback`        | Prevents fullscreen video on iOS |
| `mediaPlaybackRequiresUserGesture` | Allows auto-starting the camera  |
| `javaScriptEnabled`                | Required for SDK functionality   |
| `domStorageEnabled`                | Session storage for Android      |

***

## Handling the Callback

After verification, the WebView redirects to your callback URL with query parameters:

```
https://yourapp.com/callback?verificationSessionId=abc123&status=Approved
```

| Parameter               | Description                            |
| ----------------------- | -------------------------------------- |
| `verificationSessionId` | Unique session identifier              |
| `status`                | `Approved`, `Declined`, or `In Review` |

<Tip>
  For a better user experience, use a **custom URL scheme** (e.g., `myapp://verification-complete`) as your callback and handle it as a deep link in your app.
</Tip>

***

## Troubleshooting

<AccordionGroup>
  <Accordion title="Camera not working">
    1. Ensure `mediaPlaybackRequiresUserGesture` is `false`
    2. Verify camera permissions are granted at the OS level
    3. Check that the user agent string is set correctly
  </Accordion>

  <Accordion title="White screen or loading issues">
    1. Verify the session URL is valid and not expired
    2. Check internet connectivity
    3. Ensure JavaScript is enabled in the WebView settings
  </Accordion>

  <Accordion title="Callback not triggering">
    1. Verify your callback URL matches what you set when creating the session
    2. Check that the navigation delegate/listener is properly configured
    3. Try setting `callback_method` to `"both"` when creating the session
  </Accordion>
</AccordionGroup>

***


# WordPress + WooCommerce
Source: https://docs.didit.me/integration/web-sdks/wordpress-woocommerce

Add identity verification and age gating to WordPress and WooCommerce stores in minutes. No-code plugin, pay-per-use pricing, 500 free/month.

Add Didit identity verification and age gating to any WordPress site or WooCommerce store. The plugin works as a secure backend proxy — your API key stays on the server — and exposes shortcodes, a WooCommerce checkout gate, and developer hooks so you can drop verification in without writing JavaScript.

## Prerequisites

* WordPress 6.0 or higher
* PHP 7.4 or higher
* A [Didit Console](https://business.didit.me) account

## Step 1: Get your Didit credentials

1. Sign up or log in at **[business.didit.me](https://business.didit.me)**
2. Go to **API & Webhooks** and copy your **API Key**
3. Go to **Workflows**, create or select a workflow, and copy the **Workflow ID**

<Note>
  You can also copy the **UniLink URL** (click "Copy Link" on the workflow) if you want the simplest setup without API keys.
</Note>

## Step 2: Install the plugin

1. Download `didit-verify.zip` from the **[latest release](https://github.com/didit-protocol/plugin-wordpress/releases/latest)**
2. In your WordPress admin, go to **Plugins → Add New → Upload Plugin**
3. Choose the downloaded ZIP file and click **Install Now**
4. Click **Activate**

<Note>
  Once the plugin is approved on WordPress.org, you will also be able to install it directly by searching "Didit Verify" in **Plugins → Add New**.
</Note>

## Step 3: Configure the plugin

Go to **Settings → Didit Verify**.

### Choose your mode

| Mode                          | Best for       | What you need                           |
| ----------------------------- | -------------- | --------------------------------------- |
| **UniLink**                   | Quick testing  | Just the UniLink URL from your workflow |
| **API Session** (recommended) | Production use | Workflow ID + API Key                   |

**For UniLink:** Set Mode to "UniLink", paste your URL, and save.

**For API Session:** Set Mode to "API Session", enter your Workflow ID and API Key, and save.

<Note>
  The API key is stored securely on your server and never exposed to visitors.
</Note>

### Configure session options (API mode only)

These are optional settings that give you more control:

* **Vendor Data** — Links each verification to a specific user in your Didit dashboard, so you can track who verified. Default is WordPress User ID (e.g. `wp-42`). You can also choose User Email, a custom prefix, or disable it.
* **Callback URL** — A page on your site where users are redirected after verification. Didit appends `verificationSessionId` and `status` as query parameters.
* **Callback Method** — Which device handles the redirect: `initiator` (the device that started), `completer` (the device that finishes), or `both`.
* **Language** — Choose from 49 languages or let it auto-detect from the browser.

### Configure display options

* **Display Mode** — Modal (popup overlay) or Embedded (inline on the page)
* **Close Button** — Show or hide the X button on the modal
* **Exit Confirmation** — Show an "Are you sure?" dialog when closing
* **Auto-close** — Automatically close the modal when verification completes
* **Debug Logging** — Log SDK events to the browser console (for troubleshooting)

### Customize the button

Under **Button Appearance**, you can change:

* Button text and success text
* Background color and text color
* Border radius, padding, and font size

A live preview updates in real time as you change values.

## Step 4: Add verification to your site

### For WooCommerce stores

1. In **Settings → Didit Verify → WooCommerce**, check **Require identity verification at checkout**
2. Choose where the verification section appears:
   * Top of checkout page
   * After billing details
   * After order notes
   * Before "Place Order" (recommended)
3. Optionally enable **Send Billing Data** to auto-send the customer's name, email, phone, and address to Didit for pre-filling and cross-validation

<Note>
  Country codes are automatically converted from WooCommerce's alpha-2 format to Didit's required alpha-3 format.
</Note>

Customers must complete verification before they can place an order. The session ID is saved to the order metadata for audit purposes.

### For any WordPress page

Add this shortcode to any page or post:

```
[didit_verify]
```

A verification button will appear, styled with your Button Appearance settings.

You can override the text per page:

```
[didit_verify text="Verify Now" success_text="Done!"]
```

Or force embedded mode on a specific page:

```
[didit_verify mode="embedded"]
```

## Step 5: Restrict content to verified users (optional)

Show or hide content based on verification status:

```
[didit_gate]
This content is only visible to verified users.
[/didit_gate]
```

Unverified users see a message and a verification button. You can customize the message:

```
[didit_gate message="Please verify to continue."]Secret content here.[/didit_gate]
```

Show the user's verification status anywhere:

```
[didit_status]
```

Displays "Identity Verified" or "Not Verified" for the logged-in user.

## Checking verification status

| Where                  | How                                                                 |
| ---------------------- | ------------------------------------------------------------------- |
| **Admin panel**        | **Users → All Users** — a "Didit" column shows ✓ for verified users |
| **WooCommerce orders** | The Didit session ID appears in the order details                   |
| **Shortcode**          | `[didit_status]` displays the status on any page                    |

## Troubleshooting

| Issue                             | Solution                                                                                           |
| --------------------------------- | -------------------------------------------------------------------------------------------------- |
| "Creating session..." hangs       | Check that your Workflow ID and API Key are correct in **Settings → Didit Verify**                 |
| Modal doesn't open                | Make sure the page contains `[didit_verify]` or WooCommerce checkout verification is enabled       |
| Verification UI in wrong language | Change the **Language** setting in **Session Options**                                             |
| Need to debug                     | Enable **Debug Logging** in Display Options, then open the browser console (F12) to see SDK events |

## Security

The plugin acts as a secure backend proxy. Your API key never reaches the browser. Every session request is protected by:

1. **CSRF nonce** — requests must originate from your WordPress site
2. **Login requirement** — only registered users can create sessions (configurable)
3. **Rate limiting** — 10 sessions/hour per user, 3/hour per IP for guests
4. **Input sanitization** — all fields are whitelisted and sanitized server-side

***

## For developers

### PHP hooks

The plugin fires WordPress actions that other plugins or themes can hook into:

```php theme={null}
// When a user completes verification
add_action('didit_verification_completed', function ($user_id, $session_id, $status) {
    // Update CRM, send email, grant access, etc.
}, 10, 3);

// When a user cancels verification
add_action('didit_verification_cancelled', function ($user_id, $session_id) {
    // Log cancellation
}, 10, 2);

// When a session is created server-side
add_action('didit_session_created', function ($url, $user_id, $vendor_data) {
    // Log, notify, etc.
}, 10, 3);
```

### JavaScript event

A DOM event is dispatched when verification finishes:

```javascript theme={null}
document.addEventListener('didit:complete', function (e) {
    console.log('Result:', e.detail); // { type, session }
});
```

### Check verification in PHP

```php theme={null}
$is_verified = get_user_meta($user_id, '_didit_verified', true); // returns 1 if verified
```

## Resources

* [Plugin source code (GitHub)](https://github.com/didit-protocol/plugin-wordpress)
* [Didit API documentation](/)
* [Didit Console](https://business.didit.me)
* [Create Session API reference](/sessions-api/create-session)


# Webhooks
Source: https://docs.didit.me/integration/webhooks

Receive real-time verification, entity, and transaction events from Didit. HMAC-SHA256 signing, fan-out destinations, and bounded retries.

<AgentPromptAccordion title="Webhook Integration Prompt" />

## Overview

Webhooks are how Didit pushes **real-time updates** to your backend whenever a verification session, business session, vendor user, vendor business, or transaction changes state. Subscribing one or more destinations to the events you care about lets you react the moment a result is ready — usually within seconds of the verifying user finishing their flow.

Webhooks are the **recommended** integration pattern. Polling [`GET /v3/session/{id}/decision/`](/sessions-api/retrieve-session) is supported as a fallback, but it is slower, costs more requests, and skips events like `data.updated`, `transaction.status.updated`, and entity-level changes that are only emitted through webhooks. Treat webhook delivery as the source of truth and only poll on cold start or for reconciliation.

This chapter of the Didit Academy integration lesson picks up at the webhooks overview.

The integration Academy lesson covers webhooks from 3:12: adding a destination, picking events, and the signing secret you will verify below.

<VideoEmbed title="Webhooks overview — Didit Academy" />

<Note>
  **Cloudflare / WAF users.** Didit delivers webhooks from the static IP `18.203.201.92` with `User-Agent: DiditWebhook/2.0 +https://didit.me`. If your edge blocks unknown clients, allow this IP in **Security > WAF > Tools > IP Access Rules** and choose **Allow** for the receiving hostname.
</Note>

## Event types

Use the exact value in a destination's `subscribed_events` array. There is no wildcard — list every family you want to receive — and you can spread events across multiple destinations.

| Event                        | Resource                            | When it fires                                                                                                                                                                                                                                                                                                                                    |
| ---------------------------- | ----------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `status.updated`             | KYC session or KYB business session | A session's status changes (Not Started → In Progress → Approved / Declined / In Review / Abandoned / Resubmitted). KYB payloads include `session_kind: "business"` and `business_session_id`.                                                                                                                                                   |
| `data.updated`               | KYC session or KYB business session | Verification data is edited after creation (manual reviewer corrections to KYC, POA, NFC, KYB registry, KYB documents, etc.).                                                                                                                                                                                                                    |
| `user.status.updated`        | User entity                         | A consolidated user's status changes between `ACTIVE`, `FLAGGED`, and `BLOCKED` (console action, rule action, blocklist). Includes `previous_status`.                                                                                                                                                                                            |
| `user.data.updated`          | User entity                         | A consolidated user's profile, counters, metadata, or approved-identifiers change. Includes `changed_fields` and a `changes` map of `previous` / `current` values.                                                                                                                                                                               |
| `business.status.updated`    | Business entity                     | A consolidated business's status changes between `ACTIVE`, `FLAGGED`, and `BLOCKED` (console action, rule action, blocklist). Includes `previous_status`.                                                                                                                                                                                        |
| `business.data.updated`      | Business entity                     | A consolidated business's profile, registration data, counters, metadata, or aggregate verification fields change. Includes `changed_fields` and `changes`.                                                                                                                                                                                      |
| `activity.created`           | Activity timeline                   | Reserved for the activity timeline feed. The value is accepted in `subscribed_events` and covered by the **Try Webhook** tester, but Didit does not currently deliver `activity.created` for live traffic.                                                                                                                                       |
| `transaction.created`        | Transaction Monitoring              | A transaction is created and its initial rules verdict is ready. Includes `transaction_id`, `txn_id`, `status`, `score`, `severity`, `amount`, `currency`, `direction`.                                                                                                                                                                          |
| `transaction.status.updated` | Transaction Monitoring              | A transaction's status changes after rule evaluation, analyst action, remediation, blocklist matches, provider updates, or API/console actions.                                                                                                                                                                                                  |
| `travel_rule.status.updated` | Travel Rule                         | A [Travel Rule](/transaction-monitoring/travel-rule) exchange's status changes - on creation, ownership confirmation, email pickup response, finish/cancel, or timeout expiry. Fires for both the outbound transfer and any `INTERNAL`-rail inbound counterpart. Includes `transaction_id`, `txn_id`, `travel_rule_status`, `rail`, `direction`. |

These ten values are the complete set of subscribable events - there is no `session.status.updated`, `kyc.completed`, or similar. The only other delivery Didit makes is the unsigned [`kyb.registry_search.resolved` callback](#kyb-registry-search-callback), which goes to the per-request `webhook_url` you pass to [`POST /v3/kyb/search/`](/standalone-apis/kyb-registry), never to a destination.

<Tip>
  The Business Console > API & Webhooks > **Try Webhook** menu sends fully-formed payloads for every one of these events (approved, declined, in-review, Unicode names, KYC/KYB, entity, activity, and transaction). Use it to validate your endpoint before going live.
</Tip>

## Payload shape

### Envelope

Every webhook shares the same envelope. Fields are always serialised with `sort_keys=True` and compact separators (`,` / `:`) so the same payload reproduces the same signature on both sides.

| Field            | Type                    | Notes                                                                                                                                                                                                                                                                                                                                  |
| ---------------- | ----------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `event_id`       | `uuid`                  | Stable identifier for the event. The **same** `event_id` is sent to every destination the event fans out to and is reused on retries — key your idempotency on it.                                                                                                                                                                     |
| `webhook_type`   | string                  | One of the [event types](#event-types) above.                                                                                                                                                                                                                                                                                          |
| `timestamp`      | int (Unix seconds)      | When Didit dispatched the webhook. Used by signature verification. Refreshed on each retry.                                                                                                                                                                                                                                            |
| `created_at`     | int (Unix seconds)      | When the underlying record was last updated.                                                                                                                                                                                                                                                                                           |
| `application_id` | `uuid`                  | The application that owns the destination.                                                                                                                                                                                                                                                                                             |
| `environment`    | `"live"` \| `"sandbox"` | Whether the event came from a live or sandbox session/application.                                                                                                                                                                                                                                                                     |
| `status`         | string                  | Present on every delivered event (including `*.data.updated`). Session events use the exact [verification status labels](/integration/verification-statuses) (e.g. `"Approved"`, `"Kyc Expired"`); entity events use `ACTIVE` / `FLAGGED` / `BLOCKED`; transaction events use `APPROVED` / `IN_REVIEW` / `DECLINED` / `AWAITING_USER`. |

For **session** events (`status.updated`, `data.updated` on regular and business sessions) the envelope additionally carries:

| Field                 | Type                             | Notes                                                                                                                                                                                                                                                                                                 |
| --------------------- | -------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session_id`          | `uuid`                           | The user-verification or business-session UUID.                                                                                                                                                                                                                                                       |
| `business_session_id` | `uuid`                           | Only on KYB. Equal to `session_id`.                                                                                                                                                                                                                                                                   |
| `session_kind`        | `"business"`                     | Only on KYB events; lets a generic handler branch.                                                                                                                                                                                                                                                    |
| `workflow_id`         | `uuid`                           | Workflow used to create the session, when set.                                                                                                                                                                                                                                                        |
| `workflow_version`    | int                              | Workflow version.                                                                                                                                                                                                                                                                                     |
| `vendor_data`         | string                           | Your internal identifier, when supplied at session creation.                                                                                                                                                                                                                                          |
| `vendor_business_id`  | string                           | Only on KYB sessions, when supplied.                                                                                                                                                                                                                                                                  |
| `sandbox_scenario`    | string \| null                   | On every session event (KYC and KYB). The armed [sandbox](/integration/sandbox-testing) scenario slug (e.g. `"decline_aml_hit"`) on a sandbox session with a scenario armed; `null` on a live session, or on a sandbox session with no scenario armed. Not present on entity or transaction webhooks. |
| `metadata`            | object                           | Whatever metadata you attached at session creation, with internal dedup keys stripped.                                                                                                                                                                                                                |
| `trigger`             | string                           | Optional. Why the webhook fired: `"manual_review"` (reviewer edits from the console), `"manual_step_update"` (a reviewer changed a feature status), or `"ongoing_monitoring"` (AML ongoing-monitoring refresh).                                                                                       |
| `decision`            | object                           | Present when `status` is `Approved`, `Declined`, `In Review`, or `Abandoned`. Mirrors the [V3 session decision](/sessions-api/retrieve-session).                                                                                                                                                      |
| `resubmit_info`       | `{ nodes_to_resubmit, reasons }` | Present when `status` is `Resubmitted` (no `decision`).                                                                                                                                                                                                                                               |

### Session envelope example

```json theme={null}
{
  "event_id": "9c0c8b8a-1111-4222-9333-444444444444",
  "webhook_type": "status.updated",
  "timestamp": 1774970000,
  "created_at": 1774969994,
  "application_id": "11111111-2222-3333-4444-555555555555",
  "environment": "live",
  "sandbox_scenario": null,
  "session_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "status": "Approved",
  "workflow_id": "66666666-7777-8888-9999-000000000000",
  "workflow_version": 4,
  "vendor_data": "user_42",
  "metadata": { "tier": "premium" },
  "decision": { "...": "see /sessions-api/retrieve-session" }
}
```

<Tip>
  The `decision` object is the same schema returned by [`GET /v3/session/{id}/decision/`](/sessions-api/retrieve-session). For the canonical per-feature field reference (every property on `id_verifications[]`, `aml_screenings[]`, etc.) see [Data models](/reference/data-models). We deliberately do not duplicate the per-feature field tables here so the schema only lives in one place.
</Tip>

### V3 plural arrays (important)

Inside `decision`, every per-feature result is a **plural array** so a single workflow can include several instances of the same feature (for example, multiple ID checks across documents):

```text theme={null}
id_verifications[]        nfc_verifications[]
liveness_checks[]         face_matches[]
phone_verifications[]     email_verifications[]
poa_verifications[]       aml_screenings[]
ip_analyses[]             database_validations[]
questionnaire_responses   reviews[]
```

Each item carries a `node_id` matching the workflow graph plus a per-feature `status`. **Do not** read the legacy V2 singular fields (`id_verification`, `nfc`, `liveness`, `face_match`, `phone`, `email`, `poa`, `aml`, `ip_analysis`, `database_validation`); they only appear if a destination is explicitly pinned to `webhook_version: "v2"`.

Document-collection features — **KYB documents** and **Document AI** — do not have a dedicated plural array; they appear in the decision `features[]` list as `{ "feature": "DOCUMENT_AI", "node_id": "…" }` (one entry per node). See [Document AI](/core-technology/document-ai/overview).

### ID Verification method keys

Every `id_verifications[]` item says which [ID Verification method](/core-technology/id-verification/verification-methods) produced it, so a handler can branch on the evidence it actually got:

| Key                   | Value                                                                     |
| --------------------- | ------------------------------------------------------------------------- |
| `verification_method` | `document`, `id_lookup` or `wallet`                                       |
| `assurance`           | `documentary`, `data_match` or `cryptographic`                            |
| `wallet_provider`     | Catalog wallet id when a wallet produced it, otherwise `null`             |
| `id_lookup`           | Registry evidence when the method was `id_lookup`, otherwise `null`       |
| `wallet_verification` | Credential evidence when the method was `wallet`, otherwise `null`        |
| `fallback_from`       | Why a non-document method ended the ID step, when it declined the session |

Existing handlers keep working untouched: a document session sets `verification_method` to `document` and leaves the rest `null`. Field-by-field types are in [Data models](/reference/data-models#id-verification).

#### Approved wallet session (`status.updated`)

```json theme={null}
{
  "event_id": "3a0c1b2c-4444-4555-8666-777777777777",
  "webhook_type": "status.updated",
  "timestamp": 1774970000,
  "created_at": 1774969994,
  "application_id": "11111111-2222-3333-4444-555555555555",
  "environment": "live",
  "session_id": "cccccccc-dddd-eeee-ffff-000000000000",
  "status": "Approved",
  "vendor_data": "user_77",
  "decision": {
    "session_id": "cccccccc-dddd-eeee-ffff-000000000000",
    "status": "Approved",
    "features": ["ID_VERIFICATION"],
    "id_verifications": [
      {
        "node_id": "id_verification_1",
        "status": "Approved",
        "issuing_state": "DNK",
        "first_name": "Freja",
        "last_name": "Nielsen",
        "full_name": "Freja Nielsen",
        "date_of_birth": "1988-03-02",
        "verification_method": "wallet",
        "assurance": "cryptographic",
        "wallet_provider": "mitid",
        "fallback_from": null,
        "id_lookup": null,
        "wallet_verification": {
          "provider": "mitid",
          "provider_name": "MitID",
          "issuing_authority": "Danish Agency for Digital Government",
          "issuing_country": "DNK",
          "credential_type": "person_identification",
          "level_of_assurance": "substantial",
          "verified_at": "2026-09-04T09:12:44Z",
          "signature_valid": true,
          "attributes": {
            "full_name": "Freja Nielsen",
            "date_of_birth": "1988-03-02",
            "cpr_alias": "b0f1c2d3-e4f5-4678-9abc-def012345678"
          },
          "portrait": null,
          "face_match_score": null
        },
        "warnings": []
      }
    ],
    "reviews": [],
    "created_at": "2026-09-04T09:12:20.443172Z"
  }
}
```

### Entity event payloads

```json theme={null}
{
  "event_id": "uuid",
  "webhook_type": "user.status.updated",
  "timestamp": 1774970000,
  "created_at": 1774969994,
  "application_id": "uuid",
  "environment": "live",
  "vendor_user_id": "uuid",
  "vendor_data": "user_42",
  "status": "BLOCKED",
  "previous_status": "ACTIVE"
}
```

Entity statuses are `ACTIVE`, `FLAGGED`, or `BLOCKED`. `user.data.updated` and `business.data.updated` keep the `status` field and add a `changed_fields` array plus a `changes` map of `{ field: { previous, current } }`. `business.*` events use `vendor_business_id` instead of `vendor_user_id`.

### Transaction event payloads

Transaction webhooks ride on the same fan-out infrastructure and use the same envelope, but identify the transaction instead of a session:

```json theme={null}
{
  "event_id": "uuid",
  "webhook_type": "transaction.created",
  "timestamp": 1774970000,
  "created_at": 1774970000,
  "application_id": "uuid",
  "environment": "live",
  "transaction_id": "uuid",
  "txn_id": "finance0001",
  "status": "APPROVED",
  "score": 0,
  "severity": "UNKNOWN",
  "amount": "1200.00",
  "currency": "EUR",
  "direction": "OUTBOUND"
}
```

New transactions default to `APPROVED`. If a rule, blocklist, or workflow changes the status during creation, the initial `transaction.created` payload reflects that final status. `transaction.status.updated` carries the same shape with the updated `status`. Transaction statuses are `APPROVED`, `IN_REVIEW`, `DECLINED`, or `AWAITING_USER`; `severity` is `UNKNOWN` / `LOW` / `MEDIUM` / `HIGH` / `CRITICAL` and `direction` is `INBOUND` / `OUTBOUND`. Transaction webhooks are only delivered for **live** applications — sandbox transactions never fan out.

### KYB registry search callback

The asynchronous [`POST /v3/kyb/search/`](/standalone-apis/kyb-registry) flow delivers one extra payload that is **not** a destination event: when you pass a `webhook_url` to the search request, Didit POSTs a `kyb.registry_search.resolved` callback to that URL once the registry resolves. It differs from destination webhooks in three ways:

* It is **unsigned** — no `X-Signature*` headers. Didit marks it with `X-Didit-Unsigned-Callback: true` instead; validate it by matching `request_id` against the id returned by the search request.
* The event name lives in `event_type` (not `webhook_type`), and there is no `application_id` or `environment`.
* `timestamp` and `created_at` are epoch integers, like other webhooks but unlike the search endpoint's ISO `created_at`.

```json theme={null}
{
  "event_id": "uuid",
  "event_type": "kyb.registry_search.resolved",
  "request_id": "uuid",
  "vendor_data": "business-123",
  "metadata": { "source": "onboarding" },
  "search_status": "resolved",
  "search_resolved": true,
  "kyb_registry": { "companies": ["..."], "pagination": { "...": "..." } },
  "timestamp": 1774970000,
  "created_at": 1774970000
}
```

The callback follows the same [retry policy](#retry-policy) as destination webhooks (retries re-stamp `timestamp` and stay unsigned). See the [KYB Registry API](/standalone-apis/kyb-registry) for the full candidate-list schema.

## Signature verification

Every webhook is signed with HMAC-SHA256 using the destination's `secret_shared_key`. Three signature headers are sent so you can pick the one that survives your stack:

| Header                                | What is signed                                                                              | Middleware-safe | When to use                                                                                                                                                |
| ------------------------------------- | ------------------------------------------------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-Signature-V2`                      | Sorted, Unicode-preserved compact JSON (`ensure_ascii=False`)                               | Yes             | **Recommended** — works even if your framework re-encodes the body.                                                                                        |
| `X-Signature`                         | Exact raw bytes of the request as Didit transmitted them (`sort_keys`, `ensure_ascii=True`) | No              | Only when you can read the raw body before any parser touches it.                                                                                          |
| `X-Signature-Simple` **(deprecated)** | `"{timestamp}:{session_id}:{status}:{webhook_type}"`                                        | Yes             | Last-resort fallback that authenticates the **envelope only** — it does **not** authenticate `decision`. See the deprecation notice below before using it. |

Headers Didit always sends:

| Header                                                  | Example                              | Meaning                                                                                       |
| ------------------------------------------------------- | ------------------------------------ | --------------------------------------------------------------------------------------------- |
| `Content-Type`                                          | `application/json`                   | Body is JSON.                                                                                 |
| `User-Agent`                                            | `DiditWebhook/2.0 +https://didit.me` | Identifies Didit's webhook worker.                                                            |
| `X-Timestamp`                                           | `1774970000`                         | Unix epoch seconds when the webhook was dispatched. Reject if `abs(now - X-Timestamp) > 300`. |
| `X-Signature` / `X-Signature-V2` / `X-Signature-Simple` | hex digests                          | HMAC-SHA256 of the body or canonical string above.                                            |

### `X-Signature-Simple` is deprecated

<Warning>
  **`X-Signature-Simple` authenticates the envelope, not the payload.** Its canonical string covers only `timestamp`, `session_id`, `status` and `webhook_type`. It does **not** cover `decision` — nor `resubmit_info`, `metadata`, `vendor_data` or `event_id`. A request whose `decision` has been rewritten while those four fields are left untouched still passes `X-Signature-Simple` verification.

  It is weaker still on the events that carry no `session_id` at all. Transaction events (`transaction_id`, `txn_id`, `amount`, `score`) and entity events (`vendor_user_id`, `vendor_business_id`) sign `"{timestamp}::{status}:{webhook_type}"`, which does not identify **which** transaction or entity the event is about — two different transactions reported with the same status in the same second carry the same `X-Signature-Simple`.

  If `X-Signature-Simple` is the only header you check, treat everything outside those four fields as **untrusted** and re-fetch the record from the API — [`GET /v3/session/{session_id}/decision/`](/sessions-api/retrieve-session) for a session, [`GET /v3/transactions/{transaction_id}/`](/management-api/transactions/get) for a transaction — which is the server of record.
</Warning>

This is a compatibility constraint, not something we can patch in place. The four-field canonical string is a wire contract: every receiver that verifies `X-Signature-Simple` recomputes exactly those four fields, so changing what the header signs would silently break all of them on the signature path. Covering the body also requires a specified canonical form of the JSON that both sides reproduce byte for byte, and Didit already ships one as `X-Signature-V2`. Rather than add a second body-covering variant with its own canonicalization rules, the header stays exactly as it is and is deprecated in favour of the existing full-payload variants.

What that means for you:

* **Nothing changes on the wire.** `X-Signature-Simple` keeps being sent on every delivery, computed the same way. Existing verifiers keep working, and we will announce any removal well in advance.
* **New integrations must use `X-Signature-V2`.** It is middleware-safe *and* covers the whole payload.
* **If you cannot move off `X-Signature-Simple`**, verify it, then fetch the record from the API rather than reading it out of the webhook body.

### Why three variants?

Some web frameworks (Express body parsers, Django middleware, API gateways) silently re-encode JSON before your handler reads it. If the original body contained `"José"` and your middleware rewrites it to `"José"`, the bytes change even though the data is identical. `X-Signature` then fails. `X-Signature-V2` is computed from a canonical JSON form (sort keys, compact separators, **unescaped Unicode**) that almost every middleware reproduces deterministically — and the deprecated `X-Signature-Simple` falls back to signing only a small, parser-independent string when even that fails. Because it signs only that short string and never the body, it cannot vouch for the body.

### Recommended verification order

1. Try **`X-Signature-V2`** first. Re-encode `JSON.parse(body)` with sorted keys and Unicode preserved, then `HMAC-SHA256(secret, canonical)` and `timingSafeEqual` against the header.
2. If V2 fails and you can read raw bytes, try **`X-Signature`** against `HMAC-SHA256(secret, rawBody)`.
3. Only if both fail, fall back to the deprecated **`X-Signature-Simple`** against `HMAC-SHA256(secret, "{timestamp}:{session_id}:{status}:{webhook_type}")`. This authenticates the envelope alone: treat the `decision` in the body as untrusted and re-fetch it from [`GET /v3/session/{session_id}/decision/`](/sessions-api/retrieve-session) before you act on it.

In all cases, **reject** any request older than **5 minutes** (`abs(now - X-Timestamp) > 300`) to defend against replays.

## Retry policy

If your endpoint responds with a `5xx` or `404`, Didit retries up to **2 times** with exponential backoff:

* **1st retry** — about **1 minute** after the initial failure.
* **2nd retry** — about **4 minutes** after the 1st retry.

After the second retry the delivery is dropped. Each delivery attempt (initial + retries) is logged as a separate entry in the Business Console under the destination's **Deliveries** tab, so you can replay or inspect any attempt.

Other delivery rules to know:

* The outbound HTTP request times out after **5 seconds**.
* Didit blocks deliveries to private / localhost URLs as an SSRF guard and never follows redirects. Use a public HTTPS endpoint that answers directly.
* A destination `url` containing a raw backslash, a control character, or more than one `@` in the authority is rejected as malformed - such a URL cannot be created and an existing one cannot be redelivered or replayed. Use a plain `https://host/path` URL with at most one userinfo section (for basic-auth style webhook URLs).
* `2xx` is treated as success. Timeouts and connection failures count as retryable (they surface as `504`/`503` in the delivery log); `3xx` and `4xx` responses other than `404` are **not** retried.
* On retry Didit recomputes signatures with a fresh `X-Timestamp`, so the timestamp/signature pair always lines up.

## Setting up a destination

You can manage destinations from the **Business Console > API & Webhooks** or via the Management API.

<Steps>
  <Step title="Create the destination">
    Call [`POST /v3/webhook/destinations/`](/management-api/webhook/create-destination) (or click **Add destination** in the console) with a `label`, public `url`, `webhook_version` (`"v3"`), and a `subscribed_events` array containing every event family this endpoint should receive. At least one event is required and no wildcard exists.
  </Step>

  <Step title="Store the secret_shared_key">
    The create response returns the destination's `secret_shared_key`. **Store it now** — it is the only secret you will ever see for this destination, scoped to this destination, and is the input to all three HMAC-SHA256 signature variants.
  </Step>

  <Step title="Implement the endpoint">
    Expose a public HTTPS `POST` route, read the raw body, verify the signature (preferring `X-Signature-V2`), check the timestamp window, then dispatch on `webhook_type`. Return `2xx` as soon as you have queued the work — do heavy processing asynchronously.
  </Step>

  <Step title="Confirm receipts">
    Watch the **Deliveries** tab on the destination. Healthy webhooks return `200` within a second or two. `5xx`/`404` triggers Didit's retry policy; persistent failures are dropped after the second retry.
  </Step>

  <Step title="Iterate with Try Webhook">
    Use the [**Try Webhook**](#testing) console scenarios to drive your endpoint through approved, declined, in-review, KYB, entity, activity, and transaction payloads before flipping production traffic on.
  </Step>
</Steps>

<Frame>
  <img alt="Didit webhook testing feature in the Business Console" />
</Frame>

You can create as many destinations as you need. A common pattern is **one destination per consumer**: e.g. KYC events → your auth service, KYB events → your compliance ops service, transactions → your fraud queue. Each destination has its own secret, version, and subscription list, so a rotated secret or a bad deploy on one consumer does not affect the others.

## Code samples

To ensure the security of your webhook endpoint, verify the authenticity of incoming requests using the destination's `secret_shared_key`.

<Warning>
  **Use `X-Signature-V2`.** It is the variant most resilient to middleware re-encoding, and it fully authenticates the body (including `decision`).
</Warning>

### Node.js / Express (recommended: X-Signature-V2)

```javascript theme={null}
const express = require("express");
const crypto = require("crypto");

const app = express();
const PORT = process.env.PORT || 1337;

// Per-destination secret from POST /v3/webhook/destinations/
const WEBHOOK_SECRET_KEY = process.env.WEBHOOK_SECRET_KEY || "YOUR_WEBHOOK_SECRET_KEY";

app.use(express.json());

/**
 * Match Didit's float normalisation: whole-valued floats are serialised as ints.
 */
function shortenFloats(data) {
  if (Array.isArray(data)) return data.map(shortenFloats);
  if (data !== null && typeof data === "object") {
    return Object.fromEntries(
      Object.entries(data).map(([key, value]) => [key, shortenFloats(value)])
    );
  }
  if (typeof data === "number" && !Number.isInteger(data) && data % 1 === 0) {
    return Math.trunc(data);
  }
  return data;
}

/** Sort object keys recursively before re-stringifying. */
function sortKeys(obj) {
  if (Array.isArray(obj)) return obj.map(sortKeys);
  if (obj !== null && typeof obj === "object") {
    return Object.keys(obj).sort().reduce((acc, key) => {
      acc[key] = sortKeys(obj[key]);
      return acc;
    }, {});
  }
  return obj;
}

function verifySignatureV2(jsonBody, signatureHeader, timestampHeader, secret) {
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestampHeader, 10)) > 300) return false;

  // Reproduce Didit's canonical JSON: sorted keys, compact, Unicode preserved.
  const canonical = JSON.stringify(sortKeys(shortenFloats(jsonBody)));
  const expected = crypto.createHmac("sha256", secret).update(canonical, "utf8").digest("hex");

  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(signatureHeader, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

function verifySignatureSimple(jsonBody, signatureHeader, timestampHeader, secret) {
  const now = Math.floor(Date.now() / 1000);
  if (Math.abs(now - parseInt(timestampHeader, 10)) > 300) return false;

  const canonical = [
    jsonBody.timestamp ?? "",
    jsonBody.session_id ?? "",
    jsonBody.status ?? "",
    jsonBody.webhook_type ?? "",
  ].join(":");
  const expected = crypto.createHmac("sha256", secret).update(canonical).digest("hex");

  const a = Buffer.from(expected, "utf8");
  const b = Buffer.from(signatureHeader, "utf8");
  return a.length === b.length && crypto.timingSafeEqual(a, b);
}

app.post("/webhook", (req, res) => {
  const signatureV2 = req.get("X-Signature-V2");
  const signatureSimple = req.get("X-Signature-Simple");
  const timestamp = req.get("X-Timestamp");
  const body = req.body;

  if (!timestamp || !WEBHOOK_SECRET_KEY) {
    return res.status(401).json({ message: "Missing required headers" });
  }

  let verified = false;
  if (signatureV2 && verifySignatureV2(body, signatureV2, timestamp, WEBHOOK_SECRET_KEY)) {
    verified = true;
  } else if (signatureSimple && verifySignatureSimple(body, signatureSimple, timestamp, WEBHOOK_SECRET_KEY)) {
    // Deprecated fallback: Simple authenticates the envelope only. Do not trust
    // body.decision here — re-fetch it from GET /v3/session/{session_id}/decision/.
    verified = true;
  }
  if (!verified) return res.status(401).json({ message: "Invalid signature" });

  // Dispatch by event type. Return 2xx fast; do heavy work asynchronously.
  switch (body.webhook_type) {
    case "status.updated":
    case "data.updated":
      // session or business session
      break;
    case "user.status.updated":
    case "user.data.updated":
    case "business.status.updated":
    case "business.data.updated":
      // consolidated entity event
      break;
    case "activity.created":
      // audit timeline event
      break;
    case "transaction.created":
    case "transaction.status.updated":
      // transaction monitoring event
      break;
    case "travel_rule.status.updated":
      // travel rule exchange status event
      break;
  }
  return res.status(200).json({ ok: true });
});

app.listen(PORT, () => console.log(`Server on http://localhost:${PORT}`));
```

If you can read the raw bytes before any parser touches them, the original `X-Signature` variant works the same way but signs the raw body. We keep it in the legacy section below for completeness.

### Python / FastAPI (recommended: X-Signature-V2)

```python theme={null}
from fastapi import FastAPI, Request, HTTPException
from time import time
import json
import hmac
import hashlib
import os

app = FastAPI()


def shorten_floats(data):
    """Match Didit: whole-valued floats serialise as ints."""
    if isinstance(data, dict):
        return {k: shorten_floats(v) for k, v in data.items()}
    if isinstance(data, list):
        return [shorten_floats(x) for x in data]
    if isinstance(data, float) and data.is_integer():
        return int(data)
    return data


def verify_signature_v2(body_json, signature_header, timestamp_header, secret):
    if abs(int(time()) - int(timestamp_header)) > 300:
        return False
    canonical = json.dumps(
        shorten_floats(body_json),
        sort_keys=True,
        separators=(",", ":"),
        ensure_ascii=False,   # unescaped Unicode -- matches Didit's V2 canonical form
    )
    expected = hmac.new(secret.encode("utf-8"), canonical.encode("utf-8"), hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature_header, expected)


def verify_signature_simple(body_json, signature_header, timestamp_header, secret):
    if abs(int(time()) - int(timestamp_header)) > 300:
        return False
    canonical = ":".join([
        str(body_json.get("timestamp", "")),
        str(body_json.get("session_id", "")),
        str(body_json.get("status", "")),
        str(body_json.get("webhook_type", "")),
    ])
    expected = hmac.new(secret.encode("utf-8"), canonical.encode("utf-8"), hashlib.sha256).hexdigest()
    return hmac.compare_digest(signature_header, expected)


@app.post("/webhook")
async def handle_webhook(request: Request):
    body = json.loads((await request.body()).decode("utf-8"))
    secret = os.environ["WEBHOOK_SECRET_KEY"]

    sig_v2 = request.headers.get("x-signature-v2")
    sig_simple = request.headers.get("x-signature-simple")
    ts = request.headers.get("x-timestamp")
    if not ts:
        raise HTTPException(status_code=401, detail="Missing X-Timestamp")

    if sig_v2 and verify_signature_v2(body, sig_v2, ts, secret):
        pass
    elif sig_simple and verify_signature_simple(body, sig_simple, ts, secret):
        # Deprecated fallback: Simple authenticates the envelope only. Do not trust
        # body["decision"] here - re-fetch it from GET /v3/session/{session_id}/decision/.
        pass
    else:
        raise HTTPException(status_code=401, detail="Invalid signature")

    # Dispatch on body["webhook_type"]; return 2xx fast.
    return {"ok": True}
```

### PHP / Laravel (recommended: X-Signature-V2)

PHP's JSON defaults do **not** reproduce the canonical form. Four of them have to be overridden, and missing any single one changes the signed bytes so the digest never matches:

| PHP default                                      | What it emits                       | What you need                                                      |
| ------------------------------------------------ | ----------------------------------- | ------------------------------------------------------------------ |
| `json_decode($raw, true)` (associative)          | empty objects `{}` collapse to `[]` | decode with `$associative = false` so JSON objects stay `stdClass` |
| `json_encode` escapes forward slashes            | `https:\/\/media.didit.me`          | `JSON_UNESCAPED_SLASHES`                                           |
| `json_encode` escapes non-ASCII                  | `Jos\u00e9` instead of `José`       | `JSON_UNESCAPED_UNICODE`                                           |
| `ksort` compares numeric-looking keys as numbers | `"9"` sorts before `"10"`           | `ksort($props, SORT_STRING)`                                       |

The empty-object trap is the one that bites hardest. Didit payloads routinely carry empty maps such as `risk_view.countries.risk_scores`, `risk_view.crimes.risk_scores`, and `risk_view.custom_list`, so an associative round-trip breaks the signature on ordinary approved sessions rather than on some rare edge case.

```php theme={null}
<?php

use Illuminate\Http\Request;

class WebhookController extends Controller
{
    /**
     * Rebuild Didit's canonical JSON form: recursively sorted keys, JSON
     * objects preserved as objects, arrays left in order.
     */
    private function canonicalize($value)
    {
        if ($value instanceof \stdClass) {
            $props = get_object_vars($value);
            ksort($props, SORT_STRING); // code-point order, like Python's sort_keys
            $sorted = new \stdClass();
            foreach ($props as $key => $item) {
                $sorted->{$key} = $this->canonicalize($item);
            }
            return $sorted;
        }
        if (is_array($value)) { // JSON arrays keep their order
            return array_map(function ($item) { return $this->canonicalize($item); }, $value);
        }
        return $value;
    }

    private function verifySignatureV2(string $rawBody, string $sig, string $ts, string $secret): bool
    {
        if (abs(time() - (int) $ts) > 300) return false;

        // Decode to objects, not associative arrays: associative decoding turns
        // empty JSON objects ({}) into empty arrays ([]), and json_encode then
        // writes them back as [] -- different bytes than Didit signed.
        $decoded = json_decode($rawBody, false);
        if (json_last_error() !== JSON_ERROR_NONE) return false;

        $canonical = json_encode(
            $this->canonicalize($decoded),
            JSON_UNESCAPED_SLASHES | JSON_UNESCAPED_UNICODE
        );
        return hash_equals(hash_hmac('sha256', $canonical, $secret), $sig);
    }

    /** X-Signature: HMAC over the exact bytes received -- never a re-serialised copy. */
    private function verifySignatureRaw(string $rawBody, string $sig, string $ts, string $secret): bool
    {
        if (abs(time() - (int) $ts) > 300) return false;
        return hash_equals(hash_hmac('sha256', $rawBody, $secret), $sig);
    }

    private function verifySignatureSimple(?array $body, string $sig, string $ts, string $secret): bool
    {
        if (abs(time() - (int) $ts) > 300) return false;
        $canonical = implode(':', [
            $body['timestamp'] ?? '',
            $body['session_id'] ?? '',
            $body['status'] ?? '',
            $body['webhook_type'] ?? '',
        ]);
        return hash_equals(hash_hmac('sha256', $canonical, $secret), $sig);
    }

    public function handle(Request $request)
    {
        $secret = env('WEBHOOK_SECRET_KEY');
        $ts = $request->header('x-timestamp');
        if (!$ts || !$secret) {
            return response()->json(['message' => 'Missing required headers'], 401);
        }

        // getContent() hands you the exact bytes Didit transmitted, before any parser runs.
        $rawBody = $request->getContent();
        $body = json_decode($rawBody, true); // associative copy, for dispatch only

        $sigV2 = $request->header('x-signature-v2');
        $sig = $request->header('x-signature');
        $sigSimple = $request->header('x-signature-simple');

        $verified = ($sigV2 && $this->verifySignatureV2($rawBody, $sigV2, $ts, $secret))
            || ($sig && $this->verifySignatureRaw($rawBody, $sig, $ts, $secret))
            // Deprecated fallback: Simple authenticates the envelope only. Do not trust
            // the decision body here - re-fetch it from GET /v3/session/{session_id}/decision/.
            || ($sigSimple && $this->verifySignatureSimple($body, $sigSimple, $ts, $secret));
        if (!$verified) {
            return response()->json(['message' => 'Invalid signature'], 401);
        }

        // Dispatch on $body['webhook_type']; return 2xx fast.
        return response()->json(['ok' => true]);
    }
}
```

Two more things worth knowing:

* **Whole-valued floats need no special handling in PHP.** Didit serialises them as integers (`100.0` → `100`), and PHP's `json_encode` writes a whole float the same way, so no `shortenFloats` step is required, unlike the Node.js sample above.
* **Keep `serialize_precision` at `-1`** (the default since PHP 7.1). If your host overrides it to `17`, `json_encode` writes `87.42` as `87.420000000000002` and every `X-Signature-V2` check fails.

If you cannot get the canonical form to match, `verifySignatureRaw` above is the simpler fallback: Laravel's `$request->getContent()` returns the untouched bytes, so `X-Signature` works as long as nothing in front of PHP re-encodes the body. That is exactly the case `X-Signature-V2` is designed to survive, which is why V2 is tried first.

## Testing

You do **not** need to run a full verification to exercise your endpoint.

* From **Business Console > API & Webhooks > Try Webhook**, pick a scenario (e.g. `approved_full_features`, `declined_face_mismatch`, `in_review_aml_hit`, `business_session_approved`, `transaction_created`, `activity_created`, `user_status_updated`) and send a fully-formed webhook to your destination URL.
* Every scenario is signed with the same three signature headers and canonical encoding as production traffic, including unicode test data (`approved_kyc_with_unicode`) so you can confirm `X-Signature-V2` works through your middleware. Test deliveries carry sample data and are marked with an extra `X-Didit-Test-Webhook: true` header (and a `(Test)` suffix on the `User-Agent`) so you can keep them out of production state.
* Replay any historic delivery from a destination's **Deliveries** tab if you need to debug a regression.

For end-to-end smoke tests, run a real verification through a test workflow in your own application — the resulting webhooks use the same envelope, headers, and retry policy as the **Try Webhook** scenarios.

## Examples

### Approved KYC session (`status.updated`)

```json theme={null}
{
  "event_id": "9c0c8b8a-1111-4222-9333-444444444444",
  "webhook_type": "status.updated",
  "timestamp": 1774970000,
  "created_at": 1774969994,
  "application_id": "11111111-2222-3333-4444-555555555555",
  "environment": "live",
  "sandbox_scenario": null,
  "session_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "status": "Approved",
  "workflow_id": "66666666-7777-8888-9999-000000000000",
  "workflow_version": 4,
  "vendor_data": "user_42",
  "metadata": { "tier": "premium" },
  "decision": {
    "session_id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "session_number": 43762,
    "status": "Approved",
    "workflow_id": "66666666-7777-8888-9999-000000000000",
    "features": ["ID_VERIFICATION", "LIVENESS", "FACE_MATCH", "AML"],
    "vendor_data": "user_42",
    "id_verifications": [
      {
        "node_id": "id_verification_1",
        "status": "Approved",
        "document_type": "Identity Card",
        "document_number": "SAMPLE-DOC-12345",
        "first_name": "Jane",
        "last_name": "Doe",
        "date_of_birth": "1990-01-01",
        "issuing_state": "ESP",
        "verification_method": "document",
        "assurance": "documentary",
        "wallet_provider": null,
        "fallback_from": null,
        "id_lookup": null,
        "wallet_verification": null,
        "warnings": []
      }
    ],
    "liveness_checks": [
      { "node_id": "liveness_1", "status": "Approved", "method": "ACTIVE_3D", "score": 95.4, "warnings": [] }
    ],
    "face_matches": [
      { "node_id": "face_match_1", "status": "Approved", "score": 96.1, "warnings": [] }
    ],
    "aml_screenings": [
      { "node_id": "aml_1", "status": "Approved", "total_hits": 0, "entity_type": "person", "hits": [], "warnings": [] }
    ],
    "reviews": [],
    "created_at": "2026-05-17T08:54:25.443172Z"
  }
}
```

### Declined session with warnings (`status.updated`)

```json theme={null}
{
  "event_id": "9c0c8b8a-1111-4222-9333-555555555555",
  "webhook_type": "status.updated",
  "timestamp": 1774970000,
  "created_at": 1774969994,
  "application_id": "11111111-2222-3333-4444-555555555555",
  "environment": "live",
  "sandbox_scenario": null,
  "session_id": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff",
  "status": "Declined",
  "vendor_data": "user_99",
  "decision": {
    "session_id": "bbbbbbbb-cccc-dddd-eeee-ffffffffffff",
    "status": "Declined",
    "features": ["ID_VERIFICATION", "LIVENESS", "FACE_MATCH"],
    "id_verifications": [
      {
        "node_id": "id_verification_1",
        "status": "Declined",
        "document_type": "Passport",
        "expiration_date": "2024-01-01",
        "warnings": [
          {
            "feature": "ID_VERIFICATION",
            "risk": "DOCUMENT_EXPIRED",
            "additional_data": null,
            "log_type": "error",
            "short_description": "Document expired",
            "long_description": "The document's expiration date has passed, rendering it no longer valid for use.",
            "node_id": "id_verification_1"
          }
        ]
      }
    ],
    "liveness_checks": [{ "node_id": "liveness_1", "status": "Approved", "score": 92.0, "warnings": [] }],
    "face_matches": [
      {
        "node_id": "face_match_1",
        "status": "Declined",
        "score": 32.0,
        "warnings": [
          {
            "feature": "FACEMATCH",
            "risk": "LOW_FACE_MATCH_SIMILARITY",
            "additional_data": null,
            "log_type": "error",
            "short_description": "Low face match similarity",
            "long_description": "The facial features of the provided image don't closely match the reference image, suggesting a potential identity mismatch.",
            "node_id": "face_match_1"
          }
        ]
      }
    ],
    "reviews": []
  }
}
```

### Business session approved (`status.updated`, KYB)

```json theme={null}
{
  "event_id": "uuid",
  "webhook_type": "status.updated",
  "timestamp": 1774970000,
  "created_at": 1774969994,
  "application_id": "uuid",
  "environment": "live",
  "sandbox_scenario": null,
  "session_id": "kyb-uuid",
  "business_session_id": "kyb-uuid",
  "session_kind": "business",
  "status": "Approved",
  "vendor_data": "biz_7",
  "vendor_business_id": "acme-inc",
  "decision": {
    "session_id": "kyb-uuid",
    "session_kind": "business",
    "status": "Approved",
    "features": ["REGISTRY_CHECK", "AML", "DOCUMENT_VERIFICATION"],
    "registry_checks": [{ "node_id": "registry_1", "status": "Approved", "company_name": "Acme Corp", "...": "..." }],
    "aml_screenings": [{ "node_id": "aml_1", "status": "Approved", "entity_type": "company", "total_hits": 0, "hits": [] }],
    "document_verifications": [{ "node_id": "doc_1", "status": "Approved", "document_type": "certificate_of_incorporation" }],
    "key_people_checks": [],
    "reviews": []
  }
}
```

### Transaction created (`transaction.created`)

```json theme={null}
{
  "event_id": "uuid",
  "webhook_type": "transaction.created",
  "timestamp": 1774970000,
  "created_at": 1774970000,
  "application_id": "uuid",
  "environment": "live",
  "transaction_id": "uuid",
  "txn_id": "finance0001",
  "status": "APPROVED",
  "score": 0,
  "severity": "UNKNOWN",
  "amount": "1200.00",
  "currency": "EUR",
  "direction": "OUTBOUND"
}
```

### Travel Rule exchange status changed (`travel_rule.status.updated`)

```json theme={null}
{
  "event_id": "9c0c8b8a-1111-4222-9333-666666666666",
  "webhook_type": "travel_rule.status.updated",
  "timestamp": 1774970000,
  "created_at": 1774970000,
  "application_id": "11111111-2222-3333-4444-555555555555",
  "environment": "live",
  "transaction_id": "22222222-3333-4444-5555-666666666666",
  "txn_id": "trv-2026-07-05-001",
  "travel_rule_status": "COMPLETED",
  "rail": "INTERNAL",
  "direction": "OUTBOUND"
}
```

`travel_rule_status` carries one of the 13 exchange statuses documented in [Travel Rule](/transaction-monitoring/travel-rule#lifecycle).
`rail` is `INTERNAL`, `TRP`, or `EMAIL` (empty string if no rail could be resolved), and `direction` is `INBOUND` or `OUTBOUND`.

An [after-deposit sunrise registration](/transaction-monitoring/travel-rule#after-deposit-sunrise-registration) that mints a new inbound transaction also emits a `transaction.created` event for that transaction, before the `travel_rule.status.updated` transitions.

### User entity status changed (`user.status.updated`)

```json theme={null}
{
  "event_id": "uuid",
  "webhook_type": "user.status.updated",
  "timestamp": 1774970000,
  "created_at": 1774969980,
  "application_id": "uuid",
  "environment": "live",
  "vendor_user_id": "uuid",
  "vendor_data": "user_42",
  "status": "BLOCKED",
  "previous_status": "ACTIVE"
}
```

### Resubmitted session

```json theme={null}
{
  "event_id": "uuid",
  "webhook_type": "status.updated",
  "timestamp": 1774970000,
  "created_at": 1774969980,
  "application_id": "uuid",
  "environment": "live",
  "sandbox_scenario": null,
  "session_id": "uuid",
  "status": "Resubmitted",
  "vendor_data": "user_42",
  "resubmit_info": {
    "nodes_to_resubmit": [
      { "node_id": "feature_poa", "feature": "PROOF_OF_ADDRESS" }
    ],
    "reasons": { "feature_poa": "Poor document quality" }
  }
}
```

## Legacy: X-Signature with raw body

`X-Signature` is still sent on every delivery; it is HMAC-SHA256 over the **exact bytes** Didit transmits (`json.dumps(..., sort_keys=True, separators=(",", ":"))`). Use it only when you can read the raw body before any middleware modifies it.

<Tabs>
  <Tab title="Node.js">
    ```javascript theme={null}
    const express = require("express");
    const bodyParser = require("body-parser");
    const crypto = require("crypto");

    const app = express();
    const PORT = process.env.PORT || 1337;
    const WEBHOOK_SECRET_KEY = process.env.WEBHOOK_SECRET_KEY || "YOUR_WEBHOOK_SECRET_KEY";

    app.use(bodyParser.json({
      verify: (req, _res, buf, encoding) => {
        if (buf && buf.length) req.rawBody = buf.toString(encoding || "utf8");
      },
    }));

    app.post("/webhook", (req, res) => {
      const signature = req.get("X-Signature");
      const timestamp = req.get("X-Timestamp");
      if (!signature || !timestamp || !req.rawBody) return res.status(401).end();

      if (Math.abs(Math.floor(Date.now() / 1000) - parseInt(timestamp, 10)) > 300) {
        return res.status(401).json({ message: "Stale timestamp" });
      }

      const expected = crypto.createHmac("sha256", WEBHOOK_SECRET_KEY).update(req.rawBody).digest("hex");
      const a = Buffer.from(expected, "utf8");
      const b = Buffer.from(signature, "utf8");
      if (a.length !== b.length || !crypto.timingSafeEqual(a, b)) {
        return res.status(401).json({ message: "Invalid signature" });
      }

      const event = JSON.parse(req.rawBody);
      // Handle event.webhook_type ...
      return res.json({ ok: true });
    });

    app.listen(PORT);
    ```
  </Tab>

  <Tab title="Python">
    ```python theme={null}
    from fastapi import FastAPI, Request, HTTPException
    from time import time
    import hmac
    import hashlib
    import os

    app = FastAPI()


    def verify_raw(body: str, signature: str, timestamp: str, secret: str) -> bool:
        if abs(int(time()) - int(timestamp)) > 300:
            return False
        expected = hmac.new(secret.encode("utf-8"), body.encode("utf-8"), hashlib.sha256).hexdigest()
        return hmac.compare_digest(signature, expected)


    @app.post("/webhook")
    async def handle(request: Request):
        body = (await request.body()).decode("utf-8")
        sig = request.headers.get("x-signature")
        ts = request.headers.get("x-timestamp")
        secret = os.environ["WEBHOOK_SECRET_KEY"]

        if not sig or not ts or not verify_raw(body, sig, ts, secret):
            raise HTTPException(status_code=401, detail="Unauthorized")
        return {"ok": True}
    ```
  </Tab>
</Tabs>

## Legacy: V2 webhook format

<Warning>
  The fields below only apply when a destination is pinned to `webhook_version: "v2"`. An even older `"v1"` pin also exists (a third, singular decision shape) for destinations created before V2 — contact support before relying on it. New integrations should use **V3** (the default), which is documented above and uses plural arrays.
</Warning>

| Aspect                     | V2                                                                                                                                                          | V3                                                                         |
| -------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------- |
| Signature headers          | `X-Signature`, `X-Signature-V2`, `X-Signature-Simple` (all three are sent regardless of version; Simple is [deprecated](#x-signature-simple-is-deprecated)) | Same                                                                       |
| Decision field names       | Singular objects (`id_verification`, `liveness`, `face_match`, ...)                                                                                         | Plural arrays (`id_verifications`, `liveness_checks`, `face_matches`, ...) |
| Multiple feature instances | Not supported                                                                                                                                               | Supported via per-feature arrays with `node_id`                            |

If a downstream consumer still needs V2 shapes, create a separate destination pinned to `webhook_version: "v2"` and keep your new consumers on V3.

## Related

* [Webhook destinations API](/management-api/webhook/list-destinations) — list, create, update, delete destinations and inspect delivery logs.
* [Create webhook destination](/management-api/webhook/create-destination) — request/response schema including the once-returned `secret_shared_key`.
* [Data models](/reference/data-models) — canonical schema for every per-feature object embedded in `decision`.
* [Decision schema](/sessions-api/retrieve-session) — full field list for the `decision` object embedded in session webhooks.
* [Verification statuses](/integration/verification-statuses) — exact `status` values and transitions referenced above.
* [Rate limiting](/integration/rate-limiting) — limits that apply when polling `GET /v3/session/{id}/decision/` as a fallback.


# Get Credit Balance
Source: https://docs.didit.me/management-api/billing/balance

GET /v3/billing/balance/
Get current pre-paid credit balance in USD (organization-wide) plus auto-refill config. Amounts are decimal strings — parse with a decimal library.

<AgentPromptAccordion title="Get Credit Balance Prompt" />


# Top Up Credits
Source: https://docs.didit.me/management-api/billing/top-up

POST /v3/billing/top-up/
Add credits via a hosted Stripe Checkout session (**$50 minimum**); not available on annual plans. Redirect the customer to the returned `checkout_session_url`.

<AgentPromptAccordion title="Top Up Credits Prompt" />


# Bulk Purge Biometric Templates
Source: https://docs.didit.me/management-api/biometric-templates/batch-purge

POST /v3/biometric-templates/delete/
POST /v3/biometric-templates/delete/ — purge retained face biometric templates by id list, or every template matching a filter. Idempotent per template.

Purges many templates in one call. Provide either an explicit id list or `delete_all: true`, optionally narrowed by the same filters as [List Biometric Templates](/management-api/biometric-templates/list).

## Request body

| Field                          | Type     | Description                                                                                                                                                  |
| ------------------------------ | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `template_uuids`               | UUID\[]  | Templates to purge. Required unless `delete_all` is `true`. Ids that are already purged are reported as `already_purged`.                                    |
| `delete_all`                   | boolean  | When `true`, purges every template that matches the filters below (all of the application's templates when no filter is given). `template_uuids` is ignored. |
| `vendor_data`                  | string   | Only with `delete_all`: case-insensitive substring match on the owning User's `vendor_data`                                                                  |
| `vendor_user_uuid`             | UUID     | Only with `delete_all`: exact match on the owning User                                                                                                       |
| `status`                       | enum     | Only with `delete_all`: `pending`, `active`, `expired`, `held_out_of_use`, `purge_pending`, `purge_failed`                                                   |
| `source_type`                  | enum     | Only with `delete_all`: `session_delete`, `automatic_retention`, `backfill`                                                                                  |
| `retained_from`, `retained_to` | datetime | Only with `delete_all`: retained-date range                                                                                                                  |

<Warning>
  `delete_all: true` without filters purges every biometric template in the application and cannot be undone. Run [Count Biometric Templates](/management-api/biometric-templates/count) with the same filters first to confirm what will be purged.
</Warning>

## Examples

<Tabs>
  <Tab title="By id">
    ```bash theme={null}
    curl -X POST https://verification.didit.me/v3/biometric-templates/delete/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"template_uuids": ["9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d"]}'
    ```
  </Tab>

  <Tab title="Every template of one User">
    ```bash theme={null}
    curl -X POST https://verification.didit.me/v3/biometric-templates/delete/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"delete_all": true, "vendor_user_uuid": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f"}'
    ```
  </Tab>

  <Tab title="Every template in the application">
    ```bash theme={null}
    curl -X POST https://verification.didit.me/v3/biometric-templates/delete/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"delete_all": true}'
    ```
  </Tab>
</Tabs>

```json theme={null}
{
  "results": [
    { "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "outcome": "purged" },
    { "uuid": "1a2b3c4d-5e6f-4a7b-8c9d-0e1f2a3b4c5d", "outcome": "already_purged" }
  ]
}
```

Templates are purged one by one; each result reports `purged` or `already_purged`. If a biometric store is unavailable the call returns `503` at the first failing template; templates purged earlier in the same request stay purged, the failing one moves to `purge_failed` (already excluded from matching), and repeating the request finishes the job.

## Errors

| Status | When                                                                | Body                                                                                                                                    |
| ------ | ------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Neither `template_uuids` nor `delete_all: true` provided            | `{"template_uuids": ["This field is required unless delete_all is true."]}`                                                             |
| `400`  | Invalid filter value, or `retained_to` earlier than `retained_from` | Field-keyed validation errors                                                                                                           |
| `403`  | Console user token, or the API key is not allowed                   | `{"detail": "You do not have permission to perform this action."}`                                                                      |
| `503`  | A biometric store was unavailable; repeat the request               | `{"detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable."}` |


# Count Biometric Templates
Source: https://docs.didit.me/management-api/biometric-templates/count

GET /v3/biometric-templates/count/
GET /v3/biometric-templates/count/ — count the image-free face biometric templates your application retains, using the same filters as the list endpoint.

Returns the number of templates that match the same filters as [List Biometric Templates](/management-api/biometric-templates/list). Purged templates are not counted.

```bash theme={null}
curl -X GET "https://verification.didit.me/v3/biometric-templates/count/?status=active" \
  -H "x-api-key: YOUR_API_KEY"
```

```json theme={null}
{ "count": 128 }
```

Use it to show the total on a dashboard, or to check what a filtered [bulk purge](/management-api/biometric-templates/batch-purge) with `delete_all: true` would touch before you run it.


# Get Biometric Template
Source: https://docs.didit.me/management-api/biometric-templates/get

GET /v3/biometric-templates/{template_uuid}/
GET /v3/biometric-templates/{template_uuid}/ — retrieve one retained face biometric template with its owning User, provenance, expiry, and status.

Returns one template. Use the `biometric_template_uuid` returned by [Delete Session](/sessions-api/delete-session), the `biometric_template_id` on a [Face Search match](/core-technology/face-search/report-face-search), or an id from the [list](/management-api/biometric-templates/list).

```bash theme={null}
curl -X GET https://verification.didit.me/v3/biometric-templates/9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b/ \
  -H "x-api-key: YOUR_API_KEY"
```

```json theme={null}
{
  "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b",
  "vendor_user_uuid": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f",
  "vendor_data": "user-42",
  "source_type": "session_delete",
  "provenance_reference": "6b1e8d2f-4a3c-4f9e-8c7d-1a2b3c4d5e6f",
  "retention_policy": "retain_until_user_deleted",
  "retention_override": null,
  "retained_at": "2026-08-28T10:15:42.318402Z",
  "expires_at": "2027-08-28T10:15:42.318402Z",
  "retained_by": "3c9e2b1f-7d4a-4e8b-9c1d-5f6a7b8c9d0e",
  "retained_by_type": "API_KEY",
  "instruction_class": "operational_session_delete",
  "instruction_source": "api",
  "instruction_id": "post-approval-cleanup-2026-08",
  "held_out_of_use": false,
  "status": "active",
  "purged_at": null
}
```

The response never includes an image, a vector, the deleted session's id, or identity data. See the [overview](/management-api/biometric-templates/overview#template-object) for every field.

## Errors

| Status | When                                                                      | Body                                                               |
| ------ | ------------------------------------------------------------------------- | ------------------------------------------------------------------ |
| `403`  | Console user token, or the API key is not allowed                         | `{"detail": "You do not have permission to perform this action."}` |
| `404`  | Unknown template, a template of another application, or a purged template | `{"detail": "Biometric template not found."}`                      |


# List Biometric Templates
Source: https://docs.didit.me/management-api/biometric-templates/list

GET /v3/biometric-templates/
GET /v3/biometric-templates/ — paginated list of the image-free face biometric templates your application retains, filtered by user, status, source, and date.

Returns a paginated list of the biometric templates your application currently holds. Purged templates are not listed.

## Query parameters

| Parameter          | Type     | Description                                                                          |
| ------------------ | -------- | ------------------------------------------------------------------------------------ |
| `vendor_data`      | string   | Case-insensitive substring match on the owning User's current `vendor_data`          |
| `vendor_user_uuid` | UUID     | Exact match on the owning User                                                       |
| `status`           | enum     | `pending`, `active`, `expired`, `held_out_of_use`, `purge_pending`, `purge_failed`   |
| `source_type`      | enum     | `session_delete`, `automatic_retention`, `backfill`                                  |
| `retained_from`    | datetime | Templates retained at or after this time                                             |
| `retained_to`      | datetime | Templates retained at or before this time. Must not be earlier than `retained_from`. |
| `ordering`         | enum     | `retained_at`, `-retained_at` (default), `expires_at`, `-expires_at`                 |
| `limit`            | integer  | Page size                                                                            |
| `offset`           | integer  | Pagination offset                                                                    |

## Example

```bash theme={null}
curl -X GET "https://verification.didit.me/v3/biometric-templates/?vendor_data=user-42&status=active" \
  -H "x-api-key: YOUR_API_KEY"
```

```json theme={null}
{
  "count": 1,
  "next": null,
  "previous": null,
  "results": [
    {
      "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b",
      "vendor_user_uuid": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f",
      "vendor_data": "user-42",
      "source_type": "session_delete",
      "provenance_reference": "6b1e8d2f-4a3c-4f9e-8c7d-1a2b3c4d5e6f",
      "retention_policy": "retain_until_user_deleted",
      "retention_override": null,
      "retained_at": "2026-08-28T10:15:42.318402Z",
      "expires_at": "2027-08-28T10:15:42.318402Z",
      "retained_by": "3c9e2b1f-7d4a-4e8b-9c1d-5f6a7b8c9d0e",
      "retained_by_type": "API_KEY",
      "instruction_class": "operational_session_delete",
      "instruction_source": "api",
      "instruction_id": "post-approval-cleanup-2026-08",
      "held_out_of_use": false,
      "status": "active",
      "purged_at": null
    }
  ]
}
```

See the [overview](/management-api/biometric-templates/overview#template-object) for every field.

## Errors

| Status | When                                                                |
| ------ | ------------------------------------------------------------------- |
| `400`  | Invalid filter value, or `retained_to` earlier than `retained_from` |
| `403`  | Console user token, or the API key is not allowed                   |


# Biometric Templates
Source: https://docs.didit.me/management-api/biometric-templates/overview

Manage the image-free face biometric templates your application retains after session deletion: list, count, filter, inspect, and purge them via the API.

<AgentPromptAccordion title="Biometric Templates API Prompt" />

By default, deleting a verification session also deletes the face embedding that powered [Face Search 1:N](/core-technology/face-search/overview) and duplicate detection for that session. Applications that need duplicate detection to keep working after session deletion can opt in to **biometric-template retention**. Didit then deletes the session and all of its data as usual and keeps one separately managed, image-free face biometric template anchored to the session's [User](/entities/users/overview).

The Biometric Templates API lets you see exactly which templates your application holds, why, until when, and purge them at any time. Every template is also visible in the Business Console under **Lists → Biometric templates** and on the owning User's profile.

<Warning>
  A retained biometric template is biometric data. It is not anonymous, it is not transient, and it is not deleted with the session. It stays until its scheduled expiry, an earlier applicable-law deadline, User deletion, a privacy-erasure request, or an explicit purge. Enable retention only when your controller instruction and privacy notice cover it.
</Warning>

## How a template is created

| Trigger                                                                                                                                                                                                     | `source_type`         | Where the instruction comes from          |
| ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------- | ----------------------------------------- |
| You delete a session on an opted-in application, or send `retain_face_embeddings: true` on [Delete Session](/sessions-api/delete-session) or [Batch Delete Sessions](/management-api/sessions/batch-delete) | `session_delete`      | `instruction_source: api` or `console`    |
| Your application's general [data-retention window](/console/data-retention) expires a session on an opted-in application                                                                                    | `automatic_retention` | `instruction_source: automatic_retention` |
| A Didit-operated backfill you instructed for sessions deleted before you opted in                                                                                                                           | `backfill`            | `instruction_source: backfill`            |

Retention requires a User anchor. A session created without `vendor_data` has no User, so it cannot retain a template; the deletion reports `ineligible_no_vendor_user` and the embedding is deleted with the session.

## What a template contains

| Retained                                                                                                                                                              | Never retained                                                                             |
| --------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| The numeric face template used for matching                                                                                                                           | The face image, liveness video, document images, portrait crops, and any other media       |
| A new random template `uuid` and an opaque `provenance_reference`                                                                                                     | The deleted session's id, number, decision, extracted identity fields, or feature payloads |
| The owning User (`vendor_user_uuid`); `vendor_data` is resolved from the User when you read the template, never copied                                                | Blocklist state, prior matches, fraud labels, or cross-organization identity claims        |
| `retained_at`, `expires_at`, `retention_policy`, `retention_override`, `instruction_class`, `instruction_source`, `instruction_id`, `retained_by`, `retained_by_type` | Actor email addresses                                                                      |

Templates are tenant-scoped and used only on your instruction inside your application: duplicate-face and multi-account detection, [Biometric Authentication](/core-technology/biometric-auth/overview), and your own face lists. They are never used for model training, analytics, cross-organization matching, [Networks](/console/networks) shared signals, or Didit's independent fraud processing.

## Template object

```json theme={null}
{
  "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b",
  "vendor_user_uuid": "2f7c1a9e-8b4d-4c6a-9e1f-3d5b7a9c1e2f",
  "vendor_data": "user-42",
  "source_type": "session_delete",
  "provenance_reference": "6b1e8d2f-4a3c-4f9e-8c7d-1a2b3c4d5e6f",
  "retention_policy": "retain_until_user_deleted",
  "retention_override": null,
  "retained_at": "2026-08-28T10:15:42.318402Z",
  "expires_at": "2027-08-28T10:15:42.318402Z",
  "retained_by": "3c9e2b1f-7d4a-4e8b-9c1d-5f6a7b8c9d0e",
  "retained_by_type": "API_KEY",
  "instruction_class": "operational_session_delete",
  "instruction_source": "api",
  "instruction_id": "post-approval-cleanup-2026-08",
  "held_out_of_use": false,
  "status": "active",
  "purged_at": null
}
```

| Field                  | Type             | Description                                                                                                                                                                                  |
| ---------------------- | ---------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                 | UUID             | Template id. Randomly generated; not derived from the deleted session or its face.                                                                                                           |
| `vendor_user_uuid`     | UUID             | The owning User.                                                                                                                                                                             |
| `vendor_data`          | string or null   | The User's current `vendor_data`, resolved when you read the template.                                                                                                                       |
| `source_type`          | enum             | `session_delete`, `automatic_retention`, or `backfill`.                                                                                                                                      |
| `provenance_reference` | UUID             | Opaque reference that ties the template to its audit trail. It is not the deleted session's id and cannot be resolved to it through the API.                                                 |
| `retention_policy`     | enum             | The application policy at retention time: `delete_with_session` or `retain_until_user_deleted`.                                                                                              |
| `retention_override`   | boolean or null  | The `retain_face_embeddings` value sent on the deletion, or `null` when the policy applied.                                                                                                  |
| `retained_at`          | datetime         | When the template was created.                                                                                                                                                               |
| `expires_at`           | datetime         | When the template expires and is purged automatically. Always set.                                                                                                                           |
| `retained_by`          | string           | Principal that gave the instruction: the application id for API keys, the Console member id for Console actions, or a `service:` identifier for automatic retention. Never an email address. |
| `retained_by_type`     | enum             | `API_KEY`, `CONSOLE_USER`, or `SYSTEM`.                                                                                                                                                      |
| `instruction_class`    | enum             | `operational_session_delete` or `privacy_erasure`.                                                                                                                                           |
| `instruction_source`   | enum             | `api`, `console`, `automatic_retention`, `backfill`, `privacy_erasure`, `explicit_template_purge`, `vendor_user_delete`, `expiry`, `reconciliation`, `migration`, or `system`.               |
| `instruction_id`       | string           | The `instruction_id` you sent on the deletion, or a Didit-generated id when you omitted it.                                                                                                  |
| `held_out_of_use`      | boolean          | `true` only while a legal hold applies. A held template is excluded from all matching. See [Legal holds](#legal-holds).                                                                      |
| `status`               | enum             | Lifecycle status, see below.                                                                                                                                                                 |
| `purged_at`            | datetime or null | When the template was purged.                                                                                                                                                                |

### Status

| `status`          | Meaning                                                                                                                                          | In matching?                                                       |
| ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------ |
| `pending`         | The template is being created. If the deletion that created it returned `503`, repeat the deletion to finish it.                                 | No                                                                 |
| `active`          | The template takes part in matching until `expires_at`.                                                                                          | Yes, unless `held_out_of_use` is `true` or `expires_at` has passed |
| `expired`         | `expires_at` has passed and the automatic purge is in progress.                                                                                  | No                                                                 |
| `held_out_of_use` | A legal hold applies.                                                                                                                            | No                                                                 |
| `purge_pending`   | A purge is in progress.                                                                                                                          | No                                                                 |
| `purge_failed`    | A purge could not finish because a biometric store was unavailable. Repeat the purge; the template stays excluded from matching in the meantime. | No                                                                 |
| `purged`          | The template is deleted. Only visible on the purge response as `already_purged`; purged templates are not listed and return `404` on detail.     | No                                                                 |

## How templates are used in matching

An `active` template takes part in exactly the same matching as a live session face: automatic duplicate detection during new sessions, the standalone [Face Search API](/standalone-apis/face-search), [Biometric Authentication](/core-technology/biometric-auth/overview), and your face lists. A hit on a retained template is reported with `source: "retained_template"`, the owning User's `vendor_user_id` and `vendor_data`, and the `biometric_template_id`. It never carries a session id, a match image, identity details, or a status, because the session that produced the face no longer exists. See [Face Search report](/core-technology/face-search/report-face-search).

A retained template is never blocklisted. If the deleted session's face was on a face blocklist, that blocklist entry keeps its own independent biometric entry and its own lifecycle: removing the list entry deletes the blocklist entry, and purging the template does not touch the list.

## Purge points

All of the following remove the template from matching and delete the stored template:

| Purge point     | How                                                                                                                                                                                                                                   |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Explicit purge  | [`DELETE /v3/biometric-templates/{uuid}/`](/management-api/biometric-templates/purge) or [`POST /v3/biometric-templates/delete/`](/management-api/biometric-templates/batch-purge), or **Lists → Biometric templates** in the Console |
| User deletion   | [`POST /v3/users/delete/`](/management-api/users/delete) purges every template anchored to the User before the User is deleted                                                                                                        |
| Privacy erasure | Any deletion of a session of that User sent with `deletion_instruction: "privacy_erasure"` purges every template anchored to the User, regardless of the application policy                                                           |
| Expiry          | Didit purges the template automatically once `expires_at` passes                                                                                                                                                                      |

Switching the application policy back to `delete_with_session` stops new templates from being created but does **not** purge existing ones. Purge them explicitly.

Purges delete the stored template first and only then mark the template purged, so a purge that returns `503` leaves the template in `purge_failed`, already excluded from matching, and safe to repeat. A repeated purge of an already purged template returns `already_purged`.

## Audit trail

Every retain and purge attempt, including failures and ineligible outcomes, is recorded with the acting principal (`retained_by` / purging principal and type), `instruction_class`, `instruction_source`, `instruction_id`, `provenance_reference`, and the outcome. Send your own `instruction_id` on deletions so you can correlate Didit's audit trail with your erasure log. Audit entries never contain images, vectors, identity fields, or email addresses.

## Legal holds

A legal hold is an exception, never a retention mode. Didit does not place holds on its own initiative; a hold can only follow a documented instruction under your Data Processing Agreement or a binding order from a competent authority. While a hold applies the template is marked `held_out_of_use`: it is excluded from every kind of matching and from routine recovery, and it is never searchable. There is no API to create or lift holds. Contact your Didit representative if you receive an order that affects retained templates.

## Permissions and authentication

The Biometric Templates endpoints accept application API keys only (`x-api-key`). Business Console user tokens are rejected with `403`. Console users manage templates through **Lists → Biometric templates** with their `lists` permissions.

## Endpoints

| Endpoint                                                                                | Method | Purpose                       |
| --------------------------------------------------------------------------------------- | ------ | ----------------------------- |
| [`/v3/biometric-templates/`](/management-api/biometric-templates/list)                  | GET    | Paginated list with filters   |
| [`/v3/biometric-templates/count/`](/management-api/biometric-templates/count)           | GET    | Count with the same filters   |
| [`/v3/biometric-templates/{template_uuid}/`](/management-api/biometric-templates/get)   | GET    | One template                  |
| [`/v3/biometric-templates/{template_uuid}/`](/management-api/biometric-templates/purge) | DELETE | Purge one template            |
| [`/v3/biometric-templates/delete/`](/management-api/biometric-templates/batch-purge)    | POST   | Purge by id list or by filter |

## Related

* [Delete Session](/sessions-api/delete-session)
* [Batch Delete Sessions](/management-api/sessions/batch-delete)
* [Data retention](/console/data-retention#biometric-template-retention)
* [Faces and biometrics](/entities/users/faces-and-biometrics)


# Purge Biometric Template
Source: https://docs.didit.me/management-api/biometric-templates/purge

DELETE /v3/biometric-templates/{template_uuid}/
DELETE /v3/biometric-templates/{template_uuid}/ — purge one retained face biometric template: removed from matching, stored template deleted. Idempotent.

Purges one template: it is removed from every kind of matching and the stored template is deleted. The purge is irreversible and is recorded on the audit trail with the acting principal.

```bash theme={null}
curl -X DELETE https://verification.didit.me/v3/biometric-templates/9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b/ \
  -H "x-api-key: YOUR_API_KEY"
```

```json theme={null}
{ "uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b", "outcome": "purged" }
```

| `outcome`        | Meaning                                                          |
| ---------------- | ---------------------------------------------------------------- |
| `purged`         | The template was purged by this call.                            |
| `already_purged` | The template had already been purged. Repeating a purge is safe. |

## Retry semantics

Didit deletes the stored template first and only then marks the template purged. If a biometric store is unavailable the call returns `503`, the template moves to `status: purge_failed`, and it is already excluded from matching. Repeat the same call to finish the purge.

## Errors

| Status | When                                                                                                              | Body                                                                                                                                    |
| ------ | ----------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `403`  | Console user token, or the API key is not allowed                                                                 | `{"detail": "You do not have permission to perform this action."}`                                                                      |
| `404`  | Unknown template or a template of another application                                                             | `{"detail": "Biometric template not found."}`                                                                                           |
| `503`  | A biometric store was unavailable. The template is in `purge_failed` and excluded from matching; repeat the call. | `{"detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable."}` |

## Other purge points

Templates are also purged when you delete the owning User with [Batch Delete Users](/management-api/users/delete), when you delete any session of that User with `deletion_instruction: "privacy_erasure"`, and automatically at `expires_at`. See [Purge points](/management-api/biometric-templates/overview#purge-points).


# Create Business
Source: https://docs.didit.me/management-api/businesses/create

POST /v3/businesses/create/
Pre-create a [business](/entities/businesses) *without* a KYB session. All fields are optional, but you should always send `vendor_data` — without it the record cannot be linked to sessions or transactions. When provided, `vendor_data` must be unique among non-deleted businesses (exact match; conflicts return 400). Not idempotent.

<AgentPromptAccordion title="Create Business Prompt" />

## Overview

Explicitly creates a [Business entity](/entities/businesses/overview) before any Business Verification (KYB) session runs.

## When to use it

* **Pre-seed metadata** (partner, tier, internal identifiers) before the first Business Verification (KYB) session.
* **Migrate** from another KYB vendor with an existing business roster.
* **Transaction-only** registration — submit transactions for a business that you verified through an offline process.

## Notes

* `vendor_data` is required and unique per application. Duplicates return a conflict error — use [`PATCH /v3/businesses/{vendor_data}/`](/management-api/businesses/update) to update.
* Registry-derived fields (`legal_name`, `registration_number`, `country_code`) can be seeded but will be **overwritten** by the first approved Business Verification (KYB) session's registry data.
* If `country_code` matches your application's [dangerous countries](/entities/businesses/blocklist#dangerous-countries) list, the business is created in `BLOCKED` status.
* Emits `business.data.updated`.

## Permissions

Role must grant `create:businesses`.

## Related

* [Business data model](/entities/businesses/data-model)
* [Vendor data linking](/entities/vendor-data-linking)
* [Business operations](/entities/businesses/operations)


# Batch Delete Businesses
Source: https://docs.didit.me/management-api/businesses/delete

POST /v3/businesses/delete/
**Permanently delete** businesses — this cannot be undone. For blocking prefer [Update Business Status](#patch-/v3/businesses/-vendor_data-/update-status/) with `BLOCKED`.

<AgentPromptAccordion title="Batch Delete Businesses Prompt" />

## Overview

Deletes one or more [Business entities](/entities/businesses/overview). The business records are removed permanently. Business Verification (KYB) sessions are not covered by this endpoint and survive with their link to the business cleared; delete them with [Delete Session](/sessions-api/delete-session). Transactions are not covered either; delete those from the Console.

## When to use it

* **Right-to-be-forgotten** requests.
* **Clean-up** of test businesses during QA.
* **Deprovisioning** businesses removed from your own platform.

## Notes

* Accepts a list of `vendor_data` values or `didit_internal_id` values.
* Idempotent — deleting an already-deleted business is a no-op.
* Returns only a count of what was deleted, not a per-item report. Values that matched nothing are skipped silently.
* Emits `business.data.updated` with `deleted_at` set.
* Records owned by the business entity itself go with it: its tag links, its comment history, and its own device and network records.
* Records produced by a KYB session do NOT: company registry data, uploaded documents, AML hits, beneficial owners and key-people checks all belong to the session and survive until you delete the session itself.

## Permissions

Role must grant `delete:businesses`. Typically reserved for `OWNER` and `ADMIN`.

## Related

* [Data retention](/console/data-retention)
* [Audit logs](/console/audit-logs)
* [Business operations](/entities/businesses/operations)


# Get Business
Source: https://docs.didit.me/management-api/businesses/get

GET /v3/businesses/{vendor_data}/
Fetch one [business](/entities/businesses) by `vendor_data` (exact match). Adds `metadata` and `updated_at` to the list view. Deleted businesses return 404.

<AgentPromptAccordion title="Get Business Prompt" />

## Overview

Returns a single [Business entity](/entities/businesses/overview) keyed by `vendor_data`.

## When to use it

* **Lookup** a business's current verification state — the `features` map gives you the latest status of every KYB feature at a glance.
* **Detail views** in your own admin UI.
* **Risk scoring** using aggregate counters and feature statuses.

## Notes

* `vendor_data` in the URL is case-sensitive.
* Returns `404` if no business with that `vendor_data` exists.
* Aggregate counters (`session_count`, `approved_count`, `declined_count`, `in_review_count`) update in real time as Business Verification (KYB) sessions complete.
* Registry-derived fields (`legal_name`, `registration_number`, `country_code`) reflect the latest approved Business Verification (KYB) session.

## Permissions

Role must grant `read:businesses`.

## Related

* [Businesses overview](/entities/businesses/overview)
* [Data model](/entities/businesses/data-model)
* [List businesses](/management-api/businesses/list)


# List Businesses
Source: https://docs.didit.me/management-api/businesses/list

GET /v3/businesses/
List [businesses](/entities/businesses) Didit assembles from KYB sessions sharing the same `vendor_data` (free-form string, NOT a UUID), plus businesses created via the API. Paginated, ordered by `last_session_at` desc. This endpoint does not support filtering or search parameters — fetch pages and filter client-side.

<AgentPromptAccordion title="List Businesses Prompt" />

## Overview

Returns a paginated list of [Business entities](/entities/businesses/overview) for the authenticated application.

## When to use it

* **Sync** your business table to an external BI or warehouse.
* **Analyst queues** — filter by `status=FLAGGED` to drive a review inbox.
* **Search** by `display_name`, `legal_name`, `registration_number`, or `vendor_data`.

## Filters and pagination

| Query parameter                               | Description                                                              |
| --------------------------------------------- | ------------------------------------------------------------------------ |
| `status`                                      | `ACTIVE`, `FLAGGED`, or `BLOCKED`.                                       |
| `search`                                      | Substring match on display name, legal name, registration, vendor\_data. |
| `country_code`                                | ISO 3166-1 alpha-3 country of incorporation.                             |
| `created_after`, `created_before`             | Creation date window.                                                    |
| `last_activity_after`, `last_activity_before` | Activity window.                                                         |
| `page_size`                                   | 1–200. Default 50.                                                       |
| `cursor`                                      | Pagination cursor.                                                       |

## Notes

* `vendor_data` may be `null` if the originating session or transaction did not provide one.
* Cursor-based pagination — persist the `next` cursor between calls.
* See the [Business data model](/entities/businesses/data-model) for every field.

## Permissions

Role must grant `list:businesses`.

## Related

* [Businesses overview](/entities/businesses/overview)
* [Get business](/management-api/businesses/get)
* [Business operations](/entities/businesses/operations)


# Update Business
Source: https://docs.didit.me/management-api/businesses/update

PATCH /v3/businesses/{vendor_data}/
Partial update of a business: `display_name`, `legal_name`, `registration_number`, `country_code`, `status`, `metadata`. `metadata` fully replaces. Setting `status` to `BLOCKED` adds the `vendor_data` to the system blocklist; moving away from `BLOCKED` removes that entry.

<AgentPromptAccordion title="Update Business Prompt" />

## Overview

Updates mutable fields on a [Business entity](/entities/businesses/overview). Fields populated from registry lookups (`legal_name`, `registration_number`, `country_code`) become read-only after the first approved Business Verification (KYB) session.

## When to use it

* **Rename** — set a better `display_name` for internal views.
* **Update metadata** — move a business between internal tiers, record an internal note, change tags.
* **Override registry data** (with caution) — overrides are accepted but flagged in the [audit log](/console/audit-logs).

## Notes

* `vendor_data` in the URL cannot be changed via this endpoint.
* Emits a `business.data.updated` webhook with a `changed_fields` array.

## Permissions

Role must grant `update:businesses`.

## Related

* [Business operations](/entities/businesses/operations)
* [Data model](/entities/businesses/data-model)
* [Update status](/management-api/businesses/update-status)


# Update Business Status
Source: https://docs.didit.me/management-api/businesses/update-status

PATCH /v3/businesses/{vendor_data}/update-status/
Flip only the lifecycle `status` of a business — VendorBusinessStatusChoices (`ACTIVE`/`FLAGGED`/`BLOCKED`, NOT session statuses). `BLOCKED` adds `vendor_data` to the system blocklist.

<AgentPromptAccordion title="Update Business Status Prompt" />

## Overview

Moves a [Business entity](/entities/businesses/overview) between `ACTIVE`, `FLAGGED`, and `BLOCKED`. See [entity lifecycle](/entities/lifecycle) for the full state machine.

## When to use it

* **Block** a sanctioned or confirmed-fraudulent business.
* **Flag** a business pending manual review.
* **Unblock** after remediation.
* **Propagate external signals** from your own compliance systems.

## Notes

* Valid values: `ACTIVE`, `FLAGGED`, `BLOCKED`.
* Passing a `reason` string is recommended — it is persisted and surfaced in the audit log and webhook payload.
* `BLOCKED` businesses have all new Business Verification (KYB) sessions auto-declined and all new transactions auto-declined, including when they appear as counterparty.
* Emits `business.status.updated` with `previous_status`, `status`, and `reason`.

## Enforcement

| Status    | New Business Verification (KYB) sessions | Transactions involving this business |
| --------- | ---------------------------------------- | ------------------------------------ |
| `ACTIVE`  | Normal flow                              | Normal flow                          |
| `FLAGGED` | Routed to `IN_REVIEW`                    | May auto-escalate via rules          |
| `BLOCKED` | Auto-declined                            | Auto-declined                        |

## Permissions

Role must grant `update-status:businesses`.

## Related

* [Entity lifecycle](/entities/lifecycle)
* [Business blocklist](/entities/businesses/blocklist)
* [Entity webhooks](/entities/webhooks)


# Create Case Blueprint
Source: https://docs.didit.me/management-api/case-blueprints/create

POST /v3/organization/{organization_id}/application/{application_id}/cases/blueprints/
Create a case blueprint: general settings (assignment, escalation, transfer, 4-eyes pairing) plus content_config, the six sections that drive the case page.

<AgentPromptAccordion title="Create Case Blueprint API Prompt" />

Create a blueprint. `content_config` is validated strictly - only the six known sections and their documented keys are accepted, so a typo returns a 400 rather than silently being ignored.

## Related

* [List case blueprints](/management-api/case-blueprints/list)
* [Install blueprint presets](/management-api/case-blueprints/install-presets)
* [Blueprints (Console)](/console/case-management/blueprints)


# Install Blueprint Presets
Source: https://docs.didit.me/management-api/case-blueprints/install-presets

POST /v3/organization/{organization_id}/application/{application_id}/cases/blueprints/presets/install/
Copy one or more presets into the application as editable blueprints. Idempotent per preset_key; omit preset_keys to install every preset not yet installed.

<AgentPromptAccordion title="Install Blueprint Presets API Prompt" />

Copy one or more built-in presets into the application as editable blueprints. Call `GET .../cases/blueprints/presets/` first to see the full catalogue and which presets are already installed.

## Related

* [Create case blueprint](/management-api/case-blueprints/create)
* [Blueprints (Console)](/console/case-management/blueprints)


# List Case Blueprints
Source: https://docs.didit.me/management-api/case-blueprints/list

GET /v3/organization/{organization_id}/application/{application_id}/cases/blueprints/
List case blueprints for the application.

<AgentPromptAccordion title="List Case Blueprints API Prompt" />

List blueprints for the application. `GET .../cases/blueprints/{blueprint_uuid}/` returns the same shape plus `content_config`, connected creation sources, and the escalation graph for a single blueprint.

## Related

* [Create case blueprint](/management-api/case-blueprints/create)
* [Install blueprint presets](/management-api/case-blueprints/install-presets)
* [Blueprints (Console)](/console/case-management/blueprints)


# Bulk Update Case Status
Source: https://docs.didit.me/management-api/cases/bulk-status

POST /v3/organization/{organization_id}/application/{application_id}/cases/bulk/status/
Apply the same status transition to several cases in one call: OPEN reopens, AWAITING_USER requests info, RESOLVED resolves (resolution required). Each case is evaluated independently; gate failures (incomplete checklist, missing required note) are reported per case without aborting the batch.

<AgentPromptAccordion title="Bulk Update Case Status API Prompt" />

Apply the same status transition to many cases at once, mirroring the Cases list's bulk **Set Status** action. Failures are reported per case, so one blocked case never rolls back the rest of the batch.

## Related

* [Resolve case](/management-api/cases/resolve)
* [List cases](/management-api/cases/list)


# Create Case
Source: https://docs.didit.me/management-api/cases/create

POST /v3/organization/{organization_id}/application/{application_id}/cases/
Create a case anchored to exactly one subject (a user or a business), directly or by deriving the subject from an attached session/transaction link. Source is always `MANUAL` for API-created cases.

<AgentPromptAccordion title="Create Case API Prompt" />

Create a case anchored to exactly one subject. Provide `subject` directly, or supply `links` and let Didit derive the subject from the first linked entity's owner.

<Tip>
  Pass `blueprint` whenever you have one - it determines which case-page sections render, whether resolution requires a note, and where the case routes on escalation or transfer.
</Tip>

## Related

* [List cases](/management-api/cases/list)
* [Resolve case](/management-api/cases/resolve)
* [Creating cases (Console)](/console/case-management/creating-cases)


# Create Case Note
Source: https://docs.didit.me/management-api/cases/create-note

POST /v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/notes/
Post a plain-text note, optionally mentioning teammates, tagging it, or attaching files uploaded via notes/presign/.

<AgentPromptAccordion title="Create Case Note API Prompt" />

Post a plain-text note. To attach a file, first upload it with `POST .../notes/presign/` and pass the returned `s3_key` in `attachments`.

## Related

* [List case notes](/management-api/cases/list-notes)
* [Get case](/management-api/cases/get)


# Get Case
Source: https://docs.didit.me/management-api/cases/get

GET /v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/
Retrieve a case with its subject, blueprint, notes, events, links, and checklist.

<AgentPromptAccordion title="Get Case API Prompt" />

Retrieve a case with everything needed to render a full case page: subject, blueprint (including its `content_config`), the newest notes and events, links, and checklist state.

## Related

* [List cases](/management-api/cases/list)
* [List case notes](/management-api/cases/list-notes)
* [Resolve case](/management-api/cases/resolve)


# List Cases
Source: https://docs.didit.me/management-api/cases/list

GET /v3/organization/{organization_id}/application/{application_id}/cases/
List cases for the application, newest first. Supports filtering, search, and sorting; see query parameters. Paginated with `limit`/`offset`.

<AgentPromptAccordion title="List Cases API Prompt" />

List cases for the application, newest first by default. Every filter and sort option available in the Console's Cases list is exposed as a query parameter, including full-text `search` across the subject, tags, case number, and linked session or transaction IDs.

## Related

* [Create case](/management-api/cases/create)
* [Case analytics](/management-api/cases/statistics)
* [Cases (Console)](/console/case-management/cases)


# List Case Notes
Source: https://docs.didit.me/management-api/cases/list-notes

GET /v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/notes/
List notes on the case, newest first.

<AgentPromptAccordion title="List Case Notes API Prompt" />

List notes on a case, newest first. Notes are plain text with optional attachments and tags - there is no rich-text formatting.

## Related

* [Create case note](/management-api/cases/create-note)
* [Get case](/management-api/cases/get)


# Print Case
Source: https://docs.didit.me/management-api/cases/print

GET /v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/print/
Render the full case (summary, subject, checklist state, notes, attached sessions/transactions, events, FIU report list) as a PDF and return a presigned download URL.

<AgentPromptAccordion title="Print Case API Prompt" />

Render the full case as a PDF and get back a presigned download URL. Use this for internal audits, handoffs, or record-keeping - it is independent of the case's FIU reports.

## Related

* [FIU reports (Console)](/console/case-management/fiu-reports)
* [Finalize report](/management-api/regulatory-reports/finalize)


# Request Info (Awaiting User)
Source: https://docs.didit.me/management-api/cases/request-info

POST /v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/request-info/
Move an open case to awaiting_user while more information is collected from the verified user. Fails with 400 if a resolution is currently pending 4-eyes approval.

<AgentPromptAccordion title="Request Info API Prompt" />

Pause an open case in `AWAITING_USER` while your team collects more information from the verified user. Use [reopen](/console/case-management/cases) once the case can resume active investigation.

## Related

* [Resolve case](/management-api/cases/resolve)
* [Transfer case](/management-api/cases/transfer)


# Resolve Case
Source: https://docs.didit.me/management-api/cases/resolve

POST /v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/resolve/
Resolve the case as false_positive or valid_threat. Blocked with 400 if the blueprint's checklist is not optional and items remain incomplete, or if the blueprint requires a resolution note and none is given. When the case's blueprint has a four_eyes_checker_blueprint configured, the resolution is staged (case.pending_resolution) and the case moves to the checker blueprint instead of resolving immediately; a different user must call approve or reject-approval.

<AgentPromptAccordion title="Resolve Case API Prompt" />

Resolve a case. If its blueprint pairs with a checker blueprint for [4-eyes review](/console/case-management/four-eyes), this stages the resolution instead of closing the case - check the response's `pending_resolution` field to tell the two outcomes apart.

## Related

* [4-eyes review (Console)](/console/case-management/four-eyes)
* [Checklist (Console)](/console/case-management/checklist)
* [Bulk update status](/management-api/cases/bulk-status)


# Case Analytics
Source: https://docs.didit.me/management-api/cases/statistics

GET /v3/organization/{organization_id}/application/{application_id}/cases/statistics/
Aggregate case analytics for the date range (defaults to the last 30 days; max 731 days): a created-vs-reviewed time series, per-officer/blueprint/source/status tables, rollup totals, and the live open/overdue queue depth.

<AgentPromptAccordion title="Case Analytics API Prompt" />

Aggregate metrics behind the Console's [Overview and Analytics pills](/console/case-management/analytics): a daily created-vs-reviewed series, four breakdown tables, rollup totals, and the live open/overdue queue.

## Related

* [Analytics (Console)](/console/case-management/analytics)
* [List cases](/management-api/cases/list)


# Transfer Case
Source: https://docs.didit.me/management-api/cases/transfer

POST /v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/transfer/
Move the case to a different, active blueprint of the same application. Requires the current blueprint to have transfer_enabled, otherwise 400.

<AgentPromptAccordion title="Transfer Case API Prompt" />

Move a case to a different blueprint entirely, distinct from [escalation](/console/case-management/blueprints#escalation-and-transfer), which always routes to one fixed target. Transfer only works when the case's current blueprint has `transfer_enabled` set.

## Related

* [Blueprints (Console)](/console/case-management/blueprints)
* [Resolve case](/management-api/cases/resolve)


# Get Branding
Source: https://docs.didit.me/management-api/customization/get

GET /v3/customization/
Returns the white-label branding for the application resolved from the API key: colors, fonts, border radii, logo URLs and UI/UX options. Custom domain and white-label email settings are managed only in the Business Console and are not part of this response.

<AgentPromptAccordion title="Get Branding Prompt" />

## Overview

Returns the white-label branding for the application resolved from your API key — the same branding shown to end users in the [verification flow](/console/white-label). The response covers colors, fonts, border radii, logo URLs and UI/UX options.

## When to use it

* **Read current theme** — fetch the active palette, font and logos before rendering or editing them.
* **Sync branding** — mirror Didit branding into your own admin UI.

## Notes

* The application is resolved from the API key — there are no path or query parameters.
* `logo_square`, `logo_rectangular`, `favicon` and `font_url` are read-only. Set logos by uploading images in [Update Branding](/management-api/customization/update).
* Custom domain and white-label email are **not** part of this response; they remain managed in the Business Console.

## Permissions

The API key must be able to read customization for the application.

## Related

* [Update branding](/management-api/customization/update)
* [White-label in the Console](/console/white-label)


# Update Branding
Source: https://docs.didit.me/management-api/customization/update

PATCH /v3/customization/
Partial update of the application's white-label branding. Send `application/json` to change colors, fonts, radii and UI options, or `multipart/form-data` to upload logo images. Only the fields you include are changed. Custom domain and white-label email cannot be set through this endpoint — use the Business Console for those.

<AgentPromptAccordion title="Update Branding Prompt" />

## Overview

Partial-updates the white-label branding for the application resolved from your API key. Send `application/json` to change colors, fonts, radii and UI options, or `multipart/form-data` to upload logos. Only the fields you include are changed — everything else is left untouched.

## When to use it

* **Theme the flow** — set your brand colors, font and corner radii.
* **Upload logos** — set the square logo, rectangular logo and favicon.
* **Tune the experience** — set the public app name, privacy policy URL, and toggles like skipping the welcome screen or hiding the progress bar.

## Uploading logos

Send logos as `multipart/form-data`:

* `image_square` — 1:1 aspect ratio, max **1 MB**
* `image_rectangular` — 2:1 aspect ratio, max **1 MB**
* `image_favicon` — max **500 KB**

Allowed image types are `png`, `jpg`, `jpeg` and `webp`. The response returns the resulting `logo_square`, `logo_rectangular` and `favicon` URLs. To remove a logo, send the matching `delete_logo_square`, `delete_logo_rectangular` or `delete_favicon` flag as `true`.

## Notes

* The application is resolved from the API key — there are no path parameters.
* Hex colors accept `#RRGGBB` or `#RRGGBBAA`. `font_weight` must be a weight available for the selected `font_family`.
* **Custom domain and white-label email are not configurable here.** Manage those in the [Business Console](/console/white-label).

## Permissions

The API key must be able to update customization for the application.

## Related

* [Get branding](/management-api/customization/get)
* [White-label in the Console](/console/white-label)


# Create List
Source: https://docs.didit.me/management-api/lists/create

POST /v3/lists/
POST /v3/lists/ — create a new allowlist or custom list for your Didit application. System blocklists are auto-provisioned. Pay-per-call, no contracts.

<AgentPromptAccordion title="Create List API Prompt" />

Create a new list for your application. Only `allowlist` and `custom` types can be created — system blocklists are auto-provisioned.

## Request body

| Field         | Type   | Required | Description                                                                                                                                              |
| ------------- | ------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `name`        | string | Yes      | List name (must be unique per application)                                                                                                               |
| `description` | string | No       | Optional description                                                                                                                                     |
| `list_type`   | string | Yes      | `allowlist` or `custom`                                                                                                                                  |
| `entry_type`  | string | Yes      | One of: `face`, `document`, `phone`, `email`, `ip_address`, `device_fingerprint`, `wallet_address`, `bank_account`, `country`, `user`, `business`, `key` |

<RequestExample>
  ```bash theme={null}
  curl -X POST "https://verification.didit.me/v3/lists/" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"name": "Trusted IPs", "list_type": "allowlist", "entry_type": "ip_address"}'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "uuid": "f1e2d3c4-...",
    "name": "Trusted IPs",
    "description": "",
    "list_type": "allowlist",
    "entry_type": "ip_address",
    "is_system": false,
    "entry_count": 0,
    "last_entry_added_at": null,
    "created_at": "2025-06-09T12:26:54Z",
    "updated_at": "2025-06-09T12:26:54Z"
  }
  ```
</ResponseExample>


# Create List Entry
Source: https://docs.didit.me/management-api/lists/create-entry

POST /v3/lists/{list_uuid}/entries/
Add an entry — face, document, IP, wallet, email, phone — to a Didit blocklist, allowlist, or custom list. Programmatic compliance and fraud controls.

<AgentPromptAccordion title="Create List Entry API Prompt" />

Add an entry to a list. The value is validated based on the list's entry type:

* **email**: Must be a valid email address
* **phone**: Must be a valid international phone number (auto-normalized to E.164)
* **ip\_address**: Must be a valid IP address or CIDR range (e.g. `192.168.1.1` or `10.0.0.0/8`)
* **device\_fingerprint**: Must be at least 8 alphanumeric characters
* **country**: Must be a valid [ISO 3166-1 alpha-3 country code](/core-technology/id-verification/supported-documents-id-verification) (e.g. `USA`, `GBR`, `ESP`). Alpha-2 codes (e.g. `US`) are accepted and automatically converted to alpha-3.
* **face**, **document**, **wallet\_address**, **bank\_account**, **user**, **business**, **key**: Any non-empty string

<Info>
  All entry values are **case-insensitive**. Values are normalized on storage (lowercased for most types, uppercased for country codes) and matched case-insensitively during verification. For example, blocking `User@Example.COM` will also catch `user@example.com`.
</Info>

For face entries, use the [Upload face](/management-api/lists/upload-face) endpoint instead — unless you provide a `reference_session_id`, which handles face blocklisting automatically (including biometric matching).

## Request body

| Field                   | Type          | Required    | Description                                                                                                                                                                                                                                   |
| ----------------------- | ------------- | ----------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `value`                 | string        | Conditional | The value to add (phone number, email, IP, etc.). Required unless `reference_session_id` is provided. When both `value` and `reference_session_id` are provided, the value is used to disambiguate (e.g. when a session has multiple phones). |
| `reference_session_id`  | string (UUID) | No          | Verification session ID. Didit auto-extracts the value from the session based on the list's entry type, links the entry back, and marks the underlying model as blocklisted. See [Adding from a session](#adding-from-a-session).             |
| `reference_object_uuid` | string (UUID) | No          | UUID of the source entity (transaction UUID, vendor user `didit_internal_id`, etc.). Stored on the entry for traceability — lets you navigate from the blocklist back to the original entity.                                                 |
| `display_label`         | string        | No          | Human-readable label shown in the console                                                                                                                                                                                                     |
| `comment`               | string        | No          | Comment or reason for adding                                                                                                                                                                                                                  |
| `metadata`              | object        | No          | Additional structured data. Commonly used for document context (`full_name`, `issuing_state`, `document_type`) or entity references (`reference_type`, `reference_id`).                                                                       |

## Adding from a session

When you provide a `reference_session_id`, Didit automatically:

1. Looks up the session (must belong to the same application)
2. Extracts the value based on the list's entry type:
   * **face** → links the biometric data for future matching, sets `is_blocklisted` on the Face model
   * **document** → extracts document number, stores full name / issuing state / document type in metadata, sets `is_blocklisted` on the KYC model
   * **phone** → extracts the phone number, sets `is_blocklisted` on the Phone model
   * **email** → extracts the email address, sets `is_blocklisted` on the Email model
   * **ip\_address** → extracts the IP from the session's location data
   * **device\_fingerprint** → extracts the device fingerprint from the session's location data
3. Sets `reference_session` and `reference_object_uuid` on the entry for traceability

Returns `400` if the session is not found or does not contain data for the requested entry type.

### Disambiguating multiple values

If a session has multiple instances of the same type (e.g. two phone numbers from a multi-step workflow), pass both `reference_session_id` and `value`. The backend finds the matching instance and returns `400` if the value doesn't match any data in the session.

```json theme={null}
{
  "reference_session_id": "a1b2c3d4-...",
  "value": "+34612345678"
}
```

If you omit `value`, the most recently created instance is used.

## Referencing transactions, users, and businesses

When blocklisting data from a transaction or vendor user/business, pass the entity's UUID as `reference_object_uuid` and indicate the source type in `metadata`:

```json theme={null}
{
  "value": "0xABC123...",
  "reference_object_uuid": "txn-uuid-here",
  "metadata": {
    "reference_type": "transaction",
    "reference_id": "txn-uuid-here"
  }
}
```

This lets you navigate from the blocklist entry back to the original transaction, user, or business in the console.

| Source entity        | `reference_object_uuid`                         | `metadata.reference_type`               |
| -------------------- | ----------------------------------------------- | --------------------------------------- |
| Verification session | Auto-set by backend (face/KYC/phone/email UUID) | Not needed — use `reference_session_id` |
| Transaction          | Transaction UUID                                | `"transaction"`                         |
| Vendor user          | `didit_internal_id`                             | `"vendor_user"`                         |
| Vendor business      | `didit_internal_id`                             | `"vendor_business"`                     |

<RequestExample>
  ```bash Manual value theme={null}
  curl -X POST "https://verification.didit.me/v3/lists/{list_uuid}/entries/" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"value": "+14155552671", "comment": "Reported as fraud"}'
  ```

  ```bash From session theme={null}
  curl -X POST "https://verification.didit.me/v3/lists/{list_uuid}/entries/" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"reference_session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890"}'
  ```

  ```bash From session (disambiguate) theme={null}
  curl -X POST "https://verification.didit.me/v3/lists/{list_uuid}/entries/" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"reference_session_id": "a1b2c3d4-...", "value": "+34612345678"}'
  ```

  ```bash From transaction theme={null}
  curl -X POST "https://verification.didit.me/v3/lists/{list_uuid}/entries/" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{
      "value": "0xd15ae8c92c304c5ca11778143480e391",
      "reference_object_uuid": "e7f8a9b0-1234-5678-abcd-ef0123456789",
      "metadata": {"reference_type": "transaction"}
    }'
  ```
</RequestExample>

<ResponseExample>
  ```json Manual value theme={null}
  {
    "uuid": "a1b2c3d4-...",
    "value": "+14155552671",
    "display_label": "",
    "comment": "Reported as fraud",
    "added_by": "api",
    "reference_session_id": null,
    "reference_session_number": null,
    "reference_object_uuid": null,
    "metadata": null,
    "created_at": "2025-06-09T12:26:54Z"
  }
  ```

  ```json From session (document) theme={null}
  {
    "uuid": "f9e8d7c6-...",
    "value": "AB1234567",
    "display_label": "John Doe - AB1234567",
    "comment": "",
    "added_by": "console",
    "reference_session_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
    "reference_session_number": 42,
    "reference_object_uuid": "b2c3d4e5-...",
    "metadata": {
      "full_name": "John Doe",
      "issuing_state": "USA",
      "document_type": "PASSPORT",
      "document_number": "SAMPLE-DOC-12345"
    },
    "created_at": "2025-06-09T12:30:00Z"
  }
  ```

  ```json From transaction theme={null}
  {
    "uuid": "11223344-...",
    "value": "0xd15ae8c92c304c5ca11778143480e391",
    "display_label": "",
    "comment": "",
    "added_by": "console",
    "reference_session_id": null,
    "reference_session_number": null,
    "reference_object_uuid": "e7f8a9b0-1234-5678-abcd-ef0123456789",
    "metadata": {
      "reference_type": "transaction"
    },
    "created_at": "2025-06-09T12:35:00Z"
  }
  ```
</ResponseExample>


# Delete List
Source: https://docs.didit.me/management-api/lists/delete

DELETE /v3/lists/{list_uuid}/
DELETE /v3/lists/{list_uuid}/ — remove an allowlist or custom list from your Didit application. System blocklists cannot be deleted.

<AgentPromptAccordion title="Delete List API Prompt" />

Delete a list. System lists (blocklists) cannot be deleted. Returns 204 on success.

<RequestExample>
  ```bash theme={null}
  curl -X DELETE "https://verification.didit.me/v3/lists/{list_uuid}/" \
    -H "x-api-key: YOUR_API_KEY"
  ```
</RequestExample>


# Delete List Entry
Source: https://docs.didit.me/management-api/lists/delete-entry

DELETE /v3/lists/{list_uuid}/entries/{entry_uuid}/
DELETE /v3/lists/{list_uuid}/entries/{entry_uuid}/ — remove an entry from a Didit blocklist, allowlist, or custom list. Auto-unblocks on system lists.

<AgentPromptAccordion title="Delete List Entry API Prompt" />

Remove an entry from a list. For system blocklists, the corresponding item is automatically unblocked so it will no longer be declined during future verifications. Returns 204 on success.

<RequestExample>
  ```bash theme={null}
  curl -X DELETE "https://verification.didit.me/v3/lists/{list_uuid}/entries/{entry_uuid}/" \
    -H "x-api-key: YOUR_API_KEY"
  ```
</RequestExample>


# Get List
Source: https://docs.didit.me/management-api/lists/get

GET /v3/lists/{list_uuid}/
GET /v3/lists/{list_uuid}/ — retrieve details of a specific Didit blocklist, allowlist, or custom list including entry count and metadata.

<AgentPromptAccordion title="Get List API Prompt" />

Get the details of a specific list, including entry count and last entry timestamp.

<RequestExample>
  ```bash theme={null}
  curl -X GET "https://verification.didit.me/v3/lists/{list_uuid}/" \
    -H "x-api-key: YOUR_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "uuid": "a1b2c3d4-...",
    "name": "Face Blocklist",
    "description": "Blocked biometric faces...",
    "list_type": "blocklist",
    "entry_type": "face",
    "is_system": true,
    "entry_count": 5,
    "last_entry_added_at": "2025-06-09T12:26:54Z",
    "created_at": "2025-01-01T00:00:00Z",
    "updated_at": "2025-06-09T12:26:54Z"
  }
  ```
</ResponseExample>


# List All Lists
Source: https://docs.didit.me/management-api/lists/list

GET /v3/lists/
GET /v3/lists/ — retrieve all blocklists, allowlists, and custom lists for your app. Filter by list type or entry type. Pay-per-call, no contracts.

<AgentPromptAccordion title="List Lists API Prompt" />

Retrieve a paginated list of all lists (blocklists, allowlists, custom) for your application. Filter by `list_type` or `entry_type`.

## Query parameters

| Parameter    | Type    | Description                                                                                                                                                            |
| ------------ | ------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `list_type`  | string  | Filter by type: `blocklist`, `allowlist`, or `custom`                                                                                                                  |
| `entry_type` | string  | Filter by entry type: `face`, `document`, `phone`, `email`, `ip_address`, `device_fingerprint`, `wallet_address`, `bank_account`, `country`, `user`, `business`, `key` |
| `ordering`   | string  | Sort by: `created_at`, `-created_at`, `entry_count`, `-entry_count`, `last_entry_added_at`, `-last_entry_added_at`                                                     |
| `offset`     | integer | Pagination offset (default: 0)                                                                                                                                         |
| `limit`      | integer | Page size (default: 25)                                                                                                                                                |

<RequestExample>
  ```bash theme={null}
  curl -X GET "https://verification.didit.me/v3/lists/?list_type=blocklist" \
    -H "x-api-key: YOUR_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "count": 10,
    "next": null,
    "previous": null,
    "results": [
      {
        "uuid": "a1b2c3d4-...",
        "name": "Face Blocklist",
        "description": "Blocked biometric faces...",
        "list_type": "blocklist",
        "entry_type": "face",
        "is_system": true,
        "entry_count": 3,
        "last_entry_added_at": "2025-06-09T12:26:54Z",
        "created_at": "2025-01-01T00:00:00Z",
        "updated_at": "2025-06-09T12:26:54Z"
      }
    ]
  }
  ```
</ResponseExample>


# List Entries
Source: https://docs.didit.me/management-api/lists/list-entries

GET /v3/lists/{list_uuid}/entries/
GET /v3/lists/{list_uuid}/entries/ — retrieve paginated entries in a Didit blocklist, allowlist, or custom list with search filtering. Pay-per-call.

<AgentPromptAccordion title="List Entries API Prompt" />

Retrieve entries in a specific list with optional search filtering.

## Query parameters

| Parameter | Type    | Description                              |
| --------- | ------- | ---------------------------------------- |
| `search`  | string  | Search entries by value or display label |
| `offset`  | integer | Pagination offset (default: 0)           |
| `limit`   | integer | Page size (default: 25)                  |

## Response fields

| Field                      | Type            | Description                                                                                                                                                                                                            |
| -------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `uuid`                     | string          | Unique entry ID                                                                                                                                                                                                        |
| `value`                    | string          | The blocklisted value (phone number, email, document number, IP, etc.)                                                                                                                                                 |
| `display_label`            | string          | Human-readable label                                                                                                                                                                                                   |
| `comment`                  | string          | Comment or reason for adding                                                                                                                                                                                           |
| `added_by`                 | string          | Who added the entry (`api`, `console`, email, or `system`)                                                                                                                                                             |
| `reference_session_id`     | string \| null  | Session ID this entry was created from (for session-based entries)                                                                                                                                                     |
| `reference_session_number` | integer \| null | Session number for display                                                                                                                                                                                             |
| `reference_object_uuid`    | string \| null  | UUID of the source entity — Face/KYC/Phone/Email object (for session entries), or transaction/vendor user/business UUID (for entity-based entries). Use with `metadata.reference_type` to navigate back to the source. |
| `metadata`                 | object \| null  | Structured data. May include `reference_type` (`"transaction"`, `"vendor_user"`, `"vendor_business"`), document context (`full_name`, `issuing_state`), or face image URLs.                                            |
| `created_at`               | string          | ISO 8601 timestamp                                                                                                                                                                                                     |

<RequestExample>
  ```bash theme={null}
  curl -X GET "https://verification.didit.me/v3/lists/{list_uuid}/entries/?search=example" \
    -H "x-api-key: YOUR_API_KEY"
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "count": 2,
    "next": null,
    "previous": null,
    "results": [
      {
        "uuid": "e1f2a3b4-...",
        "value": "test@example.com",
        "display_label": "",
        "comment": "Reported as fraudulent",
        "added_by": "api",
        "reference_session_id": null,
        "reference_session_number": null,
        "reference_object_uuid": null,
        "metadata": null,
        "created_at": "2025-06-09T12:26:54Z"
      },
      {
        "uuid": "a9b8c7d6-...",
        "value": "0xd15ae8c92c304c5ca11778143480e391",
        "display_label": "",
        "comment": "",
        "added_by": "console",
        "reference_session_id": null,
        "reference_session_number": null,
        "reference_object_uuid": "e7f8a9b0-1234-5678-abcd-ef0123456789",
        "metadata": {
          "reference_type": "transaction",
          "reference_id": "e7f8a9b0-1234-5678-abcd-ef0123456789"
        },
        "created_at": "2025-06-09T12:35:00Z"
      }
    ]
  }
  ```
</ResponseExample>


# Lists
Source: https://docs.didit.me/management-api/lists/overview

Manage Didit blocklists, allowlists, and custom lists for KYC, fraud, and transaction screening. All-in-one identity infrastructure, pay-per-call.

<AgentPromptAccordion title="Lists API Prompt" />

The Lists API lets you manage typed lists for your application. System blocklists are automatically created and checked during verification and transaction screening. You can also create allowlists and custom lists for workflow conditions.

## Concepts

| Type          | Description                                                                                                                    |
| ------------- | ------------------------------------------------------------------------------------------------------------------------------ |
| **Blocklist** | System-created, one per entry type. Items in a blocklist cause automatic decline during verification or transaction screening. |
| **Allowlist** | User-created. Used in workflow conditions and to suppress duplicate/reuse actions for trusted matching items.                  |
| **Custom**    | User-created. Flexible lists for workflow branching, monitoring rules, or manual review.                                       |

## Entry types

| Entry type           | Checked during                              | On match             |
| -------------------- | ------------------------------------------- | -------------------- |
| `face`               | Liveness verification                       | Session declined     |
| `document`           | ID verification (OCR)                       | Session declined     |
| `phone`              | Phone verification                          | Session declined     |
| `email`              | Email verification                          | Session declined     |
| `ip_address`         | Device & IP Analysis (supports CIDR ranges) | Session declined     |
| `device_fingerprint` | Device & IP Analysis                        | Session declined     |
| `wallet_address`     | Transaction screening                       | Transaction declined |
| `bank_account`       | Transaction screening                       | Transaction declined |
| `user`               | Transaction screening                       | User blocked         |
| `business`           | Transaction screening                       | Business blocked     |
| `country`            | Workflow conditions                         | Configurable         |
| `key`                | Custom use                                  | Configurable         |

## Allowlists

Allowlists do not override blocklists or authenticity checks. They only suppress duplicate/reuse actions for the same entry type. For example, a face in a face allowlist can skip the `DUPLICATED_FACE` action, an IP in an IP allowlist can skip the `DUPLICATED_IP_ADDRESS` action, and a device fingerprint in a device allowlist can skip the `DUPLICATED_DEVICE_FINGERPRINT` action. Didit still records an informational allowlist warning so you can audit why the duplicate action did not run.

## System blocklists

Every application automatically gets 10 system blocklists (one per supported entry type). These cannot be deleted or renamed. You can add entries to them via the API or from the console.

## Traceability

Every blocklist entry can be linked back to its source entity so you can navigate from the list to the original record:

* **From a session** — pass `reference_session_id` when [creating an entry](/management-api/lists/create-entry). Didit auto-extracts the value (face, document, phone, email, IP, or device), marks the underlying model as blocklisted, and links the entry back to the session. If the session has multiple instances of the same type, also pass `value` to disambiguate.
* **From a transaction, user, or business** — pass `reference_object_uuid` with the entity's UUID and include `metadata.reference_type` (`"transaction"`, `"vendor_user"`, or `"vendor_business"`) so the console can link back to the original record.

## Endpoints

<CardGroup>
  <Card title="List all lists" icon="list" href="/management-api/lists/list">
    Retrieve all lists for an application.
  </Card>

  <Card title="List entries" icon="table" href="/management-api/lists/list-entries">
    Retrieve entries in a list.
  </Card>

  <Card title="Create entry" icon="circle-plus" href="/management-api/lists/create-entry">
    Add a value to a blocklist — by value, session reference, or transaction reference.
  </Card>

  <Card title="Delete entry" icon="circle-minus" href="/management-api/lists/delete-entry">
    Remove an entry and unblock the underlying entity.
  </Card>

  <Card title="Upload face" icon="face-smile" href="/management-api/lists/upload-face">
    Upload a face image directly to a face blocklist.
  </Card>
</CardGroup>


# Update List
Source: https://docs.didit.me/management-api/lists/update

PATCH /v3/lists/{list_uuid}/
PATCH /v3/lists/{list_uuid}/ — rename or update the description of a Didit allowlist or custom list. System blocklists are immutable.

<AgentPromptAccordion title="Update List API Prompt" />

Update the name or description of a list. System lists cannot be modified.

## Request body

| Field         | Type   | Description                               |
| ------------- | ------ | ----------------------------------------- |
| `name`        | string | New name (must be unique per application) |
| `description` | string | New description                           |

<RequestExample>
  ```bash theme={null}
  curl -X PATCH "https://verification.didit.me/v3/lists/{list_uuid}/" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"name": "Updated List Name"}'
  ```
</RequestExample>


# Upload Face to List
Source: https://docs.didit.me/management-api/lists/upload-face

POST /v3/lists/{list_uuid}/entries/face-upload/
Upload a base64 face image to a Didit face blocklist or allowlist. Didit extracts the biometric and uses it during future face matching.

<AgentPromptAccordion title="Upload Face to List API Prompt" />

Upload a base64-encoded face image to a face-type blocklist or allowlist. Didit extracts the biometric data, validates a face is detected, inserts the embedding into the matching database, and creates a list entry.

Only available for lists with `entry_type: face` and `list_type: blocklist` or `list_type: allowlist`.

<Tip>
  If you're blocklisting or allowlisting a face **from an existing session**, use [Create entry](/management-api/lists/create-entry) with `reference_session_id` instead — the backend links the entry back to the session.
</Tip>

## Request body

| Field     | Type   | Required | Description                                   |
| --------- | ------ | -------- | --------------------------------------------- |
| `image`   | string | Yes      | Base64-encoded face image (JPG, PNG, or WebP) |
| `comment` | string | No       | Comment or reason for adding                  |

<RequestExample>
  ```bash theme={null}
  curl -X POST "https://verification.didit.me/v3/lists/{list_uuid}/entries/face-upload/" \
    -H "x-api-key: YOUR_API_KEY" \
    -H "Content-Type: application/json" \
    -d '{"image": "/9j/4AAQSkZ...", "comment": "Known fraudster"}'
  ```
</RequestExample>

<ResponseExample>
  ```json theme={null}
  {
    "uuid": "a1b2c3d4-...",
    "value": "face-uuid-here",
    "display_label": "",
    "comment": "Known fraudster",
    "added_by": "api",
    "reference_session_id": null,
    "reference_session_number": null,
    "reference_object_uuid": "face-uuid-here",
    "metadata": {
      "reference_image_url": "https://..."
    },
    "created_at": "2025-06-09T12:26:54Z"
  }
  ```
</ResponseExample>

<Warning>
  The image must contain a clearly visible face. If no face is detected, a 400 error is returned.
</Warning>


# Get Network
Source: https://docs.didit.me/management-api/networks/get

GET /v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/
Retrieve a single network's full detail, including stats, fraud tags, and risk signals.

<AgentPromptAccordion title="Get Network API Prompt" />

Retrieve one network with everything needed to render a network's overview panel: its risk breakdown, detected fraud tags, and risk-signal summaries, on top of the fields shared with the list.

## Related

* [List networks](/management-api/networks/list)
* [Network members](/management-api/networks/members)
* [Network graph](/management-api/networks/graph)


# Get Network Graph
Source: https://docs.didit.me/management-api/networks/graph

GET /v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/graph/
Retrieve the network as a graph of subject nodes (vendor users, vendor businesses, transaction parties) and signal nodes (the shared device/IP/face/document/phone/email/address values linking them), with edges representing memberships.

<AgentPromptAccordion title="Network Graph API Prompt" />

Retrieve the network as a graph: subject nodes for each vendor user, vendor business, or transaction party in the network, signal nodes for each shared device, IP, face, document number, phone, email, or address value linking them, and edges for the memberships between them.

Use `depth` to bound how many hops out from a `focus_kind`/`focus_id` subject to return, this is what backs the Console's graph view zooming into one applicant's immediate connections instead of loading the whole network. Omit `depth` (or pass `all`) for the full neighborhood; `truncated` tells you whether a bounded request cut anything off.

## Related

* [Get network](/management-api/networks/get)
* [Network members](/management-api/networks/members)
* [Network signals](/management-api/networks/signals)


# List Networks
Source: https://docs.didit.me/management-api/networks/list

GET /v3/organization/{organization_id}/application/{application_id}/networks/
List fraud networks detected within this application's organization, newest activity first by default. By default dismissed networks are excluded; pass status to include them. Sandbox applications never have networks - clustering excludes sandbox data entirely.

<AgentPromptAccordion title="List Networks API Prompt" />

List fraud networks detected for your organization, newest activity first by default. Every filter available in the Console's Networks list is exposed as a query parameter, including free-text `q` search and the same status, signal, pattern, and risk-band chips.

<Note>
  Sandbox applications never have networks. Clustering runs on production data only.
</Note>

## Related

* [Get network](/management-api/networks/get)
* [Network graph](/management-api/networks/graph)
* [Networks (Console)](/console/networks)


# Get Network Map
Source: https://docs.didit.me/management-api/networks/map

GET /v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/map/
Geographic points where this network's members' addresses/locations converge, sourced from the sessions, business sessions, and transactions backing its memberships.

<AgentPromptAccordion title="Network Map API Prompt" />

Retrieve the geographic points where this network's members converge, one entry per observed location. `convergence_count` is the number of distinct points multiple members share, useful for spotting a network anchored on one address or city even when its members otherwise look unrelated. This backs the Console's map view of a network.

## Related

* [Get network](/management-api/networks/get)
* [Network timeline](/management-api/networks/timeline)
* [Network members](/management-api/networks/members)


# List Network Members
Source: https://docs.didit.me/management-api/networks/members

GET /v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/members/
List the subjects (vendor users, vendor businesses, or transaction parties) that belong to this network.

<AgentPromptAccordion title="List Network Members API Prompt" />

List every subject (vendor user, vendor business, or transaction party) that belongs to this network, with each member's verification outcome, risk, tags, and the sessions, business sessions, or transactions that placed them in the network.

<Note>
  A member's `node_status` (`approved`, `in_review`, `declined`, `not_completed`) is that applicant's own verification outcome. It is separate from the network's `status` (`active`, `in_review`, `resolved`, `dismissed`), which tracks the investigation, not any one member.
</Note>

## Related

* [Get network](/management-api/networks/get)
* [Network graph](/management-api/networks/graph)
* [Network signals](/management-api/networks/signals)


# Network Membership Lookup
Source: https://docs.didit.me/management-api/networks/membership-lookup



<AgentPromptAccordion title="Network Membership Lookup API Prompt" />

Given a session, business session, user, business, transaction, or transaction party, look up which fraud networks it belongs to. Every variant returns the same shape - `{"results": [EntityNetworkMembership, ...]}` - so you can point any entity you already have a UUID for at the matching endpoint without a separate lookup step.

| Entity            | Endpoint                                                                             | Resolves through                                          |
| ----------------- | ------------------------------------------------------------------------------------ | --------------------------------------------------------- |
| Session           | `GET .../sessions/{session_id}/networks/`                                            | The session's linked vendor user                          |
| Business session  | `GET .../business-sessions/{business_session_id}/networks/`                          | The business session's linked vendor business             |
| User              | `GET .../users/{vendor_user_uuid}/networks/`                                         | The vendor user directly                                  |
| Business          | `GET .../businesses/{vendor_business_uuid}/networks/`                                | The vendor business directly                              |
| Transaction       | `GET .../transactions/{transaction_uuid}/networks/`                                  | The transaction's backing KYC/KYB session's subject       |
| Transaction party | `GET .../transactions/{transaction_uuid}/parties/{transaction_party_uuid}/networks/` | The party itself (remitter, beneficiary, or counterparty) |

Each `EntityNetworkMembership` carries the network summary (`network`, same shape as [list networks](/management-api/networks/list)), the resolved `subject`, which `signal_types` connected it, `signal_count`, and `joined_at`/`last_seen_at`. An entity with no fraud connections returns an empty `results` array, not a 404.

<Note>
  The transaction endpoint resolves membership through the transaction's backing session's subject. The transaction party endpoint resolves it through the party itself, which is what you want for a remitter or beneficiary that is not the transaction's own KYC subject.
</Note>

## Related

* [List networks](/management-api/networks/list)
* [Get network](/management-api/networks/get)
* [Network members](/management-api/networks/members)


# List Network Signals
Source: https://docs.didit.me/management-api/networks/signals

GET /v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/signals/
List the signals (shared device, IP, face, document number, phone, email, or address values) that link this network's members.

<AgentPromptAccordion title="List Network Signals API Prompt" />

List the signals (shared device fingerprints, IP addresses, faces, document numbers, phone numbers, emails, or addresses) that link this network's members. This is the same data the graph's signal nodes carry, returned as a flat list.

<Note>
  Signal values themselves are never exposed. Every exact-match signal type (`ip_address`, `device`, `document_number`, `phone`, `email`, `address`) is identified by a keyed hash of its normalized value; `face` is matched by similarity search rather than a stored value at all.
</Note>

## Related

* [Get network](/management-api/networks/get)
* [Network members](/management-api/networks/members)
* [Network graph](/management-api/networks/graph)


# Get Network Timeline
Source: https://docs.didit.me/management-api/networks/timeline

GET /v3/organization/{organization_id}/application/{application_id}/networks/{network_uuid}/timeline/
Chronological events for this network: detection, each signal's observation, and lifecycle status changes.

<AgentPromptAccordion title="Network Timeline API Prompt" />

Retrieve the chronological event history for a network: when it was first detected, when each signal was observed, and every lifecycle status change with its reason. This backs the Console's timeline view of a network.

## Related

* [Get network](/management-api/networks/get)
* [Network signals](/management-api/networks/signals)
* [Network map](/management-api/networks/map)


# Create Questionnaire
Source: https://docs.didit.me/management-api/questionnaires/create

POST /v3/questionnaires/
Create a simple linear questionnaire. Send `form_elements` in display order; branching and repeatable groups require the Console. Defaults to `published` v1.

<AgentPromptAccordion title="Create Questionnaire API Prompt" />

Use this endpoint to create simple questionnaires through the API. Send a `form_elements` array in the order users should answer the questions. Didit builds the internal questionnaire graph for you.

The API supports simple linear questionnaires only. Do not send `graph`, `branches`, `next`, or conditional rules.

## Required fields

* `title` is the internal questionnaire name.
* `languages` must include `en`.
* `form_elements` must contain at least one question.
* Each form element needs an `element_type` and a translated `label`.

## Element types

Use lowercase values such as `short_text`, `multiple_choice`, `email`, `file_upload`, or `date_picker`. Uppercase enum values such as `SHORT_TEXT` are also accepted.

For `dropdown`, `single_choice`, and `multiple_choice`, add `options`. If you omit an option `value`, Didit generates one from the label.

```json theme={null}
{
  "title": "Customer Onboarding",
  "languages": ["en"],
  "default_language": "en",
  "form_elements": [
    {
      "id": "occupation",
      "element_type": "short_text",
      "label": { "en": "What is your occupation?" },
      "is_required": true
    },
    {
      "id": "source_of_funds",
      "element_type": "multiple_choice",
      "label": { "en": "Source of funds" },
      "is_required": true,
      "options": [
        { "value": "employment", "label": { "en": "Employment" } },
        { "value": "business", "label": { "en": "Business" } },
        { "value": "investments", "label": { "en": "Investments" } }
      ]
    }
  ]
}
```

## Field validation

Add an optional `validation` object to a `short_text`, `long_text`, or `number` element to enforce a format on the user's answer. This is useful for identifiers with strict formats such as tax IDs, national IDs, or card numbers. Validation runs while the user fills the field (the user cannot proceed until it passes) and is re-enforced by the API on submission.

| Field           | Applies to                | Description                                                                                                                               |
| --------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------- |
| `pattern`       | `short_text`, `long_text` | Regular expression the value must fully match. Use the portable ECMA-262 subset; do not add `^`/`$` anchors (the whole value is matched). |
| `min_length`    | `short_text`, `long_text` | Minimum number of characters.                                                                                                             |
| `max_length`    | `short_text`, `long_text` | Maximum number of characters.                                                                                                             |
| `min`           | `number`                  | Minimum numeric value.                                                                                                                    |
| `max`           | `number`                  | Maximum numeric value.                                                                                                                    |
| `error_message` | all of the above          | Translated message shown when the value does not pass. Falls back to a generic message if omitted.                                        |

```json theme={null}
{
  "title": "Customer Onboarding",
  "languages": ["en"],
  "default_language": "en",
  "form_elements": [
    {
      "id": "tax_id",
      "element_type": "short_text",
      "label": { "en": "Tax ID" },
      "is_required": true,
      "validation": {
        "pattern": "[A-Z]{2}[0-9]{9}",
        "min_length": 11,
        "max_length": 11,
        "error_message": { "en": "Enter a valid Tax ID (2 letters followed by 9 digits)." }
      }
    }
  ]
}
```

The response includes `questionnaire_id`. Store it, because you will use it as `questionnaire_uuid` when you add the questionnaire to a workflow.


# Delete Questionnaire
Source: https://docs.didit.me/management-api/questionnaires/delete

DELETE /v3/questionnaires/{questionnaire_uuid}/
Permanently delete one questionnaire version (no undo). Stored questionnaire responses linked to this version are deleted with it, and sessions referencing it lose the link; other versions in the same group are not deleted. Workflows that referenced it keep running but the questionnaire step can no longer load it.

<AgentPromptAccordion title="Delete Questionnaire API Prompt" />


# Get Questionnaire
Source: https://docs.didit.me/management-api/questionnaires/get

GET /v3/questionnaires/{questionnaire_uuid}/
Fetch full questionnaire detail for one version by `questionnaire_uuid`: title, `languages`, canonical `graph`, derived `sections`, and version metadata.

<AgentPromptAccordion title="Get Questionnaire API Prompt" />


# List Questionnaires
Source: https://docs.didit.me/management-api/questionnaires/list

GET /v3/questionnaires/
List your questionnaires, newest first, in a limit/offset pagination envelope (`{count, next, previous, results}`, default page size 50). Each row is one version; `questionnaire_group_id` is the stable group ID resolved to the latest `published` version.

<AgentPromptAccordion title="List Questionnaires API Prompt" />


# Update Questionnaire
Source: https://docs.didit.me/management-api/questionnaires/update

PATCH /v3/questionnaires/{questionnaire_uuid}/
Update a questionnaire. Versioning depends on the `status` field you send and the current state of the version: (1) no `status` on a **published** version → the published version is updated in place (same `questionnaire_id`, same `version`); (2) no `status` on a **draft** → the draft is updated and immediately published; (3) `status: "published"` on a **published** version → a NEW published version is created under the same `questionnaire_group_id` (new `questionnaire_id`, `version` + 1) and returned, and any existing draft in the group is deleted; (4) `status: "draft"` keeps a draft as a draft (autosave) but is rejected with 400 on a published version (`"Cannot revert a published version to draft."`).

<AgentPromptAccordion title="Update Questionnaire API Prompt" />

Use `PATCH` for partial updates. To rename a questionnaire, send only `title` or `description`.

```json theme={null}
{
  "title": "Updated Customer Onboarding"
}
```

To update questions, send the full desired `form_elements` array. This replaces the previous question list. Keep any existing questions you still want to show.

```json theme={null}
{
  "form_elements": [
    {
      "id": "occupation",
      "element_type": "short_text",
      "label": { "en": "What is your occupation?" },
      "is_required": true
    },
    {
      "id": "source_of_funds",
      "element_type": "multiple_choice",
      "label": { "en": "Source of funds" },
      "options": [
        { "value": "employment", "label": { "en": "Employment" } },
        { "value": "business", "label": { "en": "Business" } }
      ]
    }
  ]
}
```

The v3 API only supports simple linear questionnaires. It rejects `graph`, `branches`, `next`, and conditional rules.

The response includes `questionnaire_id`. When you update a `published` questionnaire, the API may create a new version. Capture the returned `questionnaire_id` and use it in workflows instead of assuming the id in the URL is still the latest version.


# Create Report From Case
Source: https://docs.didit.me/management-api/regulatory-reports/create-for-case

POST /v3/organization/{organization_id}/application/{application_id}/cases/{case_uuid}/regulatory-reports/
Create a draft FIU report for the case: DRAFT status, auto-populated from the optional template plus the case's subject, linked transactions, and narrative. Validate then finalize to produce the goAML XML and PDF.

<AgentPromptAccordion title="Create Report From Case API Prompt" />

Create a draft report scoped to a case. Prefer this over the standalone create endpoint when you already have the case open - it can omit `template` and derive `report_type`/`jurisdiction` directly.

## Related

* [List reports](/management-api/regulatory-reports/list)
* [Validate report](/management-api/regulatory-reports/validate)
* [Finalize report](/management-api/regulatory-reports/finalize)


# Get Report Download URL
Source: https://docs.didit.me/management-api/regulatory-reports/download-url

GET /v3/organization/{organization_id}/application/{application_id}/regulatory-reports/{report_uuid}/download-url/
Mint a presigned URL for a finalized report's goAML XML or PDF.

<AgentPromptAccordion title="Get Report Download URL API Prompt" />

Get a presigned download URL for a finalized report's goAML XML (for FIU portal submission) or PDF (for internal records).

## Related

* [Finalize report](/management-api/regulatory-reports/finalize)
* [List reports](/management-api/regulatory-reports/list)


# Finalize Report
Source: https://docs.didit.me/management-api/regulatory-reports/finalize

POST /v3/organization/{organization_id}/application/{application_id}/regulatory-reports/{report_uuid}/finalize/
Re-validate, then render the goAML XML and PDF and upload both to S3. On SAR/STR/TFR reports, this also moves the case's transaction alerts from Pending SAR to SAR filed.

<AgentPromptAccordion title="Finalize Report API Prompt" />

Finalize a report. This is the point of no return, a finalized report cannot be edited or deleted, only downloaded.

## Related

* [Download report](/management-api/regulatory-reports/download-url)
* [Validate report](/management-api/regulatory-reports/validate)
* [Print case](/management-api/cases/print)


# List Reports
Source: https://docs.didit.me/management-api/regulatory-reports/list

GET /v3/organization/{organization_id}/application/{application_id}/regulatory-reports/
Application-wide FIU report list, optionally filtered by status, report_type, or case.

<AgentPromptAccordion title="List Reports API Prompt" />

List reports app-wide, the same data behind the Console's standalone Reports page. This is the endpoint to poll for a queue of DRAFT reports awaiting validation and finalization.

## Related

* [Create standalone report](/management-api/regulatory-reports/create-for-case)
* [Validate report](/management-api/regulatory-reports/validate)
* [Download report](/management-api/regulatory-reports/download-url)


# Validate Report
Source: https://docs.didit.me/management-api/regulatory-reports/validate

POST /v3/organization/{organization_id}/application/{application_id}/regulatory-reports/{report_uuid}/validate/
Check the report against the obligatory goAML header fields (reporting entity ID, submission code, local currency, action taken, submission date), plus at least one attached transaction and a 2-letter jurisdiction, without generating any files. Also stores the result on the report: validation_errors and validated_at are updated, and a non-finalized report's status moves to VALIDATED (no errors) or back to DRAFT (errors).

<AgentPromptAccordion title="Validate Report API Prompt" />

Dry-run validation against the obligatory goAML fields, without generating XML or PDF. [Finalize](/management-api/regulatory-reports/finalize) re-validates internally, so calling this first is optional but useful for surfacing errors early.

## Related

* [Finalize report](/management-api/regulatory-reports/finalize)
* [Create report from case](/management-api/regulatory-reports/create-for-case)


# Create Report Template
Source: https://docs.didit.me/management-api/report-templates/create

POST /v3/organization/{organization_id}/application/{application_id}/report-templates/
Create a reusable per-jurisdiction, per-report-type goAML header template. Rejected with 400 if any of the template-level obligatory fields (rentity_id, submission_code, currency_code_local) is missing from field_config; an invalid template cannot be saved or used to create a report. Per-filing header fields (action, submission_date, transactions) are enforced at report validate/finalize time instead.

<AgentPromptAccordion title="Create Report Template API Prompt" />

Create a reusable goAML header template. A template must pass obligatory-field validation (`rentity_id`, `submission_code`, `currency_code_local`) to be saved, both on create and again whenever it is edited. Per-filing header fields such as `action` and `submission_date` are enforced when the report itself is validated or finalized, not on the template.

## Related

* [List report templates](/management-api/report-templates/list)
* [Create report from case](/management-api/regulatory-reports/create-for-case)


# List Report Templates
Source: https://docs.didit.me/management-api/report-templates/list

GET /v3/organization/{organization_id}/application/{application_id}/report-templates/
List FIU report templates for the application.

<AgentPromptAccordion title="List Report Templates API Prompt" />

List report templates for the application, one per jurisdiction and report type combination you file regularly.

## Related

* [Create report template](/management-api/report-templates/create)
* [Create report from case](/management-api/regulatory-reports/create-for-case)
* [FIU reports (Console)](/console/case-management/fiu-reports)


# Batch Delete Sessions
Source: https://docs.didit.me/management-api/sessions/batch-delete

POST /v3/sessions/delete/
Delete many KYC sessions by session number or all at once, with a per-session outcome that reports whether a biometric template was retained or deleted.

<AgentPromptAccordion title="Batch Delete Sessions Prompt" />

## Behavior

Each matched session is deleted exactly as by [Delete Session](/sessions-api/delete-session): the session, its decision and extracted data, its feature records, and all of its stored media are deleted, it disappears from every read endpoint, and previously issued media URLs stop resolving.

The response is `200 OK` with one result per matched session so that you can see what happened to each one.
A result confirms the session was deleted except when its `face_retention_outcome` is `failed_retryable`: that session was **not** deleted and its embedding is untouched, so treat that row as a failure to retry, never as deletion confirmation.
Numbers that do not match a live KYC session in your application are skipped and do not appear in `results`.

## Retention and instruction fields

The endpoint accepts the same optional fields as the single-session endpoint and applies them to every matched session:

| Field                     | Type                                                        | Description                                                                                                                                                      |
| ------------------------- | ----------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `retain_face_embeddings`  | boolean or null                                             | Override the application's `face_retention_policy` for this request.                                                                                             |
| `face_retention_days`     | integer (1-3650)                                            | Finite retention duration for retained templates. Required when retaining unless the application sets `face_retention_days`.                                     |
| `face_retention_deadline` | datetime (ISO 8601)                                         | Optional hard expiry, must be in the future.                                                                                                                     |
| `deletion_instruction`    | `operational_session_delete` (default) or `privacy_erasure` | `privacy_erasure` purges every retained template for each session's User before deleting the session and cannot be combined with `retain_face_embeddings: true`. |
| `instruction_id`          | string (max 255)                                            | Your durable reference for this instruction. Recorded on the audit trail and on every retained template.                                                         |

See [Delete Session](/sessions-api/delete-session#face-biometric-data-delete-or-retain) for what a retained template does and does not contain, how `expires_at` is computed, and what a privacy-erasure instruction does.

## Per-session outcomes

```json theme={null}
{
  "results": [
    { "session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02", "session_number": 1001, "face_retention_outcome": "deleted", "biometric_template_uuid": null },
    { "session_id": "b8e1d2c3-4f5a-4b6c-8d7e-9f0a1b2c3d4e", "session_number": 1002, "face_retention_outcome": "retained_with_user", "biometric_template_uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b" },
    { "session_id": "7a1e9c2d-5f4b-4c3a-8e2d-1b0a9f8e7d6c", "session_number": 1003, "face_retention_outcome": "ineligible_no_vendor_user", "biometric_template_uuid": null },
    { "session_id": "c1d2e3f4-a5b6-4c7d-8e9f-0a1b2c3d4e5f", "session_number": 1004, "face_retention_outcome": "failed_retryable", "biometric_template_uuid": null }
  ]
}
```

| `face_retention_outcome`    | Meaning                                                                                                                                                                                                                                                                        |
| --------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `deleted`                   | The session and its face embedding are deleted. Default behavior.                                                                                                                                                                                                              |
| `retained_with_user`        | The session is deleted. One image-free biometric template stays anchored to the User; its id is `biometric_template_uuid`.                                                                                                                                                     |
| `none`                      | The session had no face embedding to delete or retain.                                                                                                                                                                                                                         |
| `ineligible_no_vendor_user` | Retention was requested, but the session is not linked to a User, so nothing can anchor a template. The session and its embedding are deleted.                                                                                                                                 |
| `failed_retryable`          | A biometric store was unavailable while retaining or purging a template for this session. This session is **not** deleted and its embedding is untouched. Re-run the request for it; retries converge on a single template. Other sessions in the same request are unaffected. |

Sessions are processed one by one. A `failed_retryable` outcome on one session does not roll back the others.

## Examples

<Tabs>
  <Tab title="Delete by number">
    ```bash theme={null}
    curl -X POST https://verification.didit.me/v3/sessions/delete/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"session_numbers": ["1001", "1002", "1003"]}'
    ```
  </Tab>

  <Tab title="Delete and retain templates">
    ```bash theme={null}
    curl -X POST https://verification.didit.me/v3/sessions/delete/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "session_numbers": ["1001", "1002"],
        "retain_face_embeddings": true,
        "face_retention_days": 365,
        "instruction_id": "post-approval-cleanup-2026-08"
      }'
    ```
  </Tab>

  <Tab title="Privacy erasure">
    ```bash theme={null}
    curl -X POST https://verification.didit.me/v3/sessions/delete/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "session_numbers": ["1001"],
        "deletion_instruction": "privacy_erasure",
        "instruction_id": "dsar-2026-0142"
      }'
    ```
  </Tab>
</Tabs>

## Migration from 204 responses

Until this release the endpoint returned `204 No Content`. It now returns `200 OK` with `results[]`. Update clients that assert on `204`. The default deletion behavior is unchanged: existing applications stay on `delete_with_session` until you explicitly change the policy.

## Related

* [Delete Session](/sessions-api/delete-session)
* [Biometric templates](/management-api/biometric-templates/overview)
* [Data retention](/console/data-retention)


# Create Session Review
Source: https://docs.didit.me/management-api/sessions/create-review

POST /v3/sessions/{session_id}/reviews/
Append a note to a User Verification (KYC) session's review / activity feed. **This endpoint only records an entry — it never changes the session.** The session's `status` is left untouched, no status-transition validation runs, and no webhook fires. To actually approve, decline, or re-open a session (which also writes a fully-attributed `STATUS_UPDATED` entry to this feed), use `PATCH /v3/session/{session_id}/update-status/` instead.

Both body fields are optional and an empty JSON object is accepted. `new_status` is stored purely as a label on the entry and accepts any of the ten session status values (case-sensitive). `@email` mentions inside `comment` are stored as plain text only — they trigger no notifications on this endpoint, and the entry's `mentioned_emails` stays empty.

Note on attribution: entries created here carry no actor information. In the feed they show `actor_display: "Unknown"`, `actor_type: "CONSOLE_USER"`, and `activity_type: "STATUS_UPDATED"` (storage defaults), and the `201` body's `user` field is `"Unknown"`.

<AgentPromptAccordion title="Create Session Review Prompt" />


# List Session Reviews
Source: https://docs.didit.me/management-api/sessions/list-reviews

GET /v3/sessions/{session_id}/reviews/
Return the audit trail / activity feed for a User Verification (KYC) session, newest first, in a paginated envelope (`count` / `next` / `previous` / `results`, 50 entries per page by default).

Feed entries are written by every actor that touches the session: manual decisions made through `PATCH /v3/session/{session_id}/update-status/` (which records `previous_status` → `new_status`), Console reviewer activity (comments with `@email` mentions, KYC/POA data edits, file uploads/removals, tag changes, detail-page views), AML ongoing-monitoring matches, and notes appended via `POST` on this same path. Reading this feed is the API-side equivalent of the **Activity** panel in the Didit Console session view.

Only User Verification (KYC) sessions are addressable here; Business Verification (KYB) session IDs return `404`.

<AgentPromptAccordion title="List Session Reviews Prompt" />


# Create Transaction
Source: https://docs.didit.me/management-api/transactions/create

POST /v3/transactions/
Submit a transaction for synchronous AML/risk monitoring. The transaction is created `APPROVED`, then your rules (and crypto screening, when applicable) run inline and may flip the returned `status` to `IN_REVIEW` or `DECLINED`. **`transaction_id` is your idempotency key** (max 128 chars, unique per app); reusing it returns 400. A `transaction.created` webhook is dispatched on success (sandbox applications are not billed and do not emit webhooks).

<AgentPromptAccordion title="Create Transaction API Prompt" />


# Get Transaction
Source: https://docs.didit.me/management-api/transactions/get

GET /v3/transactions/{transaction_id}/
Retrieve the full monitoring record for one transaction: parties, score/severity, rule runs, alerts, Travel Rule outcome, remediation session.

<AgentPromptAccordion title="Get Transaction API Prompt" />


# Get Transaction (SDK Token)
Source: https://docs.didit.me/management-api/transactions/get-sdk

GET /v1/transactions/{transaction_id}/
Device-facing read endpoint, authenticated with the same `X-Transaction-Token` used to submit. The SDKs poll it after an auto-launched action flow completes or its window closes, so the final state never depends on a single notification. Returns the same transaction detail as the submit response, including the current `action_required` block (`null` once the action is resolved).

<AgentPromptAccordion title="Get Transaction (SDK Token) API Prompt" />


# List Transactions
Source: https://docs.didit.me/management-api/transactions/list

GET /v3/transactions/
Paginated list of monitored transactions, newest first (`txn_date` desc). `count` is capped at 100; use `total_transactions` for the true row count. This endpoint does not support filtering or search parameters.

<AgentPromptAccordion title="List Transactions API Prompt" />


# Backtest Rules
Source: https://docs.didit.me/management-api/transactions/rules-backtest

POST /v3/transactions/rules/backtest/
Evaluate a hypothetical rule configuration against your recent transactions (most recent first, up to the backtest cap) without creating a rule or touching any transaction. Use it before activating a rule to see how often it would have matched and how many subjects it would have affected.

<AgentPromptAccordion title="Backtest Rules API Prompt" />


# Create Rule
Source: https://docs.didit.me/management-api/transactions/rules-create

POST /v3/transactions/rules/
Create a CUSTOM transaction-monitoring rule. Titles are unique per application (duplicate -> 400). A `change_status` action targeting `AWAITING_USER` must carry `workflow_id`. Rules created in ACTIVE mode apply to new transactions immediately - the recommended workflow is create in TEST mode, backtest, then switch mode to ACTIVE.

<AgentPromptAccordion title="Create Rule API Prompt" />


# Delete Rule
Source: https://docs.didit.me/management-api/transactions/rules-delete

DELETE /v3/transactions/rules/{rule_uuid}/
Delete a CUSTOM rule. Deletion is immediate and permanent: the rule stops evaluating for new transactions and disappears from listings, while past rule runs on already-evaluated transactions keep their recorded results. Library rules cannot be deleted - uninstall them via the install endpoint instead (they can always be reinstalled from the library).

<AgentPromptAccordion title="Delete Rule API Prompt" />


# Get Rule
Source: https://docs.didit.me/management-api/transactions/rules-get

GET /v3/transactions/rules/{rule_uuid}/
Retrieve one rule with its full configuration and execution counters.

<AgentPromptAccordion title="Get Rule API Prompt" />


# Install Library Rules
Source: https://docs.didit.me/management-api/transactions/rules-install

POST /v3/transactions/rules/install/
Install one or more presets onto the application, by `library_keys` or a whole `bundle`. Installed presets evaluate immediately in their default mode; already-installed keys are skipped.

<AgentPromptAccordion title="Install Library Rules API Prompt" />


# List Rule Library
Source: https://docs.didit.me/management-api/transactions/rules-library

GET /v3/transactions/rules/library/
Browse the full preset rule library (150+ rules) with each entry's complete configuration and an `is_installed` flag for this application. Filter by bundle, category, or free-text search.

<AgentPromptAccordion title="List Rule Library API Prompt" />


# List Rules
Source: https://docs.didit.me/management-api/transactions/rules-list

GET /v3/transactions/rules/
List the application's transaction-monitoring rules: your custom rules plus any library presets you have installed. Filter by source, category, mode, bundle or free-text search; order with `ordering` (run_count, approved_pct, reviewed_pct, declined_pct, latest_triggered_at, title, created_at, source, each with an optional `-` prefix).

<AgentPromptAccordion title="List Rules API Prompt" />


# Uninstall Library Rules
Source: https://docs.didit.me/management-api/transactions/rules-uninstall

DELETE /v3/transactions/rules/install/
Remove installed presets from the application, by `library_keys` or a whole `bundle`. Uninstalled presets stop evaluating immediately and can be reinstalled from the library at any time.

<AgentPromptAccordion title="Uninstall Library Rules API Prompt" />


# Update Rule
Source: https://docs.didit.me/management-api/transactions/rules-update

PATCH /v3/transactions/rules/{rule_uuid}/
Partially update a rule. Custom rules accept every configuration field. Library (PRESET) rules accept only `mode` - use it to activate, disable, or switch a preset to TEST; any other field returns 400.

<AgentPromptAccordion title="Update Rule API Prompt" />


# Screen Wallet
Source: https://docs.didit.me/management-api/transactions/screen-wallet

POST /v3/wallet-screening/
Run on-demand AML screening for a single crypto wallet/address without creating a transaction. Resolves your application's configured blockchain analytics provider (Merkle Science or Crystal), screens the address synchronously, and returns the normalised risk result. Nothing is written to the transactions table. One AML monitoring usage is billed per successful screening (sandbox applications are not billed).

<AgentPromptAccordion title="Screen Wallet API Prompt" />


# Screen Wallet PDF
Source: https://docs.didit.me/management-api/transactions/screen-wallet-pdf

POST /v3/wallet-screening/pdf/
Stateless companion to `POST /v3/wallet-screening/`: repost the exact JSON body that endpoint returned — including the `report_signature` it added — and get back a Didit-branded PDF of the same result. No provider is called and nothing is billed or persisted; this only re-renders a result Didit already produced. The signature ties the PDF to an unmodified result: editing `risk_score`, `severity`, `sanctions_hit`, or any other signed field before reposting fails with `400`.

<AgentPromptAccordion title="Screen Wallet PDF Prompt" />

## Why it's stateless

Standalone wallet screening writes nothing to the transactions table, so there is no stored record for this endpoint to render from. Instead, you repost the exact JSON that `POST /v3/wallet-screening/` already gave you, and Didit renders that payload into a PDF without calling a provider again.

## The `report_signature` field

Every `POST /v3/wallet-screening/` response now includes a `report_signature` field — an opaque signature scoped to your application. This endpoint verifies it before rendering, so a caller can't edit `risk_score`, `severity`, `sanctions_hit`, or any other field and get a clean-looking Didit-branded PDF for a result Didit never produced.

Always repost the full response body **unmodified**, including `report_signature`. Reordering keys is fine; changing any signed value is not.

```bash theme={null}
# 1. Run the screening and save the full response
RESULT=$(curl -s -X POST https://verification.didit.me/v3/wallet-screening/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wallet_address": "0x28c6c06298d514db089934071355e5743bf21d60", "blockchain": "ETH"}')

# 2. Repost it verbatim to render the PDF
curl -X POST https://verification.didit.me/v3/wallet-screening/pdf/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$RESULT" \
  -o wallet_screening_report.pdf
```

## Billing

No provider call is made and nothing is billed — this only re-renders a result you already paid for when you called `POST /v3/wallet-screening/`.

## Errors

| Status | Meaning                                                                                                                                       |
| ------ | --------------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | Body is not a JSON object matching the wallet-screening result shape, or `report_signature` is missing or does not match the reposted fields. |
| `401`  | Missing or invalid `x-api-key`.                                                                                                               |

## Next steps

<CardGroup>
  <Card title="Screen Wallet" icon="code" href="/management-api/transactions/screen-wallet">
    Run the underlying on-demand wallet screening and get the JSON result to repost here.
  </Card>

  <Card title="On-demand wallet screening" icon="link" href="/transaction-monitoring/wallet-screening">
    Overview of the standalone wallet-screening endpoint and result model.
  </Card>
</CardGroup>


# Mint SDK Transaction Token
Source: https://docs.didit.me/management-api/transactions/sdk-token

POST /v3/transactions/sdk-token/
Mint a short-lived scoped token your app passes to the Didit SDKs so they can submit transactions directly from the end-user's device via `POST /v1/transactions/`. The token is bound to one `vendor_data` (your user id): every transaction submitted with it has its subject identity enforced server-side from that binding, so a tampered client cannot submit on behalf of another user. Mint tokens from your backend - never ship the API key itself in an app. camelCase aliases (`vendorData`, `ttlSeconds`, `maxUses`) are also accepted.

<AgentPromptAccordion title="Mint SDK Transaction Token API Prompt" />


# Submit Transaction (SDK Token)
Source: https://docs.didit.me/management-api/transactions/submit-sdk

POST /v1/transactions/
Device-facing endpoint the Didit SDKs call to submit a transaction directly from the end-user's device. Authentication is a scoped token from `POST /v3/transactions/sdk-token/` sent in the `X-Transaction-Token` header instead of an API key, and the endpoint is CORS-enabled so browsers can call it cross-origin. The payload uses the camelCase wire aliases shown below (the SDK `submitTransaction` methods build it for you). Three server-side guarantees: the application is always taken from the token; the subject identity (`externalUserId`) is always enforced from the token's `vendor_data`, so spoofed payload values are ignored; and device intelligence (the SDK device fingerprint plus server-derived IP and user agent) is attached to the subject automatically.

<AgentPromptAccordion title="Submit Transaction (SDK Token) API Prompt" />


# Confirm or Deny Wallet Ownership
Source: https://docs.didit.me/management-api/travel-rule/confirm-ownership

POST /v3/transactions/{transaction_id}/travel-rule/ownership/
Called by the beneficiary's application when its INTERNAL-rail transfer is UNCONFIRMED_OWNERSHIP. Confirming marks the matching wallet address book entry as ownership-verified and runs the beneficiary name match on both sides of the transfer; denying declines both sides.

<AgentPromptAccordion title="Confirm Wallet Ownership API Prompt" />


# Register Wallet Address
Source: https://docs.didit.me/management-api/travel-rule/create-wallet-address

POST /v3/travel-rule/wallet-addresses/
Add an entry to your Travel Rule wallet address book so inbound INTERNAL-rail transfers can resolve against it.

<AgentPromptAccordion title="Register Wallet Address API Prompt" />


# Mint Wallet-Ownership Widget Session
Source: https://docs.didit.me/management-api/travel-rule/create-widget-session

POST /v3/travel-rule/widget-session/
Mint a hosted wallet-ownership widget URL/token. Send the customer to the returned url to prove control of a wallet (message signing, Satoshi test, screenshot, or self-declaration). The widget is web-only in this release - open the url in the system browser or a custom tab, never inside a mobile SDK webview.

<AgentPromptAccordion title="Mint Wallet-Ownership Widget Session API Prompt" />


# Delete Wallet Address
Source: https://docs.didit.me/management-api/travel-rule/delete-wallet-address

DELETE /v3/travel-rule/wallet-addresses/{entry_uuid}/
Deletes the entry. It stops matching new transfers immediately and the address is freed up for re-registration.

<AgentPromptAccordion title="Delete Wallet Address API Prompt" />


# Get Email Pickup Info
Source: https://docs.didit.me/management-api/travel-rule/get-pickup

GET /v3/travel-rule/pickup/{token}/
Public, unauthenticated. Lets a non-Didit counterparty VASP preview the pending exchange from the emailed pickup link. The token itself is the authentication.

<AgentPromptAccordion title="Get Email Pickup Info API Prompt" />


# Get Travel Rule Settings
Source: https://docs.didit.me/management-api/travel-rule/get-settings

GET /v3/travel-rule/settings/
Read the application's Travel Rule settings and VASP profile. Auto-creates a default (disabled) settings row and an empty profile on first read.

<AgentPromptAccordion title="Get Travel Rule Settings API Prompt" />

## Network availability

GTR, TRUST, VerifyVASP, and Sygna all require an active membership. GTR is not automatically included with Didit. Read `networks` for the application you are configuring:

* **`own`** - Your connected membership takes precedence, even if the network is in `disabled_networks`. Exchanges use your network identity.
* **`didit`** - Platform membership is configured and you have not disabled it. No customer membership credentials are needed for this network.
* **`off`** - You disabled platform routing and have no connected own membership. Remove the network from `disabled_networks` to allow platform routing when available, or connect your own membership.
* **`unavailable`** - Neither a connected own membership nor an enabled platform membership is available. Connect your own membership in **Marketplace**, or use a reachable `INTERNAL`, `TRP`, or `EMAIL` counterparty.

`platform_available` is configuration status, not a live network health check. `connected` reports a saved membership that passed local credential validation, not a successful exchange with the provider. Enabling `is_enabled` or clearing `disabled_networks` cannot provision a missing membership.

For checks you can run without network credentials, see [Testing without network credentials](/transaction-monitoring/travel-rule#testing-without-network-credentials).


# Get Widget Context
Source: https://docs.didit.me/management-api/travel-rule/get-widget-context

GET /v3/travel-rule/widget/{token}/
Public read endpoint keyed by the widget session token - no API key required. Returns the widget context plus the status of every proof, so you can poll it to detect completion; completed_at becomes non-null once a proof is verified. A SATOSHI_TEST proof can sit at status PENDING while its deposit is seen on-chain but unconfirmed - a background job automatically rechecks it and completes it once the deposit confirms, so no client action is needed while it waits. Each proof carries the fields its method needs: deposit_address, expected_amount, and its own expires_at for SATOSHI_TEST; challenge for MESSAGE_SIGNING. Prefer the travel_rule.status.updated webhook over polling when the session is linked to a transfer.

<AgentPromptAccordion title="Get Widget Context API Prompt" />


# List Wallet Addresses
Source: https://docs.didit.me/management-api/travel-rule/list-wallet-addresses

GET /v3/travel-rule/wallet-addresses/
Paginated list of your application's Travel Rule wallet address book, newest first.

<AgentPromptAccordion title="List Wallet Addresses API Prompt" />


# Register Inbound (Sunrise) Transfer
Source: https://docs.didit.me/management-api/travel-rule/register-inbound

POST /v3/travel-rule/inbound/
Register Travel Rule data for a crypto deposit that already settled on-chain before any exchange took place. Creates an inbound travelRule transaction (or reuses an unclaimed deposit) and resolves the transfer against your wallet address book. A transaction.created webhook fires for newly-created transactions.

<AgentPromptAccordion title="Register Inbound Sunrise Transfer API Prompt" />


# Respond to Email Pickup
Source: https://docs.didit.me/management-api/travel-rule/respond-pickup

POST /v3/travel-rule/pickup/{token}/respond/
Public, unauthenticated. Accepts or declines the exchange from the emailed pickup link. On accept, beneficiary_name is checked against the originator's name_matching_strictness policy.

<AgentPromptAccordion title="Respond to Email Pickup API Prompt" />


# Search the VASP Directory
Source: https://docs.didit.me/management-api/travel-rule/search-vasps

GET /v3/travel-rule/vasps/
Paginated search across discoverable Didit customers with Travel Rule enabled, plus VASPs catalogued in the internal counterparty registry. Excludes your own application's profile.

<AgentPromptAccordion title="VASP Directory Search API Prompt" />


# Update Travel Rule Settings
Source: https://docs.didit.me/management-api/travel-rule/update-settings

PUT /v3/travel-rule/settings/
Upsert the application's Travel Rule settings and VASP profile. Partial update — only send the fields you want to change. Setting `is_enabled: true` requires a non-blank `legal_name` (already stored or included in the same request), otherwise returns 400.

<AgentPromptAccordion title="Update Travel Rule Settings API Prompt" />


# Finish, Cancel, or Resend a Transfer
Source: https://docs.didit.me/management-api/travel-rule/update-transfer

PATCH /v3/transactions/{transaction_id}/travel-rule/
Provide `payment_txn_id` to report the on-chain hash and move an outbound COMPLETED transfer to FINISHED (its INTERNAL-rail counterpart also moves to FINISHED), `{"action": "cancel"}` to cancel a non-terminal transfer, or `{"action": "resend"}` to re-run routing for an outbound transfer stuck in COUNTERPARTY_VASP_NOT_FOUND, COUNTERPARTY_VASP_NOT_REACHABLE, or NOT_ENOUGH_COUNTERPARTY_DATA (improve the counterparty data first, e.g. add a travel_address to the destination wallet entry).

<AgentPromptAccordion title="Travel Rule Transfer Actions API Prompt" />


# Update Wallet Address
Source: https://docs.didit.me/management-api/travel-rule/update-wallet-address

PATCH /v3/travel-rule/wallet-addresses/{entry_uuid}/
Partial update of holder_name, holder_vendor_data, entity_type, and travel_address. Setting travel_address attaches a TRP routing address to the entry; invalid values are rejected with 400. The response echoes only these four fields.

<AgentPromptAccordion title="Update Wallet Address API Prompt" />


# Create User
Source: https://docs.didit.me/management-api/users/create

POST /v3/users/create/
Pre-create a [user](/entities/users) by `vendor_data` *without* a verification session. `vendor_data` must be unique among non-deleted users for the application (exact match; conflicts return 400). Not idempotent.

<AgentPromptAccordion title="Create User Prompt" />

## Overview

Explicitly creates a [User entity](/entities/users/overview) before any session is run. The returned entity lands in `ACTIVE` status unless you specify otherwise.

## When to use it

* **Pre-seed metadata** (tier, signup source, internal tags) before the customer verifies.
* **Migrate from another vendor** — recreate your existing user roster in Didit so history and analytics start from a known baseline.
* **Import trusted profile faces** — create the User first, then call [Upload User Face](/management-api/users/upload-face) with the returned `didit_internal_id`.
* **Transaction-only use cases** — register a User with `vendor_data` so you can submit transactions without ever running a User Verification (KYC) session.

## Notes

* `vendor_data` is required and must be unique per application. Attempting to create a duplicate returns a conflict error — use [`PATCH /v3/users/{vendor_data}/`](/management-api/users/update) to update an existing user.
* `vendor_data` has a hard limit of 2000 bytes (UTF-8 encoded). A value over that limit returns a 400 validation error instead of being accepted.
* Fields that are normally derived from verified sessions (`full_name`, `date_of_birth`) can be seeded here but may be **overwritten** by the first approved User Verification (KYC) session.
* Face images are not accepted by this endpoint. To attach a trusted imported face, use [`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`](/management-api/users/upload-face) after this endpoint returns `didit_internal_id`.
* Creating a user emits a `user.data.updated` webhook.

## Permissions

Any active API key of the application can call this endpoint. Didit API keys are
**application-scoped, not role-scoped**: the Console's [roles and permissions](/console/roles-permissions)
(`create:users` and the rest) decide what a *person* can do in the Console, and are not evaluated
for Management API traffic. Control who can call this endpoint by controlling who can read
the application's API key.

## Related

* [User data model](/entities/users/data-model)
* [Upload User Face](/management-api/users/upload-face)
* [Vendor data linking](/entities/vendor-data-linking)
* [User operations](/entities/users/operations)


# Batch Delete Users
Source: https://docs.didit.me/management-api/users/delete

POST /v3/users/delete/
**Permanently delete** users — the user records are removed permanently. For everyday blocking prefer [Update User Status](#patch-/v3/users/-vendor_data-/update-status/) with `BLOCKED`. Select users with `vendor_data_list`, with `didit_internal_id_list`, or with both at once; or pass `delete_all: true`. The Console's `filter_*` batch params are rejected with a `400` rather than ignored, so a narrowed intent can never turn into a full wipe.

**Biometric templates:** every image-free biometric template retained for these users after session deletion (see `/v3/biometric-templates/`) is purged before the user is deleted, so the person stops matching in duplicate detection and Face Search. If a template cannot be purged because a biometric store is unavailable, the call returns `503`, no user in the request is deleted, and repeating the request finishes the job.

<AgentPromptAccordion title="Batch Delete Users Prompt" />

## Overview

Deletes one or more [User entities](/entities/users/overview). The user records are removed permanently. Their verification sessions are not covered by this endpoint and survive with their link to the user cleared; delete them with [Delete Session](/sessions-api/delete-session) or [Batch Delete Sessions](/management-api/sessions/batch-delete). Transactions are not covered either; delete those from the Console.

## When to use it

* **Right-to-be-forgotten** requests (GDPR / CCPA).
* **Clean-up** of test users during QA.
* **Deprovisioning** users removed from your own platform.

## Notes

* Accepts a list of `vendor_data` values, a list of `didit_internal_id` values, or `delete_all: true`. The two lists can be combined and are OR'd.
* The Console's `filter_*` batch params are rejected with a `400`. This endpoint has no Users table to narrow, and silently ignoring them on `delete_all` would delete every user in the application.
* All-or-nothing: if the deletion cannot be completed for the users you selected, none of them is deleted and you can safely repeat the same request.
* Idempotent — re-sending the same list returns `deleted: 0` after the first run.
* Returns only a count of what was deleted, not a per-item report. Values that matched nothing are skipped silently. Send a de-duplicated list if you want to compare `deleted` against the number of identifiers you sent, since a repeated identifier is only counted once.
* No webhook is emitted for a deletion. Webhooks fire on user status and data changes, not on delete — so an integration that needs a deletion signal must record it on its own side.
* Verification sessions linked to the user are NOT deleted by this endpoint. They remain, with their link to the user cleared, so their documents, faces and media are only removed once you delete the sessions themselves.
* Retained [biometric templates](/management-api/biometric-templates/overview) anchored to the user ARE purged, before the user is deleted. If a template cannot be purged because a biometric store is unavailable, the call returns `503`, no user in the request is deleted, and repeating the request finishes the job.

## Permissions

Any active API key of the application can call this endpoint. Didit API keys are
**application-scoped, not role-scoped**: the Console's [roles and permissions](/console/roles-permissions)
(`delete:users` and the rest) decide what a *person* can do in the Console, and are not evaluated
for Management API traffic. Control who can call this endpoint by controlling who can read
the application's API key.

## Related

* [Data retention](/console/data-retention)
* [Audit logs](/console/audit-logs)
* [User operations](/entities/users/operations)
* [Biometric templates](/management-api/biometric-templates/overview)


# Get User
Source: https://docs.didit.me/management-api/users/get

GET /v3/users/{vendor_data}/
Fetch one [user](/entities/users) by `vendor_data` (exact match). Adds `metadata`, `comments`, and `updated_at` to the list view, and switches `tags` to the detailed tag-link shape.

<AgentPromptAccordion title="Get User Prompt" />

## Overview

Returns a single [User entity](/entities/users/overview) keyed by `vendor_data`. Responses include `didit_internal_id` — Didit's stable internal identifier.

## When to use it

* **Lookup** a user's current verification state — the `features` map gives you the latest status of every feature in a single object.
* **Detail views** in your own UI — pull the profile on demand before rendering.
* **Risk scoring** — combine session counters and `features` to score each user on your side.

## Notes

* `vendor_data` in the URL is case-sensitive.
* Returns `404` if no user with that `vendor_data` exists in the application.
* Aggregate counters (`session_count`, `approved_count`, `declined_count`, `in_review_count`) update in real time as sessions complete.
* See the [User data model](/entities/users/data-model) for every field.

## Permissions

Any active API key of the application can call this endpoint. Didit API keys are
**application-scoped, not role-scoped**: the Console's [roles and permissions](/console/roles-permissions)
(`read:users` and the rest) decide what a *person* can do in the Console, and are not evaluated
for Management API traffic. Control who can call this endpoint by controlling who can read
the application's API key.

## Related

* [Users overview](/entities/users/overview)
* [Data model](/entities/users/data-model)
* [List users](/management-api/users/list)


# List Users
Source: https://docs.didit.me/management-api/users/list

GET /v3/users/
List [users](/entities/users) Didit assembles from KYC sessions sharing the same `vendor_data` (free-form string, NOT a UUID), plus users created via the API. Paginated, ordered by `last_session_at` desc. This endpoint does not support filtering or search parameters — fetch pages and filter client-side.

<AgentPromptAccordion title="List Users Prompt" />

## Overview

Returns a paginated list of [User entities](/entities/users/overview) for the authenticated application. Use this to sync users to your warehouse, find users needing analyst attention, or search by display name.

## When to use it

* **Periodic sync** of your user table to an external BI or warehouse.
* **Analyst queues** — filter by `status=FLAGGED` or stale `last_activity_at` to drive a review inbox.
* **Search** users by `display_name`, `full_name`, or `vendor_data`.

## Filters and pagination

| Query parameter                               | Description                                                                    |
| --------------------------------------------- | ------------------------------------------------------------------------------ |
| `status`                                      | Filter by `ACTIVE`, `FLAGGED`, or `BLOCKED`.                                   |
| `search`                                      | Substring match on `vendor_data`, `display_name`, `full_name`, emails, phones. |
| `country_code`                                | Filter by `issuing_states` (ISO 3166-1 alpha-3).                               |
| `created_after`, `created_before`             | Creation date window (ISO 8601).                                               |
| `last_activity_after`, `last_activity_before` | Activity window.                                                               |
| `page_size`                                   | 1–200. Default: 50.                                                            |
| `cursor`                                      | Pagination cursor returned in the previous response.                           |

## Notes

* Each response item includes `didit_internal_id`. `vendor_data` may be `null` when the original session or transaction did not provide one.
* This endpoint paginates via cursor — persist the `next` cursor between calls and stop when `next` is empty.
* See the [User data model](/entities/users/data-model) for all fields on a user row.

## Permissions

Any active API key of the application can call this endpoint. Didit API keys are
**application-scoped, not role-scoped**: the Console's [roles and permissions](/console/roles-permissions)
(`list:users` and the rest) decide what a *person* can do in the Console, and are not evaluated
for Management API traffic. Control who can call this endpoint by controlling who can read
the application's API key.

## Related

* [Users overview](/entities/users/overview)
* [Get user](/management-api/users/get)
* [User operations](/entities/users/operations)


# Update User
Source: https://docs.didit.me/management-api/users/update

PATCH /v3/users/{vendor_data}/
Partial update of a user: `display_name`, `full_name`, `date_of_birth`, `status`, `metadata`, `approved_emails`/`approved_phones`/`issuing_states`. `metadata` fully replaces. **Note:** unlike [Update User Status](#patch-/v3/users/-vendor_data-/update-status/), changing `status` here does NOT record a status-change activity and does NOT sync the system blocklist — use the dedicated update-status endpoint for `BLOCKED`/unblock flows.

<AgentPromptAccordion title="Update User Prompt" />

## Overview

Updates mutable fields on a [User entity](/entities/users/overview). Fields propagated from verified User Verification (KYC) sessions (`full_name`, `date_of_birth`, `portrait_image`, aggregate counters, `features`) are read-only.

## When to use it

* **Update your own metadata** — move a user between tiers, change tags, record an internal note.
* **Rename** — set a better `display_name` for internal-facing console views.
* **Override verified data** (with caution) — manual overrides are allowed but logged to the audit trail.

## Notes

* `vendor_data` in the URL cannot be changed via this endpoint. Create a new user and delete the old one if you need to rekey.
* Emits a `user.data.updated` webhook with a `changed_fields` array so consumers can sync efficiently.
* If you PATCH a field that is currently managed by a verified session, the override will be accepted but flagged in the [audit log](/console/audit-logs).

## Permissions

Any active API key of the application can call this endpoint. Didit API keys are
**application-scoped, not role-scoped**: the Console's [roles and permissions](/console/roles-permissions)
(`update:users` and the rest) decide what a *person* can do in the Console, and are not evaluated
for Management API traffic. Control who can call this endpoint by controlling who can read
the application's API key.

## Related

* [User operations](/entities/users/operations)
* [Data model](/entities/users/data-model)
* [Update status](/management-api/users/update-status)


# Update User Status
Source: https://docs.didit.me/management-api/users/update-status

PATCH /v3/users/{vendor_data}/update-status/
Flip only the lifecycle `status` of a user — `ACTIVE`/`FLAGGED`/`BLOCKED` (NOT session statuses). `BLOCKED` adds the `vendor_data` to the system blocklist; moving away from `BLOCKED` removes that entry. Each change is recorded as a `STATUS_CHANGED` activity on the user.

<AgentPromptAccordion title="Update User Status Prompt" />

## Overview

Moves a [User entity](/entities/users/overview) between `ACTIVE`, `FLAGGED`, and `BLOCKED`. See [entity lifecycle](/entities/lifecycle) for the full state machine.

## When to use it

* **Block a user** after confirming fraud or a compliance breach.
* **Flag a user** pending manual review without hard-blocking them.
* **Unblock** a user after successful remediation.
* **Propagate external signals** — e.g. when your own fraud engine scores a user above a threshold, move them to `FLAGGED` via this endpoint.

## Notes

* Valid values: `ACTIVE`, `FLAGGED`, `BLOCKED`. Invalid values return 400.
* Passing a `reason` string is recommended — it is persisted and surfaced in the [audit log](/console/audit-logs) and webhook payload.
* `BLOCKED` users have all new sessions auto-declined and all new transactions auto-declined.
* Emits a `user.status.updated` webhook with `previous_status`, `status`, and `reason`.

## Enforcement

| Status    | Effect on new sessions              | Effect on new transactions                      |
| --------- | ----------------------------------- | ----------------------------------------------- |
| `ACTIVE`  | Normal flow                         | Normal flow                                     |
| `FLAGGED` | Permitted but routed to `IN_REVIEW` | Permitted; may auto-escalate depending on rules |
| `BLOCKED` | Auto-declined                       | Auto-declined                                   |

## Permissions

Any active API key of the application can call this endpoint. Didit API keys are
**application-scoped, not role-scoped**: the Console's [roles and permissions](/console/roles-permissions)
(`update-status:users` and the rest) decide what a *person* can do in the Console, and are not evaluated
for Management API traffic. Control who can call this endpoint by controlling who can read
the application's API key.

## Related

* [Entity lifecycle](/entities/lifecycle)
* [User blocklist](/entities/users/blocklist)
* [Entity webhooks](/entities/webhooks)


# Upload User Face
Source: https://docs.didit.me/management-api/users/upload-face

POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/
Attach a trusted imported face image to an existing User profile. Use this after creating or retrieving a User by `vendor_data` and reading its `didit_internal_id`. The uploaded face is stored on the User profile and indexed for duplicate detection and face search. It is not added to a face blocklist.

<AgentPromptAccordion title="Upload User Face Prompt" />

## Overview

Use this endpoint when you import Users from another provider and already have a trusted face image for each person. The User remains keyed by your `vendor_data`, but this profile attachment endpoint uses `didit_internal_id` so the target User is unambiguous.

<Note>
  This is different from [Upload face to list](/management-api/lists/upload-face). Profile upload attaches a face to a User for evidence, duplicate detection, and face search. List upload adds a face to a face-type blocklist so future matching sessions can be rejected.
</Note>

## Endpoint

**`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`**

## Migration flow

<Steps>
  <Step title="Create or find the User">
    Call [`POST /v3/users/create/`](/management-api/users/create) for a new profile, or [`GET /v3/users/{vendor_data}/`](/management-api/users/get) for an existing one.
  </Step>

  <Step title="Store didit_internal_id">
    The User response includes `didit_internal_id`. Keep using `vendor_data` in your database; use `didit_internal_id` only for profile attachment endpoints.
  </Step>

  <Step title="Upload the face">
    Send a raw base64 image in the `image` field. The backend validates image decoding, image size, and face detection before saving it.
  </Step>
</Steps>

## Example

```bash theme={null}
# 1. Create the User keyed by your external id
curl -X POST https://verification.didit.me/v3/users/create/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-42",
    "display_name": "Jane Doe",
    "metadata": { "previous_provider": "legacy-kyc-vendor" }
  }'

# 2. Upload an imported face to the returned didit_internal_id
curl -X POST https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/upload/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "image": "<base64-encoded-jpg-or-png>",
    "comment": "Imported from previous KYC provider"
  }'
```

## Request body

| Field     | Type   | Required | Description                                                                                     |
| --------- | ------ | -------- | ----------------------------------------------------------------------------------------------- |
| `image`   | string | Yes      | Raw base64-encoded JPG or PNG. Do not include `data:image/...;base64,`. Max decoded size: 2 MB. |
| `comment` | string | No       | Operator-visible note shown on the User profile.                                                |

## Response

```json theme={null}
{
  "uuid": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "image_url": "https://signed-url.example/face.jpg",
  "comment": "Imported from previous KYC provider",
  "uploaded_by": "api",
  "created_at": "2026-05-18T12:00:00Z"
}
```

## Validation and limits

* Max 5 manually uploaded faces per User.
* Max decoded image size is 2 MB.
* The image must be valid base64 and decode as an image.
* The image must contain a detectable face. Use a frontal, well-lit face crop when possible.
* The uploaded face is indexed for future duplicate detection and face search.
* The uploaded face is not automatically blocklisted.

## List or delete uploaded faces

List profile faces:

```bash theme={null}
curl https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/ \
  -H "x-api-key: YOUR_API_KEY"
```

Delete one profile face:

```bash theme={null}
curl -X DELETE https://verification.didit.me/v3/organization/$ORGANIZATION_ID/application/$APPLICATION_ID/vendor-users/by-id/$DIDIT_INTERNAL_ID/faces/$FACE_UUID/ \
  -H "x-api-key: YOUR_API_KEY"
```

## Permissions

Use an API key for the same application. The key must belong to an app allowed to manage the target User profile.

## Failure modes

* `400` — invalid base64, invalid image, no detectable face, image over 2 MB, or the User already has 5 uploaded faces.
* `401` — missing or invalid credentials.
* `403` — API key is valid but not allowed to manage this User profile.
* `404` — no User exists for that `didit_internal_id` in the application.
* `429` — rate-limited; back off using `Retry-After`.

## Related

* [Create User](/management-api/users/create)
* [Get User](/management-api/users/get)
* [Import and Export Users](/entities/users/import-export)
* [Faces and Biometrics](/entities/users/faces-and-biometrics)
* [Upload face to blocklist](/management-api/lists/upload-face)


# Create Webhook Destination
Source: https://docs.didit.me/management-api/webhook/create-destination

POST /v3/webhook/destinations/
Create a webhook destination. The response includes the auto-generated `secret_shared_key` HMAC signing secret (also readable later via `GET /v3/webhook/destinations/{destination_uuid}/`). Always send `subscribed_events` with at least one event (no wildcards): an explicit empty list is rejected with 400, and omitting the field creates a destination subscribed to nothing, which never receives a webhook. The `(application, url)` pair must be unique among non-deleted destinations.

<AgentPromptAccordion title="Create Webhook Destination API Prompt" />

Webhook destinations let you send different Didit events to different URLs. Each destination has its own `secret_shared_key`, `webhook_version`, and `subscribed_events` list.

## How `subscribed_events` works

`subscribed_events` is a required array of exact event names. Didit delivers a webhook to this destination only when the payload's `webhook_type` matches one of the values in the array.

* Include at least one event.
* Use only the supported event names below.
* Add every event you want delivered; there is no wildcard value like `*` or `all`.
* To route different product areas to different systems, create multiple destinations with different `subscribed_events` lists.

## Event catalog

| Event                        | Subscribe when you need                                                                                                                                   |
| ---------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status.updated`             | User Verification (KYC) or Business Verification (KYB) session status changes. KYB payloads include `session_kind: "business"` and `business_session_id`. |
| `data.updated`               | Session verification data is corrected or updated after creation, such as reviewer edits to KYC, Proof of Address, or KYB data.                           |
| `user.status.updated`        | A User entity changes status, for example `ACTIVE`, `FLAGGED`, or `BLOCKED`.                                                                              |
| `user.data.updated`          | A User entity profile, counters, metadata, documents, or aggregate verification fields change.                                                            |
| `business.status.updated`    | A Business entity changes status, for example after manual review, KYB results, or a blocklist action.                                                    |
| `business.data.updated`      | A Business entity profile, counters, metadata, registration fields, or aggregate verification fields change.                                              |
| `activity.created`           | A timeline activity is recorded for a User, Business, external counterparty, session, or transaction.                                                     |
| `transaction.created`        | A Transaction Monitoring transaction is created and its initial rule evaluation is complete.                                                              |
| `transaction.status.updated` | A transaction changes status after rules, analyst review, remediation, provider updates, or API/console actions.                                          |

Common subscription sets:

```json theme={null}
{
  "subscribed_events": ["status.updated", "data.updated"]
}
```

```json theme={null}
{
  "subscribed_events": ["transaction.created", "transaction.status.updated"]
}
```

```json theme={null}
{
  "subscribed_events": [
    "user.status.updated",
    "user.data.updated",
    "business.status.updated",
    "business.data.updated",
    "activity.created"
  ]
}
```

For payload examples and signing code, see the [webhooks guide](/integration/webhooks).


# Delete Webhook Destination
Source: https://docs.didit.me/management-api/webhook/delete-destination

DELETE /v3/webhook/destinations/{destination_uuid}/
Delete a webhook destination. Future events stop being pushed to its URL. Past delivery records are not affected and stay queryable from the Business Console, so deleting a destination is not a way to remove your delivery history. Calling again returns 404.

<AgentPromptAccordion title="Delete Webhook Destination API Prompt" />


# Get Webhook Destination
Source: https://docs.didit.me/management-api/webhook/get-destination

GET /v3/webhook/destinations/{destination_uuid}/
Retrieve one webhook destination with its `secret_shared_key` signing secret and delivery health summary. API-key callers always receive the secret in full; Console users without `read:webhooks` see an empty string.

<AgentPromptAccordion title="Get Webhook Destination API Prompt" />


# List Webhook Destinations
Source: https://docs.didit.me/management-api/webhook/list-destinations

GET /v3/webhook/destinations/
List all webhook destinations (unpaginated array, oldest first). Each row includes URL, subscribed events, and delivery health metrics. The signing secret is NOT included in the list — fetch a single destination (`GET /v3/webhook/destinations/{destination_uuid}/`) to read `secret_shared_key`.

<AgentPromptAccordion title="List Webhook Destinations API Prompt" />


# Update Webhook Destination
Source: https://docs.didit.me/management-api/webhook/update-destination

PATCH /v3/webhook/destinations/{destination_uuid}/
Update a webhook destination. **`subscribed_events` is REPLACED wholesale, not merged** — fetch first, append, resend. Secret is not rotated.

<AgentPromptAccordion title="Update Webhook Destination API Prompt" />

Use this endpoint to change where a destination sends webhooks and which events it receives.

## Updating `subscribed_events`

When you send `subscribed_events`, provide the complete event list that should remain subscribed after the update. The array replaces the previous subscription set.

```json theme={null}
{
  "subscribed_events": [
    "status.updated",
    "data.updated",
    "transaction.created",
    "transaction.status.updated"
  ]
}
```

Supported values are:

| Event                        | What it represents                                                             |
| ---------------------------- | ------------------------------------------------------------------------------ |
| `status.updated`             | User Verification (KYC) or Business Verification (KYB) session status changed. |
| `data.updated`               | Session verification data changed after creation.                              |
| `user.status.updated`        | User entity status changed.                                                    |
| `user.data.updated`          | User entity data changed.                                                      |
| `business.status.updated`    | Business entity status changed.                                                |
| `business.data.updated`      | Business entity data changed.                                                  |
| `activity.created`           | Activity timeline entry created.                                               |
| `transaction.created`        | Transaction created and initially evaluated.                                   |
| `transaction.status.updated` | Transaction status changed.                                                    |

Use the [create destination guide](/management-api/webhook/create-destination) for detailed event descriptions and common subscription sets.


# Create Workflow
Source: https://docs.didit.me/management-api/workflows/create

POST /v3/workflows/
Create a simple workflow. Send `features` in execution order (ordering rules apply); defaults to `published` v1. The body accepts ONLY the fields listed in `SimpleWorkflowRequest` — any other key (including `workflow_type`) is rejected with a 400. Not idempotent — each call creates a new workflow. Maximum 50 workflows per application.

<AgentPromptAccordion title="Create Workflow API Prompt" />

Use this endpoint to create workflows through the API without building workflow graph nodes yourself. Send a `features` array in the order users should complete the checks. Didit converts it into a node-based workflow internally and adds the final status step automatically.

This `POST /v3/workflows/` endpoint creates **simple, linear** workflows only — a flat `features` list. For **branching, conditional routing, Document AI, and decline/decision nodes**, use the node **[graph format](#branching--node-based-workflows-graph)** documented below (it powers the visual builder in the console and the [Didit MCP](/integration/mcp/overview) workflow tools).

See [Workflow Feature Configs](/management-api/workflows/feature-configs) for every `config` field accepted by each feature.

## Basic KYC workflow

```json theme={null}
{
  "workflow_label": "Standard KYC",
  "features": [
    {
      "feature": "OCR",
      "config": {
        "documents_allowed": {
          "USA": {
            "DL": {
              "enabled": 1,
              "sides": 2
            }
          }
        },
        "duplicated_user_action": "REVIEW"
      }
    },
    {
      "feature": "LIVENESS",
      "config": {
        "face_liveness_method": "PASSIVE"
      }
    },
    {
      "feature": "FACE_MATCH"
    }
  ]
}
```

## Questionnaire workflow

First create the questionnaire with `POST /v3/questionnaires/`. Then use the returned `questionnaire_id` as `questionnaire_uuid`.

```json theme={null}
{
  "workflow_label": "Source of Funds",
  "features": [
    {
      "feature": "QUESTIONNAIRE",
      "config": {
        "questionnaire_uuid": "11111111-2222-3333-4444-555555555555",
        "review_questionnaire_manually": true
      }
    }
  ]
}
```

Feature order matters. For example, put `OCR` before `FACE_MATCH`, `NFC`, `DATABASE_VALIDATION`, or user AML checks that depend on document data.

## Feature config reference

Each `features[]` item has this shape:

```json theme={null}
{
  "feature": "OCR",
  "label": "ID Verification",
  "config": {}
}
```

The exact `config` object depends on the feature. Review the full field list, defaults, required settings, value ranges, and examples in [Workflow Feature Configs](/management-api/workflows/feature-configs).

For `OCR`, omit `config.documents_allowed`, send `null`, or send `{}` to allow every supported document type. Include it only when you want to restrict the workflow to specific countries or document types. For `QUESTIONNAIRE`, `config.questionnaire_uuid` is required.

## Optional workflow settings

You can include any of these top-level fields when creating a workflow to control session behavior. They are all optional and fall back to the workflow defaults when omitted.

| Field                     | Type                      | Description                                                                                                             |
| ------------------------- | ------------------------- | ----------------------------------------------------------------------------------------------------------------------- |
| `is_white_label_enabled`  | boolean                   | Enable white-label customization for sessions created with this workflow. Default `false`.                              |
| `is_desktop_allowed`      | boolean                   | Allow the verification flow to run on desktop browsers. Default `false`.                                                |
| `max_retry_attempts`      | integer (0–10)            | Maximum retry attempts allowed after a declined verification. `0` blocks the user after the first decline. Default `3`. |
| `retry_window_days`       | integer (1–365) or `null` | Rolling window in days used to count retries (`null` = all-time limit). Default `7`.                                    |
| `session_expiration_time` | integer (3600–2419200)    | Seconds before an unfinished session expires. Minimum 1 hour, maximum 4 weeks. Default `604800` (7 days).               |

```json theme={null}
{
  "workflow_label": "Standard KYC",
  "is_white_label_enabled": true,
  "is_desktop_allowed": true,
  "max_retry_attempts": 5,
  "retry_window_days": 14,
  "session_expiration_time": 86400,
  "features": [
    { "feature": "OCR" },
    { "feature": "LIVENESS" },
    { "feature": "FACE_MATCH" }
  ]
}
```

## Branching & node-based workflows (graph)

A linear `features` list can't express "if X then Y." For **conditional branching** (decline on a status, route on an extracted field, gate a step on a match), a **Document AI** request step, or terminal **decline/decision** nodes, Didit workflows use a **node graph** — the same structure the console's visual builder produces.

<Info>
  The simplest way to build a graph workflow is the **[Didit MCP](/integration/mcp/overview)** — ask an agent in plain language ("after ID verification, if the profession is ≈ 'Software Engineer', add a proof-of-funds step") and it constructs, validates, and saves the graph for you. The structure below is what those tools (and the console) produce.
</Info>

### Graph shape

A graph is `{ start_node, nodes }`. `nodes` is a map of node id → node. Edges are implicit: each node points forward via `next` (unconditional) and/or `branches[].goto` (conditional).

| Node type           | Shape                                                                                                                                   |
| ------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `feature`           | `{ "node_type": "feature", "feature": "OCR", "config": {…}, "next": "<id>", "branches": [] }`                                           |
| `branch`            | `{ "node_type": "branch", "branches": [ { "id", "logic": "and"\|"or", "rules": [<rule>], "goto": "<id>" } ], "next": "<fallback id>" }` |
| `status` (terminal) | `{ "node_type": "status", "session_status": "Approved"\|"Declined"\|"In Review"\|"Determine" }`                                         |
| `action`            | `{ "node_type": "action", "actions": [ { "type": "add_tag"\|"add_review"\|… } ], "next": "<id>" }`                                      |
| `webhook`           | `{ "node_type": "webhook", "config": { "url", "method" }, "branches": [], "next": "<id>" }`                                             |

`start_node` must be a feature node. Branches are evaluated in order, **first match wins**; an empty `rules: []` is the catch-all "else" (keep it last). `session_status: "Determine"` auto-decides from the combined feature outcomes.

<Warning>
  **Every branch node must have an explicit else branch** — a branch with `rules: []` that routes sessions matching none of the conditions. Don't rely on the branch node's `next` as the fallback: a bare `next` renders as an ambiguous edge in the builder and is easy to omit. When you send a branch node with a `next` and no else branch, the API **converts that `next` into an explicit else branch** for you (so `{ …, "branches": [<conditions>], "next": "liveness" }` is saved as `branches: [<conditions>, { "id": "else", "rules": [], "goto": "liveness" }]`). Build the else yourself to be explicit; the conversion is a safety net, not a substitute.
</Warning>

### Branch rules & operators

Each rule compares a **field** to a **value** with an **operator**:

```json theme={null}
{ "field": "kyc.extra_fields.profession", "operator": "fuzzy_match", "value": "Software Engineer", "score": 80 }
```

* **Fields** name a feature outcome (`kyc.status`, `aml.status`, `document_ai.status`, `face_match.score`, …) or an extracted value (`kyc.full_name`, `kyc.age`, `kyc.nationality`, `kyc.extra_fields.profession`, a Document-AI field `document_ai.<key>`, `expected_details.*`). A branch may only read a field whose feature has run on every path reaching it.
* **Operators:** `equals`, `not_equals`, `greater_than(_or_equals)`, `less_than(_or_equals)`, `contains`, `not_contains`, `in`, `not_in`, `is_empty`, `is_not_empty`, `regex`, and **`fuzzy_match`** (string fields only; requires a `score` 0–100 — a similarity threshold, e.g. profession ≥ 80% similar to "Software Engineer").

### Branch on why NFC did not run

After an `NFC` node, use `nfc.skip_reason` with `equals` or `in` to route sessions by why the chip read did not happen. The field has these six stable values:

* `USER_SKIPPED`
* `DOCUMENT_WITHOUT_CHIP`
* `CHIP_CERTIFICATE_UNAVAILABLE`
* `DEVICE_WITHOUT_NFC`
* `INTEGRATION_WITHOUT_NFC_ACCESS`
* `MRZ_KEY_UNAVAILABLE`

See [NFC skip reasons](/core-technology/nfc-verification/warnings-nfc-verification#skip-reasons) for what each value means. When NFC succeeds, `nfc.skip_reason` is `null`, so neither an `equals` nor an `in` rule for a skip reason matches.

The field also resolves for **gate-skipped** NFC nodes. This includes cases where no NFC report or warning exists, and cases where `allow_nfc_skip` is `false` but the document or device gate prevents NFC from running. You can therefore route these sessions without relying on an `nfc_verifications[]` entry.

<Note>
  Sessions stored before NFC capability became tri-state can have `has_device_nfc_support: false`. An older web session may therefore resolve to `DEVICE_WITHOUT_NFC` instead of `INTEGRATION_WITHOUT_NFC_ACCESS`.
</Note>

This graph uses `equals` for a user skip, `in` for gate or capability skips, and an explicit else for successful NFC. The branch comes after the `NFC` node, and every destination points forward to a terminal node:

```json theme={null}
{
  "start_node": "ocr",
  "nodes": {
    "ocr": {
      "node_type": "feature",
      "feature": "OCR",
      "next": "nfc"
    },
    "nfc": {
      "node_type": "feature",
      "feature": "NFC",
      "config": { "allow_nfc_skip": false },
      "next": "route_nfc"
    },
    "route_nfc": {
      "node_type": "branch",
      "branches": [
        {
          "id": "user_skipped",
          "logic": "and",
          "rules": [
            { "field": "nfc.skip_reason", "operator": "equals", "value": "USER_SKIPPED" }
          ],
          "goto": "manual_review"
        },
        {
          "id": "nfc_unavailable",
          "logic": "and",
          "rules": [
            {
              "field": "nfc.skip_reason",
              "operator": "in",
              "value": [
                "DOCUMENT_WITHOUT_CHIP",
                "CHIP_CERTIFICATE_UNAVAILABLE",
                "DEVICE_WITHOUT_NFC",
                "INTEGRATION_WITHOUT_NFC_ACCESS",
                "MRZ_KEY_UNAVAILABLE"
              ]
            }
          ],
          "goto": "manual_review"
        },
        {
          "id": "else",
          "logic": "and",
          "rules": [],
          "goto": "approved"
        }
      ]
    },
    "manual_review": { "node_type": "status", "session_status": "In Review" },
    "approved": { "node_type": "status", "session_status": "Approved" }
  }
}
```

To express “NFC was not performed for any known reason,” use `in` with **all six** values. Keep an explicit else branch for successful NFC (`nfc.skip_reason: null`) and any future value that your graph does not yet recognize.

### Document AI (e.g. proof of funds)

A `DOCUMENT_AI` feature node requests one or more documents and extracts named fields:

```json theme={null}
{
  "node_type": "feature",
  "feature": "DOCUMENT_AI",
  "label": "Proof of Funds",
  "config": {
    "document_ai_documents": [
      {
        "document_key": "proof_of_funds",
        "title": "Proof of Funds",
        "description": "Upload a recent bank statement.",
        "fields": [
          {
            "key": "account_holder",
            "name": "Account holder",
            "instruction": "The full name of the account holder as printed on the statement.",
            "type": "text",
            "required": true,
            "is_full_name": true
          },
          {
            "key": "closing_balance",
            "name": "Closing balance",
            "instruction": "The closing balance amount.",
            "type": "number",
            "required": true
          }
        ]
      }
    ],
    "document_ai_missing_required_fields_action": "REVIEW",
    "document_ai_name_mismatch_action": "REVIEW"
  },
  "next": "final_decision"
}
```

Each configured field becomes a branchable value `document_ai.<key>`, and the step's outcome is `document_ai.status`.

Set `"is_full_name": true` on the field that holds the document holder's full name. Its extracted value is compared against the verified identity's full name (the OCR/ID-verification name, or the session's expected details), and `document_ai_name_mismatch_action` decides what happens on a mismatch below `document_ai_name_match_score_threshold`. The flag is **optional** — a document may mark no field — and **at most one field per document** may set it. See [Workflow feature configs → Document AI](/management-api/workflows/feature-configs#document-ai) for every Document AI config field.

### Endpoints & draft lifecycle

Graph editing is per-application and uses the console/management endpoints (user-Bearer + `read:workflows`/`write:workflows`). A graph can only be edited on a **draft** version, so the lifecycle is **create-draft → set graph → publish**:

| Method  | Path                                                                              | Purpose                                 |
| ------- | --------------------------------------------------------------------------------- | --------------------------------------- |
| `GET`   | `…/verification-settings/{settings_uuid}/workflow-graph/`                         | Current graph + `status`/`is_editable`  |
| `POST`  | `…/application/{app}/workflow-graph/validate/` (body `{ "graph": … }`)            | Dry-run validation                      |
| `GET`   | `…/application/{app}/workflow-graph/field-definitions/`                           | Branchable fields + valid operators     |
| `POST`  | `…/verification-settings/{settings_uuid}/create-draft/`                           | Editable draft from a published version |
| `PUT`   | `…/verification-settings/{settings_uuid}/workflow-graph/` (body `{ "graph": … }`) | Save the graph                          |
| `PATCH` | `…/verification-settings/{settings_uuid}/` (body `{ "status": "published" }`)     | Publish the draft                       |

### Worked example: route Software Engineers to proof of funds

> After ID verification: if it was **declined**, decline the session; if the holder's **profession ≈ "Software Engineer"** (≥80% similar), request a **proof-of-funds** document; then make a final decision.

```json theme={null}
{
  "start_node": "ocr_1",
  "nodes": {
    "ocr_1": { "node_type": "feature", "feature": "OCR", "label": "ID Verification", "next": "after_ocr" },
    "after_ocr": {
      "node_type": "branch",
      "label": "Route after ID verification",
      "branches": [
        { "id": "declined", "logic": "or", "rules": [ { "field": "kyc.status", "operator": "equals", "value": "Declined" } ], "goto": "decline" },
        { "id": "software_engineer", "logic": "and", "rules": [ { "field": "kyc.extra_fields.profession", "operator": "fuzzy_match", "value": "Software Engineer", "score": 80 } ], "goto": "proof_of_funds" },
        { "id": "else", "logic": "and", "rules": [], "goto": "final_decision" }
      ]
    },
    "proof_of_funds": {
      "node_type": "feature",
      "feature": "DOCUMENT_AI",
      "label": "Proof of Funds",
      "config": {
        "document_ai_documents": [
          { "document_key": "proof_of_funds", "title": "Proof of Funds", "description": "Upload a recent bank statement.",
            "fields": [
              { "key": "account_holder", "name": "Account holder", "type": "text", "required": true },
              { "key": "closing_balance", "name": "Closing balance", "type": "number", "required": true }
            ] }
        ],
        "document_ai_missing_required_fields_action": "REVIEW"
      },
      "next": "final_decision"
    },
    "final_decision": { "node_type": "status", "session_status": "Determine", "label": "Final decision" },
    "decline": { "node_type": "status", "session_status": "Declined", "label": "Declined" }
  }
}
```

The final node uses `session_status: "Determine"`, which **auto-decides** (approve / decline / in-review) from whatever features actually ran on the session — so both the proof-of-funds path and the else path resolve correctly without any branch reading `document_ai.status` (which doesn't exist on the path that skips Document AI). Remember: a branch may only read a field whose feature ran on *every* path reaching it.

Send it as `{ "graph": <above> }` to the `…/workflow-graph/` endpoint (validate first). To build a **new** workflow from scratch use the MCP's `didit_workflow_set_graph`; to **modify an existing** workflow use `didit_workflow_edit_graph` (small ops, preserves the existing nodes and allow-lists). See the [Didit MCP](/integration/mcp/tools).


# Delete Workflow
Source: https://docs.didit.me/management-api/workflows/delete

DELETE /v3/workflows/{settings_uuid}/
Permanently delete one workflow version (no undo). Existing sessions keep their verification results but their workflow reference is cleared; other versions in the same `workflow_id` group are not deleted.

<AgentPromptAccordion title="Delete Workflow API Prompt" />


# Workflow Feature Configs
Source: https://docs.didit.me/management-api/workflows/feature-configs

Reference for all config fields accepted by POST and PATCH /v3/workflows/ when building simple linear workflows with the features array.

Use these `config` fields inside each item of the `features` array for [`POST /v3/workflows/`](/management-api/workflows/create) and [`PATCH /v3/workflows/{settings_uuid}/`](/management-api/workflows/update).

```json theme={null}
{
  "workflow_label": "Standard KYC",
  "features": [
    {
      "feature": "OCR",
      "config": {
        "documents_allowed": {
          "USA": {
            "DL": {
              "enabled": 1,
              "sides": 2
            }
          }
        }
      }
    }
  ]
}
```

The v3 workflow API builds a linear node-based workflow from the ordered `features` array. Send features in the exact execution order.

<Note>
  Which engine runs a feature — Didit's own, or a third-party provider — is not one of the config fields below. It's managed through the console's [Marketplace](/console/marketplace), which sets `provider_key` and `fallback_to_native` on the feature's `config` object for you.
</Note>

## Validation rules

* `OCR` defaults to all supported countries and document types when `config.documents_allowed` is omitted, `null`, or `{}`. If you send a custom `documents_allowed` object, it must contain at least one valid country and one enabled document type. Each document config can set `sides` to `1` for front-only capture or `2` for front-and-back capture.
* `QUESTIONNAIRE` requires `config.questionnaire_uuid`.
* `KYB_DOCUMENTS` requires `config.kyb_required_document_groups`.
* `FACE_MATCH` must come after `OCR` in simple workflow requests.
* `NFC`, `DATABASE_VALIDATION`, and person `AML` require `OCR` when they appear in the same workflow.
* KYB sub-features such as `KYB_DOCUMENTS` and `KYB_KEY_PEOPLE` require `KYB_REGISTRY` earlier in the workflow.
* A workflow is either a person (KYC) workflow or a business (KYB) workflow, never both. A workflow that uses any KYB feature (`KYB_REGISTRY`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE`) may only combine it with `AML`, `DOCUMENT_AI`, `QUESTIONNAIRE`, `PHONE_VERIFICATION`, `EMAIL_VERIFICATION`, and `IP_ANALYSIS`. It cannot include person-only features such as `OCR`, `LIVENESS`, `FACE_MATCH`, `NFC`, `PROOF_OF_ADDRESS`, `DATABASE_VALIDATION`, or `AGE_ESTIMATION`, and a person workflow cannot include KYB features. On a business workflow `DOCUMENT_AI` compares any field marked `is_full_name` against the verified company instead of a person. To verify the people behind a company, build a separate KYC workflow and reference it from the `KYB_KEY_PEOPLE` node using `kyb_ubo_verification_workflow`, `kyb_officer_verification_workflow`, or `kyb_shareholder_verification_workflow`.
* Action fields use `DECLINE`, `REVIEW`, or `NO_ACTION` unless the field below says it is restricted.
* Score and threshold fields are numbers from `0` to `100` unless a narrower range is listed.

## Common status rules

Every feature supports an optional `status_rules` array. Use it to override the feature status when a field condition matches.

```json theme={null}
{
  "status_rules": [
    {
      "field": "kyc.issuing_state",
      "operator": "in",
      "value": ["VEN", "IRN"],
      "status": "In Review",
      "value_type": "literal"
    },
    {
      "field": "kyc.extra_fields.profession",
      "operator": "fuzzy_match",
      "value": "Soft. Engineer",
      "score": 80,
      "status": "Declined",
      "value_type": "literal"
    },
    {
      "field": "kyc.extra_fields.dl_class_code_b_to",
      "operator": "less_than",
      "value": "2030-01-01",
      "status": "In Review",
      "value_type": "literal"
    },
    {
      "field": "kyc.extra_fields.dl_class_code_b_from",
      "operator": "less_than",
      "value": { "direction": "past", "amount": 3, "unit": "years" },
      "status": "Declined",
      "value_type": "relative_date"
    }
  ]
}
```

| Field        | Type   | Description                                                                                                                                                                                                                                                                             |
| ------------ | ------ | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `field`      | string | Field path to check, such as `kyc.issuing_state` or `kyc.document_type`.                                                                                                                                                                                                                |
| `operator`   | string | One of `equals`, `not_equals`, `greater_than`, `greater_than_or_equals`, `less_than`, `less_than_or_equals`, `contains`, `not_contains`, `in`, `not_in`, `is_empty`, `is_not_empty`, `regex`, or `fuzzy_match`.                                                                         |
| `value`      | any    | Comparison value. Omit or send `null` for operators that do not need a value.                                                                                                                                                                                                           |
| `status`     | string | One of `Approved`, `Declined`, `In Review`, or `No Action`.                                                                                                                                                                                                                             |
| `value_type` | string | Optional. `literal` by default. Use `field` to compare against another field, `list` to resolve a Didit list UUID at runtime, or `relative_date` to compare a date field against today plus/minus a duration.                                                                           |
| `score`      | number | Required for `fuzzy_match`. Minimum similarity score from `0` to `100`. The rule matches when the computed similarity is greater than or equal to this value (`similarity >= score`). For example, `Software Engineer` can match `Soft. Engineer` when the similarity is at least `80`. |

Read the example above as: `kyc.extra_fields.profession` fuzzy matches `Soft. Engineer` with a minimum score of `80` → set the feature status to `Declined`.

For ID Verification, target extracted `extra_fields` values such as `kyc.extra_fields.profession`, driver license class validity dates like `kyc.extra_fields.dl_class_code_b_from` and `kyc.extra_fields.dl_class_code_b_to`, or per-class restriction/information codes like `kyc.extra_fields.dl_class_code_b_notes` (column 12 of UK licences). These values come from the OCR result's `extra_fields` object; they are not part of `expected_details`.

<Note>
  `dl_class_code_*_from` and `dl_class_code_*_to` are always either a valid ISO date or absent from `extra_fields` — Didit never returns unreadable OCR text in a date field. If the class-table cell can't be read, the field is omitted rather than sent as a raw string, so use the `is_empty` operator to route unreadable class dates instead of assuming the field is always present.
</Note>

For date fields, use `value_type: "relative_date"` with a value object shaped as `{ "direction": "past" | "future", "amount": number, "unit": "days" | "months" | "years" }`. For example, `operator: "less_than"` with `{ "direction": "past", "amount": 3, "unit": "years" }` matches dates older than three years from today.

## OCR / ID Verification

Feature value: `OCR`.

| Config field                                               | Type              | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| ---------------------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `documents_allowed`                                        | object            | Optional. Omit it, send `null`, or send `{}` to allow every supported country and document type. Send an ISO3 country code to document type config only when you want to restrict allowed documents. At least one custom document must have `enabled: 1`. Document configs can include `sides: 1` for front-only capture or `sides: 2` for front-and-back capture. Document types include `P`, `ID`, `DL`, `RP`, `HIC`, `TC`, `SSC`, and other country-supported values.                                            |
| `methods`                                                  | object            | Which of the three [ID Verification methods](/core-technology/id-verification/verification-methods) each country may use: document capture, non-doc lookup against a government or other authoritative source, and digital ID wallets. Omit the key, a country, or a method inside a country and that country is document capture only. Every method and wallet must be marked available for the country in the capability catalog, or the save is rejected. See [Methods per country](#methods-per-country) below. |
| `document_blur_fields_by_country`                          | object            | ISO3 country code to blur field names to redact on document images.                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `image_capture_methods_allowed`                            | string\[]         | Allowed capture methods. Values include `CAMERA_SCAN` and `UPLOAD`.                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `duplicated_user_action`                                   | action            | Action for a duplicated user.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `is_age_restrictions_enabled`                              | boolean           | Enables minimum and maximum age checks.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `age_restrictions_by_country`                              | object            | ISO3 country code to an age config with `minimum_age`, optional `maximum_age`, and optional `states`.                                                                                                                                                                                                                                                                                                                                                                                                               |
| `minimum_age`                                              | integer           | Global minimum age, `1` to `120`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `minimum_age_action`                                       | action            | Action when the user is below `minimum_age`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `maximum_age`                                              | integer           | Global maximum age, `1` to `120`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   |
| `maximum_age_action`                                       | action            | Action when the user is above `maximum_age`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `expiration_date_not_detected_action`                      | action            | Action when the document expiration date is missing.                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `invalid_code_action`                                      | action            | Action when a barcode or machine-readable code is invalid.                                                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `invalid_mrz_action`                                       | action            | Action when the MRZ is invalid.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `inconsistent_data_action`                                 | action            | Action when extracted document fields conflict.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `invalid_validation_action`                                | action            | Action when document validation fails.                                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `expected_details_mismatch_action`                         | action            | Action when expected user details do not match the document.                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `image_too_blurry_action`                                  | action            | Action for blurry document images.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `image_too_dark_action`                                    | action            | Action for dark document images.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `image_too_bright_action`                                  | action            | Action for overexposed document images.                                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `unparsed_address_action`                                  | action            | Action when the document address cannot be parsed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `document_or_personal_number_format_mismatch_action`       | action            | Action when document or personal number format does not match the expected pattern.                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `document_without_portrait_action`                         | action            | Action when the recognized document type never carries a portrait photo on any side (some residence permits, health cards, registration certificates, and other catalog-known portrait-less document families). Defaults to `REVIEW`. Consider `DECLINE` when Face Match anchors the workflow's identity check.                                                                                                                                                                                                     |
| `is_document_selfie_portrait_match_enabled`                | boolean           | Enables document portrait to selfie comparison.                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `document_selfie_portrait_match_decline_threshold`         | integer           | Decline threshold for document portrait to selfie match.                                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `document_selfie_portrait_match_review_threshold`          | integer           | Review threshold for document portrait to selfie match.                                                                                                                                                                                                                                                                                                                                                                                                                                                             |
| `id_verification_name_match_score_threshold`               | integer           | Name match threshold across multiple ID verifications.                                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `id_verification_max_retry_attempts`                       | integer           | Retry limit for ID verification, `2` to `5`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `id_document_quality_threshold`                            | integer           | Minimum capture-quality score (`0` to `100`) a document image must reach to be accepted. The quality check always runs; only this threshold is configurable. Defaults to `20`, tuned so degraded and borderline captures (blur, motion, unreadable text) are rejected while legible documents pass; raise it for stricter capture requirements. The console presents this value on a perceptual slider where the default of `20` displays as a balanced 50%.                                                        |
| `cross_org_fraud_document_action`                          | action            | Verdict when this document was flagged as fraudulent by another organization in the network.                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `document_audio_recording_enabled`                         | boolean           | Record the microphone during document capture, so a reviewer can hear the session. Off by default.                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `document_liveness_portrait_replace_decline_threshold`     | integer           | `0` to `100`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `document_liveness_portrait_replace_review_threshold`      | integer           | `0` to `100`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `document_liveness_printed_copy_decline_threshold`         | integer           | `0` to `100`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `document_liveness_printed_copy_review_threshold`          | integer           | `0` to `100`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `document_liveness_screen_replay_decline_threshold`        | integer           | `0` to `100`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `document_liveness_screen_replay_review_threshold`         | integer           | `0` to `100`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `image_quality_too_low_action`                             | action            | Verdict when overall document image quality is below the bar.                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| `is_image_capture_review_screen_enabled`                   | boolean           | Show the user a review screen after each document capture, letting them retake the photo before it is submitted. Off by default.                                                                                                                                                                                                                                                                                                                                                                                    |
| `is_ocr_id_verification_data_review_enabled`               | boolean           | Let the user review and correct the extracted identity data before the step completes. Off by default. A correction is scored against `ocr_id_verification_data_review_critical_fields`, and a disagreement takes the critical or the minor action accordingly. The review still runs when the workflow includes NFC - a later chip read simply supersedes it.                                                                                                                                                      |
| `ocr_id_verification_data_review_critical_fields`          | string\[]         | Which extracted identity fields count as critical when the user edits the OCR result, so a mismatch takes the critical action rather than the minor one. Shape: `["first_name" \| "last_name" \| "date_of_birth" \| ...]`.                                                                                                                                                                                                                                                                                          |
| `ocr_id_verification_data_review_critical_mismatch_action` | restricted action | Verdict when the user's edit disagrees with OCR on a critical field.                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `ocr_id_verification_data_review_minor_mismatch_action`    | action            | Verdict when the user's edit disagrees with OCR on a non-critical field.                                                                                                                                                                                                                                                                                                                                                                                                                                            |
| `status_rules`                                             | array             | Optional custom status rules.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |

<Note>
  Document liveness is configured with the six `document_liveness_*` thresholds above, not with
  per-signal action fields. `portrait_replacement_action`, `printed_copy_action` and
  `screen_capture_action` are account-level settings and are **not** accepted in a workflow
  feature config: the API strips unknown config keys on save, so sending them there has no
  effect. Each signal has a decline threshold and a review threshold on a `0`-`100` scale where
  a higher score means the document is more likely to be genuine.
</Note>

Example:

```json theme={null}
{
  "feature": "OCR",
  "config": {
    "documents_allowed": {
      "USA": {
        "DL": {
          "enabled": 1,
          "sides": 2
        }
      }
    },
    "duplicated_user_action": "REVIEW",
    "image_capture_methods_allowed": ["CAMERA_SCAN", "UPLOAD"]
  }
}
```

### Methods per country

`methods` is keyed by [ISO 3166-1 alpha-3](https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3) country code. Each country carries up to three method objects; anything you leave out takes its default.

```json theme={null}
{
  "feature": "OCR",
  "config": {
    "methods": {
      "ZAF": {
        "document": { "enabled": true },
        "id_lookup": {
          "enabled": true,
          "max_attempts": 2,
          "skip_liveness_and_face_match": true,
          "on_partial_match": "fallback_to_document",
          "on_no_match": "fallback_to_document",
          "on_provider_error": "fallback_to_document"
        },
        "wallet": { "enabled": false, "providers": [], "on_failure": "fallback_to_document" }
      },
      "DNK": {
        "document": { "enabled": true },
        "wallet": { "enabled": true, "providers": ["mitid"], "on_failure": "fallback_to_document" }
      }
    }
  }
}
```

| Key                                             | Type                                | Default                | Description                                                                                                                                                                                                                                                                                                                                                                                        |
| ----------------------------------------------- | ----------------------------------- | ---------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `<ISO3>.document.enabled`                       | boolean                             | `true`                 | Whether a photographed document is accepted in this country. Which documents are accepted keeps living in `documents_allowed`.                                                                                                                                                                                                                                                                     |
| `<ISO3>.id_lookup.enabled`                      | boolean                             | `false`                | Offer the non-document lookup against this country's government or other authoritative source. Rejected when the catalog does not mark the country's source `available`.                                                                                                                                                                                                                           |
| `<ISO3>.id_lookup.max_attempts`                 | integer                             | `1`                    | `1` to `5`. How many **answered** lookups the user gets before the fallback switch fires. A number that fails the client-side format check never reaches the register, so it neither counts nor bills.                                                                                                                                                                                             |
| `<ISO3>.id_lookup.skip_liveness_and_face_match` | boolean                             | `true`                 | After a match against a register that returns a portrait, skip the workflow's own Liveness and Face Match steps — the lookup already ran passive liveness on the selfie and matched it to that portrait. Normalised to `false` on save for a source that returns no portrait, where the switch would mean nothing.                                                                                 |
| `<ISO3>.id_lookup.on_partial_match`             | `fallback_to_document` \| `decline` | `fallback_to_document` | What happens when the register answered but some fields did not match.                                                                                                                                                                                                                                                                                                                             |
| `<ISO3>.id_lookup.on_no_match`                  | `fallback_to_document` \| `decline` | `fallback_to_document` | What happens when the register answered and holds no matching record.                                                                                                                                                                                                                                                                                                                              |
| `<ISO3>.id_lookup.on_provider_error`            | `fallback_to_document` \| `decline` | `fallback_to_document` | What happens when the register could not be reached. Never billed.                                                                                                                                                                                                                                                                                                                                 |
| `<ISO3>.id_lookup.response_fields`              | string\[] \| null                   | `null`                 | Optional subset of the source's response field keys. Unknown keys are rejected and the source's required fields are always added back, so the saved value is always a valid selection. The current staging implementation applies this selection to comparison output, optional gender and retained registry portraits. Required identity fields remain. See the rollout and retention note below. |
| `<ISO3>.wallet.enabled`                         | boolean                             | `false`                | Offer digital ID wallet sign-in in this country.                                                                                                                                                                                                                                                                                                                                                   |
| `<ISO3>.wallet.providers`                       | string\[]                           | `[]`                   | Catalog wallet ids this country accepts — an accept-list, never a ranking. The order you send is normalised into catalog order. At least one wallet is required when `enabled` is `true`. A wallet that is not offered in the country, or that is still coming soon, is rejected.                                                                                                                  |
| `<ISO3>.wallet.on_failure`                      | `fallback_to_document` \| `decline` | `fallback_to_document` | What happens when the sign-in is cancelled, times out or fails. Never billed.                                                                                                                                                                                                                                                                                                                      |

Validation the API applies on save:

* An unknown country code, an unknown key inside a country, or an unknown key inside a method is rejected — nothing is silently dropped.
* A country where no method is enabled is rejected: nobody there could verify.
* `fallback_to_document` in a country where `document.enabled` is `false` declines at runtime, because there is nowhere to fall back to.

<Warning>
  The current staging implementation applies `id_lookup.response_fields` to comparison output, optional gender and retained registry portraits. Required identity fields remain part of the verification record. This is not a guarantee that every intermediate provider payload is excluded from processing. Production rollout has not been verified for this change; confirm the behavior in your target environment before relying on field selection for retention requirements.
</Warning>

Read the capability catalog before you write `methods` — through the console's **Countries** tab, or with the [`didit_workflow_get_id_verification_methods_catalog`](/integration/mcp/tools) MCP tool. Behaviour, coverage and billing are on [ID Verification methods](/core-technology/id-verification/verification-methods).

## NFC / ePassport

Feature value: `NFC`.

| Config field                  | Type    | Description                                                                                                                                                       |
| ----------------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `allow_nfc_skip`              | boolean | Allows users to skip NFC when their document supports chip reading.                                                                                               |
| `skip_nfc_action`             | action  | Action when the user skips NFC.                                                                                                                                   |
| `unverified_chip_action`      | action  | Action when chip verification fails.                                                                                                                              |
| `trust_anchor_missing_action` | action  | Verdict when the chip's data-group hashes are intact but the certificate chain cannot be verified, because the issuing country's CSCA trust anchor is not loaded. |
| `status_rules`                | array   | Optional custom status rules.                                                                                                                                     |

## Liveness

Feature value: `LIVENESS`.

| Config field                                         | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                    |
| ---------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `face_liveness_method`                               | string  | One of `ACTIVE_3D`, `FLASHING`, or `PASSIVE`.                                                                                                                                                                                                                                                                                                                                                                  |
| `face_liveness_mode`                                 | string  | Liveness mode override.                                                                                                                                                                                                                                                                                                                                                                                        |
| `face_liveness_flash_mode`                           | string  | Flash mode for the `ACTIVE_3D` and `FLASHING` methods. `"0"` (not strict, default) verifies that the colors flashed on screen reflect on the user's face; `"1"` (strict) additionally requires the reflections to match the exact flashed color sequence — stronger against replay and video-injection attacks, but with more false rejections.                                                                |
| `face_liveness_score_decline_threshold`              | integer | Decline threshold.                                                                                                                                                                                                                                                                                                                                                                                             |
| `face_liveness_score_review_threshold`               | integer | Review threshold.                                                                                                                                                                                                                                                                                                                                                                                              |
| `face_liveness_possible_duplicated_face_action`      | action  | Action when the face may be duplicated.                                                                                                                                                                                                                                                                                                                                                                        |
| `face_liveness_multiple_faces_action`                | action  | Action when multiple faces are detected.                                                                                                                                                                                                                                                                                                                                                                       |
| `face_liveness_video_anomaly_action`                 | action  | Action when the stored recording contains a repeated moving sequence. Default `NO_ACTION`; `REVIEW` and `DECLINE` can escalate a decided verification asynchronously. Sparse or repeated still frames alone do not trigger it.                                                                                                                                                                                 |
| `race_map_similarity_thresholds`                     | object  | Per-demographic similarity thresholds.                                                                                                                                                                                                                                                                                                                                                                         |
| `face_privacy_mode_enabled`                          | boolean | Enables privacy mode for face assets.                                                                                                                                                                                                                                                                                                                                                                          |
| `face_quality_review_threshold`                      | integer | Review threshold for face image quality.                                                                                                                                                                                                                                                                                                                                                                       |
| `face_quality_decline_threshold`                     | integer | Decline threshold for face image quality. Must be less than or equal to the review threshold.                                                                                                                                                                                                                                                                                                                  |
| `face_luminance_min_threshold`                       | integer | Minimum luminance threshold. Must be lower than `face_luminance_max_threshold`.                                                                                                                                                                                                                                                                                                                                |
| `face_luminance_min_action`                          | action  | Action when luminance is too low.                                                                                                                                                                                                                                                                                                                                                                              |
| `face_luminance_max_threshold`                       | integer | Maximum luminance threshold.                                                                                                                                                                                                                                                                                                                                                                                   |
| `face_luminance_max_action`                          | action  | Action when luminance is too high.                                                                                                                                                                                                                                                                                                                                                                             |
| `face_liveness_max_attempts`                         | integer | Total liveness submissions per session, `1` to `3`. Default `3` means one initial attempt plus two retries. Setting `1` does not disable retries for capture-quality failures: when every warning on the attempt is environmental (`LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE`, `LOW_FACE_QUALITY`, `HIGH_FACE_OCCLUSION`, `NO_FACE_DETECTED`) the user always gets a second attempt with actionable feedback. |
| `cross_org_fraud_face_action`                        | action  | **Deprecated and no longer applied.** It treated a face as if it carried a fraud verdict, which a stable biometric identity cannot. Still accepted so existing workflows keep validating. Use `cross_org_identity_claim_pattern_action`.                                                                                                                                                                       |
| `cross_org_identity_claim_pattern_action`            | action  | Verdict when other organizations in the network recorded identity-claim events for this same person in which the claimed identity did not match. Review or No action only — a Decline set here is downgraded to Review. See [Cross-organization identity claims](/core-technology/liveness/cross-organization-identity-claims).                                                                                |
| `external_capture_device_action`                     | action  | Verdict when an external capture device is detected.                                                                                                                                                                                                                                                                                                                                                           |
| `face_audio_recording_enabled`                       | boolean | Record the microphone during the selfie capture, so a reviewer can hear the session. Off by default.                                                                                                                                                                                                                                                                                                           |
| `face_liveness_duplicated_face_name_mismatch_action` | action  | Verdict when a duplicate face is found under a different name.                                                                                                                                                                                                                                                                                                                                                 |
| `frame_injection_action`                             | action  | Verdict when injected video frames are detected.                                                                                                                                                                                                                                                                                                                                                               |
| `screen_capture_action`                              | action  | Verdict when the selfie is a photo of a screen.                                                                                                                                                                                                                                                                                                                                                                |
| `virtual_camera_action`                              | action  | Verdict when a virtual camera feed is detected.                                                                                                                                                                                                                                                                                                                                                                |
| `status_rules`                                       | array   | Optional custom status rules.                                                                                                                                                                                                                                                                                                                                                                                  |

## Face Match

Feature value: `FACE_MATCH`.

| Config field                         | Type              | Description                                                                                                                                                                                                                                                                                                                     |
| ------------------------------------ | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `face_match_score_decline_threshold` | integer           | Decline threshold.                                                                                                                                                                                                                                                                                                              |
| `face_match_score_review_threshold`  | integer           | Review threshold.                                                                                                                                                                                                                                                                                                               |
| `face_match_max_attempts`            | integer           | Total face-match submissions per session, `1` to `3`. Default `3` means one initial attempt plus two retries.                                                                                                                                                                                                                   |
| `face_match_not_computed_action`     | restricted action | Verdict when no face-match score could be produced (missing portrait or selfie).                                                                                                                                                                                                                                                |
| `face_match_eyes_covered_action`     | action            | Verdict when the eyes region is covered in the selfie. Defaults to `NO_ACTION`, which records the evidence without changing the Face Match result. This signal is still being calibrated, so it stays shadow-only until the region reports as calibrated: set `REVIEW` or `DECLINE` now and it takes effect from that point on. |
| `face_match_mouth_covered_action`    | action            | Verdict when the mouth region is covered in the selfie. Same `NO_ACTION` default and same calibration caveat as `face_match_eyes_covered_action`.                                                                                                                                                                               |
| `face_match_face_covered_action`     | action            | Verdict when the face as a whole is covered in the selfie. Same `NO_ACTION` default and same calibration caveat as `face_match_eyes_covered_action`.                                                                                                                                                                            |
| `status_rules`                       | array             | Optional custom status rules.                                                                                                                                                                                                                                                                                                   |

## Age Estimation

Feature value: `AGE_ESTIMATION`.

| Config field                                         | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                    |
| ---------------------------------------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `enable_id_verification_fallback`                    | boolean | Runs ID Verification when age estimation lands in the borderline range.                                                                                                                                                                                                                                                                                                                                        |
| `minimum_age_threshold`                              | integer | Minimum accepted age, `1` to `100`.                                                                                                                                                                                                                                                                                                                                                                            |
| `borderline_minimum_age_threshold`                   | integer | Lower bound for the borderline range, `1` to `100`.                                                                                                                                                                                                                                                                                                                                                            |
| `borderline_maximum_age_threshold`                   | integer | Upper bound for the borderline range, `1` to `100`.                                                                                                                                                                                                                                                                                                                                                            |
| `face_liveness_method`                               | string  | One of `ACTIVE_3D`, `FLASHING`, or `PASSIVE`.                                                                                                                                                                                                                                                                                                                                                                  |
| `face_liveness_flash_mode`                           | string  | Flash mode for the `ACTIVE_3D` and `FLASHING` methods. `"0"` (not strict, default) verifies that the colors flashed on screen reflect on the user's face; `"1"` (strict) additionally requires the reflections to match the exact flashed color sequence.                                                                                                                                                      |
| `face_liveness_score_decline_threshold`              | number  | Decline threshold for the liveness check used by age estimation.                                                                                                                                                                                                                                                                                                                                               |
| `face_liveness_score_review_threshold`               | number  | Review threshold for the liveness check used by age estimation.                                                                                                                                                                                                                                                                                                                                                |
| `face_liveness_possible_duplicated_face_action`      | action  | Action when the face may be duplicated.                                                                                                                                                                                                                                                                                                                                                                        |
| `face_liveness_multiple_faces_action`                | action  | Action when multiple faces are detected.                                                                                                                                                                                                                                                                                                                                                                       |
| `face_liveness_video_anomaly_action`                 | action  | Action when the stored recording contains a repeated moving sequence. Default `NO_ACTION`; `REVIEW` and `DECLINE` can escalate a decided verification asynchronously. Sparse or repeated still frames alone do not trigger it.                                                                                                                                                                                 |
| `face_privacy_mode_enabled`                          | boolean | Enables privacy mode for face assets.                                                                                                                                                                                                                                                                                                                                                                          |
| `face_quality_review_threshold`                      | integer | Review threshold for face quality.                                                                                                                                                                                                                                                                                                                                                                             |
| `face_quality_decline_threshold`                     | integer | Decline threshold for face quality.                                                                                                                                                                                                                                                                                                                                                                            |
| `face_luminance_min_threshold`                       | integer | Minimum luminance threshold.                                                                                                                                                                                                                                                                                                                                                                                   |
| `face_luminance_min_action`                          | action  | Action when luminance is too low.                                                                                                                                                                                                                                                                                                                                                                              |
| `face_luminance_max_threshold`                       | integer | Maximum luminance threshold.                                                                                                                                                                                                                                                                                                                                                                                   |
| `face_luminance_max_action`                          | action  | Action when luminance is too high.                                                                                                                                                                                                                                                                                                                                                                             |
| `face_liveness_max_attempts`                         | integer | Total liveness submissions per session, `1` to `3`. Default `3` means one initial attempt plus two retries. Setting `1` does not disable retries for capture-quality failures: when every warning on the attempt is environmental (`LOW_FACE_LUMINANCE`, `HIGH_FACE_LUMINANCE`, `LOW_FACE_QUALITY`, `HIGH_FACE_OCCLUSION`, `NO_FACE_DETECTED`) the user always gets a second attempt with actionable feedback. |
| `external_capture_device_action`                     | action  | Verdict when an external capture device is detected.                                                                                                                                                                                                                                                                                                                                                           |
| `face_audio_recording_enabled`                       | boolean | Record the microphone during the selfie capture, so a reviewer can hear the session. Off by default.                                                                                                                                                                                                                                                                                                           |
| `face_liveness_duplicated_face_name_mismatch_action` | action  | Verdict when a duplicate face is found under a different name.                                                                                                                                                                                                                                                                                                                                                 |
| `frame_injection_action`                             | action  | Verdict when injected video frames are detected.                                                                                                                                                                                                                                                                                                                                                               |
| `screen_capture_action`                              | action  | Verdict when the selfie is a photo of a screen.                                                                                                                                                                                                                                                                                                                                                                |
| `virtual_camera_action`                              | action  | Verdict when a virtual camera feed is detected.                                                                                                                                                                                                                                                                                                                                                                |
| `status_rules`                                       | array   | Optional custom status rules.                                                                                                                                                                                                                                                                                                                                                                                  |

## Phone Verification

Feature value: `PHONE_VERIFICATION`.

| Config field                         | Type    | Description                                                                                                                                                                                                                                                                                                           |
| ------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `code_size`                          | integer | OTP size, `4` to `8`.                                                                                                                                                                                                                                                                                                 |
| `phone_max_retries`                  | integer | Maximum send retries, `1` to `5`.                                                                                                                                                                                                                                                                                     |
| `phone_max_check_attempts`           | integer | Maximum OTP check attempts, `1` to `5`.                                                                                                                                                                                                                                                                               |
| `phone_verification_countries`       | object  | ISO2 country code to channel config. Example: `{ "US": { "sms": { "enabled": true } } }`.                                                                                                                                                                                                                             |
| `disposable_number_action`           | action  | Action for disposable numbers.                                                                                                                                                                                                                                                                                        |
| `voip_number_action`                 | action  | Action for VoIP numbers.                                                                                                                                                                                                                                                                                              |
| `duplicated_phone_number_action`     | action  | Action for duplicated phone numbers.                                                                                                                                                                                                                                                                                  |
| `high_risk_phone_action`             | action  | Action when the delivery provider blocks the OTP send. Only `DECLINE` or `REVIEW`; default `DECLINE`. Applied only when every block on the step carries `risk_factors` of exactly `["device_attribute"]`; any other risk factor, any mix including it, or no risk factors at all declines regardless of this setting. |
| `phone_shared_device_mode`           | boolean | Allows shared-device phone verification mode.                                                                                                                                                                                                                                                                         |
| `phone_enrichment_enabled`           | boolean | Enables phone intelligence enrichment (line-type risk, trust index, carrier, porting / SIM-swap history, fraud-risk score). **Charged \$0.05 per verification** on top of the phone verification price.                                                                                                               |
| `phone_intelligence_score_action`    | action  | Action when the phone fraud-risk score is at or above `phone_intelligence_score_threshold`.                                                                                                                                                                                                                           |
| `phone_intelligence_score_threshold` | integer | Fraud-risk score (`0`–`100`, higher is riskier) that triggers `phone_intelligence_score_action`. Default `80`.                                                                                                                                                                                                        |
| `phone_type_risk_action`             | action  | Action when the number is flagged as a high-risk phone type.                                                                                                                                                                                                                                                          |
| `recent_port_action`                 | action  | Action when the number was recently ported (SIM-swap / porting signal).                                                                                                                                                                                                                                               |
| `low_phone_trust_action`             | action  | Action when the phone trust index is at or below `phone_trust_index_threshold`.                                                                                                                                                                                                                                       |
| `phone_trust_index_threshold`        | integer | Trust index (`0`–`100`, lower is riskier) at or below which `low_phone_trust_action` is applied. Default `30`.                                                                                                                                                                                                        |
| `phone_social_enabled`               | boolean | Enables the social footprint check: which messaging, social, e-commerce and professional platforms the verified number is registered on. **Charged \$0.05 per verification** on top of the phone verification price, independent of `phone_enrichment_enabled`.                                                       |
| `phone_no_social_presence_action`    | action  | Action when the social footprint check finds the number registered on none of the platforms it covers - a common synthetic-identity signal. Default `NO_ACTION`.                                                                                                                                                      |
| `cross_org_fraud_phone_action`       | action  | Verdict when this number was flagged as fraudulent by another organization in the network.                                                                                                                                                                                                                            |
| `status_rules`                       | array   | Optional custom status rules.                                                                                                                                                                                                                                                                                         |

Phone Verification is disabled until the organization completes its first top-up.

<Note>
  Phone intelligence enrichment is an optional add-on. When `phone_enrichment_enabled` is `true`, each completed phone verification is enriched with phone intelligence and **billed \$0.05 per request** in addition to the standard phone verification cost. The score-based actions only take effect once the enrichment score is available; the trust-index, phone-type and porting actions apply as soon as enrichment runs.

  The social footprint check is a second, separate add-on. When `phone_social_enabled` is `true`, each completed phone verification also reports which online platforms the number is registered on - messaging, social media, e-commerce and professional services - and is **billed \$0.05 per request**. It can be enabled with or without `phone_enrichment_enabled`: the two add-ons are priced and billed independently. A lookup that finds the number on none of the platforms it covers is a valid, billable answer and triggers `phone_no_social_presence_action`. Use `phone.social_profiles_registered` (the number of platforms the number is registered on) to branch on the result in a workflow graph.
</Note>

## Email Verification

Feature value: `EMAIL_VERIFICATION`.

| Config field                         | Type    | Description                                                                                                                                                                                                                                                                 |
| ------------------------------------ | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `email_code_size`                    | integer | OTP size, `4` to `8`.                                                                                                                                                                                                                                                       |
| `email_max_retries`                  | integer | Maximum send retries, `1` to `5`.                                                                                                                                                                                                                                           |
| `email_max_check_attempts`           | integer | Maximum OTP check attempts, `1` to `5`.                                                                                                                                                                                                                                     |
| `email_alphanumeric_code`            | boolean | Uses alphanumeric email codes.                                                                                                                                                                                                                                              |
| `breached_email_action`              | action  | Action for breached emails.                                                                                                                                                                                                                                                 |
| `disposable_email_action`            | action  | Action for disposable emails.                                                                                                                                                                                                                                               |
| `duplicated_email_action`            | action  | Action for duplicated emails.                                                                                                                                                                                                                                               |
| `only_corporate_emails_allowed`      | boolean | Rejects non-corporate email addresses.                                                                                                                                                                                                                                      |
| `email_enrichment_enabled`           | boolean | Enables email intelligence enrichment (deliverability, domain reputation, data-breach exposure, fraud-risk score). **Charged \$0.05 per verification** on top of the email verification price.                                                                              |
| `email_intelligence_score_action`    | action  | Action when the email fraud-risk score is at or above `email_intelligence_score_threshold`.                                                                                                                                                                                 |
| `email_intelligence_score_threshold` | integer | Fraud-risk score (`0`–`100`, higher is riskier) that triggers `email_intelligence_score_action`. Default `80`.                                                                                                                                                              |
| `recent_email_breach_action`         | action  | Action when the email appears in a recent known data breach.                                                                                                                                                                                                                |
| `frequent_email_breach_action`       | action  | Action when the email appears across many known data breaches.                                                                                                                                                                                                              |
| `email_social_enabled`               | boolean | Enables the social footprint check: which email, social, professional, e-commerce and entertainment platforms the verified address is registered on. **Charged \$0.05 per verification** on top of the email verification price, independent of `email_enrichment_enabled`. |
| `email_no_social_presence_action`    | action  | Action when the social footprint check finds the address registered on none of the platforms it covers - a common synthetic-identity signal. Default `NO_ACTION`.                                                                                                           |
| `cross_org_fraud_email_action`       | action  | Verdict when this address was flagged as fraudulent by another organization in the network.                                                                                                                                                                                 |
| `status_rules`                       | array   | Optional custom status rules.                                                                                                                                                                                                                                               |

<Note>
  Email intelligence enrichment is an optional add-on. When `email_enrichment_enabled` is `true`, each completed email verification is enriched with email intelligence and **billed \$0.05 per request** in addition to the standard email verification cost. The score-based action takes effect once the enrichment score is available; the breach actions apply as soon as enrichment runs.

  The social footprint check is a second, separate add-on. When `email_social_enabled` is `true`, each completed email verification also reports which online platforms the address is registered on - email providers, social media, professional, e-commerce and entertainment services - and is **billed \$0.05 per request**. It can be enabled with or without `email_enrichment_enabled`: the two add-ons are priced and billed independently. A lookup that finds the address on none of the platforms it covers is a valid, billable answer and triggers `email_no_social_presence_action`. Use `email.social_profiles_registered` (the number of platforms the address is registered on) to branch on the result in a workflow graph.
</Note>

## Database Validation

Feature value: `DATABASE_VALIDATION`.

| Config field                                | Type   | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      |
| ------------------------------------------- | ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `database_validation_countries`             | object | ISO3 country code to `{ "services": ["service_id"] }`. Use service IDs from the Database Validation catalog.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `database_validation_partial_match_action`  | action | Action when database validation returns a partial match.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         |
| `database_validation_no_match_action`       | action | Action when database validation returns no match.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                |
| `database_validation_not_applicable_action` | action | Action when database validation cannot run because the document does not carry the identifier the configured services require (e.g. a passport without a national ID number). Defaults to `NO_ACTION`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           |
| `database_validation_field_sources`         | object | Where to read a database input that no earlier step in the graph can fill. `source` names the producer and `key` names the value inside it: a Document AI field key for `document_ai`, a questionnaire node id for `questionnaire`, and `expected_details.<field>` or `metadata.<key>` for `expected_data`. Exact-key matches against an upstream step resolve automatically and are deliberately not persisted, so renaming a Document AI field never freezes a stale mapping into the config. A malformed entry is dropped on save rather than rejected, which un-satisfies its service and drops it from the selection. Shape: `{"<db_validation_input_field>": {"source": "document_ai"\|"questionnaire"\|"expected_data", "key": "<docai field key>\|<questionnaire node id>\|expected_details.<field>\|metadata.<key>"}}`. |
| `status_rules`                              | array  | Optional custom status rules.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    |

Example:

```json theme={null}
{
  "feature": "DATABASE_VALIDATION",
  "config": {
    "database_validation_countries": {
      "BRA": {
        "services": ["SERVICE_ID_FROM_CATALOG"]
      }
    },
    "database_validation_field_sources": {
      "tax_id": {
        "source": "expected_data",
        "key": "expected_details.document_number"
      }
    },
    "database_validation_no_match_action": "REVIEW",
    "database_validation_partial_match_action": "REVIEW"
  }
}
```

<Warning>
  `database_validation_countries` is what makes this step do anything. A `DATABASE_VALIDATION`
  feature saved without it is accepted and then runs no check at all, so always send at least one
  country with at least one service ID. Service IDs that do not belong to the country you list
  are dropped on save.
</Warning>

## AML

Feature value: `AML`.

For KYC person screening, use these fields:

| Config field                        | Type    | Description                                                                                                                                            |
| ----------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `is_aml_ongoing_monitoring_enabled` | boolean | Enables ongoing AML monitoring.                                                                                                                        |
| `aml_score_approve_threshold`       | integer | Approve threshold.                                                                                                                                     |
| `aml_score_review_threshold`        | integer | Review threshold.                                                                                                                                      |
| `aml_match_score_threshold`         | integer | Match score threshold for possible matches.                                                                                                            |
| `aml_name_weight`                   | integer | Name weight. If any AML weight is provided, name, DOB, and country weights must sum to `100`.                                                          |
| `aml_dob_weight`                    | integer | Date of birth weight.                                                                                                                                  |
| `aml_country_weight`                | integer | Country weight.                                                                                                                                        |
| `create_cases_on_hit`               | boolean | Open a case automatically when the screening returns a hit, instead of leaving the hit to be triaged from the session. Off by default.                 |
| `case_blueprint`                    | uuid    | Which case blueprint the automatically-created case is built from. Only meaningful with `create_cases_on_hit`; the account default is used when unset. |
| `status_rules`                      | array   | Optional custom status rules.                                                                                                                          |

For KYB company screening, use these fields:

| Config field                            | Type    | Description                                                               |
| --------------------------------------- | ------- | ------------------------------------------------------------------------- |
| `kyb_score_approve_threshold`           | integer | Company AML approve threshold.                                            |
| `kyb_score_review_threshold`            | integer | Company AML review threshold.                                             |
| `kyb_enable_ongoing_monitoring`         | boolean | Enables KYB ongoing AML monitoring.                                       |
| `kyb_company_aml_match_score_threshold` | integer | Company AML match score threshold.                                        |
| `kyb_company_aml_name_weight`           | integer | Company name weight. Company AML weights must sum to `100` when provided. |
| `kyb_company_aml_dob_weight`            | integer | Incorporation date or DOB weight.                                         |
| `kyb_company_aml_country_weight`        | integer | Country weight.                                                           |

## Device & IP Analysis

Feature value: `IP_ANALYSIS`.

| Config field                      | Type    | Description                                                                                                                                                                                                              |
| --------------------------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `ip_mismatch_action`              | action  | Action when IP geolocation does not match expected data.                                                                                                                                                                 |
| `vpn_detection_action`            | action  | Action when VPN or proxy usage is detected.                                                                                                                                                                              |
| `expected_ip_mismatch_action`     | action  | Action when the IP does not match the expected IP.                                                                                                                                                                       |
| `duplicated_ip_action`            | action  | Action when the IP is reused suspiciously.                                                                                                                                                                               |
| `duplicated_device_action`        | action  | Action when the same persistent device fingerprint is reused across sessions from different `vendor_data` values.                                                                                                        |
| `recovered_device_action`         | action  | Action when v2 fingerprint recovery links the session to a previously seen device with high confidence after the persistent device ID changed.                                                                           |
| `is_ip_geofencing_enabled`        | boolean | Enables IP geofencing restrictions. When `false`, `ip_geofencing_by_country` is preserved but not enforced.                                                                                                              |
| `ip_geofencing_by_country`        | object  | Per-country IP location rules keyed by ISO-3 country code: `{"USA": {"allowed": true, "states": {"California": {"allowed": false}}}}`. State/region entries override the country flag; countries not listed are allowed. |
| `ip_geofencing_action`            | action  | Action when the session IP is located in a country or state/region that is not allowed. Defaults to `DECLINE`.                                                                                                           |
| `automation_detected_action`      | action  | Verdict when the session looks driven by automation rather than a person.                                                                                                                                                |
| `cross_org_fraud_device_action`   | action  | Verdict when this device was flagged as fraudulent by another organization in the network.                                                                                                                               |
| `cross_org_fraud_ip_action`       | action  | Verdict when this IP was flagged as fraudulent by another organization in the network.                                                                                                                                   |
| `device_app_tampered_action`      | action  | Verdict when the host application binary looks tampered with.                                                                                                                                                            |
| `device_blocklist_action`         | action  | Verdict when the device is on the organization's block list.                                                                                                                                                             |
| `device_debugger_action`          | action  | Verdict when a debugger is attached to the host application.                                                                                                                                                             |
| `device_emulator_action`          | action  | Verdict when the device is an emulator rather than real hardware.                                                                                                                                                        |
| `device_hooking_action`           | action  | Verdict when runtime hooking or instrumentation is detected.                                                                                                                                                             |
| `device_integrity_missing_action` | action  | Verdict when no platform device-integrity attestation was returned.                                                                                                                                                      |
| `device_rooted_action`            | action  | Verdict when the device is rooted or jailbroken.                                                                                                                                                                         |
| `multiple_devices_action`         | action  | Verdict when the session was driven from more than one device.                                                                                                                                                           |
| `status_rules`                    | array   | Optional custom status rules.                                                                                                                                                                                            |

Example:

```json theme={null}
{
  "feature": "IP_ANALYSIS",
  "config": {
    "vpn_detection_action": "REVIEW",
    "duplicated_device_action": "REVIEW",
    "recovered_device_action": "REVIEW",
    "is_ip_geofencing_enabled": true,
    "ip_geofencing_by_country": {
      "USA": { "allowed": true, "states": { "California": { "allowed": false } } },
      "RUS": { "allowed": false, "states": null }
    },
    "ip_geofencing_action": "DECLINE"
  }
}
```

Use `recovered_device_action` separately from `duplicated_device_action` when you want to monitor high-confidence recovered devices before automatically declining them. This is useful during rollout because recovered-device matches are designed for fraud-ring detection but should still be calibrated against your own traffic.

## Proof of Address

Feature value: `PROOF_OF_ADDRESS`.

| Config field                               | Type              | Description                                                                                        |
| ------------------------------------------ | ----------------- | -------------------------------------------------------------------------------------------------- |
| `poa_documents_allowed`                    | object            | ISO3 country code to POA document type config. At least one valid document type should be enabled. |
| `poa_languages_allowed`                    | object            | ISO 639-1 language code to `0` or `1`. At least one language should be enabled.                    |
| `poa_name_or_address_mismatch_action`      | action            | Action when the name or address does not match expected data.                                      |
| `poa_document_issues_action`               | action            | Action when the document has quality or extraction issues.                                         |
| `poa_max_attempts_exceeded_action`         | restricted action | Action when the user exceeds retry attempts. Use `DECLINE` or `REVIEW`.                            |
| `poa_document_authenticity_action`         | restricted action | Action when authenticity checks fail. Use `DECLINE` or `REVIEW`.                                   |
| `poa_unsupported_document_type_action`     | action            | Action when the document type is unsupported.                                                      |
| `poa_unsupported_language_action`          | action            | Action when the document language is unsupported.                                                  |
| `poa_issuer_not_identified_action`         | action            | Action when the document issuer is not identified.                                                 |
| `poa_issue_date_not_detected_action`       | action            | Action when the issue date is missing.                                                             |
| `poa_unparsable_or_invalid_address_action` | action            | Action when the address is invalid or cannot be parsed.                                            |
| `poa_name_match_score_threshold`           | integer           | Name match threshold.                                                                              |
| `poa_max_retry_attempts`                   | integer           | Retry limit, `2` to `5`.                                                                           |
| `status_rules`                             | array             | Optional custom status rules.                                                                      |

## Questionnaire

Feature value: `QUESTIONNAIRE`.

| Config field                    | Type    | Description                                                                                |
| ------------------------------- | ------- | ------------------------------------------------------------------------------------------ |
| `questionnaire_uuid`            | UUID    | Required. Use the `questionnaire_id` returned by `POST /v3/questionnaires/`.               |
| `review_questionnaire_manually` | boolean | Sends questionnaire responses to manual review.                                            |
| `status_rules`                  | array   | Optional custom status rules. You can target `questionnaire.answers.<question_id>` fields. |

## KYB Registry

Feature value: `KYB_REGISTRY`.

| Config field                      | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       |
| --------------------------------- | ------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kyb_accepted_countries`          | object  | Legacy ISO3 country allow-list for business registry lookup. Superseded by `kyb_registry_countries_config`; still readable, still derived from it for existing workflows, but no longer the way to configure new ones.                                                                                                                                                                                                                                                                                                            |
| `kyb_manual_company_action`       | action  | Action when the company requires manual handling.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 |
| `kyb_registry_fields_config`      | object  | Per-field visibility and requiredness for the registry form in the hosted flow. See below.                                                                                                                                                                                                                                                                                                                                                                                                                                        |
| `kyb_registry_countries_config`   | object  | Per-country registry routing, as `{"<ISO2>": {"enabled": bool, "tier": "basic" \| "shareholders" \| "ubo"}}`. Each enabled country picks the data tier charged when a company is selected (`basic` is the Lite tier), and only tiers the [pricing endpoint](/getting-started/kyb-registry-pricing) marks available for that country can be enabled. At least one country must be enabled: a registry check that searches nowhere is rejected. Manually entered companies are billed separately and do not use this configuration. |
| `kyb_registry_monitoring_enabled` | boolean | Keep the company's registry record under continuous monitoring after a Shareholders or UBO result: a change of status, officers, ownership, or address moves the session back to review and fires a webhook. Available only where the registry provider offers monitoring. USD 2.00 per company per year, cancellable at any time. Off by default.                                                                                                                                                                                |
| `kyb_vat_invalid_action`          | action  | Action when the company's VAT number fails EU VIES validation. Defaults to `REVIEW`.                                                                                                                                                                                                                                                                                                                                                                                                                                              |
| `kyb_vat_unverified_action`       | action  | Action when the VAT number could not be validated because VIES was unavailable. Defaults to `NO_ACTION`.                                                                                                                                                                                                                                                                                                                                                                                                                          |
| `status_rules`                    | array   | Optional custom status rules.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     |

`kyb_registry_fields_config` maps each configurable field key to `{"enabled": bool, "required": bool}`. `enabled: false` hides the field, `enabled: true, required: false` shows it as optional, and `enabled: true, required: true` makes it mandatory at submit. `company_name`, `country_code`, and `region` are always shown and required and cannot be configured. When the object is omitted, `null`, or `{}`, the default applies: only `incorporation_date` is required and every other field is optional.

```json theme={null}
{
  "kyb_registry_fields_config": {
    "registration_number": { "enabled": true, "required": true },
    "incorporation_date": { "enabled": true, "required": true },
    "vat_number": { "enabled": true, "required": false },
    "control_scheme": { "enabled": false, "required": false }
  }
}
```

Configurable field keys: `registration_number`, `incorporation_date`, `legal_address`, `vat_number`, `alternative_names`, `tax_number`, `company_type`, `legal_entity_identifier`, `location_of_registration`, `nature_of_business`, `registered_capital_amount`, `registered_capital_currency`, `website`, `email`, `phone`, `control_scheme`. See [configurable registry form fields](/business-verification/company-data#configurable-registry-form-fields) for the end-user behavior and [VAT validation](/business-verification/company-data#vat-validation-vies) for how `vat_number` is checked against VIES.

## KYB Documents

Feature value: `KYB_DOCUMENTS`.

| Config field                                | Type              | Description                                                         |
| ------------------------------------------- | ----------------- | ------------------------------------------------------------------- |
| `kyb_required_document_groups`              | object or array   | Required. Required KYB document groups.                             |
| `kyb_document_subtype_config`               | object            | Per-document subtype enablement and age configuration.              |
| `kyb_document_tampering_action`             | restricted action | Action when tampering is detected. Use `DECLINE` or `REVIEW`.       |
| `kyb_document_critical_mismatch_action`     | restricted action | Action for critical document mismatches. Use `DECLINE` or `REVIEW`. |
| `kyb_document_non_critical_mismatch_action` | action            | Action for non-critical document mismatches.                        |
| `kyb_document_age_action`                   | action            | Action when document age rules fail.                                |
| `kyb_document_max_retry_attempts`           | integer           | Retry limit for KYB documents.                                      |
| `kyb_document_max_attempts_exceeded_action` | restricted action | Action when max attempts are exceeded. Use `DECLINE` or `REVIEW`.   |
| `status_rules`                              | array             | Optional custom status rules.                                       |

## KYB Key People

Feature value: `KYB_KEY_PEOPLE`.

| Config field                              | Type            | Description                                                                                                                                                                                                                                                                                                                                                                                                                                               |
| ----------------------------------------- | --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `kyb_ubo_ownership_threshold`             | integer         | UBO ownership threshold, `0` to `100`.                                                                                                                                                                                                                                                                                                                                                                                                                    |
| `kyb_shareholder_ownership_threshold`     | integer         | Shareholder ownership threshold, `0` to `100`. It cannot be higher than `kyb_ubo_ownership_threshold`.                                                                                                                                                                                                                                                                                                                                                    |
| `kyb_key_people_ownership_required`       | boolean         | Requires an ownership percentage on every submitted key person. Enforced at submission and surfaced to the hosted UI, which marks the field as required. Default `false`.                                                                                                                                                                                                                                                                                 |
| `kyb_require_ubo_kyc`                     | boolean         | Requires UBOs to complete a person verification workflow.                                                                                                                                                                                                                                                                                                                                                                                                 |
| `kyb_ubo_verification_workflow`           | UUID            | Required when `kyb_require_ubo_kyc` is `true`. Must reference a non-KYB workflow in the same application.                                                                                                                                                                                                                                                                                                                                                 |
| `kyb_require_officer_kyc`                 | boolean         | Requires officers to complete person verification.                                                                                                                                                                                                                                                                                                                                                                                                        |
| `kyb_shareholder_verification_workflow`   | UUID            | Person verification workflow for shareholders.                                                                                                                                                                                                                                                                                                                                                                                                            |
| `kyb_officer_verification_workflow`       | UUID            | Person verification workflow for officers.                                                                                                                                                                                                                                                                                                                                                                                                                |
| `kyb_require_corporate_ubo_kyb`           | boolean         | Requires corporate UBOs to complete KYB.                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `kyb_corporate_ubo_verification_workflow` | UUID            | Required when `kyb_require_corporate_ubo_kyb` is `true`. Must reference a KYB workflow in the same application.                                                                                                                                                                                                                                                                                                                                           |
| `kyb_reject_if_ubo_rejected`              | boolean         | Rejects the business when a required UBO verification is rejected.                                                                                                                                                                                                                                                                                                                                                                                        |
| `kyb_wait_for_all_ubos`                   | boolean         | Waits for all required UBO verifications before deciding the KYB session.                                                                                                                                                                                                                                                                                                                                                                                 |
| `kyb_role_config`                         | object or array | Per-role configuration. Each required KYC role must include a `verification_workflow`.                                                                                                                                                                                                                                                                                                                                                                    |
| `kyb_reuse_verified_individuals`          | boolean         | Reuses already verified individuals when possible.                                                                                                                                                                                                                                                                                                                                                                                                        |
| `kyb_notify_parties_by_email`             | boolean         | Sends email notifications to invited key people.                                                                                                                                                                                                                                                                                                                                                                                                          |
| `kyb_key_people_company_fields`           | object          | Which company details are collected for a CORPORATE key person. Same list-of-descriptors shape and same rules as `kyb_key_people_person_fields`. Shape: `[{"key": "<field key>", "label": "<label>", "type": "text"\|"number"\|"date"\|"phone"\|"email", "required": true\|false, "custom": true\|false}]`.                                                                                                                                               |
| `kyb_key_people_document_mismatch_action` | action          | Verdict when a key person's document disagrees with the details declared for them.                                                                                                                                                                                                                                                                                                                                                                        |
| `kyb_key_people_person_fields`            | object          | Which personal details are collected for an individual key person, as an ORDERED LIST of field descriptors (not a map). `key` is required and non-empty; `type` must be one of text, number, date, phone or email; `custom` marks a field the customer added rather than one of the built-ins. Shape: `[{"key": "<field key>", "label": "<label>", "type": "text"\|"number"\|"date"\|"phone"\|"email", "required": true\|false, "custom": true\|false}]`. |
| `kyb_key_people_prefill_from_registry`    | boolean         | Pre-fill the key-people list from the company registry result, so the customer confirms and corrects rather than typing every officer and shareholder in.                                                                                                                                                                                                                                                                                                 |
| `status_rules`                            | array           | Optional custom status rules.                                                                                                                                                                                                                                                                                                                                                                                                                             |

## Document AI

Feature value: `DOCUMENT_AI`.

Requests one or more documents from the user and extracts the named fields you define with a vision model. Each configured field becomes a branchable value `document_ai.<key>`, and the step's outcome is `document_ai.status`.

| Config field                                 | Type              | Description                                                                                                                                 |
| -------------------------------------------- | ----------------- | ------------------------------------------------------------------------------------------------------------------------------------------- |
| `document_ai_documents`                      | array             | Required. The documents to request (at most `3`). Each entry is a document object (see below).                                              |
| `document_ai_unreadable_document_action`     | action            | Action when the document cannot be read or no data can be extracted.                                                                        |
| `document_ai_missing_required_fields_action` | action            | Action when a required field cannot be extracted.                                                                                           |
| `document_ai_document_tampering_action`      | restricted action | Action when the document shows signs of manipulation. Use `DECLINE` or `REVIEW`.                                                            |
| `document_ai_name_mismatch_action`           | action            | Action when the extracted full name does not match the verified identity. Requires a field marked with `is_full_name`.                      |
| `document_ai_unsupported_file_action`        | action            | Action when the uploaded file type is not supported.                                                                                        |
| `document_ai_max_attempts_exceeded_action`   | restricted action | Action when the user exceeds the retry attempts. Use `DECLINE` or `REVIEW`.                                                                 |
| `document_ai_name_match_score_threshold`     | integer           | Minimum score (`0`–`100`) for the extracted full name to match the verified identity. Below it, `document_ai_name_mismatch_action` applies. |
| `document_ai_max_retry_attempts`             | integer           | Retry limit, `2` to `5`.                                                                                                                    |
| `status_rules`                               | array             | Optional custom status rules. You can target `document_ai.<key>` fields.                                                                    |

Each entry in `document_ai_documents` is a document:

| Document field     | Type   | Description                                                                                    |
| ------------------ | ------ | ---------------------------------------------------------------------------------------------- |
| `document_key`     | string | Required. Stable identifier for the document, unique within the step.                          |
| `title`            | string | Required. Title shown to the user.                                                             |
| `description`      | string | Required. Instructions shown to the user about what to upload.                                 |
| `title_i18n`       | object | Optional. Locale code to translated title (e.g. `{ "es": "Comprobante de fondos" }`).          |
| `description_i18n` | object | Optional. Locale code to translated description.                                               |
| `fields`           | array  | Required. The fields to extract (at least one). Field keys must be unique within the document. |

Each entry in a document's `fields` is a field:

| Field          | Type    | Description                                                                                                                                                                                                                                                                                                                                                                                                          |
| -------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `key`          | string  | Required. Stable JSON key for the extracted value, unique within the document. Branch on it as `document_ai.<key>`.                                                                                                                                                                                                                                                                                                  |
| `name`         | string  | Required. Human-readable field label.                                                                                                                                                                                                                                                                                                                                                                                |
| `name_i18n`    | object  | Optional. Locale code to translated field name.                                                                                                                                                                                                                                                                                                                                                                      |
| `instruction`  | string  | Optional. Instruction telling the model exactly what to extract for this field.                                                                                                                                                                                                                                                                                                                                      |
| `type`         | string  | Field type: `text`, `number`, or `date`. Defaults to `text`.                                                                                                                                                                                                                                                                                                                                                         |
| `required`     | boolean | Whether the field must be present. Defaults to `false`. When `true` and the value is missing, `document_ai_missing_required_fields_action` applies.                                                                                                                                                                                                                                                                  |
| `is_full_name` | boolean | Optional, defaults to `false`. Marks the field whose value is the document holder's full name, compared against the verified identity (the ID-verification name, or the session's expected details). **At most one field per document** may set it `true`, and it is **not mandatory** — a document may mark none, in which case no name comparison runs for that document. Only `text` fields can be the full name. |

Example:

```json theme={null}
{
  "feature": "DOCUMENT_AI",
  "config": {
    "document_ai_documents": [
      {
        "document_key": "proof_of_funds",
        "title": "Proof of Funds",
        "description": "Upload a recent bank statement.",
        "title_i18n": { "es": "Comprobante de fondos" },
        "fields": [
          {
            "key": "account_holder",
            "name": "Account holder",
            "instruction": "The full name of the account holder as printed on the statement.",
            "type": "text",
            "required": true,
            "is_full_name": true
          },
          {
            "key": "closing_balance",
            "name": "Closing balance",
            "instruction": "The closing balance amount.",
            "type": "number",
            "required": false
          }
        ]
      }
    ],
    "document_ai_missing_required_fields_action": "REVIEW",
    "document_ai_name_mismatch_action": "REVIEW",
    "document_ai_name_match_score_threshold": 80
  }
}
```


# Get Workflow
Source: https://docs.didit.me/management-api/workflows/get

GET /v3/workflows/{settings_uuid}/
Fetch full configuration for one workflow version by `settings_uuid`: feature toggles, thresholds, allowed documents, graph, retry policy, callbacks, and pricing.

<AgentPromptAccordion title="Get Workflow API Prompt" />


# List Workflows
Source: https://docs.didit.me/management-api/workflows/list

GET /v3/workflows/
List your workflows, newest first, in a limit/offset pagination envelope (`{count, next, previous, results}`, default page size 50). Each row is one version; `workflow_id` is the stable group ID and new sessions use the latest `published` version.

<AgentPromptAccordion title="List Workflows API Prompt" />


# Update Workflow
Source: https://docs.didit.me/management-api/workflows/update

PATCH /v3/workflows/{settings_uuid}/
Update a workflow. Versioning depends on the `status` field you send and the current state of the version: (1) no `status` on a **published** version → the published version is updated in place (same `uuid`, same `version`); (2) no `status` on a **draft** → the draft is updated and immediately published; (3) `status: "published"` on a **published** version → a NEW published version is created under the same `workflow_id` (new `uuid`, `version` + 1) and returned, and any existing draft in the group is deleted; (4) `status: "draft"` keeps a draft as a draft (autosave) but is rejected with 400 on a published version (`"Cannot revert a published version to draft."`). The body accepts the same strict field whitelist as create — unknown keys are rejected with 400.

<AgentPromptAccordion title="Update Workflow API Prompt" />

Use `PATCH` for partial updates. To rename a workflow, send only `workflow_label`.

```json theme={null}
{
  "workflow_label": "Premium KYC"
}
```

To change the checks in the workflow, send the full desired `features` array. This replaces the previous feature order and configuration.

```json theme={null}
{
  "features": [
    {
      "feature": "OCR",
      "config": {
        "documents_allowed": {
          "USA": {
            "DL": {
              "enabled": 1,
              "sides": 2
            }
          }
        }
      }
    },
    {
      "feature": "AML",
      "config": {
        "aml_score_review_threshold": 70,
        "aml_score_approve_threshold": 30
      }
    }
  ]
}
```

The v3 API keeps workflows simple: one linear path and one final status step. Branching, action nodes, and webhook nodes are not accepted here.

## Feature config reference

When you send `features` in a `PATCH`, the array replaces the previous feature order and configuration. Include every required config again.

The exact `config` object depends on the feature. Review the full field list, defaults, required settings, value ranges, and examples in [Workflow Feature Configs](/management-api/workflows/feature-configs).

For `OCR`, omit `config.documents_allowed`, send `null`, or send `{}` to allow every supported document type. Include it only when you want to restrict the workflow to specific countries or document types. For `QUESTIONNAIRE`, `config.questionnaire_uuid` is required.

## Updating workflow settings

You can patch session-level settings without touching the feature list. Send only the fields you want to change.

| Field                     | Type                      | Description                                                                                                |
| ------------------------- | ------------------------- | ---------------------------------------------------------------------------------------------------------- |
| `is_white_label_enabled`  | boolean                   | Enable white-label customization for sessions created with this workflow.                                  |
| `is_desktop_allowed`      | boolean                   | Allow the verification flow to run on desktop browsers.                                                    |
| `max_retry_attempts`      | integer (0–10)            | Maximum retry attempts allowed after a declined verification. `0` blocks the user after the first decline. |
| `retry_window_days`       | integer (1–365) or `null` | Rolling window in days used to count retries (`null` = all-time limit).                                    |
| `session_expiration_time` | integer (3600–2419200)    | Seconds before an unfinished session expires. Minimum 1 hour, maximum 4 weeks.                             |

```json theme={null}
{
  "is_white_label_enabled": true,
  "is_desktop_allowed": true,
  "max_retry_attempts": 5,
  "retry_window_days": 14,
  "session_expiration_time": 86400
}
```

Use the workflow `uuid` returned by the list, create, or get endpoint as `settings_uuid` in this URL.


# Data models
Source: https://docs.didit.me/reference/data-models

Canonical JSON schemas for every Didit report object — NFC, ID, Liveness, Face Match, AML, IP, POA, Phone, Email, KYB Registry, Documents, Key People.

## Overview

Every per-feature report follows the V3 serializer shape defined in `service-didit-verification`. The same object appears in three places, so the schema you see here is the single source of truth across them:

* `GET /v3/session/{sessionId}/decision/` — each feature is returned as a plural array (`id_verifications[]`, `nfc_verifications[]`, `liveness_checks[]`, `face_matches[]`, `poa_verifications[]`, `phone_verifications[]`, `email_verifications[]`, `aml_screenings[]`, `ip_analyses[]`, `database_validations[]`, `questionnaire_responses[]`, and the KYB equivalents `registry_checks[]`, `document_verifications[]`, `key_people_checks[]`).
* Webhook payloads (`status.updated`, `data.updated`) — same shape inside the `decision` envelope.
* Standalone APIs — single-object responses (Face Search, Age Estimation, Biometric Authentication) reuse the same field set.

<Note>
  V3 introduced multi-instance workflows: every feature object carries a `node_id` that pins the report to the workflow graph node that produced it. V2 endpoints (singular `kyc`, `face`, `aml`, etc.) remain backwards-compatible but only return the first instance.
</Note>

## Common fields

Every report object exposes the following:

| Field      | Type                                        | Description                                                                                                                                                                                                                                                                 |
| ---------- | ------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `status`   | string                                      | Feature-level lifecycle status — one of the values in [Status enum](#status-enum-reference). Source: `common/config/choices.py:FeatureStatusChoices` (lines 343-348). The parent session's top-level `status` uses the wider session enum (`StatusChoices`, lines 106-117). |
| `node_id`  | string \| null                              | Workflow graph node identifier. Populated for V3 multi-instance workflows; `null` for legacy single-feature sessions.                                                                                                                                                       |
| `warnings` | array of [warning objects](#warning-object) | Risk signals filtered to this feature and `node_id`. Returned by `Session.get_logs(...)` (`sessions/models/session.py:1611`).                                                                                                                                               |

Media fields (`portrait_image`, `front_image`, `document_file`, …) are presigned URLs with a limited validity window — download them promptly rather than persisting the URL. Examples show them as `https://<media-host>/...`.

## Warning object

Returned in every `warnings[]` array. Schema from `logs/serializers/log.py:8-65` (`LogV3Serializer`).

| Field               | Type           | Nullable | Description                                                                                                                                                                                                                                                                                                     | Example                                                                              |
| ------------------- | -------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `feature`           | string (enum)  | No       | Which feature emitted the warning. Values from `LogWarningChoices` (`common/config/choices.py:190-204`): `ID_VERIFICATION`, `NFC`, `LIVENESS`, `FACEMATCH`, `PROOF_OF_ADDRESS`, `PHONE`, `EMAIL`, `AML`, `LOCATION`, `DATABASE_VALIDATION`, `QUESTIONNAIRE`, `KYB_REGISTRY`, `KYB_DOCUMENTS`, `KYB_KEY_PEOPLE`. | `"ID_VERIFICATION"`                                                                  |
| `risk`              | string         | No       | Stable risk code (e.g. `DOCUMENT_EXPIRED`, `LOW_LIVENESS_SCORE`). Values from `logs/choices.py:RiskChoices`. Used as the key into description tables.                                                                                                                                                           | `"DOCUMENT_EXPIRED"`                                                                 |
| `additional_data`   | object \| null | Yes      | Risk-specific context (e.g. score thresholds, matched fields). Shape varies by risk code.                                                                                                                                                                                                                       | `{ "score": 42.1, "threshold": 70 }`                                                 |
| `log_type`          | string (enum)  | No       | One of `error`, `warning`, `information`. From `LogTypeChoices` (`common/config/choices.py:207-210`).                                                                                                                                                                                                           | `"error"`                                                                            |
| `short_description` | string         | No       | Human-readable label for the risk. From `logs/choices.py:RISK_SHORT_DESCRIPTIONS`.                                                                                                                                                                                                                              | `"Document expired"`                                                                 |
| `long_description`  | string         | No       | Longer human-readable explanation suitable for end-user-facing surfaces. From `logs/choices.py:RISK_LONG_DESCRIPTIONS`.                                                                                                                                                                                         | `"The document's expiration date has passed, rendering it no longer valid for use."` |
| `node_id`           | string \| null | Yes      | Workflow graph node the warning was raised against. `null` for legacy V2 logs without `node_id`.                                                                                                                                                                                                                | `"first_id_verification"`                                                            |

```json theme={null}
{
  "feature": "ID_VERIFICATION",
  "risk": "DOCUMENT_EXPIRED",
  "additional_data": null,
  "log_type": "error",
  "short_description": "Document expired",
  "long_description": "The document's expiration date has passed, rendering it no longer valid for use.",
  "node_id": "first_id_verification"
}
```

## Report objects

The remaining sections cover each per-feature report object. The H3 heading text is intentionally stable so other docs can deep-link to it.

### ID verification

Returned from each KYC/ID document a user submits. Appears as `id_verifications[]` in `GET /v3/session/{sessionId}/decision/` and inside the `kyc` field of V2 responses. Source: `kyc/serializers/kyc.py:383-414` (`IDVerificationV3Serializer`, extends `IDVerificationV2Serializer` at `kyc/serializers/kyc.py:320-380`).

| Field                                       | Type                        | Nullable | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Example                                                                                      |
| ------------------------------------------- | --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `status`                                    | string                      | No       | See [Status enum](#status-enum-reference).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `"Approved"`                                                                                 |
| `document_type`                             | string                      | Yes      | Human-readable document class (`Passport`, `Identity Card`, `Driver's License`, `Residence Permit`, `Health Insurance Card`, `Tax Card`, `Social Security Card`, `Work Permit`, `Visa`, `Public Service Card`, `Birth Certificate`, `Firearm License`, `Other`). Source: `DOC_TYPE_MAPPING` (`common/config/choices.py:1275-1289`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `"Passport"`                                                                                 |
| `document_subtype`                          | string                      | Yes      | Document subtype code from Didit's document registry, filtered to what the workflow's document settings accept. Region-specific documents include the region. Full code list: [Document subtypes](/core-technology/id-verification/document-subtypes-id-verification).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `"QUEENSLAND_DRIVER_LICENSE_GENERIC"`                                                        |
| `document_number`                           | string                      | Yes      | OCR-extracted document number.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `"AB1234567"`                                                                                |
| `personal_number`                           | string                      | Yes      | OCR-extracted personal/national identifier.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `"99999999R"`                                                                                |
| `portrait_image`                            | string (URL)                | Yes      | Presigned URL to the face crop.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `"https://<media-host>/.../portrait.jpg?..."`                                                |
| `front_image`                               | string (URL)                | Yes      | Presigned URL to the cleaned document front.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `"https://<media-host>/.../front.jpg?..."`                                                   |
| `front_video`                               | string (URL)                | Yes      | Presigned URL to the front capture video (when available).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `"https://<media-host>/.../front.mp4?..."`                                                   |
| `back_image`                                | string (URL)                | Yes      | Presigned URL to the cleaned document back.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `"https://<media-host>/.../back.jpg?..."`                                                    |
| `back_video`                                | string (URL)                | Yes      | Presigned URL to the back capture video.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `null`                                                                                       |
| `full_front_image`                          | string (URL)                | Yes      | Unclipped (full-frame) front capture.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `"https://<media-host>/.../full_front.jpg?..."`                                              |
| `full_back_image`                           | string (URL)                | Yes      | Unclipped (full-frame) back capture.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `null`                                                                                       |
| `front_image_camera_front`                  | string (URL)                | Yes      | Front-camera image taken at the same time as the document front.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `null`                                                                                       |
| `back_image_camera_front`                   | string (URL)                | Yes      | Front-camera image taken at the same time as the document back.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `null`                                                                                       |
| `front_image_camera_front_face_match_score` | float (0-100)               | Yes      | Similarity between the document portrait and the front-camera capture.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `null`                                                                                       |
| `back_image_camera_front_face_match_score`  | float (0-100)               | Yes      | Same as above but for the back capture.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `null`                                                                                       |
| `front_image_quality_score`                 | object                      | Yes      | Quality metrics for the front image: scores 0-100 (`focus_score`, `brightness_score`, `resolution_score`, `overall_score`), plus `brightness_issue` (`ok`, `too_dark`, `too_bright`) and `is_document_fully_visible` (boolean).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `{ "focus_score": 91.0, "overall_score": 88.5 }`                                             |
| `back_image_quality_score`                  | object                      | Yes      | Same shape as `front_image_quality_score`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `null`                                                                                       |
| `date_of_birth`                             | string (YYYY-MM-DD)         | Yes      | OCR-extracted DOB.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `"1990-05-12"`                                                                               |
| `age`                                       | integer                     | Yes      | Computed age in years at extraction time.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `35`                                                                                         |
| `expiration_date`                           | string (YYYY-MM-DD)         | Yes      | Document expiration.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `"2032-05-11"`                                                                               |
| `date_of_issue`                             | string (YYYY-MM-DD)         | Yes      | Document issue date.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `"2022-05-11"`                                                                               |
| `issuing_state`                             | string (ISO 3166-1 alpha-3) | Yes      | Issuing country code.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `"ESP"`                                                                                      |
| `issuing_state_name`                        | string                      | Yes      | Localized issuing country name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `"Spain"`                                                                                    |
| `first_name`                                | string                      | Yes      | OCR-extracted given name(s).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `"María"`                                                                                    |
| `last_name`                                 | string                      | Yes      | OCR-extracted surname(s).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `"García López"`                                                                             |
| `full_name`                                 | string                      | Yes      | Full normalized name (vendor-supplied).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `"María García López"`                                                                       |
| `gender`                                    | string                      | Yes      | `M`, `F`, or other vendor-supplied value.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `"F"`                                                                                        |
| `address`                                   | string                      | Yes      | Raw OCR-extracted address line.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `"Calle Mayor 1, 28001 Madrid"`                                                              |
| `formatted_address`                         | string                      | Yes      | Geocoded/formatted address (when parseable).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `"Calle Mayor 1, 28001 Madrid, Spain"`                                                       |
| `parsed_address`                            | object                      | Yes      | Structured, geocoded address: `street_1`, `street_2`, `city`, `region`, `country`, `postal_code`, `address_type`, `formatted_address`, `document_location` (`{latitude, longitude}`), `raw_results`, `is_best_match`. Source: `kyc/utils/address.py:147-197`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `{ "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001", "country": "ES" }` |
| `place_of_birth`                            | string                      | Yes      | OCR-extracted place of birth.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `"Madrid"`                                                                                   |
| `marital_status`                            | string                      | Yes      | When extractable.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `null`                                                                                       |
| `nationality`                               | string (ISO 3166-1 alpha-3) | Yes      | OCR-extracted nationality.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `"ESP"`                                                                                      |
| `extra_fields`                              | object                      | Yes      | Document-type-specific fields not covered by the canonical schema (e.g. driver license categories).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `{ "DL Class": "B" }`                                                                        |
| `mrz`                                       | object                      | Yes      | Parsed MRZ fields when present (`document_number`, `birth_date`, `expiry_date`, `surname`, `given_names`, …).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `{ "document_number": "AB1234567", "surname": "GARCIA", "given_names": "MARIA" }`            |
| `extra_files`                               | array of strings (URL)      | No       | Presigned URLs to any additional uploaded files.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `[]`                                                                                         |
| `matches`                                   | array of objects            | No       | Cross-session document matches. Each item: `{ session_id, session_number, vendor_data, verification_date, user_details: { name, document_type, document_number }, status, is_blocklisted, api_service, front_image_url }`. `front_image_url` is presigned.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `[]`                                                                                         |
| `verification_method`                       | string                      | No       | Which [ID Verification method](/core-technology/id-verification/verification-methods) produced this row: `document`, `id_lookup` or `wallet`. Always `document` for a photographed document, including every session created before the other methods existed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `"id_lookup"`                                                                                |
| `assurance`                                 | string                      | No       | Assurance tier derived from `verification_method`: `documentary`, `data_match` or `cryptographic`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `"data_match"`                                                                               |
| `wallet_provider`                           | string \| null              | Yes      | Catalog wallet id when a wallet produced this row (`mitid`, `bankid_se`, `itsme`, ...). `null` otherwise.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `"mitid"`                                                                                    |
| `fallback_from`                             | object \| null              | Yes      | Why a non-document method ended the ID step: `{ method, reason, action }`. Set on the declined row when a lookup or a wallet sign-in failed and the country's switch was `decline`. Current staging also preserves it on the resulting document verification after a fallback; confirm production rollout. `null` when no earlier non-document failure is recorded.                                                                                                                                                                                                                                                                                                                                                                                                                                        | `{ "method": "id_lookup", "reason": "no_match", "action": "decline" }`                       |
| `id_lookup`                                 | object \| null              | Yes      | Source evidence, present only when `verification_method` is `id_lookup`: `source` (the exact source queried — a government register in most countries, a credit-bureau or residential-records file in some), `checked_at`, `attempts`, `max_attempts`, `outcome` (`match`, `partial_match`, `no_match`, `provider_error`, `format_rejected`), `comparison[]` (`{ field, label, provided, record, result }`; `field` is one of `identification_number`, `full_name`, `date_of_birth`, `address`, and `result` is `match`, `partial` or `no_match`; earlier releases may include a `provider` row with `error`), `source_errors[]` (current staging: separate source diagnostics; confirm production rollout), `registry_portrait` (presigned URL, only for sources that return one) and `face_match_score`. | see below                                                                                    |
| `wallet_verification`                       | object \| null              | Yes      | Credential evidence, present only when `verification_method` is `wallet`: `provider`, `provider_name`, `issuing_authority`, `issuing_country`, `credential_type`, `level_of_assurance` (`low`, `substantial`, `high`), `verified_at`, `signature_valid`, `attributes` (what the wallet shared), `portrait` (presigned URL when the wallet shares one) and `face_match_score`.                                                                                                                                                                                                                                                                                                                                                                                                                              | see below                                                                                    |
| `node_id`                                   | string \| null              | Yes      | Workflow node identifier (V3).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `"first_id_verification"`                                                                    |
| `warnings`                                  | array                       | No       | See [Warning object](#warning-object).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `[]`                                                                                         |

```json theme={null}
{
  "status": "Approved",
  "document_type": "Passport",
  "document_subtype": "PASSPORT_GENERIC",
  "document_number": "AB1234567",
  "personal_number": "99999999R",
  "portrait_image": "https://<media-host>/.../portrait.jpg?signature=...",
  "front_image": "https://<media-host>/.../front.jpg?signature=...",
  "front_video": null,
  "back_image": "https://<media-host>/.../back.jpg?signature=...",
  "back_video": null,
  "full_front_image": "https://<media-host>/.../full_front.jpg?signature=...",
  "full_back_image": null,
  "front_image_camera_front": null,
  "back_image_camera_front": null,
  "front_image_camera_front_face_match_score": null,
  "back_image_camera_front_face_match_score": null,
  "front_image_quality_score": {
    "focus_score": 91.0,
    "brightness_score": 88.0,
    "brightness_issue": "ok",
    "is_document_fully_visible": true,
    "resolution_score": 95.0,
    "overall_score": 88.5
  },
  "back_image_quality_score": null,
  "date_of_birth": "1990-05-12",
  "age": 35,
  "expiration_date": "2032-05-11",
  "date_of_issue": "2022-05-11",
  "issuing_state": "ESP",
  "issuing_state_name": "Spain",
  "first_name": "María",
  "last_name": "García López",
  "full_name": "María García López",
  "gender": "F",
  "address": "Calle Mayor 1, 28001 Madrid",
  "formatted_address": "Calle Mayor 1, 28001 Madrid, Spain",
  "parsed_address": { "street_1": "Calle Mayor 1", "street_2": null, "city": "Madrid", "region": "Madrid", "postal_code": "28001", "country": "ES", "address_type": "Calle" },
  "place_of_birth": "Madrid",
  "marital_status": null,
  "nationality": "ESP",
  "extra_fields": {},
  "mrz": {
    "document_number": "AB1234567",
    "surname": "GARCIA",
    "given_names": "MARIA",
    "birth_date": "900512",
    "expiry_date": "320511"
  },
  "extra_files": [],
  "matches": [],
  "node_id": "first_id_verification",
  "verification_method": "document",
  "assurance": "documentary",
  "wallet_provider": null,
  "fallback_from": null,
  "id_lookup": null,
  "wallet_verification": null,
  "warnings": []
}
```

The same object with a non-document method. Only the method-specific keys change — everything a document read fills in is populated from the register record or the wallet attributes instead, and the keys that do not apply are `null`.

```json theme={null}
{
  "status": "Approved",
  "issuing_state": "ZAF",
  "first_name": "Thabo",
  "last_name": "Mokoena",
  "full_name": "Thabo Mokoena",
  "date_of_birth": "1991-06-15",
  "personal_number": "9106155043088",
  "node_id": "first_id_verification",
  "verification_method": "id_lookup",
  "assurance": "data_match",
  "wallet_provider": null,
  "fallback_from": null,
  "id_lookup": {
    "source": "Department of Home Affairs",
    "checked_at": "2026-09-04T09:12:44Z",
    "attempts": 1,
    "max_attempts": 2,
    "outcome": "match",
    "comparison": [
      { "field": "identification_number", "label": "ID number", "provided": "9106155043088", "record": "9106155043088", "result": "match" },
      { "field": "full_name", "label": "Full name", "provided": "Thabo Mokoena", "record": "Thabo Mokoena", "result": "match" },
      { "field": "date_of_birth", "label": "Date of birth", "provided": "1991-06-15", "record": "1991-06-15", "result": "match" }
    ],
    "registry_portrait": "https://<media-host>/.../registry_portrait.jpg?signature=...",
    "face_match_score": 96.4
  },
  "wallet_verification": null,
  "warnings": []
}
```

```json theme={null}
{
  "status": "Approved",
  "issuing_state": "DNK",
  "first_name": "Freja",
  "last_name": "Nielsen",
  "full_name": "Freja Nielsen",
  "date_of_birth": "1988-03-02",
  "node_id": "first_id_verification",
  "verification_method": "wallet",
  "assurance": "cryptographic",
  "wallet_provider": "mitid",
  "fallback_from": null,
  "id_lookup": null,
  "wallet_verification": {
    "provider": "mitid",
    "provider_name": "MitID",
    "issuing_authority": "Danish Agency for Digital Government",
    "issuing_country": "DNK",
    "credential_type": "person_identification",
    "level_of_assurance": "substantial",
    "verified_at": "2026-09-04T09:12:44Z",
    "signature_valid": true,
    "attributes": {
      "full_name": "Freja Nielsen",
      "date_of_birth": "1988-03-02",
      "cpr_alias": "b0f1c2d3-e4f5-4678-9abc-def012345678"
    },
    "portrait": null,
    "face_match_score": null
  },
  "warnings": []
}
```

### NFC verification

Returned for each ePassport chip read against an ID document. Appears as `nfc_verifications[]` in `GET /v3/session/{sessionId}/decision/` (one per parent KYC record). Source: `kyc/serializers/epassport.py:121-139` (`NFCV3Serializer`, extends `NFCV2Serializer` at `kyc/serializers/epassport.py:83-118`).

| Field                 | Type           | Nullable | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | Example                                                                                          |
| --------------------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `status`              | string         | No       | See [Status enum](#status-enum-reference).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `"Approved"`                                                                                     |
| `portrait_image`      | string (URL)   | Yes      | Presigned URL to the chip-extracted face image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `"https://<media-host>/.../nfc_portrait.jpg?..."`                                                |
| `signature_image`     | string (URL)   | Yes      | Presigned URL to the chip-extracted signature image (when stored on the chip).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `null`                                                                                           |
| `chip_data`           | object         | Yes      | Personal data parsed from the chip's Data Groups, flattened (`kyc/utils/epassport.py:165-212`): `dgs` (Data Groups read), `surname`, `name`, `country`, `nationality`, `birth_date` (`YYYY-MM-DD`), `expiry_date` (`YYYY-MM-DD`), `sex` (`M`/`F`), `document_type` (MRZ document code), `document_number`, `optional_data`, MRZ check digits (`birth_date_hash`, `expiry_date_hash`, `document_number_hash`, `optional_data_hash`, `final_hash`), `mrz_string`, `mrz_type` (`TD1`/`TD2`/`TD3`); plus `place_of_birth` and `address` (and `full_name` / `full_name_non_latin` for non-Latin names) when the chip carries DG11 — those keys are absent otherwise. `null` when the NFC step was skipped. | `{ "document_number": "AB1234567", "name": "MARIA" }`                                            |
| `authenticity`        | object         | No       | `{ sod_integrity, dg_integrity }`. `sod_integrity` validates that the Document Security Object (SOD) signature chains to a valid issuing-country CSCA (and the DSC is neither revoked nor expired); `dg_integrity` validates that each Data Group hashes match the SOD. Both `true` means the chip is genuine and untampered.                                                                                                                                                                                                                                                                                                                                                                         | `{ "sod_integrity": true, "dg_integrity": true }`                                                |
| `certificate_summary` | object         | Yes      | Summary of the document-signer certificate (`kyc/utils/epassport.py:338-348`): `issuer`, `subject`, `serial_number` (integer), `not_valid_before`, `not_valid_after` (`YYYY-MM-DD HH:MM:SS`), plus a `validation` object `{ csca_verified, dsc_revoked, dsc_expired, csca_expired }` (`kyc/views/epassport.py:86`).                                                                                                                                                                                                                                                                                                                                                                                   | `{ "issuer": "Common Name: CSCA SPAIN, Country: ES", "not_valid_after": "2031-02-18 10:21:11" }` |
| `node_id`             | string \| null | Yes      | Workflow node identifier (V3).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `"first_nfc"`                                                                                    |
| `is_nfc_skipped`      | boolean        | No       | `true` when this NFC step was explicitly skipped instead of read; `skip_reason` says why.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `false`                                                                                          |
| `skip_reason`         | string         | Yes      | Why the step was skipped — only set when `is_nfc_skipped` is `true`. One of `USER_SKIPPED`, `DOCUMENT_WITHOUT_CHIP`, `CHIP_CERTIFICATE_UNAVAILABLE`, `DEVICE_WITHOUT_NFC`, `INTEGRATION_WITHOUT_NFC_ACCESS`, `MRZ_KEY_UNAVAILABLE`; see [Skip reasons](/core-technology/nfc-verification/warnings-nfc-verification#skip-reasons). The decision payload also carries a session-level `nfc_skip_reason` with the same taxonomy, covering NFC steps that were bypassed before creating any report.                                                                                                                                                                                                       | `null`                                                                                           |
| `warnings`            | array          | No       | See [Warning object](#warning-object).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `[]`                                                                                             |

```json theme={null}
{
  "status": "Approved",
  "portrait_image": "https://<media-host>/.../nfc_portrait.jpg?signature=...",
  "signature_image": null,
  "chip_data": {
    "dgs": ["DG1", "DG2", "DG11"],
    "surname": "GARCIA LOPEZ",
    "name": "MARIA",
    "country": "ESP",
    "nationality": "ESP",
    "birth_date": "1990-05-12",
    "expiry_date": "2032-05-11",
    "sex": "F",
    "document_type": "P",
    "document_number": "AB1234567",
    "optional_data": "",
    "birth_date_hash": "4",
    "expiry_date_hash": "7",
    "document_number_hash": "3",
    "optional_data_hash": "",
    "final_hash": "8",
    "mrz_string": "P<ESPGARCIA<LOPEZ<<MARIA<<<<<<<<<<<<<<<<<<<<AB1234567ESP9005124F3205117<<<<<<<<<<<<<<08",
    "mrz_type": "TD3",
    "place_of_birth": "MADRID",
    "address": "CALLE MAYOR 1, MADRID"
  },
  "authenticity": { "sod_integrity": true, "dg_integrity": true },
  "certificate_summary": {
    "issuer": "Common Name: CSCA SPAIN, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
    "subject": "Common Name: DS n-eID SPAIN 2, Organizational Unit: PASSPORT, Organization: DIRECCION GENERAL DE LA POLICIA, Country: ES",
    "serial_number": 118120836164494130086420187336801405660,
    "not_valid_before": "2020-11-18 10:21:11",
    "not_valid_after": "2031-02-18 10:21:11",
    "validation": {
      "csca_verified": true,
      "dsc_revoked": false,
      "dsc_expired": false,
      "csca_expired": false
    }
  },
  "node_id": "first_nfc",
  "is_nfc_skipped": false,
  "skip_reason": null,
  "warnings": []
}
```

### Liveness check

Returned per liveness session. Appears as `liveness_checks[]` in `GET /v3/session/{sessionId}/decision/`. Source: `face/serializers/face.py:301-320` (`LivenessV3Serializer`, extends `LivenessV2Serializer` at `face/serializers/face.py:216-298`).

| Field             | Type             | Nullable | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Example                                        |
| ----------------- | ---------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------- |
| `status`          | string           | No       | See [Status enum](#status-enum-reference).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `"Approved"`                                   |
| `method`          | string (enum)    | Yes      | `ACTIVE_3D`, `FLASHING`, or `PASSIVE` (`LivenessMethodChoices`, `common/config/choices.py:514-517`). Passive runs when desktop sessions are allowed and the user is on a desktop.                                                                                                                                                                                                                                                                                                                                                                                      | `"PASSIVE"`                                    |
| `score`           | float (0-100)    | Yes      | Liveness confidence, rounded to 2 decimals.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `92.41`                                        |
| `reference_image` | string (URL)     | Yes      | Presigned URL to the user's reference face crop.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `"https://<media-host>/.../reference.jpg?..."` |
| `video_url`       | string (URL)     | Yes      | Presigned URL to the liveness video (active mode only).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `"https://<media-host>/.../liveness.webm?..."` |
| `age_estimation`  | float            | Yes      | Estimated age (in years) of the largest face in the reference image.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `34.2`                                         |
| `matches`         | array of objects | No       | Cross-session face matches. Each item: `{ session_id, session_number, similarity_percentage, vendor_data, vendor_user_id, biometric_template_id, verification_date, user_details: { full_name, document_type, document_number }, match_image_url, status, is_blocklisted, is_allowlisted, api_service, source }`. `source` is `session`, `imported`, `list_entry`, or `retained_template`. A retained-template match has `vendor_user_id`, `vendor_data`, and `biometric_template_id`; its session, image, identity-detail, status, and API-service fields are `null`. | `[]`                                           |
| `face_quality`    | float (0-100)    | Yes      | Passive-liveness face-quality score (normalized to a percentage).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `87.50`                                        |
| `face_luminance`  | float (0-100)    | Yes      | Passive-liveness face-luminance score (normalized from 0-255 to a percentage).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `54.12`                                        |
| `node_id`         | string \| null   | Yes      | Workflow node identifier (V3).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `"first_liveness"`                             |
| `warnings`        | array            | No       | See [Warning object](#warning-object).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `[]`                                           |

```json theme={null}
{
  "status": "Approved",
  "method": "PASSIVE",
  "score": 92.41,
  "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
  "video_url": null,
  "age_estimation": 34.2,
  "matches": [],
  "face_quality": 87.50,
  "face_luminance": 54.12,
  "node_id": "first_liveness",
  "warnings": []
}
```

### Face match

Returned per face-match comparison (typically the user's liveness face against the document portrait). Appears as `face_matches[]` in `GET /v3/session/{sessionId}/decision/`. Source: `face/serializers/face.py:367-389` (`FaceMatchV3Serializer`, extends `FaceMatchV2Serializer` at `face/serializers/face.py:323-364`).

| Field                     | Type           | Nullable | Description                                                                                                                                                                                                                                             | Example                                     |
| ------------------------- | -------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `status`                  | string         | No       | See [Status enum](#status-enum-reference).                                                                                                                                                                                                              | `"Approved"`                                |
| `score`                   | float (0-100)  | Yes      | Similarity, rounded to 2 decimals. When the provider returns only an `unmatched_faces[].Confidence`, it's converted to `100 - confidence`.                                                                                                              | `97.83`                                     |
| `source_image_session_id` | string (UUID)  | Yes      | The session whose stored portrait supplied the source (reference) image — set in portrait-based flows (biometric authentication, or a portrait supplied at session creation). `null` when the reference is the document portrait from the same session. | `null`                                      |
| `source_image`            | string (URL)   | Yes      | Presigned URL to the source (reference) image — usually the document portrait, or the stored portrait in biometric-authentication flows.                                                                                                                | `"https://<media-host>/.../source.jpg?..."` |
| `target_image`            | string (URL)   | Yes      | Presigned URL to the target (live face) image captured during liveness.                                                                                                                                                                                 | `"https://<media-host>/.../target.jpg?..."` |
| `node_id`                 | string \| null | Yes      | Workflow node identifier (V3).                                                                                                                                                                                                                          | `"first_face_match"`                        |
| `warnings`                | array          | No       | See [Warning object](#warning-object).                                                                                                                                                                                                                  | `[]`                                        |

```json theme={null}
{
  "status": "Approved",
  "score": 97.83,
  "source_image_session_id": null,
  "source_image": "https://<media-host>/.../source.jpg?signature=...",
  "target_image": "https://<media-host>/.../target.jpg?signature=...",
  "node_id": "first_face_match",
  "warnings": []
}
```

### Face search

Returned by the standalone Face Search API (`POST /v3/face-search/`). Face Search never appears as a plural array in `/v3/session/{sessionId}/decision/` — when persisted with `save_api_request=true` the session surfaces there as a `FACE_SEARCH` entry in `features[]` plus a `liveness_checks[]` item carrying the stored `matches`. Sources: `apis/serializers/face_search.py:8-79` (`FaceSearchResponseSerializer` wrapping `FaceSearchDetailsSerializer`); match dicts built in `face/utils/utils.py:869-884`.

Top-level response:

| Field         | Type              | Nullable | Description                                                                                                                                          | Example                                  |
| ------------- | ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------- |
| `request_id`  | string (UUID)     | No       | The persisted session id when `save_api_request=true` (usable with `GET /v3/session/{sessionId}/decision/`); otherwise a transient correlation UUID. | `"4a1c2c4e-8b1b-4d6a-91b5-ee9a1f3a2c7f"` |
| `face_search` | object            | No       | The search-details payload — see fields below.                                                                                                       | —                                        |
| `vendor_data` | string            | Yes      | Echoed `vendor_data` from the request.                                                                                                               | `null`                                   |
| `metadata`    | object            | Yes      | Echoed `metadata` from the request.                                                                                                                  | `null`                                   |
| `created_at`  | string (ISO 8601) | No       | Server-side request timestamp.                                                                                                                       | `"2026-06-12T01:04:42.763237+00:00"`     |

`face_search` object:

| Field           | Type                                                            | Nullable | Description                                                                                                                                                                                                                                                                                                                 | Example                                                                                 |
| --------------- | --------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
| `status`        | string                                                          | No       | `Declined` only when a `FACE_IN_BLOCKLIST` or `POSSIBLE_FACE_IN_BLOCKLIST` warning fired; `Approved` otherwise — duplicate matches alone never decline (`apis/views/face_search.py:242-248`).                                                                                                                               | `"Approved"`                                                                            |
| `total_matches` | integer                                                         | No       | Number of returned matches in `matches[]` (0–5).                                                                                                                                                                                                                                                                            | `1`                                                                                     |
| `matches`       | array of [face-search match objects](#face-search-match-object) | No       | Up to 5 matches above the similarity floor, sorted by descending similarity (blocklisted entries first with `search_type=blocklisted_or_approved`).                                                                                                                                                                         | `[…]`                                                                                   |
| `user_image`    | object                                                          | No       | Detection result for the submitted image: `{ entities: [{ bbox, confidence }], best_angle }` — one entity per detected face.                                                                                                                                                                                                | `{ "entities": [{ "bbox": [40, 40, 120, 120], "confidence": 0.73 }], "best_angle": 0 }` |
| `warnings`      | array of objects                                                | No       | Reduced warning shape for this standalone API — no `node_id`. The serializer contract declares `{ risk, additional_data, log_type, short_description, long_description }` (`apis/serializers/face_search.py:49-54`); the runtime payload also carries `feature`, always `"LIVENESS"` (`apis/views/face_search.py:332-341`). | `[]`                                                                                    |

#### Face-search match object

| Field                   | Type              | Nullable | Description                                                                                                                                                                                                                                                                                                                                   | Example                                                                                              |
| ----------------------- | ----------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------- |
| `session_id`            | string (UUID)     | Yes      | The matched verification session. `null` when `source` is `imported`, `list_entry`, or `retained_template`.                                                                                                                                                                                                                                   | `"a3f2a6f1-…"`                                                                                       |
| `session_number`        | integer           | Yes      | Console-friendly number of the matched session; `null` for non-session matches.                                                                                                                                                                                                                                                               | `1024`                                                                                               |
| `similarity_percentage` | float (0-100)     | No       | Similarity between the submitted face and the matched face.                                                                                                                                                                                                                                                                                   | `96.42`                                                                                              |
| `source`                | string (enum)     | No       | Where the matched face was enrolled from: `session` (verification session or saved standalone call), `imported` (direct user-profile face upload), `list_entry` (face attached to a list), `retained_template` (image-free [biometric template](/management-api/biometric-templates/overview) retained after the source session was deleted). | `"session"`                                                                                          |
| `vendor_data`           | string            | Yes      | The matched session's `vendor_data`, or the linked User's for `imported` and `retained_template` matches.                                                                                                                                                                                                                                     | `"user-12345"`                                                                                       |
| `vendor_user_id`        | string (UUID)     | Yes      | The linked User. `null` for `list_entry` matches and for sessions without a User.                                                                                                                                                                                                                                                             | `"2f7c1a9e-…"`                                                                                       |
| `biometric_template_id` | string (UUID)     | Yes      | The retained template that matched. Set only for `retained_template` matches; use it with `GET`/`DELETE /v3/biometric-templates/{id}/`.                                                                                                                                                                                                       | `null`                                                                                               |
| `verification_date`     | string (ISO 8601) | Yes      | When the matched face was captured, or when a `retained_template` was retained; `null` for `list_entry` matches.                                                                                                                                                                                                                              | `"2024-11-04T09:14:02Z"`                                                                             |
| `user_details`          | object            | Yes      | `{ full_name, document_type, document_number }` from the matched session's document verification; for `imported` matches only `full_name` is set; `null` when no identity data exists and always `null` for `retained_template` matches.                                                                                                      | `{ "full_name": "María García López", "document_type": "Passport", "document_number": "AB1234567" }` |
| `match_image_url`       | string (URL)      | Yes      | Matched user's reference face — presigned URL when `save_api_request=true`, raw storage path otherwise. Always `null` for `retained_template` matches, which hold no image.                                                                                                                                                                   | `"https://<media-host>/.../matched.jpg?..."`                                                         |
| `status`                | string            | Yes      | The matched session's verification status (see [Status enum](#status-enum-reference)); `null` for non-session matches.                                                                                                                                                                                                                        | `"Approved"`                                                                                         |
| `is_blocklisted`        | boolean           | No       | Whether the matched face is in your face blocklist. Always `false` for `retained_template` matches; a blocklisted face is reported separately as a `list_entry` match.                                                                                                                                                                        | `false`                                                                                              |
| `is_allowlisted`        | boolean           | No       | Whether the matched face is in one of your allowlists.                                                                                                                                                                                                                                                                                        | `false`                                                                                              |
| `api_service`           | string (enum)     | Yes      | Uppercase standalone API type of the matched session (e.g. `PASSIVE_LIVENESS`, `FACE_MATCH`); `null` for workflow sessions and non-session matches.                                                                                                                                                                                           | `null`                                                                                               |

```json theme={null}
{
  "request_id": "4a1c2c4e-8b1b-4d6a-91b5-ee9a1f3a2c7f",
  "face_search": {
    "status": "Approved",
    "total_matches": 1,
    "matches": [
      {
        "session_id": "a3f2a6f1-1c1c-4eec-8b69-1c1c2f3a2c7f",
        "session_number": 1024,
        "similarity_percentage": 96.42,
        "source": "session",
        "vendor_data": "user-12345",
        "verification_date": "2024-11-04T09:14:02Z",
        "user_details": {
          "full_name": "María García López",
          "document_type": "Passport",
          "document_number": "AB1234567"
        },
        "match_image_url": "https://<media-host>/.../matched.jpg?signature=...",
        "status": "Approved",
        "is_blocklisted": false,
        "is_allowlisted": false,
        "api_service": null
      }
    ],
    "user_image": {
      "entities": [
        {
          "bbox": [40, 40, 120, 120],
          "confidence": 0.732973
        }
      ],
      "best_angle": 0
    },
    "warnings": []
  },
  "vendor_data": null,
  "metadata": null,
  "created_at": "2026-06-12T01:04:42.763237+00:00"
}
```

### AML screening

Returned per screened entity. Appears as `aml_screenings[]` in `GET /v3/session/{sessionId}/decision/` for both KYC and KYB sessions. Source: `aml/serializers/aml.py:63-85` (`AMLV3Serializer`, extends `AMLV2Serializer` at `aml/serializers/aml.py:28-60`).

| Field                               | Type                | Nullable | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | Example                                                                |
| ----------------------------------- | ------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------- |
| `status`                            | string              | No       | See [Status enum](#status-enum-reference).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `"Approved"`                                                           |
| `total_hits`                        | integer             | No       | Number of screening hits (always present, defaults to `0`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `2`                                                                    |
| `entity_type`                       | string (enum)       | Yes      | `person` or `company` (`EntityTypeChoices`, `common/config/choices.py:675-677`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                        | `"person"`                                                             |
| `hits`                              | array of objects    | No       | One entry per hit. Key fields: `id`, `caption`, `match` (bool), `target` (bool \| null — whether the entity is the direct target of the listing), `match_score` (float 0-100 identity confidence), `risk_score` (float 0-100 entity risk), `score` (deprecated 0-1 float), `datasets[]` (e.g. `PEP`, `PEP Level 1`-`4`, `Sanctions`, `Adverse Media`, `Warnings and Regulatory Enforcement`, `Fitness and Probity`), `properties` (names, aliases, dates of birth, …), `features`, `url`, `first_seen`, `last_seen`, `rca_name`, `risk_view`, `score_breakdown`, `pep_matches`, `sanction_matches`, `warning_matches`, `adverse_media_matches`, `adverse_media_details`, `linked_entities`, `additional_information`, and `review_status` (`Unreviewed`, `Confirmed Match`, `False Positive`, `Inconclusive` — editable via the update-AML-hit-status endpoint, `AMLHitStatusChoices`). | `[…]`                                                                  |
| `score`                             | float (0-100)       | Yes      | Overall screening score — the highest `risk_score` among hits not marked `False Positive` (`aml/services/aml.py:832-842`); `0` when every hit is a false positive. `null` until computed.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `42.7`                                                                 |
| `screened_data`                     | object              | Yes      | Snapshot of the data sent to screening: `full_name`, `nationality`, `date_of_birth`, `document_number`.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `{ "full_name": "María García López", "date_of_birth": "1990-05-12" }` |
| `is_ongoing_monitoring_enabled`     | boolean             | No       | Whether the entity is subscribed to ongoing-monitoring re-screens.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `false`                                                                |
| `next_ongoing_monitoring_bill_date` | string (YYYY-MM-DD) | Yes      | Computed as `last_aml_bill_date + 365 days` when ongoing monitoring is enabled.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `null`                                                                 |
| `node_id`                           | string \| null      | Yes      | Workflow node identifier (V3).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `"first_aml"`                                                          |
| `warnings`                          | array               | No       | See [Warning object](#warning-object).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `[]`                                                                   |

```json theme={null}
{
  "status": "In Review",
  "total_hits": 1,
  "entity_type": "person",
  "hits": [
    {
      "id": "Q7XW3-aml-hit-1",
      "caption": "Maria Garcia Lopez",
      "match": true,
      "target": true,
      "match_score": 86.4,
      "risk_score": 42.7,
      "datasets": ["PEP Level 2"],
      "properties": {
        "name": ["María García López", "M. García"],
        "alias": ["Maria Garcia"],
        "birthDate": ["1990-05-12"]
      },
      "url": "https://example.org/registry/entities/Q7XW3",
      "first_seen": "2023-11-02T00:00:00Z",
      "last_seen": "2026-05-01T00:00:00Z",
      "review_status": "Unreviewed"
    }
  ],
  "score": 42.7,
  "screened_data": {
    "full_name": "María García López",
    "date_of_birth": "1990-05-12",
    "nationality": "ES",
    "document_number": "AB1234567"
  },
  "is_ongoing_monitoring_enabled": false,
  "next_ongoing_monitoring_bill_date": null,
  "node_id": "first_aml",
  "warnings": []
}
```

### IP analysis

Returned per captured network location. Appears as `ip_analyses[]` in `GET /v3/session/{sessionId}/decision/` for both KYC and KYB sessions. Source: `kyc/serializers/location.py:196-243` (`IPAnalysisSerializerV3`).

| Field                | Type                        | Nullable | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | Example                                                                                                                              |
| -------------------- | --------------------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ |
| `status`             | string                      | No       | See [Status enum](#status-enum-reference).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `"Approved"`                                                                                                                         |
| `node_id`            | string \| null              | Yes      | Workflow node identifier (V3).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `"first_ip_analysis"`                                                                                                                |
| `device_brand`       | string                      | Yes      | User-agent-derived device brand.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `"Apple"`                                                                                                                            |
| `device_model`       | string                      | Yes      | Device model.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `"iPhone"`                                                                                                                           |
| `browser_family`     | string                      | Yes      | Browser family.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                          | `"Mobile Safari"`                                                                                                                    |
| `os_family`          | string                      | Yes      | OS family.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `"iOS"`                                                                                                                              |
| `platform`           | string                      | Yes      | High-level platform (`mobile`, `desktop`, `tablet`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `"mobile"`                                                                                                                           |
| `device_fingerprint` | string                      | Yes      | Stable per-device fingerprint hash.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `"f2a3…"`                                                                                                                            |
| `ip_country`         | string                      | Yes      | Country name resolved from the IP.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `"Spain"`                                                                                                                            |
| `ip_country_code`    | string (ISO 3166-1 alpha-2) | Yes      | Country code resolved from the IP.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `"ES"`                                                                                                                               |
| `ip_state`           | string                      | Yes      | Region / state resolved from the IP.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `"Comunidad de Madrid"`                                                                                                              |
| `ip_city`            | string                      | Yes      | City resolved from the IP.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                               | `"Madrid"`                                                                                                                           |
| `latitude`           | float                       | Yes      | IP-derived latitude.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `40.4168`                                                                                                                            |
| `longitude`          | float                       | Yes      | IP-derived longitude.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `-3.7038`                                                                                                                            |
| `ip_address`         | string                      | Yes      | The captured IP address.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `"203.0.113.42"`                                                                                                                     |
| `isp`                | string                      | Yes      | ISP name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `"Telefonica de Espana"`                                                                                                             |
| `organization`       | string                      | Yes      | Organization name (often equal to ISP).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `"Telefonica de Espana"`                                                                                                             |
| `is_vpn_or_tor`      | boolean                     | Yes      | `true` when the IP belongs to a VPN, proxy, or Tor exit node.                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `false`                                                                                                                              |
| `is_data_center`     | boolean                     | Yes      | `true` when the IP belongs to a known hosting / data-center ASN.                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `false`                                                                                                                              |
| `time_zone`          | string                      | Yes      | IANA time-zone name.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `"Europe/Madrid"`                                                                                                                    |
| `time_zone_offset`   | string                      | Yes      | UTC offset.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                              | `"+02:00"`                                                                                                                           |
| `ip`                 | object                      | No       | `{ location, distance_from_id_document, distance_from_poa_document }`. `location = { latitude, longitude }`. Distances in km, `null` when either side is missing.                                                                                                                                                                                                                                                                                                                                                                        | `{ "location": { "latitude": 40.4168, "longitude": -3.7038 }, "distance_from_id_document": 3.4, "distance_from_poa_document": 1.1 }` |
| `id_document`        | object                      | No       | `{ location, distance_from_ip, distance_from_poa_document }`. ID document location resolved from `issuing_state` and parsed address.                                                                                                                                                                                                                                                                                                                                                                                                     | `{ "location": { "latitude": 40.4165, "longitude": -3.7026 }, "distance_from_ip": 3.4, "distance_from_poa_document": 4.0 }`          |
| `poa_document`       | object                      | No       | `{ location, distance_from_ip, distance_from_id_document }`. POA address geocoded.                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `{ "location": { "latitude": 40.4170, "longitude": -3.7040 }, "distance_from_ip": 1.1, "distance_from_id_document": 4.0 }`           |
| `matches`            | array of objects            | No       | Cross-session IP/device matches. Each item: `{ session_id, session_number, vendor_data, verification_date, match_type, match_source, matched_value, status, is_blocklisted, api_service, source, device_info, location_info, confidence, match_mode }`. `match_type` is `ip_address` or `device_fingerprint`; `match_source` is `ip_address`, `persistent_id`, `legacy_fp`, or `recovered_high` (recovered matches also carry `recovery_similarity`, `tls_ja4_corroborated`, `recovery_gate_reason`). Capped at 5 IP + 5 device matches. | `[]`                                                                                                                                 |
| `warnings`           | array                       | No       | See [Warning object](#warning-object).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                   | `[]`                                                                                                                                 |

```json theme={null}
{
  "status": "Approved",
  "node_id": "first_ip_analysis",
  "device_brand": "Apple",
  "device_model": "iPhone",
  "browser_family": "Mobile Safari",
  "os_family": "iOS",
  "platform": "mobile",
  "device_fingerprint": "f2a3c1de8b994a3f9e4cdf3a02b1a7c9",
  "ip_country": "Spain",
  "ip_country_code": "ES",
  "ip_state": "Comunidad de Madrid",
  "ip_city": "Madrid",
  "latitude": 40.4168,
  "longitude": -3.7038,
  "ip_address": "203.0.113.42",
  "isp": "Telefonica de Espana",
  "organization": "Telefonica de Espana",
  "is_vpn_or_tor": false,
  "is_data_center": false,
  "time_zone": "Europe/Madrid",
  "time_zone_offset": "+02:00",
  "ip": {
    "location": { "latitude": 40.4168, "longitude": -3.7038 },
    "distance_from_id_document": 3.4,
    "distance_from_poa_document": 1.1
  },
  "id_document": {
    "location": { "latitude": 40.4165, "longitude": -3.7026 },
    "distance_from_ip": 3.4,
    "distance_from_poa_document": 4.0
  },
  "poa_document": {
    "location": { "latitude": 40.4170, "longitude": -3.7040 },
    "distance_from_ip": 1.1,
    "distance_from_id_document": 4.0
  },
  "matches": [],
  "warnings": []
}
```

### Proof of address

Returned per submitted address document. Appears as `poa_verifications[]` in `GET /v3/session/{sessionId}/decision/`. Source: `poa/serializers/poa.py:212-227` (`POAV3Serializer`, extends `POAV2Serializer` at `poa/serializers/poa.py:173-209`).

| Field                                | Type                        | Nullable | Description                                                                                                                                                                                                                                                                                                                                                          | Example                                                                                          |
| ------------------------------------ | --------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------ |
| `status`                             | string                      | No       | See [Status enum](#status-enum-reference).                                                                                                                                                                                                                                                                                                                           | `"Approved"`                                                                                     |
| `issuing_state`                      | string (ISO 3166-1 alpha-3) | Yes      | Country code of the document issuer.                                                                                                                                                                                                                                                                                                                                 | `"ESP"`                                                                                          |
| `document_type`                      | string                      | No       | High-level type from `PoaDocumentTypeChoices` (`common/config/choices.py:868-873`): `UTILITY_BILL`, `BANK_STATEMENT`, `GOVERNMENT_ISSUED_DOCUMENT`, `OTHER_POA_DOCUMENT`. Falls back to `UNKNOWN` — never `null`.                                                                                                                                                    | `"UTILITY_BILL"`                                                                                 |
| `document_subtype`                   | string                      | No       | Subtype code from `PoaDocumentSubtypeChoices` (e.g. `ELECTRICITY_BILL`, `WATER_BILL`, `ACCOUNT_STATEMENT`). Falls back to `UNKNOWN` — never `null`.                                                                                                                                                                                                                  | `"ELECTRICITY_BILL"`                                                                             |
| `issuer`                             | string                      | Yes      | Name of the issuing entity.                                                                                                                                                                                                                                                                                                                                          | `"Iberdrola"`                                                                                    |
| `issue_date`                         | string (YYYY-MM-DD)         | Yes      | Document issue date.                                                                                                                                                                                                                                                                                                                                                 | `"2026-04-15"`                                                                                   |
| `expiration_date`                    | string (YYYY-MM-DD)         | Yes      | Expiration date printed on the document, when present.                                                                                                                                                                                                                                                                                                               | `null`                                                                                           |
| `poa_address`                        | string                      | Yes      | Raw OCR-extracted address.                                                                                                                                                                                                                                                                                                                                           | `"Calle Mayor 1, 28001 Madrid"`                                                                  |
| `poa_formatted_address`              | string                      | Yes      | Geocoded/formatted address.                                                                                                                                                                                                                                                                                                                                          | `"Calle Mayor 1, 28001 Madrid, Spain"`                                                           |
| `poa_parsed_address`                 | object                      | Yes      | Structured address (`street_1`, `street_2`, `city`, `region`, `postal_code`, `country` (alpha-2), `address_type`, `document_location`, …).                                                                                                                                                                                                                           | `{ "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001" }`                      |
| `document_file`                      | string (URL)                | Yes      | Presigned URL to the uploaded document.                                                                                                                                                                                                                                                                                                                              | `"https://<media-host>/.../poa.pdf?..."`                                                         |
| `document_language`                  | string                      | Yes      | Detected document language (ISO 639-1).                                                                                                                                                                                                                                                                                                                              | `"es"`                                                                                           |
| `document_metadata`                  | object                      | Yes      | Filtered metadata: `file_size`, `content_type`, `creation_date`, `modified_date`, `creator`, `producer`, `software`, `encryption`, `is_signed`, `is_tampered`, `signature_info`, `exif_original_date`, `exif_digitized_date`, `processed_by_known_editor`, `has_different_creation_mod_date`, `overlay_manipulation`.                                                | `{ "file_size": 184221, "content_type": "application/pdf", "is_tampered": false }`               |
| `extra_fields`                       | object                      | No       | Bank-account fields (`bank_account_number`, `bank_iban`, `bank_sort_code`, `bank_routing_number`, `bank_swift_bic`, `bank_branch_name`, `bank_branch_address`), `document_phone_number`, `additional_names`, plus any custom keys persisted on the record.                                                                                                           | `{ "bank_iban": null, "additional_names": [] }`                                                  |
| `name_on_document`                   | string                      | Yes      | Name as it appears on the POA.                                                                                                                                                                                                                                                                                                                                       | `"María García López"`                                                                           |
| `expected_details_address`           | string                      | Yes      | Address the customer typed during signup (verbatim).                                                                                                                                                                                                                                                                                                                 | `"Calle Mayor 1, Madrid"`                                                                        |
| `expected_details_formatted_address` | string                      | Yes      | Geocoded expected address.                                                                                                                                                                                                                                                                                                                                           | `"Calle Mayor 1, 28001 Madrid, Spain"`                                                           |
| `expected_details_parsed_address`    | object                      | Yes      | Structured expected address.                                                                                                                                                                                                                                                                                                                                         | `{ "city": "Madrid", "postal_code": "28001" }`                                                   |
| `name_match_score_expected_details`  | float (0-100)               | Yes      | Fuzzy match between `name_on_document` and the name supplied at session creation.                                                                                                                                                                                                                                                                                    | `94.0`                                                                                           |
| `name_match_score_id_verification`   | float (0-100)               | Yes      | Fuzzy match between `name_on_document` and the verified ID's `full_name`.                                                                                                                                                                                                                                                                                            | `100.0`                                                                                          |
| `extra_files`                        | array of strings (URL)      | No       | Presigned URLs to additional uploaded files.                                                                                                                                                                                                                                                                                                                         | `[]`                                                                                             |
| `detected_codes`                     | array of objects            | No       | QR codes and barcodes detected across every processed page of the document: `type`, `page_number` (1-based), `position` (polygon), `x`/`y`/`width`/`height` (bounding box), `page_width`/`page_height`, `raw_payload` (base64), `parsed_payload` (decoded value, `null` when a code was located but could not be decoded). Empty array when detection finds nothing. | `[{ "type": "QR_CODE", "page_number": 1, "parsed_payload": "https://issuer.example/inv/9981" }]` |
| `node_id`                            | string \| null              | Yes      | Workflow node identifier (V3).                                                                                                                                                                                                                                                                                                                                       | `"first_poa"`                                                                                    |
| `warnings`                           | array                       | No       | See [Warning object](#warning-object).                                                                                                                                                                                                                                                                                                                               | `[]`                                                                                             |

```json theme={null}
{
  "status": "Approved",
  "issuing_state": "ESP",
  "document_type": "UTILITY_BILL",
  "document_subtype": "ELECTRICITY_BILL",
  "issuer": "Iberdrola",
  "issue_date": "2026-04-15",
  "expiration_date": null,
  "poa_address": "Calle Mayor 1, 28001 Madrid",
  "poa_formatted_address": "Calle Mayor 1, 28001 Madrid, Spain",
  "poa_parsed_address": { "street_1": "Calle Mayor 1", "city": "Madrid", "postal_code": "28001", "country": "ES" },
  "document_file": "https://<media-host>/.../poa.pdf?signature=...",
  "document_language": "es",
  "document_metadata": {
    "file_size": 184221,
    "content_type": "application/pdf",
    "creation_date": "2026-04-15T08:11:32Z",
    "modified_date": "2026-04-15T08:11:32Z",
    "creator": "Iberdrola Billing",
    "producer": "Adobe PDF Library 15.0",
    "software": null,
    "encryption": null,
    "is_signed": true,
    "is_tampered": false,
    "signature_info": { "signer_name": "Iberdrola Clientes", "date": "2026-04-15T08:11:32Z" },
    "exif_original_date": null,
    "exif_digitized_date": null,
    "processed_by_known_editor": false,
    "has_different_creation_mod_date": false,
    "overlay_manipulation": null
  },
  "extra_fields": {
    "bank_account_number": null,
    "bank_iban": null,
    "bank_sort_code": null,
    "bank_routing_number": null,
    "bank_swift_bic": null,
    "bank_branch_name": null,
    "bank_branch_address": null,
    "document_phone_number": null,
    "additional_names": []
  },
  "name_on_document": "María García López",
  "expected_details_address": "Calle Mayor 1, Madrid",
  "expected_details_formatted_address": "Calle Mayor 1, 28001 Madrid, Spain",
  "expected_details_parsed_address": { "city": "Madrid", "postal_code": "28001", "country": "ES" },
  "name_match_score_expected_details": 94.0,
  "name_match_score_id_verification": 100.0,
  "extra_files": [],
  "detected_codes": [
    {
      "type": "QR_CODE",
      "page_number": 1,
      "position": [[820, 1120], [1002, 1120], [1002, 1302], [820, 1302]],
      "x": 820,
      "y": 1120,
      "width": 182,
      "height": 182,
      "page_width": 1190,
      "page_height": 1684,
      "raw_payload": "aHR0cHM6Ly9pYmVyZHJvbGEuZXMvZmFjdHVyYS85OTgx",
      "parsed_payload": "https://iberdrola.es/factura/9981"
    },
    {
      "type": "CODE_128",
      "page_number": 1,
      "position": [[112, 1480], [560, 1480], [560, 1540], [112, 1540]],
      "x": 112,
      "y": 1480,
      "width": 448,
      "height": 60,
      "page_width": 1190,
      "page_height": 1684,
      "raw_payload": "MDA5OTgxMDAwNDI=",
      "parsed_payload": "0099810042"
    }
  ],
  "node_id": "first_poa",
  "warnings": []
}
```

### Phone verification

Returned per phone-verification attempt. Appears as `phone_verifications[]` in `GET /v3/session/{sessionId}/decision/` for both KYC and KYB sessions. Source: `phone/serializers/phone.py:251-266` (`PhoneV3Serializer`, extends `PhoneV2Serializer` at `phone/serializers/phone.py:103-248`).

| Field                   | Type                        | Nullable | Description                                                                                                                                                                                                                                                    | Example                                    |
| ----------------------- | --------------------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------ |
| `status`                | string                      | No       | See [Status enum](#status-enum-reference).                                                                                                                                                                                                                     | `"Approved"`                               |
| `phone_number_prefix`   | string                      | No       | E.164 country prefix (with `+`).                                                                                                                                                                                                                               | `"+34"`                                    |
| `phone_number`          | string                      | No       | Subscriber number without the prefix.                                                                                                                                                                                                                          | `"612345678"`                              |
| `full_number`           | string                      | No       | The full E.164 number (`phone_number_prefix + phone_number`).                                                                                                                                                                                                  | `"+34612345678"`                           |
| `country_code`          | string (ISO 3166-1 alpha-2) | Yes      | Country of the number.                                                                                                                                                                                                                                         | `"ES"`                                     |
| `country_name`          | string                      | Yes      | Localized country name.                                                                                                                                                                                                                                        | `"Spain"`                                  |
| `carrier`               | object                      | No       | `{ name, type }` where `type` is a `LineTypeChoices` value (`common/config/choices.py:648-667`): `mobile`, `fixed_line`, `voip`, `isp`, `vpn`, `toll_free`, `premium_rate`, `satellite`, `pager`, `payphone`, `voice_mail`, `unknown`, and other line classes. | `{ "name": "Movistar", "type": "mobile" }` |
| `is_disposable`         | boolean                     | No       | `true` when the carrier marks the number as temporary/disposable.                                                                                                                                                                                              | `false`                                    |
| `is_virtual`            | boolean                     | No       | `true` when `carrier.type` is one of `voip`, `isp`, `vpn`.                                                                                                                                                                                                     | `false`                                    |
| `verification_method`   | string                      | No       | Channel used to deliver the OTP (`whatsapp`, `sms`, …). Reads from the last send attempt's `actual_channel` (falls back to the requested `channel`, then `sms`).                                                                                               | `"whatsapp"`                               |
| `verification_attempts` | integer                     | No       | Total OTP send attempts (initial send plus resends).                                                                                                                                                                                                           | `1`                                        |
| `verified_at`           | string (ISO 8601)           | Yes      | Timestamp the OTP was successfully entered.                                                                                                                                                                                                                    | `"2026-05-17T10:14:02Z"`                   |
| `lifecycle`             | array of objects            | No       | Chronological events: send attempts, delivery callbacks, code checks, and the final status event. Each event is `{ type, timestamp, details, fee }`. Event types come from `PhoneEventChoices`.                                                                | `[…]`                                      |
| `matches`               | array of objects            | No       | Cross-session phone-number matches. Each item: `{ session_id, session_number, vendor_data, verification_date, phone_number, status, is_blocklisted, api_service, source }`. `source` is `session` or `list_entry`.                                             | `[]`                                       |
| `node_id`               | string \| null              | Yes      | Workflow node identifier (V3).                                                                                                                                                                                                                                 | `"first_phone"`                            |
| `warnings`              | array                       | No       | See [Warning object](#warning-object).                                                                                                                                                                                                                         | `[]`                                       |

```json theme={null}
{
  "status": "Approved",
  "phone_number_prefix": "+34",
  "phone_number": "612345678",
  "full_number": "+34612345678",
  "country_code": "ES",
  "country_name": "Spain",
  "carrier": { "name": "Movistar", "type": "mobile" },
  "is_disposable": false,
  "is_virtual": false,
  "verification_method": "whatsapp",
  "verification_attempts": 1,
  "verified_at": "2026-05-17T10:14:02Z",
  "lifecycle": [
    {
      "type": "PHONE_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2026-05-17T10:13:51Z",
      "details": { "status": "Success", "reason": null, "channel": "whatsapp", "actual_channel": "whatsapp" },
      "fee": 0.04
    },
    {
      "type": "PHONE_DELIVERY_DELIVERED",
      "timestamp": "2026-05-17T10:13:52Z",
      "details": { "channel": "whatsapp", "status": "delivered" },
      "fee": 0
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2026-05-17T10:14:02Z",
      "details": { "code_tried": "482917", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "PHONE_VERIFICATION_APPROVED",
      "timestamp": "2026-05-17T10:14:02Z",
      "details": null,
      "fee": 0
    }
  ],
  "matches": [],
  "node_id": "first_phone",
  "warnings": []
}
```

### Email verification

Returned per email-verification attempt. Appears as `email_verifications[]` in `GET /v3/session/{sessionId}/decision/` for both KYC and KYB sessions. Source: `email_verification/serializers/email.py:149-164` (`EmailV3Serializer`, extends `EmailV2Serializer` at `email_verification/serializers/email.py:38-146`).

| Field                   | Type              | Nullable | Description                                                                                                                                                                                          | Example                      |
| ----------------------- | ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------- |
| `status`                | string            | No       | See [Status enum](#status-enum-reference).                                                                                                                                                           | `"Approved"`                 |
| `email`                 | string            | No       | The submitted email address.                                                                                                                                                                         | `"maria.garcia@example.com"` |
| `is_breached`           | boolean           | No       | `true` when the email appears in a known data breach.                                                                                                                                                | `false`                      |
| `breaches`              | array of objects  | No       | Per-breach detail when `is_breached` is `true`: `{ name, domain, logo_path, breach_date, description, is_verified, data_classes, breach_emails_count }`.                                             | `[]`                         |
| `is_disposable`         | boolean           | No       | `true` when the email belongs to a disposable-mail provider.                                                                                                                                         | `false`                      |
| `is_undeliverable`      | boolean           | No       | `true` when SMTP delivery probing shows the inbox doesn't accept mail.                                                                                                                               | `false`                      |
| `verification_attempts` | integer           | No       | Total OTP check attempts.                                                                                                                                                                            | `1`                          |
| `verified_at`           | string (ISO 8601) | Yes      | Timestamp the OTP was successfully entered.                                                                                                                                                          | `"2026-05-17T10:15:22Z"`     |
| `lifecycle`             | array of objects  | No       | Chronological events: send attempts, code checks, and the final status event. Each event is `{ type, timestamp, details, fee }`. Event types come from `EmailEventChoices`.                          | `[…]`                        |
| `matches`               | array of objects  | No       | Cross-session email matches. Each item: `{ session_id, session_number, vendor_data, verification_date, email, status, is_blocklisted, api_service, source }`. `source` is `session` or `list_entry`. | `[]`                         |
| `node_id`               | string \| null    | Yes      | Workflow node identifier (V3).                                                                                                                                                                       | `"first_email"`              |
| `warnings`              | array             | No       | See [Warning object](#warning-object).                                                                                                                                                               | `[]`                         |

```json theme={null}
{
  "status": "Approved",
  "email": "maria.garcia@example.com",
  "is_breached": false,
  "breaches": [],
  "is_disposable": false,
  "is_undeliverable": false,
  "verification_attempts": 1,
  "verified_at": "2026-05-17T10:15:22Z",
  "lifecycle": [
    {
      "type": "EMAIL_VERIFICATION_MESSAGE_SENT",
      "timestamp": "2026-05-17T10:15:11Z",
      "details": { "status": "Success", "reason": null },
      "fee": 0.03
    },
    {
      "type": "VALID_CODE_ENTERED",
      "timestamp": "2026-05-17T10:15:22Z",
      "details": { "code_tried": "739204", "status": "Approved" },
      "fee": 0
    },
    {
      "type": "EMAIL_VERIFICATION_APPROVED",
      "timestamp": "2026-05-17T10:15:22Z",
      "details": null,
      "fee": 0
    }
  ],
  "matches": [],
  "node_id": "first_email",
  "warnings": []
}
```

### Database validation

Returned per database lookup run against the user's submitted data. Appears as `database_validations[]` in `GET /v3/session/{sessionId}/decision/`. Source: `database_validation/serializers/database_validation.py:21-142` (`DatabaseValidationV3Serializer`, extends `DatabaseValidationV2Serializer`).

| Field             | Type                        | Nullable | Description                                                                                                                                                                                                                                                                                                                                                                                     | Example                                                             |
| ----------------- | --------------------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------- |
| `issuing_state`   | string (ISO 3166-1 alpha-3) | Yes      | Country whose registry was queried.                                                                                                                                                                                                                                                                                                                                                             | `"ESP"`                                                             |
| `validation_type` | string (enum)               | No       | How the result was corroborated: `one_by_one` (single-service outcome), `two_by_two` (two or more distinct services independently full-matched the identification number), or `not_enabled` (the validator was skipped or no provider responded — a definitive `no_match` still yields `one_by_one`). Never `null`. Source: `DatabaseValidationChoices` (`common/config/choices.py:1097-1100`). | `"one_by_one"`                                                      |
| `screened_data`   | object                      | No       | The data submitted to the registry. File fields (`selfie`, `cnh_qr_code_image`, `document_image`) are presigned at read time.                                                                                                                                                                                                                                                                   | `{ "document_number": "99999999R", "date_of_birth": "1990-05-12" }` |
| `validations`     | array of objects            | No       | One entry per catalog service that produced a match. Each entry can include `service_id`, `service_name`, `validation` (provider verdict object), `outcome_code`, `outcome_detail`, and `source_data` (cleaned citizen profile: `full_name`, `gender`, `date_of_birth`, `photo` (presigned URL), `signature` (presigned URL), …).                                                               | `[…]`                                                               |
| `errors`          | array of objects            | Yes      | Per-service errors when a lookup failed; the key is omitted entirely when empty. Each entry is the upstream service's error object plus the `service_id` that produced it.                                                                                                                                                                                                                      | `[]`                                                                |
| `match_type`      | string (enum)               | Yes      | Aggregate match verdict across queried services: `full_match`, `partial_match`, or `no_match` (`DatabaseValidationMatchTypeChoices`, `common/config/choices.py:1103-1106`). `null` until evaluated.                                                                                                                                                                                             | `"full_match"`                                                      |
| `status`          | string                      | No       | See [Status enum](#status-enum-reference).                                                                                                                                                                                                                                                                                                                                                      | `"Approved"`                                                        |
| `node_id`         | string \| null              | Yes      | Workflow node identifier (V3).                                                                                                                                                                                                                                                                                                                                                                  | `"first_db_validation"`                                             |
| `warnings`        | array                       | No       | See [Warning object](#warning-object).                                                                                                                                                                                                                                                                                                                                                          | `[]`                                                                |

```json theme={null}
{
  "issuing_state": "ESP",
  "validation_type": "one_by_one",
  "screened_data": {
    "document_number": "99999999R",
    "date_of_birth": "1990-05-12",
    "first_name": "María",
    "last_name": "García López"
  },
  "validations": [
    {
      "service_id": "esp_dni",
      "service_name": "Spain - DNI/NIE verification",
      "validation": { "is_valid": true, "match_score": 100 },
      "outcome_code": "MATCH",
      "outcome_detail": "All identifiers match the registry record.",
      "source_data": {
        "full_name": "María García López",
        "gender": "F",
        "date_of_birth": "1990-05-12",
        "photo": "https://<media-host>/.../registry_photo.jpg?signature=...",
        "signature": null
      }
    }
  ],
  "match_type": "full_match",
  "status": "Approved",
  "node_id": "first_db_validation",
  "warnings": []
}
```

### Questionnaire response

Returned per questionnaire submission. Appears as `questionnaire_responses[]` in `GET /v3/session/{sessionId}/decision/` for both KYC and KYB sessions. Source: `questionnaires/serializers/questionnaire.py:591-597` (`QuestionnaireResponseV3Serializer`, extends `QuestionnaireResponseSerializer` at `questionnaires/serializers/questionnaire.py:520-588`).

| Field                     | Type              | Nullable | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | Example                           |
| ------------------------- | ----------------- | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------- |
| `questionnaire_id`        | string (UUID)     | No       | Identifier of the questionnaire version that was answered.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `"6a0f1c2c-…"`                    |
| `title`                   | string            | No       | Questionnaire name, as set in the Console.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `"Customer risk profile"`         |
| `description`             | string            | Yes      | Questionnaire description.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `"Short risk-profile questions."` |
| `languages`               | array of strings  | No       | Language codes the questionnaire is published in.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                      | `["en", "es"]`                    |
| `default_language`        | string            | No       | Fallback language code.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | `"en"`                            |
| `is_active`               | boolean           | No       | Whether this questionnaire version is the active one.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  | `true`                            |
| `is_simple_questionnaire` | boolean           | No       | `true` when the questionnaire has no branching (flat list).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `true`                            |
| `questionnaire_group_id`  | string (UUID)     | No       | Identifier shared across versions of the same questionnaire.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | `"a7c2c2c2-…"`                    |
| `version`                 | integer           | No       | Version number of the active template.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `3`                               |
| `status`                  | string            | No       | One of `Approved`, `In Review`, `Not Finished` (a questionnaire-level decline maps to `In Review`).                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | `"Approved"`                      |
| `published_at`            | string (ISO 8601) | Yes      | When the template was published.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                       | `"2026-01-12T11:00:00Z"`          |
| `sections`                | array of objects  | No       | Ordered sections after applying graph traversal and visibility filtering. Each section is `{ title, description, items[] }` (title/description come from the opening `SECTION_HEADER`, pre-translated). Each item is a form element (`uuid`, `value` (node id), `element_type`, `is_required`, `title`, `description`, `placeholder`, `choices`, `max_files`, `required_if`, `repeatable_config`, plus an `answer` field — `null` when unanswered, omitted on `HEADING`/`PARAGRAPH`/`SEPARATOR` layout items). File answers contain `{ files: [<presigned URL>, …] }`. | `[…]`                             |
| `node_id`                 | string \| null    | Yes      | Workflow node identifier (V3).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                         | `"first_questionnaire"`           |

```json theme={null}
{
  "questionnaire_id": "6a0f1c2c-3b7d-4d2c-9eb6-fdc6c7c92ef9",
  "title": "Customer risk profile",
  "description": "Short risk-profile questions.",
  "languages": ["en", "es"],
  "default_language": "en",
  "is_active": true,
  "is_simple_questionnaire": true,
  "questionnaire_group_id": "a7c2c2c2-1111-4d2c-9eb6-fdc6c7c92ef9",
  "version": 3,
  "status": "Approved",
  "published_at": "2026-01-12T11:00:00Z",
  "sections": [
    {
      "title": "Source of funds",
      "description": null,
      "items": [
        {
          "uuid": "4f1d5e2c-aaaa-4d2c-9eb6-fdc6c7c92ef9",
          "value": "q_source_of_funds",
          "element_type": "SINGLE_CHOICE",
          "is_required": true,
          "title": "What is your main source of funds?",
          "description": null,
          "placeholder": null,
          "choices": [
            { "label": "Salary", "value": "salary" },
            { "label": "Business income", "value": "business" },
            { "label": "Investments", "value": "investments" }
          ],
          "max_files": 1,
          "required_if": null,
          "repeatable_config": null,
          "answer": { "value": "salary" }
        }
      ]
    }
  ],
  "node_id": "first_questionnaire"
}
```

### Age estimation

Returned by the standalone Age Estimation API (`POST /v3/age-estimation/`). The response carries a subset of [`Liveness check`](#liveness-check)'s shape under an `age_estimation` envelope — `status`, `method`, `score`, `age_estimation`, `warnings` — plus a standalone-only `user_image` face-detection block; it does **not** include `reference_image`, `video_url`, `matches`, `face_quality`, or `face_luminance`. In workflow sessions there is no separate array — the estimated age surfaces as `liveness_checks[].age_estimation` in `GET /v3/session/{sessionId}/decision/`. Source: `apis/serializers/age_estimation.py:50-55` (`AgeEstimationResponseSerializer`), envelope assembled in `apis/views/age_estimation.py:138-174`.

| Field            | Type              | Nullable | Description                                                                                                                                                                                                                                                                                                                                     | Example                              |
| ---------------- | ----------------- | -------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `request_id`     | string (UUID)     | No       | Persisted session id when `save_api_request=true` (the default); otherwise a transient correlation UUID.                                                                                                                                                                                                                                        | `"3b1f1e2c-…"`                       |
| `age_estimation` | object            | No       | Result envelope: `status` (`Approved` / `Declined`), `method` (always `PASSIVE`), `score` (liveness 0-100, nullable), `age_estimation` (predicted age in years of the largest face, nullable), `user_image` (`entities[]` with per-face `age`, `bbox` `[x_min, y_min, x_max, y_max]`, `confidence`, `gender`; plus `best_angle`), `warnings[]`. | `{ … }`                              |
| `vendor_data`    | string            | Yes      | Echoed `vendor_data` from the request.                                                                                                                                                                                                                                                                                                          | `null`                               |
| `metadata`       | object            | Yes      | Echoed `metadata` from the request.                                                                                                                                                                                                                                                                                                             | `null`                               |
| `created_at`     | string (ISO 8601) | No       | Server-side request timestamp.                                                                                                                                                                                                                                                                                                                  | `"2026-05-17T10:22:13.512941+00:00"` |

```json theme={null}
{
  "request_id": "3b1f1e2c-7777-4d2c-9eb6-fdc6c7c92ef9",
  "age_estimation": {
    "status": "Approved",
    "method": "PASSIVE",
    "score": 94.10,
    "age_estimation": 28.7,
    "user_image": {
      "entities": [
        { "age": 28.7, "bbox": [40, 40, 100, 100], "confidence": 0.72, "gender": "male" }
      ],
      "best_angle": 0
    },
    "warnings": []
  },
  "vendor_data": null,
  "metadata": null,
  "created_at": "2026-05-17T10:22:13.512941+00:00"
}
```

### Biometric authentication

Biometric authentication runs the same Liveness + Face Match pipeline used in standard KYC, but configured to compare the captured face against an existing user's reference image instead of a freshly-OCR'd document portrait. There is no dedicated serializer — `GET /v3/session/{sessionId}/decision/` returns the standard [Liveness check](#liveness-check) and [Face match](#face-match) objects under `liveness_checks[]` and `face_matches[]`. The session's workflow is configured with `workflow_type = "biometric_authentication"` (`WorkflowTypeChoices`, `common/config/choices.py:636`).

| Field             | Type                                       | Nullable | Description                                                                                                                                                                                                                                                                                                                            | Example                                                           |
| ----------------- | ------------------------------------------ | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------- |
| `liveness_checks` | array of [Liveness check](#liveness-check) | No       | Liveness result for the authentication attempt.                                                                                                                                                                                                                                                                                        | `[ { "status": "Approved", … } ]`                                 |
| `face_matches`    | array of [Face match](#face-match)         | No       | Match result against the enrolled reference. `source_image_session_id` is set to the session's own `session_id` — the reference face (the supplied `portrait_image`, or the stored face reused via `vendor_data` when `portrait_image` is omitted) is recorded under the authentication session itself (`face/views/face.py:656-659`). | `[ { "status": "Approved", "source_image_session_id": "…", … } ]` |
| `status`          | string                                     | No       | Top-level session status (see [Status enum](#status-enum-reference)).                                                                                                                                                                                                                                                                  | `"Approved"`                                                      |

```json theme={null}
{
  "session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9",
  "status": "Approved",
  "liveness_checks": [
    {
      "status": "Approved",
      "method": "PASSIVE",
      "score": 95.10,
      "reference_image": "https://<media-host>/.../reference.jpg?signature=...",
      "video_url": null,
      "age_estimation": null,
      "matches": [],
      "face_quality": 91.20,
      "face_luminance": 53.10,
      "node_id": "biometric_auth_liveness",
      "warnings": []
    }
  ],
  "face_matches": [
    {
      "status": "Approved",
      "score": 98.42,
      "source_image_session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9",
      "source_image": "https://<media-host>/.../source.jpg?signature=...",
      "target_image": "https://<media-host>/.../target.jpg?signature=...",
      "node_id": "biometric_auth_face_match",
      "warnings": []
    }
  ]
}
```

### KYB registry

Returned per registry-confirmed company in a KYB workflow. Appears as `registry_checks[]` in `GET /v3/session/{sessionId}/decision/` for business sessions. Source: `kyb/serializers/kyb.py:939-964` (`RegistryCheckV3Serializer`).

| Field                 | Type           | Nullable | Description                                                                                                             | Example                              |
| --------------------- | -------------- | -------- | ----------------------------------------------------------------------------------------------------------------------- | ------------------------------------ |
| `status`              | string         | No       | See [Status enum](#status-enum-reference).                                                                              | `"Approved"`                         |
| `node_id`             | string \| null | Yes      | Workflow node identifier (V3).                                                                                          | `"first_registry"`                   |
| `data_resolved`       | boolean        | No       | `true` when the registry fetch has completed (or `is_from_registry` is `false`, meaning the data was entered manually). | `true`                               |
| `company`             | object         | No       | Full company payload — see [Company object](#company-object) below.                                                     | `{ … }`                              |
| `ownership_structure` | object         | Yes      | Provider-supplied ownership graph (`nodes`, `edges`, percentages). Free-form JSON.                                      | `{ "nodes": [...], "edges": [...] }` |
| `warnings`            | array          | No       | See [Warning object](#warning-object).                                                                                  | `[]`                                 |

#### Company object

From `kyb/serializers/kyb.py:220-321` (`KYBCompanyResponseSerializer`).

| Field                         | Type                        | Nullable | Description                                                                                                                                                                                                                                                                          |
| ----------------------------- | --------------------------- | -------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `uuid`                        | string (UUID)               | No       | Internal company identifier.                                                                                                                                                                                                                                                         |
| `node_id`                     | string \| null              | Yes      | Workflow node identifier.                                                                                                                                                                                                                                                            |
| `status`                      | string                      | No       | Feature status (`FeatureStatusChoices`).                                                                                                                                                                                                                                             |
| `registry_status`             | string                      | Yes      | Company status from the registry (`active`, `dissolved`, …).                                                                                                                                                                                                                         |
| `data_resolved`               | boolean                     | No       | Same definition as on the parent object.                                                                                                                                                                                                                                             |
| `company_name`                | string                      | Yes      | Registered company name.                                                                                                                                                                                                                                                             |
| `registration_number`         | string                      | Yes      | Registry identifier.                                                                                                                                                                                                                                                                 |
| `country_code`                | string (ISO 3166-1 alpha-2) | Yes      | Country of incorporation.                                                                                                                                                                                                                                                            |
| `region`                      | string                      | Yes      | ISO 3166-2 subdivision when applicable (e.g. `US-CA`).                                                                                                                                                                                                                               |
| `company_type`                | string                      | Yes      | Legal form (`LLC`, `SL`, …).                                                                                                                                                                                                                                                         |
| `incorporation_date`          | string (YYYY-MM-DD)         | Yes      | Date of incorporation.                                                                                                                                                                                                                                                               |
| `registered_address`          | string                      | Yes      | Registered legal address.                                                                                                                                                                                                                                                            |
| `tax_number`                  | string                      | Yes      | Tax / VAT identifier.                                                                                                                                                                                                                                                                |
| `risk_level`                  | string                      | Yes      | Provider-supplied risk rating.                                                                                                                                                                                                                                                       |
| `verification_status`         | string                      | Yes      | Internal verification status enum.                                                                                                                                                                                                                                                   |
| `is_from_registry`            | boolean                     | No       | `true` when sourced from the registry (vs. manual entry).                                                                                                                                                                                                                            |
| `fetch_status`                | string                      | Yes      | `pending`, `resolved`, `failed`.                                                                                                                                                                                                                                                     |
| `alternative_names`           | string                      | Yes      | Comma-separated alternative trade names.                                                                                                                                                                                                                                             |
| `nature_of_business`          | string                      | Yes      | Free-text business activity description.                                                                                                                                                                                                                                             |
| `registered_capital`          | string                      | Yes      | Registered capital as a human-readable string.                                                                                                                                                                                                                                       |
| `registered_capital_amount`   | string (decimal)            | Yes      | Parsed registered capital amount.                                                                                                                                                                                                                                                    |
| `registered_capital_currency` | string (ISO 4217)           | Yes      | Currency code.                                                                                                                                                                                                                                                                       |
| `website`                     | string (URL)                | Yes      | Company website.                                                                                                                                                                                                                                                                     |
| `email`                       | string                      | Yes      | Public contact email.                                                                                                                                                                                                                                                                |
| `phone`                       | string                      | Yes      | Public contact phone.                                                                                                                                                                                                                                                                |
| `legal_entity_identifier`     | string                      | Yes      | LEI when available.                                                                                                                                                                                                                                                                  |
| `location_of_registration`    | string                      | Yes      | Registry office / region.                                                                                                                                                                                                                                                            |
| `vat_number`                  | string                      | Yes      | VAT number submitted for the company.                                                                                                                                                                                                                                                |
| `vat_validation_status`       | string                      | No       | Result of the EU VIES check: `valid`, `invalid`, `could_not_validate`, or `not_applicable`. Only EU-27 + Northern Ireland (`XI`) VAT numbers are validated; everything else returns `not_applicable`. See [VAT validation](/business-verification/company-data#vat-validation-vies). |
| `vat_validated_name`          | string                      | Yes      | Company name registered in VIES (empty when the member state does not disclose it).                                                                                                                                                                                                  |
| `vat_validated_address`       | string                      | Yes      | Address registered in VIES (empty when not disclosed).                                                                                                                                                                                                                               |
| `vat_checked_at`              | string (ISO 8601)           | Yes      | Timestamp of the VIES check; `null` when no check ran.                                                                                                                                                                                                                               |
| `financial_summary`           | object                      | Yes      | Snapshot of latest financial highlights when supplied by the registry.                                                                                                                                                                                                               |
| `officers`                    | array of objects            | No       | B2C-safe officer list: `{ uuid, name, designation, role, nationality, is_active, kyc_status, kyc_session_url }`.                                                                                                                                                                     |
| `beneficial_owners`           | array of objects            | No       | B2C-safe UBO list: `{ uuid, name, first_name, last_name, entity_type, roles, ownership_min_shares, ownership_max_shares, is_active, kyc_status, kyc_session_url, effective_ownership_percent }`.                                                                                     |
| `addresses`                   | array of objects            | Yes      | Per-address detail from the registry.                                                                                                                                                                                                                                                |
| `industries`                  | array of objects            | Yes      | SIC/NAICS-style classifications.                                                                                                                                                                                                                                                     |
| `accounts`                    | array of objects            | Yes      | Filed accounts metadata.                                                                                                                                                                                                                                                             |
| `registry_data`               | object                      | Yes      | Raw registry payload (vendor-specific).                                                                                                                                                                                                                                              |
| `user_provided_data`          | object                      | Yes      | Snapshot of user-edited fields.                                                                                                                                                                                                                                                      |
| `confirmed_by_user_at`        | string (ISO 8601)           | Yes      | Timestamp the user confirmed the extracted data.                                                                                                                                                                                                                                     |
| `last_console_edit_at`        | string (ISO 8601)           | Yes      | Timestamp of the last console edit.                                                                                                                                                                                                                                                  |
| `is_editable`                 | boolean                     | No       | `true` while registry-sourced data can still be edited by the end user.                                                                                                                                                                                                              |

```json theme={null}
{
  "status": "Approved",
  "node_id": "first_registry",
  "data_resolved": true,
  "company": {
    "uuid": "b1f1e2c2-9999-4d2c-9eb6-fdc6c7c92ef9",
    "node_id": "first_registry",
    "status": "Approved",
    "registry_status": "active",
    "data_resolved": true,
    "company_name": "Sante Clinics SL",
    "registration_number": "B12345678",
    "country_code": "ES",
    "region": null,
    "company_type": "SL",
    "incorporation_date": "2018-03-22",
    "registered_address": "Calle Mayor 1, 28001 Madrid, Spain",
    "tax_number": "B12345678",
    "risk_level": "low",
    "verification_status": "verified",
    "is_from_registry": true,
    "fetch_status": "resolved",
    "alternative_names": "Sante Clinics",
    "nature_of_business": "Medical clinic operations",
    "registered_capital": "EUR 50,000",
    "registered_capital_amount": "50000.00",
    "registered_capital_currency": "EUR",
    "website": "https://santeclinics.com",
    "email": "info@santeclinics.com",
    "phone": "+34911223344",
    "legal_entity_identifier": null,
    "location_of_registration": "Registro Mercantil de Madrid",
    "vat_number": "ESB12345678",
    "vat_validation_status": "valid",
    "vat_validated_name": "SANTE CLINICS SL",
    "vat_validated_address": "CALLE MAYOR 1, 28001 MADRID",
    "vat_checked_at": "2026-05-17T10:11:05Z",
    "financial_summary": null,
    "officers": [
      {
        "uuid": "c1f1e2c2-aaaa-4d2c-9eb6-fdc6c7c92ef9",
        "name": "María García López",
        "designation": "Administrador único",
        "role": "Director",
        "nationality": "ESP",
        "is_active": true,
        "kyc_status": "Approved",
        "kyc_session_url": "https://verify.didit.me/s/…"
      }
    ],
    "beneficial_owners": [
      {
        "uuid": "d1f1e2c2-bbbb-4d2c-9eb6-fdc6c7c92ef9",
        "name": "María García López",
        "first_name": "María",
        "last_name": "García López",
        "entity_type": "person",
        "roles": ["UBO"],
        "ownership_min_shares": "75.00",
        "ownership_max_shares": "75.00",
        "is_active": true,
        "kyc_status": "Approved",
        "kyc_session_url": "https://verify.didit.me/s/…",
        "effective_ownership_percent": 75.0
      }
    ],
    "addresses": [],
    "industries": [],
    "accounts": [],
    "registry_data": {},
    "user_provided_data": {},
    "confirmed_by_user_at": "2026-05-17T10:11:02Z",
    "last_console_edit_at": null,
    "is_editable": false
  },
  "ownership_structure": null,
  "warnings": []
}
```

### KYB document

Returned per node that collects KYB supporting documents. Appears as `document_verifications[]` in `GET /v3/session/{sessionId}/decision/` for business sessions — one entry per `node_id`, with `items[]` listing each uploaded document. Source: `kyb/serializers/kyb.py:1053-1068` (`DocumentVerificationV3Serializer`); each item follows `kyb/serializers/kyb.py:811-851` (`KYBDocumentResponseSerializer`).

| Field             | Type                                                            | Nullable | Description                                                                                                                                                                                                                             | Example                                                                                                                                 |
| ----------------- | --------------------------------------------------------------- | -------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `status`          | string                                                          | No       | Aggregate status across this node's documents: `Approved` only when every pipeline document is approved; `Declined` if any is declined; `In Review` otherwise; `Not Finished` while pending. See [Status enum](#status-enum-reference). | `"Approved"`                                                                                                                            |
| `node_id`         | string \| null                                                  | Yes      | Workflow node identifier (V3).                                                                                                                                                                                                          | `"first_kyb_documents"`                                                                                                                 |
| `items`           | array of [KYB document item objects](#kyb-document-item-object) | No       | One entry per uploaded or requested document.                                                                                                                                                                                           | `[…]`                                                                                                                                   |
| `groups`          | object                                                          | No       | Per-document-group counts: `{ <group_name>: { total, approved, pending, declined, in_review, other, missing } }`.                                                                                                                       | `{ "incorporation_certificate": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 } }` |
| `required_groups` | array of strings                                                | No       | Document groups required by the workflow configuration.                                                                                                                                                                                 | `["incorporation_certificate", "shareholder_register"]`                                                                                 |
| `warnings`        | array                                                           | No       | See [Warning object](#warning-object).                                                                                                                                                                                                  | `[]`                                                                                                                                    |

#### KYB document item object

| Field                | Type              | Nullable | Description                                                                                        |
| -------------------- | ----------------- | -------- | -------------------------------------------------------------------------------------------------- |
| `uuid`               | string (UUID)     | No       | Internal document identifier.                                                                      |
| `document_type`      | string            | Yes      | High-level group (`incorporation_certificate`, `shareholder_register`, …).                         |
| `document_subtype`   | string            | Yes      | Provider-specific subtype.                                                                         |
| `document_group`     | string            | Yes      | Mirror of `document_type` (alias kept for clarity).                                                |
| `file_url`           | string (URL)      | Yes      | Presigned URL to the cleaned file.                                                                 |
| `original_filename`  | string            | Yes      | Filename as uploaded.                                                                              |
| `file_size`          | integer           | Yes      | File size in bytes.                                                                                |
| `status`             | string            | No       | Per-document status (`FeatureStatusChoices`).                                                      |
| `created_at`         | string (ISO 8601) | No       | Upload timestamp.                                                                                  |
| `cross_check_result` | object            | Yes      | Cross-check verdict against registry / other docs.                                                 |
| `document_metadata`  | object            | Yes      | Same filtered metadata shape as POA's `document_metadata`.                                         |
| `description`        | string            | Yes      | Reviewer- or system-supplied description.                                                          |
| `is_requested`       | boolean           | No       | `true` when the workflow expected this document.                                                   |
| `ocr_data`           | object            | Yes      | OCR-extracted fields when available.                                                               |
| `is_console_upload`  | boolean           | No       | `true` when the document was uploaded by a console reviewer (excluded from the aggregate verdict). |
| `is_confirmed`       | boolean           | No       | `true` when the reviewer has explicitly confirmed the document.                                    |

```json theme={null}
{
  "status": "Approved",
  "node_id": "first_kyb_documents",
  "items": [
    {
      "uuid": "e1f1e2c2-cccc-4d2c-9eb6-fdc6c7c92ef9",
      "document_type": "incorporation_certificate",
      "document_subtype": "registro_mercantil_extract",
      "document_group": "incorporation_certificate",
      "file_url": "https://<media-host>/.../incorporation.pdf?signature=...",
      "original_filename": "incorporation_certificate.pdf",
      "file_size": 256412,
      "status": "Approved",
      "created_at": "2026-05-17T10:08:00Z",
      "cross_check_result": { "matches_registry_name": true, "matches_registration_number": true },
      "document_metadata": {
        "file_size": 256412,
        "content_type": "application/pdf",
        "is_signed": true,
        "is_tampered": false
      },
      "description": null,
      "is_requested": true,
      "ocr_data": { "company_name": "Sante Clinics SL", "registration_number": "B12345678" },
      "is_console_upload": false,
      "is_confirmed": true
    }
  ],
  "groups": {
    "incorporation_certificate": { "total": 1, "approved": 1, "pending": 0, "declined": 0, "in_review": 0, "other": 0, "missing": 0 }
  },
  "required_groups": ["incorporation_certificate", "shareholder_register"],
  "warnings": []
}
```

### KYB key person

Returned per Key People node in a KYB workflow. Appears as `key_people_checks[]` in `GET /v3/session/{sessionId}/decision/` for business sessions. Source: `kyb/serializers/kyb.py:967-1050` (`KeyPeopleCheckV3Serializer`).

| Field             | Type           | Nullable | Description                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                | Example                                                     |
| ----------------- | -------------- | -------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------- |
| `status`          | string         | No       | See [Status enum](#status-enum-reference).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                 | `"Approved"`                                                |
| `node_id`         | string \| null | Yes      | Workflow node identifier (V3).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                             | `"first_key_people"`                                        |
| `registry`        | object         | No       | `{ officers[], beneficial_owners[] }` extracted from the registry. Officers follow `KYBPersonResponseSerializer` (`kyb/serializers/kyb.py:533-645`); beneficial owners follow `KYBBeneficialOwnerResponseSerializer` (`kyb/serializers/kyb.py:648-788`, which adds `date_of_birth`, `country_of_birth`, `email`, `company_name`, `registration_number`, `entity_type`, `roles`, `ownership_min_shares`, `ownership_max_shares`, `child_beneficial_owners`, `effective_ownership_percent`). Both include per-party AML + KYC enrichment (`aml_status`, `kyc_status`, `kyc_session_url`, `kyc_session_id`, `verification_workflow_type`, `verification_workflow_id`, `verification_workflow_label`, `verification_workflow_features`, `didit_internal_id`, `kyc_document_type`, `kyc_nationality`, `kyc_liveness_passed`, `kyc_verified_at`, `kyc_aml_categories`, `kyc_notification_sent_at`).                                                                                                                                                                                                                                                                                                                                                                                                                              | `{ "officers": [...], "beneficial_owners": [...] }`         |
| `submitted`       | object         | No       | `{ parties[] }` - entries the business confirmed / submitted via the key-people flow (`BusinessParty` rows with `source=USER`). Each party follows `BusinessPartySubmissionResponseSerializer` (`kyb/serializers/party.py:146-194`): `uuid`, `entity_type`, `source`, `name`, `first_name`, `last_name`, `company_name`, `registration_number`, `email`, `nationality`, `phone_number`, `date_of_birth`, `position`, `custom_fields`, `is_active`, `is_skipped`, `requires_verification`, `roles[]` (`{ role, ownership_percent, voting_percent }`), `kyc_session_id`, `kyc_session_status`, `kyc_session_url`, `kyc_session_deleted`, `kyb_sub_session_id`, `kyb_sub_session_status`, `kyb_sub_session_url`, `kyb_sub_session_deleted`, `verification_workflow_type`, `verification_workflow_id`, `verification_workflow_label`, `verification_workflow_features`, `didit_internal_id`. `kyc_session_deleted` / `kyb_sub_session_deleted` mark a child session that was deleted: its status stays frozen at whatever it was, the matching `*_session_url` comes back `null` because the link no longer resolves, and the party stops blocking the parent (the check drops to `In Review` instead). Clear it with [`PATCH /v3/session/{id}/kyb/parties/{party_uuid}/`](/sessions-api/update-data#skip-a-key-people-party). | `{ "parties": [...] }`                                      |
| `ubo_kyc_summary` | object         | Yes      | Counts across active UBOs with linked KYC: `{ total, approved, flagged, pending }`. `null` when no active UBOs have KYC linked.                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                            | `{ "total": 2, "approved": 2, "flagged": 0, "pending": 0 }` |
| `warnings`        | array          | No       | See [Warning object](#warning-object).                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                     | `[]`                                                        |

```json theme={null}
{
  "status": "Approved",
  "node_id": "first_key_people",
  "registry": {
    "officers": [
      {
        "uuid": "c1f1e2c2-aaaa-4d2c-9eb6-fdc6c7c92ef9",
        "name": "María García López",
        "designation": "Administrador único",
        "role": "Director",
        "nationality": "ESP",
        "appointment_date": "2018-03-22",
        "termination_date": null,
        "is_active": true,
        "address": "Calle Mayor 1, 28001 Madrid",
        "aml_status": "Approved",
        "kyc_status": "Approved",
        "kyc_session_url": "https://verify.didit.me/s/…",
        "kyc_session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9",
        "verification_workflow_type": "kyc",
        "verification_workflow_id": "11111111-1111-1111-1111-111111111111",
        "verification_workflow_label": "KYB officer KYC",
        "verification_workflow_features": [
          { "feature": "ID_VERIFICATION", "status": "Approved" },
          { "feature": "LIVENESS", "status": "Approved" },
          { "feature": "FACE_MATCH", "status": "Approved" }
        ],
        "didit_internal_id": "user-12345",
        "kyc_document_type": "Passport",
        "kyc_nationality": "ESP",
        "kyc_liveness_passed": true,
        "kyc_verified_at": "2026-05-17T10:10:11Z",
        "kyc_aml_categories": [],
        "kyc_notification_sent_at": "2026-05-15T08:00:00Z"
      }
    ],
    "beneficial_owners": []
  },
  "submitted": {
    "parties": [
      {
        "uuid": "d1f1e2c2-bbbb-4d2c-9eb6-fdc6c7c92ef9",
        "entity_type": "person",
        "source": "USER",
        "name": "María García López",
        "first_name": "María",
        "last_name": "García López",
        "company_name": null,
        "registration_number": null,
        "email": "maria.garcia@example.com",
        "nationality": "ESP",
        "phone_number": null,
        "date_of_birth": "1990-05-12",
        "position": "Administrador único",
        "custom_fields": {},
        "is_active": true,
        "is_skipped": false,
        "requires_verification": true,
        "roles": [
          { "role": "UBO", "ownership_percent": 75.0, "voting_percent": null }
        ],
        "kyc_session_id": "9b1f1e2c-8888-4d2c-9eb6-fdc6c7c92ef9",
        "kyc_session_status": "Approved",
        "kyc_session_url": "https://verify.didit.me/s/…",
        "kyb_sub_session_id": null,
        "kyb_sub_session_status": null,
        "kyb_sub_session_url": null,
        "verification_workflow_type": "kyc",
        "verification_workflow_id": "11111111-1111-1111-1111-111111111111",
        "verification_workflow_label": "KYB officer KYC",
        "verification_workflow_features": [
          { "feature": "ID_VERIFICATION", "status": "Approved" },
          { "feature": "LIVENESS", "status": "Approved" }
        ],
        "didit_internal_id": "user-12345"
      }
    ]
  },
  "ubo_kyc_summary": { "total": 1, "approved": 1, "flagged": 0, "pending": 0 },
  "warnings": []
}
```

## Status enum reference

Two related value spaces share the `status` field name. Every per-feature report object on this page uses the feature-level enum; the parent session's top-level `status` uses the wider session enum.

### Feature-level statuses

Used by every report object's `status` field. Source: `common/config/choices.py:343-348` (`FeatureStatusChoices`).

| Value             | Meaning                                                                                                              |
| ----------------- | -------------------------------------------------------------------------------------------------------------------- |
| `Not Finished`    | The feature has been provisioned but the user has not completed it yet.                                              |
| `Approved`        | The feature passed all checks.                                                                                       |
| `Declined`        | The feature failed at least one hard check (see `warnings[]` with `log_type: "error"`).                              |
| `In Review`       | The feature triggered soft-fail signals and is awaiting manual review (see `warnings[]` with `log_type: "warning"`). |
| `Resub Requested` | A reviewer requested the user resubmit this feature.                                                                 |

Phone, email, and ID verification can additionally surface `Expired` when their step times out (`PhoneStatusChoices` at `common/config/choices.py:377-382`, `EmailStatusChoices` at `common/config/choices.py:434-439`).

### Session-level statuses

Used by the parent session's top-level `status`. Source: `common/config/choices.py:106-117` (`StatusChoices`).

| Value           | Meaning                                                                                |
| --------------- | -------------------------------------------------------------------------------------- |
| `Not Started`   | The session has been created but the user has not begun it.                            |
| `In Progress`   | The user has started the flow; result not yet finalized.                               |
| `Approved`      | The session passed all checks.                                                         |
| `Declined`      | The session failed at least one hard check.                                            |
| `In Review`     | The session is awaiting manual review.                                                 |
| `Expired`       | The session expired before completion.                                                 |
| `Abandoned`     | The user left the flow without completing it.                                          |
| `Kyc Expired`   | The KYC's validity window elapsed (used in re-verification flows).                     |
| `Resubmitted`   | The user resubmitted after a prior decline; this session is superseded by a newer one. |
| `Awaiting User` | The system is waiting on a user-side action (e.g. OTP entry).                          |

<Tip>
  Terminal session values are `Approved`, `Declined`, `In Review`, `Expired`, `Kyc Expired`, and `Abandoned`. A session can reach its overall decision while an individual feature stays `In Review`.
</Tip>


# Create Session
Source: https://docs.didit.me/sessions-api/create-session

POST /v3/session/
Create a User Verification (KYC) or Business Verification (KYB) session and receive a hosted verification `url` plus a `session_token` to redirect or embed for your end user. The `workflow_id` selects which verification steps run and whether the session is KYC or KYB.

Call this from your backend (never the browser — the API key is a secret) whenever a user or business needs to be verified: at signup, before a sensitive action, or when re-verification is required. Prerequisites: a published workflow (created in the Console [Workflows](https://docs.didit.me/console/workflows) page) and an application API key with available credits. Sandbox applications bypass the credit check.

**Idempotency:** when `vendor_data` is provided and an unfinished session (`Not Started`, `In Progress`, `Resubmitted`, or `Awaiting User`) with the same `vendor_data` already exists on the workflow's **current latest published version** (and that session already has a hosted verification URL), the existing session is returned (still `201`) instead of creating a duplicate — with its `callback` and `metadata` updated to the newly provided values. An unfinished session created on an older version of the workflow (one that has since been republished) is **not** reused; a new session pinned to the latest published version is created instead. Sessions in `Approved`, `Declined`, `In Review`, `Expired`, `Abandoned`, or `Kyc Expired` are never reused.

**Side effects:** the hosted verification URL is generated and stored; if `contact_details.send_notification_emails` is `true` and an email is provided, a verification invite email is sent. The session expires after the workflow's configured session expiration time. For KYB workflows, `contact_details.phone` and `expected_details` are ignored.

<AgentPromptAccordion title="Create Session Prompt" />

## KYC and KYB support

A single endpoint creates both User Verification and Business Verification sessions. The **workflow's type** determines which kind:

* Pass a **KYC workflow** `workflow_id` → a User Verification (KYC) session is created. Response `session_kind: "user"`.
* Pass a **KYB workflow** `workflow_id` → a Business Verification (KYB) session is created. Response `session_kind: "business"`.

Configure workflows in the console at *Workflows → Create workflow*. A workflow is either KYC or KYB at creation time; you cannot switch types afterward.

## Examples

<Tabs>
  <Tab title="User Verification (KYC)">
    ```bash theme={null}
    curl -X POST https://verification.didit.me/v3/session/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "workflow_id": "YOUR_KYC_WORKFLOW_ID",
        "vendor_data": "user-42",
        "callback": "https://yourapp.com/callback"
      }'
    ```

    **Response (201 Created):**

    ```json theme={null}
    {
      "session_id": "4c5c7f3a-1f82-4f3b-8d8e-1a8d2d2f9b7a",
      "session_kind": "user",
      "session_number": 1024,
      "session_token": "...",
      "url": "https://verify.didit.me/session/...",
      "status": "Not Started",
      "workflow_id": "YOUR_KYC_WORKFLOW_ID",
      "vendor_data": "user-42"
    }
    ```
  </Tab>

  <Tab title="Business Verification (KYB)">
    ```bash theme={null}
    curl -X POST https://verification.didit.me/v3/session/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "workflow_id": "YOUR_KYB_WORKFLOW_ID",
        "vendor_data": "biz-acme-001",
        "callback": "https://yourapp.com/callback"
      }'
    ```

    **Response (201 Created):**

    ```json theme={null}
    {
      "session_id": "bs-01HJX1...",
      "session_kind": "business",
      "session_number": 89,
      "session_token": "...",
      "url": "https://verify.didit.me/session/...",
      "status": "Not Started",
      "workflow_id": "YOUR_KYB_WORKFLOW_ID",
      "vendor_data": "biz-acme-001"
    }
    ```
  </Tab>
</Tabs>

## Testing with sandbox scenarios

On a sandbox-mode application, pass `sandbox_scenario` to pre-load a deterministic outcome (approve, a specific decline, or an In Review scenario) without touching real providers or your balance:

```json theme={null}
{
  "workflow_id": "YOUR_SANDBOX_WORKFLOW_ID",
  "sandbox_scenario": "decline_document_expired"
}
```

`sandbox_scenario` is rejected with `400` on live applications. If you don't know the outcome yet at create time, arm (or re-arm) it later via `POST /v3/session/{session_id}/sandbox/arm/`, as long as the session is still `Not Started`: the hosted flow's pre-flow scenario picker uses this same endpoint. See [Sandbox & Test Data](/integration/sandbox-testing) for the full scenario catalog, the magic-value registry, and the arm endpoint's request/response shape.

## `vendor_data` binds the session to an entity

* For KYC workflows: binds to a [User entity](/entities/users/overview). If the user doesn't exist, it's auto-created.
* For KYB workflows: binds to a [Business entity](/entities/businesses/overview). Auto-created if new.

Learn more in [vendor data linking](/entities/vendor-data-linking).

## Important: disclosure and consent still happen in your product

`Create Session` generates a verification URL and session token. It does **not** by itself prove that you showed the user the disclosures or obtained the consent required for your specific use case.

If you start a Didit session from your own application, website, SDK wrapper, or white-label flow, you should handle the legal layer in your own UX before the user starts capture.

## Recommended pre-verification checklist

1. Tell the user that **your company** is requesting the verification and that **Didit** is the verification provider / processor powering the flow.
2. Link to **your privacy notice** and any controller-side legal terms that apply to the journey.
3. Link to Didit's [Verification Privacy Notice](https://didit.me/terms/verification-privacy-notice) and [End User Terms for Identity Verification](https://didit.me/terms/identity-verification).
4. If your workflow includes document capture, selfie capture, liveness, or biometrics, collect **explicit affirmative consent** wherever the applicable law or your legal position requires it.
5. If you use a custom UI, custom domain, or API-only journey, render these disclosures in your own product before sending the user into the Didit flow.
6. Keep your own record of notice / consent text, timestamp, and related metadata if your legal team requires an audit trail.

<Warning>
  Legal requirements vary by jurisdiction. White-label branding does not remove Didit's role in the verification flow. Review your implementation with counsel before launch if you operate in jurisdictions with biometric-specific rules.
</Warning>


# Delete Session
Source: https://docs.didit.me/sessions-api/delete-session

DELETE /v3/session/{sessionId}/delete/
Delete a KYC or KYB session and all of its data. By default the face embedding goes with it; opted-in applications can keep an image-free biometric template.

<AgentPromptAccordion title="Delete Session Prompt" />

## KYC and KYB support

Works for both **User Verification (KYC)** and **Business Verification (KYB)** sessions. The `session_id` is resolved against both session types; the same delete behavior applies to both. Biometric-template retention only applies to KYC sessions, because only KYC sessions carry a face embedding.

## Behavior

* The session is deleted, together with its decision, its extracted data, its associated feature records (ID verifications, registry checks, documents, AML, IP analysis, and so on) and all of its stored media.
* The session disappears from list and decision responses immediately, and media URLs issued before the call stop resolving.
* Deletion is irreversible. There is no restore endpoint, so export anything you need, such as a decision PDF, before you call it.
* The response is `200 OK` with a JSON body that reports what happened to the session's face biometric data. See [Migration](#migration-from-204-responses) if your client still expects `204`.

## Face biometric data: delete or retain

Every KYC session with a liveness selfie carries a face embedding that powers [Face Search 1:N](/core-technology/face-search/overview) and duplicate detection. By default that embedding is deleted with the session (`face_retention_policy: delete_with_session`), so a person whose session you deleted can verify again without being flagged as a duplicate.

Applications that need duplicate detection to survive session deletion can opt in to **biometric-template retention**. Didit then deletes the session and all of its data as usual, and keeps one separately managed, image-free face biometric template anchored to the session's [User](/entities/users/overview).

<Warning>
  A retained biometric template is biometric data. It is not anonymous, it is not transient, and it is not deleted with the session. It stays until its scheduled expiry, an earlier applicable-law deadline, User deletion, a privacy-erasure request, or an explicit purge. Only enable retention when your controller instruction and privacy notice cover it.
</Warning>

What a retained template does and does not contain:

| Retained                                                                                                                            | Never retained                                                                             |
| ----------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------ |
| The numeric face template used for matching                                                                                         | The face image, liveness video, document images, portrait crops, and any other media       |
| A new random template id and an opaque `provenance_reference`                                                                       | The deleted session's id, number, decision, extracted identity fields, or feature payloads |
| The owning User (`vendor_user_uuid`, current `vendor_data`)                                                                         | Blocklist state, prior matches, fraud labels, or cross-organization identity claims        |
| Retention metadata: `retained_at`, `expires_at`, policy, override, instruction class, `instruction_id`, and the acting principal id | Actor email addresses                                                                      |

Retention is configured in three places, from broadest to most specific:

1. **Application policy** in **Business Console → App Settings → Data** or through `PATCH /v3/webhook/` (`face_retention_policy`, `face_retention_days`). See [Data retention](/console/data-retention#biometric-template-retention).
2. **Per-call override** with `retain_face_embeddings` on this endpoint and on [Batch Delete Sessions](/management-api/sessions/batch-delete).
3. **Instruction class** with `deletion_instruction`. A `privacy_erasure` instruction always wins: it purges every retained template for that User and never retains a new one.

### Request body

All fields are optional. Omit the body to follow the application policy.

| Field                     | Type                                                        | Description                                                                                                                                                                                                     |
| ------------------------- | ----------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `retain_face_embeddings`  | boolean or null                                             | Override the application policy for this deletion. `true` retains a template, `false` deletes the embedding with the session, `null` or omitted follows the policy.                                             |
| `face_retention_days`     | integer (1-3650)                                            | Finite retention duration for the template. Required when a template is retained unless the application already sets `face_retention_days`.                                                                     |
| `face_retention_deadline` | datetime (ISO 8601)                                         | Optional hard expiry. Must be in the future.                                                                                                                                                                    |
| `deletion_instruction`    | `operational_session_delete` (default) or `privacy_erasure` | The class of instruction you are giving. `privacy_erasure` purges every retained template for the session's User before deleting the session and cannot be combined with `retain_face_embeddings: true`.        |
| `instruction_id`          | string (max 255)                                            | Your durable reference for this instruction, for example your erasure-ticket id. Recorded on the audit trail and on any retained template. If you omit it Didit generates one, readable on the template detail. |

### Response

```json theme={null}
{
  "session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02",
  "session_number": 1024,
  "face_retention_outcome": "retained_with_user",
  "biometric_template_uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b"
}
```

| `face_retention_outcome`    | Meaning                                                                                                                                                                                                                                      |
| --------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `deleted`                   | The session and its face embedding are deleted. Default behavior.                                                                                                                                                                            |
| `retained_with_user`        | The session is deleted. One image-free biometric template stays anchored to the User; its id is `biometric_template_uuid`. Manage it with the [Biometric Templates API](/management-api/biometric-templates/overview).                       |
| `none`                      | The session had no face embedding to delete or retain (for example a KYB session, or a KYC session without a liveness selfie).                                                                                                               |
| `ineligible_no_vendor_user` | Retention was requested, but the session is not linked to a User (it was created without `vendor_data`), so nothing can anchor a template. The session and its embedding are deleted. The ineligible outcome is recorded on the audit trail. |

The response confirms that Didit accepted and applied your deletion instruction. It is not an erasure certificate: keep the `instruction_id` in your own erasure log so you can correlate the audit trail later.

### Retention duration and expiry

Every retained template has a finite `expires_at`. Didit sets it to the earliest of:

1. `face_retention_days` from the request, or the application's `face_retention_days` when the request omits it;
2. the application's general data-retention window, when one is configured;
3. `face_retention_deadline` from the request, when provided.

A request that would retain a template without any finite duration is rejected with `400` and nothing is deleted. Retained templates cannot outlive the earliest applicable customer instruction, purpose end, configured expiry, data-subject erasure instruction, or statutory biometric deadline. You are responsible for choosing a duration that satisfies the laws that apply to your users; choose a shorter one whenever an applicable rule requires it.

### Privacy erasure

Send `deletion_instruction: "privacy_erasure"` when you are acting on a data-subject request. Didit purges every retained biometric template anchored to the session's User, then deletes the session and its embedding. The application retention policy cannot override a privacy-erasure instruction, and `retain_face_embeddings: true` is rejected with `400`.

Deleting the User with [Batch Delete Users](/management-api/users/delete) also purges its retained templates.

## What is not affected

Deleting a session does not clean these up for you. If you are handling a right-to-erasure request, account for them separately.

* **Blocklist entries** created from the session (face or document) stay in place. Remove them from the [blocklist](/entities/users/blocklist). A face blocklist entry keeps its own biometric entry, independent of any retained template.
* **Hosted-flow share tokens** already issued for the session are not revoked.
* **Webhook deliveries already queued** still arrive, and no webhook is emitted for the deletion itself.
* **Credits already consumed** by the verification are not refunded.
* The parent **User** or **Business** entity is not deleted. Use [Delete Users](/management-api/users/delete) or [Delete Businesses](/management-api/businesses/delete) for those.
* A **retained biometric template** (only when you opted in) stays until it expires or you purge it. Purge it with the [Biometric Templates API](/management-api/biometric-templates/purge), by deleting the User, or by repeating the deletion of another session of the same User with `deletion_instruction: "privacy_erasure"`.

## Examples

<Tabs>
  <Tab title="Default (application policy)">
    ```bash theme={null}
    curl -X DELETE https://verification.didit.me/v3/session/4c5c7f3a-.../delete/ \
      -H "x-api-key: YOUR_API_KEY"
    ```

    Response on an application that has not opted in:

    ```json theme={null}
    {
      "session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02",
      "session_number": 1024,
      "face_retention_outcome": "deleted",
      "biometric_template_uuid": null
    }
    ```
  </Tab>

  <Tab title="Retain a biometric template">
    ```bash theme={null}
    curl -X DELETE https://verification.didit.me/v3/session/4c5c7f3a-.../delete/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"retain_face_embeddings": true, "face_retention_days": 365, "instruction_id": "cleanup-2026-08-0142"}'
    ```

    ```json theme={null}
    {
      "session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02",
      "session_number": 1024,
      "face_retention_outcome": "retained_with_user",
      "biometric_template_uuid": "9d2f4b6e-1c3a-4e8f-b7d5-0a1c2e3f4a5b"
    }
    ```
  </Tab>

  <Tab title="Force deletion on an opted-in app">
    ```bash theme={null}
    curl -X DELETE https://verification.didit.me/v3/session/4c5c7f3a-.../delete/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"retain_face_embeddings": false}'
    ```

    ```json theme={null}
    {
      "session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02",
      "session_number": 1024,
      "face_retention_outcome": "deleted",
      "biometric_template_uuid": null
    }
    ```
  </Tab>

  <Tab title="Privacy erasure">
    ```bash theme={null}
    curl -X DELETE https://verification.didit.me/v3/session/4c5c7f3a-.../delete/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"deletion_instruction": "privacy_erasure", "instruction_id": "dsar-2026-0142"}'
    ```

    Every retained template for the session's User is purged first, then the session is deleted:

    ```json theme={null}
    {
      "session_id": "4c5c7f3a-3b1d-4b7e-9c39-2b4f7e6a1d02",
      "session_number": 1024,
      "face_retention_outcome": "deleted",
      "biometric_template_uuid": null
    }
    ```
  </Tab>

  <Tab title="Session without a User">
    A session created without `vendor_data` has no User to anchor a template to:

    ```bash theme={null}
    curl -X DELETE https://verification.didit.me/v3/session/7a1e9c2d-.../delete/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{"retain_face_embeddings": true, "face_retention_days": 365}'
    ```

    ```json theme={null}
    {
      "session_id": "7a1e9c2d-5f4b-4c3a-8e2d-1b0a9f8e7d6c",
      "session_number": 1031,
      "face_retention_outcome": "ineligible_no_vendor_user",
      "biometric_template_uuid": null
    }
    ```
  </Tab>

  <Tab title="Business Verification (KYB) session">
    ```bash theme={null}
    curl -X DELETE https://verification.didit.me/v3/session/bs-01HJX1.../delete/ \
      -H "x-api-key: YOUR_API_KEY"
    ```

    ```json theme={null}
    {
      "session_id": "0f3c9b7e-2d1a-4e5f-8c6b-7a9d8e1f2c3b",
      "session_number": 88,
      "face_retention_outcome": "none",
      "biometric_template_uuid": null
    }
    ```
  </Tab>
</Tabs>

## Errors

| Status | When                                                                                                                                                                                                       | Body                                                                                                                                    |
| ------ | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------- |
| `400`  | `privacy_erasure` combined with `retain_face_embeddings: true`                                                                                                                                             | `{"retain_face_embeddings": ["Privacy erasure cannot retain biometric templates."]}`                                                    |
| `400`  | Retention requested without a finite duration on the request or the application                                                                                                                            | `{"detail": "A finite biometric-template retention duration is required."}`                                                             |
| `403`  | The credential lacks `delete:sessions` or does not own the session                                                                                                                                         | `{"detail": "You do not have permission to perform this action."}`                                                                      |
| `404`  | Unknown or already-deleted session                                                                                                                                                                         | `{"detail": "Not found."}`                                                                                                              |
| `503`  | A biometric store was unavailable while retaining or purging a template. The session is not deleted and the source embedding is untouched. Repeat the same request; retries converge on a single template. | `{"detail": "The biometric-template operation could not finish because an external store is unavailable. The operation is retryable."}` |

On `400` and `503` nothing is deleted.

## Permission

Requires `delete:sessions`. The same permission covers both User Verification (KYC) and Business Verification (KYB) sessions, and the retention override.

## Batch delete

For bulk operations, use `POST /v3/sessions/delete/`. It accepts the same retention and instruction fields and returns a per-session outcome. See [Batch Delete Sessions](/management-api/sessions/batch-delete).

## Migration from 204 responses

Until this release the endpoint returned `204 No Content`. It now returns `200 OK` with the JSON body documented above so that every deletion reports its `face_retention_outcome`. Update clients that assert on `204`.

The default behavior is unchanged: existing applications stay on `delete_with_session`, and no migration enables retention on your behalf. Enable it explicitly in the Console or through `PATCH /v3/webhook/`.

## Related

* [Biometric templates](/management-api/biometric-templates/overview)
* [Data retention](/console/data-retention)
* [Sessions overview](/sessions-api/overview)


# Generate PDF
Source: https://docs.didit.me/sessions-api/generate-pdf

GET /v3/session/{sessionId}/generate-pdf/
Render and download a compliance-ready PDF report for a finished verification session. The same path serves both User Verification (KYC) and Business Verification (KYB) sessions — the server resolves the `sessionId` against both session types and picks the matching report template.

**Eligible statuses.** The session must already carry a final or reviewable status:

- KYC sessions: `Approved`, `Declined`, `In Review`, or `Kyc Expired`.
- KYB sessions: `Approved`, `Declined`, or `In Review`.

Any other status (`Not Started`, `In Progress`, `Expired`, `Abandoned`, …) returns `403` with an explanatory `detail` string — see the `403` response below.

**What the report contains.** The PDF mirrors the console session view at the moment of the request:

- **KYC** — rolled-up session status, the warnings list, and one section per executed feature: ID Verification (document images plus extracted fields), NFC, Liveness, Face Match, Email Verification, Phone Verification, Proof of Address, Questionnaire answers, Database Validation, AML Screening, and IP Analysis — followed by session tags, console review activity (comments and status changes), and the session event timeline.
- **KYB** — registry checks (company data), AML screenings, business document verifications, key-people checks, questionnaire responses, phone/email verifications, IP analyses, and the session event timeline, followed by tags and review activity.

**Branding.** If your application has white-label customization, the report is rendered with your logo and links to your privacy-policy URL; otherwise it carries Didit branding. Reports are rendered in English — there is no language parameter.

**No caching.** Every call re-renders the PDF from the current session data, so a report generated after a manual review reflects the reviewer’s decision. Two calls for the same session can produce byte-different files — archive the downloaded file if you need an immutable copy.

**Latency.** Rendering downloads every stored image (document sides, selfies, extra files) before composing the PDF, so media-heavy sessions can take several seconds. Use a generous client read timeout (60 s recommended) and stream the body to disk.

**Trailing slash.** The canonical route ends with a trailing slash (`…/generate-pdf/`). Requests without it receive a `301` redirect to the slashed URL — most HTTP clients follow it automatically for `GET`, but plain `curl` needs `-L` (or call the slashed URL directly, as in the samples).

If you need the underlying data as JSON instead of a rendered report, use `GET /v3/session/{sessionId}/decision/`.

<AgentPromptAccordion title="Generate PDF Prompt" />

## KYC and KYB support

Works for both **User Verification (KYC)** and **Business Verification (KYB)** sessions. Didit routes to the appropriate PDF template automatically:

* User Verification (KYC) session → report with ID verification, liveness, face match, AML, POA sections.
* Business Verification (KYB) session → report with company registry, key people (UBOs/officers), documents, AML, questionnaire, phone, email, and IP analysis sections when those features are part of the workflow.

Both use the same PDF generation pipeline and support white-label customization (logo, privacy policy URL).

## Filename convention

| Kind     | Filename                    |
| -------- | --------------------------- |
| User     | `session_<session_id>.pdf`  |
| Business | `business_<session_id>.pdf` |

Returned via the `Content-Disposition: attachment; filename=...` header.

## Status requirement

The session must be in `APPROVED`, `DECLINED`, or `IN_REVIEW` to generate a PDF. In-progress or not-started sessions return `403`.

## Examples

<Tabs>
  <Tab title="User Verification (KYC) PDF">
    ```bash theme={null}
    curl https://verification.didit.me/v3/session/4c5c7f3a-.../generate-pdf/ \
      -H "x-api-key: YOUR_API_KEY" \
      -o kyc-report.pdf
    ```
  </Tab>

  <Tab title="Business Verification (KYB) PDF">
    ```bash theme={null}
    curl https://verification.didit.me/v3/session/bs-01HJX1.../generate-pdf/ \
      -H "x-api-key: YOUR_API_KEY" \
      -o kyb-report.pdf
    ```
  </Tab>
</Tabs>

## White-label

When the application has white-label customization enabled, the PDF uses your logo and privacy-policy URL. Configure at *Console → Customization*.

## Permission

Requires `read:sessions`. Same scope for both kinds.

## Related

* [Sessions overview](/sessions-api/overview)
* [Retrieve session](/sessions-api/retrieve-session) — JSON version of the same decision
* [KYB response schema](/business-verification/response-schema) — fields included in business PDFs


# Import Data from Another Provider
Source: https://docs.didit.me/sessions-api/import-verifications

POST /v3/session/imports/
Create an asynchronous import job for historical User Verification sessions, Business Verification sessions, transaction monitoring records, or workflow custom status rules. Use this to migrate from providers such as Sumsub, MetaMap, Veriff, Onfido, Persona, Trulioo, Jumio, Incode, iDenfy, or any other provider after transforming the export into Didit's canonical CSV/NDJSON format. Imports are disabled by default and must be enabled per organization by Didit.

Use this guide to choose the right import path when you move data from another provider into Didit. There are two different jobs customers often call "import":

* **Import historical verification work** — recreate completed KYC, KYB, transaction monitoring, or workflow-rule records so Didit shows the old provider history. Use `POST /v3/session/imports/`.
* **Import operating data** — create Users, Businesses, profile faces, blocklist entries, or allowlist entries so Didit can use them in future checks. Use the entity, face, and list APIs.

Verification imports create historical records with `session_type: "MIGRATED"` for KYC and KYB. They do not send end-user emails, do not redirect users into the hosted flow, and do not re-run the original verification. The imported records appear in session lists, entity profiles, transaction views, and `GET /v3/session/{session_id}/decision/` where applicable.

## Which import should you use?

| Goal                                               | Use this import path                                                                                                        | What it creates                                                                                                | Best for                                                                                                                           |
| -------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| Recreate historical KYC sessions                   | `POST /v3/session/imports/` with `import_type=user_verification`                                                            | `Session`, ID Verification data, optional document/selfie images, document and liveness videos, tags, metadata | Moving completed applicants from Sumsub, MetaMap, Veriff, Onfido, Persona, Jumio, Incode, iDenfy, Trulioo, or another KYC provider |
| Recreate historical KYB sessions                   | `POST /v3/session/imports/` with `import_type=business_verification`                                                        | `BusinessSession`, registry company data, officers, beneficial owners, tags, metadata                          | Moving completed business checks from KYB vendors, company registry providers, or internal KYB tooling                             |
| Recreate historical transaction monitoring records | `POST /v3/session/imports/` with `import_type=transactions`                                                                 | `Transaction`, subject/counterparty parties, provider results, Travel Rule data, network snapshot, metadata    | Moving rule-engine, KYT, wallet-screening, or fiat transaction monitoring history                                                  |
| Import custom workflow status rules                | `POST /v3/session/imports/` with `import_type=status_rules`                                                                 | `VerificationSettings.feature_status_rules`                                                                    | Moving policy logic from another provider or spreadsheet into Didit's workflow engine                                              |
| Create Users without historical sessions           | `POST /v3/users/create/` or Console CSV import                                                                              | `VendorUser` profile rows                                                                                      | Loading your user roster before starting new Didit checks                                                                          |
| Attach trusted profile faces to users              | `POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/` | Profile face evidence indexed for duplicate detection and face search                                          | Migrating profile face images from another KYC provider without recreating full sessions                                           |
| Blocklist or allowlist faces                       | `POST /v3/lists/{list_uuid}/entries/face-upload/` or `POST /v3/lists/{list_uuid}/entries/` with `reference_session_id`      | Face list entry and biometric embedding                                                                        | Migrating known fraud faces, trusted allowlist faces, or blocklisting a face from an existing Didit session                        |
| Create Businesses without historical KYB sessions  | `POST /v3/businesses/create/` or Console CSV import                                                                         | `VendorBusiness` profile rows                                                                                  | Loading a business customer roster before running KYB                                                                              |

<Note>
  If you only need a user or business profile for future checks, do not import a historical verification session. Use the User or Business entity APIs. If you need the old provider's decision, document fields, warnings, or evidence to appear as compliance history in Didit, use `POST /v3/session/imports/`.
</Note>

## What can migrate from each provider?

Didit accepts a canonical CSV or NDJSON file, so you can migrate from any provider once you export and transform the data. The import contract is always Didit's canonical schema.

| Provider family                        | Typical sources                                                                                                                      | Usually migratable                                                                                                                                    | Notes                                                                                                                              |
| -------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| KYC providers                          | Sumsub, MetaMap, Veriff, Onfido, Persona, Jumio, Incode, iDenfy, Trulioo, HyperVerge, AU10TIX, Mitek, Ondato                         | Applicant id, vendor user id, decision status, document fields, document images, selfie/liveness image, rejection labels, tags, raw provider metadata | Use `import_type=user_verification`. If the provider cannot export images, import the structured fields and keep image URLs empty. |
| KYB providers                          | Company registry providers, Sumsub KYB, Trulioo KYB, Creditsafe-style registry exports, internal KYB tools                           | Company name, registration number, country, registry status, officers, beneficial owners, risk level, raw registry payload                            | Use `import_type=business_verification`. Officers and UBOs are passed as JSON arrays.                                              |
| Transaction monitoring / KYT providers | Sumsub Transaction Monitoring, Chainalysis-style KYT exports, Crystal, Merkle Science, Sardine, Unit21, Alloy, internal rule engines | Transaction id, amount, currency, direction, subject/counterparty, rule hits, provider results, Travel Rule status, network graph snapshot            | Use `import_type=transactions`. Imported transactions are historical records; they are not re-screened by default.                 |
| Workflow and policy spreadsheets       | Compliance policy exports, provider rule tables, internal risk spreadsheets                                                          | Per-feature status rules such as "if issuing country is X, set ID Verification to In Review"                                                          | Use `import_type=status_rules`. Rules are validated against Didit's workflow field catalog before they are saved.                  |
| User/profile stores                    | CRM, customer DB, provider user export, data warehouse                                                                               | `vendor_data`, display name, metadata, tags, trusted face images                                                                                      | Use User APIs and profile face upload. This is not the same as a completed verification session.                                   |
| Blocklist / allowlist data             | Provider fraud lists, internal fraud ops sheets, chargeback lists, sanctions-adjacent internal lists                                 | Emails, phones, documents, wallets, IPs, device fingerprints, faces, countries, users, businesses                                                     | Use Lists APIs. For face images, use the dedicated face upload endpoint so Didit can extract the biometric embedding.              |

## Migration workflow

1. Decide whether you are importing history, profiles, faces, lists, transactions, or rules.
2. Export the data from the old provider yourself. Do not send old-provider API keys to Didit.
3. Transform the provider export into the matching Didit canonical CSV or NDJSON template.
4. For large migrations, prefer NDJSON and split into files you can retry independently.
5. Create the import job and poll progress.
6. Fetch row errors, fix only failed rows, and retry them. All import jobs are idempotent on their natural external id.

## Create an import job

Create an import job with a single multipart request:

```bash theme={null}
curl -X POST https://verification.didit.me/v3/session/imports/ \
  -H "x-api-key: YOUR_API_KEY" \
  -F "import_type=user_verification" \
  -F "workflow_id=YOUR_KYC_WORKFLOW_ID" \
  -F "file=@didit-import.ndjson"
```

Use CSV for smaller spreadsheet-driven migrations and NDJSON for large migrations. For 100k+ rows, NDJSON is easier to stream, split, validate, and retry.

For transaction imports, omit `workflow_id`:

```bash theme={null}
curl -X POST https://verification.didit.me/v3/session/imports/ \
  -H "x-api-key: YOUR_API_KEY" \
  -F "import_type=transactions" \
  -F "file=@didit-transactions.ndjson"
```

### Request fields

| Field             | Required                            | Description                                                                                                                                                                                    |
| ----------------- | ----------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `import_type`     | No, defaults to `user_verification` | One of `user_verification`, `business_verification`, `status_rules`, `transactions`.                                                                                                           |
| `workflow_id`     | Yes, except for `transactions`      | UUID of the workflow the imported records attach to. `user_verification` and `status_rules` need a User Verification workflow; `business_verification` needs a Business Verification workflow. |
| `file`            | Either `file` or `source_file_url`  | The canonical CSV or NDJSON file, uploaded inline.                                                                                                                                             |
| `source_file_url` | Either `file` or `source_file_url`  | HTTPS URL Didit downloads the file from. Private-network URLs are rejected.                                                                                                                    |
| `source_format`   | No                                  | `csv` or `ndjson`. Inferred from the file extension when omitted.                                                                                                                              |

### How records are tracked and deduplicated

There is no request field for the data source — every import uses Didit's canonical schema. Each imported record stores `metadata.imported_from = "generic"` for traceability.

`user_verification` and `business_verification` imports deduplicate rows on `external_id` within the application, so retrying the same file won't create duplicates. `transactions` imports deduplicate on `transaction_id` instead.

## Import document photos, videos, and selfie evidence

For `import_type=user_verification`, you can import the original document photos, document/liveness capture videos, and selfie image from the previous provider.

Use these canonical columns:

| Evidence                | Preferred column           | Small-import fallback   | Stored in Didit as              |
| ----------------------- | -------------------------- | ----------------------- | ------------------------------- |
| Document front image    | `document_front_url`       | `document_front_base64` | ID Verification OCR front image |
| Document back image     | `document_back_url`        | `document_back_base64`  | ID Verification OCR back image  |
| Selfie / liveness image | `selfie_url`               | `selfie_base64`         | Face/Liveness reference image   |
| Document front video    | `document_front_video_url` | URL only                | ID Verification OCR front video |
| Document back video     | `document_back_video_url`  | URL only                | ID Verification OCR back video  |
| Liveness video          | `liveness_video_url`       | URL only                | Face/Liveness capture video     |

For large migrations, use **HTTPS URLs**. Didit downloads each file, validates the URL is safe, stores a Didit-owned copy, and links it to the imported session. Images are compressed; videos are stored as-is. Inline base64 is accepted for images on small imports, but **videos must always be supplied as a URL** — base64 would inflate each video by \~33% and quickly exceed the per-file import limit.

Example NDJSON row with provider-hosted media URLs:

```json theme={null}
{
  "external_id": "applicant-123",
  "vendor_data": "user-42",
  "created_at": "2025-01-12T10:30:00Z",
  "status": "Approved",
  "email": "user@example.com",
  "phone": "+34687020083",
  "first_name": "Jane",
  "last_name": "Doe",
  "date_of_birth": "1990-05-15",
  "document_type": "P",
  "issuing_state": "USA",
  "document_number": "123456789",
  "expiration_date": "2030-01-15",
  "document_front_url": "https://provider-export.example.com/files/applicant-123-front.jpg",
  "document_back_url": "https://provider-export.example.com/files/applicant-123-back.jpg",
  "selfie_url": "https://provider-export.example.com/files/applicant-123-selfie.jpg",
  "document_front_video_url": "https://provider-export.example.com/files/applicant-123-front.webm",
  "document_back_video_url": "https://provider-export.example.com/files/applicant-123-back.webm",
  "liveness_video_url": "https://provider-export.example.com/files/applicant-123-liveness.mp4",
  "reject_reasons_json": "[]",
  "provider_metadata_json": "{\"source\":\"sumsub-export\"}"
}
```

Important media rules:

* URLs must use `https`.
* URLs must not resolve to private IPs, localhost, link-local ranges, or internal metadata hosts.
* Images accept either a URL column or its `*_base64` fallback; base64 takes precedence when both are set. Videos are URL only — there is no `*_video_base64` column.
* Videos must be `mp4`, `webm`, or `mov`, and each video may be at most **10 MB**. Larger or non-video files are rejected as row errors.
* Didit enforces connect/read timeouts, maximum file size, and no infinite retries.
* Media download failures are stored as row errors so the rest of the import can continue.
* If you do not have media from the provider, leave these columns empty. Didit still imports the structured decision and document fields.
* Imported images and videos are evidence for historical review. Didit does not re-run OCR, liveness, or document-fraud analysis on imported historical media by default.

<AgentPromptAccordion title="User Verification Import Prompt" />

<AgentPromptAccordion title="Business Verification Import Prompt" />

<AgentPromptAccordion title="Custom Status Rules Import Prompt" />

<AgentPromptAccordion title="Transaction Import Prompt" />

## Poll progress

```bash theme={null}
curl https://verification.didit.me/v3/session/imports/IMPORT_ID/ \
  -H "x-api-key: YOUR_API_KEY"
```

The response includes `status`, `import_type`, `total_rows`, `processed_rows`, `created_count`, `updated_count`, `skipped_count`, `failed_count`, and `checkpoint_row`.

## Download row errors

```bash theme={null}
curl https://verification.didit.me/v3/session/imports/IMPORT_ID/errors/ \
  -H "x-api-key: YOUR_API_KEY"
```

Each error includes `row_number`, `external_id`, `error`, and `raw_row`, so you can fix only the failed rows and retry.

## Abuse protection

Historical import jobs through `POST /v3/session/imports/` are disabled by default. Didit enables this capability per organization after review because these jobs can process millions of rows and download media. The normal operating-data imports in this guide — creating Users, creating Businesses, uploading profile faces, uploading face blocklists, or adding list entries — do not require special migration enablement beyond the normal API key permissions, product availability, and rate limits for those endpoints.

Historical import jobs also run on isolated workers with file size limits, row budgets, HTTPS-only media URLs, private-network URL blocking, per-application active-job limits, and per-row error capture.

## Canonical statuses

| Provider outcome                           | Didit status |
| ------------------------------------------ | ------------ |
| Approved / Green / Verified                | `Approved`   |
| Declined / Red / Rejected                  | `Declined`   |
| Manual review / Pending / Review needed    | `In Review`  |
| Incomplete / Init / Unknown historical row | `Expired`    |

## Idempotency

Didit uses `external_id` as the import idempotency key for User Verification and Business Verification imports, scoped per application. Transaction imports use `transaction_id` per application. Retrying the same file skips rows that were already imported and creates rows that were not processed yet.

## Import users, profile faces, and blocklists

Use these paths when you are not recreating a completed verification session:

### Import user profiles

Create users with [`POST /v3/users/create/`](/management-api/users/create) or the Business Console CSV import in [Import and Export Users](/entities/users/import-export). This creates or updates the `VendorUser` profile only. It does not create a verification session, KYC decision, document report, warning, or webhook history.

Use this when you want Didit to know the customer exists before future checks, or when you need to backfill CRM-like fields such as `display_name`, tags, or metadata.

### Upload trusted profile faces

After a User exists, upload a trusted profile face with [`POST /v3/organization/{organization_id}/application/{application_id}/vendor-users/by-id/{didit_internal_id}/faces/upload/`](/management-api/users/upload-face). This attaches biometric evidence to the User profile and indexes it for duplicate detection and face search.

This does **not** blocklist the face. It is useful when you have a trusted profile image from a previous KYC provider and want future Didit checks to compare against it.

### Import face blocklists and allowlists

To block or allow a face directly, use [`POST /v3/lists/{list_uuid}/entries/face-upload/`](/management-api/lists/upload-face) with a face-type list. Didit extracts the biometric embedding and stores a list entry.

Use this for known fraudster images, trusted allowlist faces, or provider fraud-list migrations. If the face comes from an existing Didit session, prefer [`POST /v3/lists/{list_uuid}/entries/`](/management-api/lists/create-entry) with `reference_session_id`; Didit extracts the right face from the session and links the entry back to the source.

### Import user, business, document, wallet, email, phone, IP, or device lists

Use [`POST /v3/lists/{list_uuid}/entries/`](/management-api/lists/create-entry) for non-face list values. This is the right path for provider blocklists, allowlists, chargeback lists, wallet addresses, known risky IPs, device fingerprints, document numbers, emails, phones, users, or businesses.

## Next steps

<CardGroup>
  <Card title="Import users" icon="users" href="/entities/users/import-export">
    Load User profiles and attach trusted profile faces.
  </Card>

  <Card title="Import businesses" icon="building" href="/entities/businesses/import-export">
    Load Business profiles before running KYB.
  </Card>

  <Card title="Upload profile face" icon="face-viewfinder" href="/management-api/users/upload-face">
    Attach trusted face images to imported Users.
  </Card>

  <Card title="Upload face to list" icon="ban" href="/management-api/lists/upload-face">
    Add faces to blocklists or allowlists.
  </Card>

  <Card title="Create list entry" icon="list" href="/management-api/lists/create-entry">
    Import phones, emails, wallets, documents, IPs, devices, users, or businesses into lists.
  </Card>

  <Card title="Rate limits" icon="gauge" href="/integration/rate-limiting">
    Design safe migration loops and retries.
  </Card>
</CardGroup>


# List Sessions
Source: https://docs.didit.me/sessions-api/list-sessions

GET /v3/sessions/
Returns a paginated list of verification sessions for the application identified by your API key, newest first (descending `session_number`).

**Canonical URL:** the route is `/v3/sessions/` (trailing slash). Requests to `/v3/sessions` without the slash receive a `301` redirect to the slashed URL with the query string preserved; most HTTP clients follow it transparently on GET.

**When to use this endpoint vs webhooks.** Use this endpoint for dashboards, back-office search, reconciliation, and batch exports. Do not poll it to track the progress of individual verifications - configure [webhooks](/integration/webhooks) instead, which push `status.updated` events the moment a session changes. For one session's full result, call `GET /v3/session/{sessionId}/decision/`.

**KYC and KYB sessions.** `session_kind` selects which kinds are listed:
- `user` (default) - User Verification (KYC) sessions only. Backward-compatible behavior.
- `business` - Business Verification (KYB) sessions only. Rows have a different, smaller shape (see the response schema).
- `all` - both kinds in one response: the KYC page and the KYB page for the same `limit`/`offset` are concatenated in `results` (KYC rows first), so a page can contain up to `2 x limit` rows. `count` is the sum of both kinds and `next`/`previous` reflect the KYC-side pagination. For strict pagination of mixed data, call `user` and `business` separately.

Every row carries a `session_kind` discriminator (`"user"` or `"business"`).

**Pagination.** Standard limit/offset: `limit` (default 50) and `offset` (default 0), with `next`/`previous` ready-made page URLs. For KYC rows `count` is exact. For KYB rows `count` is computed with a bounded scan and is capped at 100 - when there are more than 100 matches it stays at 100, so iterate using `next` (or by checking whether a full page came back) rather than computing total pages from `count`.

**Filter semantics.** All filters combine with AND and apply to KYC rows. When `session_kind` is `business` or `all`, the KYB side honors the shared parameters `vendor_data`, `status`, `workflow_id`, `country` (registry-company country code), `date_from`, `date_to`, `search` (company name, registration number — type registration numbers without separators, e.g. `DPC001` not `DPC-001` — vendor_data, session number, or session UUID), `warning`, and `organization_name`; the remaining KYC-only filters are ignored for KYB rows. Comma-separated parameters (`status`, `country`, `document_type`, `region`, `workflow_id`, `document_name`, `warning`, `organization_name`, `session_type`) match any of the listed values (OR within the parameter). `vendor_data` is an exact match - use `search` for partial matching. Unknown values in list filters simply return no rows (no error); malformed typed values (`date_from`, `date_to`, `didit_internal_id`, `api_service`, `session_kind`) return `400` with a per-field error object.

**Search.** `search` adapts to the input: a full UUID looks up `session_id`; digits (with optional `+ - . space`) match session-number prefix, document/personal numbers, phone-number prefix, or `vendor_data`; values containing `@` match email prefixes; any other text matches names (accent-insensitive) and `vendor_data`.

No fixed per-endpoint rate limit is enforced, but keep list polling infrequent and rely on webhooks for real-time updates.

<AgentPromptAccordion title="List Sessions Prompt" />

## Session kind filter

Use the `session_kind` query parameter to choose which kind of sessions to return:

| Value            | Returns                                                                                                    |
| ---------------- | ---------------------------------------------------------------------------------------------------------- |
| `user` (default) | Only User Verification (KYC) sessions. **Backward-compatible behavior** — omit `session_kind` to get this. |
| `business`       | Only Business Verification (KYB) sessions.                                                                 |
| `all`            | Both User Verification and Business Verification sessions, concatenated.                                   |

Every row in the response includes `session_kind: "user" | "business"` so your client can switch on shape per row.

## Common filters

These filters apply to both kinds (the user-only filters are ignored when `session_kind=business`, and vice versa):

| Query parameter        | Description                                                                                                                                       |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `session_kind`         | `user`, `business`, or `all`. Default `user`.                                                                                                     |
| `vendor_data`          | Exact match on your identifier.                                                                                                                   |
| `status`               | `APPROVED`, `DECLINED`, `IN_REVIEW`, etc.                                                                                                         |
| `workflow_id`          | Filter by the workflow used.                                                                                                                      |
| `country`              | Country code filter (user: `issuing_states`, business: `country_code`).                                                                           |
| `date_from`, `date_to` | Created-date window (ISO 8601).                                                                                                                   |
| `search`               | Substring match. For user: vendor\_data, full name, document number, phone, email. For business: vendor\_data, company name, registration number. |

## Examples

<Tabs>
  <Tab title="List User Verification (KYC) sessions (default)">
    ```bash theme={null}
    curl -G https://verification.didit.me/v3/sessions/ \
      -H "x-api-key: YOUR_API_KEY" \
      --data-urlencode "vendor_data=user-42"
    ```

    **Response (truncated):**

    ```json theme={null}
    {
      "count": 3,
      "next": null,
      "previous": null,
      "results": [
        {
          "session_id": "...",
          "session_kind": "user",
          "session_number": 1024,
          "session_url": "...",
          "portrait_image": "...",
          "document_type": "Passport",
          "full_name": "John Doe",
          "country": "GBR",
          "status": "APPROVED",
          "vendor_data": "user-42",
          "didit_internal_id": "...",
          "created_at": "2026-04-10T09:00:00Z",
          "features": "ID_VERIFICATION,LIVENESS,FACE_MATCH,AML",
          "phone_number": "+14155550123",
          "email_address": "jane@example.com",
          "additional_details": null
        }
      ]
    }
    ```
  </Tab>

  <Tab title="List Business Verification (KYB) sessions">
    ```bash theme={null}
    curl -G https://verification.didit.me/v3/sessions/ \
      -H "x-api-key: YOUR_API_KEY" \
      --data-urlencode "session_kind=business" \
      --data-urlencode "status=APPROVED"
    ```

    **Response (truncated):**

    ```json theme={null}
    {
      "count": 1,
      "next": null,
      "previous": null,
      "results": [
        {
          "session_id": "...",
          "session_kind": "business",
          "session_number": 89,
          "status": "APPROVED",
          "vendor_data": "biz-acme-001",
          "created_at": "2026-04-01T09:00:00Z",
          "workflow_id": "wf_kyb_standard",
          "workflow_type": "business",
          "workflow_label": "Standard KYB",
          "company_name": "Acme Corporation Limited",
          "registration_number": "12345678",
          "country": "GBR"
        }
      ]
    }
    ```
  </Tab>

  <Tab title="List both kinds">
    ```bash theme={null}
    curl -G https://verification.didit.me/v3/sessions/ \
      -H "x-api-key: YOUR_API_KEY" \
      --data-urlencode "session_kind=all" \
      --data-urlencode "date_from=2026-04-01T00:00:00Z"
    ```

    Returns User Verification and Business Verification rows in a single `results` array. Consumers should switch per row on `session_kind`.

    <Note>
      The `all` mode concatenates results rather than interleaving them by timestamp. For high-volume mixed traversals, call each kind separately and merge client-side.
    </Note>
  </Tab>
</Tabs>

## Row shapes differ by kind

User Verification (KYC) rows include: `portrait_image`, `document_type`, `full_name`, `country` (issuing state), `phone_number`, `email_address`.

Business Verification (KYB) rows include: `workflow_type`, `workflow_label`, `company_name`, `registration_number`, `country` (country of incorporation).

Both carry: `session_id`, `session_kind`, `session_number`, `status`, `vendor_data`, `created_at`.

See [sessions overview](/sessions-api/overview) for the complete feature matrix.

## Pagination

Cursor-based via `page_size` and the `next` / `previous` pointers in the response. Default `page_size=25`, max `100`.

## Related

* [Sessions overview](/sessions-api/overview)
* [Retrieve session](/sessions-api/retrieve-session) — full decision for a single row
* [Businesses overview](/entities/businesses/overview) — the Business entity aggregated across sessions
* [Users overview](/entities/users/overview) — the User entity aggregated across sessions


# Management API (v3)
Source: https://docs.didit.me/sessions-api/management-api

Configure workflows, questionnaires, users, billing, and blocklists via API key. Agent-native, MCP-ready. Pay-per-use pricing, no contracts.

## Authentication

All management API endpoints use your application API key. No org/app UUIDs are needed in URLs -- the application is identified from your key.

```bash theme={null}
curl -H "x-api-key: YOUR_API_KEY" https://verification.didit.me/v3/...
```

Don't have an API key yet? [Register programmatically in 2 API calls](/integration/programmatic-registration).

***

## Workflows

Workflows define what verification steps your users go through (ID scan, liveness, face match, AML screening, etc.). Each workflow is a reusable configuration you attach to sessions.

<ParamField type="GET">
  List all workflows for your application. Returns each workflow's features, thresholds, and whether it's the default.
</ParamField>

<ParamField type="POST">
  Create a new workflow. Define which verification features to enable, set thresholds, configure accepted document types, and more.
</ParamField>

<ParamField type="GET">
  Get full details of a specific workflow, including all feature configurations and thresholds.
</ParamField>

<ParamField type="PATCH">
  Update a workflow configuration. You can modify any feature settings, thresholds, or accepted documents.
</ParamField>

<ParamField type="DELETE">
  Delete a workflow. Sessions already using this workflow are not affected.
</ParamField>

<Warning>
  We strongly recommend using the **Business Console** to create and configure workflows. The visual workflow builder provides templates, drag-and-drop feature configuration, document settings, threshold tuning, and preview — all without writing code. Use the API only for automation or programmatic management of workflows.
</Warning>

### Quick Example: Create a Workflow

The `workflow_type` determines the base feature set. Individual features are then toggled with `is_*_enabled` flags.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/workflows/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "workflow_label": "Standard KYC",
    "workflow_type": "kyc",
    "is_default": true,
    "is_face_match_enabled": true,
    "is_liveness_enabled": true,
    "is_aml_enabled": false
  }'
```

Available `workflow_type` values: `kyc`, `kyb`, `adaptive_age_verification`, `biometric_authentication`, `address_verification`, `questionnaire_verification`, `email_verification`, `phone_verification`.

For `kyc` workflows, ID verification is automatically included — you don't need a separate flag for it. Use the `is_*_enabled` flags to add or remove optional features like face match, liveness, AML, NFC, phone, email, proof of address, Device & IP Analysis, and more.

Then use the workflow when creating sessions:

```bash theme={null}
curl -X POST https://verification.didit.me/v3/session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "callback_url": "https://myapp.com/callback",
    "workflow_id": "WORKFLOW_UUID_FROM_ABOVE"
  }'
```

***

## Questionnaires

Custom forms you can add to verification workflows to collect additional information from users.

<ParamField type="GET">
  List all questionnaires.
</ParamField>

<ParamField type="POST">
  Create a new questionnaire with custom questions, branching logic, and translations.
</ParamField>

<ParamField type="GET">
  Get questionnaire details including all questions and form structure.
</ParamField>

<ParamField type="PATCH">
  Update a questionnaire.
</ParamField>

<ParamField type="DELETE">
  Delete a questionnaire.
</ParamField>

***

## Users

Manage verified individuals (users) in your application. Each user is identified by a `vendor_data` string you provide when creating sessions.

<ParamField type="GET">
  List all users for your application, including their verification status and session history.
</ParamField>

<ParamField type="GET">
  Get user details by your vendor\_data identifier.
</ParamField>

<ParamField type="PATCH">
  Update user metadata.
</ParamField>

<ParamField type="POST">
  Batch delete users. Body: `{"vendor_data_list": ["user-1", "user-2"]}` or `{"delete_all": true}`. Also purges every biometric template retained for those users.
</ParamField>

***

## Biometric Templates

Image-free face biometric templates an opted-in application retains after deleting sessions. See [Biometric templates](/management-api/biometric-templates/overview).

<ParamField type="GET">
  Paginated list with filters (`vendor_data`, `vendor_user_uuid`, `status`, `source_type`, `retained_from`, `retained_to`, `ordering`).
</ParamField>

<ParamField type="GET">
  Count with the same filters.
</ParamField>

<ParamField type="GET">
  One template: owning User, provenance reference, expiry, instruction, status.
</ParamField>

<ParamField type="DELETE">
  Purge one template. Returns `{"uuid": "...", "outcome": "purged" | "already_purged"}`.
</ParamField>

<ParamField type="POST">
  Bulk purge. Body: `{"template_uuids": [...]}` or `{"delete_all": true}` plus optional filters.
</ParamField>

***

## Session Operations

<ParamField type="POST">
  Batch delete sessions. Requires `delete:sessions`. Body: `{"session_numbers": ["1", "2", "3"]}` or `{"delete_all": true}`, plus optional `retain_face_embeddings`, `face_retention_days`, `face_retention_deadline`, `deletion_instruction`, and `instruction_id`. Returns `200` with a per-session `face_retention_outcome`.
</ParamField>

<ParamField type="GET">
  List reviews and activity log for a session.
</ParamField>

<ParamField type="POST">
  Add a review note or status change to a session.
</ParamField>

***

## Billing

<ParamField type="GET">
  Get current credit balance and auto-refill settings.
</ParamField>

```json theme={null}
{
  "balance": "142.5000",
  "auto_refill_enabled": true,
  "auto_refill_amount": "100.0000",
  "auto_refill_threshold": "10.0000"
}
```

<ParamField type="POST">
  Create a Stripe checkout session to top up credits. Minimum \$50.
</ParamField>

```json theme={null}
{
  "amount_in_dollars": 100,
  "success_url": "https://myapp.com/billing/success",
  "cancel_url": "https://myapp.com/billing/cancel"
}
```

***

## Lists (Blocklists, Allowlists & Custom)

Manage typed lists for blocklisting, allowlisting, and custom workflow conditions. See the full [Lists API documentation](/management-api/lists/overview).

<ParamField type="GET">
  List all lists for the application (blocklists, allowlists, custom).
</ParamField>

<ParamField type="POST">
  Add an entry to a list. Supports `reference_session_id` to auto-extract data from a session, and `reference_object_uuid` for traceability to transactions/users/businesses.
</ParamField>

<ParamField type="DELETE">
  Remove an entry from a list.
</ParamField>

<ParamField type="POST">
  Upload a face image to a face blocklist (base64).
</ParamField>

***

## Webhook Configuration

<ParamField type="GET">
  Get current webhook configuration including URL, version, the secret key for verifying webhook signatures, and the application's data-retention and biometric-template retention policy.
</ParamField>

```json theme={null}
{
  "webhook_url": "https://myapp.com/webhooks/didit",
  "webhook_version": "v3",
  "secret_shared_key": "whsec_a1b2c3d4e5f6...",
  "capture_method": "both",
  "data_retention_months": null,
  "face_retention_policy": "delete_with_session",
  "face_retention_days": null
}
```

<ParamField type="PATCH">
  Update webhook URL, version, or rotate the secret key. Set `rotate_secret_key: true` to generate a new webhook secret (old one immediately invalidated). Also sets the application's retention policy: `data_retention_months`, and `face_retention_policy` (`delete_with_session` default, or `retain_until_user_deleted`) together with a required finite `face_retention_days` (1-3650) when retention is enabled. See [Biometric template retention](/console/data-retention#biometric-template-retention).
</ParamField>

```json theme={null}
{
  "webhook_url": "https://myapp.com/webhooks/didit",
  "webhook_version": "v3"
}
```

***

## Complete API Endpoint Summary

| Endpoint                              | Method             | Description                                                         |
| ------------------------------------- | ------------------ | ------------------------------------------------------------------- |
| `/v3/session/`                        | POST               | Create a verification session                                       |
| `/v3/sessions/`                       | GET                | List all sessions                                                   |
| `/v3/session/{id}/decision/`          | GET                | Get session verification result                                     |
| `/v3/session/{id}/update-status/`     | PATCH              | Approve or decline a session                                        |
| `/v3/session/{id}/delete/`            | DELETE             | Delete a single session                                             |
| `/v3/sessions/delete/`                | POST               | Batch delete sessions                                               |
| `/v3/sessions/{id}/reviews/`          | GET, POST          | Session activity/reviews                                            |
| `/v3/workflows/`                      | GET, POST          | List/create workflows                                               |
| `/v3/workflows/{id}/`                 | GET, PATCH, DELETE | Workflow detail/update/delete                                       |
| `/v3/questionnaires/`                 | GET, POST          | List/create questionnaires                                          |
| `/v3/questionnaires/{id}/`            | GET, PATCH, DELETE | Questionnaire detail                                                |
| `/v3/users/`                          | GET                | List verified users                                                 |
| `/v3/users/{vendor_data}/`            | GET, PATCH         | User detail/update                                                  |
| `/v3/users/delete/`                   | POST               | Batch delete users (also purges their retained biometric templates) |
| `/v3/biometric-templates/`            | GET                | List retained biometric templates                                   |
| `/v3/biometric-templates/count/`      | GET                | Count retained biometric templates                                  |
| `/v3/biometric-templates/{id}/`       | GET, DELETE        | Template detail / purge                                             |
| `/v3/biometric-templates/delete/`     | POST               | Bulk purge templates                                                |
| `/v3/lists/`                          | GET, POST          | List all lists / create list                                        |
| `/v3/lists/{id}/`                     | GET, PATCH, DELETE | List detail / update / delete                                       |
| `/v3/lists/{id}/entries/`             | GET, POST          | List entries / add entry                                            |
| `/v3/lists/{id}/entries/{eid}/`       | DELETE             | Remove entry                                                        |
| `/v3/lists/{id}/entries/face-upload/` | POST               | Upload face to blocklist                                            |
| `/v3/webhook/`                        | GET, PATCH         | Webhook configuration (URL, secret, version) and retention policy   |
| `/v3/billing/balance/`                | GET                | Check credit balance                                                |
| `/v3/billing/top-up/`                 | POST               | Top up credits                                                      |


# Sessions Overview
Source: https://docs.didit.me/sessions-api/overview

Unified Sessions API for KYC and KYB verification. One endpoint, one workflow_id, session_kind discriminator. Pay-per-use pricing, no contracts.

This chapter of the Didit Academy user journey lesson picks up at the hosted flow versus building your own screens.

In the Academy lesson on what users see, the 5:34 chapter weighs the hosted flow against building your own screens, which is exactly the trade-off this API decides for you.

<VideoEmbed title="The hosted flow vs building your own screens — Didit Academy" />

Sessions are the unit of verification on Didit. When you start a verification, a **session** is created; when the verification finishes, the session carries the full decision payload. The same session API handles both kinds:

| Kind                                    | What it verifies         | Decision payload includes                                                                                                           |
| --------------------------------------- | ------------------------ | ----------------------------------------------------------------------------------------------------------------------------------- |
| **User Verification (KYC) session**     | An individual person     | ID verification, liveness, face match, POA, NFC, database validation, phone, email, AML, questionnaires, Device & IP Analysis       |
| **Business Verification (KYB) session** | A company / legal entity | Company registry check, key people (officers/UBOs), document verifications, phone, email, AML, questionnaires, Device & IP Analysis |

## Kind is determined by the workflow

When you [create a session](/sessions-api/create-session), you pass a `workflow_id`. The workflow's type determines whether the session is a User Verification or a Business Verification — callers do not choose separately. KYB workflows create Business Verification sessions; KYC workflows create User Verification sessions.

## `session_kind` discriminator

Every session response — from create, retrieve, list, update-status, share, and import — includes a top-level field:

```json theme={null}
{
  "session_id": "...",
  "session_kind": "user",
  ...
}
```

* `"user"` — the session is a **User Verification (KYC) session**. The response contains user-specific feature arrays.
* `"business"` — the session is a **Business Verification (KYB) session**. The response contains business-specific feature arrays.

Use this field to switch on shape on your side.

<Note>
  The enum values are the short identifiers `"user"` and `"business"` — we keep them short for API ergonomics. The full names **User Verification (KYC)** and **Business Verification (KYB)** are used throughout the documentation for clarity.
</Note>

## Feature arrays by kind

The feature arrays present in a decision depend on the kind. Fields absent from one kind simply do not appear in that response (no nulls, no placeholders):

| Feature array             | User Verification (KYC) | Business Verification (KYB) |
| ------------------------- | :---------------------: | :-------------------------: |
| `id_verifications`        |            ✅            |              —              |
| `liveness_checks`         |            ✅            |              —              |
| `face_matches`            |            ✅            |              —              |
| `nfc_verifications`       |            ✅            |              —              |
| `poa_verifications`       |            ✅            |              —              |
| `database_validations`    |            ✅            |              —              |
| `registry_checks`         |            —            |              ✅              |
| `document_verifications`  |            —            |              ✅              |
| `key_people_checks`       |            —            |              ✅              |
| `aml_screenings`          |            ✅            |              ✅              |
| `phone_verifications`     |            ✅            |              ✅              |
| `email_verifications`     |            ✅            |              ✅              |
| `questionnaire_responses` |            ✅            |              ✅              |
| `ip_analyses`             |            ✅            |              ✅              |
| `reviews`                 |            ✅            |              ✅              |
| `contact_details`         |            ✅            |              ✅              |

## Shared top-level fields

Every session (both kinds) carries these fields:

| Field                      | Description                                                                       |
| -------------------------- | --------------------------------------------------------------------------------- |
| `session_id`               | UUID of the session                                                               |
| `session_kind`             | `"user"` (User Verification / KYC) or `"business"` (Business Verification / KYB)  |
| `session_number`           | Sequential number within the application                                          |
| `session_url`              | Hosted verification URL                                                           |
| `status`                   | Overall session status — `APPROVED`, `DECLINED`, `IN_REVIEW`, `IN_PROGRESS`, etc. |
| `workflow_id`              | UUID of the workflow used                                                         |
| `vendor_data`              | Your identifier for the entity. [Learn more](/entities/vendor-data-linking)       |
| `metadata`                 | Free-form JSON you attached on creation                                           |
| `callback`                 | Optional callback URL                                                             |
| `features`                 | Comma-separated feature list the workflow runs                                    |
| `expected_details`         | Optional expected-data payload for cross-validation                               |
| `created_at`, `expires_at` | Timestamps                                                                        |

## Endpoints covered

The following endpoints all accept either kind. No separate `/v3/business-session/*` paths.

| Endpoint                                                                | Works for                                                                                           |
| ----------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| [`POST /v3/session/`](/sessions-api/create-session)                     | Creates a User Verification or Business Verification session based on workflow type                 |
| [`GET /v3/session/{id}/decision/`](/sessions-api/retrieve-session)      | Retrieves either kind — dispatches on `session_id`                                                  |
| [`GET /v3/sessions/`](/sessions-api/list-sessions)                      | Lists either kind. Use `session_kind` query parameter to filter                                     |
| [`PATCH /v3/session/{id}/update-status/`](/sessions-api/update-status)  | Updates either kind                                                                                 |
| [`DELETE /v3/session/{id}/delete/`](/sessions-api/delete-session)       | Deletes either kind                                                                                 |
| [`GET /v3/session/{id}/generate-pdf/`](/sessions-api/generate-pdf)      | Generates a PDF for either kind — routes to the User Verification or Business Verification template |
| [`POST /v3/session/{id}/share/`](/sessions-api/share-session/share)     | Share token includes `session_kind`                                                                 |
| [`POST /v3/session/import-shared/`](/sessions-api/share-session/import) | Imports either kind — preserves `session_kind` from the token                                       |

## How lookups work

User Verification and Business Verification sessions are two distinct kinds. IDs use UUIDs so collisions are impossible. When you call an endpoint with a `session_id`, Didit:

1. Looks up the id in the User Verification table first (covers most traffic).
2. Falls back to the Business Verification table if not found.
3. Returns 404 if neither table has a match.

You never need to tell the API which kind you're looking for.

## Statuses are identical

Status values are the same for both kinds: `NOT_STARTED`, `IN_PROGRESS`, `APPROVED`, `DECLINED`, `IN_REVIEW`, `ABANDONED`, `EXPIRED`, `RESUBMITTED`, `AWAITING_USER`. See [verification statuses](/integration/verification-statuses) for the full reference.

## Webhooks

Webhook events already carry a `session_kind` field so your webhook handlers can dispatch per kind:

| Event                                               | Kind            | Fires when                                                                                                 |
| --------------------------------------------------- | --------------- | ---------------------------------------------------------------------------------------------------------- |
| `status.updated`                                    | Both            | A session's status changed. Payload carries `session_kind: "user"` or `"business"`.                        |
| `data.updated`                                      | Both            | A session's data changed (feature results, registry refresh, ongoing AML). Payload carries `session_kind`. |
| `business.status.updated` / `business.data.updated` | Business entity | The linked Business entity changed.                                                                        |
| `user.status.updated` / `user.data.updated`         | User entity     | The linked User entity changed.                                                                            |

See [webhooks](/integration/webhooks) for signature verification and retry semantics, plus [KYB webhooks](/business-verification/webhooks) for the Business Verification event catalog.

## Next steps

<CardGroup>
  <Card title="Create session" icon="play" href="/sessions-api/create-session">
    Start a verification — User Verification or Business Verification.
  </Card>

  <Card title="Retrieve session" icon="file-lines" href="/sessions-api/retrieve-session">
    Fetch the decision. Works for both kinds.
  </Card>

  <Card title="List sessions" icon="list" href="/sessions-api/list-sessions">
    Filter by `session_kind`.
  </Card>

  <Card title="Update status" icon="pen-to-square" href="/sessions-api/update-status">
    Approve, decline, review, resubmit.
  </Card>

  <Card title="Generate PDF" icon="file-pdf" href="/sessions-api/generate-pdf">
    Per-kind PDF reports.
  </Card>

  <Card title="Share + import" icon="share-nodes" href="/sessions-api/share-session/overview">
    Move sessions between apps.
  </Card>
</CardGroup>


# Retrieve Session
Source: https://docs.didit.me/sessions-api/retrieve-session

GET /v3/session/{sessionId}/decision/
Retrieve the complete decision report for a verification session — the rolled-up session `status` plus one report per verification feature the workflow executed. This is the canonical read endpoint for both User Verification (KYC) and Business Verification (KYB) sessions: the same path serves both, and the top-level `session_kind` discriminator tells you which shape you received (`"user"` or `"business"`).

**Every feature report is a plural array.** V3 workflows are graphs that can run the same feature more than once, so each block (`id_verifications`, `nfc_verifications`, `liveness_checks`, `face_matches`, `poa_verifications`, `document_ai_documents`, `phone_verifications`, `email_verifications`, `aml_screenings`, `ip_analyses`, `database_validations`, `questionnaire_responses`) is a JSON array whose items each carry a `node_id` identifying the workflow graph node that produced them. Read NFC as `response.nfc_verifications[0]` — never as a singular `nfc` field. A block is `null` until the workflow has run that feature at least once; features the workflow does not include never appear with data.

**When to call.** The recommended pattern is event-driven: wait for the `status.updated` webhook that fires when the session reaches a decision (`Approved`, `Declined`, `In Review`), then call this endpoint once to fetch the full report. Polling also works — the endpoint can be called at any point in the session lifecycle and returns the data produced so far — but webhook-then-fetch is cheaper and faster. Media URLs in the response (document images, videos, PDFs) are short-lived presigned links: fetch them promptly or re-request the decision to get fresh ones, and do not persist them as long-term references.

**Statuses.** The top-level `status` is the session lifecycle status (`Not Started`, `In Progress`, `Awaiting User`, `In Review`, `Approved`, `Declined`, `Resubmitted`, `Expired`, `Kyc Expired`, `Abandoned`). Each feature item additionally carries its own feature-level `status` (`Not Finished`, `Approved`, `Declined`, `In Review`, ...). A session can be `Approved` overall while an individual feature is `In Review`, depending on the workflow's decision rules.

**Authentication and visibility.** Authenticate with the application API key in the `x-api-key` header (a console user Bearer token with the `read:sessions` permission also works). Only sessions owned by the authenticated application are visible. If your workflow restricts response attributes, non-allowed fields inside feature items are returned as `null` while `status`, `warnings`, and `node_id` are always preserved.

**Rate limits.** GET requests are limited to 600 per minute per API key. Exceeding the limit returns `429` with `Retry-After` and `X-RateLimit-*` headers.

<AgentPromptAccordion title="Retrieve Session Decision Prompt" />

## KYC and KYB support

This endpoint works for both **User Verification (KYC)** and **Business Verification (KYB)** sessions. The response always includes a top-level `session_kind` field:

* `"user"` — User Verification (KYC) session. Response carries `id_verifications`, `liveness_checks`, `face_matches`, `nfc_verifications`, `poa_verifications`, `database_validations`.
* `"business"` — Business Verification (KYB) session. Response carries `registry_checks`, `document_verifications`, `key_people_checks`.

Both kinds share `aml_screenings`, `phone_verifications`, `email_verifications`, `questionnaire_responses`, `ip_analyses`, `document_ai_documents`, `reviews`, `contact_details` — plus the common top-level fields (`session_id`, `session_number`, `session_url`, `status`, `workflow_id`, `vendor_data`, `metadata`, `callback`, `features`, `expected_details`, `created_at`, `expires_at`).

Didit resolves the `session_id` against both session types (User Verification first, Business Verification second) and returns whichever matches. UUIDs are unique per application — no ambiguity.

See [sessions overview](/sessions-api/overview) for the full matrix of kind-specific features.

## Examples

<Tabs>
  <Tab title="User Verification (KYC)">
    ```bash theme={null}
    curl https://verification.didit.me/v3/session/4c5c7f3a-1f82-4f3b-8d8e-1a8d2d2f9b7a/decision/ \
      -H "x-api-key: YOUR_API_KEY"
    ```

    **Response (truncated):**

    ```json theme={null}
    {
      "session_id": "4c5c7f3a-1f82-4f3b-8d8e-1a8d2d2f9b7a",
      "session_kind": "user",
      "session_number": 1024,
      "session_url": "https://verify.didit.me/...",
      "status": "APPROVED",
      "workflow_id": "wf_kyc_standard",
      "vendor_data": "user-42",
      "features": "ID_VERIFICATION,LIVENESS,FACE_MATCH,AML",
      "id_verifications": [
        { "node_id": "feature_ocr_1", "status": "Approved", "document_type": "Passport", "full_name": "John Doe", "...": "..." }
      ],
      "liveness_checks": [
        { "node_id": "feature_liveness_1", "status": "Approved", "score": 0.98 }
      ],
      "face_matches": [
        { "node_id": "feature_face_match_1", "status": "Approved", "score": 0.94 }
      ],
      "aml_screenings": [
        { "node_id": "feature_aml_1", "status": "Approved", "total_hits": 0, "score": 0 }
      ],
      "phone_verifications": [],
      "email_verifications": [],
      "questionnaire_responses": [],
      "ip_analyses": [],
      "reviews": [],
      "contact_details": { "email": "alex.sample@example.com", "phone": null },
      "expected_details": null,
      "metadata": {},
      "callback": null,
      "created_at": "2026-04-16T10:00:00Z",
      "expires_at": "2026-04-23T10:00:00Z"
    }
    ```
  </Tab>

  <Tab title="Business Verification (KYB)">
    ```bash theme={null}
    curl https://verification.didit.me/v3/session/bs-01HJX1.../decision/ \
      -H "x-api-key: YOUR_API_KEY"
    ```

    **Response (truncated):**

    ```json theme={null}
    {
      "session_id": "bs-01HJX1...",
      "session_kind": "business",
      "session_number": 89,
      "session_url": "https://verify.didit.me/...",
      "status": "APPROVED",
      "workflow_id": "wf_kyb_standard",
      "vendor_data": "biz-acme-001",
      "features": ["KYB_REGISTRY", "KYB_COMPANY_AML", "KYB_DOCUMENTS", "KYB_KEY_PEOPLE"],
      "registry_checks": [
        {
          "status": "Approved",
          "node_id": "feature_kyb_registry",
          "data_resolved": true,
          "company": {
            "uuid": "...",
            "node_id": "feature_kyb_registry",
            "status": "Approved",
            "registry_status": "active",
            "company_name": "Acme Corporation Limited",
            "registration_number": "12345678",
            "country_code": "GBR",
            "company_type": "Private Limited",
            "incorporation_date": "2010-05-14",
            "registered_address": "1 Main Street, London EC1A 1AA, United Kingdom",
            "tax_number": "SAMPLE-TAX-12345",
            "risk_level": "LOW",
            "verification_status": "verified",
            "is_from_registry": true,
            "fetch_status": "resolved",
            "alternative_names": ["Acme Ltd"],
            "nature_of_business": "Software publishing",
            "registered_capital": "100000 GBP",
            "website": "https://acme.example",
            "email": "alex.sample@example.com",
            "phone": "+15550101000",
            "legal_entity_identifier": "529900XXXXXXXXXXXXX",
            "financial_summary": {},
            "officers": [
              { "uuid": "...", "name": "Jane Doe", "role": "director", "nationality": "USA", "is_active": true, "kyc_status": "Approved", "kyc_session_url": "https://verify.didit.me/..." }
            ],
            "beneficial_owners": [
              { "uuid": "...", "name": "John Smith", "entity_type": "person", "roles": ["ubo"], "ownership_min_shares": 40, "ownership_max_shares": 40, "kyc_status": "Pending", "effective_ownership_percent": 40.0 }
            ],
            "addresses": [],
            "industries": [],
            "accounts": [],
            "registry_data": { },
            "user_provided_data": { },
            "confirmed_by_user_at": "2026-04-16T10:10:00Z",
            "is_editable": false
          },
          "ownership_structure": { },
          "warnings": []
        }
      ],
      "aml_screenings": [
        {
          "node_id": "feature_kyb_company_aml",
          "status": "Approved",
          "total_hits": 0,
          "score": 0,
          "entity_type": "COMPANY",
          "hits": []
        }
      ],
      "document_verifications": [
        {
          "status": "Approved",
          "node_id": "feature_kyb_documents",
          "items": [
            { "uuid": "...", "document_type": "certificate_of_incorporation", "status": "Approved", "file_url": "https://...", "ocr_data": { } }
          ],
          "groups": { "legal_presence": { "approved": 1, "pending": 0, "missing": 0 } },
          "required_groups": ["legal_presence", "ownership_structure"],
          "warnings": []
        }
      ],
      "key_people_checks": [
        {
          "status": "Approved",
          "node_id": "feature_kyb_key_people",
          "officers": [
            { "uuid": "...", "name": "Jane Doe", "role": "director", "kyc_status": "Approved", "kyc_session_url": "..." }
          ],
          "beneficial_owners": [
            { "uuid": "...", "name": "John Smith", "roles": ["ubo"], "ownership_min_shares": 40, "ownership_max_shares": 40, "kyc_status": "Pending" }
          ],
          "registry": {
            "officers": [
              { "uuid": "...", "name": "Jane Doe", "role": "director", "kyc_status": "Approved" }
            ],
            "beneficial_owners": [
              { "uuid": "...", "name": "John Smith", "roles": ["ubo"], "ownership_min_shares": 40, "kyc_status": "Pending" }
            ]
          },
          "submitted": {
            "parties": [
              { "uuid": "...", "entity_type": "person", "name": "Alice Chen", "role": "ubo", "ownership_percent": 35.0, "requires_verification": true, "kyc_session_status": "Not Started", "kyc_session_url": "https://verify.didit.me/..." }
            ]
          },
          "ubo_kyc_summary": {
            "total": 2,
            "approved": 1,
            "flagged": 0,
            "pending": 1
          },
          "warnings": []
        }
      ],
      "phone_verifications": null,
      "email_verifications": null,
      "questionnaire_responses": null,
      "ip_analyses": null,
      "reviews": [],
      "contact_details": { "email": "alex.sample@example.com", "email_lang": "en", "send_notification_emails": true, "phone": null },
      "expected_details": null,
      "metadata": {},
      "callback": null,
      "created_at": "2026-04-16T10:00:00Z",
      "expires_at": "2026-04-23T10:00:00Z"
    }
    ```
  </Tab>
</Tabs>

## Handling the response on your side

```typescript theme={null}
const res = await fetch(`${BASE}/v3/session/${sessionId}/decision/`, {
  headers: { "x-api-key": API_KEY },
});
const decision = await res.json();

switch (decision.session_kind) {
  case "user":
    handleUserDecision(decision);
    break;
  case "business":
    handleBusinessDecision(decision);
    break;
}
```

## Errors

| Status | Reason                                                                                          |
| ------ | ----------------------------------------------------------------------------------------------- |
| `404`  | No session with that `session_id` exists for this application (both session types are checked). |
| `403`  | Missing `read:sessions` privilege.                                                              |
| `401`  | Invalid API key.                                                                                |

## Related

* [Sessions overview](/sessions-api/overview) — kind discrimination and feature matrix.
* [KYB response schema](/business-verification/response-schema) — field-by-field business decision reference.
* [Verification statuses](/integration/verification-statuses) — status machine shared by both kinds.
* [Webhooks](/integration/webhooks) — subscribe to `status.updated` for both User and Business Verification sessions (filter on `session_kind`).


# Import Shared Session
Source: https://docs.didit.me/sessions-api/share-session/import

POST /v3/session/import-shared/
Redeem a share token to clone a KYC or KYB session into the calling application with a fresh `session_id`. Not idempotent — a token redeems once per receiver.

<AgentPromptAccordion title="Import Shared Session Prompt" />

## KYC and KYB support

Didit decodes the share token, reads the embedded `session_kind`, and clones the corresponding kind of session:

* `session_kind: "user"` — clones the user session plus its related identity, face, liveness, face-match, AML, location, POA, phone, email, database-validation, and log rows.
* `session_kind: "business"` — clones the business session plus its related registry check, key-people records, documents, AML screenings, phone, email, location, questionnaire, and log rows.

If the token predates the unified sharing rollout and has no `session_kind` field, Didit defaults to `"user"` for backward compatibility.

## What gets created

* A **new session** of the same kind in your application with a fresh `session_id`, `session_number`, and `session_url`.
* The new session's `shared_from_session` field points at the original session in the source application.
* The new session's status is either the original status (`trust_review: true`) or `IN_REVIEW` (`trust_review: false`).
* A new entity (User or Business) is auto-created for the `vendor_data` if one doesn't exist.

## Examples

<Tabs>
  <Tab title="Import a User Verification (KYC) session">
    ```bash theme={null}
    curl -X POST https://verification.didit.me/v3/session/import-shared/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "share_token": "eyJhbGciOiJIUzI1NiJ9...",
        "workflow_id": "your-kyc-workflow-id",
        "vendor_data": "partner-user-42",
        "trust_review": false
      }'
    ```

    **Response (201 Created):**

    ```json theme={null}
    {
      "session_id": "new-uuid",
      "session_kind": "user",
      "shared_from_session": "original-uuid",
      "status": "In Review",
      "vendor_data": "partner-user-42",
      "id_verifications": [...],
      "liveness_checks": [...],
      "...": "..."
    }
    ```
  </Tab>

  <Tab title="Import a Business Verification (KYB) session">
    ```bash theme={null}
    curl -X POST https://verification.didit.me/v3/session/import-shared/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "share_token": "eyJhbGciOiJIUzI1NiJ9...",
        "workflow_id": "your-kyb-workflow-id",
        "vendor_data": "partner-biz-acme",
        "trust_review": true
      }'
    ```

    **Response (201 Created):**

    ```json theme={null}
    {
      "session_id": "new-uuid",
      "session_kind": "business",
      "shared_from_session": "original-uuid",
      "status": "Approved",
      "vendor_data": "partner-biz-acme",
      "registry_checks": [...],
      "key_people_checks": [...],
      "document_verifications": [...],
      "...": "..."
    }
    ```
  </Tab>
</Tabs>

## `trust_review` parameter

| Value   | Effect                                                                                                                         |
| ------- | ------------------------------------------------------------------------------------------------------------------------------ |
| `true`  | The imported session preserves the original status (e.g. `APPROVED`). Use when you fully trust the sharing partner's decision. |
| `false` | The imported session lands in `IN_REVIEW` so your team can re-review before acting. Safe default for external partners.        |

## Errors

| Status | Reason                                                                         |
| ------ | ------------------------------------------------------------------------------ |
| `401`  | Share token invalid or expired.                                                |
| `403`  | Token not intended for your application, or session has already been imported. |
| `404`  | Original session no longer exists.                                             |
| `404`  | `workflow_id` not found in your application.                                   |

## Idempotency

Importing the same `share_token` twice is rejected with `403` — the duplicate-import check runs against both user and business tables depending on `session_kind`.

## Related

* [Share session](/sessions-api/share-session/share)
* [Reusable KYC guide](/core-technology/reusable-kyc/share-kyc-via-api)
* [Sessions overview](/sessions-api/overview)


# Share Session (Reusable KYC)
Source: https://docs.didit.me/sessions-api/share-session/overview

Reusable KYC and KYB — share verified sessions across trusted partners with time-limited tokens. Skip re-verification, cut friction, save costs.

The Share Session API enables **Reusable KYC and KYB** — securely sharing verified session data between trusted partner organizations. Works for both User Verification (KYC) and Business Verification (KYB) sessions. The share token encodes the `session_kind` so the receiving application reconstructs the same kind when importing.

## Endpoints

<CardGroup>
  <Card title="Share Session" icon="share-nodes" href="/sessions-api/share-session/share">
    `POST /v3/session/{sessionId}/share/` — Generate a time-limited share token for a verified session.
  </Card>

  <Card title="Import Shared Session" icon="download" href="/sessions-api/share-session/import">
    `POST /v3/session/import-shared/` — Import a session shared by a partner using a share token.
  </Card>
</CardGroup>

## How it works

<Steps>
  <Step title="Partner A shares a session">
    After a user completes verification on Partner A's platform, Partner A calls **Share Session** with the session ID and the target partner's application ID. Didit returns a time-limited `share_token`.
  </Step>

  <Step title="Share token is sent to Partner B">
    Partner A sends the `share_token` to Partner B through their own secure channel (API call, webhook, etc.).
  </Step>

  <Step title="Partner B imports the session">
    Partner B calls **Import Shared Session** with the `share_token`. Didit creates a copy of the verified session in Partner B's account with full verification data.
  </Step>
</Steps>

## Requirements

| Requirement                | Details                                                                                    |
| -------------------------- | ------------------------------------------------------------------------------------------ |
| **Session status**         | Only finished sessions (`"Approved"`, `"Declined"`, `"In Review"`) can be shared           |
| **Partner application ID** | The target partner's application ID (found in Business Console settings)                   |
| **Token TTL**              | Configurable from 60 seconds to 86,400 seconds (24 hours). Default: 3,600 seconds (1 hour) |
| **Authentication**         | Both partners must authenticate with their own API keys                                    |

## Use cases

* **Banking → Fintech**: A user verified by a bank can access a fintech partner without re-verifying
* **Marketplace → Payment provider**: Sellers verified on a marketplace can onboard to the payment provider instantly
* **Insurance → Healthcare**: Cross-industry verification sharing between trusted partners
* **Group companies**: Share verification data across multiple applications within the same organization

<Note>
  Learn more about the Reusable KYC feature in the [Share KYC via API guide](/core-technology/reusable-kyc/share-kyc-via-api).
</Note>


# Share Session
Source: https://docs.didit.me/sessions-api/share-session/share

POST /v3/session/{sessionId}/share/
Mint a short-lived JWT that lets a specific Didit application import this finished session. Pair with `POST /v3/session/import-shared/`.

<AgentPromptAccordion title="Share Session Prompt" />

## KYC and KYB support

Works for both **User Verification (KYC)** and **Business Verification (KYB)** sessions. Didit resolves the `session_id` against both session types and generates a JWT share token that includes:

```json theme={null}
{
  "session_id": "...",
  "session_kind": "user" | "business",
  "from_application_id": "...",
  "for_application_id": "...",
  "iat": ...,
  "exp": ...
}
```

When the receiving partner imports the token, Didit clones the corresponding kind of session (KYC or KYB) with its relations.

## Requirements

* Session must be in a **finished** status (`APPROVED`, `DECLINED`, `IN_REVIEW`).
* You must have the `write:sessions` privilege.
* The `for_application_id` must be a valid Didit application (usually a partner's application).

## Examples

<Tabs>
  <Tab title="Share a User Verification (KYC) session">
    ```bash theme={null}
    curl -X POST https://verification.didit.me/v3/session/4c5c7f3a-.../share/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "for_application_id": "partner-app-uuid",
        "ttl_in_seconds": 3600
      }'
    ```

    **Response:**

    ```json theme={null}
    {
      "share_token": "eyJhbGciOiJIUzI1NiJ9...",
      "for_application_id": "partner-app-uuid",
      "session_kind": "user"
    }
    ```
  </Tab>

  <Tab title="Share a Business Verification (KYB) session">
    ```bash theme={null}
    curl -X POST https://verification.didit.me/v3/session/bs-01HJX1.../share/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "for_application_id": "partner-app-uuid",
        "ttl_in_seconds": 7200
      }'
    ```

    **Response:**

    ```json theme={null}
    {
      "share_token": "eyJhbGciOiJIUzI1NiJ9...",
      "for_application_id": "partner-app-uuid",
      "session_kind": "business"
    }
    ```
  </Tab>
</Tabs>

## TTL bounds

| Parameter        | Min | Max   | Default |
| ---------------- | --- | ----- | ------- |
| `ttl_in_seconds` | 60  | 86400 | 3600    |

## Related

* [Import shared session](/sessions-api/share-session/import)
* [Reusable KYC guide](/core-technology/reusable-kyc/share-kyc-via-api)
* [Sessions overview](/sessions-api/overview)


# Update AML Hit Status
Source: https://docs.didit.me/sessions-api/update-aml-hit-status

PATCH /v3/session/{sessionId}/update-aml-hit-status/
Mark individual AML screening hits as Confirmed Match, False Positive, or Inconclusive — single or in bulk — straight from the API.

<AgentPromptAccordion title="Update AML Hit Status Prompt" />

## What this does

AML screening returns a list of **hits** — potential matches against sanction lists, PEP databases, watchlists, and adverse media. Each hit has a `review_status` (its disposition) that starts as `Unreviewed` or `False Positive` depending on the match score. This endpoint lets your team (or your automation) record a decision on each hit — without changing the overall session decision.

Find the hits and their IDs in the [session decision](/sessions-api/retrieve-session) — the AML check's `hits` array, where each hit's `id` is the `hit_id` you pass here.

## Review statuses

| `review_status`   | Meaning                                                                    |
| ----------------- | -------------------------------------------------------------------------- |
| `Unreviewed`      | Default for hits at or above the match threshold — still needs a decision. |
| `Confirmed Match` | A true match for the screened individual / entity.                         |
| `False Positive`  | Not the same entity. Default for hits below the match threshold.           |
| `Inconclusive`    | Could not be determined.                                                   |

<Note>
  Reviewer decisions are **preserved across ongoing-monitoring re-screens** — a hit you mark `False Positive` keeps that status when the provider re-screens the entity.
</Note>

## Update a single hit

**`PATCH /v3/session/{sessionId}/update-aml-hit-status/`**

```bash theme={null}
curl -X PATCH https://verification.didit.me/v3/session/4c5c7f3a-.../update-aml-hit-status/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hit_id": "abc123",
    "review_status": "False Positive"
  }'
```

For a session with multiple AML checks (graph workflows), add `?node_id=feature_aml_1` to the URL or include `"node_id"` in the body to target a specific check.

## Update many hits at once

**`PATCH /v3/session/{sessionId}/bulk-update-aml-hit-status/`**

Pass `hit_updates`, a list of `{ hit_id, review_status }` pairs. The operation is **all-or-nothing**: if any `hit_id` is not found, the request returns `404` and no hit is changed.

```bash theme={null}
curl -X PATCH https://verification.didit.me/v3/session/4c5c7f3a-.../bulk-update-aml-hit-status/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "hit_updates": [
      { "hit_id": "abc123", "review_status": "Confirmed Match" },
      { "hit_id": "def456", "review_status": "False Positive" }
    ]
  }'
```

A successful bulk call fires a single `data.updated` webhook and records one activity entry covering all the changes.

## What happens after an update

* **Webhook** — a `data.updated` event fires on the session.
* **Audit trail** — the change is recorded on the session's review trail with the actor (API key or user), visible in the console's activity timeline.
* **Overall AML step status is untouched** — changing a hit's disposition does not, by itself, change the AML step status or the session decision. To change the AML **step** status (`Approved` / `Declined` / `In Review`), use [update-feature-status](/sessions-api/update-feature-status). To change the **session** decision, use [update-status](/sessions-api/update-status).

## KYC and KYB support

Works for both **User Verification (KYC)** and **Business Verification (KYB)** sessions — Didit resolves the `sessionId` across both. For KYB, AML screening runs on the company and its key people; each AML check exposes its own hits.

## Permission

Requires the `write:sessions` privilege, with either a client API key (`x-api-key`) or a user authorization header.

## Errors

| Status | Meaning                                                                                                  |
| ------ | -------------------------------------------------------------------------------------------------------- |
| `400`  | `review_status` is not a valid value, `hit_id` is empty, or `hit_updates` is empty.                      |
| `403`  | Missing/invalid credentials, or the caller lacks `write:sessions`.                                       |
| `404`  | Session not found, the session has no AML check, or a `hit_id` was not found (bulk: nothing is changed). |

## Related

* [Update feature status](/sessions-api/update-feature-status) — change the AML **step** status (or any other step).
* [Update session status](/sessions-api/update-status) — change the overall session decision.
* [Retrieve session](/sessions-api/retrieve-session) — read the AML `hits` and their IDs.
* [AML screening](/standalone-apis/aml-screening) — how screening and scoring work.


# Update Session Data
Source: https://docs.didit.me/sessions-api/update-data

Correct OCR-extracted KYC, POA, or KYB registry fields on existing sessions. Three PATCH endpoints, partial updates, webhook-emitting. Pay-per-call.

<AgentPromptAccordion title="Update Session Data Prompt" />

Sometimes OCR misreads an ID, a utility bill, or a registry entry. Didit exposes three PATCH endpoints you can call to correct the extracted data without having to rerun the whole verification.

| Endpoint                                                                             | Use when                                                                                                             |
| ------------------------------------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------- |
| [`PATCH /v3/session/{id}/update-data/`](#update-kyc-identity-data)                   | Fix values extracted from an ID document on a **User Verification (KYC)** session                                    |
| [`PATCH /v3/session/{id}/update-poa-data/`](#update-proof-of-address-poa-data)       | Fix values extracted from a utility bill / bank statement / lease agreement on a **User Verification (KYC)** session |
| [`PATCH /v3/session/{id}/kyb/{company_uuid}/update-data/`](#update-kyb-company-data) | Fix registry-extracted fields on a **Business Verification (KYB)** session                                           |
| [`PATCH /v3/session/{id}/kyb/parties/{party_uuid}/`](#skip-a-key-people-party)       | Exempt a Key People party from verification when it can no longer complete its own check                             |

All four accept your **client API key** or a **user authorization header**, and all four emit a `data.updated` webhook on success so your system and downstream analytics stay in sync.

## Shared requirements

* **Authorization** — client API key (standard `x-api-key` / `Authorization` bearer) or user-auth token.
* **Privilege** —
  * KYC and POA: `write:sessions`
  * KYB company and Key People party: `write:businesses`
* **Session status** (KYC / POA only) — must be one of `APPROVED`, `DECLINED`, `IN_REVIEW`, or `KYC_EXPIRED`. Sessions that haven't reached a reviewable state cannot be patched. KYB company updates have no status gate.
* **Feature record must exist** — you can only patch KYC fields if the session captured a KYC, POA fields if it captured a POA, and KYB company fields if the session has a registry check.
* **Partial updates** — only fields you include are changed. Omit a field to leave it as-is. Send `null` to clear an `extra_fields` key.
* **Webhooks** — a successful update fires `data.updated` with `session_kind: "user"` or `"business"`, and the session's audit trail records which specific fields changed and who changed them.

## Update KYC identity data

**`PATCH /v3/session/{sessionId}/update-data/`**

Patch any field extracted from the ID document. Supports graph-based multi-instance workflows via an optional `node_id` query parameter or body field — target a specific KYC record when a single session has multiple KYC steps.

### Mutable fields

| Field                               | Notes                                                                                                        |
| ----------------------------------- | ------------------------------------------------------------------------------------------------------------ |
| `document_type`                     | ISO document code — `P` (passport), `ID`, `DL`, `RP`.                                                        |
| `document_number`                   | The printed document number.                                                                                 |
| `personal_number`                   | Personal / tax ID number when printed on the document.                                                       |
| `date_of_birth`                     | ISO 8601 date.                                                                                               |
| `date_of_issue` / `expiration_date` | ISO 8601 dates.                                                                                              |
| `issuing_state`                     | Issuing country, ISO 3166-1 alpha-3.                                                                         |
| `first_name` / `last_name`          | `full_name` is auto-recomputed from these two.                                                               |
| `gender`                            | `M`, `F`, or `X` when present.                                                                               |
| `nationality`                       | Free text.                                                                                                   |
| `marital_status`                    | Free text.                                                                                                   |
| `place_of_birth`                    | Free text.                                                                                                   |
| `address`                           | Free-text address from the document. Triggers re-geocoding.                                                  |
| `parsed_address`                    | Structured address — see the nested shape below.                                                             |
| `extra_fields`                      | Arbitrary extra fields from the ID (e.g. `blood_group`, `municipality`). Send `null` for a key to remove it. |

`parsed_address` only accepts these nested keys: `address_type`, `city`, `region`, `street_1`, `street_2`, `postal_code`, `country` (ISO 3166-1 **alpha-2**).

### Example

```bash theme={null}
curl -X PATCH "https://verification.didit.me/v3/session/4c5c7f3a.../update-data/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "first_name": "John",
    "last_name": "Doe",
    "date_of_birth": "1990-01-01",
    "issuing_state": "ESP",
    "extra_fields": { "municipality": "Madrid" }
  }'
```

For a multi-instance graph workflow, add `?node_id=feature_ocr_2` to the URL (or pass `"node_id": "feature_ocr_2"` in the body) to target a specific KYC record.

## Update Proof of Address (POA) data

**`PATCH /v3/session/{sessionId}/update-poa-data/`**

Patch fields extracted from a proof-of-address document. Same status gates and privilege as KYC updates. Also supports `node_id` for multi-instance workflows.

### Mutable fields

| Field                | Notes                                                                                                                                                                                                                                             |
| -------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `issuing_state`      | Country that issued the document, ISO 3166-1 alpha-3.                                                                                                                                                                                             |
| `document_type`      | e.g. `utility_bill`, `bank_statement`, `lease_agreement`.                                                                                                                                                                                         |
| `document_language`  | ISO 639-1 language of the document.                                                                                                                                                                                                               |
| `issuer`             | Utility company, bank, landlord, etc.                                                                                                                                                                                                             |
| `issue_date`         | ISO 8601 date.                                                                                                                                                                                                                                    |
| `poa_address`        | Address as printed on the document (free-text). Triggers re-geocoding.                                                                                                                                                                            |
| `name_on_document`   | Full name printed on the document.                                                                                                                                                                                                                |
| `poa_parsed_address` | Structured address — same nested shape as KYC `parsed_address`.                                                                                                                                                                                   |
| `extra_fields`       | Document-specific fields — bank details (`bank_account_number`, `bank_iban`, `bank_sort_code`, `bank_routing_number`, `bank_swift_bic`, `bank_branch_name`, `bank_branch_address`), `document_phone_number`, `additional_names` (list or `null`). |

### Example

```bash theme={null}
curl -X PATCH "https://verification.didit.me/v3/session/4c5c7f3a.../update-poa-data/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "utility_bill",
    "issuer": "Iberdrola",
    "issue_date": "2026-03-15",
    "name_on_document": "Jane Doe",
    "poa_parsed_address": {
      "street_1": "Calle Mayor 10",
      "city": "Madrid",
      "postal_code": "28013",
      "country": "ES"
    }
  }'
```

## Update KYB company data

**`PATCH /v3/session/{sessionId}/kyb/{companyUuid}/update-data/`**

Correct registry-extracted fields on a KYB company. The endpoint edits **both** the canonical company columns and the raw `registry_data` snapshot, so the "Extracted from Registry" view in the console reflects your corrections. `user_provided_data` — what the end user confirmed in the hosted flow — is not modified. `last_console_edit_at` is stamped, and a `data.updated` webhook fires with `trigger: "console_registry_edit"`.

### Requirements

* **Privilege** — `write:businesses` (different from the KYC / POA privilege).
* The `companyUuid` in the URL must belong to the given `sessionId`, otherwise you get a 404.
* No session status gate — KYB company data can be corrected at any time.

### Mutable fields

| Field                                                           | Notes                                                                                |
| --------------------------------------------------------------- | ------------------------------------------------------------------------------------ |
| `company_name`                                                  | Legal name.                                                                          |
| `registration_number`                                           | Official registration number.                                                        |
| `country_code`                                                  | Country of incorporation, ISO 3166-1 alpha-3.                                        |
| `incorporation_date` / `registration_date` / `dissolution_date` | ISO 8601 dates.                                                                      |
| `tax_number`                                                    | Tax identification number.                                                           |
| `legal_address`                                                 | Alias for `registered_address` — lands on the canonical `registered_address` column. |
| `company_type`                                                  | Ltd / LLC / PLC / SA / GmbH / SL etc.                                                |
| `registry_status`                                               | `active`, `dissolved`, `struck_off`, `inactive`, etc.                                |
| `verification_status`                                           | `verified`, `failed`, `unknown`.                                                     |
| `alternative_names`                                             | Trade names, former names, DBAs.                                                     |
| `nature_of_business`                                            | Short description.                                                                   |
| `registered_capital`                                            | Authorized / issued capital.                                                         |
| `website`, `email`, `phone`                                     | Contact details.                                                                     |
| `legal_entity_identifier`                                       | LEI.                                                                                 |
| `location_of_registration`                                      | City / subdivision.                                                                  |
| `control_scheme`                                                | Governance scheme when registry exposes it.                                          |

Any field you omit is left untouched. Any field you send is written to the canonical column (when one exists) and merged into the raw `registry_data` JSON. Dates are serialized as ISO 8601 strings when merged into `registry_data`.

### Example

```bash theme={null}
curl -X PATCH "https://verification.didit.me/v3/session/bs-01HJX1.../kyb/f7a9c1b2-4e6d.../update-data/" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "company_name": "Acme Corporation Limited",
    "registration_number": "12345678",
    "registry_status": "active",
    "legal_address": "1 Main Street, London EC1A 1AA, United Kingdom",
    "alternative_names": "Acme Ltd, Acme Group"
  }'
```

Response: the full KYB company object — same shape as `registry_checks[].company` in the [session decision](/sessions-api/retrieve-session#business-verification-kyb).

## Skip a Key People party

**`PATCH /v3/session/{sessionId}/kyb/parties/{partyUuid}/`**

Exempt a Key People party from verification - the escape hatch for a party that can never finish its own check. The usual cause is a deleted child session: once the individual KYC handed to a UBO or director is deleted, its status is frozen and it can never settle, so the KYB has nothing left that could move it out of `Awaiting User`. Skipping the party drops it out of the Key People aggregation, the check is recomputed on the spot, and the session can settle and be approved or declined.

### Requirements

* **Privilege** - `write:businesses`.
* The `partyUuid` in the URL must belong to the given `sessionId`, otherwise you get a 404.
* **Not gated by `allow_skip`.** That role setting limits what the applicant may skip while filling in the hosted Key People screen; this endpoint is the operator override, so it works even on roles the applicant could not have skipped.

### Body

| Field        | Type    | Notes                                                                                             |
| ------------ | ------- | ------------------------------------------------------------------------------------------------- |
| `is_skipped` | boolean | `true` exempts the party; `false` puts it back in scope and the check goes back to waiting on it. |

`requires_verification` is deliberately left untouched, so an overridden party reads as `requires_verification: true` **and** `is_skipped: true` - the record still shows that the rules asked for a check.

### Example

```bash theme={null}
curl -X PATCH "https://verification.didit.me/v3/session/bs-01HJX1.../kyb/parties/0a3f1e2c-7c2f.../" \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{ "is_skipped": true }'
```

Response: the updated party - the same shape as an entry of `key_people_checks[].submitted.parties[]` in the [session decision](/business-verification/response-schema#key_people_checks).

A `data.updated` webhook fires with `trigger: "console_key_people_skip"`.

<Note>
  A party whose child session was deleted is flagged in the decision payload with
  `kyc_session_deleted: true` (or `kyb_sub_session_deleted: true` for corporate
  parties), and its `kyc_session_url` / `kyb_sub_session_url` is returned as
  `null` because the link no longer resolves. Deleting a child session never
  approves the party on its own - the Key People check drops to `In Review` so a
  human makes the call.
</Note>

## What happens after an update

* **Webhook** — `data.updated` fires on the session, with the session's `session_kind` in the payload (`"user"` or `"business"`). Subscribe once at the destination level and route on `session_kind`.
* **Audit trail** — the session records exactly which fields changed, the previous and new values, and (for user-auth calls) the actor email. Visible in the console's Events tab.
* **Address re-geocoding** — for KYC and POA updates that change `address` / `poa_address`, Didit re-runs geocoding in the background. Failures are swallowed so the update never fails because of a geocoding issue.
* **AML re-evaluation** — KYC updates that change name / DOB / nationality can re-trigger AML screening if AML hadn't finished on the session. Results surface on the session decision.

## When not to use these endpoints

* **Rerunning the whole verification** — if the customer has to re-take their ID photo or re-upload a document, use [update-status](/sessions-api/update-status) to move the session to `Resubmitted` instead.
* **Changing profile fields on the User or Business entity** — use [`PATCH /v3/users/{vendor_data}/`](/management-api/users/update) or [`PATCH /v3/businesses/{vendor_data}/`](/management-api/businesses/update) — those endpoints update entity-level data, not session-level data.
* **Editing Key People details** - there's no public API to patch a party's name, roles, or ownership; that data is submitted through the hosted flow. The one patchable field is `is_skipped` (see [Skip a Key People party](#skip-a-key-people-party)).

## Errors

| Status | Meaning                                                                                                                                                                          |
| ------ | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `401`  | Missing or invalid credentials.                                                                                                                                                  |
| `403`  | Caller lacks the required privilege (`write:sessions` or `write:businesses`).                                                                                                    |
| `404`  | Session not found, or the session doesn't carry the record you're patching (no KYC, no POA, no matching company, no matching party, or a party that belongs to another session). |
| `400`  | Validation error — invalid country code, unknown `parsed_address` key, `extra_fields` not an object, etc.                                                                        |

## Next steps

<CardGroup>
  <Card title="Retrieve session" icon="file-lines" href="/sessions-api/retrieve-session">
    Fetch the full decision to see the updated fields.
  </Card>

  <Card title="Update status" icon="pen-to-square" href="/sessions-api/update-status">
    Approve, decline, or re-open a session after a data correction.
  </Card>

  <Card title="Webhooks" icon="bolt" href="/integration/webhooks">
    Subscribe to `data.updated` events.
  </Card>
</CardGroup>


# Update Feature Status
Source: https://docs.didit.me/sessions-api/update-feature-status

PATCH /v3/session/{sessionId}/features/{nodeId}/update-status/
Approve, decline, or move a single verification step (OCR, Liveness, Face Match, AML, POA, Phone…) to review without changing the overall session decision.

<AgentPromptAccordion title="Update Feature Status Prompt" />

## What this does

A verification session is made up of individual **features** (steps) — ID/OCR, Liveness, Face Match, AML, Proof of Address, Phone, and so on. This endpoint lets you set the status of **one** of those steps — `Approved`, `Declined`, or `In Review` — **without** changing the overall session decision.

Use [update-status](/sessions-api/update-status) when you want to approve, decline, or re-open the whole session. Use **this** endpoint when you only want to record a decision on a single step (for example, mark the Face Match step as `Declined` for your own review workflow while leaving the session in its current state).

## Targeting a step with `node_id`

In graph-based workflows each step has a `node_id` (for example `feature_ocr_1`, `feature_liveness_1`, `feature_aml_1`). You can find these in the [session decision](/sessions-api/retrieve-session) — each feature in a V3 decision carries its `node_id`.

For **non-graph (single-step) workflows** the underlying feature has no node ID. Pass the literal value `default` as the `nodeId` to target it.

## KYC and KYB support

Works identically for **User Verification (KYC)** and **Business Verification (KYB)** sessions — Didit resolves the `sessionId` across both. Supported step types include ID/OCR, Liveness, Face Match, NFC, AML, Proof of Address, Phone, Email, Database Validation, Questionnaire, and the KYB registry / documents / key-people checks.

<Note>
  Standalone API sessions (those created through the standalone verification APIs, `session_type = API`) cannot have individual feature statuses changed — the endpoint returns `400`.
</Note>

## Examples

<Tabs>
  <Tab title="Approve a step">
    ```bash theme={null}
    curl -X PATCH https://verification.didit.me/v3/session/4c5c7f3a-.../features/feature_ocr_1/update-status/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "new_status": "Approved",
        "comment": "Document manually verified by compliance"
      }'
    ```
  </Tab>

  <Tab title="Decline the Face Match step">
    ```bash theme={null}
    curl -X PATCH https://verification.didit.me/v3/session/4c5c7f3a-.../features/feature_face_match/update-status/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "new_status": "Declined"
      }'
    ```
  </Tab>

  <Tab title="Single-step workflow (default node)">
    ```bash theme={null}
    curl -X PATCH https://verification.didit.me/v3/session/4c5c7f3a-.../features/default/update-status/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "new_status": "In Review"
      }'
    ```
  </Tab>
</Tabs>

## What happens after an update

* **Webhook** — a `data.updated` event fires on the session so your systems and analytics stay in sync.
* **Audit trail** — the change is recorded on the session's review trail with the actor (API key or user) and your optional `comment`, visible in the console's activity timeline.
* **Overall session status is untouched** — to also change the final decision, call [update-status](/sessions-api/update-status) separately.

## Permission

Requires the `write:sessions` privilege, with either a client API key (`x-api-key`) or a user authorization header.

## Related

* [Update session status](/sessions-api/update-status) — change the overall session decision.
* [Update AML hit status](/sessions-api/update-aml-hit-status) — review individual AML matches.
* [Retrieve session](/sessions-api/retrieve-session) — fetch the decision (and each feature's `node_id`).
* [Webhooks](/integration/webhooks) — subscribe to `data.updated`.


# Update Session Status
Source: https://docs.didit.me/sessions-api/update-status

PATCH /v3/session/{sessionId}/update-status/
Manually override the final decision of a KYC or KYB verification session. Set `new_status` to `Approved` or `Declined` to record a manual decision, or to `Resubmitted` to clear specific verification steps and let the user redo them through the same verification URL. The endpoint accepts both user (KYC) and business (KYB) session IDs.

Call it once a session has reached a reviewable state: the current status must be `Approved`, `Declined`, `In Review`, `Kyc Expired`, `Abandoned`, or `Resubmitted`. Sessions that are still `Not Started`, `In Progress`, or `Awaiting User`, or that ended as `Expired`, return `400`. The new status must differ from the current one, and your API key's organization needs the `write:sessions` permission. The eligible-state check runs before body validation, so an ineligible session returns the `Wrong Current Status` error even when the payload is also invalid.

For `Resubmitted`, pass `nodes_to_resubmit` to choose which workflow steps the user must redo, or omit it to auto-select existing feature attempts in a resubmittable state (`Declined`, `In Review`, `Not Finished`, `Expired`). Never-attempted features are not auto-selected — list them explicitly in `nodes_to_resubmit`, or the request returns `400` when no recorded attempt needs resubmission. Captured data for the selected steps is deleted, the steps are reordered to match the workflow graph, the session's expiration window restarts, and the original verification URL becomes usable again. Backend-only steps (`AML`, `DATABASE_VALIDATION`, `IP_ANALYSIS`) at the head of the list run immediately without user interaction; if every resubmitted step is backend-only, the session re-finalizes within the same request. `KYB_REGISTRY` and `KYB_KEY_PEOPLE` cannot be resubmitted directly — resubmit the relevant child KYC sessions instead and the parent business session recomputes automatically.

Every successful call fires the `status.updated` [webhook](/integration/webhooks) once the change commits and appends an activity entry — with actor attribution and your `comment` — to the session's `reviews`, visible in [Get Decision](#get-/v3/session/-sessionId-/decision/) and in the console activity timeline. The user-profile aggregates linked to the session's `vendor_data` update as well. Declining disables ongoing AML monitoring for the session; re-approving re-enables it (from `Resubmitted`, `Declined`, or `Kyc Expired`) when the workflow has monitoring turned on. Approving or declining a child KYC that belongs to a KYB key-people check recomputes the parent business session's status. Set `send_email: true` (with `email_address`) to notify the user: a status notice for `Approved`/`Declined`, or a resubmission email containing the verification link and per-step reasons for `Resubmitted`.

The operation is intentionally not repeatable with the same value: re-sending the current status returns `400` (`The new status is the same as the current status.`), so accidental double-submissions are harmless. Authentication and permission failures both return `403` — this API never responds `401`.

<AgentPromptAccordion title="Update Session Status Prompt" />

## KYC and KYB support

This endpoint works identically for **User Verification (KYC)** and **Business Verification (KYB)** sessions. Didit resolves the `session_id` against both session types; status-transition validation is the same for both (the same enum of statuses applies to both).

The response includes `session_kind` so your downstream logic can switch on the outcome kind.

## Allowed transitions

You can move a session to `APPROVED`, `DECLINED`, `IN_REVIEW`, or `RESUBMITTED`. The session's current status must be one of: `APPROVED`, `DECLINED`, `IN_REVIEW`, `KYC_EXPIRED`, `ABANDONED`, or `RESUBMITTED` — otherwise the API returns a validation error.

A resubmit whose `nodes_to_resubmit` contain only backend-only features (`AML`, `DATABASE_VALIDATION`, `IP_ANALYSIS`) executes automatically and returns the session to a decided status with no user interaction.
Repeating such a resubmit within 30 seconds returns `429 Too Many Requests` with a `Retry-After` header, since an immediate repeat cannot produce a different result.
Do not auto-resubmit from a webhook handler whenever you receive an `In Review` status - review the finding or change the underlying data first.

## Examples

<Tabs>
  <Tab title="Approve a User Verification (KYC) session">
    ```bash theme={null}
    curl -X PATCH https://verification.didit.me/v3/session/4c5c7f3a-.../update-status/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "new_status": "Approved",
        "comment": "Cleared after manual review by compliance team"
      }'
    ```
  </Tab>

  <Tab title="Decline a Business Verification (KYB) session">
    ```bash theme={null}
    curl -X PATCH https://verification.didit.me/v3/session/bs-01HJX1.../update-status/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "new_status": "Declined",
        "comment": "Sanctioned subsidiary detected in ownership chain"
      }'
    ```
  </Tab>

  <Tab title="Request resubmission">
    ```bash theme={null}
    curl -X PATCH https://verification.didit.me/v3/session/.../update-status/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "new_status": "Resubmitted",
        "nodes_to_resubmit": [
          { "node_id": "feature_poa_1", "feature": "POA" }
        ],
        "comment": "Please upload a clearer proof of address",
        "send_email": true
      }'
    ```
  </Tab>
</Tabs>

## Permission

Requires the `write:sessions` privilege. The same privilege covers both kinds.

## Related

* [Verification statuses](/integration/verification-statuses) — status-machine reference.
* [Retrieve session](/sessions-api/retrieve-session) — fetch the decision after updating.
* [Sessions overview](/sessions-api/overview) — kind discrimination.


# Age Estimation API
Source: https://docs.didit.me/standalone-apis/age-estimation

POST /v3/age-estimation/
Estimate a person's age from a single face photo and run a passive liveness check in the same call — returns the model-predicted `age_estimation` (in years), a liveness `score` (0–100), and an `Approved`/`Declined` `status`. The age is **model-predicted from the face, not verified against a document** — use it for age gates and low-friction checks, not as legal proof of age.

**How it works.** The image is analyzed for faces (set `rotate_image=true` if captures may be sideways or upside down); each detected face gets an estimated age, and the largest face in the frame drives `age_estimation`. In parallel, a passive liveness model scores whether the photo shows a live person (no user challenge required) and detects presentation attacks (photos of photos, screens, masks). Submit one clear, front-facing, well-lit face per image for best results.

**Decision logic.** Any warning declines: `status` is `Approved` only when the `warnings` array is empty. A liveness `score` at or below `face_liveness_score_decline_threshold` (default `30`) adds `LOW_LIVENESS_SCORE`; a detected attack adds `LIVENESS_FACE_ATTACK`; no face found by the liveness model adds `NO_FACE_DETECTED`; no estimable face age adds `AGE_NOT_DETECTED` (`age_estimation` is `null`); an estimated age below `age_estimation_decline_threshold` (default `18`) adds `AGE_BELOW_MINIMUM`. Borderline ages near your threshold deserve a fallback to document-based verification — the model's error grows for faces close to the limit.

**Billing.** Each `200` response consumes one Age Estimation API credit (standalone APIs have no free tier). When the organization's balance cannot cover the call, the endpoint returns `403` with the not-enough-credits error before any image processing.

**Session persistence (`save_api_request`, default `true`).** When `true`, the call is persisted as an API-type session: it appears in the Business Console, the returned `request_id` is a real session id you can pass to `GET /v3/session/{sessionId}/decision/` (the result is exposed there in `liveness_checks[]`, with `features: ["AGE_ESTIMATION"]`), the face crop and reference image are stored, the face embedding is added to your application's face index (used by face search and duplicate detection), and a `status.updated` webhook is emitted. When `false`, nothing is stored and `request_id` is a one-off correlation UUID that cannot be looked up later.

**Sandbox.** Sandbox API keys skip all processing and billing: after request validation (malformed input still returns `400`), the endpoint returns a static `Approved` mock payload (`age_estimation: 30`, no warnings), no session is persisted, and no credits are consumed.

**Authentication.** Send your application's API key in the `x-api-key` header. Missing or invalid credentials return `403` (`{"detail": "You do not have permission to perform this action."}`) — this API never returns `401`.

**Rate limit.** Shared write budget of 300 requests/min per API key across all POST/PATCH/DELETE endpoints; exceeding it returns `429`.



# AML Screening API
Source: https://docs.didit.me/standalone-apis/aml-screening

POST /v3/aml/
Screen a person or company against PEP, sanctions, warning/watchlist, and adverse-media datasets in one call.

**Two-score model.** Each hit carries a `match_score` (0–100, identity confidence) and a `risk_score` (0–100, entity risk). Hits whose `match_score` is below `aml_match_score_threshold` (default **93**) are tagged `review_status: "False Positive"` and ignored for risk purposes; the highest `risk_score` among the remaining hits becomes `aml.score`. The final `aml.status` follows your thresholds: `score` > `aml_score_review_threshold` (default **100**) → `Declined`; `score` > `aml_score_approve_threshold` (default **80**) → `In Review`; otherwise `Approved`. Whenever `score` is non-zero and ≥ the approve threshold a `POSSIBLE_MATCH_FOUND` warning is added (a score of exactly 0 never warns).

**Match-score weights.** `aml_name_weight` + `aml_dob_weight` + `aml_country_weight` must sum to exactly 100 (defaults 60/25/15). Components missing from the request are re-normalized away; a matching `document_number` acts as a golden key that overrides `match_score` to 100.

**Latency.** Plain screenings typically complete in a few seconds. With `include_adverse_media=true` the API waits for adverse-media enrichment (an initial ~5 s pause plus up to ~25 s of polling) — configure a client timeout of **at least 60 seconds**.

**Persistence.** `save_api_request` defaults to **true**: the screening is stored as a session (`request_id` works with `GET /v3/session/{sessionId}/decision/`), it appears in the console, a `status.updated` webhook fires, and hit review statuses can be updated later. With `save_api_request=false` nothing is stored and `request_id` is a transient correlation id. `include_ongoing_monitoring=true` keeps re-screening the profile and requires `save_api_request=true` (enforced with a `400`).

**Idempotency.** Send an `Idempotency-Key` header when retrying after a timeout or transient error. The key is scoped to your application and the exact request body. The first completed request stores its response; later identical retries return that same response and do not run or bill another AML screening. If the original request is still running, retry later with the same key. If the same key is reused with a different body, the API returns `409`.

**Billing.** One AML API credit is charged after the first successful screening. Replayed idempotent responses are not charged again; an insufficient balance returns `403` before any new screening happens.

**Sandbox.** Keys from sandbox applications skip screening and billing entirely and return a mocked result — `Approved` with zero hits unless you pass `sandbox_scenario`. `save_api_request` works the same as on live keys, so a saved sandbox screening is retrievable through `GET /v3/session/{sessionId}/decision/` and `GET /v3/session/{sessionId}/generate-pdf/`.



# Document AI API
Source: https://docs.didit.me/standalone-apis/document-ai

POST /v3/document-ai/
Extract the fields **you** define from any supporting document — payslips, proof of funds, source-of-wealth letters, tax statements, contracts, invoices — in one call. Send the file plus a `fields` definition (key, name, extraction instruction, type) and get back typed values (`text`, `number`, `date` as `YYYY-MM-DD`), an optional name-match score against the expected person or company, PDF/EXIF tamper signals, an `Approved`/`Declined`/`In Review` `status`, and a `warnings` list explaining every issue found. This is the server-to-server counterpart of the hosted Document AI workflow step (see `/core-technology/document-ai/overview`); it uses Didit's default extraction model and does not expose provider selection.

**Latency.** Extraction is LLM-based: typical calls take **5–15 seconds**, multi-page PDFs up to **~30 seconds**. Configure a client timeout of **at least 45 seconds** and do not retry before the call completes.

**Request format.** `multipart/form-data` only. `fields` is **one JSON-encoded array string** (1–30 items, at most 16 KB); bracket-style form arrays are rejected with `400`. Each item is `{key, name, instruction, type, required, is_full_name}` — `key` is the JSON key you get back (`^[a-z0-9_]{1,64}$`, unique), `instruction` tells the model what to read, `type` is `text` (default) | `number` | `date`, `required` raises `DOCUMENT_AI_MISSING_REQUIRED_FIELDS` when the value cannot be read, and at most one field may set `is_full_name: true` to mark the value compared against the expected name.

**Name matching.** Pass `expected_first_name` + `expected_last_name` (person) **or** `expected_company_name` (+ optional `expected_company_country`) — not both. The value of the `is_full_name` field (or, when none is marked, the first text field whose key looks like a name) is compared fuzzily; `name_match_score` (0–100) and `name_on_document` are always returned when both sides exist, and a score below `document_ai_name_match_score_threshold` (default 80) adds `DOCUMENT_AI_NAME_MISMATCH`, governed by `document_ai_name_mismatch_action`.

**Decision logic.** Each risk maps to a configurable action: `DECLINE` → `status: "Declined"`, `REVIEW` → `status: "In Review"`, `NO_ACTION` → informational only. Defaults mirror the workflow step: unreadable document `REVIEW`, missing required fields `REVIEW`, suspected manipulation `DECLINE`, name mismatch `NO_ACTION`, unsupported file `REVIEW`. A document that cannot be processed at all returns `400`; a readable but problematic document returns `200` with `Declined`/`In Review` — always inspect `document_ai.status` and `document_ai.warnings`, not just the HTTP code.

**Billing.** Each `200` response consumes one Document AI API credit — **$0.20 per document, no free tier** (standalone APIs never have one). When the organization's balance cannot cover the call, the endpoint returns `403` before any processing. Sandbox API keys return a deterministic mock response and are not charged.

**Persistence.** With `save_api_request=true` (default) the call is stored as an API-type session: the document, the extracted values, the field definitions and the name-match snapshot are kept, the session shows up in the Business Console, and `request_id` works with `GET /v3/session/{sessionId}/decision/`.

Send one document and the list of fields you want read from it. Didit runs its default extraction model over the file, returns every field typed (`text`, `number`, or `date` as `YYYY-MM-DD`), detects and decodes supported QR codes and barcodes, checks the file for manipulation, and optionally compares the name on the document against the person or company you expect. Use it for proof of funds, payslips, bank statements, tax documents, invoices, or any document that does not fit a fixed template.

This is the server-to-server version of the hosted [Document AI](/core-technology/document-ai/overview) step. The request is `multipart/form-data`: the file goes in `document`, and the field definitions go in `fields` as one JSON-encoded array string.

## Define the fields to extract

`fields` is a JSON array of 1 to 30 items, sent as a single string. Each item has a `key` (lowercase letters, digits, and underscores, unique within the request), a human-readable `name`, an `instruction` that tells the model what to look for, a `type` (`text`, `number`, or `date`), and two flags: `required` and `is_full_name`.

```json theme={null}
[
  {
    "key": "account_holder",
    "name": "Account holder",
    "instruction": "Full name of the person or company the account belongs to",
    "type": "text",
    "required": true,
    "is_full_name": true
  },
  {
    "key": "balance",
    "name": "Closing balance",
    "instruction": "Closing balance shown on the statement, as a number without the currency symbol",
    "type": "number",
    "required": true
  },
  {
    "key": "currency",
    "name": "Currency",
    "instruction": "Three-letter currency code of the balance",
    "type": "text"
  },
  {
    "key": "statement_date",
    "name": "Statement date",
    "instruction": "Date the statement was issued",
    "type": "date",
    "required": true
  }
]
```

In a multipart request the whole array is one form value:

```bash theme={null}
curl -X POST https://verification.didit.me/v3/document-ai/ \
  -H "x-api-key: $DIDIT_API_KEY" \
  -F "document=@./bank-statement.pdf" \
  -F 'fields=[{"key":"account_holder","name":"Account holder","instruction":"Full name of the account holder","type":"text","required":true,"is_full_name":true},{"key":"balance","name":"Closing balance","instruction":"Closing balance as a number","type":"number","required":true}]' \
  -F "expected_first_name=Jane" \
  -F "expected_last_name=Doe"
```

The response echoes the normalized `fields` and returns `extracted_data` keyed by your `key` values, with `null` for anything the model could not find. `name`, `instruction`, and `type` are optional on each item (`type` defaults to `text`); `key` is required. Sending `fields` as bracket-style form keys (`fields[0][key]=...`) or as anything other than a JSON array returns `400` before any extraction runs, so nothing is billed.

## QR codes and barcodes

Every successful response includes `document_ai.detected_codes`. Each item contains:

| Field                       | Description                                                                                |
| --------------------------- | ------------------------------------------------------------------------------------------ |
| `type`                      | Detected symbology, such as `QR_CODE`, `CODE_128`, `EAN_13`, `DATA_MATRIX`, or `PDF_417`   |
| `page_number`               | 1-based page number                                                                        |
| `position`                  | Detected polygon in rendered-page pixels, or `null` when no reliable location is available |
| `x`, `y`, `width`, `height` | Bounding box in rendered-page pixels, or `null` when no reliable location is available     |
| `page_width`, `page_height` | Rendered page dimensions used by the coordinates                                           |
| `parsed_payload`            | Decoded string or structured value, or `null` when the code can only be located            |
| `raw_payload`               | Raw decoder payload as a base64 string when available; otherwise an empty string           |

The array covers every processed page of a PDF and is empty when no supported code is found. Didit never guesses a payload: damaged QR codes may be returned with their location and `parsed_payload: null`, while failures in code detection do not fail the Document AI request.

## Name matching

Mark at most one field with `is_full_name: true` and send who you expect the document to belong to:

| You are verifying | Send                                                                                 | The name is compared against |
| ----------------- | ------------------------------------------------------------------------------------ | ---------------------------- |
| A person          | `expected_first_name` + `expected_last_name`                                         | the person's full name       |
| A company         | `expected_company_name` (+ optional `expected_company_country`, a 2-letter ISO code) | the company name             |

Send one group or the other, not both. When a name is extracted and an expected name is present, the response includes `name_match_score` (0 to 100) and `name_on_document`. A score below `document_ai_name_match_score_threshold` (default `80`) raises the `DOCUMENT_AI_NAME_MISMATCH` warning and applies `document_ai_name_mismatch_action`. If no field is marked `is_full_name`, Didit falls back to the first text field whose key looks like a name (`name`, `holder`, `full_name`, `account_holder`); mark the field explicitly when you want to control which value is compared. When no name value can be found on the document, or no expected name is sent, the name check is skipped and `name_match_score` is `null`.

## Risks and actions

Each risk below maps to an action parameter you can set per request: `DECLINE`, `REVIEW`, or `NO_ACTION`. The strictest triggered action decides `document_ai.status` (`Declined` > `In Review` > `Approved`), and every triggered risk is listed in `document_ai.warnings`. The defaults match the hosted workflow step; see [Document AI rules & warnings](/core-technology/document-ai/warnings-document-ai) for how each risk is detected.

| Risk                                  | Parameter                                    | Default     |
| ------------------------------------- | -------------------------------------------- | ----------- |
| `DOCUMENT_AI_UNREADABLE_DOCUMENT`     | `document_ai_unreadable_document_action`     | `REVIEW`    |
| `DOCUMENT_AI_MISSING_REQUIRED_FIELDS` | `document_ai_missing_required_fields_action` | `REVIEW`    |
| `DOCUMENT_AI_SUSPECTED_MANIPULATION`  | `document_ai_document_tampering_action`      | `DECLINE`   |
| `DOCUMENT_AI_NAME_MISMATCH`           | `document_ai_name_mismatch_action`           | `NO_ACTION` |
| `DOCUMENT_AI_UNSUPPORTED_FILE`        | `document_ai_unsupported_file_action`        | `REVIEW`    |

## Files, saving, and billing

* **Accepted files:** PDF (multi-page supported), JPG, JPEG, PNG, TIFF, WebP, or a ZIP containing the document, up to 30 MB. Encrypted PDFs return `400`; upload a decrypted PDF or a photo instead.
* **`save_api_request`** (default `true`): the request, extracted fields, and detected codes appear in the Business Console under **Manual Checks**, where your team can review them. Set it to `false` to skip saving.
* **`vendor_data`** and **`metadata`** are returned unchanged in the response so you can link the result to your own records.
* **Price:** \$0.20 per document, billed when the document is processed and a status is returned. Standalone APIs do not include the free monthly workflow tier. See [Pricing](/getting-started/pricing#standalone-api-pricing-server-to-server).

<Note>
  Need the user to upload the document themselves, collect up to 3 documents in one flow, auto-translate the upload screen, or cross-reference extracted fields against ID or questionnaire data? Use the hosted [Document AI workflow step](/core-technology/document-ai/overview) instead.
</Note>


# Check Email Code
Source: https://docs.didit.me/standalone-apis/email-check

POST /v3/email/check/
Verify the OTP delivered by [`POST /v3/email/send/`](/standalone-apis/email-send) and get the final verification result plus email intelligence: deliverability, breach exposure (`is_breached` and the `breaches` list from a breach-intelligence database), disposable-provider detection, and duplicate usage of the address across your sessions.

**How the check finds the verification.** Matching is by your application plus the `email` address — `request_id` is not an input. The most recent pending verification created within the last **5 minutes** is checked. If there is none (never sent, already finalized, undeliverable at send time, or older than 5 minutes) the endpoint returns `200` with `status: "Expired or Not Found"`.

**Attempt budget.** Each verification allows **3 code attempts**. The first two wrong codes return `status: "Failed"` with the attempts remaining and `email: null`; the third wrong code finalizes the verification as `Declined` with an `EMAIL_CODE_ATTEMPTS_EXCEEDED` warning and returns the full email report. Codes are compared case-insensitively (relevant for `alphanumeric_code` sends); only the most recently sent code is valid.

**Outcomes.** `Approved` — correct code and no declining risk. `Declined` — terminal: the code was correct but a declining risk matched (a `DECLINE` action below, a blocklisted address, or the address found undeliverable at finalization), or the attempt budget was exhausted. `Failed` — wrong code, attempts remaining. `Expired or Not Found` — nothing to check. On `Approved`/`Declined` the `request_id` equals the send's `request_id` (the session id) and `email` carries the full report (`is_breached`, `breaches`, `is_disposable`, `is_undeliverable`, `warnings`, `lifecycle`, `matches`); on `Failed` and `Expired or Not Found` the `request_id` is a one-off random UUID.

**Risk actions.** `duplicated_email_action`, `breached_email_action`, and `disposable_email_action` decide what happens when the corresponding risk is detected on a correct code: `DECLINE` flips the final status to `Declined`; `NO_ACTION` (default) records the risk in `email.warnings` without affecting the status.

**Billing.** Checks are free — the credit is consumed by the successful send.

**Session persistence.** A finalized check updates the session created by the send (visible in the Business Console, queryable via `GET /v3/session/{sessionId}/decision/`) and fires a `status.updated` webhook.

**Sandbox.** Sandbox API keys skip all processing: any well-formed code (`123456` included) returns a static `Approved` payload with a simplified `email` object (`status`, `email`, `is_breached`, `is_disposable`, `is_undeliverable`); malformed input still returns `400`. Nothing is persisted.

**Authentication.** Send your application's API key in the `x-api-key` header. Missing or invalid credentials return `403` (`{"detail": "You do not have permission to perform this action."}`) — this API never returns `401`.

**Rate limit.** Shared write budget of 300 requests/min per API key across all POST/PATCH/DELETE endpoints; exceeding it returns `429`.

**Social footprint.** Set `enable_social` to `true` to add a `email_social` block: the online platforms this address is registered on, with per-category counts and any profile details available. `profiles_registered: 0` means the platforms were checked and the address was found on none of them - a valid, billable answer. The block is absent when the add-on was not requested or the check could not be completed, and it is not billed in that case. Billing adds one `email_social` unit per request on top of this endpoint's own price.



# Email Risk API
Source: https://docs.didit.me/standalone-apis/email-risk

POST /v3/email/risk/
Risk-score an email address without sending an OTP. Deliverability, disposable-domain, breach, and fraud signals in one server-to-server call.

Use `POST /v3/email/risk/` when you need email intelligence without asking the user to enter a one-time code.

It does not send an email. It creates an API session, enriches the address, applies your email-risk rules, and returns the same normalized email block used by Email Verification in one synchronous response.

When the request is saved, Didit can also use the scored email as aggregate evidence in **Networks**. Network graphs may show high-risk email intelligence, breach context, and social-profile coverage on shared email signals, but they do not reveal the raw email address to other organizations.

## Interpret the response

* `status` is the final decision for this API session. It is normally `Approved`; the risk evaluation can produce `In Review` or `Declined`.
* `email.is_breached`, `email.is_disposable`, and `email.is_undeliverable` are the stable yes/no signals for application logic.
* `email.breaches` lists the most recent known breaches containing the address when coverage is available, with the breach date and the data classes exposed.
* `email.email_intelligence.score` uses a 0-100 risk scale where a higher number means higher risk. `breach_risk_level` (`Low`, `Medium`, `High`) and `no_of_breaches` are derived views.
* `email.email_intelligence.reason_codes` explains which normalized signals contributed to the result. Values can grow over time, so do not reject unknown codes.
* `email.email_intelligence` and `email.enrichment` are compatibility aliases with the same normalized object. New integrations can read `email.enrichment`.
* `email.matches` lists other sessions of your application where the same address was used by a different user. Use it for duplicate-account detection.
* `request_id` is the API session id. Store it with `vendor_data` if you need to correlate the result with later webhooks or console activity.

<Warning>
  `email.email_intelligence` and `email.enrichment` are best-effort fields. A completed lookup can omit both when no usable intelligence data is returned for that address, domain, or plan. Build rules on `is_breached`, `is_disposable`, and `is_undeliverable` first and treat missing intelligence as "unknown", not "safe".
</Warning>

## Social footprint add-on

Set `enable_social` to `true` to add a `email_social` block to the response under `email`: the online platforms this email address is registered on, grouped by category, with the summary counts and any profile details our data partners return.

* `email.email_social.profiles_registered` and `email.email_social.profiles_checked` are the headline numbers: platforms where the email address is confirmed registered, out of the platforms evaluated.
* `email.email_social.registered_platforms` and `email.email_social.not_registered_platforms` list each platform with its `category` and `scope` (`global`, or `local` for region-specific platforms).
* `email.email_social.categories` gives the registered count and ratio per category, and `email.email_social.profiles` carries per-platform profile details when a platform exposes them (name, photo URL, about text, privacy status, business-account flag).
* Summary indexes (`digital_footprint_diversity`, `digital_sophistication_index`, `engagement_depth_index`, `subscription_affordability_index`) are 0-10 composites. Every count can be `null` when the check returned no data for it.

`profiles_registered: 0` is a real answer, not a failure: the platforms were checked and the email address was found on none of them, which is a common synthetic-identity signal. This endpoint does not act on it by itself - use `email_no_social_presence_action` in a workflow to turn it into a Review or Decline verdict.

The block is absent when `enable_social` is not set, and also when the social check could not be completed - in which case it is not billed.

## Sandbox behavior

Sandbox keys validate the request and return deterministic approved data. They do not send an email, consume credits, create a session, or contribute to Networks. With `enable_social` set, they also return a deterministic `email_social` block.

## Billing

Email Risk API calls use Email Risk API pricing, lower than full Email Verification because no email is sent. A live request is billable once the lookup starts, even when some best-effort fields are unavailable.

The social footprint add-on is billed separately: one `email_social` unit per request on top of the Email Risk API price, whenever the check completes. The credit check before the lookup covers both.


# Send Email Code
Source: https://docs.didit.me/standalone-apis/email-send

POST /v3/email/send/
Send a one-time passcode (OTP) to an email address, then verify it with [`POST /v3/email/check/`](/standalone-apis/email-check).

**How send and check pair up.** Verification state is keyed by your application plus the `email` address — the check call does not take `request_id`. Each new send creates a pending verification that lives for **5 minutes**: call the check with the same address and the code the user received before the window closes. Calling send again for the same address while a verification is pending generates a fresh code for that same verification (`status: "Retry"`, same `request_id`); the previous code stops working. At most one retry is attached this way (two sends total); a further send starts a fresh verification with a new `request_id`. The 5-minute window is measured from the first send and is not extended by retries.

**Deliverability pre-check.** Before anything is sent, the address goes through syntax and DNS/MX validation. Addresses that cannot receive mail return `200` with `status: "Undeliverable"` and `reason: "email_can_not_be_delivered"` — no email is sent, nothing is billed, and the verification is immediately finalized as `Declined` (a follow-up check returns `Expired or Not Found`). A downstream send failure reports the same way.

**Code format and branding.** Codes are 4–8 characters (`options.code_size`, default 6), numeric by default; set `options.alphanumeric_code: true` for uppercase letters and digits (the check comparison is case-insensitive). The email template is localized via `options.locale` (54 supported languages) and can use your application's white-label branding via `options.use_white_label_customization`.

**Billing.** One Email Verification API credit per successful send (`status: "Success"`), charged at send time. `Retry` and `Undeliverable` sends are free, and checks are free.

**Session persistence.** Every new verification is persisted as an API-type session: `request_id` is a real session id you can pass to `GET /v3/session/{sessionId}/decision/`, the verification appears in the Business Console, and `status.updated` webhooks fire as it progresses.

**Sandbox.** Sandbox API keys skip delivery and billing: after request validation (malformed input still returns `400`), the endpoint returns a static `Success` payload with a random `request_id`; no email is sent and nothing is persisted. Use code `123456` on the sandbox check.

**Authentication.** Send your application's API key in the `x-api-key` header. Missing or invalid credentials return `403` (`{"detail": "You do not have permission to perform this action."}`) — this API never returns `401`.

**Rate limit.** Shared write budget of 300 requests/min per API key across all POST/PATCH/DELETE endpoints; exceeding it returns `429`.



# Email Verification API
Source: https://docs.didit.me/standalone-apis/email-verification

Two-step OTP email verification with breach, disposable-address, and deliverability risk scoring. Pay-per-use pricing, 500 free per month.

The Email Verification API provides a two-step flow: send a one-time code to an email address, then verify the code the user enters. The system also performs risk assessment including breach exposure, disposable provider detection, and deliverability checks.

## Endpoints

<CardGroup>
  <Card title="Send Email Code" icon="paper-plane" href="/standalone-apis/email-send">
    `POST /v3/email/send/` — Send a one-time verification code to an email address.
  </Card>

  <Card title="Check Email Code" icon="circle-check" href="/standalone-apis/email-check">
    `POST /v3/email/check/` — Verify the code and retrieve email risk data.
  </Card>

  <Card title="Score Email Risk" icon="shield-alert" href="/standalone-apis/email-risk">
    `POST /v3/email/risk/` — Score deliverability, breach, and disposable-email risk without sending a code.
  </Card>
</CardGroup>

## How it works

1. Call **Send Email Code** with the target email address
2. The user receives a 6-digit code (valid for 5 minutes)
3. Call **Check Email Code** with the email and code
4. Receive verification result plus risk signals (breach exposure, disposable provider, deliverability)

By default, standalone OTP emails use Didit branding. To use your application's configured white-label sender and branding for a specific standalone email verification session, pass `options.use_white_label_customization: true` to `POST /v3/email/send/`. The default is `false`.

## Risk signals

The check response includes:

| Signal             | Description                        |
| ------------------ | ---------------------------------- |
| `is_breached`      | Email found in known data breaches |
| `is_disposable`    | Temporary/throwaway email provider |
| `is_undeliverable` | Address does not accept mail       |

For full response structure, see [Email Verification Report](/core-technology/email-verification/overview).


# Face Match
Source: https://docs.didit.me/standalone-apis/face-match

POST /v3/face-match/
Compare two face images (1:1) and get back a similarity `score` (0–100) plus an `Approved`/`Declined` `status`.

**How it works.** Both images are decoded and analyzed by a biometric model (set `rotate_image=true` if captures may be sideways or upside down), then a similarity score between the two faces is computed. A score **strictly above** `face_match_score_decline_threshold` (default `30`) returns `status: "Approved"`; a score at or below it returns `Declined` with a `LOW_FACE_MATCH_SIMILARITY` warning. If no face pair can be scored at all, the call still returns `200` with `status: "Declined"` and a `NO_REFERENCE_IMAGE` warning — `score` is `null` on the default save path, or `0` with `save_api_request=false`. Submit one clear, front-facing face per image for best results.

**Billing.** Each `200` response consumes one Face Match API credit (standalone APIs have no free tier). When the organization's balance cannot cover the call, the endpoint returns `403` with the not-enough-credits error before any image processing.

**Session persistence (`save_api_request`, default `true`).** When `true`, the call is persisted as an API-type session: it appears in the Business Console, the returned `request_id` is a real session id you can pass to `GET /v3/session/{sessionId}/decision/`, both images are stored as the session's face-match source/target images, and a `status.updated` webhook is emitted to your configured webhook endpoints. When `false`, nothing is stored and `request_id` is a one-off correlation UUID that cannot be looked up later.

**Face search index.** This endpoint never enrolls faces into your face search index and never runs blocklist or duplicate screening — use `POST /v3/passive-liveness/` or `POST /v3/face-search/` for those.

**Sandbox.** Sandbox API keys skip all processing and billing: after request validation (malformed input still returns `400`), the endpoint returns a static `Approved` mock payload, no session is persisted, and no credits are consumed.

**Authentication.** Send your application's API key in the `x-api-key` header. Missing or invalid credentials return `403` (`{"detail": "You do not have permission to perform this action."}`) — this API never returns `401`.

**Rate limit.** Shared write budget of 300 requests/min per API key across all POST/PATCH/DELETE endpoints; exceeding it returns `429`.



# Face Search
Source: https://docs.didit.me/standalone-apis/face-search

POST /v3/face-search/
Search a face image (1:N) against your application's face search index — faces enrolled from verification sessions, saved standalone API calls, direct user-profile face uploads, and your block/allow lists — and get back ranked similarity matches plus blocklist and duplicate warnings.

**How it works.** The largest detected face in `user_image` is embedded and searched against the index, scoped to your application. Up to **5 matches** above the similarity floor are returned in `matches`, each with `similarity_percentage`, the originating session (`session_id`, `session_number`, `status`, `vendor_data`), `user_details` extracted during that session's document verification, `is_blocklisted` / `is_allowlisted` flags, and a `source` discriminator (`session`, `imported`, or `list_entry`).

- `search_type=most_similar` (default) ranks every enrolled face by similarity — use it for deduplication and fraud-ring investigation.
- `search_type=blocklisted_or_approved` restricts candidates to blocklisted faces, allowlisted faces, faces from approved sessions, and imported user-profile faces, ranking blocklisted entries first — use it when the primary goal is blocklist screening.

`status` is `Declined` only when a `FACE_IN_BLOCKLIST` or `POSSIBLE_FACE_IN_BLOCKLIST` warning fires; `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` (`information`) and `MULTIPLE_FACES_DETECTED` (`warning`) never decline. Unlike Passive Liveness, this endpoint does **not** exclude prior sessions with the same `vendor_data` from matching. A passive-liveness analysis also runs internally and is stored with the persisted session, but its result is not part of this response.

**Billing.** Each `200` response consumes one Face Search API credit (standalone APIs have no free tier). Insufficient balance returns `403` before any image processing.

**Session persistence and face enrollment (`save_api_request`, default `true`).** When `true`, the call is persisted as an API-type session (Business Console, `GET /v3/session/{sessionId}/decision/` via the returned `request_id`, `status.updated` webhook) and the searched face is enrolled into your face search index. Faces enrolled by Face Search calls are excluded from future Face Search results, so repeated searches never match each other. When `false`, the call is one-shot: nothing is stored, the face is not enrolled, and `match_image_url` values are internal storage paths rather than downloadable URLs.

**Sandbox.** Sandbox API keys skip all processing and billing: after request validation (malformed input still returns `400`), the endpoint returns a static `Approved` mock payload, no session is persisted, and no credits are consumed.

**Authentication.** Send your application's API key in the `x-api-key` header. Missing or invalid credentials return `403` (`{"detail": "You do not have permission to perform this action."}`) — this API never returns `401`.

**Rate limit.** Shared write budget of 300 requests/min per API key across all POST/PATCH/DELETE endpoints; exceeding it returns `429`.



# ID Verification API
Source: https://docs.didit.me/standalone-apis/id-verification

POST /v3/id-verification/
OCR an identity document and run document fraud checks in one call — returns the extracted holder fields, the parsed MRZ, an `Approved`/`Declined` `status`, and a `warnings` list explaining every issue found. Supports 14,000+ document types from 220+ countries and territories.

**How it works.** Send the document's `front_image` (required) and, for two-sided documents, the `back_image`. Upload uncropped photos with all four corners of the document visible — the service detects, aligns, and crops the document itself, so do not pre-crop. The document is classified automatically (you never declare the country or document type), the visual zone is read with OCR, and the MRZ and any barcodes are decoded. Cross-checks then validate dates, number formats, and MRZ check digits, and compare the visual zone against the MRZ. With `perform_document_liveness=true`, the images are additionally screened for screen replays, printed copies, and portrait manipulation.

**Decision logic.** `status` is `Approved` unless at least one warning resolves to a decline. Fraud and hard-failure risks always decline: `DOCUMENT_EXPIRED`, `SCREEN_CAPTURE_DETECTED`, `PRINTED_COPY_DETECTED`, `PORTRAIT_MANIPULATION_DETECTED`, `PUBLIC_DOCUMENT_IMAGE_DETECTED`, plus extraction failures (`NAME_NOT_DETECTED`, `DATE_OF_BIRTH_NOT_DETECTED`, `DOCUMENT_NUMBER_NOT_DETECTED`). (`PORTRAIT_IMAGE_NOT_DETECTED`, `COULD_NOT_DETECT_DOCUMENT_TYPE`, `INVALID_DATE`, and `MRZ_NOT_DETECTED` exist in workflow sessions but are never produced by this standalone endpoint.) Three risk groups are configurable per request via `invalid_mrz_action`, `inconsistent_data_action`, and `expiration_date_not_detected_action` (`DECLINE` or `NO_ACTION`). All other warnings (e.g. `POSSIBLE_DUPLICATED_USER`) are informational and never decline on their own. A document that cannot be processed at all returns `400` with `{"error": "COULD_NOT_RECOGNIZE_DOCUMENT"}`; a readable but problematic document returns `200` with `status: "Declined"` — always inspect `id_verification.status` and `id_verification.warnings`, not just the HTTP code.

**Billing.** Each `200` response consumes one ID Verification API credit (standalone APIs have no free tier). When the organization's balance cannot cover the call, the endpoint returns `403` with the not-enough-credits error before any image processing.

**Session persistence (`save_api_request`, default `true`).** When `true`, the call is persisted as an API-type session: it appears in the Business Console, the returned `request_id` is a real session id you can pass to `GET /v3/session/{sessionId}/decision/`, the cropped document/portrait images are stored and returned as short-lived media URLs (`https://<media-host>/ocr/...`), and a `status.updated` webhook is emitted to your configured webhook endpoints. When `false`, nothing is stored, `request_id` is a one-off correlation UUID, and `portrait_image`/`front_image`/`back_image` are returned inline as base64-encoded JPEG strings.

**Sandbox.** Sandbox API keys skip all processing and billing: after request validation (malformed input still returns `400`), the endpoint returns a static `Approved` mock payload (a fictional "Sandbox User" USA identity card), no session is persisted, and no credits are consumed.

**Authentication.** Send your application's API key in the `x-api-key` header. Missing or invalid credentials return `403` (`{"detail": "You do not have permission to perform this action."}`) — this API never returns `401`.

**Rate limit.** Shared write budget of 300 requests/min per API key across all POST/PATCH/DELETE endpoints; exceeding it returns `429`.



# IP Risk API
Source: https://docs.didit.me/standalone-apis/ip-risk

POST /v3/ip/risk/
Risk-score an IP address with geolocation, ISP, VPN/Tor, datacenter, threat, and claimed-country mismatch signals.

Use `POST /v3/ip/risk/` when your backend already has an IP address and needs a server-to-server risk decision.

The response includes geolocation, network ownership, VPN/Tor and data-center flags, threat data, and `country_mismatch` when you send a claimed country.

## Interpret the response

* `status` is `In Review` when the resolved country conflicts with `claimed_country`, or when the address is associated with VPN, Tor, or data-center infrastructure. Otherwise it is `Approved`.
* `ip.ip_country_code` contains the resolved country code. Compare countries through `ip.country_mismatch` instead of comparing raw country strings yourself.
* `ip.latitude` and `ip.longitude` are approximate network geolocation, not a precise device location.
* `ip.is_vpn_or_tor`, `ip.is_data_center`, `ip.proxy_type`, and `ip.threat` carry network-risk evidence.
* `ip.asn_number`, `ip.asn_organization`, `ip.connection_type`, and `ip.carrier` describe the network the address belongs to.
* `request_id` is the API session id. Store it with `vendor_data` if you need to correlate the result with later webhooks or console activity.

<Note>
  IP enrichment is best effort. If no enrichment source returns usable data, the endpoint returns an approved response with `ip.ip_address: null`, `ip.country_mismatch: null`, and an empty `ip.threat` object. Individual enrichment fields can also be `null` when unavailable.
</Note>

## Device intelligence

The IP Risk API is a pure server-to-server endpoint. Device fingerprinting is not, because a backend cannot observe browser or device signals by itself. For hosted-flow and SDK sessions, Didit exposes the already collected device fields on the session response, including `device_fingerprint`, device and browser details, `user_agent`, raw device data, and cross-session matches.

## Sandbox behavior

Sandbox keys validate the request and return deterministic approved data. They do not contact external intelligence services, consume credits, create a session, or contribute to Networks.

## Billing

IP Risk API calls use IP Risk API pricing. A live request is billable once the lookup starts.


# KYB Registry API
Source: https://docs.didit.me/standalone-apis/kyb-registry

Search company registries, then retrieve the company at the tier you need: Lite (select), Shareholders or UBOs, priced per country.

## Endpoints and billing

Successful standalone searches using a paid company-data source cost **\$0.50 per request**, regardless of the number of candidates. Empty results, failed searches, and results served only by other sources are not charged. A later profile retrieval is billed separately.

Retrieval is sold in three data tiers, one endpoint each, priced per country ([per-country prices](/getting-started/kyb-registry-pricing)):

| Endpoint                                                                   | What you get                                                                                                                                        | Price                                        |
| -------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------- |
| [`POST /v3/kyb/search/`](/standalone-apis/kyb-registry-search)             | Candidate companies: name, registration number, status, type                                                                                        | \$0.50 when paid-source results are returned |
| [`POST /v3/kyb/select/`](/standalone-apis/kyb-registry-select)             | **Lite**: the company profile (identifiers, status, legal form, incorporation date, registered address, activity, contact details) and the officers | Lite price, \$2.00                           |
| [`POST /v3/kyb/shareholders/`](/standalone-apis/kyb-registry-shareholders) | Lite plus the direct shareholders with their ownership bands                                                                                        | Shareholders price: $4.00-$22.00 by country  |
| [`POST /v3/kyb/ubo/`](/standalone-apis/kyb-registry-ubo)                   | Shareholders plus the ultimate beneficial owners resolved through the ownership chain                                                               | UBO price: $5.00-$96.00 by country           |

`select` is the Lite tier: it is what a hosted KYB workflow bills for a registry check at the Lite level, and it keeps the contract it has always had. Europe means the EEA, the United Kingdom and Switzerland.

<Note>
  **You pay for the tier delivered.** Every response carries `registry_tier_requested` and `registry_tier_delivered`. When the country's registries hold no ownership data, or the registry has no ownership record for the selected company, an ownership request is delivered and billed as the highest tier available (usually Lite), and `registry_ownership_status` says why.
</Note>

<Note>
  **Versioning.** The Shareholders and UBO endpoints exist on `/v3/` only. The standalone search fee also applies to `/v2/kyb/search/`; profile retrieval is billed separately.
</Note>

Use `POST /v3/kyb/search/` to find candidate companies. Search does not create a saved check.

Registry searches can take around 90 seconds. Send `webhook_url` when you want Didit to return immediately and notify your URL once candidates are ready. The search callback is unsigned on purpose, so you do not need to configure a shared secret for this lightweight notification.

Use `POST /v3/kyb/select/`, `POST /v3/kyb/shareholders/` or `POST /v3/kyb/ubo/` with the returned `kyb_response_id` to retrieve the profile at the tier you need. Retrieval is billable and saves the result as a Manual Check in the Business Console.

## Typical flow

1. Search by company name, registration number, and country.
2. If `search_resolved=false`, wait for the optional `webhook_url` callback instead of polling.
3. Show the returned candidates to your operator or customer.
4. Retrieve the matching `kyb_response_id` at the tier you need (select for Lite, shareholders, or ubo).
5. Store the returned `request_id` and use it to retrieve the saved business verification result.

## Search callback

When the provider tells Didit the search is resolved, Didit sends one `POST` to your `webhook_url`:

```json theme={null}
{
  "event_id": "7f5a1c93-6a44-4f0e-9f2b-3d8a1c6f2e91",
  "event_type": "kyb.registry_search.resolved",
  "request_id": "b5ef9df5-bd9e-4d61-bbe5-5eb7a8fb6f85",
  "vendor_data": "business-123",
  "metadata": {
    "source": "onboarding"
  },
  "search_status": "resolved",
  "search_resolved": true,
  "kyb_registry": {
    "companies": [
      {
        "kyb_response_id": "kyb_resp_123",
        "name": "TESCO PLC",
        "registration_number": "00445790",
        "status": "active",
        "type": "Public Limited Company",
        "risk_level": null,
        "fetch_status": "pending"
      }
    ],
    "pagination": {
      "total": 1,
      "page": 1,
      "per_page": 25
    },
    "search_status": "resolved",
    "search_resolved": true
  },
  "timestamp": 1767225600,
  "created_at": 1767225600
}
```

Treat the callback as a delivery notification. Use the returned `kyb_response_id` with `POST /v3/kyb/select/`, `POST /v3/kyb/shareholders/` or `POST /v3/kyb/ubo/` to run the billable registry profile retrieval.


# KYB Registry Search
Source: https://docs.didit.me/standalone-apis/kyb-registry-search

POST /v3/kyb/search/
Search official company registries for candidate companies by name and/or registration number. This is step 1 of the two-step registry flow: **search** returns lightweight candidates, then `POST /v3/kyb/select/` retrieves the full profile of one candidate.

**Search billing.** Successful searches using a paid company-data source cost USD 0.50 per request, regardless of candidate count. Empty results, failures and results served only by other sources are not charged. The applicable price is reserved before searching; insufficient balance returns 403 with code `insufficient_credits`. Contract rates apply where agreed, and an unconfigured contract search rate returns 403. Sandbox searches are free. Repeating a successful search can incur another charge; callback delivery does not add a charge. Profile retrieval is billed separately. This search fee also applies to v2. Candidates always come back with `fetch_status: "pending"`: the full company data is only fetched (and billed) on select.

**`kyb_response_id` is ephemeral.** It is a per-search handle, not a stable company id. Select promptly after searching and re-search to get a fresh handle instead of storing it.

**Two modes.**
- *Synchronous (default):* the API polls the registry until the search resolves and returns the final candidate list (`search_resolved: true`).
- *Asynchronous:* pass `webhook_url` and the API returns immediately — usually with `search_status: "pending"` and an empty candidate list — then POSTs a `kyb.registry_search.resolved` callback to your URL when the registry finishes. The callback body is `{"event_id", "event_type": "kyb.registry_search.resolved", "request_id", "vendor_data", "metadata", "search_status", "search_resolved", "kyb_registry", "timestamp", "created_at"}` — note `timestamp` and `created_at` in the callback are epoch integers, unlike this endpoint's ISO `created_at` — and is sent **unsigned** (header `X-Didit-Unsigned-Callback: true`, no `X-Signature`).

**Country codes.** ISO 3166-1 alpha-2 (`GB`, `DE`), plus `XX-YY` subdivision codes where registries are regional — e.g. `US-CA` for California.

**Sandbox.** Keys from sandbox applications return one static candidate without contacting any registry.

Use this endpoint first to find matching company registry candidates.
Search does not create a saved Manual Check.

Successful standalone searches using a paid company-data source cost **\$0.50 per request**, regardless of the number of candidates. Empty results, failed searches, and results served only by other sources are not charged. A later profile retrieval is billed separately.

For a search that can use a paid source, Didit checks and reserves the applicable search price before contacting the registry.
Insufficient balance returns `403` with `code: "insufficient_credits"`.
Contract billing follows your agreed search rate; an unconfigured contract rate is rejected before the search.
Sandbox searches are free.
Each repeated successful search is a new billable request; callback delivery does not add another search charge.

If you send `webhook_url`, Didit can return immediately while the provider resolves the search, then post the candidates to your callback URL when they are ready. The callback is unsigned by design, so you do not need to configure a webhook secret for this search notification. See the [search callback payload example](/standalone-apis/kyb-registry#search-callback).

After you pick the correct `kyb_response_id`, call `POST /v3/kyb/select/` (Lite), `POST /v3/kyb/shareholders/` or `POST /v3/kyb/ubo/` to retrieve the billable registry profile at the tier you need.

<Note>
  Each candidate's `fetch_status` is `pending` at search time and stays `pending` until you select that candidate — search only lists candidates, and select is what fetches the full profile. Do not poll search waiting for it to resolve.

  `kyb_response_id` is an opaque, ephemeral handle scoped to one search request: pass it back exactly as you received it and never parse it or derive anything from its contents, and expect repeating the same search to return new ids. Select the candidate promptly after searching, and use `registration_number` when you need a stable identifier for the company itself.
</Note>

## Handle registry outages

If the registry provider is temporarily unavailable, the endpoint returns `502` with a stable machine-readable code:

```json theme={null}
{
  "detail": "The company registry provider is temporarily unavailable.",
  "code": "kyb_registry_provider_unavailable"
}
```

When you receive this code, let the user continue with manual company entry or ask them to retry later. Keep validation errors separate: invalid search input returns `400` and does not use this outage code.


# KYB Registry Select
Source: https://docs.didit.me/standalone-apis/kyb-registry-select

POST /v3/kyb/select/
Retrieve the **Lite** registry profile of one candidate returned by `POST /v3/kyb/search/` — company details, registered address, identifiers, status, activity and the officers, plus the raw registry payload. Shareholders and ultimate beneficial owners are sold by `POST /v3/kyb/shareholders/` and `POST /v3/kyb/ubo/`.

**Pairing with search.** Pass the candidate's `kyb_response_id` exactly as returned by a search of the same application. The handle is ephemeral and scoped to that search — select promptly, and re-search for a fresh handle rather than storing it.

**Billing.** Each select is billed at the country's Lite price (any search fee is separate); see [KYB registry pricing](/getting-started/kyb-registry-pricing). The balance is checked before any registry call (`403` when short) and the charge is recorded against the created business session.

**Persistence is mandatory.** Every select creates a business session (its id is the `request_id`) so billing and retrieval can be tracked; it appears in the console. `save_api_request` is accepted for symmetry but must be `true` (the default) — sending `false` returns `400`.

Use this endpoint after `POST /v3/kyb/search/` returns candidate companies.

Select is the **Lite** tier: it retrieves the company profile and its officers, billed at the country's Lite price ([per-country prices](/getting-started/kyb-registry-pricing)). It stores the request as a Manual Check in the Business Console and returns a `request_id` you can use to retrieve the saved business verification result. For the shareholders or the ultimate beneficial owners use [`POST /v3/kyb/shareholders/`](/standalone-apis/kyb-registry-shareholders) or [`POST /v3/kyb/ubo/`](/standalone-apis/kyb-registry-ubo).

Didit waits for the source registry to finish before responding, so `fetch_status` is `resolved` in most responses. If a slow registry keeps the profile pending past that wait, the response returns `fetch_status: pending` with `data_resolved: false`, and Didit completes the saved check automatically as soon as the provider finishes — re-read the saved verification result instead of repeating the search, since a new search issues new `kyb_response_id` values.


# KYB Registry Shareholders
Source: https://docs.didit.me/standalone-apis/kyb-registry-shareholders

POST /v3/kyb/shareholders/
Retrieve the Lite profile **plus the direct shareholders** (natural persons and corporate entities, with their ownership bands) of one candidate returned by `POST /v3/kyb/search/`.

**Pairing with search.** Pass the candidate's `kyb_response_id` exactly as returned by a search of the same application. The search runs on the Lite registry chain; when the country's ownership data lives at another registry Didit re-finds the company there by registration number, at no extra cost.

**Billing.** Billed at the country's Shareholders price - see [KYB registry pricing](/getting-started/kyb-registry-pricing). When the registry holds no shareholder record for the company (or the country offers no ownership data at all) the Lite profile is delivered and billed instead: read `registry_tier_delivered` and `registry_ownership_status`. The balance is checked against the Shareholders price before any registry call (`403` when short).

**Availability.** v3 only. Every call creates a business session (its id is the `request_id`).

**Pending reports.** When a report is still being prepared, the endpoint returns 202 Accepted, kyb_registry.fetch_status=pending, and registry_tier_delivered=null. Keep request_id and retrieve GET /v3/session/{request_id}/decision/ until registry_checks[0].company.fetch_status is resolved. Didit completes the report automatically and charges the delivered tier once it is ready. Do not repeat the purchase while it is pending; every new POST creates a separate request.

Use this endpoint after `POST /v3/kyb/search/` returns candidate companies when you need the **direct shareholders** on top of the Lite profile.

It is billed at the country's Shareholders price ([per-country prices](/getting-started/kyb-registry-pricing)). Where the registry holds no shareholder record for the company, or the country offers no ownership data at all, the Lite profile is delivered and billed instead: `registry_tier_delivered` is `basic` and `registry_ownership_status` is `unavailable`.

When the report is still being prepared, the endpoint returns `202 Accepted`, `kyb_registry.fetch_status: "pending"`, and `registry_tier_delivered: null`.
Keep the returned `request_id` and retrieve `GET /v3/session/{request_id}/decision/` until `registry_checks[0].company.fetch_status` is `resolved`.
Didit completes the pending report automatically and charges the delivered tier once it is ready.
Do not repeat the purchase request while it is pending: each new POST creates a separate request.

Available on v3 only. `POST /v2/kyb/select/` and `POST /v3/kyb/select/` keep their contract and price.


# KYB Registry UBOs
Source: https://docs.didit.me/standalone-apis/kyb-registry-ubo

POST /v3/kyb/ubo/
Retrieve the Lite profile, the direct shareholders **and the ultimate beneficial owners** resolved through the ownership chain (`registry_data.ubo_resolution` carries the corporate parent chain) of one candidate returned by `POST /v3/kyb/search/`.

**Pairing with search.** Pass the candidate's `kyb_response_id` exactly as returned by a search of the same application. The search runs on the Lite registry chain; when the country's ownership data lives at another registry Didit re-finds the company there by registration number, at no extra cost.

**Billing.** Billed at the country's UBO price - see [KYB registry pricing](/getting-started/kyb-registry-pricing). The tier delivered is the highest the country and the registry can serve: Shareholders when the chain cannot be resolved, Lite when there is no ownership record at all; `registry_tier_delivered` names what was billed. The balance is checked against the UBO price before any registry call (`403` when short).

**Availability.** v3 only. Every call creates a business session (its id is the `request_id`).

**Pending reports.** When a report is still being prepared, the endpoint returns 202 Accepted, kyb_registry.fetch_status=pending, and registry_tier_delivered=null. Keep request_id and retrieve GET /v3/session/{request_id}/decision/ until registry_checks[0].company.fetch_status is resolved. Didit completes the report automatically and charges the delivered tier once it is ready. Do not repeat the purchase while it is pending; every new POST creates a separate request.

Use this endpoint after `POST /v3/kyb/search/` returns candidate companies when you need the **ultimate beneficial owners**: the shareholders plus the natural persons and corporate parents resolved through the ownership chain (`registry_data.ubo_resolution`).

It is billed at the country's UBO price ([per-country prices](/getting-started/kyb-registry-pricing)). The tier delivered is the highest the country and the registry can serve, and `registry_tier_delivered` names what was billed: `shareholders` when the chain could not be resolved, `basic` when there is no ownership record at all.

When the report is still being prepared, the endpoint returns `202 Accepted`, `kyb_registry.fetch_status: "pending"`, and `registry_tier_delivered: null`.
Keep the returned `request_id` and retrieve `GET /v3/session/{request_id}/decision/` until `registry_checks[0].company.fetch_status` is `resolved`.
Didit completes the pending report automatically and charges the delivered tier once it is ready.
Do not repeat the purchase request while it is pending: each new POST creates a separate request.

Available on v3 only. `POST /v2/kyb/select/` and `POST /v3/kyb/select/` keep their contract and price.


# Passive Liveness
Source: https://docs.didit.me/standalone-apis/passive-liveness

POST /v3/passive-liveness/
Detect presentation attacks — printed photos, screen replays, masks, deepfakes — from a single face image. No video, motion, or user interaction required.

**How it works.** The image is analyzed by a biometric model; the largest detected face is evaluated and a liveness `score` (0–100) is computed. `status` is `Declined` when any `error`-severity warning fires:
- `NO_FACE_DETECTED` — the liveness model found no face,
- `LOW_LIVENESS_SCORE` — score at or below `face_liveness_score_decline_threshold` (default `30`),
- `LIVENESS_FACE_ATTACK` — the model detected a presentation attack,
- `FACE_IN_BLOCKLIST` / `POSSIBLE_FACE_IN_BLOCKLIST` — the face matches an entry on your face blocklist.

`MULTIPLE_FACES_DETECTED` is a `warning`-severity signal (does not decline), and `DUPLICATED_FACE` / `POSSIBLE_DUPLICATED_FACE` are `information`-severity signals that the same face already appeared in another approved session (they never decline). `face_quality` and `face_luminance` (0–100, nullable) describe capture quality.

**Blocklist and duplicate screening.** Runs on **every** call — with or without `save_api_request` — by matching the detected face against your application's face search index. Prior faces with the same `vendor_data` are excluded from the entire index search — so re-running liveness for the same user does not trigger `DUPLICATED_FACE`, and a blocklisted face originating from a session with the caller's own `vendor_data` is also NOT flagged (`FACE_IN_BLOCKLIST` screening is bypassed for same-`vendor_data` faces).

**Billing.** Each `200` response consumes one Passive Liveness API credit (standalone APIs have no free tier). Insufficient balance returns `403` before any image processing.

**Session persistence and face enrollment (`save_api_request`, default `true`).** When `true`, the call is persisted as an API-type session (Business Console, `GET /v3/session/{sessionId}/decision/` via the returned `request_id`, `status.updated` webhook), the reference image and face crop are stored, and the detected face is **enrolled into your face search index** so later Face Search calls and duplicate checks can match it. When `false`, the call is one-shot: nothing is stored and the face is not enrolled (blocklist/duplicate screening still runs).

**Sandbox.** Sandbox API keys skip all processing and billing: after request validation (malformed input still returns `400`), the endpoint returns a static `Approved` mock payload, no session is persisted, and no credits are consumed.

**Authentication.** Send your application's API key in the `x-api-key` header. Missing or invalid credentials return `403` (`{"detail": "You do not have permission to perform this action."}`) — this API never returns `401`.

**Rate limit.** Shared write budget of 300 requests/min per API key across all POST/PATCH/DELETE endpoints; exceeding it returns `429`.



# Check Phone Code
Source: https://docs.didit.me/standalone-apis/phone-check

POST /v3/phone/check/
Verify the OTP delivered by [`POST /v3/phone/send/`](/standalone-apis/phone-send) and get the final verification result plus phone intelligence: carrier name and line type, virtual (VoIP) and disposable flags, and duplicate usage of the number across your sessions.

**How the check finds the verification.** Matching is by your application plus the E.164 `phone_number` — `request_id` is not an input. The most recent pending verification created within the last **5 minutes** is checked. If there is none (never sent, already finalized, or older than 5 minutes) the endpoint returns `200` with `status: "Expired or Not Found"`.

**Attempt budget.** Each verification allows **3 code attempts**. The first two wrong codes return `status: "Failed"` with the attempts remaining and `phone: null`; the third wrong code finalizes the verification as `Declined` with a `VERIFICATION_CODE_ATTEMPTS_EXCEEDED` warning and returns the full phone report.

**Outcomes.** `Approved` — correct code and no declining risk. `Declined` — terminal: the code was correct but a declining risk matched (a `DECLINE` action below, a blocklisted or high-risk number), or the attempt budget was exhausted. `Failed` — wrong code, attempts remaining. `Expired or Not Found` — nothing to check. On `Approved`/`Declined` the `request_id` equals the send's `request_id` (the session id) and `phone` carries the full report (`carrier`, `is_virtual`, `is_disposable`, `warnings`, `lifecycle`, `matches`); on `Failed` and `Expired or Not Found` the `request_id` is a one-off random UUID.

**Risk actions.** `duplicated_phone_number_action`, `disposable_number_action`, and `voip_number_action` decide what happens when the corresponding risk is detected on a correct code: `DECLINE` flips the final status to `Declined`; `NO_ACTION` (default) records the risk in `phone.warnings` without affecting the status.

**Billing.** Checks are free — delivery is billed on the send side (see [Phone Verification Pricing](/getting-started/phone-verification-pricing)).

**Session persistence.** A finalized check updates the session created by the send (visible in the Business Console, queryable via `GET /v3/session/{sessionId}/decision/`) and fires a `status.updated` webhook.

**Sandbox.** Sandbox API keys skip all processing: any well-formed code (4–8 digits, `123456` included) returns a static `Approved` payload with a simplified flat `phone` object (`status`, `phone_number`, `country_code`, `carrier_name`, `line_type`, `flags`); malformed input still returns `400`. Nothing is persisted.

**Authentication.** Send your application's API key in the `x-api-key` header. Missing or invalid credentials return `403` (`{"detail": "You do not have permission to perform this action."}`) — this API never returns `401`.

**Rate limits.** Shared write budget of 300 requests/min per API key, plus the upstream anti-abuse cap of 4 attempts per number per hour; exceeding either returns `429`.

**Social footprint.** Set `enable_social` to `true` to add a `phone_social` block: the online platforms this number is registered on, with per-category counts and any profile details available. `profiles_registered: 0` means the platforms were checked and the number was found on none of them - a valid, billable answer. The block is absent when the add-on was not requested or the check could not be completed, and it is not billed in that case. Billing adds one `phone_social` unit per request on top of this endpoint's own price.

## Handle provider outages

If the phone provider is temporarily unavailable, this endpoint returns `502` with a stable machine-readable code:

```json theme={null}
{
  "detail": "The phone verification provider is temporarily unavailable.",
  "code": "phone_provider_unavailable"
}
```

Treat this response as retryable. Use a short backoff and show the user a temporary-service message instead of asking them to change a valid phone number or code.


# Phone Risk API
Source: https://docs.didit.me/standalone-apis/phone-risk

POST /v3/phone/risk/
Risk-score a phone number without sending an OTP. Carrier, line type, porting, disposable-number, and fraud signals in one server-to-server call.

Use `POST /v3/phone/risk/` when you need phone intelligence before, instead of, or outside an OTP flow.

It does not send a code to the user. It creates an API session, enriches the number, applies your phone-risk rules, and returns the same normalized phone block used by Phone Verification in one synchronous response.

When the request is saved, Didit can also use the scored phone number as aggregate evidence in **Networks**. Network graphs may show high-risk phone intelligence, porting and line-type context on shared phone signals, but they do not reveal the raw phone number to other organizations.

## Interpret the response

* `status` is the final decision for this API session. It is normally `Approved`; the risk evaluation can produce `In Review` or `Declined`.
* `phone.full_number` is the normalized E.164 number. `phone.phone_number_prefix` and `phone.phone_number` split it into the international prefix and national number.
* `phone.is_disposable` and `phone.is_virtual` are the stable yes/no signals for application logic. The carrier lookup adds `carrier.name` and `carrier.type` (`mobile`, `voip`, and similar).
* `phone.phone_intelligence.score` uses a 0-100 risk scale where a higher number means higher risk. `phone_type_risk` (`Low`, `Medium`, `High`) and `phone_trust_index` (inverse of the score) are derived views.
* `phone.phone_intelligence` and `phone.enrichment` are compatibility aliases with the same normalized object. New integrations can read `phone.enrichment`.
* `phone.matches` lists other sessions of your application where the same number was used by a different user. Use it for duplicate-account detection.
* `request_id` is the API session id. Store it with `vendor_data` if you need to correlate the result with later webhooks or console activity.

<Warning>
  `phone.phone_intelligence` and `phone.enrichment` are best-effort fields. A completed lookup can omit both when no usable intelligence data is returned for that number, country, or plan. Build rules on the stable normalized fields first and treat missing intelligence as "unknown", not "safe".
</Warning>

## Social footprint add-on

Set `enable_social` to `true` to add a `phone_social` block to the response under `phone`: the online platforms this phone number is registered on, grouped by category, with the summary counts and any profile details our data partners return.

* `phone.phone_social.profiles_registered` and `phone.phone_social.profiles_checked` are the headline numbers: platforms where the phone number is confirmed registered, out of the platforms evaluated.
* `phone.phone_social.registered_platforms` and `phone.phone_social.not_registered_platforms` list each platform with its `category` and `scope` (`global`, or `local` for region-specific platforms).
* `phone.phone_social.categories` gives the registered count and ratio per category, and `phone.phone_social.profiles` carries per-platform profile details when a platform exposes them (name, photo URL, about text, privacy status, business-account flag).
* Summary indexes (`digital_footprint_diversity`, `digital_sophistication_index`, `engagement_depth_index`, `subscription_affordability_index`) are 0-10 composites. Every count can be `null` when the check returned no data for it.

`profiles_registered: 0` is a real answer, not a failure: the platforms were checked and the phone number was found on none of them, which is a common synthetic-identity signal. This endpoint does not act on it by itself - use `phone_no_social_presence_action` in a workflow to turn it into a Review or Decline verdict.

The block is absent when `enable_social` is not set, and also when the social check could not be completed - in which case it is not billed.

## Sandbox behavior

Sandbox keys validate the request and return deterministic approved data. They do not send an OTP, consume credits, create a session, or contribute to Networks. With `enable_social` set, they also return a deterministic `phone_social` block.

## Billing

Phone Risk API calls use Phone Risk API pricing, lower than full Phone Verification because no OTP is sent. A live request is billable once the lookup starts, even when some best-effort fields are unavailable.

The social footprint add-on is billed separately: one `phone_social` unit per request on top of the Phone Risk API price, whenever the check completes. The credit check before the lookup covers both.


# Send Phone Code
Source: https://docs.didit.me/standalone-apis/phone-send

POST /v3/phone/send/
Send a one-time passcode (OTP) to a phone number over WhatsApp, SMS, or another supported channel, then verify it with [`POST /v3/phone/check/`](/standalone-apis/phone-check).

**How send and check pair up.** Verification state is keyed by your application plus the E.164 `phone_number` — the check call does not take `request_id`. Each new send creates a pending verification that lives for **5 minutes**: call the check with the same number and the code the user received before the window closes. Calling send again for the same number while a verification is pending re-sends a code for that same verification (`status: "Retry"`, same `request_id`). At most one retry is attached this way (two sends total); a further send starts a fresh verification with a new `request_id`. The 5-minute window is measured from the first send and is not extended by retries.

**Delivery channels.** `options.preferred_channel` selects the channel (`whatsapp` by default; `sms`, `telegram`, `voice`, `rcs`, `viber`, and `zalo` are also supported). When the preferred channel is unavailable for the destination country or number, delivery automatically falls back to SMS — the send still reports `Success`, and the channel actually used is reported by the check response (`phone.verification_method` and the `lifecycle` events).

**Send statuses.** `Success` — OTP sent for a new verification; `Retry` — OTP re-sent for the pending verification; `Blocked` — the anti-fraud layer refused to send (see `reason`, e.g. `repeated_attempts`, `suspicious`, `spam`). A `Blocked` send immediately finalizes the verification as `Declined` with a high-risk warning, so a follow-up check returns `Expired or Not Found`.

**Billing.** The price depends on the destination country and the channel that actually delivers the message — see [Phone Verification Pricing](/getting-started/phone-verification-pricing). Only `Blocked` sends are guaranteed free: any other unbilled send attempt is charged at verification finalization or expiration, even if delivery was never confirmed or the delivery provider reported the message undeliverable. Checks are always free. As an anti-abuse measure, phone verification is disabled until your organization's first top-up (`403`).

**Session persistence.** Every new verification is persisted as an API-type session: `request_id` is a real session id you can pass to `GET /v3/session/{sessionId}/decision/`, the verification appears in the Business Console, and `status.updated` webhooks fire as it progresses.

**Sandbox.** Sandbox API keys skip delivery and billing: after request validation (malformed input still returns `400`), the endpoint returns a static `Success` payload with a random `request_id`; no message is sent and nothing is persisted. Use code `123456` on the sandbox check.

**Authentication.** Send your application's API key in the `x-api-key` header. Missing or invalid credentials return `403` (`{"detail": "You do not have permission to perform this action."}`) — this API never returns `401`.

**Rate limits.** Shared write budget of 300 requests/min per API key across all POST/PATCH/DELETE endpoints, plus an anti-abuse cap of 4 send attempts per phone number per hour; exceeding either returns `429`.

## Handle provider outages

If the phone provider is temporarily unavailable, this endpoint returns `502` with a stable machine-readable code:

```json theme={null}
{
  "detail": "The phone verification provider is temporarily unavailable.",
  "code": "phone_provider_unavailable"
}
```

Treat this response as retryable. Use a short backoff and show the user a temporary-service message instead of asking them to change a valid phone number or code.


# Phone Verification API
Source: https://docs.didit.me/standalone-apis/phone-verification

Two-step SMS OTP verification with carrier, virtual number, and disposable detection. Pay-per-use pricing, no contracts, 500 free per month.

The Phone Verification API provides a two-step flow: send a one-time code to a phone number, then verify the code. The system detects carrier type, virtual numbers, and disposable phones.

## Endpoints

<CardGroup>
  <Card title="Send Phone Code" icon="paper-plane" href="/standalone-apis/phone-send">
    `POST /v3/phone/send/` — Send a one-time verification code via SMS.
  </Card>

  <Card title="Check Phone Code" icon="circle-check" href="/standalone-apis/phone-check">
    `POST /v3/phone/check/` — Verify the code and retrieve phone risk data.
  </Card>

  <Card title="Score Phone Risk" icon="shield-alert" href="/standalone-apis/phone-risk">
    `POST /v3/phone/risk/` — Score carrier, line type, porting, and fraud risk without sending an OTP.
  </Card>
</CardGroup>

## How it works

1. Call **Send Phone Code** with the phone number in E.164 format (e.g., `+14155552671`)
2. The user receives a code via SMS (valid for 5 minutes)
3. Call **Check Phone Code** with the phone number and code
4. Receive verification result plus risk signals (carrier type, virtual number detection)

## Delivery channels

Didit supports multiple channels depending on country availability:

| Channel  | Description                 |
| -------- | --------------------------- |
| SMS      | Standard text message       |
| WhatsApp | WhatsApp messaging          |
| Telegram | Telegram messaging          |
| RCS      | Rich Communication Services |
| Viber    | Viber messaging             |

## Risk signals

| Signal          | Description                      |
| --------------- | -------------------------------- |
| `is_disposable` | Temporary/throwaway phone number |
| `is_virtual`    | VoIP or virtual number           |
| `carrier.type`  | `mobile`, `landline`, or `voip`  |

For full response structure, see [Phone Verification Report](/core-technology/phone-verification/overview).

## Provider outages

If the upstream phone provider fails to answer a send or check request, both endpoints return `502` with `code: "phone_provider_unavailable"` instead of a generic error. This is safe to retry, is not billed, and does not consume an attempt from the per-number hourly cap. Branch on `code` rather than parsing the `detail` message, since the message text is not a stable contract.


# Proof of Address API
Source: https://docs.didit.me/standalone-apis/proof-of-address

POST /v3/poa/
Extract and validate a Proof of Address document — utility bills, bank statements, and government-issued documents — in one call. Returns the issuer, issue/expiry dates, the holder name, the raw and parsed/geocoded address, an `Approved`/`Declined` `status`, and a `warnings` list explaining every issue found.

**Latency.** Extraction is LLM-based: typical calls take **5–15 seconds**, multi-page PDFs up to **~30 seconds**. Configure a client timeout of **at least 45 seconds** and do not retry before the call completes.

**How it works.** The document (image or PDF, up to 15 MB; encrypted PDFs require `document_password`) is classified into a document type and subtype (e.g. `UTILITY_BILL` / `WATER_BILL`), and the issuer, dates, holder name, and address are extracted with LLM-based extraction. The address is parsed and geocoded into `poa_parsed_address`. PDF/EXIF forensics screen for tampering — modification after digital signing, known PDF editors, overlay-text manipulation, suspicious re-exports — surfacing `SUSPECTED_DOCUMENT_MANIPULATION` or `DOCUMENT_METADATA_MISMATCH`. Document age is validated against `poa_document_age_months`, and the language against `poa_languages_allowed`. If you pass `expected_address`, `expected_country`, or `expected_first_name`/`expected_last_name`, the extracted values are cross-checked and mismatches are flagged.

**Decision logic.** `status` is `Approved` unless at least one warning resolves to a decline. Hard failures always decline: `MISSING_ADDRESS_INFORMATION`, `POA_DOCUMENT_EXPIRED`, `INVALID_DOCUMENT_TYPE`, `UNABLE_TO_VALIDATE_DOCUMENT_AGE`, plus `UNABLE_TO_EXTRACT_ISSUE_DATE` and `POA_NAME_NOT_DETECTED` (not configurable on this endpoint). Five risk groups are configurable per request via the `poa_*_action` options (`DECLINE` or `NO_ACTION`, all defaulting to `DECLINE`). `POA_DOCUMENT_NOT_SUPPORTED_FOR_APPLICATION` and `UNPARSABLE_OR_INVALID_ADDRESS` are informational on this endpoint and never decline. A document that cannot be processed at all returns `400`; a readable but problematic document returns `200` with `status: "Declined"` — always inspect `poa.status` and `poa.warnings`, not just the HTTP code.

**Billing.** Each `200` response consumes one Proof of Address API credit (standalone APIs have no free tier). When the organization's balance cannot cover the call, the endpoint returns `403` with the not-enough-credits error before any document processing.

**Session persistence (`save_api_request`, default `true`).** When `true`, the call is persisted as an API-type session: it appears in the Business Console, the uploaded document is stored, the returned `request_id` is a real session id you can pass to `GET /v3/session/{sessionId}/decision/` (the decision additionally exposes `document_file` and the `document_metadata` forensics, which this response omits), and a `status.updated` webhook is emitted. When `false`, nothing is stored and `request_id` is a one-off correlation UUID that cannot be looked up later.

**Sandbox.** Sandbox API keys skip all processing and billing: after request validation (malformed input still returns `400`), the endpoint returns a static `Approved` mock payload (a fictional "Sandbox Power Co." electricity bill), no session is persisted, and no credits are consumed.

**Authentication.** Send your application's API key in the `x-api-key` header. Missing or invalid credentials return `403` (`{"detail": "You do not have permission to perform this action."}`) — this API never returns `401`.

**Rate limit.** Shared write budget of 300 requests/min per API key across all POST/PATCH/DELETE endpoints; exceeding it returns `429`.

Note: `FUTURE_ISSUE_DATE` and `POOR_DOCUMENT_QUALITY` exist in workflow sessions but are never produced by this standalone endpoint — a future-dated document is not auto-declined here.



# Alerts
Source: https://docs.didit.me/transaction-monitoring/alerts

Lifecycle of transaction alerts: created from rules, providers, or analysts; triaged, linked to cases, and resolved. Pay-per-call $0.02 per transaction.

An **alert** is a record that a transaction or pattern requires attention — either from a rule match, a provider flag (sanctions, wallet risk), or a manual analyst escalation. Alerts are the unit of triage in the Business Console.

## Alert lifecycle

```mermaid theme={null}
stateDiagram-v2
    [*] --> OPEN: Created (rule, provider, manual)
    OPEN --> INVESTIGATING: Analyst picks up
    OPEN --> DISMISSED: Clear false positive
    INVESTIGATING --> AWAITING_USER: Need user input
    AWAITING_USER --> INVESTIGATING: User responded
    INVESTIGATING --> PENDING_SAR: Preparing SAR filing
    PENDING_SAR --> SAR_FILED: SAR submitted to regulator
    INVESTIGATING --> RESOLVED: Closed — action taken
    INVESTIGATING --> DISMISSED: Closed — no action
    SAR_FILED --> [*]
    RESOLVED --> [*]
    DISMISSED --> [*]
```

## Alert sources

| Source     | Description                                                                                                                  |
| ---------- | ---------------------------------------------------------------------------------------------------------------------------- |
| `RULE`     | Generated by a matched transaction rule. Most alerts.                                                                        |
| `PROVIDER` | Generated by an external provider — wallet screening hit, sanctions match on counterparty, transaction screening escalation. |
| `MANUAL`   | Opened by an analyst from the console.                                                                                       |

## Alert statuses

| Status          | Meaning                                                                       |
| --------------- | ----------------------------------------------------------------------------- |
| `OPEN`          | Not yet picked up by an analyst.                                              |
| `INVESTIGATING` | An analyst is actively reviewing.                                             |
| `AWAITING_USER` | Blocked on user action (remediation session pending).                         |
| `PENDING_SAR`   | Analyst has decided to file a Suspicious Activity Report; filing in progress. |
| `SAR_FILED`     | SAR has been filed with the regulator.                                        |
| `RESOLVED`      | Alert closed with an action (e.g. user blocked, funds held).                  |
| `DISMISSED`     | Alert closed as a false positive. No action taken.                            |

## Alert fields

| Field                   | Description                                                       |
| ----------------------- | ----------------------------------------------------------------- |
| `uuid`                  | Alert ID                                                          |
| `title`                 | Short description (auto-generated from the rule)                  |
| `description`           | Longer description or analyst notes                               |
| `severity`              | Nullable — legacy field; use the alert's associated score instead |
| `source`                | `RULE`, `PROVIDER`, or `MANUAL`                                   |
| `assigned_to`           | Analyst currently owning the alert                                |
| `due_at`                | SLA deadline for resolution                                       |
| `linked_case_id`        | If linked to an investigation case                                |
| `linked_transaction_id` | The transaction that generated the alert                          |
| `resolved_at`           | When the alert reached a terminal state                           |

## Linking alerts to cases

A single alert might be small enough to resolve on its own. Larger or pattern-based investigations warrant a **case** — a container for multiple alerts, transactions, users, and evidence.

See [Cases](/transaction-monitoring/cases) for the case model.

Link from the alert detail pane: *Alerts → \[alert] → Link to case*. You can link to an existing case or create a new one from the alert.

## SAR workflow

For jurisdictions requiring Suspicious Activity Reports (SARs) or CTRs (Currency Transaction Reports):

1. Move the alert to `PENDING_SAR` and attach supporting evidence.
2. Generate the SAR filing (PDF + structured metadata) via *Alerts → \[alert] → Generate SAR*.
3. Submit to your regulator's portal through your usual filing channel.
4. Mark the alert as `SAR_FILED` and record the filing reference number.

Didit does not directly submit SARs to regulators — SAR filing remains your compliance team's responsibility. The console generates the artifact (form + evidence) to streamline the process.

## Console workflow

### Alerts list

Located at *Transactions → Alerts*. Columns: `Alert ID`, `Title`, `Transaction`, `Applicant`, `Status`, `Assigned to`, `Due date`, `Source`, `Severity`.

Filters: by status, source, severity, assigned analyst, date range. Saved views supported.

### Alert triage

Double-click an alert to open the triage surface:

* **Summary** — rule that fired, transaction context, score, matched conditions.
* **Transaction** — the underlying transaction with all parties and payment methods.
* **User / Business** — linked [entity](/entities/overview) profile.
* **Related alerts** — other alerts tied to the same user or pattern.
* **Actions** — assign, add note, link to case, close (resolve / dismiss), generate SAR.

### Bulk actions

From the alerts list:

* **Bulk assign** to an analyst.
* **Bulk dismiss** (use with care — logged to audit).
* **Bulk link to case** to group related alerts into one investigation.

## Assignment and SLAs

* Alerts can be auto-assigned to a round-robin analyst pool configured at *Settings → Team → Analyst pool*.
* `due_at` is computed from the alert's severity and your SLA matrix at *Settings → Transaction Monitoring → SLAs*.
* Overdue alerts are surfaced on the Alerts dashboard and via weekly email digests.

## Alert webhooks

Alerts currently flow through the `transaction.status.updated` webhook and are surfaced in the transaction response. Dedicated alert lifecycle webhooks are on the roadmap — subscribe to application changelog for updates.

## Programmatic access

Alert CRUD is **console-only** in the public API today — there is no public alert endpoint in this openapi spec. Use the console to triage and resolve alerts. Transactions with alerts can be retrieved via `GET /v3/transactions/` and inspected in bulk.

## Next steps

<CardGroup>
  <Card title="Cases" icon="folder-open" href="/transaction-monitoring/cases">
    Full investigation workflow.
  </Card>

  <Card title="Rules" icon="scale-balanced" href="/transaction-monitoring/rules">
    What generates alerts.
  </Card>

  <Card title="Console" icon="desktop" href="/transaction-monitoring/console">
    Console UI walkthrough.
  </Card>
</CardGroup>


# Crypto & Wallet Screening
Source: https://docs.didit.me/transaction-monitoring/aml-screening

Automated wallet and transaction-hash screening with risk scores, exposure analysis, and network graphs. Wallet screening starts at $0.15 per check.

For cryptocurrency transactions, Didit can screen wallet addresses and transaction hashes against blockchain analytics providers such as Merkle Science, Crystal, Chainalysis, Elliptic, and TRM Labs during transaction creation. Screening runs server-side — no additional API calls are needed from your side.

<Tip>
  Need to screen an address **without** a transaction? Use the [on-demand wallet screening](/transaction-monitoring/wallet-screening) endpoint (`POST /v3/wallet-screening/`) to get the same risk result for a single wallet with one API call.
</Tip>

## How screening triggers

Crypto screening runs automatically when both conditions are met:

1. The transaction has `currency_kind: "crypto"` in its transaction details
2. Transaction monitoring is enabled in your [application settings](/transaction-monitoring/settings)

You can override this default per transaction with `include_crypto_screening` in the create transaction payload:

| Value             | Behaviour                                                              |
| ----------------- | ---------------------------------------------------------------------- |
| `true`            | Run crypto screening even if the application-level default is disabled |
| `false`           | Skip crypto screening even if the application-level default is enabled |
| omitted or `null` | Use the application-level default configured in the Console            |

<Tip>
  The application-level default lives in **Transactions** > **Settings** in the Business Console. `include_crypto_screening` only overrides that default for the single transaction you are creating.
</Tip>

## Inbound vs outbound

`transaction_details.direction` is required because it tells Didit which side of the transfer should be screened.

| Direction                  | Before the on-chain transfer                                                                         | After the on-chain transfer                                                                                        |
| -------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
| **Inbound** (deposits)     | Screen the counterparty sender wallet, if you provide it in `counterparty.payment_method.account_id` | Screen the transaction hash scoped to your service/customer deposit address in `subject.payment_method.account_id` |
| **Outbound** (withdrawals) | Screen the destination wallet in `counterparty.payment_method.account_id` before you send funds      | Screen the transaction hash scoped to the same destination wallet in `counterparty.payment_method.account_id`      |

For pre-transfer screening, omit `transaction_details.payment_reference_id`; Didit runs wallet screening on the relevant wallet address. For post-transfer screening, include the blockchain transaction hash in `transaction_details.payment_reference_id`; Didit runs transaction screening and stores transaction summary data when on-chain enrichment is available.

## Required fields

For all crypto screening requests, send:

* `transaction_details.direction` — `INBOUND` or `OUTBOUND`
* `transaction_details.currency_kind` — `crypto`
* `transaction_details.currency` — the asset or chain identifier, for example `BTC`, `ETH`, or `SOL`
* A wallet address in the participant selected by the direction rules above

For transaction-hash screening after the transfer is on-chain, also send:

* `transaction_details.payment_reference_id` — the blockchain transaction hash

If crypto screening is enabled and the required wallet address for the direction is missing, the Create Transaction API rejects the request.

## Example: pre-transfer outbound screening

Before sending funds, create an outbound crypto transaction without a transaction hash. Didit screens the destination wallet.

```json theme={null}
{
  "transaction_id": "withdrawal-001",
  "transaction_category": "finance",
  "include_crypto_screening": true,
  "transaction_details": {
    "direction": "OUTBOUND",
    "amount": "0.25",
    "currency": "ETH",
    "currency_kind": "crypto",
    "action_type": "withdrawal"
  },
  "subject": {
    "entity_type": "individual",
    "vendor_data": "user-123",
    "full_name": "John Doe"
  },
  "counterparty": {
    "entity_type": "unhosted_wallet",
    "full_name": "John Doe",
    "payment_method": {
      "method_type": "crypto_wallet",
      "account_id": "0xRecipientWallet..."
    }
  }
}
```

## Example: post-transfer inbound screening

After receiving funds, include the transaction hash. Didit screens the transaction hash scoped to your deposit address and enriches the response with transaction summary information where available.

```json theme={null}
{
  "transaction_id": "deposit-001",
  "transaction_category": "finance",
  "include_crypto_screening": true,
  "transaction_details": {
    "direction": "INBOUND",
    "amount": "0.25",
    "currency": "ETH",
    "currency_kind": "crypto",
    "action_type": "deposit",
    "payment_reference_id": "0xTransactionHash..."
  },
  "subject": {
    "entity_type": "individual",
    "vendor_data": "user-123",
    "full_name": "John Doe",
    "payment_method": {
      "method_type": "crypto_wallet",
      "account_id": "0xYourServiceDepositAddress..."
    }
  },
  "counterparty": {
    "entity_type": "unhosted_wallet",
    "full_name": "John Doe"
  }
}
```

## Supported providers

| Provider           | Status                                 | Managed pricing  | Connected-key pricing |
| ------------------ | -------------------------------------- | ---------------- | --------------------- |
| **Merkle Science** | Available                              | \$0.15/screening | \$0.02/screening      |
| **Crystal**        | Connect a provider key via Marketplace | Not available    | \$0.02/screening      |
| **Chainalysis**    | Connect a provider key via Marketplace | Not available    | \$0.02/screening      |
| **Elliptic**       | Connect a provider key via Marketplace | Not available    | \$0.02/screening      |
| **TRM Labs**       | Connect a provider key via Marketplace | Not available    | \$0.02/screening      |

Configure your preferred provider in **Transactions** > **Settings** > **Provider Preferences** in the [Business Console](https://business.didit.me), or connect your own provider key from the console **Marketplace** (Crypto monitoring category).

<Tip>
  With **connected-key pricing**, you connect an existing provider API key and pay the listed infrastructure fee per screening. Use this option when you already have a commercial agreement with a blockchain analytics provider.
</Tip>

## Screening results

Each screening produces a standardised result regardless of which provider is used.

### Risk score and severity

Every screened wallet or transaction receives:

* **Risk score** (0–100) — higher scores indicate greater exposure to risky entities
* **Severity level** — derived from the score: `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`

### Source of funds analysis

A percentage breakdown of where the funds originated, categorised by entity type:

| Category                 | Risk level | Description                                              |
| ------------------------ | ---------- | -------------------------------------------------------- |
| `SANCTIONED`             | Critical   | Entities on international sanctions lists (OFAC, EU, UN) |
| `TERRORIST_FINANCING`    | Critical   | Addresses linked to terrorist financing                  |
| `CHILD_EXPLOITATION`     | Critical   | Addresses linked to child exploitation material          |
| `RANSOMWARE`             | High       | Ransomware payment addresses                             |
| `STOLEN_FUNDS`           | High       | Addresses associated with known theft or hacks           |
| `DARKNET_MARKET`         | High       | Darknet marketplace addresses                            |
| `MIXER`                  | High       | Mixing or tumbling services used to obscure fund origins |
| `SCAM`                   | High       | Known scam or fraud addresses                            |
| `HIGH_RISK_EXCHANGE`     | Medium     | Exchanges with weak KYC/AML controls                     |
| `HIGH_RISK_JURISDICTION` | Medium     | Entities in FATF-listed high-risk jurisdictions          |
| `GAMBLING_UNLICENSED`    | Medium     | Unlicensed gambling platforms                            |
| `P2P_EXCHANGE`           | Low        | Peer-to-peer exchange services                           |
| `EXCHANGE`               | Low        | Regulated cryptocurrency exchanges                       |
| `UNNAMED_SERVICE`        | Low        | Unidentified services                                    |

Each entity in the breakdown includes the percentage of funds, received and sent amounts, and whether the connection is direct or indirect.

### Exposure table

An exposure table showing source, destination, and counterparty entities, including:

* Entity name and category
* Direct vs. indirect connection (hop distance)
* Received and sent amounts
* Risk level per entity

### Network graph

A visual node-edge representation of the wallet's transaction relationships:

* **Nodes** represent wallets, exchanges, services, and other entities
* **Edges** represent transactions between nodes, with amounts and transaction hashes
* **Metrics** include graph-level statistics such as centrality and depth

The network graph is available in the [Business Console](/transaction-monitoring/console) as an interactive visualization.

## Integration with rules

Screening results feed directly into the [rules engine](/transaction-monitoring/rules). Didit includes preset rules that fire automatically based on screening data:

| Preset rule                                  | Action                                     |
| -------------------------------------------- | ------------------------------------------ |
| **Sanctions counterparty**                   | Immediate decline — any sanctions exposure |
| **Terrorist financing / child exploitation** | Immediate decline                          |
| **Darknet market exposure**                  | Add score + flag for review                |
| **Mixer/obfuscation service exposure**       | Add score + flag for review                |
| **High-risk source of funds (>30%)**         | Add score + flag for review                |
| **Multiple risky counterparties**            | Add score + flag for review                |
| **Medium wallet risk score**                 | Add score + flag for review                |
| **Screening pending**                        | Hold transaction until screening completes |

After screening completes, Didit automatically re-evaluates all rules against the enriched transaction data and triggers any applicable webhooks.

## Next steps

<CardGroup>
  <Card title="Submitting transactions" icon="arrow-right-to-bracket" href="/transaction-monitoring/transactions">
    How to submit transactions including crypto wallet details.
  </Card>

  <Card title="Rules & scoring" icon="scale-balanced" href="/transaction-monitoring/rules">
    How screening results feed into the rule engine.
  </Card>

  <Card title="Console guide" icon="gauge" href="/transaction-monitoring/console">
    Viewing crypto screening analysis, source of funds, and network graphs in the console.
  </Card>
</CardGroup>


# Cases & Investigations
Source: https://docs.didit.me/transaction-monitoring/cases

Open investigation cases from flagged transactions and alerts, then work them in the shared Case Management module. $0.02 per transaction.

When transactions are flagged by rules, Didit creates **alerts** that can be organized into **cases** for structured investigation. Cases group related transactions, track investigation progress, and maintain an audit trail.

<Note>
  Cases created from transaction rules use the same [Case Management](/console/case-management/cases) module as every other case in the console, one lifecycle, one API, whether a case started from a rule, an AML hit, a workflow, or a manual click. This page covers the transaction-monitoring-specific pieces: alerts and the **Create case** rule effect. For the full case lifecycle, blueprints, checklist, 4-eyes review, and FIU reporting, see [Case Management](/console/case-management/cases).
</Note>

## Alerts

Every time a rule matches a transaction, an **alert** is created. Alerts can also be created manually by analysts or by external providers.

### Alert sources

| Source       | Description                                                 |
| ------------ | ----------------------------------------------------------- |
| **Rule**     | Automatically created when a transaction rule matches       |
| **Provider** | Created by an external AML or blockchain analytics provider |
| **Manual**   | Created manually by an analyst from the console             |

### Alert statuses

| Status          | Description                                          |
| --------------- | ---------------------------------------------------- |
| `OPEN`          | New alert, not yet reviewed                          |
| `INVESTIGATING` | An analyst is actively working on this alert         |
| `AWAITING_USER` | Additional information is needed from the user       |
| `PENDING_SAR`   | Under review for a Suspicious Activity Report filing |
| `SAR_FILED`     | A Suspicious Activity Report has been filed          |
| `RESOLVED`      | Investigation complete, no further action needed     |
| `DISMISSED`     | Alert reviewed and determined to be a false positive |

## Opening a case from a rule

Add the **Create case** effect to a [transaction rule](/transaction-monitoring/rules) to open cases automatically whenever it matches:

* **Blueprint** the case routes to (assignment, escalation, 4-eyes, and case-page content all come from the blueprint, see [Blueprints](/console/case-management/blueprints))
* **Grouping**: **By applicant** reuses the subject's open case across every rule; **By rule and applicant** opens one case per rule per applicant
* **Attach matched transaction**, to link the triggering transaction to the case automatically

Cases created this way carry source `TRANSACTION_RULE` and are anchored to the transaction's subject (a user or a business), the same [one-subject-per-case](/console/case-management/cases#one-subject-per-case) rule every case follows.

You can also open a case manually from any transaction with **Add to case**, either attaching it to an existing open case for the same subject or creating a new one. See [Creating cases](/console/case-management/creating-cases) for every entry point.

## Case lifecycle and resolution

Cases move through **Open**, **Awaiting user**, and **Resolved**, closing with resolution **False positive** or **Valid threat**. See [Cases](/console/case-management/cases) for the full lifecycle, and [FIU Reports & Templates](/console/case-management/fiu-reports) to generate a SAR, STR, CTR, or other filing from a resolved investigation.

## API

Cases opened from transaction rules are fully manageable through the [Management API](/management-api/cases/list), list, create, resolve, attach transactions as links, and pull [case analytics](/management-api/cases/statistics) for your own dashboards.

## Next steps

<CardGroup>
  <Card title="Alerts" icon="bell" href="/transaction-monitoring/alerts">
    Alert lifecycle, sources, and SAR workflow.
  </Card>

  <Card title="Case Management" icon="folder-open" href="/console/case-management/cases">
    Full lifecycle, lists, blueprints, and 4-eyes review.
  </Card>

  <Card title="FIU Reports" icon="file-lines" href="/console/case-management/fiu-reports">
    Templates, report types, and printable filings.
  </Card>
</CardGroup>


# Transaction Monitoring Console
Source: https://docs.didit.me/transaction-monitoring/console

Review transactions, tune rules, investigate alerts, and monitor analytics in the Didit Business Console. Pay-per-call $0.02 per transaction, no contracts.

The **Transactions** section in the Business Console provides a complete workspace for transaction monitoring, investigation, and analytics.
Its tab bar exposes five views: **Transactions** (the list), **Overview**, **Rules**, **Travel Rule**, and **Settings**.

## Transaction list

The main Transactions view shows all submitted transactions with:

| Column             | Description                                             |
| ------------------ | ------------------------------------------------------- |
| **Transaction ID** | Your external transaction identifier (`txn_id`)         |
| **Status**         | `APPROVED`, `IN_REVIEW`, `DECLINED`, or `AWAITING_USER` |
| **Score**          | Risk score from the rules engine                        |
| **Severity**       | Highest severity of matched rules                       |
| **Amount**         | Transaction amount and currency                         |
| **Direction**      | `INBOUND` or `OUTBOUND`                                 |
| **Tags**           | Application-defined tags for categorization             |
| **Created**        | Timestamp of transaction submission                     |

Filter by status, severity, date range, tags, direction, or search by transaction ID.

## Transaction detail

Click a transaction to see:

* **Score breakdown** — which rules matched and their individual contributions
* **Linked parties** — applicant and counterparty details
* **Payment method** — card, bank transfer, crypto wallet details
* **Crypto Monitoring** — for crypto transactions, a dedicated section showing:
  * Provider risk score and severity badge (Crystal, Merkle Science, etc.)
  * Transfer details (transaction hash, wallet address, blockchain, direction)
  * **Source of funds** tab — pie chart of entity type distribution and sortable entity table with received/sent amounts and hop distances
  * **Counterparty connections** tab — entities the wallet has transacted with, filterable by direct/indirect exposure
  * **Visualization** button — interactive graph view of wallet relationships and fund flows using a node-edge diagram
* **Travel rule** — for virtual asset transfers, a dedicated tab showing the exchange status, rail, counterparty VASP (name, LEI, due-diligence score), the IVMS originator/beneficiary data cards, and the full status timeline. Analysts with write access can act directly from here: **Confirm/Reject ownership** (`UNCONFIRMED_OWNERSHIP`), **Confirm corrected address** (`COUNTERPARTY_MISMATCHED_DATA`), **Resend transfer** (unroutable outbound transfers), **Finish transfer** (report the on-chain hash on a `COMPLETED` outbound transfer), and **Cancel transfer**. See [Travel rule](/transaction-monitoring/travel-rule)
* **Network graph** — interactive node-edge visualization of transaction relationships and fund flows. See [crypto screening](/transaction-monitoring/aml-screening)
* **Related transactions** — other transactions involving the same subject or counterparty, with quick navigation
* **Notes** — internal analyst notes with timestamps, author names, and team member mentions
* **Remediation** — linked verification session if the transaction is in `AWAITING_USER`
* **Timeline** — full history of status changes, rule matches, analyst actions, and webhook deliveries

## Rules management

All transaction monitoring rules are created and managed from the console. From the **Rules** tab:

* View all active, disabled, and built-in rules
* See execution counters (how many times each rule has matched)
* Enable or disable rules without deleting them
* Create custom rules with the rule builder
* Edit conditions, velocity windows, and actions

## Overview & analytics

The **Overview** tab displays transaction analytics:

* Transaction count and volume over time
* Average transaction amount
* Approved vs. rejected vs. flagged trend chart (with previous period overlay)
* Category and action-type breakdowns
* User geography distribution
* Top rules triggered
* Analyst performance metrics
* Score distribution histogram

Use the filters to narrow analytics by **tag**, **action type** (deposit, withdrawal, etc.), or **date range**.

## Bulk operations

Select multiple transactions to perform batch actions:

* **Export to CSV** — download transaction data with configurable column selection
* **Bulk status update** — change the status of selected transactions (or all matching current filters) at once
* **Bulk delete** — remove selected transactions and their associated data

All bulk actions are logged in the audit trail for compliance tracking.

## Travel Rule workspace

The **Travel Rule** tab is the compliance team's home for the [managed exchange](/transaction-monitoring/travel-rule), in four sub-tabs:

* **Transfers** — every Travel Rule exchange with its status, rail, and direction; click through to the transaction's Travel Rule tab to act on one.
* **Unmatched deposits** — inbound on-chain deposits recorded ahead of any exchange, waiting to be claimed or [registered](/transaction-monitoring/travel-rule#after-deposit-sunrise-registration).
* **VASP directory** — search the counterparty [directory](/transaction-monitoring/travel-rule#directory), including due-diligence scores and reachable rails.
* **Address book** — register, edit, and remove the [wallet addresses](/transaction-monitoring/travel-rule#wallet-address-book) inbound transfers resolve against, with each entry's ownership-verification state.

## Settings

Configure score thresholds, default currency, and blockchain analytics provider preferences from **Transactions** > **Settings**. Select remediation workflows directly on rules that move transactions to `AWAITING_USER`. See [Settings](/transaction-monitoring/settings) for details.

The same page carries the Travel Rule configuration, in three cards:

* **VASP profile** — the master **Travel Rule** toggle, your legal name, LEI, compliance email, jurisdiction, your read-only **travel address** (copyable once assigned), and the **Discoverable in the VASP directory** switch.
* **Exchange policy** — name matching strictness, confirmation timeout, on-timeout outcome, threshold amount, auto-accept for inbound transfers, and the **Allow self-declaration** / **Allow screenshot proof** proof-method switches.
* **Interoperability networks** — one row per network (Global Travel Rule, TRUST, VerifyVASP, Sygna Bridge). A green **Your membership** badge marks networks you connected your own credentials for in the Marketplace; a switch opts in or out of Didit's platform membership; **Connect in marketplace** links to the network's Marketplace tile.

## Marketplace

The **Marketplace** section (own sidebar entry) is where you connect your own provider accounts:

* **Crypto monitoring:** connect an existing blockchain analytics API key and pay the [connected-key screening fee](/transaction-monitoring/aml-screening#supported-providers).
* **Travel Rule networks** — connect your own GTR, TRUST, VerifyVASP, or Sygna Bridge membership credentials; a connected membership always takes precedence over Didit's platform membership. Networks marked **Request access** (CODE, TRISA, Notabene, Veriscope) run through an integration-request flow - the Didit team coordinates the onboarding with you.

Each tile shows managed and connected-key availability, a credential form with a **Test connection** check, and a connected-state view. Secrets are never shown after saving.

## Next steps

<CardGroup>
  <Card title="Alerts" icon="bell" href="/transaction-monitoring/alerts">
    Alert triage and lifecycle.
  </Card>

  <Card title="Cases" icon="folder-open" href="/transaction-monitoring/cases">
    Investigation workflow.
  </Card>

  <Card title="Rules" icon="scale-balanced" href="/transaction-monitoring/rules">
    Configure the rule engine.
  </Card>
</CardGroup>


# Rules on Events
Source: https://docs.didit.me/transaction-monitoring/event-rules

Velocity, ratio, ordered-sequence and cross-subject correlation rules over event data - written in the same rule builder as your transaction rules.

[Events](/transaction-monitoring/events) are evaluated by the same engine as transactions. There is one rule model, one condition vocabulary and one set of actions - a rule simply declares which record kinds it applies to.

## Applies to

`scope.record_types` decides what a rule fires on.

| `record_types`               | Fires on                            |
| ---------------------------- | ----------------------------------- |
| omitted or `["transaction"]` | Transactions only - **the default** |
| `["event"]`                  | Events only                         |
| `["transaction", "event"]`   | Both                                |

<Note>
  Leaving it out keeps a rule transaction-only. Every rule written before events existed behaves exactly as it did, and a rule never starts matching logins because its scope happened to be empty.
</Note>

In the console this is the **Applies to** selector on a rule's Trigger step. Choosing Events reveals an **Event categories** checklist that narrows the rule further; leave it all unchecked to evaluate every category.

```json theme={null}
{
  "title": "Failed login burst",
  "scope": {
    "record_types": ["event"],
    "event_categories": ["security"]
  },
  "aggregation": [
    {
      "metric": "count",
      "operator": "gte",
      "value": 3,
      "window": "30m",
      "filters": {
        "subject_vendor_data": "__current__",
        "event.action_type": "login_failed"
      }
    }
  ],
  "actions": [
    { "type": "add_score", "value": 40 },
    { "type": "change_status", "value": "IN_REVIEW" }
  ]
}
```

`"__current__"` means "the same value as the event being evaluated" - that is how a rule says *per subject*, *per device* or *per round* without naming one.

## Event fields

Conditions read namespaced paths. The transaction vocabulary you already know (`action_type`, `subject_vendor_data`, `subject_ip_country`, `custom_values.<key>`) also resolves on an event.

| Group                             | Paths                                                                                                                                                                                                                                                                                        |
| --------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| Event                             | `event.category`, `event.action_type`, `event.occurred_at`, `event.amount`, `event.currency`, `event.direction`, `event.session_id`, `event.session_sequence`                                                                                                                                |
| Device and network                | `event.device.fingerprint`, `event.device.persistent_device_id`, `event.device.bot_score`, `event.ip.address`, `event.ip.country`, `event.ip.asn_number`, `event.ip.asn_organization`, `event.ip.is_vpn_or_tor`, `event.ip.is_data_center`, `event.ip.proxy_type`                            |
| Gameplay                          | `event.gameplay.game_id`, `event.gameplay.table_id`, `event.gameplay.round_id`, `event.gameplay.hand_id`, `event.gameplay.match_id`, `event.gameplay.market_id`, `event.gameplay.side`, `event.gameplay.role`, `event.gameplay.counterparty_vendor_data`, `event.gameplay.net_result_amount` |
| Payment and dispute               | `event.payment.reference_id`, `event.payment.payment_fingerprint`, `event.payment.instrument_reference_hash`, `event.payment.withdrawal_address_hash`, `event.dispute.dispute_id`, `event.dispute.chargeback_id`                                                                             |
| Security and responsible gambling | `event.security.changed_field`, `event.responsible_gambling.identity_match_ref`                                                                                                                                                                                                              |
| Bot and assistance telemetry      | `event.bot.timing_variance_ms`, `event.bot.actions_per_minute`, `event.bot.pointer_entropy`, `event.bot.reaction_time_ms_p50`, `event.bot.assistance_indicator`                                                                                                                              |
| Subject signals                   | `subject.email.risk_score`, `subject.email.social_count`, `subject.email.is_disposable`, `subject.phone.risk_score`, `subject.phone.line_type`, `subject.phone.social_count`                                                                                                                 |
| Anything else                     | `event.payload.<key>`, `custom_values.<key>`                                                                                                                                                                                                                                                 |

Subject signals are cached on the monitored user, not recomputed per event, so a rule can read them at ingestion speed.

## Aggregations

### Velocity

The reducers you already use on transactions - `count`, `sum`, `avg`, `min`, `max`, `distinct_count` - over a rolling `window` (`30m`, `24h`, `7d`, `30d`).

### Ratio

Two reducers over the same window. This is how wager-to-deposit, withdrawal-to-deposit, bonus-to-deposit and chargeback rates are expressed.

```json theme={null}
{
  "metric": "ratio",
  "window": "24h",
  "filters": { "subject_vendor_data": "__current__" },
  "numerator":   { "metric": "sum", "field": "event.amount", "filters": { "event.action_type": "bet_placed" } },
  "denominator": { "metric": "sum", "field": "event.amount", "filters": { "event.action_type": "deposit_completed" } },
  "operator": "lte",
  "value": 0.1
}
```

Deposit 1,000, wager 20, request a withdrawal, and the ratio is 0.02 - classic minimal-play laundering.

<Note>
  A ratio with **no denominator never matches**. No deposits is not a ratio of zero, it is no evidence, and firing there would flag every brand-new user.
</Note>

### Sequence

Ordered predicates inside a window. Each step matches on `action_type`, `event_category` or an arbitrary `match` filter, and can require `min_count` occurrences before the sequence advances.

```json theme={null}
{
  "metric": "sequence",
  "key": "ato_drain",
  "window": "24h",
  "steps": [
    { "event_category": "security", "action_type": "login_failed", "min_count": 3 },
    { "event_category": "security", "action_type": "mfa_changed" },
    { "event_category": "payment",  "action_type": "withdrawal_address_changed" },
    { "event_category": "payment",  "action_type": "withdrawal_requested" }
  ]
}
```

Credential stuffing, then the MFA takeover, then the payout redirect, then the drain. The rule fires on the event that completes the chain, and the matched evidence lists the event ids of every step.

Sequence state is kept per rule and subject, so it advances as events arrive instead of rescanning the timeline. Progress older than the window is discarded rather than counted.

### Correlation

A cross-subject join: reduce over every event that shares this event's group.

```json theme={null}
{
  "metric": "correlation",
  "window": "7d",
  "pair": true,
  "group_by": ["subject_vendor_data", "event.gameplay.counterparty_vendor_data"],
  "filters": { "event.action_type": "p2p_settlement" },
  "correlate": {
    "metric": "sum",
    "field": "event.gameplay.net_result_amount",
    "filters": { "event.gameplay.role": "winner" }
  },
  "operator": "gte",
  "value": 500
}
```

`"pair": true` matches the two ends as an unordered set, so A→B and B→A land in the same group - which is what lets one rule see both halves of a collusion. Chip dumping, opposite betting and affiliate self-referral are all this shape.

Always give a correlation rule narrowing `filters`. Without them it considers every event in the window.

## Real-time and asynchronous rules

Some rules can answer inside the ingestion request and some cannot.

| Runs                               | Which rules                                                         |
| ---------------------------------- | ------------------------------------------------------------------- |
| **In the request**                 | Velocity, ratio and bounded sequences (window up to 24 hours)       |
| **Within minutes, asynchronously** | Correlation rules, and sequences with a window longer than 24 hours |

An event whose rules are still pending comes back with `"correlation_pending": true`. Its status and score update in place once the asynchronous pass completes; re-running is idempotent, so a rule never applies its score twice.

This split is deliberate: a cross-subject ring query must not make a login wait.

## Actions

The same action vocabulary as transaction rules - `add_score`, `change_status`, `add_tags`, `add_note`, `add_to_list`, `open_case`.

Two differences on events:

* `change_status` to `AWAITING_USER` is a transaction-only outcome (there is no event remediation flow) and is applied as `IN_REVIEW`.
* `open_case` links the case to the **subject** rather than to a transaction, and records the matched event id on the case.

## Evidence

Every match stores what it saw: the aggregation window, the computed value, the expected value, sampled event ids, and the **source of each matched field**.

| Source     | Meaning                                                   |
| ---------- | --------------------------------------------------------- |
| `server`   | Didit derived it (IP, user agent, origin). Authoritative. |
| `sdk`      | The Didit SDK reported it from the device.                |
| `customer` | Your systems supplied it.                                 |

An analyst can therefore tell a server-stamped IP from a client-supplied hint before acting on a match. The console shows the source next to each matched field in the event drawer.

## Worked examples

<AccordionGroup>
  <Accordion title="Minimal-play laundering">
    Deposit, token play, fast withdrawal. Condition `event.action_type eq withdrawal_requested`, plus the wager-to-deposit ratio above at `lte 0.1` over `24h`.
  </Accordion>

  <Accordion title="Friendly fraud">
    Ratio of `count(chargeback_opened)` to `count(deposit_completed)` per subject over `30d`, `gte 0.5`. Group by `event.payment.payment_fingerprint` instead of the subject to catch one instrument across accounts.
  </Accordion>

  <Accordion title="Account-takeover drain">
    The `ato_drain` sequence above, with `add_score 90` and `change_status DECLINED`.
  </Accordion>

  <Accordion title="Chip dumping">
    The pair correlation above. Raise `value` to the amount that is material for your tables, and add `event.gameplay.game_id` to `group_by` to keep games separate.
  </Accordion>

  <Accordion title="Bot play and real-time assistance">
    Conditions on `event.action_type eq bot_signal_observed`, `event.bot.timing_variance_ms lte 10` and `event.device.bot_score gte 90`, with `add_tags`. Combine with a `distinct_count` of `event.device.fingerprint` per IP to find a farm rather than one script.
  </Accordion>

  <Accordion title="Self-exclusion evasion">
    Condition on `event.action_type eq self_exclusion_match` and `event.payload.re_registration_attempt eq true`, escalating with `open_case`.
  </Accordion>
</AccordionGroup>

## Next

<CardGroup>
  <Card title="Event ingestion" icon="bolt" href="/transaction-monitoring/events">
    The envelope, the ten categories and the batch contract.
  </Card>

  <Card title="Rules API" icon="code" href="/transaction-monitoring/rules-api">
    Create, update and back-test rules programmatically.
  </Card>
</CardGroup>


# Event Ingestion
Source: https://docs.didit.me/transaction-monitoring/events

Send non-monetary activity - logins, gameplay, bonuses, payments, disputes, account security - to the same engine that scores your transactions.

Transactions are the money. Events are everything else your platform knows: the login that preceded the withdrawal, the hand that moved chips between two accounts, the bonus that was claimed twice, the chargeback that arrived a week later.

Events use one envelope for every category, are idempotent by design, and are evaluated by the [same rule engine](/transaction-monitoring/event-rules) that scores your [transactions](/transaction-monitoring/transactions).

<Note>
  Event ingestion is **opt-in**. Turn it on in **Transactions → Settings → Event monitoring**.
  Until you do, nothing changes: your existing transaction rules keep firing on transactions only, and an event rule cannot be created by accident because a rule applies to transactions unless you explicitly include events.

  Until it is on, every write lane - `POST /v3/events/`, `POST /v3/events/batch/`, `POST /v3/events/sdk-token/` and the `/v1/events/` device lane - answers `403` with `{"code": "event_monitoring_disabled"}`, and nothing is stored, enriched or evaluated. Reads are unaffected.
</Note>

## Endpoints

| Endpoint                                 | Auth                 | Use it for                                       |
| ---------------------------------------- | -------------------- | ------------------------------------------------ |
| `POST /v3/events/`                       | API key              | One event from your backend                      |
| `POST /v3/events/batch/`                 | API key              | Up to 500 events in one request                  |
| `POST /v3/events/sdk-token/`             | API key              | Mint a scoped device credential                  |
| `POST /v1/events/`                       | `X-Monitoring-Token` | One event from the device SDK                    |
| `POST /v1/events/batch/`                 | `X-Monitoring-Token` | A flushed SDK buffer                             |
| `GET /v3/events/`                        | API key              | List and filter events                           |
| `GET /v3/events/{event_uuid}/`           | API key              | One event with its rule evidence                 |
| `GET /v3/events/subjects/{vendor_data}/` | API key              | One subject's timeline (see `entity_type` below) |
| `GET /v3/events/enrichment-metrics/`     | API key              | IP-enrichment cache health                       |

The `/v3/` lane is the server lane and uses the same `x-api-key` authentication as the rest of the transaction API. The `/v1/events/` lane is the device lane - see [SDK event submission](/transaction-monitoring/sdk-event-submission).

## The envelope

```bash theme={null}
curl -X POST https://verification.didit.me/v3/events/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "login-2026-08-31-000001",
    "event_category": "auth",
    "action_type": "login",
    "occurred_at": "2026-08-31T20:40:31.123Z",
    "time_zone": "UTC",
    "subject": {
      "entity_type": "individual",
      "vendor_data": "user_391"
    },
    "session": { "session_id": "web-session-abc", "sequence": 142 },
    "device_context": {
      "fingerprint": "didit-fp-v2:a8c1",
      "network_context": { "ip_address": "203.0.113.42" }
    },
    "payload": { "method": "password" }
  }'
```

```json theme={null}
{
  "event_uuid": "0f2b...",
  "event_id": "login-2026-08-31-000001",
  "status": "ACCEPTED",
  "score": 0,
  "rules_evaluated_count": 6,
  "rules_matched_count": 0,
  "correlation_pending": false,
  "retention_class": "standard",
  "expires_at": "2026-09-30T20:40:31.123Z",
  "idempotent_replay": false,
  "rule_matches": []
}
```

| Field                  | Required | Notes                                                                                 |
| ---------------------- | -------- | ------------------------------------------------------------------------------------- |
| `event_id`             | yes      | Your own identifier, unique per application. It is the idempotency key.               |
| `event_category`       | yes      | One of the ten categories below.                                                      |
| `action_type`          | yes      | Open string, up to 128 characters.                                                    |
| `occurred_at`          | yes      | When it happened on your side. Up to 7 days in the past, 5 minutes in the future.     |
| `subject.vendor_data`  | yes      | Your user id. Resolved to the same User a transaction would resolve to.               |
| `subject.entity_type`  | no       | `individual` (default) or `company`.                                                  |
| `business.vendor_data` | no       | The business the event belongs to.                                                    |
| `session`              | no       | `session_id`, `sequence`, `page_url`, `referrer`.                                     |
| `device_context`       | no       | `fingerprint`, `persistent_device_id`, `bot_score`, and `network_context.ip_address`. |
| `transaction_context`  | no       | `amount`, `currency`, `direction`, `payment_reference_id`.                            |
| `payload`              | no       | The category's domain fields. Up to 16 KB.                                            |
| `custom_values`        | no       | Up to 100 scalar keys, addressable from rules as `custom_values.<key>`.               |

## Categories

Ten first-class categories, each with typed validation and managed [rule fields](/transaction-monitoring/event-rules#event-fields).

| Category               | Typical actions                                                                                                                                   |
| ---------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------- |
| `auth`                 | `signup`, `login`, `login_failed`, `logout`, `password_reset`, `mfa_reset`, `mfa_challenge`                                                       |
| `session`              | `session_started`, `session_ended`, `page_view`, `sdk_loaded`, `device_seen`, `bot_signal_observed`                                               |
| `gameplay`             | `round_started`, `round_completed`, `bet_placed`, `bet_settled`, `cashout`, `limit_change`, `p2p_settlement`                                      |
| `bonus`                | `bonus_claimed`, `bonus_wagered`, `bonus_released`, `promotion_viewed`                                                                            |
| `affiliate`            | `affiliate_attributed`, `referral_clicked`, `campaign_joined`, `commission_event`                                                                 |
| `payment`              | `deposit_initiated`, `deposit_completed`, `withdrawal_requested`, `withdrawal_completed`, `withdrawal_address_changed`, `payment_instrument_seen` |
| `dispute`              | `chargeback_opened`, `chargeback_won`, `chargeback_lost`, `refund_issued`, `payment_dispute_updated`                                              |
| `security`             | `login_attempt`, `login_succeeded`, `login_failed`, `password_changed`, `mfa_changed`, `credential_reset`, `country_changed`, `device_changed`    |
| `responsible_gambling` | `self_exclusion_checked`, `self_exclusion_match`, `re_registration_attempt`, `limit_breach_attempt`, `registry_status_changed`                    |
| `custom`               | Anything you define                                                                                                                               |

`auth` is the broad product category; `security` is the risk-grade subset with the ordered lifecycle that account-takeover rules read.

### Required payload keys

Some actions cannot be correlated without specific keys, so validation rejects them rather than storing evidence nobody can join.

| Action                                                                                                           | Required                                                                                                                           |
| ---------------------------------------------------------------------------------------------------------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `gameplay.p2p_settlement`                                                                                        | `game_id`, `counterparty_vendor_data`, `stake_amount`, `net_result_amount`, `role`, and one of `hand_id` / `round_id` / `match_id` |
| `gameplay.bet_placed`, `gameplay.bet_settled`                                                                    | `game_id`                                                                                                                          |
| `payment.deposit_*`, `payment.withdrawal_completed`, `payment.withdrawal_requested`, `payment.deposit_initiated` | `payment_reference_id`, `amount`, `currency`, `payment_method`, `status`                                                           |
| `payment.withdrawal_address_changed`                                                                             | `withdrawal_address_hash`                                                                                                          |
| `dispute.chargeback_*`                                                                                           | `payment_reference_id`, and one of `dispute_id` / `chargeback_id`                                                                  |
| `security.*_changed`                                                                                             | `changed_field`; account- or payout-control changes also need `previous_reference_hash` or `new_reference_hash`                    |
| `session.bot_signal_observed`                                                                                    | `telemetry_schema_version`, plus a `bot_score` or at least one telemetry metric                                                    |
| `responsible_gambling.self_exclusion_match`                                                                      | `registry_source`, `exclusion_status`, `identity_match_ref`                                                                        |

<Warning>
  Send **references and hashes**, never raw secrets. Payment instruments, withdrawal destinations and account-control changes are stored as the hashed reference you send. Never send a card number, a full withdrawal address, a password hash or an MFA secret.
</Warning>

### Example: a P2P settlement

```json theme={null}
{
  "event_id": "p2p-hand-8842-user-391",
  "event_category": "gameplay",
  "action_type": "p2p_settlement",
  "occurred_at": "2026-08-31T12:34:17.392Z",
  "subject": { "vendor_data": "user_391" },
  "payload": {
    "game_id": "poker_holdem",
    "table_id": "table_17",
    "hand_id": "hand_8842",
    "role": "winner",
    "counterparty_vendor_data": "user_812",
    "stake_amount": "250.00",
    "net_result_amount": "240.50",
    "effective_margin": "0.038",
    "operator_ledger_ref": "ledger_998123"
  }
}
```

### Example: a chargeback

```json theme={null}
{
  "event_id": "chargeback-cb_921-opened",
  "event_category": "dispute",
  "action_type": "chargeback_opened",
  "occurred_at": "2026-08-31T09:22:05.000Z",
  "subject": { "vendor_data": "user_391" },
  "transaction_context": {
    "amount": "1000.00",
    "currency": "EUR",
    "payment_reference_id": "dep_735"
  },
  "payload": {
    "dispute_id": "disp_498",
    "chargeback_id": "cb_921",
    "reason_code": "fraudulent",
    "liability_shift": false
  }
}
```

Dispute lifecycles are append-only: a correction is a new `dispute` event, never an edit of the first one.

## Idempotency

`event_id` is unique per application and is the whole idempotency contract.

* **Same `event_id`, same content** returns `200` with `"idempotent_replay": true` and the originally stored event. Retry as often as you like.
* **Same `event_id`, different content** returns `409`. You reused an id by mistake.

## Batches

`POST /v3/events/batch/` accepts up to **500 events**. A batch is partially successful by design: one malformed page view must never take down the chargeback next to it.

```json theme={null}
{
  "accepted_count": 2,
  "replayed_count": 0,
  "rejected_count": 1,
  "results": [
    { "index": 0, "outcome": "rejected", "errors": { "occurred_at": ["This field is required."] } },
    { "index": 1, "outcome": "accepted", "event_uuid": "…", "status": "ACCEPTED" },
    { "index": 2, "outcome": "accepted", "event_uuid": "…", "status": "IN_REVIEW" }
  ]
}
```

The response is `207 Multi-Status` when anything was rejected and `201 Created` when everything landed.

## Statuses

| Status      | Meaning                                                                           |
| ----------- | --------------------------------------------------------------------------------- |
| `ACCEPTED`  | Stored. No rule changed its standing (this is the normal answer for most events). |
| `APPROVED`  | A rule ran and the score stayed under your review threshold.                      |
| `IN_REVIEW` | A rule pushed it over the review threshold, or set the status directly.           |
| `DECLINED`  | A rule declined it.                                                               |

`correlation_pending: true` means a cross-subject rule still has to run; it resolves within minutes and the event's status and score update in place. See [asynchronous rules](/transaction-monitoring/event-rules#real-time-and-asynchronous-rules).

## Retention

Events are far higher volume than transactions, so each one is filed into a retention class on arrival.

| Class                    | Default hot retention | What lands here                                                            |
| ------------------------ | --------------------- | -------------------------------------------------------------------------- |
| `low_value`              | 14 days               | Page views, heartbeats, device-seen pings, bot telemetry, promotion views  |
| `standard`               | 30 days               | Auth, session, gameplay, bonus, affiliate, custom                          |
| `risk_relevant`          | 90 days               | Security and responsible-gambling events, and **any event a rule matched** |
| `monetary_or_compliance` | Transaction retention | Payment and dispute events                                                 |

Two rules follow from the table:

* An event that matches a rule is evidence, so it is promoted to `risk_relevant` automatically.
* Payment and dispute events keep transaction retention. They are never expired on the event schedule, and the per-class overrides cannot shorten them.

Override the three expirable classes per application in **Transactions → Settings → Event monitoring** (1-730 days each).

## IP enrichment

Events carry the same [IP enrichment](/transaction-monitoring/ip-enrichment) as transactions - country, ASN, VPN/proxy and data-centre flags - and enrichment is resolved **per unique IP address, never per event**. A session that fires 200 page views from one address resolves that address once.

Low-value telemetry goes further: it reads enrichment only if some other event already resolved that address. It never triggers a lookup of its own.

`GET /v3/events/enrichment-metrics/` reports the result, and the console shows the same numbers above the events list:

```json theme={null}
{
  "events_ingested": 128450,
  "enrichment_lookups": 41230,
  "enrichment_cache_hits": 40118,
  "enrichment_provider_calls": 1112,
  "enrichment_skipped_low_value": 74320,
  "unique_ips_seen": 1112,
  "cache_hit_rate": 0.973,
  "unique_ip_ratio": 0.0087,
  "provider_calls_per_1k_events": 8.65,
  "period_days": 30
}
```

## Reading events back

```bash theme={null}
curl "https://verification.didit.me/v3/events/?event_category=payment&event_category=dispute&matched_only=true" \
  -H "x-api-key: YOUR_API_KEY"
```

Filters: `event_category`, `action_type`, `status`, `retention_class`, `subject_vendor_data`, `business_vendor_data`, `session_id`, `device_fingerprint`, `ip_address`, `game_id`, `round_id`, `affiliate_code`, `payment_reference_id`, `counterparty_vendor_data`, `matched_only`, `occurred_from`, `occurred_to`, `search`. Multi-value filters repeat the parameter (`?status=A&status=B`).

### One subject's timeline

```bash theme={null}
curl "https://verification.didit.me/v3/events/subjects/acct_9931/?entity_type=company" \
  -H "x-api-key: YOUR_API_KEY"
```

A `vendor_data` is only unique **within** an entity type: the same id can name a user and a company, and Didit resolves them as two different subjects. `entity_type` says which one you are asking for - `individual` (the default) or `company`. Omitting it on a company id returns the individual's timeline, not both. The same list filters apply.

`GET /v3/events/{event_uuid}/` adds the payload, the device context, the IP enrichment, the subject's cached risk signals, and every rule match with its evidence - including whether each matched field was server-derived, SDK-derived or customer-supplied.

`DELETE /v3/events/{event_uuid}/delete/` deletes one event. It stops being returned by every read, and deletion is irreversible.

## Next

<CardGroup>
  <Card title="Rules on events" icon="filter" href="/transaction-monitoring/event-rules">
    Velocity, ratio, sequence and correlation rules over event data.
  </Card>

  <Card title="SDK event submission" icon="mobile" href="/transaction-monitoring/sdk-event-submission">
    Capture events straight from the device with a scoped credential.
  </Card>
</CardGroup>


# Transaction Monitoring Integration Guide
Source: https://docs.didit.me/transaction-monitoring/integration-guide

Architecture and best practices for KYT: real-time vs batch, parties, idempotency, historical ingestion, webhooks. Pay-per-call $0.02 per transaction.

This guide covers the full integration surface of Transaction Monitoring. The [quickstart](/transaction-monitoring/quickstart) gets you running; this page gets you to production.

## Architecture

```mermaid theme={null}
sequenceDiagram
    participant You as Your platform
    participant Didit as Didit API
    participant Rules as Rule engine
    participant AML as AML providers
    participant Webhook as Your webhook

    You->>Didit: POST /v3/transactions/ (txn_id, parties, amount)
    Didit->>Didit: IP enrichment (inline)
    Didit->>AML: Screen wallet or transaction hash + address
    AML-->>Didit: Hits / clean
    Didit->>Rules: Evaluate all active rules
    Rules-->>Didit: Score + matched rules + actions
    Didit-->>You: Transaction record with status
    Didit->>Webhook: transaction.created
    Didit->>Webhook: transaction.status.updated (if async rules)
```

## Authentication

Standard `x-api-key` header. Same keys used for sessions and entities. See [API authentication](/getting-started/api-authentication).

## Submitting a transaction

Single endpoint: `POST /v3/transactions/`. See [submitting transactions](/transaction-monitoring/transactions) for the full schema.

**Minimal payload:**

```json theme={null}
{
  "transaction_id": "tx-0001",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "500.00",
    "currency": "EUR"
  },
  "subject": { "entity_type": "person", "vendor_data": "user-42", "full_name": "John Doe" },
  "counterparty": { "entity_type": "company", "full_name": "Acme Corp" }
}
```

**Richer payload with payment methods, device context, and custom properties:**

```json theme={null}
{
  "transaction_id": "tx-0002",
  "transaction_at": "2026-04-16T10:00:00Z",
  "transaction_category": "finance",
  "transaction_details": {
    "direction": "outbound",
    "amount": "12500.00",
    "currency": "USD",
    "action_type": "withdrawal"
  },
  "subject": {
    "entity_type": "person",
    "vendor_data": "user-42",
    "full_name": "John Doe",
    "country_code": "US",
    "device_context": {
      "fingerprint": "fp-9f2c...",
      "user_agent": "Mozilla/5.0 ...",
      "browser_family": "Chrome",
      "platform": "web",
      "network_context": { "ip_address": "203.0.113.5" }
    },
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US12345678901234567890",
      "issuing_country": "US"
    }
  },
  "counterparty": {
    "entity_type": "company",
    "vendor_data": "biz-acme",
    "full_name": "Acme Corp",
    "country_code": "US",
    "payment_method": {
      "method_type": "bank_account",
      "account_id": "US09876543210987654321",
      "issuing_country": "US"
    }
  },
  "custom_properties": {
    "invoice_id": "INV-2026-00042",
    "category": "b2b_goods"
  }
}
```

camelCase aliases are accepted for every top-level field (`txnId`, `txnDate`, `type`, `info`, `applicant`, `props`, `travelRule`, `includeCryptoScreening`) - the SDK wire format and the snake\_case format land in the same place.

## Party modeling

Every transaction has a required `subject` (your customer - the party you monitor) and an optional `counterparty` (the other side). Each carries its own `payment_method` and optional `device` context.

In the response, they come back in the `parties` array with roles `APPLICANT` and `COUNTERPARTY`; a party without `vendor_data` is stored as an external snapshot (`kind: EXTERNAL`) with no linked entity.

See [transactions payload](/transaction-monitoring/transactions) for party fields.

## Idempotency

`txn_id` is unique per application. Re-submitting the same `txn_id` returns the existing transaction's current state (not an error) — effectively idempotent for retries.

**Always generate `txn_id` on your side** before submitting; don't rely on a Didit-generated ID for idempotency. Use your own database ID, a UUID, or a hash of transaction fields.

## Real-time vs batch

* **Real-time** — recommended for most use cases. Submit the transaction the moment it happens in your system. Rules evaluate synchronously and return the decision.
* **Batch / backfill** — for historical ingestion, pass `txn_date` in the past. Rules still run and can trigger webhooks. To avoid triggering rules on backfill, use the console's CSV import with the "dry ingest" flag.

## Historical ingestion

When you're migrating from another transaction monitoring system:

1. Export your historical transactions to a CSV.
2. Use *Transactions → Import history* in the console (or submit via API in a loop) with `txn_date` in the past.
3. Enable rules only after ingestion finishes, or use dry ingest to skip rule evaluation.

<Warning>
  Be deliberate about historical rule evaluation. Feeding 6 months of history through a "20 transfers in 30 days" rule will generate thousands of alerts at once.
</Warning>

## Webhooks

Subscribe to:

* `transaction.created` — every submitted transaction.
* `transaction.status.updated` — status changes (e.g. analyst moves from `IN_REVIEW` to `APPROVED`, or an async AML check updates the score).

Full details: [TM webhooks](/transaction-monitoring/webhooks).

```typescript theme={null}
app.post('/webhooks/didit-tm', (req, res) => {
  if (!verifySignature(req)) return res.status(401).end();

  const { event, data } = req.body;
  if (event === 'transaction.status.updated' && data.status === 'DECLINED') {
    suspendTransaction(data.txn_id);
  }
  res.status(200).end();
});
```

## Handling statuses

| Status          | What to do                                                                                                                                                                                                                                     |
| --------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `APPROVED`      | Process the transaction as normal.                                                                                                                                                                                                             |
| `IN_REVIEW`     | Hold the transaction until analyst review or automated re-check resolves.                                                                                                                                                                      |
| `DECLINED`      | Reject the transaction. Surface a generic error to the user.                                                                                                                                                                                   |
| `AWAITING_USER` | The user must act before the transaction can settle — read the `action_required` block and deliver its `url` to the user (the SDKs can [handle this automatically](/transaction-monitoring/sdk-transaction-submission#required-user-actions)). |

See [TM statuses](/transaction-monitoring/statuses).

## Linking transactions to entities

Pass `vendor_data` on every party. Benefits:

* Every transaction aggregates into the User or Business profile.
* Velocity and behavioral rules have the full history to evaluate against.
* Blocking an entity propagates to future transactions automatically.

Missing `vendor_data` isn't a hard error — the transaction is stored as an external snapshot — but you lose entity-level aggregation.

## Remediation sessions

When a rule action moves a transaction to `AWAITING_USER`, Didit automatically creates a **remediation session** - a standard hosted verification session for the same `vendor_data`.
Custom rules always name the workflow on the action itself; for built-in library rules the workflow falls back to the [remediation workflow in your transaction settings](/transaction-monitoring/settings#remediation-workflow), then your application's Biometric Authentication workflow (when the subject has a stored reference face), then your application's default workflow.
Travel Rule transactions are excluded from this automatic fallback - their pending action is wallet-ownership proof.
The transaction (response, every subsequent read, and every webhook) carries it in the canonical `action_required` block:

```json theme={null}
{
  "status": "AWAITING_USER",
  "action_required": {
    "type": "verification_session",
    "url": "https://verify.didit.me/session/...",
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "status": "Not Started"
  },
  "remediation": {
    "session_id": "11111111-2222-3333-4444-555555555555",
    "session_token": "SESSION_TOKEN",
    "url": "https://verify.didit.me/session/...",
    "status": "Not Started"
  }
}
```

`remediation` is kept for backward compatibility; `action_required` is the canonical block (it also carries `wallet_ownership` actions for [Travel Rule](/transaction-monitoring/travel-rule) transfers).

The user completes the verification - for a **Biometric Authentication** workflow, a liveness-checked selfie matched against the face captured at their original KYC onboarding, the strongest step-up for [high-value transactions](/transaction-monitoring/sdk-transaction-submission#example-step-up-biometrics-for-a-high-value-withdrawal).
Once the session reaches a decision, the transaction follows it automatically - `APPROVED` (`decision_reason_code: user_action_approved`), `DECLINED` (`user_action_declined`), or `IN_REVIEW` (`user_action_in_review`) - and a `transaction.status.updated` webhook fires.

<Note>
  Any workflow type except KYB can be selected.
  Biometric Authentication workflows (and workflows where face match runs before ID verification) require the subject to already have a stored reference face from an approved verification; users without one are sent to your application's default workflow instead, with a note on the transaction recording the substitution.
</Note>

## Best practices

| Practice                                                                 | Why                                                                                                              |
| ------------------------------------------------------------------------ | ---------------------------------------------------------------------------------------------------------------- |
| Always pass `vendor_data`                                                | Enables aggregation.                                                                                             |
| Use your own `txn_id`                                                    | Idempotency.                                                                                                     |
| Subscribe to both `transaction.created` and `transaction.status.updated` | Catch async state changes (e.g. analyst review outcomes).                                                        |
| Set rule thresholds deliberately                                         | Low thresholds = more alerts; high = more missed risk. See [risk scoring](/transaction-monitoring/risk-scoring). |
| Monitor rule run counts in console                                       | Catch rules that never fire (misconfigured) or fire on everything (too loose).                                   |
| Test rules in TEST mode before going live                                | See [rules](/transaction-monitoring/rules).                                                                      |

## Rate limits

See [rate limiting](/integration/rate-limiting). Transaction create is one of the highest-throughput endpoints; typical limits are in the hundreds of requests per second. Burst carefully.

## Next steps

<CardGroup>
  <Card title="Transactions" icon="arrow-right-to-bracket" href="/transaction-monitoring/transactions">
    Full payload reference.
  </Card>

  <Card title="Rules" icon="scale-balanced" href="/transaction-monitoring/rules">
    How rules evaluate.
  </Card>

  <Card title="Webhooks" icon="bolt" href="/transaction-monitoring/webhooks">
    Event catalog.
  </Card>

  <Card title="Troubleshooting" icon="wrench" href="/transaction-monitoring/troubleshooting">
    Common integration issues.
  </Card>
</CardGroup>


# IP Enrichment
Source: https://docs.didit.me/transaction-monitoring/ip-enrichment

Every transaction is enriched with IP context: country, ASN, VPN/Tor, data center, carrier. Real-time and rule-ready. Pay-per-call $0.02 per transaction.

Every transaction that includes a device IP address is enriched server-side in real time before rules evaluate it. Enrichment adds country, city, VPN/Tor/data-center flags, ASN, and carrier — all available as rule conditions.

## When enrichment runs

Inline during transaction creation:

1. You submit `POST /v3/transactions/` with `subject.device_context.network_context.ip_address` (or any party's device IP).
2. Didit looks up the IP in an in-memory cache (24-hour TTL).
3. If not cached, checks the shared IP-enrichment table (\~30-day freshness).
4. If stale or missing, resolves the IP through Didit's enrichment pipeline with multi-provider failover.
5. Enriched fields are written back to the transaction record and made available to rules.

Enrichment is **inline** — it completes before rules run — but **non-blocking on failure**. If enrichment cannot complete, the transaction still goes through; the IP simply appears without enrichment data.

## Enriched fields

| Field                   | Description                                             |
| ----------------------- | ------------------------------------------------------- |
| `ip_country`            | Country name                                            |
| `ip_country_code`       | ISO 3166-1 alpha-3                                      |
| `ip_state`              | Subdivision (state, region)                             |
| `ip_city`               | City name                                               |
| `latitude`, `longitude` | Geographic coordinates                                  |
| `isp`                   | Internet service provider name                          |
| `organization`          | Registering organization name                           |
| `is_vpn_or_tor`         | Boolean — the IP is a known VPN or Tor exit             |
| `is_data_center`        | Boolean — the IP belongs to a hosting/data-center range |
| `time_zone`             | IANA time zone (e.g. `America/New_York`)                |
| `time_zone_offset`      | Offset from UTC                                         |
| `asn_number`            | Autonomous System Number                                |
| `asn_organization`      | ASN's registered organization                           |
| `connection_type`       | `mobile`, `broadband`, `dialup`, `corporate`, ...       |
| `carrier`               | Mobile carrier (for mobile IPs)                         |
| `proxy_type`            | `VPN`, `TOR`, `PUBLIC_PROXY`, or null                   |

## Using enriched fields in rules

Any of the enriched fields can be a [rule condition](/transaction-monitoring/rules). Common patterns:

**High-risk jurisdiction by IP**

```
condition: applicant.ip_country_code IN ['IRN', 'PRK', 'SYR']
action: add_score(35), add_tags(['high_risk_ip_country'])
```

**VPN / Tor usage**

```
condition: applicant.is_vpn_or_tor == true
action: change_status('IN_REVIEW'), add_tags(['anonymization'])
```

**Data center / non-residential origin**

```
condition: applicant.is_data_center == true AND amount > 10000
action: add_score(30)
```

**IP country ≠ KYC country**

```
condition: applicant.ip_country_code != applicant.country_code
action: add_score(15), add_tags(['geo_mismatch'])
```

## Cache layers

| Layer                      | TTL       | Purpose                                            |
| -------------------------- | --------- | -------------------------------------------------- |
| In-memory cache            | 24 hours  | Sub-millisecond lookup for hot IPs                 |
| Shared IP-enrichment table | \~30 days | Shared across instances; cheaper than re-resolving |
| Enrichment pipeline        | n/a       | Fresh data when nothing else has it                |

Hits on the first two layers don't cost you anything extra. Fresh resolutions may be metered — see your billing console.

## Failure behavior

* Transaction creation **never fails** because enrichment failed.
* Missing enrichment fields simply don't match any rule conditions that reference them.
* Alerts about stuck enrichment are surfaced to your ops team via internal monitoring; no customer-facing impact.

## Validity filtering

Non-routable IPs are skipped before enrichment:

* Private (10/8, 172.16/12, 192.168/16)
* Loopback (127/8)
* Link-local (169.254/16)
* Multicast, unspecified

These save provider quota and avoid nonsense enrichment data.

## Inspecting enrichment for a transaction

**Via API.** The transaction response includes an `ip_enrichment` block:

```json theme={null}
"applicant": {
  "vendor_data": "user-42",
  "device": { "network_context": { "ip_address": "203.0.113.5" } },
  "ip_enrichment": {
    "ip_country": "United States",
    "ip_country_code": "USA",
    "ip_state": "California",
    "ip_city": "San Francisco",
    "is_vpn_or_tor": false,
    "is_data_center": false,
    "asn_number": 15169,
    "asn_organization": "Google LLC",
    "proxy_type": null
  }
}
```

**In the console.** The transaction detail page shows IP enrichment in the **IP & Device** tab with a geo-map pin.

## Privacy considerations

* Raw IPs are stored with the transaction.
* Enrichment data lives on a shared IP-keyed table — not per user.
* Right-to-be-forgotten deletion removes IPs from the transaction; the shared cache entry remains (it's not personally identifying).

## Next steps

<CardGroup>
  <Card title="Rules" icon="scale-balanced" href="/transaction-monitoring/rules">
    Use enriched fields in conditions.
  </Card>

  <Card title="Rule library" icon="books" href="/transaction-monitoring/rules-library">
    Preset IP-based rules.
  </Card>

  <Card title="Response schema" icon="file-lines" href="/transaction-monitoring/response-schema">
    Where IP enrichment appears.
  </Card>
</CardGroup>


# Transaction Monitoring
Source: https://docs.didit.me/transaction-monitoring/overview

Real-time transaction screening with rule-based scoring, velocity checks, AML, and case management. Pay-per-call $0.02 per transaction, no contracts.

This Didit Academy lesson tours the rule engine on live data: the transaction feed, how the risk score is calculated, rule creation with triggers and conditions, back-testing, and turning on crypto monitoring.

<VideoEmbed title="Catch fraud in real time: the rule engine — Didit Academy" />

Didit's Transaction Monitoring lets you screen every transaction in real time — inbound and outbound — against a configurable rule engine. Each transaction receives a risk score, and rules can automatically approve, flag for review, or decline based on your thresholds.

New to Didit TM? Start with the [quickstart](/transaction-monitoring/quickstart) for a 10-minute setup, then read the [integration guide](/transaction-monitoring/integration-guide) for architecture and production patterns. [Risk scoring](/transaction-monitoring/risk-scoring) explains exactly how scores are computed.

## How it works

<Steps>
  <Step title="Submit a transaction" icon="arrow-right-to-bracket">
    Send transaction data via the [Create Transaction](/management-api/transactions/create) API. Each transaction includes the subject and counterparty parties, financial details (amount, currency, direction), payment method information, and optional device context and custom properties for rule evaluation.

    Didit supports multiple transaction categories — from standard financial transactions to gambling events, travel rule transfers, and audit trail entries. See [Submitting transactions](/transaction-monitoring/transactions) for the full payload reference.
  </Step>

  <Step title="Rules engine evaluates" icon="gears">
    Didit runs the transaction against all active rules for your application. Rules can check:

    * **Single-transaction thresholds** — amount limits, high-risk countries, blocklisted entities
    * **Velocity windows** — cumulative volume or count over time (e.g., more than \$10,000 in 24 hours)
    * **Behavioral patterns** — structuring detection, rapid in-and-out movement, round-amount patterns
    * **AML screening** — sanctions and watchlist checks on counterparties and linked users via external providers
    * **Wallet risk** — mixer exposure, high-risk wallet addresses (for crypto transactions)

    Each matching rule contributes to the transaction's overall risk score.
  </Step>

  <Step title="Score and decide" icon="scale-balanced">
    Based on the cumulative score and the highest-severity rule match, the transaction receives a status:

    | Status          | Meaning                                        |
    | --------------- | ---------------------------------------------- |
    | `APPROVED`      | Below all thresholds — transaction is clean    |
    | `IN_REVIEW`     | Flagged for manual analyst review              |
    | `DECLINED`      | Automatically rejected by a rule               |
    | `AWAITING_USER` | Requires additional verification from the user |

    When a transaction enters `AWAITING_USER`, Didit automatically creates a linked remediation session and returns a verification URL so you can continue the flow without leaving the transaction workspace.
  </Step>

  <Step title="Monitor and investigate" icon="magnifying-glass-chart">
    Use the Business Console or API to:

    * Review flagged transactions with full context (scores, matched rules, linked parties)
    * Open investigation cases and assign analysts
    * Track analyst performance and resolution times
    * Export transaction data for compliance reporting
  </Step>
</Steps>

## Crypto screening

For cryptocurrency transactions, Didit automatically screens wallet addresses and transaction hashes against blockchain analytics providers (Crystal, Merkle Science, and more). Screening runs server-side during transaction creation — no additional API calls needed from your side.

Each screening produces a standardised risk score, source of funds analysis with exposure category breakdowns, exposure tables, and an interactive network graph. Results feed directly into the rules engine — preset rules like "Sanctions counterparty" and "Darknet market exposure" fire automatically.

See [crypto screening](/transaction-monitoring/aml-screening) for provider details, pricing, exposure categories, and network visualization.

## Key capabilities

| Capability                   | Description                                                                                                                                                                     |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Real-time scoring**        | Every transaction is scored instantly against all active rules                                                                                                                  |
| **Built-in rule library**    | Pre-configured rules for AML/CTF, fraud, crypto, responsible gaming, and blockchain analytics                                                                                   |
| **Custom rules**             | Build rules from the console with conditions, velocity windows, scopes, and automated actions                                                                                   |
| **Crypto screening**         | Automatic wallet and transaction screening via Crystal, Merkle Science, and more                                                                                                |
| **Source of funds analysis** | Breakdown of where funds originated — exchanges, mixers, sanctioned entities, scams                                                                                             |
| **Counterparty connections** | Entity-level view of who the wallet has transacted with                                                                                                                         |
| **Network graph**            | Interactive visual graph of wallet relationships and fund flows                                                                                                                 |
| **Travel rule compliance**   | Track originator and beneficiary data, protocol details, and obligation status for virtual asset transfers                                                                      |
| **Remediation workflows**    | Automatically trigger user verification when a rule requires additional checks                                                                                                  |
| **Case management**          | Open cases, link alerts and transactions, assign analysts, and attach evidence                                                                                                  |
| **Configurable settings**    | Adjust score thresholds, default currency, provider preferences, and remediation workflows per application                                                                      |
| **Webhooks**                 | Receive `transaction.created`, `transaction.updated`, `transaction.status.changed`, and `transaction.alert.generated` events in real time via [webhooks](/integration/webhooks) |

## Integration

Submit transactions via the API and receive results via webhooks:

```bash theme={null}
curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "finance0001",
    "transaction_category": "finance",
    "transaction_details": {
      "direction": "outbound",
      "amount": "1200.00",
      "currency": "EUR"
    },
    "subject": { "entity_type": "person", "vendor_data": "user-123", "full_name": "John Doe" },
    "counterparty": { "entity_type": "person", "full_name": "Jane Doe" }
  }'
```

See the [API Reference](/management-api/transactions/create) for the full payload schema.

## Next steps

<CardGroup>
  <Card title="Submitting transactions" icon="arrow-right-to-bracket" href="/transaction-monitoring/transactions">
    Full payload reference for the Create Transaction API.
  </Card>

  <Card title="Rules & scoring" icon="scale-balanced" href="/transaction-monitoring/rules">
    How the rule engine works, built-in bundles, and custom rule creation.
  </Card>

  <Card title="Event ingestion" icon="bolt" href="/transaction-monitoring/events">
    Send logins, gameplay, bonuses, payments and disputes to the same engine.
  </Card>

  <Card title="Crypto screening" icon="link" href="/transaction-monitoring/aml-screening">
    Wallet screening, source of funds, and network visualization.
  </Card>

  <Card title="Travel rule" icon="globe" href="/transaction-monitoring/travel-rule">
    Travel rule compliance data for virtual asset transfers.
  </Card>

  <Card title="Cases & investigations" icon="folder-open" href="/transaction-monitoring/cases">
    Open cases, assign analysts, and manage investigation workflows.
  </Card>

  <Card title="Settings" icon="gear" href="/transaction-monitoring/settings">
    Score thresholds, providers, and remediation configuration.
  </Card>
</CardGroup>


# Transaction monitoring quickstart: rules and webhooks
Source: https://docs.didit.me/transaction-monitoring/quickstart

Submit your first transaction, see rules fire, hook up webhooks — end-to-end in under 10 minutes. Pay-per-call $0.02 per transaction, no contracts.

Stand up Transaction Monitoring in under 10 minutes. You'll submit a test transaction, inspect its score, enable a preset rule, resubmit to see it fire, and confirm the webhook arrives.

## Prerequisites

* A Didit application with Transaction Monitoring enabled (*Settings → Transaction Monitoring → Enable*).
* An API key.
* A webhook endpoint reachable from the internet.

## Steps

<Steps>
  <Step title="Submit a baseline transaction">
    ```bash theme={null}
    curl -X POST https://verification.didit.me/v3/transactions/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "transaction_id": "baseline-0001",
        "transaction_category": "finance",
        "transaction_details": {
          "direction": "outbound",
          "amount": "500.00",
          "currency": "EUR"
        },
        "subject": { "entity_type": "person", "vendor_data": "user-42", "full_name": "Jane Doe" },
        "counterparty": { "entity_type": "company", "full_name": "Acme Supplier" }
      }'
    ```

    Response includes:

    * `status` — `APPROVED` if no rules fired, `IN_REVIEW` / `DECLINED` if any did.
    * `score` — integer 0–100+.
    * `rule_runs` — array of every rule that evaluated this transaction.
  </Step>

  <Step title="Enable a preset rule">
    Navigate to *Transactions → Rules → Library* in the Business Console. Pick a preset, for example **Structuring (outbound)**: triggers when the same user sends 20+ outbound transfers under €10,000 within 30 days. Enable it and save.
  </Step>

  <Step title="Submit transactions that trigger the rule">
    Submit 20 transactions quickly for the same user, each under €10,000:

    ```bash theme={null}
    for i in $(seq 1 20); do
      curl -X POST https://verification.didit.me/v3/transactions/ \
        -H "x-api-key: YOUR_API_KEY" \
        -H "Content-Type: application/json" \
        -d "{
          \"transaction_id\": \"struct-$i\",
          \"transaction_category\": \"finance\",
          \"transaction_details\": {
            \"direction\": \"outbound\",
            \"amount\": \"9500.00\",
            \"currency\": \"EUR\"
          },
          \"subject\": { \"entity_type\": \"person\", \"vendor_data\": \"user-42\", \"full_name\": \"Jane Doe\" },
          \"counterparty\": { \"entity_type\": \"company\", \"full_name\": \"Shell Co $i\" }
        }"
    done
    ```

    By the 20th submission, the Structuring rule fires. The transaction returns `status: IN_REVIEW` and `score` reflects the rule's `score_delta`.
  </Step>

  <Step title="Subscribe to transaction webhooks">
    ```bash theme={null}
    curl -X POST https://verification.didit.me/v3/webhook/destinations/ \
      -H "x-api-key: YOUR_API_KEY" \
      -H "Content-Type: application/json" \
      -d '{
        "label": "TM events",
        "url": "https://yourapp.com/webhooks/didit-tm",
        "subscribed_events": ["transaction.created", "transaction.status.updated"]
      }'
    ```

    The response includes `secret_shared_key` — save it immediately as `DIDIT_WEBHOOK_SECRET` in your `.env`:

    ```bash theme={null}
    DIDIT_WEBHOOK_SECRET=whsec_...   # signing secret returned from webhook registration
    ```

    Then verify the `X-Signature-V2` HMAC on every incoming webhook before trusting it (recompute HMAC-SHA256 over the canonicalised body, constant-time compare, reject stale timestamps). See [TM webhooks](/transaction-monitoring/webhooks) for the payloads and the full verification code.

    Every subsequent transaction posts to your endpoint in real time.
  </Step>

  <Step title="Inspect in the console">
    Navigate to *Transactions* in the console:

    * List view: recent transactions, filters, bulk actions.
    * Transaction detail: rule runs, IP enrichment, party details, network graph (for crypto), linked alerts and cases.
  </Step>

  <Step title="Retrieve a transaction via API">
    ```bash theme={null}
    curl https://verification.didit.me/v3/transactions/{transaction_id}/ \
      -H "x-api-key: YOUR_API_KEY"
    ```

    Returns the full [response schema](/transaction-monitoring/response-schema) — score, matched rules, party enrichment, AML screening, and more.
  </Step>
</Steps>

## What you just set up

* **Real-time scoring** — every transaction runs through every active rule.
* **AML screening** — counterparties are screened against sanctions / PEP / adverse media automatically.
* **IP enrichment** — every transaction is enriched with IP country, ASN, VPN/Tor flags.
* **Webhooks** — real-time notification on every transaction.
* **Audit trail** — rule runs, alerts, and status transitions are all queryable in the console.

## Common next moves

<CardGroup>
  <Card title="Integration guide" icon="book" href="/transaction-monitoring/integration-guide">
    Full architecture and patterns.
  </Card>

  <Card title="Rules deep dive" icon="scale-balanced" href="/transaction-monitoring/rules">
    How rules work, conditions, aggregations, actions.
  </Card>

  <Card title="Risk scoring" icon="gauge" href="/transaction-monitoring/risk-scoring">
    How scores combine into statuses.
  </Card>

  <Card title="Transactions payload" icon="arrow-right-to-bracket" href="/transaction-monitoring/transactions">
    The full transaction submission schema.
  </Card>

  <Card title="Statuses" icon="list-check" href="/transaction-monitoring/statuses">
    Transaction, alert, and case states.
  </Card>

  <Card title="Cases" icon="folder-open" href="/transaction-monitoring/cases">
    Investigate and resolve.
  </Card>
</CardGroup>


# Transaction Response Schema
Source: https://docs.didit.me/transaction-monitoring/response-schema

Annotated transaction response: score, matched rules, parties, payment methods, IP, crypto screening, travel rule, network snapshot. Pay-per-call $0.02.

This page documents the full payload returned by `POST /v3/transactions/` and `GET /v3/transactions/{id}/`.

## Top-level structure

```json theme={null}
{
  "transaction_id": "uuid",
  "txn_id": "tx-0001",
  "txn_date": "2026-04-16T12:00:00Z",
  "environment": "live",
  "direction": "OUTBOUND",
  "status": "IN_REVIEW",
  "score": 65,
  "amount": "12500.00",
  "currency": "USD",
  "amount_in_default_currency": "12500.00",
  "default_currency_code": "USD",
  "preferred_currency_amount": "12500.00",
  "transaction_type": "finance",
  "action_type": null,
  "rules_evaluated_count": 18,
  "rules_matched_count": 2,
  "decision_reason_code": "rule_score_threshold",
  "decision_reason_label": "Score above review threshold",
  "applicant": { ... },
  "remitter": null,
  "beneficiary": null,
  "counterparty": { ... },
  "payment_methods": [ ... ],
  "rule_runs": [ ... ],
  "alerts": [ ... ],
  "provider_results": [ ... ],
  "travel_rule": { ... } | null,
  "network_snapshot_id": null,
  "tags": [ ... ],
  "notes": [ ... ],
  "metadata": { },
  "custom_values": { },
  "session_id": null,
  "remediation": null,
  "action_required": null,
  "assigned_to": null,
  "created_at": "...",
  "updated_at": "..."
}
```

## Key fields

### Financial fields

* `amount` / `currency` — transaction amount as submitted.
* `amount_in_default_currency` / `default_currency_code` — amount converted to your app's default currency (for cross-currency thresholding).
* `preferred_currency_amount` — optional per-rule / per-app preferred reporting currency.

### Status fields

* `status` — `APPROVED`, `IN_REVIEW`, `DECLINED`, `AWAITING_USER`.
* `score` — integer score.
* `decision_reason_code` / `decision_reason_label` — structured + human reason for the current status.
* `environment` - `live` or `sandbox`, from the application that owns the transaction. A `sandbox` transaction is stored but never evaluated, so its empty `rule_runs` means "not evaluated" rather than "nothing matched". See [Transaction Monitoring in sandbox](/integration/sandbox-testing#transaction-monitoring-in-sandbox).

### Parties

```json theme={null}
"applicant": {
  "uuid": "...",
  "vendor_data": "user-42",
  "full_name": "John Doe",
  "first_name": "John",
  "last_name": "Doe",
  "country_code": "USA",
  "date_of_birth": "1990-01-01",
  "address": { "line_1": "...", "city": "...", "country_code": "USA" },
  "institution_info": { "name": "...", "country_code": "..." },
  "device": {
    "fingerprint": "...",
    "persistent_device_id": "...",
    "user_agent": "...",
    "browser_family": "Chrome",
    "browser_version": "131.0",
    "platform": "web",
    "os_family": "Windows",
    "os_version": "10.0",
    "network_context": {
      "ip_address": "203.0.113.5",
      "ip_country_code": "USA"
    }
  },
  "ip_enrichment": {
    "ip_country_code": "USA",
    "is_vpn_or_tor": false,
    "is_data_center": false,
    "asn_number": 15169,
    "asn_organization": "Google LLC"
  }
}
```

Each party (`applicant`, `remitter`, `beneficiary`, `counterparty`) has the same shape. See [IP enrichment](/transaction-monitoring/ip-enrichment) for the enrichment fields.

### Payment methods

```json theme={null}
"payment_methods": [
  {
    "uuid": "...",
    "role": "SOURCE",
    "type": "BANK_ACCOUNT",
    "label": "Chase checking ****1234",
    "fingerprint": "bank:us:chase:****1234",
    "account_id": "...",
    "issuing_country": "USA",
    "institution_info": { "name": "JP Morgan Chase", "country_code": "USA" },
    "details": { }
  }
]
```

`role`: `SOURCE`, `DESTINATION`, `FUNDING`, `BENEFICIARY`.
`type`: `BANK_CARD`, `BANK_ACCOUNT`, `EWALLET`, `CRYPTO_WALLET`, `UNHOSTED_WALLET`.

### Rule runs

```json theme={null}
"rule_runs": [
  {
    "rule_uuid": "...",
    "rule_name": "High-value outbound",
    "matched": true,
    "is_test": false,
    "mode": "ACTIVE",
    "score_delta": 30,
    "severity": null,
    "status_target": null,
    "action_summary": { "add_score": 30 },
    "considered_payload": { "amount": "12500.00", "direction": "OUTBOUND" },
    "matched_payload": { "amount": "12500.00" }
  },
  {
    "rule_uuid": "...",
    "rule_name": "High-risk jurisdiction counterparty",
    "matched": true,
    "score_delta": 35,
    "action_summary": { "add_score": 35, "add_tags": ["high_risk_country"] }
  }
]
```

Every rule that evaluated is included — `matched: false` rules appear too, so you can audit selectivity.

### Alerts

```json theme={null}
"alerts": [
  {
    "uuid": "...",
    "status": "OPEN",
    "source": "RULE",
    "title": "High-value + high-risk jurisdiction",
    "severity": null,
    "created_at": "..."
  }
]
```

### Provider results

External provider outputs (transaction hash screening, wallet screening, fiat monitoring, sanctions screening).

```json theme={null}
"provider_results": [
  {
    "uuid": "...",
    "result_type": "TRANSACTION_SCREENING",
    "provider": "merklescience",
    "status": "SCREENED",
    "severity": "HIGH",
    "score": 82,
    "summary": "Merkle Science risk: High (4/5). Dominant risk: stolen_funds. Driven by: 50% direct incoming exposure to Theft / Hack (Stolen Funds)",
    "payload": {
      "provider": "merklescience",
      "screening_type": "TRANSACTION_SCREENING",
      "transaction_hash": "0x...",
      "wallet_address": null,
      "blockchain": "ETH",
      "block_timestamp": "2026-04-01T00:07:11Z",
      "total_value_usd": 2942.31,
      "fee_usd": 0.09,
      "transaction_flows": [
        {
          "flow_type": "token",
          "from_address": "0x...",
          "to_address": "0x...",
          "amount": 72.83039728,
          "amount_usd": 235.97,
          "currency": "UNI",
          "token_name": "Uniswap",
          "token_address": "0x1f9840a85d5af5bf1d1762f925bdaddc4201f984",
          "transaction_hash": "0x...",
          "block_timestamp": "2026-04-01T00:07:11Z",
          "index": 460,
          "success": true,
          "metadata": {
            "provider": "blockscout",
            "token_type": "ERC-20",
            "token_icon_url": "https://...",
            "token_reputation": "ok",
            "token_holders_count": "410093",
            "from": {
              "label": "ravaga.eth",
              "tags": [{ "name": "Beacon Depositor", "type": "generic" }]
            },
            "to": {
              "label": "AirSwap: Spender",
              "is_contract": true,
              "is_verified": true
            }
          }
        }
      ],
      "source_of_funds": [
        {
          "category": "stolen_funds",
          "entity_name": "Stolen Funds",
          "entity_type": "Theft",
          "entity_subtype": "Hack",
          "exposure_direction": "incoming",
          "exposure_type": "direct",
          "is_direct": true,
          "amount_usd": 1471.16,
          "percentage": 50,
          "country": ""
        }
      ],
      "destination_of_funds": [],
      "counterparty_connections": [],
      "sanctions_hit": false,
      "risk_factors": [
        {
          "source": "exposure",
          "category": "stolen_funds",
          "label": "Theft / Hack",
          "entity_name": "Stolen Funds",
          "direction": "incoming",
          "exposure_type": "direct",
          "amount_usd": 1471.16,
          "percentage": 50,
          "is_high_risk": true,
          "description": "50% direct incoming exposure to Theft / Hack (Stolen Funds)"
        }
      ],
      "raw_response": { "...": "provider-specific details" }
    }
  }
]
```

`payload.risk_factors` is the ranked explanation of `score` — what produced the verdict, high-risk drivers first and then by value moved. A high `score` with no `is_high_risk` entry means the provider graded the entity on its own exposure model without reporting a sanctions or attributed-entity match; `summary` says so explicitly. Field-by-field reference: [Risk factors](/transaction-monitoring/wallet-screening#risk-factors). Results screened before this field existed omit the key.

For crypto transaction-hash screening, `transaction_flows` is populated when on-chain enrichment is available. It normalizes chain activity so the console can render both the transaction overview and visualization graph from the same response payload.

Supported enrichment sources:

* EVM chains use Blockscout to normalize the main transaction, internal calls, and token transfers.
* Bitcoin uses mempool.space to normalize transaction inputs and outputs.
* Solana uses Helius to normalize native SOL transfers, SPL token transfers, and available NFT event context.

Each `transaction_flows[]` item includes stable normalized fields (`flow_type`, `from_address`, `to_address`, `amount`, `amount_usd`, `currency`, `token_name`, `token_address`, `transaction_hash`, `block_timestamp`, `index`, `success`) plus provider-specific `metadata`.

Common `metadata` examples:

```json theme={null}
{
  "provider": "blockscout",
  "decoded_method_call": "swap(string aggregatorId, address tokenFrom, uint256 amount, bytes data)",
  "block_number": 23141214,
  "gas_used": "171843",
  "fee_native": 0.000342317619518133,
  "token_icon_url": "https://...",
  "token_reputation": "ok"
}
```

```json theme={null}
{
  "provider": "mempool",
  "role": "input",
  "previous_txid": "4c0c...",
  "previous_vout": 0,
  "scriptpubkey_type": "v0_p2wpkh",
  "fee_btc": 0.00000322,
  "block_height": 943130
}
```

```json theme={null}
{
  "provider": "helius",
  "source": "MAGIC_EDEN",
  "type": "NFT_BID",
  "description": "Wallet bid 2.5 SOL on an NFT.",
  "slot": 136658192,
  "fee_sol": 0.000005,
  "nft_event": {
    "type": "NFT_BID",
    "source": "MAGIC_EDEN",
    "nft_mints": ["3bUW..."]
  }
}
```

`metadata` is additive and provider-specific. Do not build critical integrations that require every key to be present for every chain.

### Travel rule

Only present for virtual-asset transfers.

```json theme={null}
"travel_rule": {
  "status": "COMPLIANT",
  "required": true,
  "protocol": "TRP",
  "obligations_count": 2,
  "originator_data": { "name": "...", "wallet_address": "..." },
  "beneficiary_data": { "name": "...", "wallet_address": "..." }
}
```

See [Travel rule](/transaction-monitoring/travel-rule).

### Network snapshot

For crypto transactions, `network_snapshot_id` points to the stored network graph (nodes, edges, metrics). View the graph in the console transaction detail page.

### Tags, notes, metadata

* `tags[]` — attached tags (either by rule action or by analyst).
* `notes[]` — analyst notes.
* `metadata` — free-form JSON you submitted on the request.
* `custom_values` — rule-engine-consumable JSON (typed fields you can reference in conditions).

### Remediation

When a rule triggers `AWAITING_USER`, Didit creates the linked verification session and returns it in two fields:

* `remediation` — the linked session: `{ "session_id", "session_token", "url", "status" }`. Stays populated for the life of the transaction, so you can always see how the user action ended.
* `action_required` — the action the user must take right now, or `null` once nothing is pending: `{ "type": "verification_session", "url", "session_id", "session_token", "status" }` (Travel Rule wallet-ownership actions use `"type": "wallet_ownership"`). Redirect the user to `url`, or feed `session_token` to a Didit SDK.

The same two fields ride on the `transaction.created` and `transaction.status.updated` webhook payloads (`action_required`) - see [webhooks](/transaction-monitoring/webhooks).

## Currency conversion

`amount_in_default_currency` uses mid-market rates from our FX provider at the transaction's `txn_date`. Rules that threshold on "amount" operate on `amount_in_default_currency` by default; rules can opt into the native amount via rule scope.

## Next steps

<CardGroup>
  <Card title="Submit transactions" icon="arrow-right-to-bracket" href="/transaction-monitoring/transactions">
    Full request schema.
  </Card>

  <Card title="Statuses" icon="list-check" href="/transaction-monitoring/statuses">
    What each status means.
  </Card>

  <Card title="Risk scoring" icon="gauge" href="/transaction-monitoring/risk-scoring">
    How score is computed.
  </Card>
</CardGroup>


# Risk Scoring
Source: https://docs.didit.me/transaction-monitoring/risk-scoring

How Didit scores every transaction: rule contributions, thresholds, and status mapping (APPROVED, IN_REVIEW, DECLINED). Pay-per-call $0.02 per transaction.

Every transaction gets a **score** — an integer that summarizes its risk. The score drives the transaction's status (`APPROVED`, `IN_REVIEW`, `DECLINED`) and the decision whether to create an alert, open a case, or require user remediation.

## The formula

```
score = Σ(score_delta of every matched rule)
```

* Base score: 0.
* Each matched rule contributes its configured `score_delta` (typically 25–35).
* A transaction with no matching rules scores 0.

## Thresholds and statuses

Score thresholds are configured per application at *Transactions → Settings*.

| Setting                             | Default | Meaning                                                                                          |
| ----------------------------------- | ------- | ------------------------------------------------------------------------------------------------ |
| `preferred_review_score_threshold`  | 60      | Scores ≥ this go to `IN_REVIEW`                                                                  |
| `preferred_decline_score_threshold` | 85      | Scores ≥ this go to `DECLINED`. The maximum slider value (`500`) means "never decline by score". |

Status assignment:

```
if decline_threshold < 500 and score >= decline_threshold: status = DECLINED
else if score >= review_threshold: status = IN_REVIEW
else: status = APPROVED
```

Individual rule actions can override this — e.g. a rule with `action: change_status → DECLINED` will decline regardless of score.

## Rule contributions — worked example

Suppose these rules fire on a single transaction:

| Rule                                | `score_delta` |
| ----------------------------------- | ------------- |
| High-value outbound (>\$10,000)     | 30            |
| High-risk jurisdiction counterparty | 35            |
| Structuring pattern detected        | 35            |

Total score = 30 + 35 + 35 = **100**.

With default thresholds (60 review, 85 decline), this transaction is `DECLINED`.

## Action overrides

Rules can also directly set the status, bypassing score thresholds:

| Rule action                     | Effect                                                                                                                                                                                                                    |
| ------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `change_status → DECLINED`      | Transaction declined regardless of score                                                                                                                                                                                  |
| `change_status → IN_REVIEW`     | Transaction goes to review regardless of score                                                                                                                                                                            |
| `change_status → AWAITING_USER` | Transaction waits for user remediation - the workflow on the rule action; library rules fall back to your settings choice, then your Biometric Authentication workflow (stored face required), then your default workflow |
| `add_score(n)`                  | Only contributes to the score; no forced status                                                                                                                                                                           |
| `add_tags([...])`               | Attaches tags for console filtering; no score effect                                                                                                                                                                      |
| `add_to_list(...)`              | Adds an identifier to a blocklist                                                                                                                                                                                         |

A single rule can have multiple actions — e.g. `add_score(35)` + `add_tags(["structuring"])` + `add_note("Auto-tagged by structuring preset")`.

## Why scores beat hard rules

A pure threshold (e.g. "decline every transaction over \$100k") triggers both legitimate high-value transactions and real risk. Combining several moderate `score_delta` rules and a review/decline threshold gives you:

* **Layered scoring** — no single rule causes a decline; multiple signals have to agree.
* **Tunable sensitivity** — raise or lower thresholds without touching rule definitions.
* **Ordering of gravity** — a transaction with score 65 goes to review (worth a look); score 90 goes to decline (serious).

## Configuring thresholds

From *Transactions → Settings*:

* **Review threshold**: raise if your review queue is flooded; lower to catch more edge cases.
* **Decline threshold**: raise to reduce false-positive declines; lower to lean toward aggressive blocking. Set it to the maximum value (`500`) to route high scores to review instead of auto-declining.

Changes apply to **new** transactions only — historical transactions retain their evaluation-time status.

## Test mode for rules

Rules can run in `TEST` mode:

* Rule evaluates against transactions but does not contribute to the score or status.
* `TransactionRuleRun` records are created with `is_test = true`.
* Lets you validate a rule's selectivity without risking production declines.

Switch to `ACTIVE` once you're happy with the selectivity.

## Severity and legacy fields

The `severity` field on Transaction and TransactionAlert is nullable and legacy. New rule evaluations don't set it. Use `score` as the primary risk signal.

## Inspecting scores

### Via API

Every transaction response includes `score`, `rules_evaluated_count`, `rules_matched_count`, and a `rule_runs[]` array:

```json theme={null}
{
  "txn_id": "tx-0002",
  "status": "IN_REVIEW",
  "score": 65,
  "rules_evaluated_count": 18,
  "rules_matched_count": 2,
  "rule_runs": [
    {
      "rule_name": "High-value outbound",
      "matched": true,
      "score_delta": 30,
      "severity": null,
      "status_target": null
    },
    {
      "rule_name": "High-risk jurisdiction counterparty",
      "matched": true,
      "score_delta": 35,
      "action_summary": { "add_tags": ["high_risk_country"] }
    }
  ]
}
```

### In the console

On the transaction detail page, the **Score** tab shows a breakdown of each matched rule's contribution and the final status mapping. Hover over the score badge for the threshold values used at evaluation time.

## Next steps

<CardGroup>
  <Card title="Rules" icon="scale-balanced" href="/transaction-monitoring/rules">
    Rule anatomy and evaluation.
  </Card>

  <Card title="Alerts" icon="bell" href="/transaction-monitoring/alerts">
    What happens when a rule fires.
  </Card>

  <Card title="Settings" icon="gear" href="/transaction-monitoring/settings">
    Configure thresholds.
  </Card>
</CardGroup>


# Rules & Scoring
Source: https://docs.didit.me/transaction-monitoring/rules

Configure KYT rules with conditions, velocity windows, and automated actions. Start from preset bundles or build custom. Pay-per-call $0.02 per transaction.

Every transaction submitted to Didit is evaluated against all active rules for your application. Rules define conditions, velocity checks, and actions that determine the transaction's final status and score.

This chapter of the Didit Academy fraud rule engine lesson picks up at creating a rule.

The rule-engine Academy lesson creates a rule on camera at 7:54: trigger, conditions, actions and scoring, then back-testing before deploy.

<VideoEmbed title="Creating a rule — Didit Academy" />

<Note>
  Rules can be managed from the **Business Console**, the **Management API**, and the **Didit MCP**. Use the console when a human on your compliance team should review every change; use the API or MCP when rules are created and tuned programmatically - for example when migrating a rule set from another provider. See the [API reference](/management-api/transactions/rules-list) and the [managing rules via API and MCP guide](/transaction-monitoring/rules-api). Rules are evaluated on every transaction submitted via [`POST /v3/transactions/`](/management-api/transactions/create), and the result appears in the transaction's `rule_runs[]` array (see [response schema](/transaction-monitoring/response-schema)).
</Note>

## Built-in rule bundles

Didit provides a pre-configured rule library covering common regulatory typologies. Install the presets (or whole bundles) you want from the library - in the console, via the [install API](/management-api/transactions/rules-install), or with the MCP tools - and control each installed preset's mode. For the complete catalogue of every preset rule with thresholds and actions, see the [Rules library](/transaction-monitoring/rules-library).

| Bundle                  | Examples                                                                                                                                                                                   |
| ----------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Finance**             | Structuring detection (inbound/outbound), large single transactions above reporting thresholds                                                                                             |
| **AML/CTF**             | Cumulative volume limits, rapid in-and-out movement, sanctions counterparty matching, PEP counterparty exposure, suspicious payment reference keywords                                     |
| **Anomaly detection**   | High velocity inbound/outbound, dormant account reactivation after 12+ months of inactivity                                                                                                |
| **FATF**                | High-risk jurisdiction exposure for counterparties and subject IPs                                                                                                                         |
| **Device intelligence** | Repeated bonus-campaign use from the same device fingerprint, multiple device fingerprints for the same subject                                                                            |
| **Fraud prevention**    | Multi-accounting via shared device fingerprints across distinct subjects                                                                                                                   |
| **Crypto monitoring**   | Mixer/obfuscation service exposure, high-risk wallet addresses (darknet, sanctioned, stolen funds)                                                                                         |
| **Crypto screening**    | High-risk source-of-funds exposure (>30%), multiple risky counterparties, terrorist financing / child exploitation auto-decline, screening-pending hold, medium wallet risk score flagging |
| **Responsible gaming**  | Rapid deposit bursts within short windows                                                                                                                                                  |
| **E-commerce**          | E-commerce specific transaction patterns                                                                                                                                                   |

## Rule sources

Every rule has a `source` that indicates who manages it:

| Source     | Description                                                                                                                                                                                                                                                                                                                         |
| ---------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Preset** | Rules installed from Didit's built-in library. You choose which presets (or whole bundles) to install, and you control each installed preset's mode (`Active`, `Test`, `Disabled`). Their conditions and thresholds are fixed - override one by building a custom rule - and they are removed by uninstalling rather than deleting. |
| **Custom** | Rules created by your team from the Business Console. You have full control over custom rules — create, edit, and delete as needed.                                                                                                                                                                                                 |

## Rule anatomy

Each rule consists of:

| Component               | Description                                                                                                                                                           |
| ----------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Title & description** | Human-readable name and explanation of what the rule detects                                                                                                          |
| **Category**            | Logical grouping (e.g., `finance`, `aml_ctf`, `crypto_monitoring`, `device_intelligence`)                                                                             |
| **Mode**                | `Active` (live evaluation), `Disabled` (skipped), or `Test` (evaluated but results don't affect the transaction)                                                      |
| **Evaluation mode**     | `All` (every condition must match) or `Any` (at least one condition must match)                                                                                       |
| **Scope**               | Limits which transactions the rule applies to. Keys: `transaction_types`, `directions` (`INBOUND`/`OUTBOUND`), `action_types` - empty or missing means no restriction |
| **Conditions**          | Field-level checks — compare transaction fields against values using operators like `eq`, `lt`, `gte`, `in`, `contains_any`, `exists`                                 |
| **Aggregation**         | Velocity windows — aggregate historical transactions over a time period (e.g., count, sum, or distinct count over 1 hour, 7 days, 30 days)                            |
| **Actions**             | What happens when the rule matches (see below)                                                                                                                        |

## Actions

When a rule matches a transaction, one or more actions are executed. Each rule can have multiple actions that are all applied together:

| Action            | `type`          | Keys                                                                                                                                      | Description                                                                                                                                                                                                  |
| ----------------- | --------------- | ----------------------------------------------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| **Add score**     | `add_score`     | `value` (integer, may be negative)                                                                                                        | Add points to the transaction's risk score. The cumulative score across all matched rules determines whether the transaction crosses the review or decline threshold.                                        |
| **Change status** | `change_status` | `value` (`APPROVED`\|`IN_REVIEW`\|`DECLINED`\|`AWAITING_USER`, alias `status`), `workflow_id` (alias `remediation_workflow_id`)           | Directly set the transaction status, regardless of the score. `workflow_id` is required when `value` is `AWAITING_USER` - omitting it returns `400`.                                                         |
| **Add tags**      | `add_tags`      | `tag_uuid` or `tag_name` (one of them), `tag_color`                                                                                       | Tag the transaction for categorization and filtering. An existing tag's `tag_uuid`, or a `tag_name` that is created on first use (stored uppercased); `tag_color` sets the hex color of a newly created tag. |
| **Add note**      | `add_note`      | `note` (alias `value`)                                                                                                                    | Attach an automated text note to the transaction for analyst context.                                                                                                                                        |
| **Add to list**   | `add_to_list`   | `list_id`                                                                                                                                 | Add the subject's `vendor_data` to a blocklist, allowlist, or custom list.                                                                                                                                   |
| **Open case**     | `open_case`     | `blueprint` (case blueprint UUID, optional), `grouping` (`by_applicant`\|`by_rule_and_applicant`), `attach_matched_transaction` (boolean) | Open (or add to) an investigation case. Only the first `open_case` action on a rule is applied.                                                                                                              |

Most preset rules combine **add score** with **change status** — for example, a sanctions counterparty rule adds 90 points to the score *and* immediately declines the transaction.

### Requiring user verification (`AWAITING_USER`)

A **change status → `AWAITING_USER`** action does more than set a status: Didit automatically creates a hosted verification session for the transaction's subject (same `vendor_data`) the moment the rule fires.
The session comes back in the transaction's `action_required` block (and in the `remediation` object) of the create response and every subsequent read, and in both transaction webhooks - so you can redirect the user immediately, see [required user actions](/transaction-monitoring/sdk-transaction-submission#required-user-actions).

Custom rules must name the workflow on the action itself (`workflow_id`) - both the console rule builder and the rules API require it.
Built-in library rules don't carry a workflow; for them the session workflow is resolved in this order:

1. The **remediation workflow** configured in your [transaction settings](/transaction-monitoring/settings#remediation-workflow).
2. Your application's **Biometric Authentication** workflow, when the subject already has a stored reference face from an approved verification.
3. Your application's default workflow.

This means `AWAITING_USER` library rules always produce an actionable session out of the box - a biometric step-up for users you already verified, a full verification otherwise.
Travel Rule transactions are excluded from this automatic fallback: their `AWAITING_USER` wait is for wallet-ownership proof, which has [its own flow](/transaction-monitoring/wallet-ownership-widget).

The strongest choice for high-risk transactions is a **Biometric Authentication** workflow: because the subject is the user you already KYC'd, Didit reuses the verified reference face from their onboarding (the approved liveness selfie, passport chip photo, or document portrait) - the user just takes one live selfie, and Didit runs liveness plus a 1:1 face match against the identity that opened the account.
Stolen credentials, phished OTPs, and SIM swaps all fail at this gate.
Full walkthrough: [step-up biometrics for a high-value withdrawal](/transaction-monitoring/sdk-transaction-submission#example-step-up-biometrics-for-a-high-value-withdrawal).

When the session reaches a decision, the transaction follows it automatically and a `transaction.status.updated` webhook fires: an approved session approves the transaction (`decision_reason_code: user_action_approved`), a declined session declines it (`user_action_declined`), and a session that ends in review sends the transaction to `IN_REVIEW` (`user_action_in_review`).
An expired or abandoned session keeps the transaction in `AWAITING_USER`.

<Note>
  Any workflow type except KYB can be used as the remediation action.
  Biometric Authentication workflows (and workflows where face match runs before ID verification) additionally require a stored reference face for the subject: an approved liveness selfie, passport chip photo, document portrait, or manually enrolled profile face.
  If none exists, the user is asked to complete your application's default workflow instead - which also enrolls their face for next time - and a note on the transaction records the substitution.
  Only when no suitable default workflow exists either is the session skipped, with the note explaining why.
</Note>

## Scoring

When a transaction matches one or more rules, the scores are combined:

1. Each rule match contributes to the transaction's overall **risk score** via the `add_score` action
2. The final score determines the transaction status based on your application's **score thresholds**
3. If any rule has a `change_status` action, that status is applied directly — `DECLINED` always takes priority

Default score thresholds (configurable in the console):

| Setting               | Default | Description                                       |
| --------------------- | ------- | ------------------------------------------------- |
| **Review threshold**  | 60      | Scores at or above this value trigger `IN_REVIEW` |
| **Decline threshold** | 85      | Scores at or above this value trigger `DECLINED`  |

## Creating custom rules

Custom rules can be created from the **Business Console** or through the **Management API** (also reachable from the [Didit MCP](/integration/mcp/tools) and any MCP-connected AI assistant).

<Tabs>
  <Tab title="Console">
    1. Go to **Transactions** > **Rules** in the console
    2. Click **Create Rule**
    3. Define the rule title, description, and category
    4. Set the **mode** - `Active` to run live, or `Test` to evaluate without affecting transactions
    5. Choose the **evaluation mode** - `All` (every condition must match) or `Any` (at least one)
    6. Set the **scope** - which transaction types or directions the rule applies to
    7. Add **conditions** - field comparisons like amount thresholds, country codes, custom property checks
    8. Optionally add **aggregation** - velocity checks over a time window (count, sum, distinct count, and more)
    9. Define one or more **actions** - add score, change status, add tags, add notes, add to list, or open a case
    10. Save and enable the rule
  </Tab>

  <Tab title="API">
    Call [`POST /v3/transactions/rules/`](/management-api/transactions/rules-create) with the same fields: `title`, `category`, `mode`, `evaluation_mode`, `scope`, `conditions`, `aggregation`, `actions`. The complete field, operator, and action reference is on this page, and [managing rules via API and MCP](/transaction-monitoring/rules-api) walks through the recommended create -> backtest -> activate workflow, including migrating a rule set from another provider's CSV export.
  </Tab>
</Tabs>

Rules in `Active` mode take effect immediately for all new transactions. Titles are unique per application.

## Backtesting

Before activating a rule, you can validate it against historical data:

* Set a rule to **Test** mode — the rule is evaluated on every new transaction, but results don't affect the transaction's status or score. Execution statistics (matched count, affected entities) accumulate so you can assess impact before going live.
* Use the **backtest** feature - in the console or via [`POST /v3/transactions/rules/backtest/`](/management-api/transactions/rules-backtest) - to retroactively evaluate a rule's conditions and aggregation against transactions from a specified time period. The backtest returns the number of transactions evaluated, matched, and the affected entities - without modifying any historical data.

## Velocity windows (aggregation)

Velocity rules aggregate historical transaction data over a time period to detect patterns that single-transaction checks would miss:

| Metric                | Description                                                                                                                   |
| --------------------- | ----------------------------------------------------------------------------------------------------------------------------- |
| `count`               | Number of transactions matching the filters in the window                                                                     |
| `sum`                 | Total of a numeric `field` (e.g., `preferred_currency_amount`) in the window                                                  |
| `max` / `min` / `avg` | Largest, smallest, or average value of a numeric `field` in the window                                                        |
| `distinct_count`      | Number of unique values of a `field` (e.g., distinct device fingerprints) in the window (`unique_count` is an accepted alias) |

Each aggregation specifies:

* A **time window**: `<N>m` (minutes), `<N>h` (hours), or `<N>d` (days) - e.g. `30m`, `6h`, `7d`, `30d`. Careful: `m` is **minutes**, not months.
* **Filters** to narrow which historical transactions are included. Keys are field paths from the [field catalog](#field-catalog); the special value `"__current__"` resolves to the same field's value on the transaction being evaluated (e.g. `"subject_vendor_data": "__current__"` scopes the window to the same subject), and a list value means membership.
* An **operator and threshold** (`eq`, `ne`, `gt`, `gte`, `lt`, `lte` against `value`, e.g. count >= 20)

### Example patterns

| Pattern                  | How it works                                                                                         |
| ------------------------ | ---------------------------------------------------------------------------------------------------- |
| **Structuring**          | Count of transactions below \$10,000 for the same subject in 30 days >= 20                           |
| **High velocity**        | Count of inbound transactions for the same subject in 7 days >= 20                                   |
| **Rapid in-and-out**     | Current transaction is outbound + count of inbound transactions for the same subject in 6 hours >= 1 |
| **Multi-accounting**     | Distinct count of subjects sharing the same device fingerprint in 7 days >= 3                        |
| **Dormant reactivation** | Days since subject's previous transaction >= 365, combined with amount >= \$1,000                    |

## Field catalog

Conditions and aggregation filters reference transaction fields by path:

| Field                                                                                                                                      | Description                                                                                            |
| ------------------------------------------------------------------------------------------------------------------------------------------ | ------------------------------------------------------------------------------------------------------ |
| `amount`, `currency`                                                                                                                       | The transaction's amount and currency code                                                             |
| `preferred_currency_amount`, `default_currency_code`                                                                                       | Amount converted to your application's preferred currency (falls back to `amount_in_default_currency`) |
| `direction`                                                                                                                                | `INBOUND` or `OUTBOUND`                                                                                |
| `action_type`                                                                                                                              | Your action type, e.g. `withdrawal`, `deposit`, `bet`                                                  |
| `transaction_type`                                                                                                                         | `finance`, `kyc`, `travel_rule`, `user_event`                                                          |
| `payment_details`                                                                                                                          | Free-text payment reference (the `contains_any` target for keyword rules)                              |
| `score`, `severity`                                                                                                                        | The transaction's current risk score and severity                                                      |
| `subject_vendor_data`, `counterparty_vendor_data`                                                                                          | Your identifiers for the two parties                                                                   |
| `subject_country`, `counterparty_country`                                                                                                  | Party country codes (ISO-2 and ISO-3 both accepted; normalized before comparison)                      |
| `subject_device_fingerprint`, `counterparty_device_fingerprint`                                                                            | Device fingerprint or persistent device id                                                             |
| `subject_browser_family`, `subject_browser_version`, `subject_platform`, `subject_accept_language`, `subject_session_age_ms`               | Device context details (`counterparty_browser_family` also available)                                  |
| `subject_ip_address`, `subject_ip_country`, `counterparty_ip_address`, `counterparty_ip_country`                                           | Network context                                                                                        |
| `subject_payment_method_type`, `subject_payment_method_country`, `subject_payment_method_fingerprint`, `subject_payment_method_account_id` | The subject-side payment method (same four fields exist for `counterparty_payment_method_*`)           |
| `travel_rule_status`, `travel_rule_required`, `travel_rule_obligations_count`                                                              | Travel Rule check state                                                                                |
| `subject_days_since_previous_transaction`                                                                                                  | Days since this subject's previous transaction of the same type (dormancy rules)                       |
| `tags`                                                                                                                                     | The transaction's tag names                                                                            |
| `custom_values.<key>`                                                                                                                      | Any key you submitted in `custom_properties` on transaction create                                     |

## Condition operators

Rules support the following comparison operators for conditions:

| Operator                                  | Description                                                                    | Example                                                      |
| ----------------------------------------- | ------------------------------------------------------------------------------ | ------------------------------------------------------------ |
| `eq` / `ne`                               | Equal / not equal                                                              | `direction eq "OUTBOUND"`                                    |
| `gt` / `gte` / `lt` / `lte`               | Numeric and date comparisons; never match when either side is missing          | `preferred_currency_amount gte 25000`                        |
| `in` / `not_in`                           | Membership in a list (a single scalar value is also accepted)                  | `counterparty_country in ["IRN", "PRK", "SYR"]`              |
| `contains` / `not_contains`               | Case-insensitive substring against a string value                              | `payment_details contains "refund"`                          |
| `contains_any`                            | Any of a list of strings is a case-insensitive substring of the field          | `payment_details contains_any ["terror", "weapon"]`          |
| `regex`                                   | The value pattern matches the field                                            | `subject_vendor_data regex "^guest-"`                        |
| `fuzzy_match`                             | Fuzzy string similarity; requires a `score` threshold (0-100) on the condition | `counterparty_name fuzzy_match "Acme Corp"` with `score: 85` |
| `exists` / `is_not_empty` / `is_not_null` | Field is present (aliases; `value` is ignored)                                 | `subject_device_fingerprint exists`                          |
| `not_exists` / `is_empty` / `is_null`     | Field is absent or empty (aliases; `value` is ignored)                         | `subject_ip_address is_empty`                                |

### Condition value types

An optional `value_type` on a condition changes how `value` is interpreted:

| `value_type`    | Meaning                                                                                                                                                            |
| --------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `list`          | `value` is a list UUID - the blocklist/allowlist/custom list's entries become the comparison value, so a rule can match "counterparty in my custom watchlist".     |
| `field`         | `value` is another field path - the condition compares two transaction fields, e.g. `subject_payment_method_account_id ne counterparty_payment_method_account_id`. |
| `relative_date` | `value` is a relative date, e.g. `{"direction": "past", "unit": "days", "amount": 30}` - for date fields like `txn_date`.                                          |

### Grouped conditions

A flat condition list combines per the rule's `evaluation_mode` (`ALL`/`ANY`). For mixed logic, give conditions a `group_index`: conditions sharing an index form a group, `group_logic` (`AND`/`OR`, default `AND`) combines conditions within a group, and `groups_logic` on the first condition (`AND`/`OR`, default `OR`) combines the group outcomes. When any condition carries a `group_index`, grouped evaluation replaces `evaluation_mode`.

### Referencing custom properties

Every key submitted in the `custom_properties` object of [`POST /v3/transactions/`](/transaction-monitoring/transactions) is stored on the transaction as `custom_values` and can be used in conditions with the field path `custom_values.<key>`. For example, a transaction submitted with `"custom_properties": {"channel": "mobile_app"}` matches the condition `custom_values.channel eq "mobile_app"`. All operators above work with custom properties, and they can also be compared against other fields or used in velocity filters.

In the Console rule builder, keys observed on recently ingested transactions appear automatically in the condition field selector under **Custom Properties**. You can also reference a key before any transaction carries it: choose **Enter custom property** in the same group and type the key exactly as your integration sends it (keys are case-sensitive). The rule simply evaluates as not-matching until transactions carrying that key arrive.

## Automatic blocklist decline

Before any rules are evaluated, Didit checks the transaction's entities against your application's blocklists. If **any** match is found, the transaction is **immediately declined** — rules are not evaluated.

The following entities are checked:

| Entity                 | Blocklist type               | What is checked                                                       |
| ---------------------- | ---------------------------- | --------------------------------------------------------------------- |
| **User (applicant)**   | User Blocklist               | The applicant's `vendor_data` identifier                              |
| **Business**           | Business Blocklist           | The business's `vendor_data` identifier                               |
| **Wallet address**     | Wallet Address Blocklist     | The `account_id` of crypto wallet payment methods                     |
| **Bank account**       | Bank Account Blocklist       | The `account_id` of bank transfer payment methods                     |
| **IP address**         | IP Address Blocklist         | The IP address from the party's device context (supports CIDR ranges) |
| **Device fingerprint** | Device Fingerprint Blocklist | The device fingerprint or persistent device ID                        |

When a blocklist match occurs:

* Transaction status is set to `DECLINED`
* Decision reason is set to `blocklisted`
* An activity record is created for audit tracking

<Note>
  Blocklist checks run before rule evaluation. A blocklisted entity will always be declined regardless of rule configuration or score thresholds.
</Note>

## Transaction screening

Didit integrates with external AML and blockchain analytics providers to enrich transactions with risk intelligence. When a transaction is submitted, the system can:

* **Screen counterparties** against global sanctions and watchlist databases
* **Evaluate wallet addresses** (for crypto transactions) against blockchain intelligence data, including mixer exposure, sanctioned entity connections, and high-risk service interactions
* **Check applicant AML status** by cross-referencing the transaction's linked user against their latest AML screening results

Screening results are attached to the transaction and factor into the rule engine's scoring. If a counterparty or wallet matches a sanctions list, the corresponding rule automatically flags or declines the transaction.

## Next steps

<CardGroup>
  <Card title="Submitting transactions" icon="arrow-right-to-bracket" href="/transaction-monitoring/transactions">
    How transactions are structured for rule evaluation.
  </Card>

  <Card title="Crypto screening" icon="link" href="/transaction-monitoring/aml-screening">
    Crypto screening results and how preset rules use them.
  </Card>

  <Card title="Settings" icon="gear" href="/transaction-monitoring/settings">
    Configure score thresholds and remediation workflows.
  </Card>

  <Card title="API reference" icon="code" href="/management-api/transactions/create">
    Create Transaction API endpoint.
  </Card>
</CardGroup>


# Managing Rules via API and MCP
Source: https://docs.didit.me/transaction-monitoring/rules-api

Create, tune, backtest, and migrate KYT rules programmatically: the Management API endpoints, the MCP tools, and the create - backtest - activate workflow.

Every rule capability of the Business Console is also available programmatically: through the **Management API** with your application API key, and through the **Didit MCP** for AI agents acting as a signed-in console user. Use them to manage rules from code, keep rule sets in version control, or let an AI assistant build and migrate rules for you.

## When to use which surface

| Surface              | Auth                       | Best for                                                                               |
| -------------------- | -------------------------- | -------------------------------------------------------------------------------------- |
| **Business Console** | Console login              | Human review of every change; visual rule building and backtesting                     |
| **Management API**   | `x-api-key`                | Automation from your backend, rule sets in code, CI-managed rule deployments           |
| **Didit MCP**        | Sign in with Didit (OAuth) | AI assistants and agents: the Didit console Copilot, Claude, Cursor, or any MCP client |

## The endpoints

| Endpoint                                                                                  | Purpose                                                       |
| ----------------------------------------------------------------------------------------- | ------------------------------------------------------------- |
| [`GET /v3/transactions/rules/`](/management-api/transactions/rules-list)                  | List rules with filters and performance ordering              |
| [`POST /v3/transactions/rules/`](/management-api/transactions/rules-create)               | Create a custom rule                                          |
| [`GET /v3/transactions/rules/{rule_uuid}/`](/management-api/transactions/rules-get)       | Read one rule with execution counters                         |
| [`PATCH /v3/transactions/rules/{rule_uuid}/`](/management-api/transactions/rules-update)  | Update a custom rule; switch any rule's mode                  |
| [`DELETE /v3/transactions/rules/{rule_uuid}/`](/management-api/transactions/rules-delete) | Delete a custom rule (permanent)                              |
| [`POST /v3/transactions/rules/backtest/`](/management-api/transactions/rules-backtest)    | Evaluate a hypothetical rule against your history             |
| [`GET /v3/transactions/rules/library/`](/management-api/transactions/rules-library)       | Browse the 150+ preset library with install status            |
| [`POST /v3/transactions/rules/install/`](/management-api/transactions/rules-install)      | Install presets by key, bundle, or the intersection of both   |
| [`DELETE /v3/transactions/rules/install/`](/management-api/transactions/rules-uninstall)  | Uninstall presets by key, bundle, or the intersection of both |

The matching MCP tools are `didit_transaction_rule_list`, `didit_transaction_rule_get`, `didit_transaction_rule_create`, `didit_transaction_rule_update`, `didit_transaction_rule_delete`, `didit_transaction_rule_backtest`, `didit_transaction_rule_library_list`, `didit_transaction_rule_install`, and `didit_transaction_rule_uninstall` - see the [MCP tool reference](/integration/mcp/tools).

The full schema - the field catalog, all 19 condition operators, velocity windows, grouped conditions, and the six action types - is documented on the [Rules & Scoring](/transaction-monitoring/rules) page and embedded in the API reference.

## Create, backtest, activate

The safe rollout pattern for any new rule:

<Steps>
  <Step title="Create the rule in TEST mode">
    ```bash theme={null}
    curl -X POST 'https://verification.didit.me/v3/transactions/rules/' \
      -H 'x-api-key: YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{
        "title": "Structuring - inbound (custom)",
        "category": "finance",
        "mode": "TEST",
        "evaluation_mode": "ALL",
        "scope": {"transaction_types": ["finance"]},
        "conditions": [{"field": "amount", "operator": "lt", "value": 10000}],
        "aggregation": [{
          "metric": "count", "operator": "gte", "value": 20, "window": "30d",
          "filters": {"direction": "INBOUND", "subject_vendor_data": "__current__"}
        }],
        "actions": [{"type": "add_score", "value": 35}]
      }'
    ```

    A `TEST` rule evaluates on every new transaction and records what it would have matched, but never touches the transaction's score or status.
  </Step>

  <Step title="Backtest against your history">
    ```bash theme={null}
    curl -X POST 'https://verification.didit.me/v3/transactions/rules/backtest/' \
      -H 'x-api-key: YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{
        "conditions": [{"field": "amount", "operator": "lt", "value": 10000}],
        "aggregation": [{
          "metric": "count", "operator": "gte", "value": 20, "window": "30d",
          "filters": {"direction": "INBOUND", "subject_vendor_data": "__current__"}
        }],
        "period_days": 90
      }'
    ```

    ```json theme={null}
    { "evaluated": 4820, "matched": 12, "affected_entities": 4, "period_days": 90 }
    ```

    A surprising `matched` count means the thresholds need tuning before the rule can act on anything.
  </Step>

  <Step title="Activate">
    ```bash theme={null}
    curl -X PATCH 'https://verification.didit.me/v3/transactions/rules/RULE_UUID/' \
      -H 'x-api-key: YOUR_API_KEY' \
      -H 'Content-Type: application/json' \
      -d '{"mode": "ACTIVE"}'
    ```

    The rule applies to all new transactions of a **live** application immediately.

    <Warning>
      Sandbox applications never evaluate rules. A sandbox transaction is stored and
      nothing more, so activating a rule on a sandbox application changes nothing you
      can observe. Backtest is the supported way to exercise a rule before it goes
      live - see [Transaction Monitoring in sandbox](/integration/sandbox-testing#transaction-monitoring-in-sandbox).
    </Warning>
  </Step>
</Steps>

## Migrating rules from another provider

Because rule creation is a plain API call with a fully documented schema, an AI assistant can translate another provider's rule export into Didit rules for you.

1. **Export** your rules from the current provider - most tools export to CSV or Excel.
2. **Drop the file** into the Didit console assistant (or any MCP-connected agent like Claude with the [Didit MCP](/integration/mcp/overview) attached). Spreadsheets are converted to text automatically.
3. The assistant **maps each row** to the Didit schema - conditions, velocity windows, actions - and shows you the mapping, calling out anything that has no Didit equivalent, before creating anything.
4. On your go-ahead it **creates the rules in TEST mode**, backtests them against your own transaction history, and reports created / failed / unmappable rows.
5. **Review the numbers and activate** the rules that look right, from the console or with a `PATCH {"mode": "ACTIVE"}`.

A provider export like this:

```csv theme={null}
Rule Name,Condition,Threshold,Window (days),Action
Structuring - Small Transfers,count of outbound transfers under amount,20 transfers under 10000 EUR,30,Flag for review
High Value Wire,single transaction amount,> 50000 USD,,Decline
```

becomes rules like this:

```json theme={null}
{
  "title": "Structuring - Small Transfers",
  "category": "finance",
  "mode": "TEST",
  "conditions": [{"field": "amount", "operator": "lt", "value": 10000}],
  "aggregation": [{
    "metric": "count", "operator": "gte", "value": 20, "window": "30d",
    "filters": {"direction": "OUTBOUND", "subject_vendor_data": "__current__"}
  }],
  "actions": [
    {"type": "add_score", "value": 35},
    {"type": "change_status", "value": "IN_REVIEW"}
  ]
}
```

<Tip>
  Before recreating a provider's rule as custom, check the [rule library](/management-api/transactions/rules-library): Didit ships 150+ presets covering the common typologies (structuring, velocity, sanctions exposure, device reuse, crypto risk), and installing a preset is one call.
</Tip>

## Validation errors are precise on purpose

The create and update endpoints validate conditions, aggregation, and scope values against exactly what the rule engine accepts: unknown operators or metrics, malformed windows (`"30days"` instead of `"30d"`), invalid scope directions, `contains_any` without a list, `fuzzy_match` without a `score`, and `change_status` to `AWAITING_USER` without a `workflow_id` all return a `400` naming the index and the problem - instead of storing a rule that silently never matches. Agents and scripts should read the error body and fix the payload. Extra scope keys beyond `transaction_types`, `directions`, and `action_types` are stored but ignored by the engine, matching how the Business Console has always saved them.

## Next steps

<CardGroup>
  <Card title="Rules & Scoring" icon="sliders" href="/transaction-monitoring/rules">
    The full rule schema: fields, operators, velocity windows, actions.
  </Card>

  <Card title="Create Rule API" icon="code" href="/management-api/transactions/rules-create">
    Endpoint reference with request and response schemas.
  </Card>

  <Card title="Rules library" icon="book" href="/transaction-monitoring/rules-library">
    The 150+ preset catalogue and its bundles.
  </Card>

  <Card title="MCP overview" icon="plug" href="/integration/mcp/overview">
    Connect an AI agent to your Didit workspace.
  </Card>
</CardGroup>


# Rules Library
Source: https://docs.didit.me/transaction-monitoring/rules-library

150+ preset KYT rules out of the box: structuring, velocity, layering, sanctions, device, crypto, travel rule, responsible gaming. Pay-per-call $0.02.

Didit ships a curated library of **over 150 preset transaction-monitoring rules** that you can install individually or by bundle. Each rule maps to a real-world AML, fraud, or compliance typology drawn from global standards and regulatory guidance — FATF recommendations, FinCEN advisories, NACHA rules, Wolfsberg principles, and Egmont Group typologies.

Choose the presets or bundles you need, then control each installed rule's mode (`ACTIVE`, `TEST`, or `DISABLED`). Preset conditions, thresholds, and actions are fixed; build a custom rule when you need different logic. Uninstall a preset to remove it from the application, and reinstall it later if needed.

<Note>
  Library rules can be browsed, installed, and uninstalled from *Transactions -> Rules -> Library* in the Business Console, via the [rule library API](/management-api/transactions/rules-library) (`GET /v3/transactions/rules/library/`, `POST`/`DELETE /v3/transactions/rules/install/`), or through the `didit_transaction_rule_library_list` / `didit_transaction_rule_install` / `didit_transaction_rule_uninstall` [MCP tools](/integration/mcp/tools). Installed presets accept `mode` changes only (activate, disable, test); their thresholds are fixed - override one by building a [custom rule](/transaction-monitoring/rules#creating-custom-rules). For how rules contribute to scoring, see [risk scoring](/transaction-monitoring/risk-scoring).
</Note>

## How presets are organised

Every preset belongs to a **bundle** (its functional family) and a **category** (its broader risk theme). Bundles let you toggle related rules together from the console; categories drive scoring and reporting.

| Bundle                              | What it covers                                                                                           |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------- |
| `finance`                           | Structuring, large transactions, cumulative volume, country spread, layering, mule fan-in, smurfing      |
| `aml_ctf`                           | Sanctions, PEP, suspicious payment references, round-amount layering, rapid in-and-out                   |
| `aml_monitoring`                    | Blockchain-derived high-risk source-of-funds exposure, terrorist financing, child exploitation           |
| `anomaly_detection`                 | High velocity, dormant reactivation, off-hours activity                                                  |
| `fatf`                              | High-risk jurisdiction exposure                                                                          |
| `device_intelligence`               | Device fingerprint reuse, multi-fingerprint accounts, IP/browser anomalies, VPN/proxy, impossible travel |
| `fraud_prevention_multi_accounting` | Shared fingerprints across distinct subjects                                                             |
| `fraud_prevention_app`              | Authorised push payment / first-time payee / scam victim signals                                         |
| `fraud_prevention_ato`              | Account takeover composite signals (PII change, new payment method)                                      |
| `fraud_prevention_consortium`       | Counterparties flagged by other institutions in the shared network                                       |
| `crypto_monitoring`                 | Mixer/darknet/sanctioned wallet exposure, chain hopping, unhosted wallets, VASP gaps                     |
| `travel_rule`                       | Global and regional Travel Rule obligations (12 regimes)                                                 |
| `responsible_gaming`                | Safer-play deposit/withdrawal limits, self-exclusion, off-hours play                                     |
| `e_commerce`                        | Card testing microtransactions, chargeback indicators, billing-country mismatch, affiliate burst         |
| `check_fraud`                       | Out-of-range / missing-number / duplicate-presented / dark-web-watchlist / washed checks, kiting         |
| `bnpl`                              | Failed-repayment first-party fraud, shared identifiers across BNPL accounts, fresh-account installments  |

## How to read this page

Each rule lists its `library_key` (stable identifier you can reference in the API or console URL), the conditions and aggregation that make it fire, and the default actions it takes. Numeric thresholds shown here are the ship defaults — every value is editable per application without losing the rule's identity.

***

## Finance bundle

These rules apply to every transaction with `transaction_type = FINANCE`. They model the regulatory baseline (BSA/FinCEN reporting thresholds, FATF velocity heuristics) plus money-mule and smurfing patterns.

### Structuring & near-threshold

| `library_key`                             | Trigger                                                                                          | Default action |
| ----------------------------------------- | ------------------------------------------------------------------------------------------------ | -------------- |
| `structuring-inbound`                     | ≥20 inbound transfers under \$10,000 by the same subject within 30 days                          | +35 score      |
| `structuring-outbound`                    | ≥20 outbound transfers under \$10,000 by the same subject within 30 days                         | +35 score      |
| `single-transaction-just-below-threshold` | A single transaction between $9,000 and $9,999                                                   | +25 score      |
| `round-amount-layering`                   | Transfer amount equals a suspiciously round value ($10k, $25k, $50k, $100k, $250k, $500k, \$1M…) | +20 score      |

### Volume & velocity

| `library_key`                   | Trigger                                                  | Default action         |
| ------------------------------- | -------------------------------------------------------- | ---------------------- |
| `large-single-transaction`      | Single transaction ≥ \$25,000                            | +50 score, `IN_REVIEW` |
| `cumulative-outbound-volume`    | Outbound volume ≥ \$100,000 in 30 days                   | +45 score, `IN_REVIEW` |
| `cumulative-inbound-volume-90d` | Inbound volume ≥ \$200,000 in 90 days                    | +30 score, `IN_REVIEW` |
| `cumulative-outbound-volume-7d` | Outbound volume ≥ \$50,000 in 7 days                     | +30 score, `IN_REVIEW` |
| `business-4h-inbound-volume`    | Business inbound volume ≥ \$30,000 in any 4-hour window  | +30 score, `IN_REVIEW` |
| `business-4h-outbound-volume`   | Business outbound volume ≥ \$30,000 in any 4-hour window | +30 score, `IN_REVIEW` |
| `high-velocity-inbound`         | ≥20 inbound transactions in 7 days                       | +25 score              |
| `high-velocity-outbound`        | ≥20 outbound transactions in 7 days                      | +25 score              |

### Layering, mule & smurfing

| `library_key`                               | Trigger                                                                            | Default action         |
| ------------------------------------------- | ---------------------------------------------------------------------------------- | ---------------------- |
| `rapid-in-and-out-movement`                 | An outbound preceded by an inbound within 6 hours                                  | +60 score, `IN_REVIEW` |
| `cash-deposit-followed-by-withdrawal`       | Cash deposits ≥ \$50,000 in 72h followed by a cash withdrawal                      | +30 score, `IN_REVIEW` |
| `money-mule-fan-in-to-counterparty`         | A counterparty receives transfers from ≥5 distinct subjects in 7 days              | +30 score, `IN_REVIEW` |
| `rapid-repeated-payments-same-counterparty` | ≥5 outbound transfers to the same counterparty in 24 hours                         | +30 score, `IN_REVIEW` |
| `cross-border-small-amount-velocity`        | A subject sends amounts under \$1,000 to ≥4 distinct counterparty countries in 24h | +30 score, `IN_REVIEW` |
| `high-risk-jurisdiction-smurfing`           | ≥5 outbound transfers under \$1,000 to the same high-risk country in 7 days        | +30 score, `IN_REVIEW` |
| `many-unique-counterparties-24h`            | Subject transacts with ≥6 distinct counterparties in 24h                           | +30 score, `IN_REVIEW` |
| `many-unique-payment-methods-7d`            | Subject rotates through ≥4 distinct payment methods in 7 days                      | +30 score, `IN_REVIEW` |
| `counterparty-country-spread-24h`           | Subject transacts with ≥4 distinct counterparty countries in 24h                   | +30 score, `IN_REVIEW` |

### Behavioural anomalies

| `library_key`                  | Trigger                                                                      | Default action |
| ------------------------------ | ---------------------------------------------------------------------------- | -------------- |
| `dormant-account-reactivation` | First transaction ≥ \$1,000 after ≥365 days of inactivity                    | +20 score      |
| `off-hours-high-value-finance` | High-value transfer (≥ \$5,000) tagged as off-hours for the subject's locale | +25 score      |

***

## AML / CTF bundle

These rules model classic AML/CTF typologies that don't depend on blockchain enrichment — they apply universally to fiat and crypto transfers.

| `library_key`                     | Trigger                                                             | Default action         |
| --------------------------------- | ------------------------------------------------------------------- | ---------------------- |
| `sanctions-counterparty`          | Counterparty (or wallet) returns a sanctions hit                    | +90 score, `DECLINED`  |
| `pep-counterparty-exposure`       | Counterparty is a politically-exposed person                        | +40 score, `IN_REVIEW` |
| `suspicious-payment-reference`    | Payment reference contains keywords linked to illicit proceeds      | +45 score, `IN_REVIEW` |
| `high-risk-jurisdiction-exposure` | Counterparty country or subject IP country is on the high-risk list | +40 score, `IN_REVIEW` |
| `high-risk-inbound-single`        | Inbound ≥ \$20,000 from a high-risk country                         | +30 score, `IN_REVIEW` |
| `high-risk-outbound-single`       | Outbound ≥ \$20,000 to a high-risk country                          | +30 score, `IN_REVIEW` |

The default high-risk jurisdiction list ships with FATF call-for-action and conflict-region territories: `IRN`, `PRK`, `SYR`, `AFG`, `RUS`, `MMR`. You can override the list per application.

***

## Crypto screening bundle

These rules consume the enriched data produced by Didit's crypto screening — they're most useful for crypto-native and VASP applications.

| `library_key`                       | Trigger                                                                                         | Default action         |
| ----------------------------------- | ----------------------------------------------------------------------------------------------- | ---------------------- |
| `aml-high-risk-source-exposure`     | ≥30% of source funds originate from sanctioned, darknet, stolen, ransomware, or scam categories | +70 score, `IN_REVIEW` |
| `aml-multiple-risky-counterparties` | ≥3 connections to high-risk entities in the source-of-funds graph                               | +50 score, `IN_REVIEW` |
| `aml-terrorist-financing-exposure`  | Any terrorist-financing exposure on the wallet                                                  | +100 score, `DECLINED` |
| `aml-child-exploitation-exposure`   | Any child-exploitation-material exposure on the wallet                                          | +100 score, `DECLINED` |
| `aml-wallet-risk-score-medium`      | Provider wallet-risk score between 40 and 70                                                    | +30 score              |

***

## Crypto monitoring bundle

Wallet-level exposure rules, plus VASP and Travel-Rule-adjacent integrity checks.

| `library_key`                                 | Trigger                                                  | Default action         |
| --------------------------------------------- | -------------------------------------------------------- | ---------------------- |
| `crypto-mixer-exposure`                       | Wallet linked to a mixer or obfuscation service          | +80 score, `IN_REVIEW` |
| `crypto-darknet_market-exposure`              | Darknet-market wallet exposure                           | +80 score, `IN_REVIEW` |
| `crypto-sanctioned-exposure`                  | Sanctioned wallet exposure                               | +90 score, `IN_REVIEW` |
| `crypto-stolen_funds-exposure`                | Stolen-funds wallet exposure                             | +85 score, `IN_REVIEW` |
| `crypto-scam-exposure`                        | Scam wallet exposure                                     | +70 score, `IN_REVIEW` |
| `crypto-ransomware-exposure`                  | Ransomware wallet exposure                               | +90 score, `IN_REVIEW` |
| `crypto-hacked_exchange-exposure`             | Hacked-exchange wallet exposure                          | +80 score, `IN_REVIEW` |
| `crypto-gambling_unlicensed-exposure`         | Unlicensed-gambling wallet exposure                      | +60 score, `IN_REVIEW` |
| `crypto-wallet-risk-score-critical`           | Provider wallet score ≥ 90                               | +90 score, `IN_REVIEW` |
| `crypto-wallet-risk-score-high`               | Provider wallet score ≥ 70                               | +60 score, `IN_REVIEW` |
| `crypto-unhosted-wallet-large-outbound`       | Outbound ≥ \$1,000 to an unhosted wallet                 | +45 score, `IN_REVIEW` |
| `crypto-repeated-unhosted-wallet-withdrawals` | ≥5 outbound transfers to unhosted wallets in 24h         | +35 score, `IN_REVIEW` |
| `crypto-many-new-wallets-per-subject`         | Subject sends to ≥5 distinct wallets in 24h              | +40 score, `IN_REVIEW` |
| `crypto-chain-hopping-pattern`                | Same subject moves funds across ≥3 blockchains in 24h    | +45 score, `IN_REVIEW` |
| `crypto-missing-vasp-id-high-value`           | Hosted-wallet transfer ≥ \$1,000 with no VASP identifier | +30 score, `IN_REVIEW` |

***

## Travel Rule bundle

Travel Rule rules apply only to `transaction_type = TRAVEL_RULE`. Each regional regime ships four rules (pending counterparty, pending action, missing data, failed exchange).

### Global Travel Rule

| `library_key`                       | Trigger                                                              | Default action             |
| ----------------------------------- | -------------------------------------------------------------------- | -------------------------- |
| `travel-rule-pending-counterparty`  | Status is `AWAITING_COUNTERPARTY` (waiting on the counterparty VASP) | +35 score, `IN_REVIEW`     |
| `travel-rule-pending-action`        | Status is `ON_HOLD` (applicant action required)                      | +35 score, `AWAITING_USER` |
| `travel-rule-missing-required-data` | Required = true and obligations remain unresolved                    | +50 score, `IN_REVIEW`     |

### Regional regimes

The same four-rule template is applied per regime. Substitute `<regime>` below for any of: `australia`, `dubai`, `eu`, `hong_kong`, `india`, `indonesia`, `japan`, `kazakhstan`, `singapore`, `south_africa`, `turkey`, `uk`.

Regime tagging is automatic: Didit stamps `custom_values.travel_rule_regime` on every Travel Rule transaction from your [Travel Rule settings](/transaction-monitoring/travel-rule#setup) `jurisdiction` - `SG` → `singapore`, `GB` → `uk`, and any EU or EEA member code such as `DE` or `FR` → `eu`. Codes without a regional bundle stamp lowercased (`US` → `us`), so custom rules can still target them. A `props.travel_rule_regime` value submitted on the transaction always overrides the derived regime.

| `library_key` template                       | Trigger                                             |
| -------------------------------------------- | --------------------------------------------------- |
| `travel-rule-<regime>-pending-counterparty`  | Regime-tagged transfer waiting on counterparty VASP |
| `travel-rule-<regime>-pending-action`        | Regime-tagged transfer needs applicant action       |
| `travel-rule-<regime>-missing-required-data` | Regime-tagged transfer is required but unresolved   |
| `travel-rule-<regime>-failed-exchange`       | Regime-tagged transfer failed                       |

That's 48 region-specific rules in addition to the three global Travel-Rule rules.

***

## Device intelligence & fraud prevention

These rules turn signals from the client SDK (device fingerprint, IP, browser, session age) and provider enrichment into fraud-detection events.

### Device fingerprint & multi-accounting

| `library_key`                                   | Trigger                                                             | Default action         |
| ----------------------------------------------- | ------------------------------------------------------------------- | ---------------------- |
| `multi-accounting-shared-fingerprint`           | One device fingerprint reused across ≥3 distinct subjects in 7 days | +50 score, `IN_REVIEW` |
| `multiple-device-fingerprints-for-same-subject` | One subject appears on ≥3 distinct fingerprints in 24h              | +20 score              |
| `same-fingerprint-transaction-burst`            | ≥6 transactions from one fingerprint in 24h                         | +30 score              |
| `same-ip-multi-accounting`                      | One IP shared by ≥3 distinct subjects in 7 days                     | +30 score              |
| `same-ip-transaction-burst`                     | ≥6 transactions from one IP in 24h                                  | +30 score              |
| `same-fingerprint-multiple-payment-methods`     | One fingerprint cycling through ≥4 payment methods in 7 days        | +30 score              |
| `shared-payment-method-across-subjects`         | One payment method reused by ≥3 distinct subjects in 7 days         | +30 score              |
| `many-ip-addresses-per-subject`                 | Subject uses ≥4 distinct IPs in 24h                                 | +30 score              |
| `new-browser-and-new-ip-combination`            | Subject shows ≥3 distinct browsers AND ≥3 distinct IPs in 24h       | +30 score              |

### IP, network & VPN

| `library_key`                            | Trigger                                                       | Default action |
| ---------------------------------------- | ------------------------------------------------------------- | -------------- |
| `vpn-or-proxy-high-value`                | VPN or proxy detected on a transfer ≥ \$5,000                 | +30 score      |
| `impossible-travel-between-transactions` | Subject transacts from ≥2 distinct IP countries within 1 hour | +30 score      |

### Behavioural composite

| `library_key`                                 | Trigger                                                                                    | Default action |
| --------------------------------------------- | ------------------------------------------------------------------------------------------ | -------------- |
| `browser-spoofing-password-reuse`             | Browser-spoofing detected AND ≥2 transactions reusing the same password hash in 30 minutes | +30 score      |
| `remote-access-high-value-transfer`           | Remote-access tool detected on a transfer ≥ \$5,000                                        | +30 score      |
| `low-session-age-high-value-transfer`         | Transfer ≥ \$5,000 within 30 seconds of session start                                      | +30 score      |
| `synthetic-identity-fresh-account-high-value` | Account opened in the last 7 days transacts ≥ \$1,000                                      | +30 score      |

### Account takeover & APP fraud

| `library_key`                       | Trigger                                                                 | Default action         |
| ----------------------------------- | ----------------------------------------------------------------------- | ---------------------- |
| `recent-pii-change-and-transaction` | Transfer ≥ \$1,000 within the recent-PII-change window                  | +45 score, `IN_REVIEW` |
| `new-payment-method-high-value`     | Transfer ≥ \$5,000 using a payment method added in the last 7 days      | +30 score              |
| `first-time-payee-high-value`       | Outbound ≥ \$5,000 to a counterparty the subject has never paid before  | +40 score, `IN_REVIEW` |
| `consortium-flagged-counterparty`   | Transfer ≥ \$500 whose counterparty was reported by another institution | +60 score, `IN_REVIEW` |

### Affiliate & bonus abuse

| `library_key`                                   | Trigger                                                   | Default action |
| ----------------------------------------------- | --------------------------------------------------------- | -------------- |
| `repeated-bonus-campaign-from-same-fingerprint` | ≥6 transactions on the same campaign + fingerprint in 2h  | +35 score      |
| `shared-fingerprint-across-bonus-campaigns`     | One fingerprint claims ≥3 distinct campaigns in 7 days    | +30 score      |
| `affiliate-fraud-repeated-fingerprint`          | ≥5 transactions on the same affiliate + fingerprint in 2h | +30 score      |

***

## Responsible gaming bundle

For iGaming applications. These rules are designed to detect both player-protection signals and bonus-abuse patterns.

| `library_key`                                  | Trigger                                                 | Default action |
| ---------------------------------------------- | ------------------------------------------------------- | -------------- |
| `responsible-gaming-rapid-deposits`            | ≥10 inbound transactions of the same action in 24h      | +20 score      |
| `responsible-gaming-rapid-withdrawals`         | ≥8 outbound transactions of the same action in 24h      | +20 score      |
| `responsible-gaming-cumulative-deposits-7d`    | Inbound volume ≥ \$5,000 in 7 days                      | +20 score      |
| `responsible-gaming-cumulative-withdrawals-7d` | Outbound volume ≥ \$5,000 in 7 days                     | +20 score      |
| `responsible-gaming-self-excluded-activity`    | Any transaction from a self-excluded account            | +20 score      |
| `responsible-gaming-loss-limit-hit`            | Activity continues after a loss-limit signal            | +20 score      |
| `responsible-gaming-bonus-hunting`             | ≥4 same-campaign + same-fingerprint transactions in 24h | +20 score      |
| `responsible-gaming-multiple-payment-methods`  | ≥4 distinct payment methods in 7 days                   | +20 score      |
| `responsible-gaming-off-hours-high-value`      | Off-hours-tagged play ≥ \$1,000                         | +20 score      |
| `responsible-gaming-failed-withdrawals`        | ≥3 failed-withdrawal attempts                           | +20 score      |
| `responsible-gaming-many-counterparties`       | ≥5 distinct counterparties in 24h                       | +20 score      |

***

## E-commerce bundle

For marketplaces and merchant-of-record applications.

| `library_key`                              | Trigger                                                   | Default action |
| ------------------------------------------ | --------------------------------------------------------- | -------------- |
| `ecommerce-card-testing-microtransactions` | ≥10 transactions ≤ \$5 from the same fingerprint in 1h    | +30 score      |
| `ecommerce-high-order-velocity`            | ≥8 transactions on one fingerprint in 30 minutes          | +30 score      |
| `ecommerce-chargeback-indicator`           | Provider/workflow has flagged a chargeback indicator      | +30 score      |
| `ecommerce-billing-country-mismatch`       | Billing-country mismatch on a transaction ≥ \$500         | +30 score      |
| `ecommerce-shared-payment-method`          | Payment method reused by ≥3 e-commerce subjects in 7 days | +30 score      |
| `ecommerce-shared-ip-multi-accounting`     | One IP shared across ≥4 e-commerce subjects in 24h        | +30 score      |
| `ecommerce-remote-checkout-high-value`     | Remote-access detected on checkout ≥ \$1,000              | +30 score      |
| `ecommerce-affiliate-burst`                | ≥5 transactions on same affiliate + fingerprint in 2h     | +30 score      |

***

## Check fraud bundle

For applications submitting check-deposit transactions. Each rule fires off `custom_values.check_*` flags the caller sets when a check carries a known risk signal (washing, missing MICR, dark-web-listed serial, etc.).

| `library_key`                     | Trigger                                                                                | Default action         |
| --------------------------------- | -------------------------------------------------------------------------------------- | ---------------------- |
| `check-amount-out-of-range`       | Check amount flagged as outside the account's normal range AND ≥ \$1,000               | +40 score, `IN_REVIEW` |
| `check-missing-or-invalid-number` | Check arrived with a missing, inconsistent, or non-sequential check number             | +35 score, `IN_REVIEW` |
| `check-duplicate-presentation`    | Same check appears to have been deposited twice (mobile + branch)                      | +70 score, `IN_REVIEW` |
| `check-on-dark-web-watchlist`     | Check serial / image was found on a dark-web or Telegram stolen-check feed             | +90 score, `DECLINED`  |
| `check-altered-or-washed`         | Check shows chemical-erasure, MICR alteration, or other washing evidence               | +70 score, `IN_REVIEW` |
| `check-deposit-rapid-multi-bank`  | Same subject deposits checks across ≥3 distinct counterparty banks within 24h (kiting) | +45 score, `IN_REVIEW` |

***

## BNPL bundle

For buy-now-pay-later providers. Surfaces first-party-fraud (non-payment) and identifier-sharing patterns specific to installment lending.

| `library_key`                            | Trigger                                                                  | Default action         |
| ---------------------------------------- | ------------------------------------------------------------------------ | ---------------------- |
| `bnpl-failed-repayment-velocity`         | ≥2 recent failed repayments on the subject — first-party fraud signal    | +45 score, `IN_REVIEW` |
| `bnpl-shared-identifier-across-accounts` | Phone, email or address has been seen on multiple distinct BNPL subjects | +40 score, `IN_REVIEW` |
| `bnpl-high-installment-on-fresh-account` | Installment ≥ \$500 from an account opened in the last 7 days            | +35 score              |

***

## Reference: standards behind the library

Every preset in Didit's library maps to a widely-accepted AML, fraud, or compliance typology. The standards we lean on:

| Source                      | Typologies contributed to the library                                                                             |
| --------------------------- | ----------------------------------------------------------------------------------------------------------------- |
| **FATF recommendations**    | Structuring, rapid movement of funds, high-risk jurisdiction exposure, counterparty PEP / sanctions screening     |
| **FinCEN advisories**       | BSA / CTR reporting thresholds, dormant-account reactivation, suspicious cash patterns                            |
| **NACHA rules**             | ACH specific thresholds and off-hours patterns                                                                    |
| **Wolfsberg principles**    | Correspondent banking and private banking typologies                                                              |
| **Egmont Group typologies** | Cross-border and layering patterns                                                                                |
| **Industry best practice**  | Velocity windowing, impossible-travel, first-time-payee, device-fingerprint reuse, BNPL first-party fraud signals |

Didit implements only the typologies that are accepted industry standards and exposes every threshold for you to tune.

***

## Customising presets

Every preset can be:

* **Tuned** — change thresholds, windows, score values, or actions per application
* **Disabled** — switch a preset to `DISABLED` mode and it stops evaluating without losing its identity
* **Tested** — switch a preset to `TEST` mode to evaluate it shadow-mode without affecting transaction outcomes
* **Extended** — create custom rules that complement or override presets

See [Rules & scoring](/transaction-monitoring/rules) for the rule anatomy, the API endpoints, and worked examples of creating custom rules.


# SDK Event Submission
Source: https://docs.didit.me/transaction-monitoring/sdk-event-submission

Capture logins, gameplay and session activity from the device with a scoped credential - subject binding and network context enforced server-side.

Most [events](/transaction-monitoring/events) that matter for fraud happen on the device: the login, the session, the gameplay round, the timing telemetry that separates a person from a script. The device lane sends them without putting an API key in a browser.

Your backend mints a short-lived credential scoped to one user; the app posts events with it.

## Flow

<Steps>
  <Step title="Mint a monitoring credential">
    Your backend calls `POST /v3/events/sdk-token/` with your API key and the user's `vendor_data`.
  </Step>

  <Step title="Submit from the device">
    The app posts to `POST /v1/events/` (or `POST /v1/events/batch/`) with the `X-Monitoring-Token` header.
  </Step>

  <Step title="Rules run as usual">
    The event is enriched, rolled up and evaluated by exactly the same [rules](/transaction-monitoring/event-rules) as a server-submitted one.
  </Step>
</Steps>

## Minting a credential

<Note>
  Minting requires [event ingestion](/transaction-monitoring/events) to be switched on for the application. While it is off, this endpoint answers `403` with `{"code": "event_monitoring_disabled"}` rather than handing out a credential that could never write.
</Note>

```bash theme={null}
curl -X POST https://verification.didit.me/v3/events/sdk-token/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user_391",
    "allowed_event_categories": ["auth", "session", "gameplay"],
    "ttl_seconds": 900,
    "max_uses": 1000,
    "bind_to_origin": "https://operator.example"
  }'
```

```json theme={null}
{
  "monitoring_token": "…",
  "expires_at": "2026-08-31T21:00:00Z",
  "allowed_event_categories": ["auth", "session", "gameplay"],
  "max_uses": 1000,
  "bind_to_origin": "https://operator.example"
}
```

| Field                      | Default      | Notes                                                              |
| -------------------------- | ------------ | ------------------------------------------------------------------ |
| `vendor_data`              | required     | The subject every event submitted with this credential belongs to. |
| `entity_type`              | `individual` | `individual` or `company`.                                         |
| `allowed_event_categories` | all          | Narrow what a leaked credential could write.                       |
| `ttl_seconds`              | 900          | 60 - 86400.                                                        |
| `max_uses`                 | 1000         | One use per **event**, not per request.                            |
| `bind_to_origin`           | none         | When set, the browser `Origin` must match exactly.                 |

## Submitting

```bash theme={null}
curl -X POST https://verification.didit.me/v1/events/ \
  -H "X-Monitoring-Token: THE_MINTED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "event_id": "session-abc-login-1",
    "event_category": "auth",
    "action_type": "login",
    "occurred_at": "2026-08-31T20:40:31.123Z",
    "session": { "session_id": "web-session-abc", "sequence": 1 },
    "device_context": { "fingerprint": "didit-fp-v2:a8c1" },
    "payload": { "method": "password" }
  }'
```

Note what the payload does **not** carry: no API key, and no subject. Both are enforced server-side.

## What the server enforces

* **Subject binding.** The credential is scoped to one `vendor_data` at mint time. A `subject` block in the request body is overwritten, so a tampered client cannot write to another user's timeline.
* **Network context.** The IP address, user agent, accept-language and origin are derived from the request, and those server-derived values win over any client hint for rule evaluation. Rule evidence records the difference as a [field source](/transaction-monitoring/event-rules#evidence).
* **Category scope.** A credential scoped to `session` cannot submit a `payment` event; it is rejected with `400`.
* **Use budget.** A batch spends one use per event, so a 500-event batch cannot slip past a 10-use credential as a single use.
* **Origin binding.** When `bind_to_origin` is set, a request whose `Origin` does not match is refused - including one with no `Origin` at all.

## Batching

```bash theme={null}
curl -X POST https://verification.didit.me/v1/events/batch/ \
  -H "X-Monitoring-Token: THE_MINTED_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "events": [ { "…": "…" }, { "…": "…" } ] }'
```

Up to 500 events per flush, with the same per-item outcomes as the [server batch endpoint](/transaction-monitoring/events#batches). A good default flush is 25 events, 5 seconds, or page/app backgrounding.

### What to drop under backpressure

If you have to shed events, shed the cheap ones. These are safe to drop:

`session.page_view` · `session.sdk_heartbeat` · `session.sdk_loaded` · `session.device_seen` · `session.bot_signal_observed` · `bonus.promotion_viewed` · `affiliate.referral_clicked`

These are not - flush them first:

every `security`, `payment`, `dispute` and `responsible_gambling` event, plus `gameplay.bet_placed`, `gameplay.bet_settled` and `gameplay.p2p_settlement`.

The list endpoints return the same classification per event as `is_droppable`, so a client can be driven by it rather than by a hardcoded copy.

## Header compatibility

The canonical header is `X-Monitoring-Token`. `X-Transaction-Token` is accepted as a temporary alias so an app that already holds a transaction credential path can migrate incrementally.

<Warning>
  The alias is transitional and will be removed before the events API reaches general availability. Send `X-Monitoring-Token` in new code.
</Warning>

## Choosing a lane

|          | Device lane                           | Server lane                                          |
| -------- | ------------------------------------- | ---------------------------------------------------- |
| Endpoint | `POST /v1/events/`                    | `POST /v3/events/`                                   |
| Auth     | `X-Monitoring-Token`                  | `x-api-key`                                          |
| Subject  | Bound to the credential               | In the payload                                       |
| Best for | Logins, sessions, gameplay, telemetry | Payments, disputes, ledger-derived events, backfills |

Both produce identical event records and run identical rules. Use the server lane whenever no end user is present.

## Next

<CardGroup>
  <Card title="Event ingestion" icon="bolt" href="/transaction-monitoring/events">
    The envelope, categories, retention and idempotency.
  </Card>

  <Card title="Rules on events" icon="filter" href="/transaction-monitoring/event-rules">
    Velocity, ratio, sequence and correlation rules.
  </Card>
</CardGroup>


# SDK Transaction Submission
Source: https://docs.didit.me/transaction-monitoring/sdk-transaction-submission

Submit monitored transactions straight from your app with a scoped token: automatic device intelligence, spoof-proof subject binding, an auto-launched wallet-ownership flow.

The Didit SDKs can submit [monitored transactions](/transaction-monitoring/transactions) directly from the end-user's device, including [Travel Rule](/transaction-monitoring/travel-rule) transfers and crypto screening.
Your backend mints a short-lived scoped token; the SDK does the rest.
It attaches device intelligence automatically, and when a Travel Rule transfer needs proof of wallet control, it auto-launches that flow on the spot.
A required verification session is never auto-launched - it comes back in the response for your app to launch with your own Didit verification integration; see [Required user actions](#required-user-actions) below.

## Overview

Client-side submission is built on three guarantees:

* **Spoof-proof subject binding.** The token is scoped to one `vendor_data` (your user id) at mint time. The subject identity of every transaction submitted with it is enforced server-side from that binding, so a tampered client cannot submit on behalf of another user, and the payload never needs to carry credentials.
* **Automatic device intelligence.** The SDK collects a device fingerprint and sends it with the submission, and Didit derives the IP address and user agent server-side. The combined device context is attached to the transaction's subject with no extra library, no separate device token, and no plumbing on your side. It powers device-based [rules](/transaction-monitoring/rules) and related-by-device correlation across sessions and transactions.
* **Auto-launched wallet-ownership proof.** When the created transaction requires the end user to prove control of a wallet, the response carries an `action_required` block of type `wallet_ownership` and the SDK opens that flow immediately, then refreshes the transaction when it finishes - no polling loops or link delivery to build yourself. A required `verification_session` action is different: it is never auto-launched, and comes back in the same block for your app to launch with its own Didit verification integration.

<Note>
  Server-side [`POST /v3/transactions/`](/transaction-monitoring/transactions) remains the right choice when no end user is present: back-office transfers, batch imports, or events reported by your own systems.
  Both paths create the same transaction records, run the same rules, and emit the same [webhooks](/transaction-monitoring/webhooks).
</Note>

## Flow

<Steps>
  <Step title="Mint a transaction token">
    Your backend calls `POST /v3/transactions/sdk-token/` with your API key and the user's `vendor_data`, and hands the returned `sdk_token` to your app.
  </Step>

  <Step title="Submit from the device">
    The app calls `submitTransaction` on the SDK, which posts the payload to `POST /v1/transactions/` with the `X-Transaction-Token` header and automatic device enrichment.
  </Step>

  <Step title="Handle any required action">
    If `action_required.type` is `wallet_ownership`, the SDK auto-launches the widget, then refreshes the transaction via `GET /v1/transactions/{transaction_id}/`.
    If it's `verification_session`, the SDK does not launch anything - read `action_required` and start your own verification flow with its `session_token` (or `url` on web).
  </Step>
</Steps>

## Minting a transaction token

Mint tokens from your backend with `POST /v3/transactions/sdk-token/` - the same API-key authentication as the rest of the `/v3/` transaction endpoints.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/transactions/sdk-token/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "vendor_data": "user-042",
    "ttl_seconds": 900,
    "max_uses": 3
  }'
```

```json theme={null}
{
  "sdk_token": "q7Zt...urlsafe",
  "expires_at": "2026-07-07T12:15:00Z"
}
```

| Field         | Type    | Description                                                                                                                                                                    |
| ------------- | ------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `vendor_data` | string  | **Required.** Your internal identifier for the end user this token is scoped to. Every transaction submitted with the token has its subject identity enforced from this value. |
| `ttl_seconds` | integer | Token lifetime in seconds. Defaults to `900` (15 minutes); maximum `86400` (24 hours).                                                                                         |
| `max_uses`    | integer | Optional. Maximum number of successful submissions allowed with this token. Omit for unlimited uses within the TTL.                                                            |

camelCase aliases (`vendorData`, `ttlSeconds`, `maxUses`) are also accepted, like the rest of the `/v3/` API.

<Warning>
  **Never ship your API key in an app.**
  The API key stays on your backend and mints tokens; only the short-lived `sdk_token` travels to the device.
  Mint a fresh token per user session rather than reusing long-lived ones, and keep `max_uses` tight when the number of expected submissions is known.
</Warning>

## Submitting from the device

The SDKs post to `POST /v1/transactions/` with the token in the `X-Transaction-Token` header.
The wire payload is camelCase; the `submitTransaction` methods build it for you, so you only deal with it directly when calling the endpoint from your own HTTP client:

```bash theme={null}
curl -X POST https://verification.didit.me/v1/transactions/ \
  -H "X-Transaction-Token: SDK_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "txnId": "wd-2026-07-07-0042",
    "type": "travelRule",
    "info": {
      "direction": "out",
      "amount": "0.25",
      "currency": "ETH",
      "currencyType": "crypto",
      "cryptoParams": { "crypto_chain": "ETH" }
    },
    "subject": { "fullName": "Jane Doe" },
    "counterparty": {
      "fullName": "Ana Diaz",
      "paymentMethod": { "type": "unhosted_wallet", "accountId": "0xBeneficiaryWallet01" }
    },
    "travelRule": {
      "status": "AWAITING_COUNTERPARTY",
      "beneficiaryData": { "wallet_address": "0xBeneficiaryWallet01", "name": "Ana Diaz" }
    },
    "includeCryptoScreening": true
  }'
```

Each top-level field maps onto its [`POST /v3/transactions/`](/transaction-monitoring/transactions) equivalent:

| Wire field                | `/v3/` equivalent          | Notes                                                                                                                                                                                                                                                                                                                                               |
| ------------------------- | -------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `txnId`                   | `transaction_id`           | **Required.** Your unique identifier for the transaction.                                                                                                                                                                                                                                                                                           |
| `txnDate`                 | `transaction_at`           | ISO-8601 timestamp; defaults to now.                                                                                                                                                                                                                                                                                                                |
| `zoneId`                  | `time_zone`                | IANA time zone id, e.g. `Europe/Madrid`.                                                                                                                                                                                                                                                                                                            |
| `type`                    | `transaction_category`     | **Required.** `finance`, `kyc`, `travelRule`, `userPlatformEvent`, `gamblingBet`, and the other categories.                                                                                                                                                                                                                                         |
| `info`                    | `transaction_details`      | **Required.** `direction`, `amount`, `currency` (required), plus `currencyType`, `amountInDefaultCurrency`, `defaultCurrencyCode`, `paymentDetails`, `paymentTxnId`, `type` (action type), `cryptoParams`.                                                                                                                                          |
| `subject`, `counterparty` | `subject`, `counterparty`  | Participants: `type` (entity type), `externalUserId`, `fullName`, `firstName`, `lastName`, `dob`, `address`, `institutionInfo`, `device`, `paymentMethod` (`type`, `accountId`, `issuingCountry`). A counterparty `paymentMethod.type` of `unhosted_wallet` declares the destination as self-hosted - see [below](#declaring-a-self-hosted-wallet). |
| `props`                   | `custom_properties`        | Custom key-value pairs, usable in rules as `custom_values.<key>`.                                                                                                                                                                                                                                                                                   |
| `travelRule`              | `travel_rule_details`      | `status`, `protocol`, `required`, `obligationsCount`, `originatorData`, `beneficiaryData`, `metadata`. When Travel Rule is enabled, Didit ignores any `status` you send and drives the exchange itself.                                                                                                                                             |
| `includeCryptoScreening`  | `include_crypto_screening` | Per-transaction crypto screening override.                                                                                                                                                                                                                                                                                                          |

The response is the same snake\_case transaction detail as the `/v3/` endpoints, plus the `action_required` block:

```json theme={null}
{
  "uuid": "22222222-3333-4444-5555-666666666666",
  "txn_id": "wd-2026-07-07-0042",
  "transaction_type": "travelRule",
  "direction": "OUTBOUND",
  "status": "APPROVED",
  "amount": "0.25",
  "currency": "ETH",
  "travel_rule": {
    "uuid": "33333333-4444-5555-6666-777777777777",
    "status": "UNCONFIRMED_OWNERSHIP",
    "required": true
  },
  "action_required": {
    "type": "wallet_ownership",
    "url": "https://verify.didit.me/wallet-ownership/3s9x...urlsafe",
    "widget_session_id": "77777777-8888-9999-aaaa-bbbbbbbbbbbb",
    "expires_at": "2026-07-07T13:00:00Z"
  }
}
```

### Declaring a self-hosted wallet

The example above declares the destination as the user's own self-hosted wallet: the counterparty's `paymentMethod.type` is `unhosted_wallet`.
That declaration changes how the [Travel Rule exchange](/transaction-monitoring/travel-rule#declared-self-hosted-wallets) runs:

* Didit skips counterparty-VASP routing entirely - there is no VASP behind a self-hosted wallet - and creates the transfer directly in `UNCONFIRMED_OWNERSHIP`.
* When `auto_wallet_verification` is on in your [Travel Rule settings](/transaction-monitoring/travel-rule#setup) (the default), a [wallet-ownership widget](/transaction-monitoring/wallet-ownership-widget) session is auto-minted and returned in `action_required`, exactly as in the response above.
* The SDK auto-launches the widget; once the user proves control of the wallet, the transfer runs the name match and advances to `COMPLETED`.

Without the declaration, Didit instead tries the [rails](/transaction-monitoring/travel-rule#overview) in order and only falls back to the ownership flow if no counterparty VASP can be found.
Declare the wallet whenever your product already knows the withdrawal target is the user's own wallet - it saves the failed routing pass and gets the user into the proof flow immediately.

### Subject enforcement

Three things are always decided by the token, never by the payload:

* The application the transaction is created under.
* The subject's identity: `subject.externalUserId` in the payload is ignored and replaced with the token's `vendor_data`.
* The device context of the subject (see below); server-derived fields win on conflict with anything supplied in `subject.device`.

A `401` from this endpoint means the token was rejected: missing, unknown, revoked, over its `max_uses`, or expired.
Expired-token responses always contain the word `expired` in the error detail, which is how the SDKs distinguish `expired_token` from `invalid_token` errors.

### Reading the transaction back

`GET /v1/transactions/{transaction_id}/` returns the same detail with the same `X-Transaction-Token` authentication.
The SDKs call it automatically after a launched action flow completes or its window closes, so the final state never depends on a single event or notification.
Use it yourself to re-check `status` and `action_required` at any point while the token is valid; from your backend, [`GET /v3/transactions/{transaction_id}/`](/transaction-monitoring/transactions) returns the same record.

## Automatic device intelligence

Every submission carries device intelligence without any integration work on your side:

* The SDK collects a privacy-safe device fingerprint (the `didit-fp-v2` schema: platform and navigator signals, a persistent device id, a bot score, and a composite hash) and sends it with the request.
* Didit derives the IP address, user agent, and accept-language server-side from the connection itself, so they cannot be forged by the payload.

The merged result is normalized into the subject participant's device context and upserted into the device graph, the same one KYC sessions feed.
That makes transactions correlatable by device across your whole user base ("related by device"), feeds device and network signals into [rules](/transaction-monitoring/rules) and [IP enrichment](/transaction-monitoring/ip-enrichment), and shows up on the transaction detail in the [Console](/transaction-monitoring/console).

Server-submitted `/v3/` transactions can keep passing explicit `device_context` objects per participant; on the SDK path you get a stronger version of the same data for free.

## Required user actions

Some transactions need the end user to do something before they can settle: a rule can require a verification session, or a Travel Rule transfer can require proof that the destination wallet is really the user's.
Both cases surface in the same place - the `action_required` block of the submit response (and of every subsequent read of the transaction):

```json theme={null}
"action_required": {
  "type": "verification_session",
  "url": "https://verify.didit.me/session/...",
  "session_id": "11111111-2222-3333-4444-555555555555",
  "session_token": "SESSION_TOKEN",
  "status": "Not Started"
}
```

```json theme={null}
"action_required": {
  "type": "wallet_ownership",
  "url": "https://verify.didit.me/wallet-ownership/3s9x...urlsafe",
  "widget_session_id": "77777777-8888-9999-aaaa-bbbbbbbbbbbb",
  "expires_at": "2026-07-07T13:00:00Z"
}
```

| Type                   | When it appears                                                                                                                                                                                                                                                                                                                                                                                                                                                                           | What the user does                                                                                                                                                                  |
| ---------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `verification_session` | A [rule action](/transaction-monitoring/rules) required additional user verification and the transaction moved to `AWAITING_USER`.                                                                                                                                                                                                                                                                                                                                                        | Completes a hosted verification session (for example a biometric re-check), launched by your app - see [Launching a verification session](#launching-a-verification-session) below. |
| `wallet_ownership`     | A Travel Rule transfer needs end-user proof of wallet control - the destination was [declared a self-hosted wallet](#declaring-a-self-hosted-wallet) (`UNCONFIRMED_OWNERSHIP`), or an outbound transfer found no counterparty VASP - and `auto_wallet_verification` is enabled in your [Travel Rule settings](/transaction-monitoring/travel-rule#setup). Didit auto-mints a [wallet-ownership widget](/transaction-monitoring/wallet-ownership-widget) session bound to the transaction. | Proves control of the wallet by message signing, Satoshi test, screenshot, or self-declaration - the SDK auto-launches this one for you.                                            |

If both could apply to the same transaction, `wallet_ownership` takes precedence, because the missing ownership proof blocks the Travel Rule exchange itself.
`action_required` becomes `null` once the pending action is resolved.
The existing `remediation` field is kept for backward compatibility; `action_required` is the canonical block.

### Auto-launch contract

`autoLaunchAction` (default `true`) auto-launches only the `wallet_ownership` action:

* **Web** - opened in the SDK's own overlay modal, with completion detected by origin-validated messaging plus a bounded transaction poll (never a single-event dependency).
* **iOS / Android** (and the React Native and Flutter wrappers, which delegate to the native SDKs) - presented as the SDK's **native wallet-ownership experience** (SwiftUI / Jetpack Compose) when `useNativeWalletOwnership` is `true` (the default), falling back to `SFSafariViewController` / a Chrome Custom Tab, and finally the default browser. After the flow closes or the app returns to the foreground, the SDK re-reads the transaction automatically.

A `verification_session` action is never auto-launched: it always comes back in `action_required` for your app to start with its own Didit verification integration.

<Warning>
  The wallet-ownership widget must never be rendered inside an embedded mobile webview - wallet deep links cannot escape it and the proof flow dead-ends.
  The SDKs already use the correct browser surface when auto-launching; keep that rule if you handle the `url` yourself.
  See the [wallet-ownership widget guide](/transaction-monitoring/wallet-ownership-widget#open-the-returned-url) for details.
</Warning>

After the SDK's own auto-launched wallet-ownership flow completes or is closed, it re-reads the transaction and hands the refreshed result to your `onActionCompleted` callback.
A `verification_session` action is not part of that cycle, since your app launches it - see the next section.

### Launching a verification session

When `action_required.type` is `verification_session`, read the block from `result.actionRequired` and hand it to your existing Didit verification integration:

<CodeGroup>
  ```typescript Web theme={null}
  if (result.actionRequired?.type === "verification_session") {
    DiditSdk.shared.startVerification({ url: result.actionRequired.url });
  }
  ```

  ```swift iOS theme={null}
  if actionRequired.type == "verification_session" {
      try await DiditSdk.shared.startVerification(token: actionRequired.sessionToken)
  }
  ```

  ```kotlin Android theme={null}
  if (actionRequired.type == "verification_session") {
      DiditSdk.startVerification(token = actionRequired.sessionToken) { result ->
          // handle the verification result
      }
  }
  ```

  ```typescript React Native theme={null}
  if (actionRequired.type === "verification_session") {
    await startVerification(actionRequired.sessionToken);
  }
  ```

  ```dart Flutter theme={null}
  if (actionRequired.type == 'verification_session') {
    await DiditSdk.startVerification(actionRequired.sessionToken);
  }
  ```
</CodeGroup>

Once your verification flow finishes, call `GET /v1/transactions/{transaction_id}/` (or wait for the [transaction webhook](#webhooks)) to pick up the transaction's refreshed status.

### Example: step-up biometrics for a high-value withdrawal

This is the flow at its best: gate risky transactions - large amounts, new beneficiaries, new devices - behind a biometric re-check of the same person you verified at onboarding.

Account takeover looks exactly like this: correct password, correct 2FA code (phished or SIM-swapped), a withdrawal to a wallet you have never seen.
Every credential-based defense has already failed by that point.
A face has not: the attacker cannot pass a liveness-checked selfie that must match the face captured during the legitimate owner's KYC onboarding.

<Steps>
  <Step title="Create the rule once, in the console">
    **Transactions → Rules → Create Rule**: condition `amount gte 5000`, action **Change status → `AWAITING_USER`**, and select your **Biometric Authentication** workflow on the action.
    Add any other risk conditions you like - first-time counterparty, new device fingerprint, IP country change - as extra conditions or extra rules.
  </Step>

  <Step title="Submit the withdrawal as usual">
    Nothing changes in your submission code. When the rule fires, the response comes back with `status: "AWAITING_USER"` and an `action_required` block of type `verification_session`:

    ```json theme={null}
    {
      "status": "AWAITING_USER",
      "action_required": {
        "type": "verification_session",
        "url": "https://verify.didit.me/session/...",
        "session_id": "11111111-2222-3333-4444-555555555555",
        "session_token": "SESSION_TOKEN",
        "status": "Not Started"
      }
    }
    ```
  </Step>

  <Step title="Launch the re-check">
    Hand the `session_token` (or `url`) to your existing Didit verification integration, exactly as in [Launching a verification session](#launching-a-verification-session).
    Because the session is created for the same `vendor_data` as the transaction's subject, Didit already holds the user's verified reference face from onboarding - the approved liveness selfie, the passport chip photo, or the document portrait.
    The user takes one live selfie; Didit runs liveness plus a 1:1 face match against that stored reference. No document rescan, no re-onboarding - a few seconds of friction, only on the transactions that deserve it.
  </Step>

  <Step title="Settle on the outcome">
    When the session completes, the transaction re-evaluates automatically: `APPROVED` if the re-check passed, `DECLINED` if it failed, with a `transaction.status.updated` webhook either way (`reason: remediation_completed` in the transaction's timeline).
    Your app picks up the result via `onActionCompleted`-style callbacks, `GET /v1/transactions/{transaction_id}/`, or the webhook.
  </Step>
</Steps>

This works because the KYC onboarding, the biometric re-check, and the transaction decision run on one platform: the face captured at onboarding is the reference for the step-up, the device graph links the session to the transaction, and the rule engine ties them together - no vendor glue, no face-image export, no separate biometrics contract.
The re-check bills as a standard Biometric Authentication feature ([\$0.10](/getting-started/pricing)) only when it actually runs.

## Web SDK

`submitTransaction` is available on the Web SDK singleton today:

```typescript theme={null}
import { DiditSdk } from "@didit-protocol/sdk-web";

const result = await DiditSdk.shared.submitTransaction({
  transactionToken: sdkToken, // minted by your backend via POST /v3/transactions/sdk-token/
  transaction: {
    txnId: "wd-2026-07-07-0042",
    txnDate: new Date().toISOString(),
    zoneId: "Europe/Madrid",
    category: "travelRule",
    details: {
      direction: "out",
      amount: "0.25",
      currency: "ETH",
      currencyType: "crypto",
      paymentDetails: "ETH withdrawal to self-hosted wallet",
      cryptoParams: { crypto_chain: "ETH" }
    },
    subject: {
      type: "individual",
      fullName: "Jane Doe"
      // no externalUserId needed: the subject identity comes from the token
    },
    counterparty: {
      type: "individual",
      fullName: "Ana Diaz",
      paymentMethod: {
        type: "unhosted_wallet",
        accountId: "0xBeneficiaryWallet01"
      }
    },
    travelRule: {
      status: "AWAITING_COUNTERPARTY", // ignored when Travel Rule is enabled: Didit drives the exchange
      beneficiaryData: {
        wallet_address: "0xBeneficiaryWallet01",
        name: "Ana Diaz"
      }
    },
    includeCryptoScreening: true
  },
  autoLaunchAction: true, // default: auto-launches wallet_ownership only; verification_session comes back in result.actionRequired for you to launch
  onActionCompleted: (refreshed) => {
    console.log(refreshed.status, refreshed.travelRuleStatus);
  }
});

console.log(result.transactionId, result.status, result.actionRequired?.type);
```

The result is `{ transactionId, status, travelRuleStatus?, actionRequired? }`.
In the SDK-level payload you write `category`, `details`, and `customProperties`; the SDK maps them onto the wire aliases (`type`, `info`, `props`) for you.

Errors are typed via `DiditTransactionError`:

```typescript theme={null}
import { DiditSdk, DiditTransactionError } from "@didit-protocol/sdk-web";

try {
  await DiditSdk.shared.submitTransaction({ transactionToken, transaction });
} catch (error) {
  if (error instanceof DiditTransactionError) {
    switch (error.type) {
      case "expired_token": // mint a fresh token and retry
        break;
      case "invalid_token": // rejected: unknown, revoked, or over max_uses
        break;
      case "validation": // inspect error.fieldErrors for per-field details
        break;
      case "network": // retry with backoff
        break;
    }
  }
}
```

## Native SDKs

<Note>
  The native `submitTransaction` API ships with iOS and Android SDK 4.1.0 (and the React Native and Flutter releases that pin it).
  Unlike the Web SDK, the native payloads use the wire field names directly: `type`, `info`, and `props`.
</Note>

<CodeGroup>
  ```swift Swift theme={null}
  import DiditSDK

  let payload = DiditTransactionPayload(
      txnId: "wd-2026-07-07-0042",
      type: "travelRule",
      info: DiditTransactionInfo(
          direction: "out",
          amount: 0.25,
          currency: "ETH",
          currencyType: "crypto",
          cryptoParams: ["crypto_chain": "ETH"]
      ),
      subject: DiditTransactionParticipant(type: "individual", fullName: "Jane Doe"),
      counterparty: DiditTransactionParticipant(
          type: "individual",
          fullName: "Ana Diaz",
          paymentMethod: DiditTransactionPaymentMethod(type: "unhosted_wallet", accountId: "0xBeneficiaryWallet01")
      ),
      travelRule: DiditTravelRuleInfo(
          beneficiaryData: ["wallet_address": "0xBeneficiaryWallet01", "name": "Ana Diaz"]
      ),
      includeCryptoScreening: true
  )

  let result = try await DiditSdk.shared.submitTransaction(
      transactionToken: sdkToken,
      transaction: payload,
      options: DiditTransactionOptions(
          autoLaunchAction: true,           // default
          useNativeWalletOwnership: true,   // default: native flow, browser fallback
          onTransactionUpdated: { refreshed in
              print(refreshed.status ?? "", refreshed.travelRuleStatus ?? "")
          }
      )
  )

  print(result.transactionId, result.status ?? "", result.actionRequired?.type ?? "none")
  // Errors: DiditTransactionError .invalidToken / .expiredToken / .validation(fieldErrors) / .network
  ```

  ```kotlin Kotlin theme={null}
  import me.didit.sdk.DiditSdk
  import me.didit.sdk.transactions.*

  val payload = DiditTransactionPayload(
      txnId = "wd-2026-07-07-0042",
      type = "travelRule",
      info = DiditTransactionInfo(
          direction = "out",
          amount = 0.25,
          currency = "ETH",
          currencyType = "crypto",
          cryptoParams = mapOf("crypto_chain" to "ETH")
      ),
      subject = DiditTransactionParticipant(type = "individual", fullName = "Jane Doe"),
      counterparty = DiditTransactionParticipant(
          type = "individual",
          fullName = "Ana Diaz",
          paymentMethod = DiditTransactionPaymentMethod(
              type = "unhosted_wallet",
              accountId = "0xBeneficiaryWallet01"
          )
      ),
      travelRule = DiditTravelRule(
          beneficiaryData = mapOf("wallet_address" to "0xBeneficiaryWallet01", "name" to "Ana Diaz")
      ),
      includeCryptoScreening = true
  )

  // suspend fun - call from a coroutine; DiditSdk.initialize() must have run first
  val result = DiditSdk.submitTransaction(
      transactionToken = sdkToken,
      transaction = payload,
      options = DiditTransactionOptions(
          autoLaunchAction = true,          // default
          useNativeWalletOwnership = true,  // default: native flow, Custom Tab fallback
          onTransactionUpdated = { refreshed ->
              Log.d("Didit", "${refreshed.status} ${refreshed.travelRuleStatus}")
          }
      )
  )

  Log.d("Didit", "${result.transactionId} ${result.status} ${result.actionRequired?.type}")
  // Errors: sealed DiditTransactionException - InvalidToken / ExpiredToken / Validation(fieldErrors) / Network
  ```

  ```typescript React Native theme={null}
  import {
    submitTransaction,
    getTransaction,
    DiditTransactionError,
  } from "@didit-protocol/sdk-react-native";

  const result = await submitTransaction(sdkToken, {
    txnId: "wd-2026-07-07-0042",
    type: "travelRule",
    info: {
      direction: "out",
      amount: 0.25,
      currency: "ETH",
      currencyType: "crypto",
      cryptoParams: { crypto_chain: "ETH" },
    },
    subject: { type: "individual", fullName: "Jane Doe" },
    counterparty: {
      type: "individual",
      fullName: "Ana Diaz",
      paymentMethod: { type: "unhosted_wallet", accountId: "0xBeneficiaryWallet01" },
    },
    travelRule: {
      beneficiaryData: { wallet_address: "0xBeneficiaryWallet01", name: "Ana Diaz" },
    },
    includeCryptoScreening: true,
  }, {
    autoLaunchAction: true, // default
    onTransactionUpdated: (refreshed) => {
      console.log(refreshed.status, refreshed.travelRuleStatus);
    },
  });

  console.log(result.transactionId, result.status, result.actionRequired?.type);
  // Errors: DiditTransactionError with code invalid_token | expired_token | validation | network
  ```

  ```dart Flutter theme={null}
  import 'package:sdk_flutter/sdk_flutter.dart';

  final result = await DiditSdk.submitTransaction(
    sdkToken,
    DiditTransactionPayload(
      txnId: 'wd-2026-07-07-0042',
      type: 'travelRule',
      info: DiditTransactionInfo(
        direction: 'out',
        amount: 0.25,
        currency: 'ETH',
        currencyType: 'crypto',
        cryptoParams: {'crypto_chain': 'ETH'},
      ),
      subject: DiditTransactionParticipant(type: 'individual', fullName: 'Jane Doe'),
      counterparty: DiditTransactionParticipant(
        type: 'individual',
        fullName: 'Ana Diaz',
        paymentMethod: DiditTransactionPaymentMethod(
          type: 'unhosted_wallet',
          accountId: '0xBeneficiaryWallet01',
        ),
      ),
      travelRule: DiditTravelRule(
        beneficiaryData: {'wallet_address': '0xBeneficiaryWallet01', 'name': 'Ana Diaz'},
      ),
      includeCryptoScreening: true,
    ),
    options: DiditTransactionOptions(
      autoLaunchAction: true, // default
      onTransactionUpdated: (refreshed) {
        debugPrint('${refreshed.status} ${refreshed.travelRuleStatus}');
      },
    ),
  );

  debugPrint('${result.transactionId} ${result.status} ${result.actionRequired?.type}');
  // Errors: DiditTransactionException with code invalid_token | expired_token | validation | network
  ```
</CodeGroup>

Every SDK also exposes `getTransaction(transactionToken, transactionId)` to re-read the transaction with the same token - the SDKs call it for you after a launched action flow, and you can call it yourself at any point.

On mobile the device fingerprint transport is already applied to all SDK network calls, so transaction submissions carry the same device intelligence automatically.

## Without the SDKs

Everything the SDKs do is plain HTTPS - nothing here requires them.
Two equivalent integration shapes:

**Server-side only (no tokens at all).** Submit with [`POST /v3/transactions/`](/management-api/transactions/create) from your backend using your API key. The response (and every subsequent `GET /v3/transactions/{transaction_id}/`) carries the same `action_required` block. You can also pass explicit `device` context per participant, since there is no SDK to collect it for you.

**Client-side with your own HTTP stack.** Mint a token with [`POST /v3/transactions/sdk-token/`](/management-api/transactions/sdk-token), then call [`POST /v1/transactions/`](/management-api/transactions/submit-sdk) and [`GET /v1/transactions/{transaction_id}/`](/management-api/transactions/get-sdk) from the device with the `X-Transaction-Token` header - the same subject binding and server-side IP/user-agent derivation apply.

Then handle `action_required` yourself:

| `action_required.type` | What to do                                                                                                                                                                                                                                                                        |
| ---------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wallet_ownership`     | Deliver `url` to the user and open it in a **real browser surface** - a normal tab on web, `SFSafariViewController` / Chrome Custom Tabs on mobile, or out-of-band via an email link or QR code. Never render it inside an embedded webview: wallet deep links cannot escape one. |
| `verification_session` | Send the user to `url` - it is the standard hosted Didit verification page - or feed `session_token` to any Didit verification integration you already run.                                                                                                                       |

And detect completion without any client callback:

* **Webhooks (recommended).** `transaction.status.updated` fires when the pending action resolves the transaction, and `travel_rule.status.updated` fires on every exchange transition - both include enough to update your records with no polling.
* **Polling.** Re-read the transaction (`/v3/` from your backend, or `/v1/` with the token while it is valid): `action_required` returns to `null` once resolved, and `status` / `travel_rule.status` carry the outcome.

There are no one-shot dependencies in this design: the widget, the verification session, and your backend all converge on the same durable transaction state, so a closed tab or a missed webhook is always recoverable by re-reading the transaction.

## Webhooks

Your backend does not need the app to report back.
When a submitted transaction requires user action (it lands in `AWAITING_USER`), the [transaction webhook](/transaction-monitoring/webhooks) - `transaction.created` or `transaction.status.updated` - includes the same `action_required` block, so your systems know about the pending action even if the app is closed before the flow finishes.
Travel Rule transitions additionally emit [`travel_rule.status.updated`](/transaction-monitoring/travel-rule#webhooks).

## Next steps

<CardGroup>
  <Card title="Submitting transactions" icon="arrow-right-to-bracket" href="/transaction-monitoring/transactions">
    The server-side Create Transaction API and the full payload reference.
  </Card>

  <Card title="Travel Rule" icon="route" href="/transaction-monitoring/travel-rule">
    The managed originator-beneficiary exchange, settings, and lifecycle.
  </Card>

  <Card title="Wallet ownership widget" icon="wallet" href="/transaction-monitoring/wallet-ownership-widget">
    The hosted proof-of-control flow behind wallet\_ownership actions.
  </Card>

  <Card title="Webhooks" icon="bell" href="/transaction-monitoring/webhooks">
    transaction.created, transaction.status.updated, and signature verification.
  </Card>

  <Card title="Rules" icon="scale-balanced" href="/transaction-monitoring/rules">
    Rule actions, including the ones that create verification sessions.
  </Card>

  <Card title="Statuses" icon="diagram-project" href="/transaction-monitoring/statuses">
    What AWAITING\_USER means in the transaction lifecycle.
  </Card>
</CardGroup>


# Settings
Source: https://docs.didit.me/transaction-monitoring/settings

Configure KYT defaults for score thresholds, currency, blockchain analytics providers, and remediation. Transaction monitoring costs $0.02 per transaction.

Configure application-level transaction monitoring settings from the Business Console to control scoring thresholds and provider preferences.

## General settings

| Setting                | Default | Description                                                                                                                                     |
| ---------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------- |
| **Monitoring enabled** | `true`  | Enable or disable transaction monitoring for the application. When disabled, submitted transactions are stored but not evaluated against rules. |
| **Default currency**   | `USD`   | Currency used for rule threshold comparisons and currency conversion. All amounts are converted to this currency for consistent evaluation.     |

## Score thresholds

Score thresholds determine how the cumulative risk score from [matched rules](/transaction-monitoring/rules) maps to a transaction status:

| Setting               | Default | Description                                                                                                                                        |
| --------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------------------------------- |
| **Review threshold**  | 60      | Transactions scoring at or above this value receive `IN_REVIEW` status                                                                             |
| **Decline threshold** | 85      | Transactions scoring at or above this value receive `DECLINED` status. Set the slider to the maximum value (`500`) to never auto-decline by score. |

Transactions below the review threshold are automatically `APPROVED`. If a rule has an explicit `change_status` action, that status takes priority over score-based thresholds — `DECLINED` always wins.

<Note>
  Lowering the review threshold increases the volume of flagged transactions for analyst review. Adjust based on your team's capacity and risk appetite.
</Note>

## Crypto monitoring

Enable or disable automatic [crypto screening](/transaction-monitoring/aml-screening) for cryptocurrency transactions. When enabled, Didit screens wallet addresses and transaction hashes against blockchain analytics providers for all transactions with `currency_kind: "crypto"`. Transaction-hash screening requires both the hash and the related wallet address.

## Provider preferences

Select and configure your preferred blockchain analytics provider:

| Provider           | Configuration                                                         |
| ------------------ | --------------------------------------------------------------------- |
| **Merkle Science** | Enable with managed pricing (the default) or connect your own API key |
| **Crystal**        | Connect your own API key from the console **Marketplace**             |
| **Chainalysis**    | Connect your own API key from the console **Marketplace**             |
| **Elliptic**       | Connect your own API key and secret from the console **Marketplace**  |
| **TRM Labs**       | Connect your own API key from the console **Marketplace**             |

When you connect your own provider key, you use your existing provider agreement and pay the listed infrastructure fee per screening through Didit.

## Remediation workflow

The **remediation workflow** (`remediation_workflow_id` on the settings API) is your application-wide default for [`AWAITING_USER` rule actions](/transaction-monitoring/rules#requiring-user-verification-awaiting-user) that don't name their own workflow - in practice, the built-in library rules (custom rules always carry their own selection, which wins).
The field accepts a workflow id (or a specific version uuid) on write and always returns the stable workflow id on read; sessions are created with the latest published version.
When such a rule sets a transaction to `AWAITING_USER`, Didit creates the linked verification session with the first workflow found in this order:

1. The remediation workflow configured here.
2. Your application's **Biometric Authentication** workflow, when the subject already has a stored reference face.
3. Your application's default workflow.

The session's URL and token are returned in the transaction's `action_required` and `remediation` fields and in both transaction webhooks, so you can redirect the user to complete the required verification.
Once that session reaches a decision, the transaction status follows it automatically (approved, declined, or in review) and a `transaction.status.updated` webhook fires.

A **Biometric Authentication** workflow is the recommended choice here: the user re-proves their identity with one live selfie matched against the face from their original onboarding.
It requires the subject to have a stored reference face from an approved verification; users without one are asked to complete your application's default workflow instead, with a note on the transaction recording the substitution.

## Where to find

Navigate to **Transactions** > **Settings** in the [Business Console](https://business.didit.me) to configure these options. Settings take effect immediately for all new transactions.

## Next steps

<CardGroup>
  <Card title="Risk scoring" icon="gauge" href="/transaction-monitoring/risk-scoring">
    How score thresholds map to statuses.
  </Card>

  <Card title="Crypto screening" icon="link" href="/transaction-monitoring/aml-screening">
    Wallet screening and provider details.
  </Card>

  <Card title="IP enrichment" icon="globe-pointer" href="/transaction-monitoring/ip-enrichment">
    What IP data is available to rules.
  </Card>
</CardGroup>


# Transaction Monitoring Statuses
Source: https://docs.didit.me/transaction-monitoring/statuses

Reference for every transaction, alert, case, and travel-rule status, with transitions and meanings. Pay-per-call $0.02 per transaction, no contracts.

Transaction Monitoring has four separate status machines: the **transaction**, each **alert**, each **case**, and (where applicable) the **travel-rule check**. This page is the reference.

## Transaction status

Set on creation and updated through the lifecycle.

| Status          | Meaning                                                                                                                                                                                                                                                                           |
| --------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `APPROVED`      | Transaction passed all rules below the review threshold.                                                                                                                                                                                                                          |
| `IN_REVIEW`     | Score crossed the review threshold, or a rule explicitly required review. Analyst attention needed.                                                                                                                                                                               |
| `DECLINED`      | Score crossed the decline threshold, or a rule explicitly declined. Transaction rejected.                                                                                                                                                                                         |
| `AWAITING_USER` | The user must act before the transaction can settle: a rule action required additional verification (a remediation session was created), or a Travel Rule transfer needs proof of wallet control. Read the transaction's `action_required` block for the concrete action and URL. |

### Transitions

```mermaid theme={null}
stateDiagram-v2
    [*] --> APPROVED: Score < review threshold, no blocking rules
    [*] --> IN_REVIEW: Score >= review threshold
    [*] --> DECLINED: Score >= decline threshold, or rule decline action
    [*] --> AWAITING_USER: Rule action change_status → AWAITING_USER
    IN_REVIEW --> APPROVED: Analyst cleared
    IN_REVIEW --> DECLINED: Analyst declined
    AWAITING_USER --> APPROVED: Remediation session approved
    AWAITING_USER --> DECLINED: Remediation session declined
    AWAITING_USER --> IN_REVIEW: Remediation session ended in review
```

Note: there is no direct transition from `APPROVED` or `DECLINED` back to other states. Use status patches via the console for corrections; those are logged to the audit trail.

## Alert status

See [Alerts](/transaction-monitoring/alerts) for full detail.

| Status          | Meaning                                |
| --------------- | -------------------------------------- |
| `OPEN`          | Just generated; unassigned.            |
| `INVESTIGATING` | Analyst is actively working it.        |
| `AWAITING_USER` | Pending user action (remediation).     |
| `PENDING_SAR`   | SAR filing in progress.                |
| `SAR_FILED`     | SAR filed with regulator; case closed. |
| `RESOLVED`      | Closed with an action taken.           |
| `DISMISSED`     | Closed as false positive.              |

## Case status

See [Case Management](/console/case-management/cases) for full detail.

| Status          | Meaning                                                       |
| --------------- | ------------------------------------------------------------- |
| `OPEN`          | Under active investigation.                                   |
| `AWAITING_USER` | Waiting on user-side input.                                   |
| `RESOLVED`      | Closed with a resolution: `FALSE_POSITIVE` or `VALID_THREAT`. |

Cases carry a separate **priority** (`LOW`, `MEDIUM`, `HIGH`).

## Travel-rule check status

Virtual-asset transfers under the FATF Travel Rule run a dedicated **13-state exchange**, separate from the transaction status above. It starts at `AWAITING_COUNTERPARTY` (or `UNCONFIRMED_OWNERSHIP` on the beneficiary side) and finishes in `FINISHED`, `CANCELLED`, or `EXPIRED`.

| Status                              | Meaning                                                                   |
| ----------------------------------- | ------------------------------------------------------------------------- |
| `AWAITING_COUNTERPARTY`             | Sent to the counterparty; awaiting their response.                        |
| `UNCONFIRMED_OWNERSHIP`             | Beneficiary wallet ownership not yet proven.                              |
| `ON_HOLD`                           | Held for manual action (transaction shows `AWAITING_USER`).               |
| `COMPLETED`                         | Originator and beneficiary data matched - safe to broadcast on-chain.     |
| `FINISHED`                          | On-chain hash reported; exchange closed.                                  |
| `CANCELLED`                         | Cancelled from a non-terminal state.                                      |
| `EXPIRED`                           | Confirmation timeout elapsed.                                             |
| `COUNTERPARTY_MISMATCHED_DATA`      | Beneficiary name did not match.                                           |
| `COUNTERPARTY_VASP_NOT_FOUND`       | No rail could resolve the counterparty.                                   |
| `COUNTERPARTY_VASP_NOT_REACHABLE`   | Counterparty identified but its `TRP` endpoint was unreachable.           |
| `COUNTERPARTY_VASP_GENERAL_DECLINE` | Counterparty declined the exchange.                                       |
| `NOT_ENOUGH_COUNTERPARTY_DATA`      | Counterparty response was incomplete (repairable).                        |
| `NOT_APPLICABLE`                    | Disabled, below `threshold_amount`, or a passively recorded legacy value. |

Older integrations may still send the legacy values `UNKNOWN`, `COMPLIANT`, `PENDING_ACTION`, `PENDING_COUNTERPARTY`, `FAILED`, and `EXEMPT`; Didit maps them onto the states above automatically.

See [Travel Rule](/transaction-monitoring/travel-rule#lifecycle) for the authoritative reference.

## Provider result status

Every external provider result (wallet screening, fiat monitoring, sanctions screening) is stored with its own status. Surfaced under `provider_results[]` in the transaction response.

| Status      | Meaning                                                           |
| ----------- | ----------------------------------------------------------------- |
| `PENDING`   | Provider query in flight.                                         |
| `COMPLETED` | Result returned successfully.                                     |
| `FAILED`    | Provider errored or timed out.                                    |
| `SKIPPED`   | Provider deliberately skipped (e.g. transaction below threshold). |

## Rule-run outcomes

Every `TransactionRuleRun` has:

* `matched` (boolean) — did the rule fire?
* `is_test` (boolean) — was the rule in TEST mode?
* `mode` — `ACTIVE`, `DISABLED`, `TEST` at evaluation time.
* `score_delta` — contribution to the score (if matched and active).
* `status_target` — the status the rule asked for (if `change_status` action).

See [Rules](/transaction-monitoring/rules) for the rule anatomy.

## Decision reason codes

Common `reason` values on status transitions:

| Reason                                                                    | Meaning                                                                                      |
| ------------------------------------------------------------------------- | -------------------------------------------------------------------------------------------- |
| `rule_score_threshold`                                                    | Score crossed review/decline threshold.                                                      |
| `rule_change_status`                                                      | A rule's `change_status` action forced a status.                                             |
| `analyst_approved` / `analyst_declined` / `analyst_cleared`               | Manual analyst action.                                                                       |
| `user_action_approved` / `user_action_declined` / `user_action_in_review` | Outcome of the linked remediation session (the user action requested while `AWAITING_USER`). |
| `provider_update`                                                         | External provider updated the result.                                                        |
| `aml_confirmed_sanction`                                                  | AML screen confirmed a sanctions match.                                                      |
| `blocklist_applicant` / `blocklist_counterparty`                          | Blocklist enforcement on a party.                                                            |

## Next steps

<CardGroup>
  <Card title="Risk scoring" icon="gauge" href="/transaction-monitoring/risk-scoring">
    How scores map to statuses.
  </Card>

  <Card title="Alerts" icon="bell" href="/transaction-monitoring/alerts">
    Alert lifecycle.
  </Card>

  <Card title="Cases" icon="folder-open" href="/transaction-monitoring/cases">
    Case lifecycle.
  </Card>
</CardGroup>


# Submitting Transactions
Source: https://docs.didit.me/transaction-monitoring/transactions

Submit transactions for real-time monitoring with parties, payment methods, device context, and custom properties. Pay-per-call $0.02 per transaction.

Submit transactions to Didit via the [Create Transaction](/management-api/transactions/create) API. Each transaction includes structured party, payment, and context data that the rules engine evaluates in real time.

<Tip>
  When the transaction originates on an end-user's device - a crypto withdrawal, an in-app payment - consider [SDK transaction submission](/transaction-monitoring/sdk-transaction-submission): a scoped token replaces the API key, device intelligence is collected automatically, and required user actions (wallet-ownership proof, step-up verification) launch on the spot.
</Tip>

## Transaction categories

Every transaction has a `transaction_category` that determines how rules and analytics treat it:

| Category                | Description                                                    |
| ----------------------- | -------------------------------------------------------------- |
| `finance`               | Standard financial transaction (deposit, withdrawal, transfer) |
| `kyc`                   | Identity verification-related event                            |
| `travel_rule`           | Virtual asset transfer requiring travel rule compliance        |
| `user_event`            | Custom platform event (login, profile change, etc.)            |
| `gambling_bet`          | Gambling wager or bet placement                                |
| `gambling_limit_change` | Change to a player's deposit, loss, or wager limit             |
| `gambling_bonus_change` | Bonus grant, redemption, or forfeiture                         |
| `audit_trail_event`     | System or compliance audit event                               |

## Transaction details

The `transaction_details` object carries the financial data:

| Field                  | Type   | Description                                                                                                     |
| ---------------------- | ------ | --------------------------------------------------------------------------------------------------------------- |
| `direction`            | string | `inbound` or `outbound`                                                                                         |
| `amount`               | string | Transaction value as a decimal string (e.g., `"1500.50"`)                                                       |
| `currency`             | string | ISO currency code (e.g., `USD`, `EUR`, `BTC`)                                                                   |
| `currency_kind`        | string | `fiat` or `crypto` — determines whether crypto screening triggers                                               |
| `action_type`          | string | Vendor-defined action label (e.g., `deposit`, `withdrawal`, `purchase`)                                         |
| `payment_details`      | string | Free-text description of the payment (e.g., `"Bank transfer from ABC Corp"`)                                    |
| `payment_reference_id` | string | External payment reference identifier. For post-transfer crypto screening, use the blockchain transaction hash. |

## Subject and counterparty

Each transaction has a **subject** (required) and an optional **counterparty**. Both use the same party model:

| Field           | Type             | Description                                                                                                                                                                                            |
| --------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `entity_type`   | string           | `person` or `company`                                                                                                                                                                                  |
| `vendor_data`   | string           | Your identifier for this party — links the transaction to a [user](/management-api/users/list) or [business profile](/business-verification/business-profiles)                                         |
| `full_name`     | string           | Full name of the party                                                                                                                                                                                 |
| `first_name`    | string           | Given name                                                                                                                                                                                             |
| `last_name`     | string           | Family name                                                                                                                                                                                            |
| `date_of_birth` | string           | ISO date (e.g., `1990-01-15`)                                                                                                                                                                          |
| `country_code`  | string           | ISO 3166-1 alpha-2 country code                                                                                                                                                                        |
| `address`       | object or string | Structured address with `street`, `city`, `state`, `country`, `postal_code`. Also accepts a plain string, such as a wallet address for a crypto counterparty — Didit stores it unchanged on the party. |

Didit derives the party's `country_code` from `address.country` when `address` is an object. When `address` is a string, `country_code` comes back `null` on that party.

When `vendor_data` matches an existing user or business, Didit automatically links the transaction to that entity's profile, enabling cross-session rule evaluation and velocity checks.
In the response, both parties come back in the `parties` array with roles `APPLICANT` and `COUNTERPARTY`.

## Payment methods

Attach a `payment_method` to each party to describe the instrument on that side:

| Field             | Type   | Description                                                                            |
| ----------------- | ------ | -------------------------------------------------------------------------------------- |
| `method_type`     | string | `bank_card`, `bank_account`, `ewallet`, `crypto_wallet`, `unhosted_wallet`, or `other` |
| `account_id`      | string | Account number, wallet address, or card token                                          |
| `issuing_country` | string | Country that issued the payment instrument                                             |

On `travelRule` transactions, a counterparty payment method with `payment_method_type: "unhosted_wallet"` declares the destination as a self-hosted wallet and routes the transfer straight to the ownership-proof flow - see [Declared self-hosted wallets](/transaction-monitoring/travel-rule#declared-self-hosted-wallets).

For crypto transactions, include wallet addresses in `account_id` and set `currency_kind` to `crypto` so blockchain screening can run automatically. Direction controls which wallet is screened: inbound pre-transfer screening uses the sender wallet in `counterparty.payment_method.account_id`; outbound screening uses the destination wallet in `counterparty.payment_method.account_id`. If you send a blockchain hash in `transaction_details.payment_reference_id`, inbound transaction screening requires your service deposit address in `subject.payment_method.account_id`, while outbound transaction screening requires the destination wallet in `counterparty.payment_method.account_id`.

## Crypto screening override

Use `include_crypto_screening` at the top level of the request to override the default configured in **Transactions** > **Settings** in the Console:

| Value             | Description                                 |
| ----------------- | ------------------------------------------- |
| `true`            | Force crypto screening for this transaction |
| `false`           | Skip crypto screening for this transaction  |
| omitted or `null` | Use the application-level default           |

## Device context

Include device information on the subject (and optionally the counterparty) party to power device intelligence rules. The request field is `device_context` on each party; the camelCase alias `device` is also accepted and is what the SDK wire format uses. The response returns it as `device` on each party in the `parties` array.

| Field                                            | Type   | Description                                                                                                                                                                          |
| ------------------------------------------------ | ------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `device_context.fingerprint`                     | string | Unique device fingerprint                                                                                                                                                            |
| `device_context.persistent_device_id`            | string | Stable cross-session device identifier (v2 fingerprint schema)                                                                                                                       |
| `device_context.user_agent`                      | string | Browser or app user agent string                                                                                                                                                     |
| `device_context.browser_family`                  | string | Browser family (e.g. `Chrome`, `Firefox`, `Safari`). **Must be sent explicitly** — it is not derived from `user_agent`. Powers rules like `subject_browser_family`.                  |
| `device_context.browser_version`                 | string | Browser version string (e.g. `131.0`). Must be sent explicitly.                                                                                                                      |
| `device_context.platform`                        | string | Platform identifier (`web`, `ios`, `android`, `macos`, `windows`, `linux`). **Must be sent explicitly** — it is not derived from `user_agent`. Powers rules like `subject_platform`. |
| `device_context.os_family`                       | string | Operating system family (e.g. `iOS`, `Android`, `Windows`)                                                                                                                           |
| `device_context.os_version`                      | string | Operating system version string                                                                                                                                                      |
| `device_context.accept_language`                 | string | Accept-Language header value (e.g. `en-US,en;q=0.9`). On the SDK path this is collected automatically.                                                                               |
| `device_context.session_id`                      | string | Session identifier of the user's current session. Stored in metadata. CamelCase alias: `sessionId`.                                                                                  |
| `device_context.session_age_ms`                  | number | Age of the user's session in milliseconds at transaction time. Powers rules like `subject_session_age_ms`.                                                                           |
| `device_context.network_context.ip_address`      | string | Client IP address                                                                                                                                                                    |
| `device_context.network_context.ip_country_code` | string | Geo-resolved country of the IP (ISO 3166-1 alpha-3)                                                                                                                                  |
| `device_context.network_context.latitude`        | number | Geographic latitude of the IP                                                                                                                                                        |
| `device_context.network_context.longitude`       | number | Geographic longitude of the IP                                                                                                                                                       |

<Note>
  `browser_family` and `platform` are **not** derived from `user_agent`. They must be sent as explicit top-level keys inside `device_context` for device intelligence rules to fire. If you rely on the Didit SDK, these fields are collected automatically.
</Note>

CamelCase aliases are accepted for every field: `userAgent`, `browserFamily`, `browserVersion`, `osFamily`, `osVersion`, `acceptLang`, `sessionId`, `sessionAgeMs`. The `network_context` sub-object accepts `ip` / `countryCode3` / `lat` / `lon` aliases, and a top-level `ipInfo` block is also folded into `network_context`.

Device context enables rules like multi-accounting detection (same fingerprint across different subjects), new-browser-and-new-IP combination detection, low session age high-value transfer, and location-based risk scoring.

## Custom properties

Add any additional key-value pairs in the `custom_properties` object. Rules can reference these fields in their conditions — useful for passing business-specific context like product category, merchant ID, or channel.

```json theme={null}
"custom_properties": {
  "product_category": "electronics",
  "merchant_id": "MER456",
  "channel": "mobile_app"
}
```

In rule conditions, reference each key with the field path `custom_values.<key>` — for example, the payload above matches `custom_values.product_category eq "electronics"`. In the Console rule builder, keys seen on recently ingested transactions appear in the condition field selector under **Custom Properties**, and **Enter custom property** in the same group lets you type any key manually (case-sensitive). See [Rules & scoring](/transaction-monitoring/rules#referencing-custom-properties) for details.

## Example request

```bash theme={null}
curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "TXN-20260410-001",
    "transaction_at": "2026-04-10T15:30:00Z",
    "transaction_category": "finance",
    "transaction_details": {
      "direction": "outbound",
      "amount": "1500.50",
      "currency": "EUR",
      "currency_kind": "fiat",
      "action_type": "withdrawal"
    },
    "subject": {
      "entity_type": "person",
      "vendor_data": "user-123",
      "full_name": "John Doe",
      "country_code": "US",
      "payment_method": {
        "method_type": "bank_account",
        "account_id": "DE89370400440532013000",
        "issuing_country": "DE"
      }
    },
    "counterparty": {
      "entity_type": "company",
      "full_name": "John Doe",
      "country_code": "GB"
    },
    "custom_properties": {
      "order_id": "ORD-7891"
    }
  }'
```

## Response

The API returns the created transaction with its initial evaluation results:

| Field                   | Type   | Description                                                             |
| ----------------------- | ------ | ----------------------------------------------------------------------- |
| `uuid`                  | string | Didit's unique transaction identifier                                   |
| `txn_id`                | string | Your provided transaction ID                                            |
| `status`                | string | `APPROVED`, `IN_REVIEW`, `DECLINED`, or `AWAITING_USER`                 |
| `score`                 | number | Cumulative risk score from all matched rules                            |
| `severity`              | string | Highest severity of matched rules (`LOW`, `MEDIUM`, `HIGH`, `CRITICAL`) |
| `decision_reason_code`  | string | Machine-readable reason for the status decision                         |
| `decision_reason_label` | string | Human-readable description of the decision                              |

See the [API Reference](/management-api/transactions/create) for the full request and response schema, and the dedicated [response schema reference](/transaction-monitoring/response-schema) for an annotated payload walkthrough.

## Idempotency

`txn_id` is unique per application. Re-submitting the same `txn_id` returns the existing transaction rather than creating a duplicate — effectively idempotent for retries. Always generate `txn_id` on your side (e.g. your own transaction DB ID, UUID, or deterministic hash).

## Historical backfill

Pass `txn_date` in the past to ingest historical transactions. Rules still evaluate by default — use the console CSV import with dry-ingest mode if you want to skip rule evaluation during bulk historical loads. See [integration guide](/transaction-monitoring/integration-guide#historical-ingestion).

## Next steps

<CardGroup>
  <Card title="Rules & scoring" icon="scale-balanced" href="/transaction-monitoring/rules">
    How submitted transactions are evaluated against rules.
  </Card>

  <Card title="Response schema" icon="file-lines" href="/transaction-monitoring/response-schema">
    Full annotated response payload.
  </Card>

  <Card title="Crypto screening" icon="link" href="/transaction-monitoring/aml-screening">
    Automatic wallet and transaction screening for crypto transactions.
  </Card>

  <Card title="Travel rule" icon="globe" href="/transaction-monitoring/travel-rule">
    Attach travel rule compliance data to virtual asset transfers.
  </Card>

  <Card title="IP enrichment" icon="globe-pointer" href="/transaction-monitoring/ip-enrichment">
    IP-derived context available to rules.
  </Card>

  <Card title="API reference" icon="code" href="/management-api/transactions/create">
    Full request schema for the Create Transaction endpoint.
  </Card>
</CardGroup>


# Travel Rule
Source: https://docs.didit.me/transaction-monitoring/travel-rule

FATF-compliant travel rule messaging for crypto VASPs and PSPs: originator/beneficiary data exchange, protocol tracking, auto-remediation. Pay-per-call $0.02.

Didit runs the full FATF/EU Transfer of Funds Regulation (TFR) originator-beneficiary exchange for virtual asset transfers: it resolves the counterparty VASP, negotiates and verifies the required data, tracks the exchange through a 13-state lifecycle, and only then lets you release funds on-chain.

## Overview

The FATF Travel Rule (Recommendation 16), implemented in the EU as the Transfer of Funds Regulation, requires a sending Virtual Asset Service Provider (the **originator VASP**) to collect and transmit originator and beneficiary information to the receiving VASP (the **beneficiary VASP**) before a virtual asset transfer settles.

Unlike most jurisdictions, the EU TFR applies with **no minimum amount** - every crypto transfer is in scope, not just transfers above a reporting threshold.

Didit's Travel Rule product is a managed exchange, not just a data field:

* You submit a transfer with `transaction_category: "travelRule"`.
* Didit resolves a rail to reach the counterparty VASP, exchanges originator and beneficiary data, and verifies the beneficiary's identity against the destination wallet.
* Only once the exchange reaches `COMPLETED` should you broadcast the transfer on-chain.
* You then report the on-chain transaction hash back to Didit to close the exchange out as `FINISHED`.

Seven rails ship in this release, tried in strict priority order - the first one that can reach the counterparty wins:

| Priority | Rail         | How it works                                                                                                                                                                                                                                                                                                                                                                              |
| -------- | ------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| 1        | `INTERNAL`   | Used when the beneficiary wallet address is already registered in another Didit customer's [wallet address book](#wallet-address-book). Didit creates a matching inbound transfer on the beneficiary's application and negotiates the exchange entirely within the platform - no outbound network call. Instant.                                                                          |
| 2        | `TRP`        | Native integration with the open Travel Rule Protocol (TRP / OpenVASP). Used when the transfer carries a [travel address](#travel-addresses), the destination wallet's address-book entry stores one, or the counterparty VASP resolves in the [directory](#directory) with a TRP endpoint. Didit exchanges originator and beneficiary data machine-to-machine, with no email round-trip. |
| 3        | `GTR`        | Global Travel Rule (GTR) network. The counterparty is resolved by an explicit `counterparty_gtr_vasp_code` or a directory entry that carries one.                                                                                                                                                                                                                                         |
| 4        | `TRUST`      | TRUST network. The counterparty is resolved by `counterparty_trust_membership_id` or a directory entry that carries one.                                                                                                                                                                                                                                                                  |
| 5        | `VERIFYVASP` | VerifyVASP network. The counterparty is resolved by `counterparty_verifyvasp_id` or a directory entry that carries one.                                                                                                                                                                                                                                                                   |
| 6        | `SYGNA`      | Sygna Bridge network (acquired by VerifyVASP in 2026, still operating for existing members). Native implementation of the Sygna protocol - ECIES-encrypted IVMS101 with signed permission requests. The counterparty is resolved by `counterparty_sygna_vasp_code` or a directory entry that carries one.                                                                                 |
| 7        | `EMAIL`      | Fallback used when the counterparty exposes no supported protocol channel. Didit emails a compliance contact a one-time pickup link so they can confirm or decline the exchange without a Didit account. This is the workhorse for the sunrise problem - counterparties that are not yet reachable on any network.                                                                        |

The network rails (`GTR`, `TRUST`, `VERIFYVASP`, `SYGNA`) run in one of two modes, per network:

* **Didit's platform membership** - when Didit's own membership for a network is active, every Travel Rule application routes over it automatically, with no setup on your side. You can opt out of individual networks with the `disabled_networks` setting (see [Setup](#setup)).
* **Your own membership** - connect your own network membership credentials in the console **Marketplace** (Travel Rule networks category). A connected membership always takes precedence over Didit's platform membership, and your transfers travel under your own network identity.

No network membership is included by default, including GTR. Enabling Travel Rule does not activate GTR, TRUST, VerifyVASP, or Sygna. Check [Get Travel Rule Settings](/management-api/travel-rule/get-settings) for your application's effective `networks` modes. If all four report `unavailable`, none can route an exchange: connect your own membership in **Marketplace**, or use a reachable `INTERNAL`, `TRP`, or `EMAIL` counterparty.

`platform_available` reports whether platform membership is configured, not a live network health check. Similarly, `connected` means your membership credentials are saved and have passed local validation; the first live exchange verifies them against the network. A `didit` or `own` mode does not guarantee counterparty reachability or successful delivery.

Further networks - CODE (the Korean alliance), TRISA, Notabene, and Veriscope - are listed in the console **Marketplace** as on-request integrations: their onboarding runs through each network's own registration or due-diligence process, so request access there and Didit coordinates the connection with you.

When none of the seven rails can resolve a counterparty, Didit runs one more resolution step before giving up: blockchain analytics attribution.
The destination wallet is looked up against blockchain analytics data; when the wallet belongs to a known exchange or custodian, Didit records the attributed VASP on the transfer, adds it to the [directory](#directory), and re-runs the rails once with the new name.
See [Blockchain analytics attribution](#blockchain-analytics-attribution) for the full behavior and pricing.

A transfer whose destination is [declared as a self-hosted wallet](#declared-self-hosted-wallets) skips all seven rails - there is no counterparty VASP to exchange with - and goes straight to end-user wallet-ownership proof.

<Note>
  Didit also operates the counterparty-facing side of the exchange: public TRP identity and inquiry endpoints other VASPs call to reach you, callback endpoints, and the email pickup flow.
  You never call those yourself - they are managed infrastructure - but the [Travel Rule interoperability](/transaction-monitoring/travel-rule-interoperability) page documents every one of them so counterparty VASPs can connect to you.
  You interact with Travel Rule only through the `/v3/` endpoints described on this page.
</Note>

## What executes when you submit a transfer

Everything below runs synchronously inside the one `POST /v3/transactions/` call - by the time you receive the response, screening has run, routing has been attempted, rules have been evaluated, and the transfer already has a definitive status.
There is no "pending pipeline" to poll for; the only asynchronous parts are the counterparty's answer and any end-user action.

```mermaid theme={null}
sequenceDiagram
    autonumber
    participant You as Your platform
    participant Didit as Didit API
    participant CP as Counterparty VASP
    participant User as Your customer

    You->>Didit: POST /v3/transactions/ (travelRule)
    Note over Didit: Validate + bind subject + blocklist check
    Note over Didit: Device & IP enrichment
    Note over Didit: Crypto screening (when crypto + monitoring on)
    Note over Didit: Threshold check -> rails in priority order -> analytics attribution
    Didit->>CP: Exchange over the first reachable rail
    Note over Didit: Rules engine (EU TFR bundle + your rules)
    Didit-->>You: Transaction + travel_rule.status + action_required
    Didit--)You: transaction.created webhook
    User->>Didit: Proves wallet control (when action_required)
    CP-->>Didit: Confirms beneficiary data
    Didit--)You: travel_rule.status.updated (COMPLETED)
    You->>You: Broadcast on-chain
    You->>Didit: PATCH .../travel-rule/ { payment_txn_id }
    Didit--)You: travel_rule.status.updated (FINISHED)
```

Step by step:

1. **Validation and identity binding.** The payload is validated (`txn_id` deduplicated - resubmitting the same id returns the existing transaction), and the `subject` is resolved to your user or business profile by `vendor_data`, linking the transfer to the identity you verified at onboarding. Blocklisted subjects, counterparties, wallets, IPs, and devices are declined immediately.
2. **Device and network enrichment.** Party IPs are geo-enriched, and any device context (automatic on [SDK submission](/transaction-monitoring/sdk-transaction-submission)) is normalized into the device graph - the same graph KYC sessions feed, so "related by device" works across onboarding and transactions.
3. **Crypto screening.** For crypto transfers with monitoring enabled, the relevant wallet (or on-chain hash) is screened against blockchain analytics before anything is exchanged - sanctions exposure, mixer proximity, stolen funds. See [Crypto & wallet screening](/transaction-monitoring/aml-screening).
4. **Travel Rule routing.** The exchange engine checks the threshold, honors a [self-hosted wallet declaration](#declared-self-hosted-wallets), then walks the [seven rails](#overview) in priority order; if none resolve, [blockchain analytics attribution](#blockchain-analytics-attribution) identifies the counterparty and the rails re-run once. Whatever the outcome, the transfer leaves this step with a concrete status - `AWAITING_COUNTERPARTY`, `COMPLETED` (INTERNAL rail), `UNCONFIRMED_OWNERSHIP`, or `COUNTERPARTY_VASP_NOT_FOUND`.
5. **Wallet-ownership minting.** If the transfer needs end-user proof of control and `auto_wallet_verification` is on, a [wallet-ownership widget](/transaction-monitoring/wallet-ownership-widget) session is minted and returned in `action_required`.
6. **Rules evaluation.** Every active rule runs - the [EU TFR bundle](#eu-tfr-rules-bundle) reacts to the transfer status set in step 4, your custom rules see the screening output of step 3, and a rule can hold the transaction (`IN_REVIEW`), decline it, or demand [step-up verification](/transaction-monitoring/sdk-transaction-submission#required-user-actions) (`AWAITING_USER`).
7. **Billing and notification.** The [\$0.02 Travel Rule line](#pricing) is recorded, the response returns with the full picture, and `transaction.created` fires to your webhook destinations.

### How each step maps to your obligations

| Pipeline step                                          | Obligation it discharges                                                                                                                     |
| ------------------------------------------------------ | -------------------------------------------------------------------------------------------------------------------------------------------- |
| Identity binding to your verified KYC profile          | Accurate, **verified** originator information (FATF R.16; EU TFR Art. 14) - the data transmitted is the identity you verified, not free text |
| Rails exchange before settlement                       | Originator and beneficiary information transmitted to the counterparty VASP **before** the transfer settles (FATF R.16; EU TFR Art. 14-16)   |
| Beneficiary name matching                              | Verification that the beneficiary data matches the destination (EU TFR Art. 16 obligations of the beneficiary CASP)                          |
| Self-hosted wallet ownership proof                     | The EU TFR self-hosted wallet obligation - verify ownership of an unhosted address instead of exchanging with a VASP                         |
| Crypto screening + EU TFR rules bundle                 | Risk-based procedures for transfers with missing or incomplete information, and sanctions exposure controls                                  |
| `COMPLETED` gate before broadcast                      | Funds are not released until the exchange concludes - the core of the rule                                                                   |
| `FINISHED` close-out with the on-chain hash + timeline | Recordkeeping: every transfer carries its full negotiation timeline for audit                                                                |

<Note>
  **Testing note.** Sandbox applications skip rule evaluation, webhooks, and billing entirely - sandbox transactions stay `APPROVED` and nothing is charged.
  The Travel Rule exchange engine itself still runs on sandbox applications when enabled - the transfer is created and moves through its statuses - but **outbound** dispatch is simulated: no rail is selected and no compliance message ever reaches a real counterparty VASP, so an outbound transfer parks at `AWAITING_COUNTERPARTY`. **Inbound** registration (`POST /v3/travel-rule/inbound/`) never dispatches, so sandbox resolves it against your wallet address book and settles it for real - `ON_HOLD`, `UNCONFIRMED_OWNERSHIP`, `COUNTERPARTY_MISMATCHED_DATA`, or `COMPLETED` then `FINISHED`. See [Transaction Monitoring in sandbox](/integration/sandbox-testing#transaction-monitoring-in-sandbox).
</Note>

## Lifecycle

Every transfer has a `status` drawn from 13 values.
The exchange starts at `AWAITING_COUNTERPARTY` in the normal case, at `NOT_APPLICABLE` when the amount is below your `threshold_amount`, or at `UNCONFIRMED_OWNERSHIP` when the destination was [declared a self-hosted wallet](#declared-self-hosted-wallets), and ends in one of the terminal states: `FINISHED`, `CANCELLED`, or `EXPIRED`.

The transfer runs its own state machine, **separate from** the underlying transaction's review status. Whenever the exchange transitions, Didit also nudges the transaction: `ON_HOLD` surfaces the transaction as `AWAITING_USER`, an expiry applies your configured `timeout_outcome`, and the [EU TFR rules](#eu-tfr-rules-bundle) can push it to `IN_REVIEW`. Read the exchange state from `travel_rule.status`; read the allow / hold / decline verdict from the transaction's own `status`.

Every transition (and every passively reported status) is also mirrored onto the transaction's custom values so [rules](/transaction-monitoring/rules) can key on it: `custom_values.travel_rule_status` (canonical status), `custom_values.travel_rule_rail` (the rail that carried the exchange, empty until one is selected), and `custom_values.travel_rule_regime` (derived from your [settings](#setup) `jurisdiction`: `SG` → `singapore`, `GB` → `uk`, and any EU or EEA member code such as `DE` or `FR` → `eu`; unmapped codes stamp lowercased, e.g. `US` → `us`. A `props.travel_rule_regime` you submit yourself always wins over the derived value).

| Status                              | Meaning                                                                                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| ----------------------------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `AWAITING_COUNTERPARTY`             | The exchange was sent to the counterparty (INTERNAL handoff or EMAIL pickup link) and Didit is waiting on a response.                                                                                                                                                                                                                                                                                                                                                                                    |
| `UNCONFIRMED_OWNERSHIP`             | The transfer is waiting on proof of wallet control. Reached when the counterparty wallet was [declared self-hosted](#declared-self-hosted-wallets) at submission (outbound or inbound), or when an inbound transfer resolves to an [address book entry](#wallet-address-book) whose ownership is not verified yet. Advances via the [wallet-ownership widget](/transaction-monitoring/wallet-ownership-widget) or [`POST .../travel-rule/ownership/`](#confirming-wallet-ownership).                     |
| `ON_HOLD`                           | Held for manual or analyst action, surfaced on the underlying transaction as `AWAITING_USER`.                                                                                                                                                                                                                                                                                                                                                                                                            |
| `COMPLETED`                         | Originator and beneficiary data matched (and ownership was confirmed, where required). Safe to broadcast the transfer on-chain.                                                                                                                                                                                                                                                                                                                                                                          |
| `FINISHED`                          | Outbound only. The on-chain transaction hash was reported via [`PATCH .../travel-rule/`](#sending-a-transfer) and the exchange is closed out.                                                                                                                                                                                                                                                                                                                                                            |
| `CANCELLED`                         | Manually cancelled with `action: "cancel"` from any non-terminal state.                                                                                                                                                                                                                                                                                                                                                                                                                                  |
| `EXPIRED`                           | `confirmation_timeout_hours` elapsed while `AWAITING_COUNTERPARTY`. A sweeper (every 15 minutes) expires the transfer and applies your configured `timeout_outcome` to the underlying transaction: `REJECT` declines it, `HOLD` moves it to review, `PROCEED` leaves it untouched.                                                                                                                                                                                                                       |
| `COUNTERPARTY_MISMATCHED_DATA`      | The beneficiary name returned by the counterparty did not satisfy the configured `name_matching_strictness`.                                                                                                                                                                                                                                                                                                                                                                                             |
| `COUNTERPARTY_VASP_NOT_FOUND`       | None of the seven rails - nor the [blockchain analytics attribution](#blockchain-analytics-attribution) fallback - could resolve a reachable counterparty VASP for this transfer. Any attributed entity is still recorded on the transfer and in the directory. On outbound transfers Didit auto-mints a [wallet-ownership widget](/transaction-monitoring/wallet-ownership-widget) session (when `auto_wallet_verification` is on) so the transfer can still complete as a self-hosted-wallet transfer. |
| `COUNTERPARTY_VASP_NOT_REACHABLE`   | A counterparty VASP was identified (travel address or directory entry) but its `TRP` endpoint could not be reached. Retry with `action: "resend"` once it is reachable again.                                                                                                                                                                                                                                                                                                                            |
| `COUNTERPARTY_VASP_GENERAL_DECLINE` | The counterparty declined the exchange (ownership denied, or email pickup declined).                                                                                                                                                                                                                                                                                                                                                                                                                     |
| `NOT_ENOUGH_COUNTERPARTY_DATA`      | The counterparty responded (over `TRP` or `EMAIL`) without enough data to complete the exchange. Repairable - update the counterparty data and re-run routing with `action: "resend"`.                                                                                                                                                                                                                                                                                                                   |
| `NOT_APPLICABLE`                    | Travel Rule is disabled for the sending application, the transfer amount was below the configured `threshold_amount`, or a legacy status string was recorded passively (see below).                                                                                                                                                                                                                                                                                                                      |

<Warning>
  **Never broadcast before `COMPLETED`.**
  Releasing funds on-chain while a transfer is `AWAITING_COUNTERPARTY`, `UNCONFIRMED_OWNERSHIP`, or in any mismatch/decline state defeats the purpose of the exchange.
  Gate your broadcast step on `status == "COMPLETED"`, then call `PATCH .../travel-rule/` with the resulting `payment_txn_id` to move to `FINISHED`.
</Warning>

The transitions at a glance (`CANCELLED` is additionally reachable from every non-terminal state with `action: "cancel"`):

```mermaid theme={null}
stateDiagram-v2
    [*] --> NOT_APPLICABLE: below threshold or disabled
    [*] --> UNCONFIRMED_OWNERSHIP: self-hosted wallet declared
    [*] --> AWAITING_COUNTERPARTY: rail dispatched
    [*] --> COMPLETED: INTERNAL rail, verified entry + name match
    [*] --> ON_HOLD: inbound with no matching wallet entry
    [*] --> COUNTERPARTY_VASP_NOT_FOUND: no rail resolved
    [*] --> COUNTERPARTY_VASP_NOT_REACHABLE: rail delivery failed
    AWAITING_COUNTERPARTY --> COMPLETED: counterparty confirmed, names match
    AWAITING_COUNTERPARTY --> COUNTERPARTY_MISMATCHED_DATA: name match failed
    AWAITING_COUNTERPARTY --> COUNTERPARTY_VASP_GENERAL_DECLINE: counterparty declined
    AWAITING_COUNTERPARTY --> NOT_ENOUGH_COUNTERPARTY_DATA: incomplete response
    AWAITING_COUNTERPARTY --> EXPIRED: confirmation timeout
    UNCONFIRMED_OWNERSHIP --> COMPLETED: ownership proven, names match
    UNCONFIRMED_OWNERSHIP --> COUNTERPARTY_MISMATCHED_DATA: name match failed
    UNCONFIRMED_OWNERSHIP --> COUNTERPARTY_VASP_GENERAL_DECLINE: ownership denied
    COUNTERPARTY_VASP_NOT_FOUND --> AWAITING_COUNTERPARTY: action resend
    COUNTERPARTY_VASP_NOT_REACHABLE --> AWAITING_COUNTERPARTY: action resend
    NOT_ENOUGH_COUNTERPARTY_DATA --> AWAITING_COUNTERPARTY: action resend
    COMPLETED --> FINISHED: payment_txn_id reported
    FINISHED --> [*]
    EXPIRED --> [*]
```

### Legacy status values

If you were already sending `travel_rule_details.status` before this release, those values still work and are mapped automatically.
camelCase spellings of any status (for example `counterpartyVaspNotFound`) are accepted too, both on submission and in [rule](/transaction-monitoring/rules) condition values, and normalize to the canonical form:

| Legacy value           | Mapped to               |
| ---------------------- | ----------------------- |
| `UNKNOWN`              | `NOT_APPLICABLE`        |
| `COMPLIANT`            | `COMPLETED`             |
| `PENDING_ACTION`       | `ON_HOLD`               |
| `PENDING_COUNTERPARTY` | `AWAITING_COUNTERPARTY` |
| `FAILED`               | `CANCELLED`             |
| `EXEMPT`               | `NOT_APPLICABLE`        |

## Setup

Configure your VASP profile and negotiation policy once per application with `GET`/`PUT /v3/travel-rule/settings/`.

```bash theme={null}
curl -X GET https://verification.didit.me/v3/travel-rule/settings/ \
  -H "x-api-key: YOUR_API_KEY"
```

```json theme={null}
{
  "is_enabled": false,
  "jurisdiction": "EU",
  "name_matching_strictness": "DEFAULT",
  "confirmation_timeout_hours": 48,
  "timeout_outcome": "HOLD",
  "threshold_amount": "0.00",
  "inbound_auto_accept": true,
  "allow_self_declaration": true,
  "allow_screenshot_proof": true,
  "auto_wallet_verification": true,
  "legal_name": "",
  "lei": "",
  "compliance_email": "",
  "is_discoverable": true,
  "travel_address": ""
}
```

```bash theme={null}
curl -X PUT https://verification.didit.me/v3/travel-rule/settings/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "is_enabled": true,
    "legal_name": "Origin CASP SL",
    "jurisdiction": "EU",
    "name_matching_strictness": "DEFAULT",
    "confirmation_timeout_hours": 48,
    "timeout_outcome": "HOLD",
    "is_discoverable": true
  }'
```

`PUT` is a partial update - send only the fields you want to change.

| Field                        | Type             | Description                                                                                                                                                                                                                                                                                                                                                                                                   |
| ---------------------------- | ---------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `is_enabled`                 | boolean          | Turns on the managed negotiation flow for outbound `travelRule` transactions from this application. Requires a non-blank `legal_name` (already stored, or included in the same request) - otherwise the request returns `400`.                                                                                                                                                                                |
| `legal_name`                 | string           | Your VASP's legal name. Shown to the counterparty on the email pickup page and returned in the [VASP directory](#directory).                                                                                                                                                                                                                                                                                  |
| `lei`                        | string           | Your Legal Entity Identifier, returned in the VASP directory.                                                                                                                                                                                                                                                                                                                                                 |
| `jurisdiction`               | string           | Your VASP's operating jurisdiction code, up to 8 characters (default `"EU"`).                                                                                                                                                                                                                                                                                                                                 |
| `name_matching_strictness`   | string           | `NONE`, `STRICT`, `DEFAULT`, or `FUZZY` - see below.                                                                                                                                                                                                                                                                                                                                                          |
| `confirmation_timeout_hours` | integer          | Hours an `AWAITING_COUNTERPARTY` transfer is allowed to sit before it auto-expires. Minimum `1`, default `48`.                                                                                                                                                                                                                                                                                                |
| `timeout_outcome`            | string           | What happens to the underlying transaction when a transfer expires: `HOLD` moves it to review, `REJECT` declines it, `PROCEED` leaves its status untouched. Default `HOLD`.                                                                                                                                                                                                                                   |
| `compliance_email`           | string           | Compliance contact email for your VASP profile.                                                                                                                                                                                                                                                                                                                                                               |
| `is_discoverable`            | boolean          | Whether your VASP profile appears in `GET /v3/travel-rule/vasps/` search results for other Didit customers, and whether the INTERNAL rail can route to you at all. Default `true`.                                                                                                                                                                                                                            |
| `inbound_auto_accept`        | boolean          | When `true`, inbound transfers whose beneficiary wallet is a verified entry in your address book and whose name matches are accepted automatically, without a manual review step. Default `true`.                                                                                                                                                                                                             |
| `allow_self_declaration`     | boolean          | When `true`, the [wallet-ownership widget](/transaction-monitoring/wallet-ownership-widget) offers self-declaration as a fallback proof method for wallets that cannot be verified another way. Default `true`.                                                                                                                                                                                               |
| `allow_screenshot_proof`     | boolean          | When `true`, the [wallet-ownership widget](/transaction-monitoring/wallet-ownership-widget) offers screenshot upload as an ownership evidence method. Weaker than cryptographic signing - disable it where your policy requires signature-grade proof. Default `true`.                                                                                                                                        |
| `auto_wallet_verification`   | boolean          | When `true`, an outbound transfer that needs end-user proof of wallet control auto-mints a [wallet-ownership widget](/transaction-monitoring/wallet-ownership-widget) session bound to the transaction and surfaces it in the transaction's `action_required` block - the Didit SDKs launch it automatically on [client-side submission](/transaction-monitoring/sdk-transaction-submission). Default `true`. |
| `vasp_attribution_enabled`   | boolean          | When `true`, an outbound transfer that no rail can route is attributed through [blockchain analytics](#blockchain-analytics-attribution) - the destination wallet is resolved to its owning VASP, the entity is added to the directory, and the rails are re-run once with the attributed name. Default `true`.                                                                                               |
| `threshold_amount`           | string (decimal) | Minimum transfer amount, in the transaction's currency, that triggers a managed exchange. Transfers below it resolve straight to `NOT_APPLICABLE` and are never negotiated. Defaults to `0.00` - matching the EU TFR's no-minimum-amount framing, so every transfer is checked regardless of size.                                                                                                            |
| `disabled_networks`          | string\[]        | Network rails (`GTR`, `TRUST`, `VERIFYVASP`, `SYGNA`) your transfers must NOT route over via Didit's platform membership. A network you connected your own membership for (console Marketplace) is never affected by this list. Default `[]`.                                                                                                                                                                 |
| `networks`                   | object           | Read-only. Per-network status keyed by `gtr` / `trust` / `verifyvasp` / `sygna`: `{rail, mode, platform_available, connected}` where `mode` is `own` (your connected membership), `didit` (Didit's platform membership), `off` (disabled by you), or `unavailable`.                                                                                                                                           |
| `travel_address`             | string           | Read-only. Your VASP's own travel address - the encoded inbound `TRP` inquiry endpoint other VASPs use to reach you. Populated once your VASP profile is complete.                                                                                                                                                                                                                                            |

### Name matching strictness

| Value     | Behaviour                                                                                                |
| --------- | -------------------------------------------------------------------------------------------------------- |
| `NONE`    | Any beneficiary name is accepted - no comparison is made.                                                |
| `STRICT`  | The normalized token sets of both names must be exactly equal.                                           |
| `DEFAULT` | Every token of the shorter name must appear in the longer name (subset match), with at least two tokens. |
| `FUZZY`   | A similarity ratio of the full normalized strings must be at least `0.85`.                               |

### Thresholds by jurisdiction

`threshold_amount` exists because Travel Rule scope varies by regulator.
Didit defaults to `0.00` - the EU position - so every transfer is exchanged unless you raise it deliberately:

| Regime                                               | Threshold            | Notes                                                                                                                             |
| ---------------------------------------------------- | -------------------- | --------------------------------------------------------------------------------------------------------------------------------- |
| **EU** - Transfer of Funds Regulation (EU) 2023/1113 | **No minimum**       | Every CASP-to-CASP crypto transfer is in scope. Ownership of a self-hosted wallet must be verified for transfers above EUR 1,000. |
| **FATF Recommendation 16** (global baseline)         | USD/EUR 1,000        | Below it, FATF permits a reduced data set (names and wallet addresses, without verification).                                     |
| **United States** - BSA Travel Rule                  | USD 3,000            | The long-standing FinCEN funds-transfer threshold, applied to convertible virtual currency.                                       |
| **United Kingdom**                                   | EUR 1,000 equivalent | Full information above; reduced data set below (MLRs Part 7A).                                                                    |
| **Singapore** - MAS PSN02                            | SGD 1,500            | Reduced requirements below the threshold.                                                                                         |
| **Switzerland** - FINMA                              | No minimum           | Information required for all transfers; proof of ownership expected for self-hosted wallets.                                      |

Set `threshold_amount` to your regulator's figure; transfers below it resolve to `NOT_APPLICABLE` without exchanging any identity data.
Thresholds evolve - confirm the current figure with your compliance counsel rather than treating this table as legal advice.

### IVMS 101 data model

The industry standard for the data exchanged under the Travel Rule is **IVMS 101** (interVASP Messaging Standard).
`travel_rule_details.originator_data` and `travel_rule_details.beneficiary_data` are IVMS 101-style person payloads: Didit wraps them in each rail's native envelope - the TRP rail exchanges `IVMS101` blocks (`ivms101.2023`, reported in the transfer's `ivms_version` field), the Sygna rail its ECIES-encrypted IVMS variant, and the network rails their own signed envelopes - so one payload shape reaches every counterparty in the format their protocol expects.

Two practical rules:

* **Latin script.** IVMS 101 requires Latin-script values; transliterate names that are natively written in another script. Didit's [name matching](#name-matching-strictness) compares normalized token sets, so ordering and casing differences don't fail an exchange - but different scripts on the two sides will.
* **You send data you have verified.** Because the subject is bound to your Didit KYC profile by `vendor_data`, the originator identity you transmit is the one Didit verified at onboarding - document-extracted, liveness-checked, and face-matched - not an unverified form field. That distinction is exactly what the FATF's "required and **accurate** originator information" wording demands.

### Travel addresses

A **travel address** is a compact, encoded string that points at a VASP's inbound `TRP` inquiry endpoint - it never exposes a raw URL or any wallet address.
Once your VASP profile is complete, Didit derives your own `travel_address` (returned read-only in settings) and publishes it so other VASPs can reach you on the `TRP` rail.
When you know a counterparty's travel address, store it on the destination [wallet address book entry](#wallet-address-book) so Didit routes that beneficiary's transfers straight over `TRP` instead of falling back to email.

## Testing without network credentials

You do not need a GTR, TRUST, VerifyVASP, or Sygna membership to test the membership-free paths. You still need a Didit API key for the application under test.

* **Sandbox inbound:** enable Travel Rule with a legal name, register a destination wallet in the address book, then call [Register Inbound Travel Rule Transfer](/management-api/travel-rule/register-inbound). Test an unknown wallet, an unverified wallet, a beneficiary-name mismatch, and a verified matching wallet. These exercise real inbound decisions without contacting a network.
* **Sandbox outbound:** submit a `travelRule` transaction. After threshold and self-hosted-wallet checks, dispatch is simulated and ordinarily waits at `AWAITING_COUNTERPARTY`. No network, email, or internal counterparty receives it; this does not prove delivery or completion of a two-party exchange.
* **Two controlled live applications:** use the `INTERNAL` rail between your own applications, or a controlled TRP counterparty, to test the exchange lifecycle without commercial network credentials. Live applications can incur normal charges and notifications; use test identities and counterparties you control.

See [Transaction Monitoring in sandbox](/integration/sandbox-testing#transaction-monitoring-in-sandbox) for the exact boundaries. Successful sandbox or local protocol tests do not validate a commercial network's credentials, membership, or production interoperability. Those require an authorized network sandbox or a controlled live exchange with valid membership credentials.

## Sending a transfer

Include the transfer on [`POST /v3/transactions/`](/transaction-monitoring/transactions) by setting `transaction_category` to `travelRule` (or `travel_rule`) and attaching a `travel_rule_details` object (alias: `travelRule`).

When Travel Rule is **enabled** for your application, Didit ignores any `status` you send and drives the exchange itself:

1. If the amount is below your configured `threshold_amount`, the transfer resolves immediately to `NOT_APPLICABLE` and nothing is negotiated.
2. If the counterparty's payment method declares the destination as a self-hosted wallet (`payment_method.method_type: "unhosted_wallet"`), no rail is tried - the transfer goes straight to `UNCONFIRMED_OWNERSHIP` and the wallet-ownership widget is auto-minted (see [Declared self-hosted wallets](#declared-self-hosted-wallets)).
3. Otherwise the rails run in priority order, and the first one that can reach the counterparty carries the exchange:
   * `INTERNAL` - `beneficiary_data.wallet_address` is registered in another Didit customer's wallet address book.
   * `TRP` - the transfer's asset has a Digital Token Identifier mapping (`BTC` and `ETH` today), and the payload carries `beneficiary_data.travel_address`, the destination's own address-book entry stores one, or the counterparty resolves in the [directory](#directory) (by `counterparty_vasp_lei` or `counterparty_vasp_name`) with a TRP endpoint.
   * `GTR`, `TRUST`, `VERIFYVASP`, `SYGNA` - the network is active for your application (your own connected membership, or Didit's platform membership when the network is not in `disabled_networks`), and the counterparty resolves to a network id (explicit field or directory entry - see [Counterparty resolution fields](#counterparty-resolution-fields)).
   * `EMAIL` - `beneficiary_data.counterparty_vasp_email` was supplied, or `counterparty_vasp_name` resolves to a directory entry with a compliance email.
4. If no rail can resolve a counterparty and `vasp_attribution_enabled` is on, Didit runs [blockchain analytics attribution](#blockchain-analytics-attribution): the destination wallet is resolved to its owning VASP, the attributed name is written to `beneficiary_data.counterparty_vasp_name` (when empty) and to the [directory](#directory), and the rails re-run once - so a wallet attributed to a VASP whose directory entry carries a TRP endpoint, network id, or compliance email routes on this second pass.
5. If the counterparty is still unresolved, the transfer is created in `COUNTERPARTY_VASP_NOT_FOUND`. On outbound transfers Didit auto-mints the [wallet-ownership widget](/transaction-monitoring/wallet-ownership-widget) (when `auto_wallet_verification` is on) so the transfer can still complete as a self-hosted-wallet transfer, and you can re-run routing later with `action: "resend"` once you have better counterparty data.

### Counterparty resolution fields

Everything Didit knows about the counterparty comes from `travel_rule_details.beneficiary_data`.
These fields drive rail resolution; all are optional:

| Field                              | Drives                                                                                                                                                                                                                |
| ---------------------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wallet_address`                   | `INTERNAL` address-book match, `TRP` address-book lookup, and the wallet-ownership flows.                                                                                                                             |
| `travel_address`                   | Routes directly over `TRP` - the strongest signal you can pass.                                                                                                                                                       |
| `counterparty_vasp_lei`            | Directory lookup by LEI for `TRP`, `GTR`, `TRUST`, `VERIFYVASP`, and `SYGNA`. Also cross-checked against the identity the TRP endpoint reports - a mismatch aborts the exchange as `COUNTERPARTY_VASP_NOT_REACHABLE`. |
| `counterparty_vasp_name`           | Directory lookup by exact name for `TRP`, `GTR`, `TRUST`, `VERIFYVASP`, `SYGNA`, and `EMAIL`. Fuzzy-checked against the TRP identity when both are present.                                                           |
| `counterparty_gtr_vasp_code`       | Explicit `GTR` network id - skips the directory.                                                                                                                                                                      |
| `counterparty_trust_membership_id` | Explicit `TRUST` network id - skips the directory.                                                                                                                                                                    |
| `counterparty_verifyvasp_id`       | Explicit `VerifyVASP` network id - skips the directory.                                                                                                                                                               |
| `counterparty_sygna_vasp_code`     | Explicit `Sygna Bridge` VASP code - skips the directory.                                                                                                                                                              |
| `counterparty_vasp_email`          | Explicit compliance contact for the `EMAIL` rail - skips the directory.                                                                                                                                               |

### Blockchain analytics attribution

When you pass nothing but a wallet address, Didit can still find out who is on the other side.
If no rail can route the transfer, Didit resolves the destination wallet against blockchain analytics attribution data - the same analysis that powers [crypto transaction screening](/transaction-monitoring/aml-screening) knows which wallets belong to which exchanges and custodians.

When the wallet is attributed to a known entity, Didit:

1. Records the attribution on the transfer: `beneficiary_data.counterparty_vasp_name` is filled (when you did not supply one), and the transfer's metadata carries a `vasp_attribution` block with the entity name, entity type, country, and `source: "blockchain_analytics"`.
2. Adds the entity to your [VASP directory](#directory) (or matches the existing entry), so the attribution is stable across transfers and you can enrich the entry with a travel address, network ids, or a compliance email.
3. Re-runs the rails once with the attributed name - a directory entry that already carries a TRP endpoint, network id, or compliance email makes the transfer route immediately instead of landing in `COUNTERPARTY_VASP_NOT_FOUND`.

The attribution call doubles as a full crypto screening: the transaction receives the complete screening output - risk score, wallet risk category, network snapshot - exactly as if crypto monitoring had run, and the transaction's `custom_values.aml_screening_trigger` is set to `travel_rule_attribution` so you can see the screening ran because Travel Rule routing required it.
When crypto monitoring already screened the same wallet on this transaction, the stored result is reused - no second analytics call, no second charge.
Attribution never blocks transaction creation: if the analytics lookup fails, the transfer simply proceeds to `COUNTERPARTY_VASP_NOT_FOUND` and nothing is charged for the attempt.
On `action: "resend"`, a previously recorded attribution is reused instead of re-queried.

Disable the whole step with `vasp_attribution_enabled: false` in [settings](#setup).
See [Pricing](#pricing) for how the attribution call is billed.

When Travel Rule is **disabled**, `travel_rule_details` (including a caller-supplied `status`, legacy or current) is still recorded on the transaction, but passively - no rail is dispatched.
Use this to backfill compliance data you already tracked with your own process.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "trv-2026-07-05-001",
    "transaction_category": "travelRule",
    "transaction_details": {
      "direction": "outbound",
      "action_type": "transfer",
      "amount": "1500.00",
      "currency": "EUR"
    },
    "subject": {
      "entity_type": "person",
      "vendor_data": "user-042",
      "full_name": "Jane Doe"
    },
    "travel_rule_details": {
      "beneficiary_data": {
        "wallet_address": "0xBeneficiaryWallet01",
        "name": "Ana Diaz"
      }
    }
  }'
```

```json theme={null}
{
  "uuid": "22222222-3333-4444-5555-666666666666",
  "txn_id": "trv-2026-07-05-001",
  "transaction_type": "travelRule",
  "direction": "OUTBOUND",
  "status": "APPROVED",
  "amount": "1500",
  "currency": "EUR",
  "travel_rule": {
    "uuid": "33333333-4444-5555-6666-777777777777",
    "status": "AWAITING_COUNTERPARTY",
    "protocol": "EMAIL",
    "required": true,
    "obligations_count": 0,
    "originator_data": {},
    "beneficiary_data": {
      "wallet_address": "0xBeneficiaryWallet01",
      "name": "Ana Diaz"
    },
    "metadata": {}
  }
}
```

If the beneficiary wallet is already a verified entry in another Didit customer's address book and its `holder_name` matches, the `INTERNAL` rail can resolve the whole exchange synchronously - the response above would show `"status": "COMPLETED"` instead.

<Note>
  The transaction's embedded `travel_rule` object is intentionally short (`uuid`, `status`, `protocol`, `required`, `obligations_count`, `originator_data`, `beneficiary_data`, `metadata`).
  The dedicated transfer endpoints below return a fuller object that also includes `direction`, `rail`, `ivms_version`, `ownership_confirmed`, `deadline_at`, `timeline`, and `counterparty_vasp`.
</Note>

To close out a `COMPLETED` outbound transfer once you've broadcast it on-chain:

```bash theme={null}
curl -X PATCH https://verification.didit.me/v3/transactions/22222222-3333-4444-5555-666666666666/travel-rule/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"payment_txn_id": "0xchainhash"}'
```

This requires the transfer to be an **outbound** transfer in `COMPLETED` status - otherwise the API returns `409`.
On success both the outbound transfer and its `INTERNAL`-rail counterpart move to `FINISHED`, and the transaction's `payment_txn_id` is set to the hash you provided.

To cancel a transfer that hasn't reached a terminal state yet, send `{"action": "cancel"}` to the same endpoint instead.

To retry an outbound transfer that could not reach its counterparty - one currently in `COUNTERPARTY_VASP_NOT_FOUND`, `COUNTERPARTY_VASP_NOT_REACHABLE`, or `NOT_ENOUGH_COUNTERPARTY_DATA` - first improve the counterparty data (for example add a `travel_address` to the destination wallet entry, or catalogue the VASP in the [directory](#directory)), then send `{"action": "resend"}` to the same endpoint. Didit re-runs the routing ladder from the start. Any other status returns `409`.

```bash theme={null}
curl -X PATCH https://verification.didit.me/v3/transactions/22222222-3333-4444-5555-666666666666/travel-rule/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"action": "resend"}'
```

### Declared self-hosted wallets

When your customer tells you the destination is their own self-hosted (unhosted) wallet, declare it on the transaction instead of letting routing discover there is no VASP behind it: set the counterparty's payment method type to `unhosted_wallet`.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/transactions/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "transaction_id": "trv-2026-07-07-002",
    "transaction_category": "travelRule",
    "transaction_details": {
      "direction": "outbound",
      "action_type": "transfer",
      "amount": "0.25",
      "currency": "ETH",
      "currency_type": "crypto"
    },
    "subject": {
      "entity_type": "person",
      "vendor_data": "user-042",
      "full_name": "Jane Doe"
    },
    "counterparty": {
      "entity_type": "external",
      "full_name": "Jane Doe",
      "payment_method": {
        "method_type": "unhosted_wallet",
        "account_id": "0xJanesColdWallet01"
      }
    },
    "travel_rule_details": {
      "beneficiary_data": {
        "wallet_address": "0xJanesColdWallet01",
        "name": "Jane Doe"
      }
    }
  }'
```

The declaration short-circuits routing entirely:

* No rail is tried - there is no counterparty VASP to exchange with - and the transfer is created directly in `UNCONFIRMED_OWNERSHIP`.
* When `auto_wallet_verification` is on (the default), Didit auto-mints a [wallet-ownership widget](/transaction-monitoring/wallet-ownership-widget) session bound to the transaction and returns it in the transaction's `action_required` block; the SDKs launch it automatically on [client-side submission](/transaction-monitoring/sdk-transaction-submission).
* Once the customer proves control of the wallet, the transfer runs the beneficiary name match and advances to `COMPLETED` (or `COUNTERPARTY_MISMATCHED_DATA` on a failed match).

This is the EU TFR self-hosted wallet obligation in API form: verify ownership of the unhosted wallet instead of exchanging data with a counterparty VASP.
The declaration is read from the payment method on the **destination** side of an outbound transfer and the **source** side of an inbound one - in both cases, the counterparty participant.
A declared-unhosted transfer is already on its final rail-free path, so `UNCONFIRMED_OWNERSHIP` is not a resendable state - complete the ownership proof (or cancel) instead of calling `action: "resend"`.

## Receiving

### Confirming wallet ownership

When the `INTERNAL` rail resolves a transfer to a wallet address whose address-book entry hasn't been ownership-verified, the beneficiary side is created in `UNCONFIRMED_OWNERSHIP`.
The beneficiary's application confirms or denies it:

```bash theme={null}
curl -X POST https://verification.didit.me/v3/transactions/{transaction_uuid}/travel-rule/ownership/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"confirmed": true}'
```

* `confirmed: true` marks the matching wallet address book entry as ownership-verified, then runs the name match on both sides - `COMPLETED` if it passes, `COUNTERPARTY_MISMATCHED_DATA` if it doesn't.
* `confirmed: false` moves both sides of the transfer to `COUNTERPARTY_VASP_GENERAL_DECLINE`.
* Returns `409` if the transfer is not currently `UNCONFIRMED_OWNERSHIP`, or if the wallet address book entry it needs was deleted in the meantime.

The response is the fuller transfer object described above; `originator_data`/`beneficiary_data` are omitted entirely until `ownership_confirmed` is `true` on an inbound transfer, to avoid leaking counterparty PII before ownership is proven.

### Wallet address book

Register the wallets you control so inbound `INTERNAL`-rail transfers can resolve against them, with `POST`/`GET /v3/travel-rule/wallet-addresses/` and `PATCH`/`DELETE /v3/travel-rule/wallet-addresses/{entry_uuid}/`.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/travel-rule/wallet-addresses/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "address": "0xBeneficiaryWallet01",
    "chain": "ethereum",
    "holder_name": "Ana Diaz",
    "holder_vendor_data": "user-042",
    "self_declared": true
  }'
```

| Field                   | Type    | Description                                                                                                                                                                                                             |
| ----------------------- | ------- | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `address`               | string  | The wallet address. Unique per application and `chain` among non-deleted entries - a duplicate returns `400`.                                                                                                           |
| `chain`                 | string  | Free-text chain identifier (for example `ethereum`, `bitcoin`). Optional.                                                                                                                                               |
| `holder_name`           | string  | Name of the wallet holder, used for the beneficiary name match.                                                                                                                                                         |
| `holder_vendor_data`    | string  | Your internal identifier for the holder.                                                                                                                                                                                |
| `entity_type`           | string  | Free text, defaults to `"individual"`.                                                                                                                                                                                  |
| `travel_address`        | string  | Optional. The counterparty VASP's travel address for this wallet, if you know it. Lets Didit route transfers to this beneficiary over the `TRP` rail instead of email.                                                  |
| `is_ownership_verified` | boolean | Read-only. Whether ownership of this address has been proven (via the [wallet-ownership widget](/transaction-monitoring/wallet-ownership-widget) or self-declaration).                                                  |
| `self_declared`         | boolean | Write-only, `POST` only. When `true`, the entry is created already verified via a `SELF_DECLARATION` proof - inbound transfers to this address skip `UNCONFIRMED_OWNERSHIP` entirely and go straight to the name match. |

`PATCH` accepts `holder_name`, `holder_vendor_data`, `entity_type`, and `travel_address`, and returns only those four fields.
`DELETE` deletes the entry (`204`) - its address is freed up for re-registration and it immediately stops matching new transfers.

<Note>
  Matching is currently by address only, not scoped by `chain`.
  Avoid registering the same address string for two different chains under one application.
</Note>

### Email pickup for unreachable counterparties

When no protocol rail can reach the counterparty, Didit falls back to `EMAIL`: it sends a one-time pickup link to `beneficiary_data.counterparty_vasp_email` (or an email resolved from `beneficiary_data.counterparty_vasp_name` against the VASP directory registry).
The recipient does not need a Didit account or an API key - the link's token is the authentication.

```bash theme={null}
curl https://verification.didit.me/v3/travel-rule/pickup/{token}/
```

```json theme={null}
{
  "originator_vasp_name": "Origin CASP SL",
  "amount": "1500.00",
  "currency": "EUR",
  "beneficiary_wallet": "bc1qexternalwallet01",
  "status": "AWAITING_COUNTERPARTY"
}
```

```bash theme={null}
curl -X POST https://verification.didit.me/v3/travel-rule/pickup/{token}/respond/ \
  -H "Content-Type: application/json" \
  -d '{"decision": "accept", "beneficiary_name": "Carlos Ruiz"}'
```

`decision` is `accept` or `decline`.
On `accept`, the supplied `beneficiary_name` is run through the originator's `name_matching_strictness` policy - `COMPLETED` on a match, `COUNTERPARTY_MISMATCHED_DATA` otherwise.
On `decline`, the transfer moves to `COUNTERPARTY_VASP_GENERAL_DECLINE`.
Both endpoints return `404` for an unknown token and `410` once the window closes - either the transfer left `AWAITING_COUNTERPARTY`, or `pickup_expires_at` (the same deadline as `confirmation_timeout_hours`) has passed.

### After-deposit sunrise registration

When a crypto deposit settles on-chain **before** any Travel Rule exchange took place - the sending VASP was unreachable, or you are backfilling historical deposits - register it after the fact with `POST /v3/travel-rule/inbound/`.

```bash theme={null}
curl -X POST https://verification.didit.me/v3/travel-rule/inbound/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "chain": "ethereum",
    "txid": "0xdeposit-hash",
    "wallet_address": "0xYourDepositWallet",
    "amount": "500.00",
    "currency": "USDC",
    "originator_data": { "name": "Origin CASP SL" },
    "beneficiary_data": { "name": "Ana Diaz" },
    "originating_vasp": { "name": "Origin CASP SL", "lei": "", "travel_address": "ta..." }
  }'
```

| Field              | Type             | Description                                                                                                                                                                                                                                          |
| ------------------ | ---------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `chain`            | string           | Chain the deposit settled on.                                                                                                                                                                                                                        |
| `txid`             | string           | The on-chain transaction hash. Used to dedupe - the same `txid` + `wallet_address` returns the existing transfer instead of creating a duplicate.                                                                                                    |
| `wallet_address`   | string           | The destination wallet you received the deposit on.                                                                                                                                                                                                  |
| `amount`           | string (decimal) | Deposit amount.                                                                                                                                                                                                                                      |
| `currency`         | string           | Deposit asset.                                                                                                                                                                                                                                       |
| `originator_data`  | object           | IVMS-101 originator payload from the sending VASP, if known.                                                                                                                                                                                         |
| `beneficiary_data` | object           | IVMS-101 beneficiary payload (your customer).                                                                                                                                                                                                        |
| `originating_vasp` | object           | Optional `{ name, lei, travel_address }` describing the sender. A `travel_address` lets Didit reach them on the `TRP` rail for any follow-up, and the VASP is catalogued in the [directory](#how-entries-get-into-the-directory) for future routing. |

Didit creates an inbound `travelRule` transaction (or reuses an unclaimed deposit it already recorded) and resolves the transfer against your [wallet address book](#wallet-address-book):

* No matching entry -> `ON_HOLD`.
* Entry exists but ownership is unproven -> `UNCONFIRMED_OWNERSHIP`.
* Beneficiary name does not match the entry's `holder_name` -> `COUNTERPARTY_MISMATCHED_DATA`.
* Verified entry and the name matches -> `COMPLETED`, then immediately `FINISHED` (the deposit has already settled).

```json theme={null}
{
  "transaction_id": "44444444-5555-6666-7777-888888888888",
  "txn_id": "sunrise-...",
  "created": true,
  "travel_rule": {
    "uuid": "55555555-6666-7777-8888-999999999999",
    "status": "FINISHED",
    "direction": "INBOUND",
    "required": true
  }
}
```

`created` is `true` when a new transaction was minted (HTTP `201`) and `false` when an existing one was reused (HTTP `200`).
On the verified-entry path both transitions happen before the endpoint responds, so the synchronous response already shows the terminal `FINISHED` status - the intermediate `COMPLETED` step is still recorded in the transfer's `timeline`.
When a new transaction is created, a [`transaction.created`](/integration/webhooks#event-types) webhook fires for it, followed by a `travel_rule.status.updated` for each transition (`COMPLETED` and `FINISHED` each fire one).
If crypto monitoring is enabled for your application, the deposit is also AML-screened and billed at the standard monitoring rate.

### Wallet ownership widget

To move a transfer out of `UNCONFIRMED_OWNERSHIP` - or to pre-verify a wallet before any transfer arrives - mint a hosted wallet-ownership widget with `POST /v3/travel-rule/widget-session/` and send your customer to the returned `url`. The widget proves control of the wallet by message signing, a Satoshi test, a screenshot, or self-declaration, then marks the matching address-book entry verified so the exchange can continue.

See [Wallet ownership widget](/transaction-monitoring/wallet-ownership-widget) for the full flow, the proof methods, and the important note that the widget must be opened in a real browser - never inside a mobile SDK webview.

## Directory

`GET /v3/travel-rule/vasps/?search=<name>` searches a combined directory of discoverable Didit customers and VASPs your compliance team has catalogued in the internal counterparty registry.

```bash theme={null}
curl "https://verification.didit.me/v3/travel-rule/vasps/?search=Bene" \
  -H "x-api-key: YOUR_API_KEY"
```

```json theme={null}
{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "name": "Bene CASP GmbH",
      "lei": "",
      "jurisdiction": "EU",
      "dd_status": "COMPLETED",
      "dd_score": 0,
      "dd_score_breakdown": {},
      "dd_assessed_at": null,
      "reachable_rails": ["INTERNAL"],
      "is_didit_customer": true
    },
    {
      "name": "Northwind Digital Assets Ltd",
      "lei": "5493001KJTIIGC8Y1R12",
      "jurisdiction": "MT",
      "dd_status": "COMPLETED",
      "dd_score": 34,
      "dd_score_breakdown": {
        "licensing": 5,
        "sanctions_pep": 0,
        "country_risk": 14,
        "analytics_risk": 15
      },
      "dd_assessed_at": "2026-06-30T09:12:00Z",
      "reachable_rails": ["EMAIL"],
      "is_didit_customer": false
    }
  ]
}
```

Results are paginated with `limit` (default `50`) and `offset` query parameters; `count`, `next`, and `previous` describe the page window.

`is_didit_customer: true` entries are other Didit applications with Travel Rule enabled and `is_discoverable: true` - reachable on the `INTERNAL` rail. Their `dd_status` is always `COMPLETED` and `dd_score` always `0`.
`is_didit_customer: false` entries come from the internal counterparty registry and carry a real `dd_status`/`dd_score`.
The `dd_score` is a single point-banded risk figure (higher is riskier); `dd_score_breakdown` shows the per-component contributions - licensing and registry standing, sanctions and PEP exposure, jurisdiction risk, and on-chain analytics risk - all derived from checks Didit already runs in-house, with no third-party lookup in the request path. `dd_assessed_at` is when that assessment last ran.
Gate on the score with the [EU TFR rules bundle](#eu-tfr-rules-bundle) rather than branching on it inline.
Your own VASP profile never appears in your own directory results.

### How entries get into the directory

There is no pre-seeded global VASP list - the directory grows from real activity:

* Didit customers appear automatically once they enable Travel Rule and keep `is_discoverable: true`.
* An inbound `TRP` inquiry upserts the initiating VASP (name, LEI, TRP endpoint) into the counterparty registry.
* An outbound `TRP` exchange records the counterparty identity and endpoint it verified during the handshake.
* An [after-deposit sunrise registration](#after-deposit-sunrise-registration) that names `originating_vasp` upserts that VASP, including its `travel_address` when supplied.
* Didit can catalogue a counterparty for you ahead of any exchange - routing identifiers, jurisdiction, and compliance contact - through support.

Entries are deduplicated by LEI first, then by exact name, and existing entries are enriched rather than duplicated when new identifiers arrive.

### Routing identifiers

A directory entry can carry one routing identifier per network.
Outbound routing consults them whenever your transfer names the counterparty by `counterparty_vasp_lei` or `counterparty_vasp_name`:

| Identifier on the entry | Used by rail |
| ----------------------- | ------------ |
| `trp_endpoint_url`      | `TRP`        |
| `gtr_vasp_code`         | `GTR`        |
| `trust_membership_id`   | `TRUST`      |
| `verifyvasp_id`         | `VERIFYVASP` |
| `sygna_vasp_code`       | `SYGNA`      |
| `compliance_email`      | `EMAIL`      |

You can always bypass the directory on a single transfer by passing the explicit fields in [Counterparty resolution fields](#counterparty-resolution-fields).

## Webhooks

Subscribe a destination to `travel_rule.status.updated` to get notified on every status transition, on both the outbound and any `INTERNAL`-rail inbound leg.

```json theme={null}
{
  "event_id": "9c0c8b8a-1111-4222-9333-666666666666",
  "webhook_type": "travel_rule.status.updated",
  "timestamp": 1774970000,
  "created_at": 1774970000,
  "application_id": "11111111-2222-3333-4444-555555555555",
  "environment": "live",
  "transaction_id": "22222222-3333-4444-5555-666666666666",
  "txn_id": "trv-2026-07-05-001",
  "travel_rule_status": "COMPLETED",
  "rail": "INTERNAL",
  "direction": "OUTBOUND"
}
```

See the [webhooks guide](/integration/webhooks#event-types) for the full event catalog, signature verification, and retry policy.

## Pricing

Outbound Travel Rule exchanges are billed **\$0.02 per transaction**, charged once at creation regardless of how many status transitions the exchange goes through afterward.

* The inbound leg Didit creates on the beneficiary's application via the `INTERNAL` rail is **not** billed.
* If crypto AML/wallet screening also runs on the same transaction (for example an inbound deposit with `currency_kind: "crypto"` and monitoring enabled), that's billed separately at the standard AML monitoring rate - it is not bundled into the Travel Rule fee.
* Travel Rule transactions use this dedicated line item instead of standard transaction-monitoring pricing, not both.

### Attribution pricing

[Blockchain analytics attribution](#blockchain-analytics-attribution) needs one wallet lookup against the analytics provider, and you always get the full value of that lookup:

* **Crypto monitoring already screened the wallet on this transaction** - the stored result is reused. One analytics call, one AML monitoring charge (the one crypto monitoring already made). Attribution adds nothing.
* **Crypto monitoring did not run** - Didit makes the required analytics call once and passes its full value on: the transaction is charged the standard crypto AML monitoring rate (\$0.15 with Didit-managed analytics) and receives the complete crypto screening output in return - risk score, wallet risk category, network snapshot - not just the VASP name. The usage line item is marked with the `travel_rule_attribution` trigger so the charge is explainable.
* **Bring-your-own analytics key** - the same platform fee that applies to crypto monitoring with your own key applies here (\$0.02 per call). Your provider bills you for the underlying lookup directly.
* **Failed lookups are never charged**, resends reuse the recorded attribution without a new call or charge, and sandbox applications are never charged.

So an outbound transfer that needed attribution costs \$0.02 (Travel Rule) + one crypto AML monitoring charge - and when both products are enabled, the analytics call and its charge happen only once.

## EU TFR rules bundle

Four preset rules ship in the `travel_rule_eu_tfr` bundle, purpose-built for EU TFR obligations.
Like every other [preset bundle](/transaction-monitoring/rules-library), enable it from the Business Console under **Transactions → Rules → Library**.

| Rule (`library_key`)                 | Trigger                                                                                       | Action                                      |
| ------------------------------------ | --------------------------------------------------------------------------------------------- | ------------------------------------------- |
| `tr_eu_mismatch_hold`                | Transfer status is `COUNTERPARTY_MISMATCHED_DATA`                                             | `+50` score, transaction set to `IN_REVIEW` |
| `tr_eu_unverified_selfhosted_review` | Transfer status is `UNCONFIRMED_OWNERSHIP` and the default-currency amount is at least `1000` | Transaction set to `IN_REVIEW`              |
| `tr_eu_vasp_not_found_score`         | Transfer status is `COUNTERPARTY_VASP_NOT_FOUND`                                              | `+25` score, tagged `travel-rule-sunrise`   |
| `tr_eu_expired_review`               | Transfer status is `EXPIRED`                                                                  | Transaction set to `IN_REVIEW`              |

These fire on every relevant transition - at transfer creation, on ownership confirmation, on email pickup response, and from the expiry sweeper - so a transfer that never resolves still surfaces for compliance review instead of settling silently.

## Why this works better on one platform

Travel Rule compliance is an identity problem wearing a payments costume - and Didit already holds the identity:

* **Verified data on the wire.** The originator information you transmit is the KYC profile Didit verified at onboarding (document OCR, liveness, face match) - bound by `vendor_data`, not retyped into a form. Standalone Travel Rule vendors transmit whatever you pass them.
* **Step-up biometrics for risky transfers.** A [rule](/transaction-monitoring/rules) can hold any high-value transfer until the user passes a biometric re-check against the face captured at onboarding - the strongest possible answer to account takeover at the moment of withdrawal. See the [worked example](/transaction-monitoring/sdk-transaction-submission#example-step-up-biometrics-for-a-high-value-withdrawal).
* **One device graph.** SDK-submitted transfers carry the same device intelligence as KYC sessions, so "new device + high amount + first-time beneficiary" is a single rule, not a data-warehouse join.
* **Screening, rules, cases, and the exchange in one place.** The wallet screening that attributes the counterparty VASP is the same screening your rules and analysts see - one charge, one console, one audit trail.
* **Published pricing.** [\$0.02 per outbound transfer](#pricing), no volume tiers, no sales call.

## FAQ

### How the exchange works

<AccordionGroup>
  <Accordion title="Does Didit run the VASP-to-VASP exchange itself, or does it only record Travel Rule data after another network completes the handshake?">
    Didit runs the exchange itself. When you submit a `travelRule` transfer, Didit performs live counterparty discovery, negotiates and verifies the originator and beneficiary data with the receiving VASP, and only clears the transfer once the exchange reaches `COMPLETED` - it is a managed handshake, not a post-settlement log. Didit also keeps the full record and compliance status of every exchange (a 13-state [lifecycle](#lifecycle), [webhooks](#webhooks), and an audit trail). If you prefer to run Travel Rule through your own process, Didit can instead record the data passively as your single system of record (see the passive-recording question below). Both modes are available; the active exchange is the default.
  </Accordion>

  <Accordion title="Is the exchange native to Didit, or does it depend on an external interoperability provider (Notabene, Sygna, VerifyVASP, TRP)?">
    It is native. Didit operates its own Travel Rule Protocol (TRP) infrastructure at `trp.didit.me` and implements the industry network protocols directly - `GTR` (Global Travel Rule), `TRUST`, `VerifyVASP`, and `Sygna Bridge` (spoken natively, including Sygna's ECIES-encrypted IVMS 101 and signed permission requests). Didit is not a reseller of a single third-party interoperability layer. Reaching a counterparty that lives on a specific membership network necessarily happens over that network - there is no single universal channel in the Travel Rule - but the discovery, handshake, verification, and recordkeeping are all executed by Didit.
  </Accordion>

  <Accordion title="Which Travel Rule networks and protocols does Didit support?">
    Natively implemented, tried in strict priority order: `INTERNAL` (both VASPs on Didit), `TRP` (OpenVASP Travel Rule Protocol), `GTR`, `TRUST`, `VerifyVASP`, `Sygna Bridge`, and an `EMAIL` fallback for counterparties with no tooling. CODE, TRISA, Notabene, and Veriscope are available on request through Didit's Marketplace. See [How Didit routes an exchange](/transaction-monitoring/travel-rule-interoperability#how-didit-routes-an-exchange) for the full routing table.
  </Accordion>

  <Accordion title="Which network should I use, and do I need my own memberships?">
    `TRP` is the universal baseline we recommend enabling: it needs no shared membership - publishing a [travel address](#travel-addresses) or TRP endpoint lets any Didit VASP reach you - and it is backed by [blockchain-analytics attribution](#blockchain-analytics-attribution) when a counterparty is known only by wallet address. For membership networks, choose by where your counterparties operate: GTR offers broad global coverage, TRUST is oriented to US VASPs, and VerifyVASP (which now also operates Sygna Bridge) has strong coverage in Asia. You can route over Didit's platform membership where available, or connect your own - both are supported, and you are not locked to a single network.
  </Accordion>

  <Accordion title="How does Didit find the counterparty VASP when I only have a wallet address?">
    Through a resolution chain: your [wallet address book](#wallet-address-book), then the protocol and network rails, then [blockchain-analytics attribution](#blockchain-analytics-attribution). If the transfer carries only a destination wallet, Didit resolves it against blockchain-analytics data to attribute the counterparty exchange or custody service, catalogues it in the [VASP directory](#directory), and routes automatically - so later transfers to that counterparty reach it directly.
  </Accordion>
</AccordionGroup>

### Pricing and licensing

<AccordionGroup>
  <Accordion title="How much does Travel Rule cost, and is it included in my KYC or verification plan?">
    Travel Rule is a separate, usage-based product. It is not bundled into identity verification. It costs \*\*$0.02 per outbound transfer** ([published pricing](#pricing), no volume tiers, no sales call). When routing needs a blockchain analytics lookup to identify the counterparty VASP, that lookup is charged once at the [attribution rate](#attribution-pricing): from $0.15 managed, or \$0.02 with an existing provider key. It is not billed again if crypto monitoring already screened the same wallet. Transfers below your threshold and the inbound legs Didit mints on the beneficiary side are not charged the Travel Rule fee.
  </Accordion>

  <Accordion title="Will I be double-charged when Travel Rule and crypto monitoring both run?">
    No. The Travel Rule fee (\$0.02, outbound only) replaces the standard transaction-screening fee for `travelRule` transactions, and the blockchain-analytics lookup is charged once: if crypto monitoring already screened the destination wallet on the transaction, [attribution](#blockchain-analytics-attribution) reuses that stored result at no extra cost. Inbound legs Didit mints on the beneficiary side are never billed the Travel Rule fee.
  </Accordion>

  <Accordion title="Can Didit provide documentation or a capability statement for my VASP licensing or regulator file?">
    Yes. Didit's KYT and transaction monitoring, AML and sanctions screening, blockchain-analytics wallet risk, and Travel Rule capabilities are all documented publicly on docs.didit.me, and you are free to cite these pages in a regulatory file. For a formal product capability statement tailored to a specific submission - for example an AIFC/AFSA, MiCA, or other VASP licensing application - contact your Didit account team with the format your regulator requires.
  </Accordion>
</AccordionGroup>

### Operations and data

<AccordionGroup>
  <Accordion title="What happens to transfers below my threshold?">
    They resolve immediately to `NOT_APPLICABLE`: no rail is tried, no identity data leaves Didit, and no Travel Rule fee is charged beyond the transfer's own creation. The EU TFR has no minimum, so EU CASPs should keep `threshold_amount` at `0.00`.
  </Accordion>

  <Accordion title="What if the counterparty never responds?">
    The transfer sits in `AWAITING_COUNTERPARTY` until `confirmation_timeout_hours` elapses, then a sweeper moves it to `EXPIRED` and applies your `timeout_outcome` to the underlying transaction - `HOLD` for review, `REJECT` to decline, or `PROCEED` to leave it untouched. The `tr_eu_expired_review` preset rule additionally surfaces every expiry to your analysts.
  </Accordion>

  <Accordion title="My counterparty has no Travel Rule tooling at all. Can I still comply?">
    Yes - that is the `EMAIL` rail. Their compliance contact receives a one-time pickup link and can confirm or decline the exchange from a hosted page with no Didit account, no API key, and no integration. For deposits that already settled before any exchange was possible, use [after-deposit sunrise registration](#after-deposit-sunrise-registration).
  </Accordion>

  <Accordion title="How do withdrawals to the user's own wallet work?">
    Declare the destination as self-hosted (`payment_method.method_type: "unhosted_wallet"`). Didit skips VASP routing and instead collects proof that your customer controls the wallet - message signing, Satoshi test, screenshot, or self-declaration - through the [wallet-ownership widget](/transaction-monitoring/wallet-ownership-widget). That is the EU TFR self-hosted wallet obligation in API form.
  </Accordion>

  <Accordion title="Is counterparty PII protected during the exchange?">
    Yes. Inbound transfers omit `originator_data`/`beneficiary_data` entirely until wallet ownership is confirmed on your side, email pickup pages show only the transfer summary (originator VASP name, amount, destination wallet) - never the person payloads - and rail exchanges run over authenticated HTTPS, with the Sygna rail additionally end-to-end encrypting the IVMS payload.
  </Accordion>

  <Accordion title="I already track Travel Rule compliance with my own process. Can I just record it?">
    Yes. With Travel Rule disabled, any `travel_rule_details` you submit (including a caller-supplied `status`, current or legacy) is recorded passively on the transaction - no rail is dispatched, nothing is negotiated. Use this to backfill or run your own process while keeping one system of record.
  </Accordion>

  <Accordion title="How do I test this before going live?">
    Sandbox applications skip rules, webhooks, and billing, and the exchange engine still runs - but sandbox never dispatches over a rail. So an **outbound** sandbox transfer parks at `AWAITING_COUNTERPARTY` instead of completing: use it to check that a transfer is created with the payload you expect. **Inbound** registration (`POST /v3/travel-rule/inbound/`) does not dispatch in the first place, so sandbox runs it for real against your wallet address book and you can exercise every outcome end to end - `ON_HOLD`, `UNCONFIRMED_OWNERSHIP`, `COUNTERPARTY_MISMATCHED_DATA`, or `COMPLETED` then `FINISHED`. For a full two-sided *outbound* loop, run it between two **live** applications on the `INTERNAL` rail: register a wallet in the second application's address book and watch both sides transition.
  </Accordion>
</AccordionGroup>

## Next steps

<CardGroup>
  <Card title="Wallet ownership widget" icon="wallet" href="/transaction-monitoring/wallet-ownership-widget">
    Prove a customer controls a wallet by signing, Satoshi test, screenshot, or self-declaration.
  </Card>

  <Card title="Interoperability" icon="handshake" href="/transaction-monitoring/travel-rule-interoperability">
    The counterparty-facing endpoints other VASPs use to reach you: TRP, callbacks, email pickup, sunrise.
  </Card>

  <Card title="Submitting transactions" icon="arrow-right-to-bracket" href="/transaction-monitoring/transactions">
    How to include travel rule data in the Create Transaction payload.
  </Card>

  <Card title="Rules library" icon="scale-balanced" href="/transaction-monitoring/rules-library">
    The full preset rule catalog, including the Travel Rule bundle.
  </Card>

  <Card title="Webhooks" icon="bell" href="/integration/webhooks">
    Subscribe to travel\_rule.status.updated and every other event family.
  </Card>

  <Card title="Console guide" icon="gauge" href="/transaction-monitoring/console">
    Viewing travel rule status in the transaction detail view.
  </Card>
</CardGroup>


# Travel Rule Interoperability
Source: https://docs.didit.me/transaction-monitoring/travel-rule-interoperability

The counterparty-facing side of Didit's Travel Rule: travel addresses, public TRP endpoints, callbacks, email pickup, and sunrise registration for VASPs exchanging with a Didit customer.

This page is for the **other side** of a [Didit Travel Rule](/transaction-monitoring/travel-rule) exchange: the counterparty VASP (or its engineering team) that needs to send Travel Rule data to, or receive it from, a VASP that runs on Didit.

Everything documented here is public infrastructure operated by Didit.
You do not need a Didit account, an API key, or any commercial relationship with Didit to interoperate - the deepest integration requires only HTTPS and JSON.

## How Didit routes an exchange

When a Didit customer sends a transfer, Didit tries these rails in strict priority order and uses the first one that can reach you:

| Priority | Rail         | What it means for you                                                                                                                                                                            |
| -------- | ------------ | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| 1        | `INTERNAL`   | Both VASPs run on Didit - the exchange settles inside the platform and no external call is made.                                                                                                 |
| 2        | `TRP`        | You expose a Travel Rule Protocol (TRP) endpoint, or the Didit customer knows your [travel address](#travel-addresses). Didit calls your TRP inquiry endpoint machine-to-machine.                |
| 3        | `GTR`        | A Global Travel Rule (GTR) membership is active for the sender and you are addressable by a GTR VASP code.                                                                                       |
| 4        | `TRUST`      | A TRUST membership is active for the sender and you are addressable by a TRUST membership id.                                                                                                    |
| 5        | `VERIFYVASP` | A VerifyVASP membership is active for the sender and you are addressable by a VerifyVASP id.                                                                                                     |
| 6        | `SYGNA`      | A Sygna Bridge membership is active for the sender and you are addressable by a Sygna VASP code. Didit speaks the Sygna protocol natively (ECIES-encrypted IVMS101, signed permission requests). |
| 7        | `EMAIL`      | No protocol channel is available - your compliance contact receives a one-time [email pickup link](#email-pickup) instead.                                                                       |

The network rails (`GTR`, `TRUST`, `VERIFYVASP`, `SYGNA`) run over a membership on the sending side - the Didit customer's own connected membership, or Didit's platform membership for that network when it is active.
GTR is not included by default. The same membership requirement applies to all four networks. The sender should check the `networks` object in [Get Travel Rule Settings](/management-api/travel-rule/get-settings): `didit` means platform membership is available for that application; `own` means a connected customer membership; `off` means platform routing is disabled; `unavailable` means neither membership is available. Enabling Travel Rule does not activate a network membership.

If you are on one of those networks, share your network identifier with the Didit customer and the exchange arrives over the network you already operate.
The fastest path with zero shared memberships is `TRP`: publish a travel address or TRP endpoint and every Didit VASP can reach you natively.

When none of the rails can identify you, Didit runs one more resolution step: **blockchain analytics attribution**.
The destination wallet is resolved against blockchain analytics data, and when it is attributed to your exchange or custody service, Didit records your name in its VASP directory and retries the rails with it.
This means you can be discovered and contacted even when the sender supplied nothing but a wallet address - and once your directory entry carries a travel address, network id, or compliance email, attributed transfers route to you automatically.
The full resolution chain is therefore: wallet address book, then the protocol and network rails, then blockchain analytics.

## Travel addresses

Every Didit VASP with Travel Rule enabled has a **travel address** - a compact string starting with `ta` that encodes the URL of its personal TRP transfer-inquiry endpoint.
Didit customers read theirs from their Travel Rule settings and share it with counterparties; when a Didit customer gives you theirs, you hold everything needed to reach them over TRP.

The encoding follows the TRP travel address convention:

* Strip the `ta` prefix.
* Base58Check-decode the remainder (Bitcoin alphabet, double-SHA256 checksum).
* The decoded bytes are the inquiry URL without its scheme; prepend `https://`.
* The URL always carries the query pair `t=i` (type: inquiry).

A decoded Didit travel address has this shape:

```
https://trp.didit.me/trp/inquiries/{profile_uuid}/?t=i
```

`{profile_uuid}` identifies the hosted VASP profile - POST your transfer inquiries to that URL, and query the matching [identity endpoint](#get-trpidentityprofile_uuid) to verify who you are talking to first.

## TRP endpoints

Didit speaks TRP API version `3.2.1` at the base URL `https://trp.didit.me`.
All endpoints exchange JSON over HTTPS.

| Method | Path                                   | Purpose                                                         |
| ------ | -------------------------------------- | --------------------------------------------------------------- |
| `GET`  | `/identity`                            | Platform-operator identity (also served at `/trp/identity`).    |
| `GET`  | `/trp/identity/{profile_uuid}/`        | Identity of one hosted VASP profile.                            |
| `POST` | `/trp/inquiries/{profile_uuid}/`       | Submit a transfer inquiry to a hosted VASP.                     |
| `POST` | `/trp/callbacks/resolution/{token}/`   | Resolve an inquiry that **Didit** sent you (approve or reject). |
| `POST` | `/trp/callbacks/confirmation/{token}/` | Confirm or cancel a transfer that Didit approved for you.       |

Two TRP headers matter:

* `api-version` - the TRP protocol version you speak, for example `3.2.1`. Required on inquiries.
* `request-identifier` - your unique id for the request, echoed back in the response headers. Required on inquiries.

Every response from Didit carries `api-version: 3.2.1` and echoes your `request-identifier`.

### GET /identity

Returns the platform operator's identity.
No headers are required.

```bash theme={null}
curl https://trp.didit.me/identity
```

```json theme={null}
{
  "name": "Didit",
  "lei": "",
  "x509": ""
}
```

### GET /trp/identity//

Returns the identity of the specific VASP you are about to exchange with - use it to verify the name and LEI before sending PII.
Didit performs the same check in reverse when it initiates: if the identity your endpoint reports does not match the expected LEI or name, the exchange is aborted.

```bash theme={null}
curl https://trp.didit.me/trp/identity/11111111-2222-3333-4444-555555555555/
```

```json theme={null}
{
  "name": "Bene CASP GmbH",
  "lei": "5493001KJTIIGC8Y1R12",
  "x509": ""
}
```

Returns `404` when the profile does not exist or its Travel Rule setup is disabled.

### POST /trp/inquiries//

Submit a transfer inquiry - you are the originator VASP, the Didit customer is the beneficiary VASP.

```bash theme={null}
curl -X POST https://trp.didit.me/trp/inquiries/11111111-2222-3333-4444-555555555555/ \
  -H "Content-Type: application/json" \
  -H "api-version: 3.2.1" \
  -H "request-identifier: 7f6a1c1e-0a63-4b1f-9f6e-7dcd7c3f1a01" \
  -d '{
    "asset": { "dti": "XB0MQJ1K5" },
    "amount": "250000000000000000",
    "callback": "https://trp.yourvasp.example/callbacks/inquiry/abc123",
    "IVMS101": {
      "Originator": { "...": "..." },
      "Beneficiary": { "...": "..." }
    }
  }'
```

| Field       | Type   | Description                                                                                   |
| ----------- | ------ | --------------------------------------------------------------------------------------------- |
| `asset.dti` | string | The Digital Token Identifier (ISO 24165) of the asset being transferred.                      |
| `amount`    | string | Integer amount in the asset's smallest unit (base units per the DTI's decimals).              |
| `callback`  | string | Absolute `https` URL on your side where Didit posts the inquiry resolution.                   |
| `IVMS101`   | object | The IVMS 101 payload carrying originator and beneficiary natural-person or legal-person data. |

Assets are identified by DTI on this rail; Didit maps `BTC` (`4H95J0R2X`) and `ETH` (`XB0MQJ1K5`) today, with further assets added over time.
An inquiry whose DTI Didit does not recognize is still accepted and surfaced to the beneficiary VASP with the DTI as the asset code.

A `200` response means the inquiry was accepted for processing; `400` means missing TRP headers or an invalid body, and `404` means the profile is unknown or disabled.
Re-sending the same `request-identifier` is idempotent - the original inquiry is reused instead of duplicated.

Didit then creates the inbound transfer on the customer's application and resolves it against the customer's wallet address book and policy.
The **resolution** arrives asynchronously as a POST to your `callback` URL with one of two bodies:

```json theme={null}
{
  "approved": {
    "address": "0xConfirmedDepositAddress",
    "callback": "https://trp.didit.me/trp/callbacks/confirmation/{token}/"
  }
}
```

```json theme={null}
{
  "rejected": "Transfer inquiry declined"
}
```

Approval can be automatic - when the beneficiary VASP enables auto-accept and the beneficiary matches a verified wallet entry - or follow a manual review or a wallet-ownership proof on the beneficiary side, so allow for delay between inquiry and resolution.

After you receive an approval and broadcast the transfer on-chain, close the exchange out by POSTing to the `approved.callback` URL you were given:

```bash theme={null}
curl -X POST "https://trp.didit.me/trp/callbacks/confirmation/{token}/" \
  -H "Content-Type: application/json" \
  -d '{ "txid": "0xchainhash" }'
```

Send `{ "canceled": "reason" }` to the same URL instead if you abort the transfer.
`txid` moves the beneficiary-side transfer to `FINISHED`; `canceled` moves it to `CANCELLED`.

### Resolving inquiries Didit sends you

When a Didit customer originates a transfer to you over TRP, Didit:

1. Fetches your `/identity` and verifies the reported name and LEI against what the customer expects.
2. POSTs a transfer inquiry to your inquiry URL with the same body shape as above - `asset.dti`, base-unit `amount`, a `callback`, and the `IVMS101` payload.

The `callback` in that inquiry points at Didit's resolution endpoint (`/trp/callbacks/resolution/{token}/`).
Respond by POSTing the same resolution bodies Didit uses: `{ "approved": { "address": "...", "callback": "..." } }` to approve (your `callback` is where Didit will post the on-chain confirmation), or `{ "rejected": "reason" }` to decline.

On approval the Didit side moves to `COMPLETED`; once the customer reports the on-chain hash, Didit POSTs `{ "txid": "..." }` to the confirmation callback you supplied (or `{ "canceled": "reason" }` if the transfer is cancelled first).

<Note>
  Callback tokens are single-purpose, unguessable secrets minted per transfer - treat the full callback URLs as confidential, and note that a resolution is only accepted while the transfer is still awaiting one.
</Note>

## Email pickup

If you expose no protocol channel at all, Didit falls back to email: your compliance contact receives a message naming the originator VASP with a one-time secure pickup link.
No account, API key, or integration is needed - the link token is the authentication.

Opening the link shows the pending exchange; the underlying API (which the hosted page drives for you) is public:

```bash theme={null}
curl https://verification.didit.me/v3/travel-rule/pickup/{token}/
```

```json theme={null}
{
  "originator_vasp_name": "Origin CASP SL",
  "amount": "1500.00",
  "currency": "EUR",
  "beneficiary_wallet": "bc1qexternalwallet01",
  "status": "AWAITING_COUNTERPARTY"
}
```

```bash theme={null}
curl -X POST https://verification.didit.me/v3/travel-rule/pickup/{token}/respond/ \
  -H "Content-Type: application/json" \
  -d '{ "decision": "accept", "beneficiary_name": "Carlos Ruiz" }'
```

`decision` is `accept` or `decline`; on accept, supply the beneficiary's name as your records hold it so the originator side can run its name match.
The link expires at the transfer's confirmation deadline - after that both endpoints return `410`.

## Sunrise: transfers that settled before the exchange

When a transfer reaches a Didit customer's wallet before any Travel Rule exchange took place - because no shared rail existed at the time - the data can still be delivered after settlement.

Send the Didit customer (your beneficiary counterparty) the Travel Rule payload through your normal channel and ask them to register it; they call [`POST /v3/travel-rule/inbound/`](/transaction-monitoring/travel-rule#after-deposit-sunrise-registration) with the deposit's chain, `txid`, wallet address, amount, and your originator data.
Include your VASP identity - name, LEI, and ideally your travel address - as `originating_vasp` in that payload: Didit then catalogues you in its [VASP directory](#getting-into-the-didit-vasp-directory), and every future exchange with any Didit VASP can reach you over TRP directly instead of email.

## Getting into the Didit VASP directory

Didit maintains a counterparty VASP registry that its customers' outbound routing consults.
There is no pre-seeded global list - entries are created and enriched from real activity:

* Your inbound TRP inquiries register your name, LEI, and TRP endpoint automatically.
* Outbound TRP exchanges to you record the identity and endpoint Didit verified.
* Sunrise registrations that name you as `originating_vasp` add your identity and travel address.
* Blockchain analytics attribution adds you when a destination wallet is resolved to your exchange or custody service - the entry starts with your attributed name and jurisdiction, and routes as soon as it is enriched with a channel.
* Didit can catalogue you proactively on request - routing identifiers, jurisdiction, and compliance contact.

An entry can carry one routing identifier per rail - `trp_endpoint_url`, `gtr_vasp_code`, `trust_membership_id`, `verifyvasp_id`, `sygna_vasp_code`, and a `compliance_email` for the email fallback.
The richer your entry, the more direct the rail Didit selects when one of its customers sends to you.
To add or correct your entry ahead of any traffic, ask the Didit customer you work with to raise it with Didit support.

## Checklist for counterparty VASPs

* **You run TRP already**: share your travel address (or TRP endpoint URL and LEI) with the Didit customer - exchanges arrive as standard TRP inquiries at your endpoint.
* **You are on GTR, TRUST, or VerifyVASP**: share your network identifier; exchanges arrive over that network whenever the Didit customer holds a membership there.
* **You have no protocol channel yet**: give the Didit customer a monitored compliance email - you will receive pickup links and can respond from the hosted page with zero integration.
* **A transfer already settled**: deliver the data via [sunrise registration](#sunrise-transfers-that-settled-before-the-exchange) through the Didit customer.
* **You also want to originate to Didit VASPs**: ask your counterparty for their travel address from their Didit Travel Rule settings, then follow [POST /trp/inquiries](#post-trpinquiriesprofile_uuid).

## Next steps

<CardGroup>
  <Card title="Travel Rule" icon="route" href="/transaction-monitoring/travel-rule">
    The customer-facing product: lifecycle, settings, rails, and the /v3/ API.
  </Card>

  <Card title="Wallet ownership widget" icon="wallet" href="/transaction-monitoring/wallet-ownership-widget">
    How beneficiary-side ownership proofs are collected when a wallet is self-hosted.
  </Card>

  <Card title="Sunrise registration" icon="sun" href="/transaction-monitoring/travel-rule#after-deposit-sunrise-registration">
    Registering Travel Rule data for deposits that already settled on-chain.
  </Card>

  <Card title="Webhooks" icon="bell" href="/integration/webhooks">
    How Didit customers observe every exchange transition on their side.
  </Card>
</CardGroup>


# Transaction Monitoring Troubleshooting
Source: https://docs.didit.me/transaction-monitoring/troubleshooting

Common KYT issues — txn_id collisions, rules not firing, AML timeouts, webhook signature mismatches, currency quirks — with causes and fixes.

A reference of common Transaction Monitoring issues, with symptom, cause, and fix.

## Duplicate `txn_id` error

**Symptom.** Submitting a transaction returns the existing record instead of an error — and your code doesn't realize it's a duplicate.

**Cause.** `txn_id` is unique per application. Re-submitting the same `txn_id` returns the existing transaction (idempotent).

**Fix.**

* Generate `txn_id` deterministically on your side (e.g. use your own transaction DB ID).
* Compare the response's `transaction_id` with what you expect; if the response's `created_at` doesn't match "now", you hit an existing record.

## Rule not firing

**Symptom.** You created a rule that should match, but no transactions are showing it in `rule_runs[]` with `matched: true`.

**Causes and fixes.**

* **The application is in sandbox mode** - a sandbox application stores the transaction row and nothing else: no rule evaluation, no AML screening, no webhooks, no billing. `rule_runs` comes back empty and the transaction stays `APPROVED` with score `0`, whatever mode your rules are in. Check `environment` on the transaction response: `"sandbox"` means it was never evaluated. See [Transaction Monitoring in sandbox](/integration/sandbox-testing#transaction-monitoring-in-sandbox) for how to validate a rule before it goes live.
* **Rule mode is `DISABLED` or `TEST`** — check *Rules → \[rule] → Mode*. Only `ACTIVE` rules contribute to scoring; `TEST` rules evaluate but don't affect status.
* **Scope filter excludes the transaction** — e.g. scope set to `transaction_type = finance` won't match `travelRule` transactions.
* **Aggregation window is shorter than needed** — a "20 transactions in 30 days" rule won't match after only 15 transactions.
* **Condition field is null** — e.g. your rule checks `counterparty.country_code` but you didn't send a counterparty.
* **Currency conversion** — the rule thresholds on `amount_in_default_currency`; if your application's default currency differs from the transaction currency, the converted amount may be below threshold.

Use the *Rules → \[rule] → Backtest* feature to replay a past transaction and see why the rule did / didn't fire.

## Rule firing on everything

**Symptom.** A rule fires on 90%+ of transactions — your review queue is flooded.

**Cause.** Conditions are too broad, or thresholds are too low.

**Fix.**

* Add `scope` filters to narrow applicability (e.g. only outbound, only certain transaction types).
* Raise thresholds (amounts, velocity counts).
* Put the rule in `TEST` mode for a week — analyze the `rule_runs` to see the match rate and tighten conditions before re-enabling.

## Crypto screening timed out

**Symptom.** Transaction completed with `status: APPROVED` but the `provider_results[]` array shows `status: FAILED` for a wallet, transaction hash, or crypto screening provider.

**Causes.**

* Provider API was briefly unavailable.
* Query timed out (typically \~10s).

**Fix.**

* Transactions never fail because of provider issues — enrichment is best-effort.
* If a specific provider fails repeatedly, check its status page or open a support ticket.
* Consider configuring provider preferences in *Settings → Transaction Monitoring → Providers* to route to alternative providers.

## IP enrichment missing

**Symptom.** A transaction's `applicant.ip_enrichment` is absent or partial.

**Causes.**

* No `applicant.device.ip` in the submission.
* IP is private / reserved (not routable).
* All enrichment providers were temporarily unavailable.

**Fix.**

* Capture the submitter's IP in your client/server and pass it on every transaction.
* Use only routable IPs — Didit silently skips private ranges.
* Check *Settings → Status* in the console for provider health.

## Webhook signature mismatch

**Symptom.** Your endpoint rejects events because the signature doesn't match.

**Causes.**

* Raw body was modified (JSON re-stringified with different whitespace).
* Wrong secret.
* Multiple destinations with the same URL — signatures differ per destination.

**Fix.**

* **Sign over the raw request body**, not the parsed JSON. Many frameworks expose a raw-body middleware.
* Rotate the secret if compromised: *Webhook destinations → \[destination] → Rotate secret*.
* Keep one destination per URL to avoid secret confusion.

## Webhook not arriving

**Symptom.** Transactions are being created but webhooks never arrive.

**Causes.**

* Destination `enabled` is `false`.
* URL not publicly reachable.
* Destination auto-disabled after repeated failures.
* Event not in `subscribed_events`.

**Fix.**

* Send a test event: *Webhook destinations → \[destination] → Send test*.
* Check recent deliveries: *Webhooks → \[destination] → Deliveries*. See 4xx/5xx responses with body/headers.
* Re-enable disabled destinations.

## Currency conversion looks wrong

**Symptom.** `amount_in_default_currency` doesn't match your expected rate.

**Causes.**

* FX rate is the mid-market rate at `txn_date`.
* Backdated transactions use the historical rate at that date.
* Some currencies (exotic FX) have coarser update intervals.

**Fix.**

* Use `amount` and `currency` (native) for display.
* Use `amount_in_default_currency` only for internal rule thresholding.
* For audit, the transaction record pins the conversion rate used at evaluation time.

## Counterparty not matching my blocklist

**Symptom.** You blocklisted a business by `vendor_data`, but a transaction with that counterparty still went through.

**Causes.**

* Counterparty in the transaction payload has no `vendor_data` — stored as external snapshot.
* `vendor_data` casing differs.

**Fix.**

* Always pass `counterparty.vendor_data` when the counterparty is an entity on your platform.
* Use the same casing everywhere — `vendor_data` is case-sensitive.

## AWAITING\_USER transactions stuck

**Symptom.** Transactions are stuck in `AWAITING_USER` because the user never completes the remediation session.

**Causes.**

* User didn't open the remediation session URL.
* Remediation session expired.

**Fix.**

* The transaction response's `remediation_session_url` is the link to deliver. Re-deliver to the user.
* Remediation sessions follow the same [KYC quickstart](/getting-started/quick-start) pattern — subscribe to completion webhooks.
* Set a timeout in your own system to expire stale transactions if remediation never completes.

## Rate limit on create

**Symptom.** `429 Too Many Requests` during high-volume bursts.

**Fix.**

* Respect the `Retry-After` header.
* Throttle client-side for burst traffic.
* Contact support for higher limits on proven production volume.

See [rate limiting](/integration/rate-limiting).

## Next steps

<CardGroup>
  <Card title="Integration guide" icon="book" href="/transaction-monitoring/integration-guide">
    Full integration patterns.
  </Card>

  <Card title="Rules" icon="scale-balanced" href="/transaction-monitoring/rules">
    How rule evaluation works.
  </Card>

  <Card title="Webhooks" icon="bolt" href="/transaction-monitoring/webhooks">
    Webhook mechanics.
  </Card>
</CardGroup>


# Wallet Ownership Widget
Source: https://docs.didit.me/transaction-monitoring/wallet-ownership-widget

Hosted widget that proves a customer controls a crypto wallet via message signing, Satoshi test, screenshot, or self-declaration - for the Travel Rule.

The wallet-ownership widget is a hosted page that proves one of your customers controls a specific crypto wallet address. Under the EU TFR, a VASP must verify ownership of a self-hosted (unhosted) wallet before releasing funds to or from it above the sunrise threshold - the widget is how Didit collects that proof without you building signing flows yourself.

A verified proof marks the matching [wallet address book entry](/transaction-monitoring/travel-rule#wallet-address-book) as `is_ownership_verified: true`, which lets a linked [Travel Rule transfer](/transaction-monitoring/travel-rule) advance out of `UNCONFIRMED_OWNERSHIP`.

## When Didit mints it for you

You rarely need to mint a session yourself.
When `auto_wallet_verification` is on in your [Travel Rule settings](/transaction-monitoring/travel-rule#setup) (the default), Didit auto-mints a widget session at transaction creation whenever a transfer needs end-user proof of wallet control:

* The transfer is in `UNCONFIRMED_OWNERSHIP` - the counterparty wallet was [declared self-hosted](/transaction-monitoring/travel-rule#declared-self-hosted-wallets) at submission, or an inbound transfer hit an unverified address-book entry.
* The transfer is outbound and in `COUNTERPARTY_VASP_NOT_FOUND` or `ON_HOLD` - no counterparty VASP could be reached, so ownership proof is the remaining path to completion.

The auto-minted session is returned in the transaction's `action_required` block (`type: "wallet_ownership"`, with the `url` to open), and the SDKs launch it automatically on [client-side submission](/transaction-monitoring/sdk-transaction-submission#required-user-actions).
Mint manually with `POST /v3/travel-rule/widget-session/` when you want to pre-verify a wallet before any transfer exists, or when you have `auto_wallet_verification` turned off.

## What it proves

The widget offers up to four proof methods. Which ones appear depends on how you minted the session and your [Travel Rule settings](/transaction-monitoring/travel-rule#setup):

| Method             | How it works                                                                                                                                                                                                                                                                                                                                                                                                                                                                                    | When it's offered                                              |
| ------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | -------------------------------------------------------------- |
| `MESSAGE_SIGNING`  | The customer signs a Didit-issued challenge string with their wallet. Supports EVM, Solana, Bitcoin, and Tron wallets; Didit verifies the signature against the address, and signing with a different account than the one being verified is rejected with a clear switch-accounts prompt. Installed browser wallets are discovered through the EIP-6963 and Wallet Standard protocols, so every extension appears as its own signing option, and mobile wallets connect through WalletConnect. | Always, for supported chain families.                          |
| `SATOSHI_TEST`     | The customer sends a tiny on-chain amount from the wallet to a deposit address you control; Didit's watcher confirms the sender, amount tolerance, and confirmation depth, then automatically completes the proof once the deposit confirms - see [Satoshi test verify contract](#satoshi-test-verify-contract) below.                                                                                                                                                                          | Only when you pass a `satoshi_deposit_address` at mint time.   |
| `SCREENSHOT`       | The customer uploads a screenshot of the wallet showing the address (JPEG/PNG/WebP, up to 10 MB). Unlike the other methods it never auto-verifies: your compliance team reviews it and confirms from the transaction's **Travel Rule** tab in the console, or via [`POST .../travel-rule/ownership/`](/management-api/travel-rule/confirm-ownership).                                                                                                                                           | Only when `allow_screenshot_proof` is `true` in your settings. |
| `SELF_DECLARATION` | The customer attests ownership without cryptographic proof - a last resort where the jurisdiction tolerates it.                                                                                                                                                                                                                                                                                                                                                                                 | Only when `allow_self_declaration` is `true` in your settings. |

### Satoshi test verify contract

Verifying a Satoshi test deposit is asynchronous, because the transaction has to be seen on-chain and then reach enough confirmations.
Submitting the deposit's `txid` returns `200` with `status: "PENDING"` the moment the deposit is seen on-chain but before it has enough confirmations - the `txid` is retained, not discarded.
It returns `200` with `status: "VERIFIED"` once the deposit confirms.
It returns `400` only for a genuinely wrong deposit: absent, sent from an unexpected address, or the wrong amount.
It returns `410` if the test window expires before a valid deposit is seen.

A background job automatically rechecks pending deposits and completes the proof the moment the transaction confirms, so the customer is never stranded after sending funds - they do not need to resubmit the `txid`.
When `SATOSHI_TEST` is offered, the widget session's own `expires_at` is extended to cover the Satoshi test window, giving the deposit time to confirm before the session itself expires.

## Flow

<Steps>
  <Step title="Mint a widget session">
    Call `POST /v3/travel-rule/widget-session/` with the wallet you need verified. Optionally link it to a transfer so the transfer advances automatically once ownership is proven.
  </Step>

  <Step title="Open the returned URL">
    Send your customer to the `url` from the response. They complete a proof there - no Didit account or API key needed; the token in the URL is the authentication.
  </Step>

  <Step title="Detect completion">
    When a proof is verified, the widget marks the address-book entry verified and, if the session is linked to a transfer, advances it. Watch for `travel_rule.status.updated` (linked transfers) or poll the widget context.
  </Step>
</Steps>

### Mint a widget session

```bash theme={null}
curl -X POST https://verification.didit.me/v3/travel-rule/widget-session/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "0xBeneficiaryWallet01",
    "chain": "ethereum",
    "holder_name": "Ana Diaz",
    "vendor_data": "user-042",
    "transaction_id": "22222222-3333-4444-5555-666666666666",
    "satoshi_deposit_address": "",
    "callback_url": "https://yourapp.example/wallet-verified",
    "expires_in_minutes": 60
  }'
```

| Field                     | Type          | Description                                                                                                                        |
| ------------------------- | ------------- | ---------------------------------------------------------------------------------------------------------------------------------- |
| `wallet_address`          | string        | The wallet address to verify.                                                                                                      |
| `chain`                   | string        | Chain identifier for the address (for example `ethereum`, `bitcoin`, `solana`).                                                    |
| `holder_name`             | string        | Name of the wallet holder, used for the beneficiary name match.                                                                    |
| `vendor_data`             | string        | Your internal identifier for the holder, carried onto the created address-book entry.                                              |
| `transaction_id`          | string (uuid) | Optional. Didit transaction UUID of a Travel Rule transfer to advance when the proof verifies. Omit to verify a wallet standalone. |
| `satoshi_deposit_address` | string        | Optional. A deposit address you control; supplying it enables the `SATOSHI_TEST` method.                                           |
| `callback_url`            | string        | Optional. Where the widget returns the customer after completion.                                                                  |
| `expires_in_minutes`      | integer       | Optional. Lifetime of the minted link; automatically extended to cover the Satoshi test window when `SATOSHI_TEST` is offered.     |

```json theme={null}
{
  "widget_session_id": "77777777-8888-9999-aaaa-bbbbbbbbbbbb",
  "token": "3s9x...urlsafe",
  "url": "https://verify.didit.me/wallet-ownership/3s9x...urlsafe",
  "expires_at": "2026-07-06T13:00:00Z"
}
```

Always open the `url` returned in the response verbatim - do not construct it yourself.

### Open the returned URL

<Warning>
  **The widget is web-only in this release. Open the `url` in the system browser or a custom tab - never inside a Didit mobile SDK webview.**

  Wallet proofs rely on deep links that hand off to the customer's wallet app (WalletConnect, Phantom, a Bitcoin wallet) and back. Those deep links **cannot escape an in-app webview**, so a widget opened inside the Didit Web/Flutter/React Native/iOS/Android SDK webview will dead-end when the wallet tries to return.

  On mobile, launch the `url` with the OS browser (`SFSafariViewController` / Chrome Custom Tabs, or the default browser) instead of rendering it in a webview. On web, a normal tab or popup is fine.
</Warning>

### Detect completion

The widget exposes a public read endpoint keyed by the token - poll it to see progress, or rely on webhooks when the session is linked to a transfer:

```bash theme={null}
curl https://verification.didit.me/v3/travel-rule/widget/{token}/
```

```json theme={null}
{
  "vasp_name": "Origin CASP SL",
  "wallet_address": "0xBeneficiaryWallet01",
  "chain": "ethereum",
  "holder_name": "Ana Diaz",
  "allowed_methods": ["MESSAGE_SIGNING", "SATOSHI_TEST", "SCREENSHOT"],
  "transfer_status": "UNCONFIRMED_OWNERSHIP",
  "callback_url": "https://yourapp.example/wallet-verified",
  "expires_at": "2026-07-06T14:00:00Z",
  "completed_at": null,
  "proofs": [
    {
      "proof_id": "88888888-9999-aaaa-bbbb-cccccccccccc",
      "method": "SATOSHI_TEST",
      "status": "PENDING",
      "wallet_address": "0xBeneficiaryWallet01",
      "chain": "ethereum",
      "deposit_address": "0xYourDepositWallet",
      "expected_amount": "0.00015",
      "expires_at": "2026-07-06T14:00:00Z",
      "created_at": "2026-07-06T13:05:00Z"
    }
  ]
}
```

* `completed_at` becomes non-null once a proof is verified.
* Each entry in `proofs` carries the fields its method needs: a `SATOSHI_TEST` proof adds `deposit_address`, `expected_amount`, and its own `expires_at`; a `MESSAGE_SIGNING` proof adds `challenge`, the string the customer signs.
* A `SATOSHI_TEST` proof can sit at `status: "PENDING"` while its deposit is seen on-chain but unconfirmed, with no action needed from you or the customer - see [Satoshi test verify contract](#satoshi-test-verify-contract) above.
* When the session was minted with a `transaction_id`, verifying the proof advances the linked transfer (out of `UNCONFIRMED_OWNERSHIP`, or resolving an inbound `TRP` transfer), and a [`travel_rule.status.updated`](/integration/webhooks#event-types) webhook fires. Prefer the webhook over polling.
* The context endpoint returns `404` for an unknown token and `410` once the session has expired without completing.

<Note>
  There are no one-shot dependencies here: the widget and your backend both converge on the same durable state (the verified address-book entry and the transfer status), so a dropped webhook or a closed tab is always recoverable by re-reading the transfer or the widget context.
</Note>

## Localization and branding

The widget renders in **54 languages**, following the language path of the link (or the browser default).

When whitelabel is enabled for your application, the widget inherits your verification-flow branding automatically: logo, brand colors, button and panel styling, custom font, favicon, and your app's public name in the title.
No separate configuration - the same customization you set up for KYC sessions applies here.

A user who returns to an already-completed link sees the completion screen again; if you passed a `callback_url`, the widget returns them there.
Expired links show a branded expiry screen prompting them to request a new link (mint a new session or use `action: "resend"` flows as appropriate).

## Next steps

<CardGroup>
  <Card title="Travel Rule" icon="route" href="/transaction-monitoring/travel-rule">
    The full exchange lifecycle, rails, settings, and receiving flows.
  </Card>

  <Card title="Wallet address book" icon="address-book" href="/transaction-monitoring/travel-rule#wallet-address-book">
    Register the wallets you control so inbound transfers resolve against them.
  </Card>

  <Card title="Webhooks" icon="bell" href="/integration/webhooks">
    Subscribe to travel\_rule.status.updated to react when a proof advances a transfer.
  </Card>

  <Card title="Native SDKs" icon="mobile" href="/integration/native-sdks/overview">
    Open the widget URL with the system browser, not the SDK webview.
  </Card>
</CardGroup>


# On-demand Wallet Screening
Source: https://docs.didit.me/transaction-monitoring/wallet-screening

Screen a single crypto wallet address for AML risk without creating a transaction. Source of funds, sanctions exposure, and risk score on demand.

Sometimes you need to check a crypto wallet's AML risk **before** there is any transaction to record — for example, when a customer adds a withdrawal address, or when your compliance team wants to vet an address ad hoc. The on-demand wallet screening endpoint screens a single address and returns the full risk result without creating a transaction.

This is the standalone counterpart to the [automatic crypto screening](/transaction-monitoring/aml-screening) that runs during [transaction submission](/transaction-monitoring/transactions). Both share the same blockchain analytics providers and the same result shape.

## When to use it

| Use case                                                 | Endpoint                                                                                  |
| -------------------------------------------------------- | ----------------------------------------------------------------------------------------- |
| Pre-check an address with no transaction to record       | **Wallet screening** — `POST /v3/wallet-screening/`                                       |
| Screen a wallet as part of a recorded deposit/withdrawal | [Create Transaction](/transaction-monitoring/transactions) with `currency_kind: "crypto"` |

Wallet screening writes nothing to the transactions table. If you need the screening attached to a monitored transaction (with rules, alerts, and webhooks), submit a transaction instead.

## Prerequisites

Transaction monitoring must be configured for the application with either a managed provider or an [existing provider key](/transaction-monitoring/aml-screening#supported-providers). Configure it in **Transactions** > **Settings** > **Provider Preferences** in the [Business Console](https://business.didit.me). If no provider is configured, the endpoint returns `409 Conflict`.

## Request

`POST https://verification.didit.me/v3/wallet-screening/`

Authenticate with the `x-api-key` header.

| Field            | Type   | Required | Description                                                                                                                                                                                                                                                      |
| ---------------- | ------ | -------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `wallet_address` | string | Yes      | The address to screen. Must match the format of the chosen chain (e.g. `0x` + 40 hex chars for EVM chains). Alias: `address`.                                                                                                                                    |
| `blockchain`     | string | Yes      | Asset / chain identifier: `BTC`, `ETH`, `LTC`, `XRP`, `BCH`, `DOGE`, `TRX`, `SOL`, `MATIC`, `BNB`, `USDT`, `USDC`. Alias: `currency`.                                                                                                                            |
| `direction`      | string | No       | `inbound`, `outbound`, `deposit`, or `withdrawal`. Optional context for the provider; omit for a neutral pre-transfer screen. It does not change the returned `risk_score`, `severity`, or the funds-flow breakdowns (see the note under [Response](#response)). |

```bash theme={null}
curl -X POST https://verification.didit.me/v3/wallet-screening/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "wallet_address": "0x28c6c06298d514db089934071355e5743bf21d60",
    "blockchain": "ETH"
  }'
```

## Response

The response is the standardised screening result — identical in shape to the `WALLET_SCREENING` provider result returned by transaction screening.

| Field                      | Type           | Description                                                                                                                                                |
| -------------------------- | -------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `provider`                 | string         | Provider that screened the address (`merklescience`, `crystal`, `chainalysis`, `elliptic`, `trmlabs`).                                                     |
| `screening_type`           | string         | Always `WALLET_SCREENING`.                                                                                                                                 |
| `risk_score`               | integer        | Normalised 0–100 risk score.                                                                                                                               |
| `severity`                 | string         | Risk bucket derived from `risk_score` (see note below): `UNKNOWN`, `LOW`, `MEDIUM`, `HIGH`, or `CRITICAL`.                                                 |
| `status`                   | string         | `SCREENED`, `PENDING`, or `ERROR`.                                                                                                                         |
| `summary`                  | string         | Human-readable summary.                                                                                                                                    |
| `wallet_address`           | string         | The screened address.                                                                                                                                      |
| `blockchain`               | string         | The screened chain.                                                                                                                                        |
| `sanctions_hit`            | boolean        | Direct or indirect sanctions exposure.                                                                                                                     |
| `dominant_risk_category`   | string \| null | Highest-weighted high-risk category, or `null`.                                                                                                            |
| `risk_factors`             | array          | Ranked explanation of `risk_score` — what produced this verdict. See [Risk factors](#risk-factors).                                                        |
| `source_of_funds`          | array          | Where funds were received from, by category.                                                                                                               |
| `destination_of_funds`     | array          | Where funds were sent to, by category.                                                                                                                     |
| `counterparty_connections` | array          | Direct/indirect counterparties with amounts and risk levels.                                                                                               |
| `report_signature`         | string         | Opaque signature over this result, scoped to your application. Repost the response unmodified, including this field, to [render it as a PDF](#pdf-report). |

<Note>
  **How `severity` is set.** `severity` is the band of the normalised `risk_score`: `0-9` → `UNKNOWN`, `10-39` → `LOW`, `40-69` → `MEDIUM`, `70-89` → `HIGH`, `90-100` → `CRITICAL`. `UNKNOWN` is the lowest band, not a separate "no data" state: `risk_score: 0` (the common clean-address case) means the provider returned no adverse assessment, while a non-zero score in the `1-9` range is a real but sub-`LOW` signal - so read the `risk_score` itself, not just the band. Either way, do not render `UNKNOWN` as an affirmative "clear" or pass.

  **`direction` does not change the risk model.** The optional `direction` field is passed to the provider as context only. It does not affect `risk_score`, `severity`, or which breakdown lists are returned: both `source_of_funds` and `destination_of_funds` are always returned regardless. Changing or omitting `direction` therefore does not require re-screening a previously screened address.
</Note>

### Risk factors

`risk_factors` is the ranked answer to "why is this address scored the way it is". Providers grade an address on their own model and return only a verdict — Merkle Science returns an integer `0-5` — so `risk_score` alone cannot be actioned. Each entry names one driver, ordered high-risk first and then by the value that moved through it.

| Field           | Type           | Description                                                                                                                                                                                                                                  |
| --------------- | -------------- | -------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `source`        | string         | `attribution` (what the provider says the address *is* — its own tag or cluster) or `exposure` (where its funds actually moved).                                                                                                             |
| `category`      | string         | Normalised risk category, same vocabulary as the exposure breakdown.                                                                                                                                                                         |
| `label`         | string         | The provider's own wording, e.g. `Gambling / Crypto only`. Use this in a UI — it matches what you would see in the provider's console.                                                                                                       |
| `entity_name`   | string \| null | Attributed entity, e.g. `Nitrogen Sports EU`.                                                                                                                                                                                                |
| `direction`     | string         | `incoming`, `outgoing`, `connected`, `attribution` (the address's own tag), or `unknown` when the provider did not report a direction.                                                                                                       |
| `exposure_type` | string         | `direct` (1 hop), `indirect` (multi-hop), `attribution` (the address's own tag), or `unknown` when the provider did not state how many hops away the counterparty is. Treat `unknown` as unclassified, never as `direct`.                    |
| `amount_usd`    | number \| null | USD value attributed to this driver.                                                                                                                                                                                                         |
| `percentage`    | number         | Share of the address's **total** screened volume, both directions combined — unlike `percentage` inside `source_of_funds` / `destination_of_funds`, which is normalised per direction. Comparable and summable across the whole list.        |
| `is_high_risk`  | boolean        | Whether the category is one Didit treats as high risk (`sanctioned`, `mixer`, `stolen_funds`, `ransomware`, `scam`, `darknet_market`, `terrorist_financing`, `child_exploitation`, `hacked_exchange`, `high_risk_exchange`, `seized_funds`). |
| `description`   | string         | One-line rendering of the driver, e.g. `9.01% indirect outgoing exposure to Gambling / Crypto only (Nitrogen Sports EU)`.                                                                                                                    |

<Note>
  **A high score with no `is_high_risk` factor is a real, meaningful outcome.** It means the provider graded the address on its own exposure model without reporting a sanctions, PEP or attributed-entity match — the factors that *are* listed are the fund flows behind the grade. `summary` states this explicitly, so treat these addresses as "review the flows", not as a confirmed hit. `risk_factors` is capped at the five strongest drivers; `source_of_funds` and `destination_of_funds` always carry the complete breakdown.

  **`risk_factors` is a top-level field, not a nested one.** Results screened before it existed omit the key entirely — read it as an empty list rather than assuming an empty explanation.
</Note>

Each entry in `source_of_funds` / `destination_of_funds` is an **exposure breakdown** with these fields:

| Field                | Type    | Description                                                                                                                |
| -------------------- | ------- | -------------------------------------------------------------------------------------------------------------------------- |
| `category`           | string  | Normalised risk category (`exchange_licensed`, `dex`, `defi`, `mixer`, `sanctioned`, `darknet_market`, `stolen_funds`, …). |
| `entity_name`        | string  | Attributed entity (e.g. `Binance.com`, `Tornado Cash`).                                                                    |
| `entity_type`        | string  | Provider entity type (`Exchange`, `Mixer`, `DeFi`, `Sanctions`).                                                           |
| `entity_subtype`     | string  | Granular subtype (`Mandatory KYC and AML`, `OFAC SDN`).                                                                    |
| `exposure_direction` | string  | `incoming`, `outgoing`, or `connected`.                                                                                    |
| `exposure_type`      | string  | `direct` (1 hop) or `indirect` (multi-hop).                                                                                |
| `amount_usd`         | number  | USD value attributed to the entity.                                                                                        |
| `percentage`         | number  | Share of the direction's total exposure (0–100).                                                                           |
| `hops`               | integer | Hops to the entity (0 for direct).                                                                                         |
| `country`            | string  | Primary ISO 3166-1 alpha-2 country of the entity.                                                                          |

```json theme={null}
{
  "provider": "merklescience",
  "screening_type": "WALLET_SCREENING",
  "risk_score": 72,
  "severity": "HIGH",
  "status": "SCREENED",
  "summary": "Merkle Science risk: High (4/5). SANCTIONS HIT. Dominant risk: mixer. Driven by: 38.6% indirect incoming exposure to Mixer / OFAC SDN (Tornado Cash); 61.4% direct incoming exposure to Exchange / Mandatory KYC and AML (Binance.com)",
  "wallet_address": "0x28c6c06298d514db089934071355e5743bf21d60",
  "blockchain": "ETH",
  "sanctions_hit": true,
  "dominant_risk_category": "mixer",
  "risk_factors": [
    {
      "source": "exposure",
      "category": "mixer",
      "label": "Mixer / OFAC SDN",
      "entity_name": "Tornado Cash",
      "direction": "incoming",
      "exposure_type": "indirect",
      "amount_usd": 11580.20,
      "percentage": 19.16,
      "is_high_risk": true,
      "description": "19.16% indirect incoming exposure to Mixer / OFAC SDN (Tornado Cash)"
    },
    {
      "source": "exposure",
      "category": "exchange_licensed",
      "label": "Exchange / Mandatory KYC and AML",
      "entity_name": "Coinbase",
      "direction": "outgoing",
      "exposure_type": "direct",
      "amount_usd": 30000.75,
      "percentage": 49.64,
      "is_high_risk": false,
      "description": "49.64% direct outgoing exposure to Exchange / Mandatory KYC and AML (Coinbase)"
    }
  ],
  "source_of_funds": [
    {
      "category": "exchange_licensed",
      "entity_name": "Binance.com",
      "entity_type": "Exchange",
      "entity_subtype": "Mandatory KYC and AML",
      "exposure_direction": "incoming",
      "exposure_type": "direct",
      "is_direct": true,
      "amount_usd": 18420.55,
      "percentage": 61.4,
      "hops": 0,
      "country": "SC"
    },
    {
      "category": "mixer",
      "entity_name": "Tornado Cash",
      "entity_type": "Mixer",
      "entity_subtype": "OFAC SDN",
      "exposure_direction": "incoming",
      "exposure_type": "indirect",
      "is_direct": false,
      "amount_usd": 11580.20,
      "percentage": 38.6,
      "hops": 2,
      "country": "RU"
    }
  ],
  "destination_of_funds": [
    {
      "category": "exchange_licensed",
      "entity_name": "Coinbase",
      "entity_type": "Exchange",
      "entity_subtype": "Mandatory KYC and AML",
      "exposure_direction": "outgoing",
      "exposure_type": "direct",
      "is_direct": true,
      "amount_usd": 30000.75,
      "percentage": 100.0,
      "hops": 0,
      "country": "US"
    }
  ],
  "counterparty_connections": [
    {
      "entity_name": "Tornado Cash",
      "entity_type": "Mixer",
      "entity_subtype": "OFAC SDN",
      "risk_level": "CRITICAL",
      "categories": ["mixer"],
      "received_usd": 11580.20,
      "sent_usd": 0.0,
      "received_hops": 2,
      "sent_hops": 0,
      "percentage": 38.6,
      "is_direct": false,
      "country": "RU"
    }
  ],
  "report_signature": "3f9c2e1a7b4d6f80c5e9a1b2d3f4e5061728394a5b6c7d8e9f0a1b2c3d4e5f6"
}
```

A clean address returns the same shape with `risk_score` near 0, `sanctions_hit: false`, `dominant_risk_category: null`, licensed-exchange-only entries, and `risk_factors` carrying no `is_high_risk` entry. See [Crypto & Wallet Screening](/transaction-monitoring/aml-screening#screening-results) for a full walkthrough of the risk categories, exposure table, and network graph.

## PDF report

To get a Didit-branded PDF of a screening result, repost the exact response body — including `report_signature` — to `POST /v3/wallet-screening/pdf/`. This is stateless: no provider call, no additional billing, nothing persisted. Editing any signed field (`risk_score`, `severity`, `sanctions_hit`, …) before reposting fails with `400`.

```bash theme={null}
RESULT=$(curl -s -X POST https://verification.didit.me/v3/wallet-screening/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{"wallet_address": "0x28c6c06298d514db089934071355e5743bf21d60", "blockchain": "ETH"}')

curl -X POST https://verification.didit.me/v3/wallet-screening/pdf/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d "$RESULT" \
  -o wallet_screening_report.pdf
```

See [Screen Wallet PDF](/management-api/transactions/screen-wallet-pdf) for the full request/response schema and error shapes.

## Billing

One AML monitoring usage is billed per successful screening at the same rate as transaction-coupled crypto screening. See [pricing](/transaction-monitoring/aml-screening#supported-providers) for managed and connected-key rates. Sandbox applications are not billed. Validation errors (`400`) and unconfigured-provider errors (`409`) are never billed.

## Errors

| Status | Meaning                                                                                  |
| ------ | ---------------------------------------------------------------------------------------- |
| `400`  | Malformed wallet address, missing `wallet_address`, or unsupported `blockchain`.         |
| `401`  | Missing or invalid `x-api-key`.                                                          |
| `409`  | No AML provider configured for the application — configure transaction monitoring first. |
| `502`  | The provider could not complete the screening; retry later.                              |

## Next steps

<CardGroup>
  <Card title="API reference" icon="code" href="/management-api/transactions/screen-wallet">
    Full request and response schema for the Screen Wallet endpoint.
  </Card>

  <Card title="Screen Wallet PDF" icon="file-pdf" href="/management-api/transactions/screen-wallet-pdf">
    Render a screening result as a Didit-branded PDF.
  </Card>

  <Card title="Crypto & wallet screening" icon="link" href="/transaction-monitoring/aml-screening">
    Automatic screening during transaction creation and the result model.
  </Card>
</CardGroup>


# Transaction Monitoring Webhooks
Source: https://docs.didit.me/transaction-monitoring/webhooks

Webhook events for transactions: triggers, payload shapes, and HMAC signature verification. Real-time delivery. Pay-per-call $0.02 per transaction.

Transaction Monitoring emits three webhook events that together cover the full transaction lifecycle. All ride on the standard Didit webhook infrastructure with HMAC-SHA256 signing - see the [webhooks reference](/integration/webhooks) for destinations, signing, and testing.

## Event catalog

| Event                        | When it fires                                                                                                                                                                                                                              |
| ---------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------ |
| `transaction.created`        | A new transaction was created and initial evaluation completed. Also fires for inbound transactions minted by an after-deposit [Travel Rule sunrise registration](/transaction-monitoring/travel-rule#after-deposit-sunrise-registration). |
| `transaction.status.updated` | The transaction's status changed - from analyst review, remediation session resolution, wallet-ownership completion, or a Travel Rule outcome applying your `timeout_outcome`.                                                             |
| `travel_rule.status.updated` | A [Travel Rule](/transaction-monitoring/travel-rule) exchange transitioned, on both the outbound and any `INTERNAL`-rail inbound leg.                                                                                                      |

Entity-level events (`user.status.updated`, `business.status.updated`) can also fire as a consequence of transaction activity - see [entity webhooks](/entities/webhooks).

<Note>
  Sandbox applications do not emit transaction or travel-rule webhooks - test deliveries against a live application, or use **API & Webhooks → Try Webhook** in the console.
</Note>

## Envelope

Didit webhooks use a **flat** body: the event fields sit at the top level next to the envelope fields - there is no nested `data` object.
Every delivery carries:

| Field                      | Description                                                                                   |
| -------------------------- | --------------------------------------------------------------------------------------------- |
| `webhook_type`             | The event name, e.g. `transaction.created`.                                                   |
| `event_id`                 | Stable identifier for the event - the same `event_id` is reused on retries, so de-dupe on it. |
| `timestamp` / `created_at` | Unix epoch seconds when the delivery was dispatched.                                          |
| `application_id`           | The application the event belongs to.                                                         |
| `environment`              | `live` or `sandbox`.                                                                          |

## Payload shapes

### `transaction.created` and `transaction.status.updated`

Both events share one payload - a compact summary plus the [`action_required`](/transaction-monitoring/sdk-transaction-submission#required-user-actions) block (or `null`):

```json theme={null}
{
  "webhook_type": "transaction.created",
  "event_id": "9c0c8b8a-1111-4222-9333-666666666666",
  "timestamp": 1774970000,
  "created_at": 1774970000,
  "application_id": "11111111-2222-3333-4444-555555555555",
  "environment": "live",
  "transaction_id": "9c7d2a30-...",
  "txn_id": "tx-0001",
  "status": "IN_REVIEW",
  "score": 65,
  "severity": "MEDIUM",
  "amount": "500.00",
  "currency": "EUR",
  "direction": "OUTBOUND",
  "action_required": null
}
```

The payload is deliberately thin: on receipt, fetch the full record with [`GET /v3/transactions/{transaction_id}/`](/management-api/transactions/get) - it returns the complete detail (parties, `rule_runs`, `provider_results`, `travel_rule`, `cost_breakdown`, `decision_reason_code`), including *why* the status changed.

### `travel_rule.status.updated`

```json theme={null}
{
  "webhook_type": "travel_rule.status.updated",
  "event_id": "9c0c8b8a-1111-4222-9333-777777777777",
  "timestamp": 1774970000,
  "created_at": 1774970000,
  "application_id": "11111111-2222-3333-4444-555555555555",
  "environment": "live",
  "transaction_id": "22222222-3333-4444-5555-666666666666",
  "txn_id": "trv-2026-07-05-001",
  "travel_rule_status": "COMPLETED",
  "rail": "INTERNAL",
  "direction": "OUTBOUND"
}
```

Fires on every non-terminal transition; once a transfer reaches `FINISHED`, `CANCELLED`, or `EXPIRED`, no further travel-rule events are sent for it.

## Example status journeys

### Simple approval

```
transaction.created (APPROVED, score 0)
```

### Review-then-approve

```
transaction.created (IN_REVIEW, score 65)
...analyst reviews...
transaction.status.updated (status: APPROVED)
```

### Step-up verification

```
transaction.created (AWAITING_USER, action_required.type: verification_session)
...user completes the biometric re-check...
transaction.status.updated (status: APPROVED, action_required: null)
```

### Travel Rule transfer

```
transaction.created (APPROVED)  +  travel_rule.status.updated (AWAITING_COUNTERPARTY, rail: EMAIL)
...counterparty accepts the pickup...
travel_rule.status.updated (COMPLETED)
...you broadcast on-chain and PATCH the hash...
travel_rule.status.updated (FINISHED)
```

## Signature verification

Every delivery is HMAC-SHA256 signed with the destination's shared secret and carries three signature headers plus a timestamp:

| Header               | Scheme                                                                                                                                                                                                                                                                                                                                                                      |
| -------------------- | --------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| `X-Signature-V2`     | HMAC over the canonical JSON (sorted keys, Unicode preserved) - **recommended**.                                                                                                                                                                                                                                                                                            |
| `X-Signature`        | HMAC over the ASCII-escaped canonical JSON (legacy).                                                                                                                                                                                                                                                                                                                        |
| `X-Signature-Simple` | HMAC over `"{timestamp}:{session_id}:{status}:{webhook_type}"` - **deprecated**. Transaction payloads carry no `session_id`, so this signs `"{timestamp}::{status}:{webhook_type}"`: it identifies neither the transaction nor its amount or score. Verify with `X-Signature-V2`, and see [the deprecation notice](/integration/webhooks#x-signature-simple-is-deprecated). |
| `X-Timestamp`        | Unix epoch seconds - reject deliveries older than 5 minutes.                                                                                                                                                                                                                                                                                                                |

```typescript theme={null}
import { createHmac, timingSafeEqual } from 'crypto';

function verify(rawBody: string, signatureV2: string, secret: string) {
  const canonical = JSON.stringify(
    Object.keys(JSON.parse(rawBody)).sort()
      .reduce((acc, k) => ({ ...acc, [k]: JSON.parse(rawBody)[k] }), {})
  );
  const expected = createHmac('sha256', secret).update(canonical).digest('hex');
  return timingSafeEqual(Buffer.from(signatureV2), Buffer.from(expected));
}
```

See the [webhooks reference](/integration/webhooks#signature-verification) for the full verification code, including the timestamp freshness check.

## Retries and delivery guarantees

* On a `5xx`, `404`, timeout, or connection failure, Didit retries up to **2 times**: roughly 1 minute after the initial failure, then roughly 4 more minutes after that.
* Retried deliveries reuse the same `event_id` - de-dupe on it in your handler.
* After the final failure, delivery for that event stops and your organization is notified; destinations are never silently disabled.
* Return a `2xx` fast (enqueue, then process) - slow ACKs risk timeouts and duplicate deliveries.

## Idempotency

Process each webhook exactly once by storing `event_id` in your own dedupe store. Re-delivery of the same event is possible when your endpoint ACKs slowly or disconnects mid-request.

## Subscribing

```bash theme={null}
curl -X POST https://verification.didit.me/v3/webhook/destinations/ \
  -H "x-api-key: YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "label": "TM events",
    "url": "https://yourapp.com/webhooks/didit-tm",
    "subscribed_events": [
      "transaction.created",
      "transaction.status.updated",
      "travel_rule.status.updated"
    ]
  }'
```

## Next steps

<CardGroup>
  <Card title="Webhooks reference" icon="bolt" href="/integration/webhooks">
    Destinations, signing, retries.
  </Card>

  <Card title="Statuses" icon="list-check" href="/transaction-monitoring/statuses">
    Full state machine.
  </Card>

  <Card title="Integration guide" icon="book" href="/transaction-monitoring/integration-guide">
    Handling webhooks in production.
  </Card>
</CardGroup>