Risk Assessments

Risk assessments are crucial for identifying and evaluating potential risks associated with customers or transactions. On this page, we’ll dive into the different risk assessment endpoints you can use to manage risk assessments programmatically. We'll look at how to query, create, update, and delete risk assessment records.

The risk assessment model

The risk assessment model contains all the information related to a risk assessment, including the assessment type, score, and details.

Properties

Name
id
Type
string
Description
Unique identifier for the risk assessment record.
Name
customer_id
Type
string
Description
Unique identifier for the customer.
Name
assessment_type
Type
string
Description
Type of risk assessment (e.g., credit risk, fraud risk).
Name
score
Type
number
Description
Risk score of the assessment.
Name
details
Type
object
Description
Details of the risk assessment.
Name
created_at
Type
timestamp
Description
Timestamp of when the risk assessment record was created.
Name
updated_at
Type
timestamp
Description
Timestamp of when the risk assessment record was last updated.

GET/v1/risk-assessments

List all risk assessments

This endpoint allows you to retrieve a paginated list of all your risk assessment records. By default, a maximum of ten records are shown per page.

Optional attributes

Name
limit
Type
integer
Description
Limit the number of risk assessment records returned.
Name
customer_id
Type
string
Description
Only show records for the specified customer.
Name
assessment_type
Type
string
Description
Only show records with the specified assessment type.

Request

GET

/v1/risk-assessments

curl -G https://api.finx.ai/v1/risk-assessments \
  -H "Authorization: Bearer {token}" \
  -d limit=10

Response

{
  "has_more": false,
  "data": [
    {
      "id": "xgQQXg3hrtjh7AvZ",
      "customer_id": "WAz8eIbvDR60rouK",
      "assessment_type": "credit risk",
      "score": 85,
      "details": {
        "credit_score": 720,
        "income": 75000
      },
      "created_at": 705103200,
      "updated_at": 705103200
    },
    {
      "id": "hSIhXBhNe8X1d8Et"
      // ...
    }
  ]
}

POST/v1/risk-assessments

Create a risk assessment

This endpoint allows you to add a new risk assessment record. You need to provide the customer ID, assessment type, score, and details to create a risk assessment record.

Required attributes

Name
customer_id
Type
string
Description
Unique identifier for the customer.
Name
assessment_type
Type
string
Description
Type of risk assessment (e.g., credit risk, fraud risk).
Name
score
Type
number
Description
Risk score of the assessment.
Name
details
Type
object
Description
Details of the risk assessment.

Request

POST

/v1/risk-assessments'

curl https://api.finx.ai/v1/risk-assessments \
  -H "Authorization: Bearer {token}" \
  -d 'customer_id'="WAz8eIbvDR60rouK" \
  -d 'assessment_type'="credit risk" \
  -d 'score'=85 \
  -d 'details'='{"credit_score": 720, "income": 75000}'

Response

{
  "id": "xgQQXg3hrtjh7AvZ",
  "customer_id": "WAz8eIbvDR60rouK",
  "assessment_type": "credit risk",
  "score": 85,
  "details": {
    "credit_score": 720,
    "income": 75000
  },
  "created_at": 705103200,
  "updated_at": 705103200
}

GET/v1/risk-assessments/:id

Retrieve a risk assessment

This endpoint allows you to retrieve a risk assessment record by providing the record id. Refer to the list at the top of this page to see which properties are included with risk assessment objects.

Request

GET

/v1/risk-assessments/xgQQXg3hrtjh7AvZ

curl https://api.finx.ai/v1/risk-assessments/xgQQXg3hrtjh7AvZ \
  -H "Authorization: Bearer {token}"

Response

{
  "id": "xgQQXg3hrtjh7AvZ",
  "customer_id": "WAz8eIbvDR60rouK",
  "assessment_type": "credit risk",
  "score": 85,
  "details": {
    "credit_score": 720,
    "income": 75000
  },
  "created_at": 705103200,
  "updated_at": 705103200
}

PUT/v1/risk-assessments/:id

Update a risk assessment

This endpoint allows you to perform an update on a risk assessment record. Examples of updates are changing the assessment type, updating the score, or modifying the details.

Optional attributes

Name
assessment_type
Type
string
Description
Updated type of risk assessment.
Name
score
Type
number
Description
Updated risk score of the assessment.
Name
details
Type
object
Description
Updated details of the risk assessment.

Request

PUT

/v1/risk-assessments/xgQQXg3hrtjh7AvZ

curl -X PUT https://api.finx.ai/v1/risk-assessments/xgQQXg3hrtjh7AvZ \
  -H "Authorization: Bearer {token}" \
  -d 'score'=90

Response

{
  "id": "xgQQXg3hrtjh7AvZ",
  "customer_id": "WAz8eIbvDR60rouK",
  "assessment_type": "credit risk",
  "score": 90,
  "details": {
    "credit_score": 720,
    "income": 75000
  },
  "created_at": 705103200,
  "updated_at": 705103200
}

DELETE/v1/risk-assessments/:id

Delete a risk assessment

This endpoint allows you to delete your risk assessment records in Fin X. Note: This will permanently delete the record and all its data — ensure this is the desired action before proceeding.

Request

DELETE

/v1/risk-assessments/xgQQXg3hrtjh7AvZ

curl -X DELETE https://api.finx.ai/v1/risk-assessments/xgQQXg3hrtjh7AvZ \
  -H "Authorization: Bearer {token}"