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

# List Partners

> Check which billers are currently available

## Overview

Returns the availability of every supported biller. Call it before a discovery so you can hide an unavailable partner from your customers instead of letting them hit a `503` at the end of a form.

The response is a map keyed by the exact `partner` value you send to [Discover Bills](/en/api-reference/bill-payment/discover-bills) — including the accents in `Algérie Télécom`.

<Note>
  A `PRODUCTION` key sees live availability. A `SANDBOX` key sees a fixed map, because a sandbox request never reaches a partner and live availability would be misleading there.
</Note>

## Response

<ResponseField name="success" type="boolean" required>
  `true` when the map was returned.
</ResponseField>

<ResponseField name="data" type="object" required>
  One entry per partner. The key set is fixed.

  <Expandable title="properties">
    <ResponseField name="ADE" type="object">
      Algérienne Des Eaux — water.
    </ResponseField>

    <ResponseField name="SONELGAZ" type="object">
      Electricity and gas.
    </ResponseField>

    <ResponseField name="SEAAL" type="object">
      Water for Algiers and Tipaza.
    </ResponseField>

    <ResponseField name="AADL" type="object">
      Housing instalments.
    </ResponseField>

    <ResponseField name="Algérie Télécom" type="object">
      Landline and internet.
    </ResponseField>
  </Expandable>
</ResponseField>

Each entry has a single field:

<ResponseField name="status" type="string" required>
  `ACTIVE` — discovery and payment are accepted.

  `UNAVAILABLE` — discovery and payment for this partner answer `503 PARTNER_UNAVAILABLE`.
</ResponseField>

<ResponseField name="meta" type="object" required>
  <Expandable title="properties">
    <ResponseField name="timestamp" type="string" required>
      Response time, ISO 8601 UTC.
    </ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="requestId" type="string" required>
  Correlation identifier, also sent as the `X-Request-Id` response header.
</ResponseField>

## Examples

<CodeGroup>
  ```bash cURL theme={null}
  curl https://billapi.oneclickdz.com/v3/partners \
    -H "X-Access-Token: YOUR_API_KEY"
  ```

  ```javascript Node.js theme={null}
  const response = await fetch("https://billapi.oneclickdz.com/v3/partners", {
    headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY },
  });

  const body = await response.json();

  if (!body.success) {
    throw new Error(`${body.error.code}: ${body.error.message}`);
  }

  const available = Object.entries(body.data)
    .filter(([, partner]) => partner.status === "ACTIVE")
    .map(([name]) => name);

  console.log(available);
  ```

  ```python Python theme={null}
  import os
  import requests

  response = requests.get(
      'https://billapi.oneclickdz.com/v3/partners',
      headers={'X-Access-Token': os.getenv('ONECLICKDZ_API_KEY')}
  )

  body = response.json()

  if not body['success']:
      raise RuntimeError(f"{body['error']['code']}: {body['error']['message']}")

  available = [
      name for name, partner in body['data'].items()
      if partner['status'] == 'ACTIVE'
  ]

  print(available)
  ```

  ```php PHP theme={null}
  <?php
  $ch = curl_init('https://billapi.oneclickdz.com/v3/partners');
  curl_setopt($ch, CURLOPT_RETURNTRANSFER, true);
  curl_setopt($ch, CURLOPT_HTTPHEADER, [
      'X-Access-Token: ' . getenv('ONECLICKDZ_API_KEY')
  ]);

  $body = json_decode(curl_exec($ch), true);
  curl_close($ch);

  if (!$body['success']) {
      throw new Exception($body['error']['code'] . ': ' . $body['error']['message']);
  }

  $available = array_keys(array_filter(
      $body['data'],
      fn($partner) => $partner['status'] === 'ACTIVE'
  ));

  print_r($available);
  ?>
  ```
</CodeGroup>

### Success Response

```json theme={null}
{
  "success": true,
  "data": {
    "ADE": { "status": "ACTIVE" },
    "SONELGAZ": { "status": "ACTIVE" },
    "SEAAL": { "status": "UNAVAILABLE" },
    "AADL": { "status": "UNAVAILABLE" },
    "Algérie Télécom": { "status": "ACTIVE" }
  },
  "meta": {
    "timestamp": "2026-08-31T10:15:32.194Z"
  },
  "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
}
```

## Error Responses

<AccordionGroup>
  <Accordion title="401 — Missing access token">
    **The `X-Access-Token` header was not sent.**

    ```json theme={null}
    {
      "success": false,
      "error": {
        "code": "MISSING_ACCESS_TOKEN",
        "message": "X-Access-Token header is required."
      },
      "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
    }
    ```

    **What to do:** add the header and retry.
  </Accordion>

  <Accordion title="401 — Invalid access token">
    **The key was rejected.**

    ```json theme={null}
    {
      "success": false,
      "error": {
        "code": "INVALID_ACCESS_TOKEN",
        "message": "The provided access token is invalid."
      },
      "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
    }
    ```

    **What to do:** verify the key with [Validate API Key](/en/api-reference/bill-payment/validate-key).
  </Accordion>

  <Accordion title="503 — Authentication unavailable">
    **We could not verify your key in time.**

    ```json theme={null}
    {
      "success": false,
      "error": {
        "code": "AUTH_UNAVAILABLE",
        "message": "Authentication is temporarily unavailable. Please retry shortly."
      },
      "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
    }
    ```

    **What to do:** retry after the `Retry-After` header. Serve the last cached map in the meantime.
  </Accordion>

  <Accordion title="503 — Service unavailable">
    **The Bill Payment API is in planned maintenance.**

    ```json theme={null}
    {
      "success": false,
      "error": {
        "code": "SERVICE_UNAVAILABLE",
        "message": "The service is temporarily unavailable. Please retry shortly."
      },
      "requestId": "req_9f3a1c72e0b84d51aB3xZq07"
    }
    ```

    **What to do:** honour `Retry-After` and retry.
  </Accordion>
</AccordionGroup>

## Current availability

`SEAAL` and `AADL` are currently `UNAVAILABLE` in both sandbox and production, and discovery or payment for them answers `503 PARTNER_UNAVAILABLE`. This is the operator's current setting, not a permanent limitation — keep both partners in your code and let this endpoint decide what to show.

<Warning>
  Do not hard-code the availability of any partner. Read this map, and treat `503 PARTNER_UNAVAILABLE` on a discovery as a partner that went unavailable between your last refresh and the request.
</Warning>

## Caching the map

Availability changes rarely. Refresh it on a timer rather than before every discovery, and keep serving the last good copy when a refresh fails.

```javascript theme={null}
let cache = { map: null, fetchedAt: 0 };
const TTL_MS = 5 * 60 * 1000;

async function getPartners() {
  if (cache.map && Date.now() - cache.fetchedAt < TTL_MS) {
    return cache.map;
  }

  try {
    const response = await fetch("https://billapi.oneclickdz.com/v3/partners", {
      headers: { "X-Access-Token": process.env.ONECLICKDZ_API_KEY },
    });

    const body = await response.json();

    if (body.success) {
      cache = { map: body.data, fetchedAt: Date.now() };
    }
  } catch (error) {
    // Keep serving the previous map rather than blocking the customer.
  }

  return cache.map ?? {};
}

async function isAvailable(partner) {
  const map = await getPartners();
  return map[partner]?.status === "ACTIVE";
}
```

## Best Practices

<CardGroup cols={2}>
  <Card title="Cache for a few minutes" icon="database">
    A 5-minute cache is enough. Calling this before every discovery adds a round trip and buys nothing.
  </Card>

  <Card title="Fail soft on refresh" icon="shield-halved">
    If the refresh fails, keep the previous map. An empty partner list is worse than a slightly stale one.
  </Card>

  <Card title="Use the exact partner value" icon="quote-left">
    Send `Algérie Télécom` with its accents. The value is the key of this map, character for character.
  </Card>

  <Card title="Handle the race" icon="triangle-exclamation">
    A partner can become unavailable after you cached it. Handle `503 PARTNER_UNAVAILABLE` on discovery too.
  </Card>
</CardGroup>

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Validate API Key" icon="key" href="/en/api-reference/bill-payment/validate-key">
    Confirm your key and environment
  </Card>

  <Card title="Discover Bills" icon="magnifying-glass-dollar" href="/en/api-reference/bill-payment/discover-bills">
    Look up what an account owes
  </Card>

  <Card title="Partners and Accounts" icon="address-card" href="/en/bill-payment-guides/1-partners-and-accounts">
    Identifiers for each partner
  </Card>

  <Card title="Bill Payment Overview" icon="file-invoice-dollar" href="/en/bill-payment-guides/overview">
    How the whole flow fits together
  </Card>
</CardGroup>