> ## Documentation Index
> Fetch the complete documentation index at: https://docs.puplar.com/llms.txt
> Use this file to discover all available pages before exploring further.

# Introduction

> Overview of the Puplar Integrations API

## Base URL

All API requests are made to:

```
https://api.puplar.com
```

Business and live/test mode are inferred from your secret key (`sk_test_…` / `sk_live_…`).

## Amounts

Unless noted otherwise, monetary `amount` values are in **minor units** (kobo for `ngn`, cents for `usd`). Wallet and checkout currencies are `ngn` and `usd`. Crypto rails use token codes `usdc` and `usdt` (see [Payouts](/guides/payouts) and [Crypto](/guides/crypto)).

## Response format

Every success response follows the same envelope:

```json theme={"theme":{"light":"min-light","dark":"poimandres"}}
{
  "message": "Customer created",
  "data": { ... }
}
```

Validation failures return HTTP `422` with issues in `data`:

```json theme={"theme":{"light":"min-light","dark":"poimandres"}}
{
  "message": "Invalid email address",
  "data": [
    { "path": "email", "message": "Invalid email address", "location": "body" }
  ]
}
```

See the [Errors guide](/guides/errors) for full details.

## Pagination

Endpoints that return lists accept `page` and `limit` query parameters:

| Parameter | Default | Max   |
| --------- | ------- | ----- |
| `page`    | `1`     | —     |
| `limit`   | `20`    | `100` |

Example:

```
GET /customers?page=2&limit=50
```

## Error codes

| Status | Meaning                                                                          |
| ------ | -------------------------------------------------------------------------------- |
| `400`  | Business rule violation or bad request                                           |
| `401`  | Missing or invalid API key                                                       |
| `403`  | Forbidden — IP not whitelisted for this key                                      |
| `404`  | Resource not found                                                               |
| `409`  | Conflict — duplicate payout/payment `reference`, or a refund already in progress |
| `422`  | Schema validation failed                                                         |
| `429`  | Rate limit exceeded (100 req / 15 min per IP)                                    |
| `500`  | Internal server error                                                            |