Risk Assessment

Score verification sessions for fraud risk using iDenfy AI-powered risk assessment profiles with configurable rules and thresholds.

Requirements

• API key pair
• RA credits
• RA profile created via the dashboard

Learn More

Advanced Customer Risk Assessment Service — automate KYC, KYB, and AML risk assessments with customizable rules and weights.

---

How It Works

1. Create an RA profile in the dashboard — define sections, questions, and risk weights.
2. Retrieve the profile via API to get the section/question keys you need for requests.
3. Run an RA check by posting answers (keyed by section and question) against the profile.
4. Receive a risk score and level (VERY_LOW through VERY_HIGH) in the response.

Section and question keys (e.g., bXUsmLJeMI, lib-YHlTleSKmo) are dynamic — they are generated when you create your RA profile. Always retrieve the profile first to get the correct keys for your requests.

---

RA Profiles

Retrieve All RA Profiles

Authorization: API key pair Method: GET Endpoint: https://ivs.idenfy.com/risk/assessment-profiles/

Response example:

[
  {
    "id": "dd121b5c-e3ef-4197-b036-8b7e872f6678",
    "name": "RA profile name"
  }
]

Retrieve Specific RA Profile

Authorization: API key pair Method: GET Endpoint: https://ivs.idenfy.com/risk/assessment-profiles/{id}/

Request Parameter

Key	Required	Explanation	Type
id	Yes	A unique integer value identifying this risk assessment.	Integer

Response example:

{
  "id": "61fbe03e-961c-4c6f-a2cd-801083ddbe0d",
  "name": "Name",
  "description": "",
  "sections": [
    {
      "key": "bXUsmLJeMI",
      "name": "Category",
      "weight": 100,
      "questions": [
        {
          "choices": [
            { "key": "XOCgRfvUlu", "title": "Yes" },
            { "key": "QQALQApLKI", "title": "No" }
          ],
          "key": "lib-YHlTleSKmo",
          "name": "Is shareholder PEP?",
          "title": "Is shareholder PEP?",
          "type": "SELECT",
          "riskLevels": [],
          "riskLevelDefault": "LOW"
        },
        {
          "choices": [],
          "key": "lib-AEgWHKDkwF",
          "name": "Shareholder residency",
          "title": "Shareholder residency",
          "type": "COUNTRY",
          "riskLevels": [],
          "riskLevelDefault": "MEDIUM"
        }
      ]
    }
  ]
}

---

RA Check

Authorization: API key pair Method: POST Endpoint: https://ivs.idenfy.com/risk/assessment-profiles/{id}/check/

Request Parameters

Parameter	Location	Required	Type	Explanation
id	Path	Yes	String	The RA Profile ID for the assessment. Must be a legitimate ID retrieved from RA profiles.
sections	Body	Yes	Object	Object containing section keys and their corresponding values, filled according to the specific profile. Retrieve profile structure from RA profiles.
name	Body	Yes	String	Full name of the person that should be checked.

Request

{
  "sections": {
    "bXUsmLJeMI": {
      "lib-YHlTleSKmo": {
        "value": ["XOCgRfvUlu"]
      },
      "lib-AEgWHKDkwF": {
        "value": ["HU"]
      }
    }
  },
  "name": "Matthew Collins"
}

Response

{
  "id": "17CRlVRrxUa91BAMvMdeYP",
  "name": "Matthew Collins",
  "sections": [
    {
      "key": "bXUsmLJeMI",
      "name": "Category",
      "weight": 100,
      "questions": [
        {
          "key": "lib-YHlTleSKmo",
          "name": "Is shareholder PEP?",
          "type": "SELECT",
          "title": "Is shareholder PEP?",
          "choices": [
            { "key": "XOCgRfvUlu", "title": "Yes" },
            { "key": "QQALQApLKI", "title": "No" }
          ],
          "riskLevels": [],
          "riskLevelDefault": "LOW",
          "answers": [
            {
              "key": "XOCgRfvUlu",
              "answer": "Yes",
              "riskLevel": "LOW",
              "riskScore": 2
            }
          ]
        },
        {
          "key": "lib-AEgWHKDkwF",
          "name": "Shareholder residency",
          "type": "COUNTRY",
          "title": "Shareholder residency",
          "choices": [],
          "riskLevels": [],
          "riskLevelDefault": "MEDIUM",
          "answers": [
            {
              "key": "HU",
              "answer": null,
              "riskLevel": "MEDIUM",
              "riskScore": 3
            }
          ]
        }
      ],
      "riskScore": 5,
      "maxRiskScore": 5
    }
  ],
  "riskScore": 100,
  "riskLevel": "VERY_HIGH",
  "comment": null,
  "createdAt": "2024-05-16T08:57:04.654818Z",
  "updatedAt": "2024-05-16T08:57:04.654821Z",
  "updateRequired": false,
  "stateChangeEvent": "INITIAL",
  "companyId": null,
  "partner": {
    "id": 2253,
    "created": "2023-10-11T14:09:40.458303Z",
    "companyName": "Name Of Environment TESTING",
    "environment": "TESTING",
    "isActive": true
  },
  "profile": {
    "id": "61fbe03e-961c-4c6f-a2cd-801083ddbe0d",
    "name": "Name"
  },
  "riskLevelChangedBy": null
}

---

Retrieve RA Checks

Retrieve All RA Checks

Authorization: API key pair Method: GET Endpoint: https://ivs.idenfy.com/risk/assessments/

Response example:

{
  "count": 2,
  "next": null,
  "previous": null,
  "results": [
    {
      "id": "17CRlVRrxUa91BAMvMdeYP",
      "name": "Matthew Collins",
      "riskLevel": "VERY_HIGH",
      "createdAt": "2024-05-16T08:57:04.654818Z",
      "updateRequired": false
    },
    {
      "id": "F1WQIFa7EdHAvjanJ0pAKc",
      "name": "Sarah Robins",
      "riskLevel": "VERY_LOW",
      "createdAt": "2024-05-07T12:50:03.816388Z",
      "updateRequired": false
    }
  ]
}

Retrieve Specific RA Check

Authorization: API key pair Method: GET Endpoint: https://ivs.idenfy.com/risk/assessments/{id}/

Response example:

{
  "id": "Fi6cT2FO0AoDYyPljKhM41",
  "name": "Matthew Collins",
  "sections": [
    {
      "key": "OxTPlZAfHZ",
      "name": "Second category",
      "weight": 100,
      "questions": [
        {
          "key": "lib-NObsdcmGfe",
          "name": "Is shareholder PEP?",
          "type": "SELECT",
          "title": "Is shareholder PEP?",
          "choices": [
            { "key": "HAwWshlziF", "title": "Yes" },
            { "key": "WuZBsvsyWC", "title": "No" }
          ],
          "riskLevels": [],
          "riskLevelDefault": "HIGH",
          "answers": []
        },
        {
          "key": "lib-tRdubSLIVr",
          "name": "Country of Incorporation",
          "type": "COUNTRY",
          "title": "Country of Incorporation",
          "choices": [],
          "riskLevels": [],
          "riskLevelDefault": "LOW",
          "answers": []
        }
      ],
      "riskScore": 0,
      "maxRiskScore": 0
    }
  ],
  "riskScore": 0,
  "riskLevel": "VERY_LOW",
  "comment": null,
  "createdAt": "2024-05-06 09:45:02.405602+00:00",
  "updatedAt": "2024-05-06 09:45:02.405609+00:00",
  "updateRequired": false,
  "stateChangeEvent": "INITIAL",
  "companyId": null,
  "partner": {
    "id": 670,
    "created": "2022-08-08T06:37:32.765693Z",
    "companyName": "Mantas Tech",
    "environment": "DEVELOPMENT",
    "isActive": true
  },
  "profile": {
    "id": "dd121b5c-e3ef-4197-b036-8b7e872f6678",
    "name": "RA profile name"
  },
  "riskLevelChangedBy": null
}

---

Update Existing RA Check

Authorization: API key pair Method: POST Endpoint: https://ivs.idenfy.com/risk/assessments/{assessment-id}

Request Parameters

Parameter	Location	Required	Type	Explanation
assessment-id	Path	Yes	String	The ID of the RA check. Must be a legitimate ID received from retrieving all RA checks.
sections	Body	Yes	Object	Section keys from the questionnaire. Required if answers are being changed. Structure must follow the RA check request format.
name	Body	Yes	String	Full name of the person being checked. Required if the name is being changed. Structure must follow the RA check request format.

The request body (containing sections and name) is only needed if modifying existing answers or details.

Request

{
  "sections": {
    "bXUsmLJeMI": {
      "lib-YHlTleSKmo": {
        "value": ["QQALQApLKI"]
      },
      "lib-AEgWHKDkwF": {
        "value": ["EE"]
      }
    }
  },
  "name": "Matthew Collins"
}

Response

{
  "id": "17CRlVRrxUa91BAMvMdeYP",
  "name": "Matthew Collins",
  "sections": [
    {
      "key": "bXUsmLJeMI",
      "name": "Category",
      "weight": 100,
      "questions": [
        {
          "key": "lib-YHlTleSKmo",
          "name": "Is shareholder PEP?",
          "type": "SELECT",
          "title": "Is shareholder PEP?",
          "choices": [
            { "key": "XOCgRfvUlu", "title": "Yes" },
            { "key": "QQALQApLKI", "title": "No" }
          ],
          "riskLevels": [],
          "riskLevelDefault": "LOW",
          "answers": [
            {
              "key": "XOCgRfvUlu",
              "answer": "Yes",
              "riskLevel": "LOW",
              "riskScore": 2
            }
          ]
        },
        {
          "key": "lib-AEgWHKDkwF",
          "name": "Shareholder residency",
          "type": "COUNTRY",
          "title": "Shareholder residency",
          "choices": [],
          "riskLevels": [],
          "riskLevelDefault": "MEDIUM",
          "answers": [
            {
              "key": "HU",
              "answer": null,
              "riskLevel": "MEDIUM",
              "riskScore": 3
            }
          ]
        }
      ],
      "riskScore": 5,
      "maxRiskScore": 5
    }
  ],
  "riskScore": 100,
  "riskLevel": "VERY_HIGH",
  "comment": null,
  "createdAt": "2024-05-16 08:57:04.654818+00:00",
  "updatedAt": "2024-05-16 08:57:04.654821+00:00",
  "updateRequired": false,
  "stateChangeEvent": "INITIAL",
  "companyId": null,
  "partner": {
    "id": 2253,
    "created": "2023-10-11T14:09:40.458303Z",
    "companyName": "Name Of Environment TESTING",
    "environment": "TESTING",
    "isActive": true
  },
  "profile": {
    "id": "61fbe03e-961c-4c6f-a2cd-801083ddbe0d",
    "name": "Name"
  },
  "riskLevelChangedBy": null
}