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

# Users

Manage your own account profile and security settings. Most teams interact with these endpoints rarely — they're mostly read-only.

## Endpoints

| Method  | Path                     | Purpose                |
| ------- | ------------------------ | ---------------------- |
| `GET`   | `/users/me`              | The current account    |
| `PATCH` | `/users/me`              | Update profile fields  |
| `GET`   | `/users/me/security`     | MFA status, last login |
| `POST`  | `/users/me/security/mfa` | Enroll MFA             |

## `GET /users/me`

```bash
curl -H "Authorization: Bearer API_KEY" \
     https://api.helodata.com/v1/users/me
```

Response:

```json
{
  "id":          "usr_01HX2K3PQ4M5",
  "email":       "you@example.com",
  "company":     "Acme Inc.",
  "plan":        "pro",
  "kyc_status":  "approved",
  "created_at":  "2026-01-15T10:00:00Z",
  "balance": {
    "currency": "USD",
    "amount":   125.40
  }
}
```

### Fields

| Field            | Type           | Description                                                     |
| ---------------- | -------------- | --------------------------------------------------------------- |
| `id`             | string         | Account ULID                                                    |
| `email`          | string         | Login email                                                     |
| `company`        | string \| null | Optional company name                                           |
| `plan`           | string         | One of `trial`, `pay-as-you-go`, `starter`, `pro`, `enterprise` |
| `kyc_status`     | string         | `not-submitted`, `pending`, `approved`, `rejected`              |
| `balance.amount` | number         | Prepaid credit in `balance.currency`                            |

## `PATCH /users/me`

Update profile fields (email change requires re-verification, handled in the dashboard):

```bash
curl -X PATCH -H "Authorization: Bearer API_KEY" \
     -H "Content-Type: application/json" \
     -d '{"company": "Acme Subsidiary"}' \
     https://api.helodata.com/v1/users/me
```

Editable fields: `company`, `billing_address`, `tax_id`, `default_currency`, `notification_email`.

## Security

```bash
curl -H "Authorization: Bearer API_KEY" \
     https://api.helodata.com/v1/users/me/security
```

Response:

```json
{
  "mfa_enabled":   true,
  "mfa_method":    "totp",
  "last_login_at": "2026-05-28T07:14:22Z",
  "last_login_ip": "203.0.113.5"
}
```

MFA enrollment via the API returns a TOTP secret + recovery codes:

```bash
curl -X POST -H "Authorization: Bearer API_KEY" \
     -d '{"method": "totp"}' \
     https://api.helodata.com/v1/users/me/security/mfa
```

Returned `secret` is what you put into your authenticator app. `recovery_codes` are one-shot fallbacks; store them offline.

## Errors

| Status | Code                      | Meaning                                         |
| ------ | ------------------------- | ----------------------------------------------- |
| `403`  | `mfa_required`            | The account requires MFA for this action        |
| `409`  | `email_in_use`            | Trying to change email to one already on file   |
| `422`  | `invalid_billing_address` | Address didn't pass tax-jurisdiction validation |