# Sales Intervention reasons

This page describes the format of the `Reasons` and `PrimaryReason` fields in the PickUpAck messages of the [Sales Intervention trade model](fxapi-trade-model-salesintervention.md).

The `Reasons` and `PrimaryReason` fields describe the reasons why a deal requires manual intervention.

## FX Integration API builders

The FX Integration API provides the following builders for creating messages that use the `Reasons` and `PrimaryReason` fields:

| Message/Part | Type | Builder |
| --- | --- | --- |
| Intervention Trade Details Fields | Part | [`InterventionTradeDetailsFields.Builder`](https://docs.caplin.com/developer/api/fxintegration/latest/com/caplin/generated/motif/fx/tradedetails/TradeDetailsPartsDef.InterventionTradeDetailsFields.Builder.html) |
| PickUpAck | Message | [`SpotTradeDetails.Builder`](https://docs.caplin.com/developer/api/fxintegration/latest/com/caplin/generated/motif/fx/tradedetails/TradeDetailsTypesDef.SpotTradeDetails.html) |
| PickUpAck | Message | [`ForwardTradeDetails.Builder`](https://docs.caplin.com/developer/api/fxintegration/latest/com/caplin/generated/motif/fx/tradedetails/TradeDetailsTypesDef.ForwardTradeDetails.html) |
| PickUpAck | Message | [`SwapTradeDetails.Builder`](https://docs.caplin.com/developer/api/fxintegration/latest/com/caplin/generated/motif/fx/tradedetails/TradeDetailsTypesDef.SwapTradeDetails.Builder.html) |

## Field formats

Two fields describe Sales Intervention reasons:

**Sales Intervention fields**

| Field | Type | Format | Description |
| --- | --- | --- | --- |
| PrimaryReason | String | - | Text describing the main reason why a deal requires intervention. For display in blotters. Can be any text, but is conventionally populated with the same text from the `header` property of the first element of the JSON array in the `Reasons` field. |
| Reasons | String | JSON | Array of `Reason` objects (see below) that describe why a deal requires intervention. |

The Reasons field contains an array of `Reason` objects:

**Reason object**

| Property | Type | Mandatory | Description |
| --- | --- | --- | --- |
| header | String | No | Heading text |
| data | Array | Yes | Array of data objects |

<details>
<summary>Reason object example</summary>

```json
{
  "header": "Settlement cut-off exceeded",
  "data": [ ... ]
}
```
</details>

The `data` property of a `Reason` object contains an array of data objects:

**Reason data objects**

| Property | Type | Mandatory | Description |
| --- | --- | --- | --- |
| title | String | Yes | The message to be displayed or the label of the value (if a value is specified) |
| value | String | No | A value to be displayed to the right of the title. If left blank, the title takes up the whole row. |
| type | String | No | Type of the `value` property (if specified): 'NUMBER', 'DATE', 'CCY_AMOUNT', or blank. |
| level | String | No | The severity of the data: 'success', 'warning', 'error', or blank |
| ccy | String | No | The currency, if `type` is set to `CCY_AMOUNT` |

<details>
<summary>Data object example 1</summary>

```json
{
  "title": "The settlement cutoff for EURUSD is 4pm, but the request was received 5:22pm"
}
```
</details>

<details>
<summary>Data object example 2</summary>

```json
{
  "title": "Amount Exceeded By",
  "value": "100000",
  "type": "CCY_AMOUNT",
  "level": "error",
  "ccy": "EUR"
}
```
</details>

## Reasons field examples

**Example 1**

| Reasons field | Display |
| --- | --- |
```
[
  {
    "header": "Settlement cut-off exceeded",
    "data": [
      {
        "title": "The settlement cutoff for EURUSD is 4pm, but the request was received 5:22pm"
      }
    ]
  }
]
```
| [source,json] | **Settlement cut-off exceeded** The settlement cutoff for EURUSD is 4pm, but the request was received 5:22pm |

**Example 2**

| Reasons field | Display |
| --- | --- |
```
[
  {
    "header": "Credit Limit Exceeded",
    "data": [
      {
        "title": "Amount Exceeded By",
        "value": "100000",
        "type": "CCY_AMOUNT",
        "level": "error",
        "ccy": "EUR"
      },
      {
        "title": "Settlement Date",
        "value": "20/03/2019",
        "type": "DATE",
        "level": "",
        "ccy": ""
      },
      {
        "title": "Rejects in last 30 days",
        "value": "2",
        "type": "NUMBER",
        "level": "warning",
        "ccy": ""
      }
    ]
  }
]
```
| [source,json] | **Credit Limit Exceeded** !=== !Amount Exceeded By: !#100,000 EUR# !Settlement Date: !20/03/2019 !Rejects in last 30 days: !#2# !=== |