User Guides
Home

List Reason Codes

Retrieve the RiskOS™ reason code catalog programmatically with the Reason Codes endpoint, including the available filters.

To pull the reason code catalog programmatically — for example, to cache descriptions in your own case management UI or keep an internal mapping in sync — call the Reason Codes endpoint instead of reading the Dashboard page manually. To interpret the codes once you have them, see Reason Codes & Score Interpretation.

PropertyValue
MethodGET
Path/api/reason-codes
AuthenticationAuthorization: Bearer YOUR_API_KEY

For the full request and response specification, see the Reason Codes API reference.


Test with Postman

Open the List Reason Codes request in Postman to explore the endpoint and send a sample request.

Run in Postman

Call the endpoint

Send a GET request with your environment-specific RiskOS™ API key in the Authorization header:

curl --request GET \
  --url https://riskos.socure.com/api/reason-codes \
  --header 'Authorization: Bearer YOUR_API_KEY'

Use the Sandbox host https://riskos.sandbox.socure.com while you integrate, and the Production host https://riskos.socure.com once you go live. Each environment requires its own API key.


Filter the catalog

By default, the endpoint returns every active reason code available to your account and excludes deprecated codes. Narrow the results with the following query parameters. You can combine parameters, and you can repeat product and name to match several values.

ParameterTypeRepeatableDescription
productstringYesReturns only codes for the named product. See the list of accepted values in the following section.
namestringYesReturns only the codes whose name exactly matches the value.
textstringNoReturns codes whose name or description contains the substring, case-insensitive. Useful for keyword search.
isActivebooleanNoSet to true to return only active codes, or false to include deprecated codes.

The product parameter accepts the following values:

  • Account Intelligence
  • Address Risk
  • Deceased Check
  • Device Risk
  • Email Risk
  • Global Watchlist Screening
  • Phone Risk
  • Predictive DocV
  • Sigma First-Party Fraud
  • Sigma Identity Fraud
  • Sigma Synthetic
  • Socure Verify (KYC)

Filter examples:

# All Email Risk codes
curl --url 'https://riskos.socure.com/api/reason-codes?product=Email%20Risk' \
  --header 'Authorization: Bearer YOUR_API_KEY'

# Two specific codes by name (repeat the name parameter)
curl --url 'https://riskos.socure.com/api/reason-codes?name=RXXXX&name=IXXXX' \
  --header 'Authorization: Bearer YOUR_API_KEY'

# Keyword search across names and descriptions
curl --url 'https://riskos.socure.com/api/reason-codes?text=address' \
  --header 'Authorization: Bearer YOUR_API_KEY'

Response

A successful request returns 200 OK with a reasonCodes array. Each entry describes one reason code:

{
  "reasonCodes": [
    {
      "name": "RXXXX",
      "provider": "Socure",
      "description": "Description of a risk signal.",
      "product": "Email Risk",
      "isActive": true,
      "releaseDate": "2024-03-15"
    }
  ]
}
FieldTypeDescription
namestringThe reason code identifier.
providerstringThe provider that produces the code.
descriptionstringHuman-readable explanation of the signal.
productstringThe product the code belongs to. Omitted when the code is not product-specific.
isActivebooleanWhether the code is currently in use.
releaseDatestringThe date the code was released (YYYY-MM-DD), when available.
deprecatedDatestringThe date the code was deprecated (YYYY-MM-DD), when applicable.
additionalNotestringSupplementary guidance for the code, when available.

Errors

StatusMeaning
401 UnauthorizedThe API key is missing or invalid.
500 Internal Server ErrorRiskOS™ couldn't retrieve the catalog. Retry, then contact Socure support if it persists.

The catalog changes infrequently. Cache the response and refresh it periodically rather than calling the endpoint on every transaction.


Related