Context signals

Before you begin

Context signals evaluate completed credit transactions and return a risk assessment — self-fraud or social engineering — to enrich your own anti-fraud decision.

They are complementary to Card Not Present Verification: they do not change the contract or the behavior of the transaction endpoints you already use. You keep receiving the terminal state of the transaction (approved, inconclusive, and so on) as usual, and then query the context signals.

Your API requests are authenticated using an access token. Any request that does not include a valid access token will return an error. Learn more in Authentication.

Permission-controlled access

Access to this endpoint is controlled by a permission (role) assigned to your company. Without it, the endpoint returns 403. Request enablement from the Unico team.

Base URL

• UAT: https://transactions.transactional.uat.unico.app/api/public/v1
• Production: https://transactions.transactional.unico.app/api/public/v1

Get context signals

GET /transactions/{transaction_id}/signals — returns the risk assessment of a completed transaction.

The result is pre-computed asynchronously as soon as the transaction reaches its terminal state, so this endpoint is only a lookup of a result that is already available.

Path parameters

Parameter	Type	Required	Description
transaction_id	string	yes	Transaction ID (UUID v4). For example, 6ab1771e-dfab-4e47-8316-2452268e5481.

Headers

Header	Value
Authorization	Bearer {token} — a valid access token.
Accept	application/json

Request example

GET /api/public/v1/transactions/6ab1771e-dfab-4e47-8316-2452268e5481/signals HTTP/1.1
Host: transactions.transactional.uat.unico.app
Authorization: Bearer {token}
Accept: application/json

200 OK

{
  "signals": {
    "auto_fraud_risk": "high",
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

Field	Type	Presence	Description
signals.auto_fraud_risk	string (enum)	optional	Self-fraud risk level. Present only when detected.
signals.social_eng_risk	string (enum)	optional	Social engineering risk level. Present only when detected.
signals.more_info.limited_data	boolean	always	true when there is not enough data for a robust assessment.
signals.more_info.holder_identified	boolean	always	false when the cardholder could not be identified.

Possible risk values: very_low, low, medium, high, very_high.

info

auto_fraud_risk and social_eng_risk are mutually exclusive — they never appear together in the same response. When limited_data is true, both risk fields are expected to be absent, since there is not enough data for an assessment.

Response examples

Social engineering risk detected:

{
  "signals": {
    "social_eng_risk": "very_high",
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

No risk identified — a regular transaction:

{
  "signals": {
    "more_info": {
      "limited_data": false,
      "holder_identified": true
    }
  }
}

Not enough data:

{
  "signals": {
    "more_info": {
      "limited_data": true,
      "holder_identified": true
    }
  }
}

Cardholder not identified:

{
  "signals": {
    "more_info": {
      "limited_data": false,
      "holder_identified": false
    }
  }
}

Other response codes

Errors are returned in the standard error format described in Errors.

HTTP Code	Code	Situation	What to do
202	—	The result has not been computed yet — asynchronous processing is still in progress.	Repeat the call (polling) until you get a 200.
400	40004	transaction_id is invalid (not a UUID v4) or a parameter is malformed.	Fix the ID format before sending the request again.
403	40305	The company does not have the permission (role) enabled for this endpoint.	Request enablement from the Unico team.
404	40401	The transaction was not found.	Check the transaction ID.
404	40484	The transaction was not found for assessment.	Treat it as "there will be no result" and stop querying.
409	40983	The transaction has not reached its terminal state yet.	Wait for the terminal state before querying again.
500	—	Internal service error.	Retry with backoff. If it persists, contact Unico support.

Rules and best practices

• Query the endpoint only after the transaction reaches its terminal state. Querying earlier returns 409.
• Only credit transactions are assessed. Transactions captured in silent mode are not.
• On a 202, repeat the call until you get a 200. Send the first request 1 second after the transaction response, then back off: 2s, 4s, 8s, 16s — up to 5 attempts.
• The service level objective is 10 seconds after the transaction response.
• Treat a 404 as "there will be no result" and stop querying.
• auto_fraud_risk and social_eng_risk are mutually exclusive.