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

# Quickstart

> Make your first IBAN verification in 5 minutes

# Quickstart Guide

All API requests are made to:

```text theme={null}
https://api.ibantrack.com/api-v1
```

This guide walks you through making your first IBAN holder verification request.

<Steps>
  <Step title="Get API Credentials">
    Log in to your Ibantrack Dashboard and retrieve your credentials under **Settings > API**.

    * **Client ID**
    * **Client Secret**

    <Note>
      You must have **Administrator privileges** to view and copy these credentials.

      Your Client ID & Secret carry significant privileges. Please keep them secure and do not share them.
    </Note>
  </Step>

  <Step title="Obtain Access Token">
    ```bash theme={null}
    curl -X POST https://api.ibantrack.com/api-v1/oauth2/token \
         -H "Content-Type: application/x-www-form-urlencoded" \
         -d "grant_type=client_credentials" \
         -d "client_id=YOUR_CLIENT_ID" \
         -d "client_secret=YOUR_CLIENT_SECRET"
    ```

    Response:

    ```json theme={null}
    {
      "access_token": "eyJhbGciOiJIUzI1NiItOvR5cCI6IkpXVCJ9...",
      "token_type": "Bearer",
      "expires_in": 3600
    }
    ```

    <Note>
      Tokens expire after 1 hour. Cache and reuse tokens until expiration.
    </Note>

    Once you have obtained an access token, include it in the `Authorization` header of every API request.

    For detailed token management, see [Authentication ](/api-reference/authentication/get-token).
  </Step>

  <Step title="Make Your First Verification">
    ```bash theme={null}
    curl -X POST https://api.ibantrack.com/api-v1/account-holder-verifications \
         -H "Authorization: Bearer YOUR_ACCESS_TOKEN" \
         -H "Content-Type: application/json" \
         -d '{
           "account": {
             "iban": "FR7630004000031234567890143"
           },
           "account_holder": {
             "name": "Jean Dupont"
           }
         }'
    ```

    Successful response:

    ```json theme={null}
    {
      "id": "abc123ab-3171-4e97-92ec-a11e9fabc123",
      "status": "completed",
      "match_result": "match"
    }
    ```

    In addition to account holder verification, Ibantrack may provide optional enrichment data derived from the submitted IBAN (Currently available only for French IBANs. \
    See [Enrichment](/documentation/core-concepts/enrichment).
  </Step>

  <Step title="Interpret the Result">
    The `match_result` tells you if the name matches:

    | Result        | Meaning                                 |
    | ------------- | --------------------------------------- |
    | `match`       | ✅ Name matches bank records             |
    | `close_match` | ⚠️ Similar name (review `matched_name`) |
    | `no_match`    | ❌ Name doesn't match                    |

    See [Match Results](/documentation/core-concepts/match-results) for details.
  </Step>
</Steps>

***

## Quick Example

<CodeGroup>
  ```bash cURL theme={null}
  # 1. Get access token
  curl -X POST https://api.ibantrack.com/api-v1/oauth2/token \
    -d "grant_type=client_credentials" \
    -d "client_id=YOUR_CLIENT_ID" \
    -d "client_secret=YOUR_CLIENT_SECRET"

  # 2. Verify account holder
  curl -X POST https://api.ibantrack.com/api-v1/account-holder-verifications \
    -H "Authorization: Bearer YOUR_TOKEN" \
    -H "Content-Type: application/json" \
    -d '{
      "account": {"iban": "FR7630004000031234567890143"},
      "account_holder": {"name": "Jean Dupont"}
    }'
  ```

  ```javascript Node.js theme={null}
  const response = await fetch('https://api.ibantrack.com/api-v1/account-holder-verifications', {
    method: 'POST',
    headers: {
      'Authorization': `Bearer ${token}`,
      'Content-Type': 'application/json'
    },
    body: JSON.stringify({
      account: { iban: 'FR7630004000031234567890143' },
      account_holder: { name: 'Jean Dupont' }
    })
  });

  const verification = await response.json();
  console.log(verification.match_result); // "match"
  ```

  ```python Python theme={null}
  response = requests.post(
      'https://api.ibantrack.com/api-v1/account-holder-verifications',
      headers={
          'Authorization': f'Bearer {token}',
          'Content-Type': 'application/json'
      },
      json={
          'account': {'iban': 'FR7630004000031234567890143'},
          'account_holder': {'name': 'Jean Dupont'}
      }
  )

  print(response.json()['match_result'])
  ```
</CodeGroup>

***

## Test in Sandbox

Use the sandbox environment to test without real bank calls.\
The `sandbox_result` input parameter forces a specific outcome:

```bash theme={null}
curl -X POST https://api.ibantrack.com/api-v1/sandbox/account-holder-verifications \
  -H "Authorization: Bearer YOUR_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
    "account": {"iban": "FR7630004000031234567890143"},
    "account_holder": {"name": "Jean Dupond"},
    "sandbox_result": "close_match"
  }'
```

See the [Sandbox](/api-reference/sandbox/create) page for more details.

***

## Response Codes

Ibantrack uses conventional HTTP response codes to indicate the success or failure of an API request.

| Code  | Description                                                                     |
| :---- | :------------------------------------------------------------------------------ |
| `200` | **Success**: Everything worked as expected.                                     |
| `400` | **Bad Request**: The request was unacceptable, often due to missing parameters. |
| `401` | **Unauthorized**: No valid client credentials or token provided.                |
| `403` | **Forbidden**: Insufficient credits to perform the verification.                |
| `429` | **Too Many Requests**: You have hit the rate limit.                             |
| `500` | **Server Error**: Something went wrong on our end.                              |

***

## Rate Limiting

To ensure platform stability and high quality of service for all users, Ibantrack API enforces the following rate limits:

| Endpoint                                    | Rate Limit            |
| :------------------------------------------ | :-------------------- |
| **POST**`/account-holder-verifications`     | 60 requests / minute  |
| **GET**`/account-holder-verifications/{id}` | 120 requests / minute |

If your application exceeds these limits, the API will return a `429 Too Many Requests` error.

<Info>
  Need higher limits for batch processing or high-volume environments? [Contact our support team](mailto:contact@ibantrack.com) to discuss a custom plan.
</Info>

***

## Next Steps

<CardGroup cols={2}>
  <Card title="Understand Match Results" icon="circle-check" href="/documentation/core-concepts/match-results">
    Learn how to interpret verification results
  </Card>

  <Card title="Full API Reference" icon="code" href="/api-reference/verifications/create-verification">
    All parameters and responses
  </Card>

  <Card title="Sandbox Guide" icon="flask" href="/api-reference/sandbox/create-sandbox-verification">
    Test all scenarios
  </Card>

  <Card title="Handle Errors" icon="triangle-exclamation" href="/documentation/core-concepts/error-handling">
    Retry logic and error codes
  </Card>
</CardGroup>