> ## Documentation Index
> Fetch the complete documentation index at: https://documentation.idenfy.com/llms.txt
> Use this file to discover all available pages before exploring further.
# 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](/guides/dashboard/risk/how-to-setup-and-configure-risk-assessment)
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](/guides/dashboard/risk/how-to-setup-and-configure-risk-assessment) — 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:**
```json theme={"system"}
[
{
"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:**
```json theme={"system"}
{
"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](#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](#ra-profiles). |
| `name` | Body | Yes | String | Full name of the person that should be checked. |
```json theme={"system"}
{
"sections": {
"bXUsmLJeMI": {
"lib-YHlTleSKmo": {
"value": ["XOCgRfvUlu"]
},
"lib-AEgWHKDkwF": {
"value": ["HU"]
}
}
},
"name": "Matthew Collins"
}
```
```json theme={"system"}
{
"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:**
```json theme={"system"}
{
"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:**
```json theme={"system"}
{
"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](#retrieve-ra-checks). |
| `sections` | Body | Yes | Object | Section keys from the questionnaire. Required if answers are being changed. Structure must follow the [RA check request](#ra-check) 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](#ra-check) format. |
The request body (containing `sections` and `name`) is only needed if modifying existing answers or details.
```json theme={"system"}
{
"sections": {
"bXUsmLJeMI": {
"lib-YHlTleSKmo": {
"value": ["QQALQApLKI"]
},
"lib-AEgWHKDkwF": {
"value": ["EE"]
}
}
},
"name": "Matthew Collins"
}
```
```json theme={"system"}
{
"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
}
```