> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.shimi.cash/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.shimi.cash/_mcp/server.

# Quickstart

> **Note**
>
> Call the Shimi API from your **backend only**. Never put your API key or tokens in a browser or mobile app.

All requests go to:

```
https://shimi-waas-api-9493532b9281.herokuapp.com/api/v1
```

### Get an access token

Exchange your API key for an access token. Pass your company reference in the path and your API key in the `x-api-key` header.

```bash
curl -X POST "https://shimi-waas-api-9493532b9281.herokuapp.com/api/v1/auth/generate-token/YOUR_COMPANY_REFERENCE" \
  -H "x-api-key: YOUR_API_KEY"
```

```json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIs...",
  "refreshToken": "eyJhbGciOiJIUzI1NiIs..."
}
```

Store both tokens securely. Each call to this endpoint replaces your previous refresh token.

### Call the API with the token

Send the access token as a Bearer token on every other request. For example, to create a customer:

```bash
curl -X POST "https://shimi-waas-api-9493532b9281.herokuapp.com/api/v1/customer/" \
  -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "firstName": "Chiamaka",
    "lastName": "Okonkwo",
    "email": "chiamaka.okonkwo@example.com",
    "mobileNo": "+2348031234567",
    "bvn": "22345678901",
    "dob": "1992-03-14"
  }'
```

```json
{
  "status": "success",
  "message": "Customer created successfully",
  "data": {
    "id": "cmg8x2k4p0001qz7h3n9d5v2a",
    "firstName": "Chiamaka",
    "lastName": "Okonkwo"
  }
}
```

The customer receives an OTP on their BVN-linked phone. Pass it to **Generate Customer Account** to create their dedicated bank account.

### Refresh the token when it expires

Access tokens last **15 minutes**. When a request returns `403 Invalid or expired access token`, get a new one with your refresh token. No API key is needed.

```bash
curl -X POST "https://shimi-waas-api-9493532b9281.herokuapp.com/api/v1/auth/refresh-access-token/" \
  -H "Content-Type: application/json" \
  -d '{ "refreshToken": "YOUR_REFRESH_TOKEN" }'
```

```json
{
  "accessToken": "eyJhbGciOiJIUzI1NiIs..."
}
```

### Set up webhooks

Add your webhook URL in the Shimi dashboard (**Settings → Webhook**) so you're told about deposits and payout outcomes as they happen. See [Webhooks](/webhooks).

## Next steps

* Read [Access & KYB](/access-and-kyb) for the errors every authenticated call can return.
* Read [Responses & idempotency](/responses-and-idempotency) before you move money.
* Browse the [API reference](/api-reference).