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

# API Overview

> Base URL, authentication, endpoint index, and fundamentals for the MasterID Public API v1.

The MasterID Public API v1 lets you submit identity verifications, check wallet balances, request mobile money collections, and receive event webhooks. Every request is authenticated, scoped to your workspace, and returns a consistent JSON envelope.

## Base URL

```text theme={null}
https://masterid.me/api/public/v1
```

All requests require HTTPS. Unauthenticated browser visits return service information only. They never expose workspace data.

## Authentication

Send your API credentials on every request using these headers.

**X-API-Key** `string` *required*

Your workspace API key, generated in the Developer Console.

**X-API-Secret** `string` *required*

Your workspace API secret, shown once when credentials are generated.

**Content-Type** `string` *required*

Must be `application/json` for requests with a body.

> [!WARNING]
>
> Keep credentials in your server's secret store. Never include them in browser JavaScript, public repositories, URLs, analytics, or application logs. Secrets cannot be recovered after their first display is closed.

Your Merchant ID does not authenticate requests. It is used only for payment collections after merchant activation.

## Endpoint index

| Method | Endpoint | Description |
| - | - | - |
| GET | [GET /catalog](https://docs.masterid.co.ug/api-reference/catalog/get-catalog.md) | List supported products, required fields, selections, and prices. |
| GET | [GET /wallet](https://docs.masterid.co.ug/api-reference/wallet/get-wallet.md) | Read your workspace wallet balance. |
| POST | POST /verifications/consent | Request exact consent wording before submitting a verification. |
| POST | POST /verifications | Submit a verification with confirmed consent. |
| GET | GET /verifications/{sessionId} | Retrieve the status and result of a verification. |
| POST | POST /collections | Request a mobile money payment collection. |
| GET | GET /collections/{reference} | Read the status of a collection. |

## Response envelope

All authenticated responses are JSON and follow one of two envelopes.

### Success

```json theme={null}
{
  "id": "<REQUEST_ID>",
  "data": { }
}
```

The `id` field is the API request ID. The `data` object contains endpoint-specific fields.

### Error

```json theme={null}
{
  "id": "<REQUEST_ID>",
  "error": "Error description"
}
```

Errors may omit the `id` when the request cannot be processed. For details on handling errors, see [Errors](https://docs.masterid.co.ug/concepts/errors.md). For common HTTP status meanings, see [Responses](https://docs.masterid.co.ug/concepts/responses.md).

## Status codes

| Code | Meaning |
| - | - |
| 200 | Completed request. |
| 202 | Accepted or pending. The operation is in progress. |
| 400 | Invalid input, consent, or idempotency header. |
| 401 | Missing, invalid, or revoked credentials. |
| 403 | Suspended account or Merchant ID mismatch. |
| 404 | Unknown operation or resource outside your workspace. |
| 409 | Idempotency conflict. |
| 413 | Request body too large. |
| 422 | Insufficient funds, merchant activation required, or other validation failure. |
| 429 | API rate limit reached. |
| 500 / 503 | Temporary processing error or unavailability. |

## Rate limits

Your workspace is limited to **60 authenticated API requests per minute**. When you receive a `429` response, wait for the `Retry-After` header before retrying.

Payment collections have additional limits:

* 40 per workspace per hour
* 200 per workspace per day
* 3 per phone number per 15 minutes
* 8 per phone number per workspace per day
* 10 per phone number across MasterID per day

These are MasterID limits, not a guarantee of throughput.

For idempotency behaviour and how to safely retry requests, see [Idempotency](https://docs.masterid.co.ug/concepts/idempotency.md). For webhook handling, see [Webhooks](https://docs.masterid.co.ug/guides/webhooks.md).


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.