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

# List Purchase Suppliers

> Your organization's purchase suppliers, with their activity code and emissions: the ids for supplier_id on purchases

[← Purchases API](/api-reference/purchases/overview)

List the suppliers your organization buys from. Each one is a supplier of the `x-organization-id` organization: the
ones you created, sending `supplier_name` and `supplier_country` in
[Create Purchases (v2)](/api-reference/purchases/create-v2) or from the Dcycle app, and those of your file imports.
Use their `id` as `supplier_id` when you create purchases: a purchase can only name a supplier of its own
organization.

Each supplier carries the activity code (SIC or CNAE) its spend-based emission factor comes from, how many purchases
it has and their emissions.

<RequestExample>
  ```bash cURL theme={"theme":{"light":"github-light","dark":"github-dark"}}
  curl "https://api.dcycle.io/v1/purchases/suppliers?page=1&size=50&filter_by=business_name:lkTELEFONICA" \
    -H "x-api-key: ${DCYCLE_API_KEY}" \
    -H "x-organization-id: ${DCYCLE_ORG_ID}"
  ```

  ```python Python theme={"theme":{"light":"github-light","dark":"github-dark"}}
  import os

  import requests

  response = requests.get(
      "https://api.dcycle.io/v1/purchases/suppliers",
      headers={"x-api-key": os.environ["DCYCLE_API_KEY"], "x-organization-id": os.environ["DCYCLE_ORG_ID"]},
      params={"page": 1, "size": 50, "filter_by": "country:eqES"},
      timeout=30,
  )
  response.raise_for_status()
  for supplier in response.json()["items"]:
      print(supplier["id"], supplier["business_name"], supplier["code"], supplier["status"])
  ```
</RequestExample>

<ResponseExample>
  ```json 200 theme={"theme":{"light":"github-light","dark":"github-dark"}}
  {
    "items": [
      {
        "id": "5f4e3d2c-1b0a-4f9e-8d7c-6b5a4f3e2d1c",
        "business_name": "TELEFONICA DE ESPANA SAU",
        "country": "ES",
        "status": "active",
        "enabled": true,
        "code": "4813",
        "code_type": "us_sic_v87",
        "purchases_count": 3,
        "co2e": 156.92,
        "official_purchase_supplier_id": "0c1b2a39-4857-4f6e-9d8c-7b6a5f4e3d2c",
        "organization_id": "a8315ef3-dd50-43f8-b7ce-d839e68d51fa",
        "organization_name": null,
        "organization_logo_url": null,
        "created_at": "2026-10-15T13:37:25.421000",
        "updated_at": "2026-10-15T13:37:30.118000"
      }
    ],
    "page": 1,
    "size": 50,
    "total": 1
  }
  ```
</ResponseExample>

## Request

### Headers

<ParamField header="x-api-key" type="string" required>
  Your API key (see [Authentication](/api-reference/introduction#authentication)).
</ParamField>

<ParamField header="x-organization-id" type="string" required>
  The organization whose suppliers are listed.
</ParamField>

### Query Parameters

<ParamField query="page" type="integer" default="1">
  Page number, from 1.
</ParamField>

<ParamField query="size" type="integer" default="50">
  Suppliers per page, 1 to 100.
</ParamField>

<ParamField query="filter_by" type="string">
  Filter expression. Each clause is `field:` plus a two-letter operator and the value, with no space
  (`country:eqES`); clauses are separated by `$`.

  **Operators:** `eq` (equals), `ne` (not equals), `lk` (contains, case-sensitive), `nl` (does not contain), `gt`,
  `ge`, `lt`, `le` (numbers), `in` / `ni` (in / not in a JSON list, e.g. `status:in["in_review","in_progress"]`).

  **Fields:** `business_name`, `country`, `status`, `purchases_count`, `co2e`.

  **Examples:** `business_name:eqTELEFONICA DE ESPANA SAU$country:eqES` finds the supplier a `supplier_name` +
  `supplier_country` resolve to; `status:eqin_review` the ones that could not be classified. A clause on any other
  field is ignored. URL-encode the value.
</ParamField>

<ParamField query="filter_match" type="string">
  How `filter_by` clauses on different fields combine: `all` (AND, the default) or `any` (OR).
</ParamField>

<ParamField query="filter_or_fields" type="string">
  Comma-separated fields whose own clauses combine with OR instead of AND, e.g. `status`.
</ParamField>

<ParamField query="sort_by" type="string">
  `field:asc` or `field:desc` (e.g. `purchases_count:desc`), several separated by `$`. Without it, the suppliers with the most emissions come first.
</ParamField>

## Response

<ResponseField name="items" type="array[object]">
  <Expandable title="supplier">
    <ResponseField name="id" type="string">The id to send as `supplier_id`.</ResponseField>
    <ResponseField name="business_name" type="string">The supplier's name, as it was sent (commas become dots).</ResponseField>
    <ResponseField name="country" type="string">ISO 3166-1 alpha-2 code, upper case.</ResponseField>

    <ResponseField name="status" type="string">
      `active` when the supplier has an activity code its purchases are calculated with; `in_progress` while a new
      supplier waits for its classification; `in_review` when it could not be classified (its purchases end in
      `error`).
    </ResponseField>

    <ResponseField name="enabled" type="boolean">Always `true`: disabled suppliers are not listed.</ResponseField>
    <ResponseField name="code" type="string | null">The supplier's activity code.</ResponseField>

    <ResponseField name="code_type" type="string | null">
      Its classification: `us_sic_v87` (SIC, set by the automatic classification) or `cnae_2009` (CNAE, when it was
      reclassified by hand or by the supplier import).
    </ResponseField>

    <ResponseField name="purchases_count" type="integer">The supplier's purchases.</ResponseField>
    <ResponseField name="co2e" type="number | null">The emissions of those purchases, kgCO2e.</ResponseField>

    <ResponseField name="official_purchase_supplier_id" type="string | null">
      The company the automatic classification matched it to, if any.
    </ResponseField>

    <ResponseField name="organization_id" type="string">The organization the supplier belongs to.</ResponseField>
    <ResponseField name="organization_name" type="string | null">`null` (filled only in the Dcycle app's group view).</ResponseField>
    <ResponseField name="organization_logo_url" type="string | null">`null` (filled only in the Dcycle app's group view).</ResponseField>
    <ResponseField name="created_at" type="datetime">When the supplier was created.</ResponseField>
    <ResponseField name="updated_at" type="datetime">When it last changed.</ResponseField>
  </Expandable>
</ResponseField>

<ResponseField name="page" type="integer">The page returned.</ResponseField>
<ResponseField name="size" type="integer">The page size.</ResponseField>
<ResponseField name="total" type="integer">The suppliers matching the filters.</ResponseField>

## Errors

`401` for a missing or invalid API key, `403` when the key's user is not a member of the organization, `422` for a
malformed query parameter, and `429` beyond the [rate limits](/api-reference/rate-limits).

## Related Endpoints

<CardGroup cols={2}>
  <Card title="Create Purchases (v2)" icon="plus" href="/api-reference/purchases/create-v2">
    Takes `supplier_id`, or creates the supplier from its name
  </Card>

  <Card title="List Purchases" icon="table" href="/api-reference/purchases/list">
    Filter purchases by `supplier_id[]`
  </Card>
</CardGroup>


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