Skip to content
Asqary Docs

Score a transaction

POST
/v1/score
curl --request POST \
  --url https://api-staging.asqary.com/v1/score \
  --header 'Authorization: Bearer <token>' \
  --header 'Content-Type: application/json' \
  --data '{ "transaction": { "id": "example", "type": "loan_application", "amount": 1, "currency": "example", "occurred_at": "2026-04-15T12:00:00Z", "channel": "example" }, "customer": { "id_hash": "example", "bvn_hash": "example", "phone_hash": "example" }, "device": { "id_hash": "example", "platform": "example" }, "beneficiary": { "account_hash": "example", "bank_code": "example" }, "location": { "country": "example", "region": "example" }, "product": "example", "policy_version_id": "example" }'

Idempotent on transaction.id: repeating a transaction ID returns the original decision (200 with Idempotent-Replayed: true) without recording the transaction again. Requires the risk:query scope.

Authorizations

Section titled “Authorizations”

Parameters

Section titled “Parameters”

Header Parameters

Section titled “Header Parameters”
X-Request-Id
string
/^[A-Za-z0-9._:\-]{1,128}$/

Your own request ID (1–128 of letters, digits and . _ : -), echoed back and stored.

Request Bodyrequired

Section titled “Request Bodyrequired”
Media typeapplication/json
object
transaction
required
object
id
required

Your transaction ID; also the idempotency key.

string
/^[A-Za-z0-9._:\-]{1,128}$/
type
required
string
Allowed values: loan_application loan_disbursement repayment transfer withdrawal deposit card_payment bill_payment other
amount
required

Minor units (kobo for NGN).

integer
currency
required

Must match the policy’s market (NGN).

string
/^[A-Z]{3}$/
occurred_at
required

Not more than 5 minutes in the future.

string format: date-time
channel
string
/^[A-Za-z0-9 ._\-]{1,64}$/
customer
required
object
id_hash
required

HMAC-SHA256 of the identifier under your identifier key, lowercase hex.

string
/^[0-9a-f]{64}$/
bvn_hash

HMAC-SHA256 of the identifier under your identifier key, lowercase hex.

string
/^[0-9a-f]{64}$/
phone_hash

HMAC-SHA256 of the identifier under your identifier key, lowercase hex.

string
/^[0-9a-f]{64}$/
device
object
id_hash
required

HMAC-SHA256 of the identifier under your identifier key, lowercase hex.

string
/^[0-9a-f]{64}$/
platform
string
/^[A-Za-z0-9 ._\-]{1,64}$/
beneficiary
object
account_hash
required

HMAC-SHA256 of the identifier under your identifier key, lowercase hex.

string
/^[0-9a-f]{64}$/
bank_code
string
/^[A-Za-z0-9 ._\-]{1,64}$/
location
object
country
string
/^[A-Z]{2}$/
region
string
/^[A-Za-z0-9 ._\-]{1,64}$/
product
string
/^[a-z0-9_]{1,40}$/
policy_version_id

Test mode only. Score against this exact version.

string
/^plv_[0-9a-f]{32}$/

Responses

Section titled “Responses”

200

Section titled “200”

Replayed an earlier decision for this transaction ID

Media typeapplication/json
object
decision_id
required
string
/^dec_[0-9a-f]{32}$/
transaction_id
required
string
score
required
integer
<= 100
risk_level
required
string
Allowed values: low medium high critical
confidence
required
integer
<= 100
recommended_action
required
string
Allowed values: approve step_up manual_review block
reasons
required
Array<object>
object
code
required
string
contribution
required

Score points this rule added.

number
message
required
string
details
required
object
key
additional properties
any
policy
required
object
id
required
string
/^pol_[0-9a-f]{32}$/
version
required
integer
version_id
required
string
/^plv_[0-9a-f]{32}$/
environment
required
string
Allowed values: live test
engine_version
required
string
created_at
required
string format: date-time

Example 

{
  "risk_level": "low",
  "recommended_action": "approve",
  "environment": "live"
}

Headers

Section titled “Headers”
X-Request-Id
string

The request ID.

Idempotent-Replayed
string
Allowed values: true

Present (true) when an earlier result was returned.

201

Section titled “201”

Scored

Media typeapplication/json
object
decision_id
required
string
/^dec_[0-9a-f]{32}$/
transaction_id
required
string
score
required
integer
<= 100
risk_level
required
string
Allowed values: low medium high critical
confidence
required
integer
<= 100
recommended_action
required
string
Allowed values: approve step_up manual_review block
reasons
required
Array<object>
object
code
required
string
contribution
required

Score points this rule added.

number
message
required
string
details
required
object
key
additional properties
any
policy
required
object
id
required
string
/^pol_[0-9a-f]{32}$/
version
required
integer
version_id
required
string
/^plv_[0-9a-f]{32}$/
environment
required
string
Allowed values: live test
engine_version
required
string
created_at
required
string format: date-time

Example 

{
  "risk_level": "low",
  "recommended_action": "approve",
  "environment": "live"
}

Headers

Section titled “Headers”
X-Request-Id
string

The request ID.

400

Section titled “400”

Malformed request (invalid_request), including unknown fields.

Media typeapplication/json
object
error_code
required

Invalid_request, unauthorized, key_expired, key_revoked, forbidden, ip_not_allowed, quota_exceeded, not_found, method_not_allowed, conflict, policy_in_use, policy_active, policy_archived, idempotency_key_reused, validation_failed, rule_not_available, backtest_invalid_rows, backtest_too_large, rate_limited, internal_error

string
message
required
string
retryable
required
boolean
request_id
string
details
One of:
Array<object>
object
field
required
string
message
required
string
code
string

Example generated

{
  "error_code": "example",
  "message": "example",
  "retryable": true,
  "request_id": "example",
  "details": {}
}

401

Section titled “401”

Missing, invalid, expired or revoked API key.

Media typeapplication/json
object
error_code
required

Invalid_request, unauthorized, key_expired, key_revoked, forbidden, ip_not_allowed, quota_exceeded, not_found, method_not_allowed, conflict, policy_in_use, policy_active, policy_archived, idempotency_key_reused, validation_failed, rule_not_available, backtest_invalid_rows, backtest_too_large, rate_limited, internal_error

string
message
required
string
retryable
required
boolean
request_id
string
details
One of:
Array<object>
object
field
required
string
message
required
string
code
string

Example generated

{
  "error_code": "example",
  "message": "example",
  "retryable": true,
  "request_id": "example",
  "details": {}
}

403

Section titled “403”

Missing scope or role, IP not allowed, or monthly quota exceeded (quota_exceeded).

Media typeapplication/json
object
error_code
required

Invalid_request, unauthorized, key_expired, key_revoked, forbidden, ip_not_allowed, quota_exceeded, not_found, method_not_allowed, conflict, policy_in_use, policy_active, policy_archived, idempotency_key_reused, validation_failed, rule_not_available, backtest_invalid_rows, backtest_too_large, rate_limited, internal_error

string
message
required
string
retryable
required
boolean
request_id
string
details
One of:
Array<object>
object
field
required
string
message
required
string
code
string

Example generated

{
  "error_code": "example",
  "message": "example",
  "retryable": true,
  "request_id": "example",
  "details": {}
}

422

Section titled “422”

validation_failed (details: field errors), rule_not_available, or backtest_invalid_rows.

Media typeapplication/json
object
error_code
required

Invalid_request, unauthorized, key_expired, key_revoked, forbidden, ip_not_allowed, quota_exceeded, not_found, method_not_allowed, conflict, policy_in_use, policy_active, policy_archived, idempotency_key_reused, validation_failed, rule_not_available, backtest_invalid_rows, backtest_too_large, rate_limited, internal_error

string
message
required
string
retryable
required
boolean
request_id
string
details
One of:
Array<object>
object
field
required
string
message
required
string
code
string

Example generated

{
  "error_code": "example",
  "message": "example",
  "retryable": true,
  "request_id": "example",
  "details": {}
}

429

Section titled “429”

Too many requests (rate_limited); retry after Retry-After seconds.

Media typeapplication/json
object
error_code
required

Invalid_request, unauthorized, key_expired, key_revoked, forbidden, ip_not_allowed, quota_exceeded, not_found, method_not_allowed, conflict, policy_in_use, policy_active, policy_archived, idempotency_key_reused, validation_failed, rule_not_available, backtest_invalid_rows, backtest_too_large, rate_limited, internal_error

string
message
required
string
retryable
required
boolean
request_id
string
details
One of:
Array<object>
object
field
required
string
message
required
string
code
string

Example generated

{
  "error_code": "example",
  "message": "example",
  "retryable": true,
  "request_id": "example",
  "details": {}
}

Headers

Section titled “Headers”
Retry-After
integer

Seconds to wait before retrying.

500

Section titled “500”

Unexpected error (internal_error, retryable).

Media typeapplication/json
object
error_code
required

Invalid_request, unauthorized, key_expired, key_revoked, forbidden, ip_not_allowed, quota_exceeded, not_found, method_not_allowed, conflict, policy_in_use, policy_active, policy_archived, idempotency_key_reused, validation_failed, rule_not_available, backtest_invalid_rows, backtest_too_large, rate_limited, internal_error

string
message
required
string
retryable
required
boolean
request_id
string
details
One of:
Array<object>
object
field
required
string
message
required
string
code
string

Example generated

{
  "error_code": "example",
  "message": "example",
  "retryable": true,
  "request_id": "example",
  "details": {}
}