List Reason Codes

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.

Property	Value
Method	`GET`
Path	`/api/reason-codes`
Authentication	`Authorization: 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.

Call the endpoint

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

Bash

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.

Parameter	Type	Repeatable	Description
`product`	string	Yes	Returns only codes for the named product. See the list of accepted values in the following section.
`name`	string	Yes	Returns only the codes whose name exactly matches the value.
`text`	string	No	Returns codes whose name or description contains the substring, case-insensitive. Useful for keyword search.
`isActive`	boolean	No	Set 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:

Bash

# 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:

JSON

{
  "reasonCodes": [
    {
      "name": "RXXXX",
      "provider": "Socure",
      "description": "Description of a risk signal.",
      "product": "Email Risk",
      "isActive": true,
      "releaseDate": "2024-03-15"
    }
  ]
}

Field	Type	Description
`name`	string	The reason code identifier.
`provider`	string	The provider that produces the code.
`description`	string	Human-readable explanation of the signal.
`product`	string	The product the code belongs to. Omitted when the code is not product-specific.
`isActive`	boolean	Whether the code is currently in use.
`releaseDate`	string	The date the code was released (`YYYY-MM-DD`), when available.
`deprecatedDate`	string	The date the code was deprecated (`YYYY-MM-DD`), when applicable.
`additionalNote`	string	Supplementary guidance for the code, when available.

Errors

Status	Meaning
`401 Unauthorized`	The API key is missing or invalid.
`500 Internal Server Error`	RiskOS™ 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.