# Dashboard, alerts and reports

Three tools sit on top of your [letters of credit](13-letters-of-credit.md) and [guarantees](14-guarantees.md):

- **The dashboard** (overview): your open exposure in one currency, counts by type and stage, what's expiring and what's waiting for approval.
- **Lifecycle alerts:** emails before expiry dates and instalment due dates, so nothing lapses unnoticed.
- **Reports:** CSV extracts of the fields you choose, on demand or emailed on a schedule.

## Before you start

- **`MG_BASE_URL` and `MG_API_KEY`**, as in the [Quickstart](../01-get-started/03-quickstart.md).
- **The right permission.** The dashboard needs *view* (`trade-finance.view_records`), and only that one: an API user with *manage* or *approve* but not *view* can't read it. Alerts and reports need *manage* (`trade-finance.manage_records`), also for reading them.

## Dashboard

| Endpoint | Returns |
|---|---|
| [Get overview metrics](api:getTradeFinanceOverviewMetrics) | Eight figures: the total value of open instruments, open LCs and open guarantees (converted into one currency), the number of open instruments, LCs and guarantees, and the LCs and guarantees waiting for approval. |
| [Count instruments by type](api:getTradeFinanceInstrumentsByType) | The number of import LCs, export LCs, inward and outward guarantees. |
| [Get value by stage](api:getTradeFinanceValueByStage) | The number and converted value of instruments that are open, closed or cancelled. |
| [Count expiries by month](api:getTradeFinanceExpiryMonths) | Expiry dates (and import LC instalment dates) in each of the next 12 months. |
| [Count expiring instruments](api:getTradeFinanceExpiringCounts) | LCs and guarantees with a date falling in a window (by default the next 30 days). |
| [List pending approvals](api:listTradeFinancePendingApprovals) | The instruments waiting for an approver, with their key dates. |
| [Export the overview](api:exportTradeFinanceOverviewPdf) | The dashboard as a PDF. |

Every dashboard endpoint takes the same filters: instrument type, category (`letter_of_credit` or `guarantee`), direction, stage (`open`, `closed`, `cancelled`), currencies, a search text, an expiry window, and `displayCurrency` (the currency totals are converted into; `USD` by default).

- **Stage** groups statuses: *open* covers everything still live (draft, pending, applied, issued, advised, amendments, documents, partly settled, claims…), *closed* covers settled, discharged, claimed, expired and closed, and *cancelled* covers rejected and cancelled.
- **Conversion** uses mid-market rates refreshed every 5 minutes. If a rate isn't available, the value is `null` with `status: "unavailable"`; the rest of the response is still returned.
- **Freshness:** results are cached for 1 to 3 minutes, so a change can take that long to show.

:::warning
The expiry chart, the expiring counts and the pending approvals only look at the **500 most recent instruments of each type**. If you have more, older instruments are left out of those three; use the lists of each instrument type instead.
:::

## Lifecycle alerts

An alert emails reminders to the addresses you choose, a set number of days before a date on your instruments:

| Trigger | Instrument | Date | Days before |
|---|---|---|---|
| `payment_due` | Import LCs | Each instalment due date (`emi_eqi_due_date`) | 7, 3, 1 |
| `upcoming_expiry` | Import LCs | `latest_document_presentation_date` or `instrument_expiry_date` | 30, 14, 7, 3, 1 |
| `upcoming_expiry` | Export LCs | `latest_date_of_shipment` or `instrument_expiry_date` | 30, 14, 7, 3, 1 |
| `upcoming_expiry` | Inward guarantees | `instrument_expiry_date` | 30, 14, 7, 3, 1 |
| `upcoming_expiry` | Outward guarantees | `fixed_expiry_date`, `discharge_date` or `extension_expiry_date` | 30, 14, 7, 3, 1 |

[Create an alert](api:createTradeFinanceLifecycleAlert) with a name, the trigger, the instrument type, the date field, the days before (any of the allowed ones) and up to 50 recipients:

```bash
curl -s -X POST "$MG_BASE_URL/trade-finance-service/api/v1/alerts" \
  -H "mp-api-key: $MG_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Guarantee expiry",
    "trigger": "upcoming_expiry",
    "instrumentType": "inward_guarantee",
    "referenceField": "instrument_expiry_date",
    "frequencies": [30, 7, 1],
    "recipients": ["treasury@example.com"]
  }'
```

- Multigate checks your instruments every day at 00:05 UTC and sends each reminder once per recipient, with a link to the instrument in the dashboard. A new alert starts with the next day's check. Closed and cancelled instruments are skipped.
- If a check is missed (for example during maintenance), reminders from the last 7 days are sent late.
- [List your alerts](api:listTradeFinanceLifecycleAlerts) or [get one](api:getTradeFinanceLifecycleAlert). Alerts can't be changed or deleted through the API yet: ask Multigate to stop one.

## Reports

A report configuration names the instrument types and the fields to include. Use it to download a CSV whenever you need one, or have it emailed on a schedule.

<Steps>
<Step title="Choose the fields">

[Get the field catalogue](api:getTradeFinanceReportFieldCatalogue) for the instrument types you want. It lists every field you can report on, with its label.

</Step>
<Step title="Create the report">

[Create a report configuration](api:createTradeFinanceReportConfiguration) with a name, a description, the instrument types and, for each type, the fields. To email it on a schedule, add `schedule` (daily, weekly or monthly, at a time in your time zone) and up to 50 `recipients`.

</Step>
<Step title="Download it on demand">

[Generate the report](api:generateTradeFinanceReport) for a date range (instruments **created** in it) to download a CSV. It can include up to 10,000 rows; a larger range fails with `422`, an empty one with `404`.

</Step>
</Steps>

Scheduled reports cover **SWIFT activity** in the period (instruments whose bank messages changed), not creation dates, and are sent as one CSV attachment that combines every instrument type in the configuration (headers suffixed by type, as in an on-demand report with several types):

- **Daily:** Monday to Friday, covering the previous business day. Weekend activity isn't included in any daily report.
- **Weekly:** on the day you choose, covering the previous 7 days.
- **Monthly:** on the day you choose (1 to 28), covering the previous month.

A period with no activity sends no email. [List your reports](api:listTradeFinanceReportConfigurations) or [get one](api:getTradeFinanceReportConfiguration); like alerts, they can't be changed or deleted through the API yet.

:::caution
Reports can include account numbers, email addresses and phone numbers. Only add recipients who are allowed to see them, and choose the fields you really need.
:::

## Next steps

- [Trade finance](12-trade-finance.md): permissions and conventions.
- [Email notifications](../03-webhooks-and-emails/04-email-notifications.md#trade-finance).