---
title: Trigger IDV based on risk
slug: detected-apis/trigger-idv-based-on-risk
docTags: 
createdAt: 2026-08-14T13:12:18.174Z
---

# Overview

Your application creates an individual profile and screens that individual. Based on the results of the risk score returned your application triggers an IDV flow for the customer to complete.

# General Flow

- Existing system has core information about the individual to be verified
- Push the customers information to Detected over API
- Submit the profile to trigger screenings, analysis and automations
- Webhook notifies of completion
- Retrieve the risk score and based on that decide if IDV is required
- Trigger an email link to be sent to the individual from detected OR retrieve the link from detected and send to the customer
- Webhook fires to notify existing systems that submission is complete and ready for review

# Data Flow

```mermaid
---
config:
  theme: redux-dark
  look: classic
  layout: dagre
---
flowchart TD
    C1((("Customer"))) -- Completes information --> CS1["Client Systems"]
    CS1 -- "1.Push details to Detected APIs" --> API["Detected APIs"]
    API -- "2.Return results" --> Risk{"3.IDV required?"}
    Risk -- No --> Done["Continue onboarding"]
    Risk -- "4.Yes — email link to customer" --> C2((("Customer")))
    C2 -- "5.Customer opens link" --> Portal["Detected Verify (KYC) Portal"]
    Portal -- "6.Webhook: verification result" --> CS3["Client Systems"]
    classDef detected fill:#d3370c,stroke:#8f2408,color:#ffffff
    class API,Portal detected
```

# Integration view

Same flow with API endpoints and webhook events called from your stack.

```mermaid
---
config:
  theme: redux-dark
  look: classic
---
sequenceDiagram
  autonumber
  participant App as Your application
  box Detected
    participant API as Detected API v2
    participant V as Verify Portal
  end

  App->>API: POST /profiles (type: individual)
  API-->>App: profile uuid
  App->>API: POST /representatives (individual + declaratory)
  App->>API: POST /onboardings/{uuid}/submissions
  Note right of API: Screenings, risk score & actions

  API--)App: Webhook: profile.updated
  App->>API: GET /profiles/{uuid}/analysis
  API-->>App: analysis

  alt Not approved + manual invite
    App->>API: POST /representatives/{uuid}/login-links (purpose: verify)
    API-->>App: login link
    App->>V: Deliver link to representative
    V--)App: Webhook: verification.updated
    App->>API: GET /representatives/{uuid}/verifications
    API-->>App: verification result
  else Approved
    App->>App: Continue onboarding
  end
```

# Platform Setup Checklist

- [ ] Setup screenings settings for 'Person (individual entity)' (if required)
- [ ] Setup the required verification flows for the 'individual' role
- [ ] Check that the "Automatically set the profile status to ‘Needs Review’ for individual profile types on verify submission" setting is set to yes
- [ ] Setup a dedicated risk profile for individuals and assign that using actions
- [ ] Setup any actions to auto approve profiles based on risk
- [ ] Create your branding for the portals
- [ ] Configure the [Profile Webhook](docId:6qlwfWddkxPsSCj192LH-) 

# Common Questions

| **Question**                                                                                   | **Answer**                                                                                          |
| ---------------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------------------- |
| I get a 400 response with `error.onboarding_incompleted`<br />when calling the submissions API | The person used in `{ "representative_id": "…" }` must exist on the profile with type `declaratory` |