> For the complete documentation index, see [llms.txt](https://docs.stonemark.tech/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://docs.stonemark.tech/alfred-api.md).

# Alfred API

API reference for authentication, users, institutions, reports, accounts, and XML generation.

## Alfred API

Alfred is a FATCA and CRS reporting platform API.

This reference is based on the current OpenAPI spec.

### Common response patterns

#### Validation errors

Most invalid requests return `422 Unprocessable Entity`.

```json
{
  "detail": [
    {
      "loc": ["body", "email"],
      "msg": "Field required",
      "type": "missing"
    }
  ]
}
```

#### Pagination

Paginated routes return:

```json
{
  "items": [],
  "total": 0,
  "page": 1,
  "page_size": 50
}
```

### Core workflow

{% stepper %}
{% step %}

### Create or access an organisation

Register with `POST /auth/register`, or sign in with `POST /auth/login`.
{% endstep %}

{% step %}

### Create a financial institution

Add the reporting entity with `POST /financial-institutions`.
{% endstep %}

{% step %}

### Create a report

Create a `FATCA`, `CRS`, or `CARF` report with `POST /reports`.
{% endstep %}

{% step %}

### Import account data

Preview the CSV, map columns, then import the data into the report.
{% endstep %}

{% step %}

### Validate and generate XML

Run `/validate`, then call `/generate` when the report is ready.
{% endstep %}
{% endstepper %}