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](https://help.socure.com/riskos/docs/reason-codes).

| 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](https://help.socure.com/riskos/reference/reasoncodesendpoint).

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

```shell
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

```shell
# 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

```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.