List Purchase Suppliers

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

GET /v1/purchases/suppliers

cURL

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}"

200

{
  "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
}

← Purchases API

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

cURL

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}"

200

{
  "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
}

Request

Headers

x-api-key · string · required

Your API key (see Authentication).

x-organization-id · string · required

The organization whose suppliers are listed.

Query Parameters

page · integer · default: "1"

Page number, from 1.

size · integer · default: "50"

Suppliers per page, 1 to 100.

filter_by · 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.

filter_match · string

How filter_by clauses on different fields combine: all (AND, the default) or any (OR).

filter_or_fields · string

Comma-separated fields whose own clauses combine with OR instead of AND, e.g. status.

sort_by · string

field:asc or field:desc (e.g. purchases_count:desc), several separated by $. Without it, the suppliers with the most emissions come first.

Response

items · array[object]

Show supplier

id · string

The id to send as supplier_id.

business_name · string

The supplier’s name, as it was sent (commas become dots).

country · string

ISO 3166-1 alpha-2 code, upper case.

status · 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).

enabled · boolean

Always true: disabled suppliers are not listed.

code · string | null

The supplier’s activity code.

code_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).

purchases_count · integer

The supplier’s purchases.

co2e · number | null

The emissions of those purchases, kgCO2e.

official_purchase_supplier_id · string | null

The company the automatic classification matched it to, if any.

organization_id · string

The organization the supplier belongs to.

organization_name · string | null

null (filled only in the Dcycle app’s group view).

organization_logo_url · string | null

null (filled only in the Dcycle app’s group view).

created_at · datetime

When the supplier was created.

updated_at · datetime

When it last changed.

page · integer

The page returned.

size · integer

The page size.

total · integer

The suppliers matching the filters.

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.

Related Endpoints

Create Purchases (v2)

Takes supplier_id, or creates the supplier from its name

List Purchases

Filter purchases by supplier_id[]