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

# API Overview

> Overview of the DHMAD API endpoints

The DHMAD API is a RESTful API that provides secure escrow services. All endpoints use JSON for request and response bodies.

## Base URL

All API requests should be made to:

* **Production**: `https://dhmad.tn/api/v1`
* **Sandbox** (for testing): `https://sandbox.dhmad.tn/api/v1` — use `sk_sandbox_` keys; see [Sandbox](/guides/sandbox)

## Authentication

All requests require authentication using an API key. You can use either:

* **Bearer Token**: `Authorization: Bearer sk_live_your_api_key_here`
* **X-API-Key Header**: `X-API-Key: sk_live_your_api_key_here`

See the [Authentication guide](/authentication) for more details.

<Warning>
  Most API operations require your developer account to be associated with a user account (e.g., checking balance, listing escrows, getting escrow details). The `GET /me` endpoint works without association. Creating escrows with `sellerEmail` also does not require association. You can associate your account in the [developer dashboard](https://developer.dhmad.tn/dashboard).
</Warning>

## Interactive API Explorer

We provide an **interactive API Explorer** (Swagger UI) in the [Developer Portal](https://developer.dhmad.tn/dashboard/api-explorer) where you can:

* Browse all available endpoints
* View request/response schemas
* Test API calls directly from your browser
* See example requests and responses (including **Quick Escrow with Proof** on `POST /v1/escrows`)
* Authenticate with your API key

<Info>
  Access the API Explorer from your [Developer Dashboard](https://developer.dhmad.tn/dashboard/api-explorer) after logging in. Click "Authorize" to add your API key and start testing endpoints.
</Info>

## Available Endpoints

### Account & Authentication

* `GET /me` - [Get API key information](/api-reference/payments) — verify your API key and get developer account details
* `GET /balance` - [Get user balance](/api-reference/ledger) — available, pending, and escrow balances

### Escrows

* **[Overview](/api-reference/escrows/overview)** — Introduction to escrows, [modes](/api-reference/escrows/overview#escrow-modes) (standard, quick, instant), [Quick Escrow with Proof](/guides/quick-escrow-with-proof), statuses, and lifecycle
* `POST /escrows` - [Create a new escrow](/api-reference/escrows/create-escrow)
* `GET /escrows` - [List escrows](/api-reference/escrows/list-escrows) (with pagination and filters)
* `GET /escrows/:id` - [Get escrow details](/api-reference/escrows/get-escrow)
* `GET /escrows/:id/proof` - [Get escrow proof](/api-reference/escrows/get-escrow-proof) — viewable proof URLs for Quick Escrow with Proof
* `GET /escrows/:id/contract` - [Get contract](/api-reference/escrows/get-contract) — retrieve contract details and PDF
* `PUT /escrows/:id` - [Update escrow](/api-reference/escrows/update-escrow) — update a pending escrow
* `POST /escrows/:id/deliver` - [Deliver escrow](/api-reference/escrows/deliver-escrow) — seller marks as delivered
* `POST /escrows/:id/reject-delivery` - [Reject delivery](/api-reference/escrows/reject-delivery-escrow) — buyer returns escrow to paid
* `POST /escrows/:id/cancel` - [Cancel escrow](/api-reference/escrows/cancel-escrow) — cancel a pending escrow

### Checkout Sessions

Checkout Sessions let you redirect users to dhmad.tn to perform critical escrow actions (sign contract, accept & pay, complete, dispute, cancellation). See the [Checkout Sessions Guide](/guides/checkout-sessions) for a full integration walkthrough.

* **[Overview](/api-reference/checkout-sessions/overview)** — How checkout sessions work, security, and supported actions
* `POST /escrows/:id/sessions` - [Create checkout session](/api-reference/checkout-sessions/create-session) — create a session and get a redirect URL
* `GET /sessions/:sessionId` - [Get checkout session](/api-reference/checkout-sessions/get-session) — verify session status after redirect

### Identity Verifications

Verify users through DHMAD **before** they have a dhmad.tn account. DHMAD emails the user a Didit KYC link (the URL is never returned to your API). When they later register with the same email, KYC links automatically. See the [KYC for marketplaces guide](/guides/kyc-for-marketplaces).

* **[Overview](/api-reference/identity-verifications/overview)** — Pre-account KYC flow, sandbox behavior, and constraints
* `POST /identity-verifications` - [Create verification](/api-reference/identity-verifications/create-verification) — start KYC and send invite email
* `GET /identity-verifications/:id` - [Get verification](/api-reference/identity-verifications/get-verification) — poll status
* `GET /identity-verifications?email=` - [List by email](/api-reference/identity-verifications/list-verifications)

<Warning>
  If you pass `redirect_url`, it must be in your **allowed redirect URLs** (Developer Dashboard → Settings). On **sandbox**, verifications auto-approve without Didit or email — production behavior differs.
</Warning>

### OAuth 2.0

OAuth endpoints for Single Sign-On (SSO) integration. See the [OAuth Setup Guide](/guides/oauth-setup) for implementation details.

* `GET /api/oauth/authorize` - [Authorization endpoint](/api-reference/oauth/authorize) — redirect users to authenticate
* `POST /api/oauth/token` - [Token endpoint](/api-reference/oauth/token) — exchange authorization code for tokens
* `GET /api/oauth/userinfo` - [UserInfo endpoint](/api-reference/oauth/userinfo) — get authenticated user profile

### Webhooks (Developer Portal Authentication)

These endpoints use developer JWT authentication (not API key). Manage them via the [Developer Dashboard](https://developer.dhmad.tn/dashboard) or the Developer Portal API. See the [Webhooks Guide](/guides/webhooks) for event payloads and signature verification.

* `POST /api/developer/webhooks` - [Create webhook](/api-reference/webhooks#create-webhook)
* `GET /api/developer/webhooks` - [List webhooks](/api-reference/webhooks#list-webhooks)
* `GET /api/developer/webhooks/:id` - [Get webhook](/api-reference/webhooks#get-webhook)
* `PUT /api/developer/webhooks/:id` - [Update webhook](/api-reference/webhooks#update-webhook)
* `POST /api/developer/webhooks/:id/regenerate-secret` - [Regenerate secret](/api-reference/webhooks#regenerate-secret)
* `DELETE /api/developer/webhooks/:id` - [Delete webhook](/api-reference/webhooks#delete-webhook)

## Response Format

All successful responses follow this format:

```json theme={null}
{
  "data": { ... }
}
```

Or for specific endpoints:

```json theme={null}
{
  "message": "Success message",
  "escrow": { ... },
  "url": "...",
  "trackingId": "..."
}
```

Error responses:

```json theme={null}
{
  "error": "Error type",
  "message": "Human-readable error description"
}
```

## Status Codes

* `200` - Success
* `201` - Created
* `400` - Bad Request
* `401` - Unauthorized
* `403` - Forbidden
* `404` - Not Found
* `429` - Too Many Requests
* `500` - Internal Server Error

## Rate Limiting

* **Default**: 100 requests per minute per IP address
* **Header**: Rate limit information is included in response headers
* **Exceeding**: Returns `429 Too Many Requests`

<Info>
  The default rate limit applies per IP address. Custom per-key rate limits can be configured when creating or updating an API key in the dashboard.
</Info>

## Pagination

List endpoints support pagination:

```
GET /escrows?page=1&limit=20
```

Response includes pagination metadata:

```json theme={null}
{
  "escrows": [ ... ],
  "pagination": {
    "page": 1,
    "limit": 20,
    "total": 100,
    "pages": 5
  }
}
```

## Escrow Modes

When creating an escrow, set `mode` to choose the transaction flow:

| Mode       | Use case                              | Contract | Completion                    |
| ---------- | ------------------------------------- | -------- | ----------------------------- |
| `standard` | Services, freelance work              | Yes      | Buyer confirms after delivery |
| `quick`    | Products between two users            | No       | Buyer confirms after delivery |
| `instant`  | In-app digital goods (you are seller) | No       | Auto-completes on deliver     |

See [Escrow Modes](/api-reference/escrows/overview#escrow-modes) for full details, required fields, and checkout actions per mode.

## Escrow Statuses

<CardGroup cols={2}>
  <Card title="pending" icon="clock">
    Escrow created, waiting for payment
  </Card>

  <Card title="paid" icon="check">
    Payment received, waiting for delivery
  </Card>

  <Card title="delivered" icon="truck">
    Service delivered, waiting for completion
  </Card>

  <Card title="completed" icon="circle-check">
    Transaction completed successfully
  </Card>

  <Card title="cancelled" icon="x">
    Escrow was cancelled
  </Card>
</CardGroup>

***

<Info>
  All timestamps are in ISO 8601 format (UTC). Example: `2024-01-15T10:30:00Z`
</Info>