> ## 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.

# Getting Started

> Step-by-step guide to start using the DHMAD API

This guide will walk you through setting up your developer account and making your first API call.

## Step 1: Create a Developer Account

1. Visit the [Developer Portal](https://developer.dhmad.tn/apply)
2. Fill out the application form with:
   * Company information
   * Contact details
   * Project description
   * Expected transaction volume
3. Submit your application

<Warning>
  Applications are reviewed by our team. You'll receive an email once your application is approved.
</Warning>

## Step 2: Set Up Your Account

Once approved, you'll receive an email with a setup link:

1. Click the setup link in your email
2. Create your developer account password
3. Choose a username
4. Complete your account setup

## Step 3: Associate User Account

To use the API, you need to associate your developer account with a user account:

1. Log into the [Developer Dashboard](https://developer.dhmad.tn/dashboard)
2. Click "Associate User Account"
3. Enter the email address of your DHMAD user account
4. Check your email and click the verification link
5. Your accounts are now associated

<Warning>
  The user account must have email verification completed before you can create escrows via the API. Phone verification is only required when the buyer accepts and pays, not at escrow creation.
</Warning>

<Info>
  The user account is used for creating escrows and managing transactions. Make sure you have a DHMAD user account before associating.
</Info>

## Step 4: Generate API Keys

1. Navigate to the [API Keys section](https://developer.dhmad.tn/dashboard) in your dashboard
2. Click "Create API Key"
3. Give your key a descriptive name (e.g., "Production App")
4. Copy your API key immediately - it won't be shown again!

<Warning>
  Keep your API keys secure! Never commit them to version control or share them publicly. Treat them like passwords.
</Warning>

## Step 5: Make Your First Request

Now you're ready to make your first API call. You can test endpoints in two ways:

### Option A: Use the Interactive API Explorer

The easiest way to test the API is using our **Interactive API Explorer** (Swagger UI):

1. Go to [API Explorer](https://developer.dhmad.tn/dashboard/api-explorer) in your dashboard
2. Click "Authorize" at the top
3. Enter your API key (use `Bearer {your_key}` format)
4. Browse and test any endpoint directly from your browser

<Info>
  The API Explorer automatically includes your API key in requests and shows you the exact request/response format for each endpoint.
</Info>

### Option B: Use cURL or Your HTTP Client

You can also make requests using cURL, Postman, or any HTTP client. Let's get your account balance:

```bash theme={null}
curl -X GET https://dhmad.tn/api/v1/balance \
  -H "Authorization: Bearer your_api_key_here" \
  -H "Content-Type: application/json"
```

<Info>
  **Testing first?** Use the [sandbox](/guides/sandbox): replace the URL with `https://sandbox.dhmad.tn/api/v1` and use a `sk_sandbox_` API key from [developer.dhmad.tn](https://developer.dhmad.tn) (sandbox keys are created in the same developer portal).
</Info>

<Accordion title="Response Example">
  ```json theme={null}
  {
    "balance": {
      "available": 0,
      "pending": 0,
      "escrow": 0
    }
  }
  ```
</Accordion>

## Step 6: Set Up Webhooks (Optional)

To receive real-time notifications when escrow status changes or identity verification completes:

1. Create a webhook endpoint in your application
2. Add the webhook URL in the [Developer Dashboard](https://developer.dhmad.tn/dashboard)
3. Verify webhook signatures for security

See the [Webhooks Guide](/guides/webhooks) for complete setup instructions.

## Verify users before DHMAD signup (Optional)

If your marketplace needs sellers verified before they create a dhmad.tn account, use the [Identity Verifications API](/guides/kyc-for-marketplaces). DHMAD emails the user a Didit link (never returned to your API) and links KYC when they register with the same email.

## Next Steps

* **[Authentication Guide](/authentication)** - Learn about API authentication
* **[Quickstart Tutorial](/quickstart)** - Build a complete example
* **[KYC for marketplaces](/guides/kyc-for-marketplaces)** - Verify users before DHMAD signup
* **[API Reference](/api-reference/overview)** - Explore all available endpoints
* **[Webhooks Guide](/guides/webhooks)** - Set up real-time notifications
* **[Best Practices](/guides/best-practices)** - Learn how to use the API effectively

***

<Note>
  You can authenticate using either `Authorization: Bearer` header or `X-API-Key` header. Both methods are supported.
</Note>