Skip to main content
POST
← Purchases API Add the suppliers your organization buys from before you send their purchases: a name, a country and, if you know it, the supplier’s activity code (CNAE or SIC), which picks the spend-based emission factor of its purchases. Nothing is calculated, so the request is synchronous (see how bulk ingestion works): it answers 201 Created with the created suppliers. It also records an ingest job, born completed, that sends no webhook. A supplier is the one Create Purchases (v2) uses for a purchase sent with its supplier_id, or with the same supplier_name and supplier_country. This route sends no email and calculates no emissions: those come with the purchases.
Beta. Part of the bulk ingest API, in beta. The contract may still change before general availability.

​
How it works

  1. Every record is checked: its name and country are free, and its code, if sent, is an active code of its framework. If any record is invalid the whole request is rejected with 422 and nothing is created (all or nothing): rejected is the number of invalid records and errors lists them (up to 100).
  2. The name and country identify a supplier in the organization, with the key Create Purchases (v2) matches supplier_name by: the exact name (case, spaces and punctuation count; commas become dots) and the country, in upper case. A supplier already stored with that key, whatever its status, rejects the record (SUPPLIER_ALREADY_EXISTS, with its id): an existing supplier is never reclassified here, because its purchases would need recalculating. Two records with the same key reject the second (DUPLICATE_SUPPLIER), also when they differ only by commas and dots or the case of the country.
  3. Every supplier is created in one transaction and returned, in the order sent. source_row_index is the position of the record in records, and client_row_id echoes yours. The stored name has its commas replaced by dots, and the country is upper-cased.
    • With code and framework, the supplier is classified at once: it is active, and its purchases are calculated with the factor of that activity and its country, without a D&B lookup.
    • Without, it is created exactly as Create Purchases (v2) creates a supplier it does not know: if Dcycle already knows an official (D&B) classification for that exact name and country, the supplier takes it; otherwise it is in_progress until its first purchase classifies it (the 80 % rule of Create Purchases (v2)).
  4. The suppliers belong to the x-organization-id organization. A record cannot name another one, not even one of your perimeter: send each organization’s suppliers with its own x-organization-id.
A later purchase sent with the same supplier_name and supplier_country, or with the supplier’s id as supplier_id, uses it. To retry a request safely, repeat it with the same Idempotency-Key.

​
Activity codes

GET /v1/purchases/suppliers/codes?framework=cnae_2009 (or us_sic_v87), with your x-api-key and x-organization-id, lists the codes of a framework, as strings (["0111", "0130", ...]). A code is accepted when it is an active code of its framework in Dcycle’s classification; any other is REFERENCE_NOT_FOUND.
For us_sic_v87, the list can include codes that are not active, which this route rejects with REFERENCE_NOT_FOUND. Prefer cnae_2009 codes, or leave code out and let Dcycle classify the supplier.

​
Request

​
Headers

​
string
required
Your API key (see Authentication).
​
string
required
The organization the suppliers belong to.
​
string
required
1 to 255 characters, one per batch, looked up per organization across every v2 bulk route. Within 24 hours, the same key with the same route and body answers the same suppliers (with Idempotent-Replayed: true) instead of creating them again; the same key with another body or on another route is 422 IDEMPOTENCY_KEY_REUSED, and while the first request is still being processed 409 IDEMPOTENCY_KEY_IN_PROGRESS. After 24 hours the key is free, and a request with it is a new one. See The Idempotency-Key.

​
Query Parameters

​
boolean
default:"false"
Check only: the same 422 for invalid records, nothing written; 200 with {"dry_run": true, "submitted": n, "valid": n} when every record is valid. It does not check or store the Idempotency-Key.

​
Body Parameters

​
array[object]
required
The suppliers to create, 1 to 1,000. A field not listed here is rejected (SCHEMA_INVALID).

​
Response

201 Created with items: one per record, in the order sent, with its source_row_index, client_row_id and the created supplier:
  • id: the id to send as supplier_id in Create Purchases (v2), and the one Delete Purchase Suppliers (v2) takes.
  • organization_id, business_name (as stored), country (upper case), created_at.
  • status: active when the supplier is classified, in_progress while Dcycle classifies it.
List Purchase Suppliers shows them with their activity code and code_type.

​
Errors

Problem details. Per-record codes in errors[].error_code of a 422 BULK_RECORDS_REJECTED: Request-level errors: 401 for a missing or invalid API key, 403 LOGGED_USER_NOT_MEMBER when the key’s user is not a member of the organization, 422 REQUEST_VALIDATION_FAILED for a malformed body (no records, more than 1,000, no Idempotency-Key), 422 IDEMPOTENCY_KEY_REUSED, 409 IDEMPOTENCY_KEY_IN_PROGRESS, and 429 beyond the rate limits.

​
Limits

Delete Purchase Suppliers (v2)

Delete suppliers by id

Create Purchases (v2)

Purchases from these suppliers

List Purchase Suppliers

The suppliers stored, with their activity code

List Ingest Jobs

The job each request records