Authentication
Every API request carries an API key. A key belongs to one organisation and can only read that organisation's compliance profiles.
Create a key
- On the platform, open Settings → API Keys and create a key. Give it a name for your own reference.
- Choose the scope: leave "Allow this key to push products into the Inbox" unticked for a read-only key, tick it for a
read_writekey. - If your organisation has two or more compliance profiles, you can bind the key to one of them.
- Copy the key. It starts with
cfa_live_and is shown once only: Conphora cannot show it again. If you lose it, revoke it and create a new one.
The key list shows each key's first characters, name, scope, its profile binding, when it was created and when it was last used. Revoking a key takes effect immediately; the key then gets 401 revoked_api_key. You can rename a key, but not change its scope or binding, create a new key instead.
Send the key
Send the key in the x-api-key header. Authorization: Bearer <key> is accepted too; when both are sent, x-api-key wins.
x-api-key: cfa_live_…
# or
Authorization: Bearer cfa_live_… Use the key on your server only, never in storefront or browser JavaScript. Browsers calling the API directly are not supported.
Scopes
| Key scope | Meaning |
|---|---|
read | GET /api/v1/products and GET /api/v1/fields. The default. |
read_write | Everything read can call, plus POST /api/v1/intake. |
The scope is fixed when the key is created.
Profile binding
- A key bound to a profile may only name that profile. Any other
profileIdgets403 profile_not_allowed. - An unbound key may name any profile in its organisation. A profile that does not exist, or belongs to another organisation, gets
404 profile_not_found.
Where to find your profile id
Every endpoint needs a profileId: the id of a compliance profile on the platform. Settings → API Keys shows an example request that already contains it. GET /api/v1/fields returns the profile's id and name, so you can check you have the right one.
GET/api/v1/products
Look up products
Look up 1 to 100 products by your own identifier, by name or by barcode, and get their compliance status, Risk Score, next action and customer pack. There is no endpoint that lists a whole catalogue; use the product feed for that.
Key scope: readPlan: every plan
Query parameters
| Parameter | Type | Required | Default | Meaning |
|---|---|---|---|---|
profileId | string | yes | The compliance profile to look in. It must belong to the key's organisation, and match the key's binding if the key is bound. | |
values | string (comma-separated or repeated) | yes | The values to look up. values=A,B,C and values=A&values=B both work; use the repeated form when a value contains a comma. Values are trimmed, blanks are dropped and exact duplicates are dropped and counted. At most 100 after duplicates are removed. | |
value | string | alias | Accepted as an alias of values and merged with it. | |
field | identifier | name | gtin | no | identifier | What the values are: identifier = your own product identifier (the column your import mapped as the identifier, such as "SKU"), name = the product name, gtin = an EAN / UPC / GTIN barcode. Case-insensitive. No other names are accepted. |
includeArchived | true | no | false | Include archived products. Without it, archived matches are left out and a not_found result reports archivedMatchCount when archived products matched. |
How matching works
identifier: an exact match first, then tolerant variants: leading zeros of all-digit values are ignored ("0012345" finds "12345"), then punctuation, then case. All-digit values longer than 15 digits are refused asvalue_precision_unsupported. A value can be at most 512 characters.gtin: the barcode is normalised to the 14-digit GS1 form and matched exactly. 8, 12, 13 and 14 digits and separators are fine; anything else isnot_a_gtin.name: the exact name first, then a search that ignores case and punctuation.- When more than one product matches, the result is
ambiguouswith the candidates. The API never guesses: ask again with a candidate'sidentifier. - With
field=identifier, a value that is not a product yet but is waiting in the Inbox comes back asstaged.
Response
The response has results (one per distinct value, in request order), summary and meta. A value that is not found, ambiguous or invalid is not an HTTP error: it comes back inside the 200 as its own result.
Results by status
status | Field | Meaning |
|---|---|---|
found | value, matchedVia, product | Exactly one product matched. |
not_found | value, archivedMatchCount (only when > 0) | No match. |
staged | value, inbox { status: pending | dismissed, receivedAt } | Waiting in the Inbox, not yet tracked, so there is no compliance state yet. |
ambiguous | value, matches [{ id, identifier, name }] | Several products matched. |
ambiguous_truncated | value | The search hit its limit of candidates. Narrow the value or use identifier. Cannot happen with field=gtin. |
invalid_value | value, reason: empty_value | value_too_long | value_precision_unsupported | not_a_gtin | The value cannot be looked up. |
matchedVia tells you how a found product matched: identifier_exact, identifier_numeric_zerostrip, identifier_numeric_roundtrip, identifier_alnum, identifier_normalized, name_exact, name_normalized, gtin_exact, gtin_canonical.
summary counts the results: requested, found, notFound, staged, ambiguous, invalid, duplicatesDropped. ambiguous includes ambiguous_truncated; duplicatesDropped appears only when values were dropped.
meta holds resolvedField (the field used), identifierField (what your import called the identifier column, for information) and apiVersion.
The product object
Every key is always present, in this order. Your imported spreadsheet columns are never returned by the API.
| Field | Type | Meaning |
|---|---|---|
id | string | Conphora's stable product id. Not a lookup value. |
profileId | string | The compliance profile. |
identifier | string | Your product identifier. |
identifierField | string | null | Your import's name for the identifier column. |
gtin | string | null | The barcode as 14 digits, zero-padded; null when the import had no valid barcode. |
name | string | The product name. |
imageUrl | string | null | The image URL from your import. |
hsCode | string | null | The HS / commodity code. |
archived | boolean | True for an archived product. |
status.classification | in_progress | awaiting_clarification | completed | failed | null | Where the classification stands; null when it has not started. |
status.compliance | not_checked | compliant | requires_compliance | The compliance state. Never null: not_checked when the product has never been evaluated. |
compliance.lastCheckedAt | number (ms epoch) | null | When the product was last evaluated. |
compliance.summary.matchedCount | number | How many requirements apply. |
compliance.summary.fulfilledCount | number | How many of those are fulfilled. |
compliance.progress | { compliance, attributes, documents }: { filled, total } | Filled / total pairs for requirements, product data and documents; {0, 0} when there are none. |
compliance.matchedRegulations[] | { id, shortName, fullTitle | null, eurLexUrl | null } | The regulations that apply. |
compliance.missingRequirements[] | { key, kind, regulation, requirementId, domain | null, label, deferred } | The open requirements. kind is doc, attr, symbol or checkpoint. deferred = marked "I don't have this data yet"; it still counts as missing. |
riskScore | integer 0–100 | null | The Conphora Risk Score: a priority, not a verdict. Null until the product is scored. |
riskBand | low | watch | high | critical | null | The band of the score. Null when there is no score. |
nextAction | object | null | The one next thing to do. Null when there is no score or nothing to do. |
nextAction.kind | string (see the list below) | What to do. |
nextAction.who | you | supplier | Whose turn it is. |
nextAction.href | string (relative platform path) | A relative path on the platform that opens the action. Open it on the platform's host. |
nextAction.after | number | The Risk Score once this action is done. |
customerPack | object | null | The customer pack with all ten items and their status (your working view, the same as on the product page). Filled on the self-service plan; null on the free check, and null when the profile has no company data yet. |
customerPack.ready | integer 0–10 | How many of the ten items are ready. |
customerPack.total | 10 | Always 10. |
customerPack.items | object: item id → ready | missing | waiting | not-needed | Each item's status, in pack order. not-needed = no part of the item applies to the product. |
customerPack.url | string | null | The full link to the product's public customer-pack page: the product's own standing link (the same one the export and the feed carry). null when there is none, and on the free check. |
customerPack.path | string | null | The same link as a path, /p/<token>, on the documents host. |
createdAt | number (ms epoch) | When the product was created in Conphora. |
updatedAt | number (ms epoch) | When the product last changed. |
Risk Score, band and next action
riskScore, riskBand and nextAction are the same on every plan. The score says which products to fix first; it never calls a product compliant or non-compliant. A known non-compliance puts the product in critical whatever the score.
riskBand | Score | Meaning |
|---|---|---|
low | 0-24 | Monitored, nothing to do |
watch | 25-49 | Something is coming |
high | 50-74 | Fix this month |
critical | 75-100 | Act now |
nextAction.kind is one of a fixed set: clearNonCompliance, reEvaluate, uploadDocument, confirmRequirement, fillProductData, askSupplier, issueDeclaration, runProcedure, registerProduct, assembleTechnicalFile, renewDocument, reconfirmRuleChange, meetKeyDate, submitReport, chaseSupplier, reviewSupplierAnswer.
Customer pack items
The keys of customerPack.items, in pack order. Each status is ready, missing, waiting or not-needed. identity, contact, declaration, standards-tests, safety-information, instructions, substances, packaging-epr, technical-file, recall-contact.
The API keeps all ten statuses. The public pack page your customer opens shows your customer two groups: identity, contact, declaration, safety-information and instructions from the start, counted as "n of 5 ready to list"; standards-tests, substances, packaging-epr and recall-contact on request, each with a button that asks you; technical-file is not on the page.
Example request
curl "https://documents.conphora.com/api/v1/products?profileId=jd7f3k2m9q8x4w1v6t5r0n3b2c&field=identifier&values=NB-1042,NB-2210,NB-9999" \
-H "x-api-key: cfa_live_…" Example response
{
"results": [
{
"value": "NB-1042",
"status": "found",
"matchedVia": "identifier_exact",
"product": {
"id": "k57bq2x9w3m8r1t6v4c0n5p7ds",
"profileId": "jd7f3k2m9q8x4w1v6t5r0n3b2c",
"identifier": "NB-1042",
"identifierField": "SKU",
"gtin": "05790000123452",
"name": "Birch stacking rings, 7 pieces",
"imageUrl": null,
"hsCode": "9503.00",
"archived": false,
"status": {
"classification": "completed",
"compliance": "requires_compliance"
},
"compliance": {
"lastCheckedAt": 1793260800000,
"summary": {
"matchedCount": 14,
"fulfilledCount": 9
},
"progress": {
"compliance": {
"filled": 9,
"total": 14
},
"attributes": {
"filled": 6,
"total": 8
},
"documents": {
"filled": 3,
"total": 5
}
},
"matchedRegulations": [
{
"id": "toy-safety",
"shortName": "TSR",
"fullTitle": "Toy Safety Regulation",
"eurLexUrl": null
},
{
"id": "gpsr",
"shortName": "GPSR",
"fullTitle": "General Product Safety Regulation",
"eurLexUrl": null
}
],
"missingRequirements": [
{
"key": "doc:TSR:eu-declaration-of-conformity",
"kind": "doc",
"regulation": "TSR",
"requirementId": "eu-declaration-of-conformity",
"domain": "documentation",
"label": "EU declaration of conformity",
"deferred": false
}
]
},
"riskScore": 58,
"riskBand": "high",
"nextAction": {
"kind": "issueDeclaration",
"who": "you",
"href": "/nordbirk/products/k57bq2x9w3m8r1t6v4c0n5p7ds?step=declaration",
"after": 41
},
"customerPack": {
"ready": 6,
"total": 10,
"items": {
"identity": "ready",
"contact": "ready",
"declaration": "missing",
"standards-tests": "ready",
"safety-information": "ready",
"instructions": "waiting",
"substances": "ready",
"packaging-epr": "missing",
"technical-file": "ready",
"recall-contact": "missing"
},
"url": null,
"path": null
},
"createdAt": 1790582400000,
"updatedAt": 1793260800000
}
},
{
"value": "NB-2210",
"status": "staged",
"inbox": {
"status": "pending",
"receivedAt": 1793174400000
}
},
{
"value": "NB-9999",
"status": "not_found"
}
],
"summary": {
"requested": 3,
"found": 1,
"notFound": 1,
"staged": 1,
"ambiguous": 0,
"invalid": 0
},
"meta": {
"resolvedField": "identifier",
"identifierField": "SKU",
"apiVersion": "2026-09-10"
}
} Errors
400 missing_parameter, 400 too_many_values, 400 unknown_field, 400 invalid_profile_id, 401 missing_api_key, 401 invalid_api_key, 401 revoked_api_key, 403 profile_not_allowed, 404 profile_not_found, 413 response_too_large, 429 rate_limited — Errors
GET/api/v1/fields
Discover fields
Shows which `field` values the lookup accepts and what the profile's import calls its identifier column. Any key scope; same profile rules as above.
Key scope: readPlan: every plan
Query parameters
| Parameter | Type | Required | Meaning |
|---|---|---|---|
profileId | string | yes | The compliance profile. |
Response
| Field | Type | Meaning |
|---|---|---|
profile.id | string | The profile id. |
profile.name | string | The profile name. |
identifierField | string | null | What the newest import calls the identifier column. |
supportedFields | string[] | Always ["identifier", "name", "gtin"]. |
meta.apiVersion | string | The API version. |
Example request
curl "https://documents.conphora.com/api/v1/fields?profileId=jd7f3k2m9q8x4w1v6t5r0n3b2c" \
-H "x-api-key: cfa_live_…" Example response
{
"profile": {
"id": "jd7f3k2m9q8x4w1v6t5r0n3b2c",
"name": "Nordbirk ApS"
},
"identifierField": "SKU",
"supportedFields": [
"identifier",
"name",
"gtin"
],
"meta": {
"apiVersion": "2026-09-10"
}
} Errors
400 missing_parameter, 400 invalid_profile_id, 401 missing_api_key, 401 invalid_api_key, 401 revoked_api_key, 403 profile_not_allowed, 404 profile_not_found, 429 rate_limited — Errors
POST/api/v1/intake
Push products
Push up to 100 products per request into a profile's Inbox. New identifiers wait in the Inbox until someone on your team moves them to tracking; a product whose identifier matches an existing product updates that product in place. The push itself is not billed, and sending the same product again changes nothing.
Key scope: read_writePlan: self-service plan
Needs a key with the read_write scope (otherwise 403 insufficient_scope) and the self-service plan (otherwise 403 membership_required). The body is JSON, at most 1 MB.
Request body
| Field | Type | Required | Meaning |
|---|---|---|---|
profileId | string | yes | The target compliance profile. |
products | array (1–100) | yes | The products. A later duplicate of a uniqueId is dropped (the first one wins) and counted. |
products[].uniqueId | string | number | yes | Your product identifier, at most 512 characters after trimming. |
products[].name | string | yes | The product name (at most 10,000 characters). |
products[].description | string | yes | The product description. Conphora's classification needs it. |
products[].gtin | string | number | no | The barcode. When present it must be a valid GTIN, or the row is rejected with not_a_gtin. |
products[].imageUrl | string | no | An image URL. |
products[].attributes | object of string | number | boolean | null | no | Any other columns, as a flat object. At most 300 keys of at most 200 characters; long strings are cut to 10,000 characters; nested values are rejected. A key named like a top-level field is overwritten by the top-level value. |
products[].hints | object: category → attribute keys | no | Tells the classification which attributes describe what. Every key must exist in attributes and may appear in one category only. |
Hint categories: productDescription, material, productCategory, packaging, supplierInfo, other.
A profile's Inbox holds at most 50,000 waiting rows; a push past that gets 429 intake_full.
Response
results are in request order, one per product: uniqueId, status, and intakeId, productId or errors where they apply.
Results by status
status | Meaning |
|---|---|
staged | New: now waiting in the Inbox (intakeId). |
refreshed | Was already waiting; its content was updated. |
resurfaced | Had been dismissed from the Inbox and came back as pending because its content changed. |
unchanged | Already known, and nothing changed. |
updated | Matched an active product, which was updated (productId). |
updated_idle | Matched an archived product, which was updated in place and stays archived. |
invalid | The row was rejected: errors lists { field, reason }. |
Reasons for invalid: required, invalid_type, too_long, not_a_gtin, too_many_attributes, unknown_category, reserved_key, unknown_attribute, assigned_twice.
summary counts the results: received, staged, refreshed, unchanged, updated, updatedIdle, archivedSkipped, invalid, duplicatesDropped. received counts products after duplicates were dropped; refreshed includes resurfaced; archivedSkipped is always 0 and kept for older clients.
If a request fails part-way with 500 intake_failed, the products before index completed were saved and results lists them; send the rest again.
Example request
curl -X POST "https://documents.conphora.com/api/v1/intake" \
-H "x-api-key: cfa_live_…" \
-H "Content-Type: application/json" \
-d '{
"profileId": "jd7f3k2m9q8x4w1v6t5r0n3b2c",
"products": [
{
"uniqueId": "NB-3001",
"name": "Oak pull-along duck",
"description": "Wooden pull toy for children from 12 months, water-based paint.",
"gtin": "5790000123469",
"attributes": {
"Material": "Oak, water-based paint",
"Age": "12m+"
},
"hints": {
"material": [
"Material"
]
}
},
{
"uniqueId": "NB-3002",
"name": "Felt play mat"
}
]
}' Example response
{
"results": [
{
"uniqueId": "NB-3001",
"status": "staged",
"intakeId": "m12x7c4v9b2n8q5w3e6r1t0y4u"
},
{
"uniqueId": "NB-3002",
"status": "invalid",
"errors": [
{
"field": "description",
"reason": "required"
}
]
}
],
"summary": {
"received": 2,
"staged": 1,
"refreshed": 0,
"unchanged": 0,
"updated": 0,
"updatedIdle": 0,
"archivedSkipped": 0,
"invalid": 1
},
"meta": {
"apiVersion": "2026-09-10"
}
} Errors
400 missing_parameter, 400 invalid_profile_id, 400 invalid_json, 400 invalid_payload, 400 too_many_products, 401 missing_api_key, 401 invalid_api_key, 401 revoked_api_key, 403 insufficient_scope, 403 profile_not_allowed, 403 membership_required, 404 profile_not_found, 413 payload_too_large, 429 rate_limited, 429 intake_full, 500 intake_failed, 503 rate_limiter_unavailable — Errors
GET/feed/{token}
Product feed
A product feed is a fixed URL that always serves the latest data of one compliance profile's active products, as JSON, CSV or Excel. It needs no API key: the token in the URL is the credential, so anyone who has the URL can read the feed until you revoke it.
Create and revoke a feed link
- On the platform, open Tables, choose "Feed" in the toolbar and create a link. The link takes the columns visible in the table at that moment; you can change its columns and give it a label later.
- Each link has copy buttons for CSV, XLSX and JSON.
- Revoking a link takes effect immediately: the next request gets
404.
Feed links are available on every plan. The two customer-pack columns are filled on the self-service plan only.
Query parameters
| Parameter | Meaning |
|---|---|
format | The output format: json (the default), csv or xlsx. |
shared | Keep only the products that have an open customer-pack share link with this label (your customer's name, case-insensitive), and point each row's "Customer pack URL" at that share instead of the product's standing link. This gives one customer a catalogue-level pack. Empty on the free check, which has no share links. |
Formats
format | Meaning |
|---|---|
json | An array of objects, one key per column name. Structured columns are arrays and objects, dates are ISO 8601, missing values are null. |
csv | UTF-8 with a header row of column names, comma-separated. Cells with several values are joined with line breaks. |
xlsx | One sheet with the same cells as the CSV. |
Columns
A link serves the columns chosen for it, in this order: first your own imported columns under their own names (identifier, name, then the rest), then Conphora's columns. Unlike the API, the feed does include your imported data:
| Column | Meaning |
|---|---|
EAN / GTIN | The 14-digit barcode. |
Commodity Code | The HS code. |
Matched Regulations | The short names of the regulations that apply. |
Markets | The markets, with country code and name. |
EN Standards | The recommended standards (shown on the platform as "Recommended Standards"; the feed keeps this name). |
Tested for | What your documents show the product was tested for. |
Attributes | The product data, label, value and unit. |
Attributes on Product | The attributes that go on the product. |
Attributes on Packaging | The attributes that go on the packaging. |
Attributes in Documentation | The attributes that go in the documentation. |
Attributes in Online Listing | The attributes that go in the online listing. |
Document Links | One entry per document: title, type, compliance areas and a link to the document. |
Customer pack | "6 of 10 ready" and each of the ten items' status (the feed keeps all ten; the pack page shows five from the start and four on request) (in JSON: { ready, total, items }). Empty, or null in JSON, on the free check. |
Customer pack URL | The link to the product's customer-pack page: the product's own standing link, or the shared customer's share when you filter. Empty on the free check. |
Created | When the product was created. |
Updated | When the product last changed. |
The feed has no compliance-status, Risk Score or next-action column; those are in the API. The feed has no version number: its column names are its contract, and your imported column names follow your imports.
Example request
curl "https://documents.conphora.com/feed/<your-feed-token>?format=json" Example response
[
{
"SKU": "NB-1042",
"Product name": "Birch stacking rings, 7 pieces",
"Colour": "Natural",
"EAN / GTIN": "05790000123452",
"Commodity Code": "9503.00",
"Matched Regulations": [
"TSR",
"GPSR"
],
"Markets": [
{
"countryCode": "DK",
"name": "Denmark"
},
{
"countryCode": "SE",
"name": "Sweden"
}
],
"Customer pack": {
"ready": 6,
"total": 10,
"items": {
"identity": "ready",
"contact": "ready",
"declaration": "missing",
"standards-tests": "ready",
"safety-information": "ready",
"instructions": "waiting",
"substances": "ready",
"packaging-epr": "missing",
"technical-file": "ready",
"recall-contact": "missing"
}
},
"Customer pack URL": null,
"Created": "2026-09-29T08:00:00.000Z",
"Updated": "2026-10-29T08:00:00.000Z"
}
] Feed errors are plain text, not JSON: 404 when the link is invalid or revoked, 413 when the export would be too large (CSV is the most compact format).
Rate limits
Reads and writes have separate limits, each counted per API key and per organisation (all keys together). A request must pass both. The figures are today's values, set to stop runaway scripts, not to throttle normal use.
| Requests | Counted per | Rate | Burst |
|---|---|---|---|
GET /api/v1/products, GET /api/v1/fields | API key | 600 / minute | 120 |
GET /api/v1/products, GET /api/v1/fields | organisation | 3,000 / minute | 500 |
POST /api/v1/intake | API key | 120 / minute | 30 |
POST /api/v1/intake | organisation | 600 / minute | 100 |
Over the limit, the API answers 429 with the error rate_limited, a retryAfterMs field and a Retry-After header in seconds (at least 1). Wait that long before you retry.
HTTP/1.1 429 Too Many Requests
Retry-After: 2
{
"error": "rate_limited",
"message": "Too many requests. Slow down and retry.",
"retryAfterMs": 1800
} Errors
Every error from an `/api/v1` endpoint is JSON of the shape `{ "error": "<code>", "message": "<text>" }`, sometimes with extra fields, sent with the HTTP status. Branch on `error`, never on `message`. A wrong method or an unknown path is not one of these endpoints and does not answer in this shape.
| Status | error | When | Extra fields | Endpoints |
|---|---|---|---|---|
| 400 | missing_parameter | No profileId, no values, or no products / an empty array. | all | |
| 400 | too_many_values | More than 100 distinct values. | maxValues | GET /api/v1/products |
| 400 | unknown_field | field is not identifier, name or gtin. | supportedFields | GET /api/v1/products |
| 400 | invalid_profile_id | profileId is not a well-formed id. | all | |
| 400 | invalid_json | The body is not JSON. | POST /api/v1/intake | |
| 400 | invalid_payload | The body is not an object, or products is not an array. | POST /api/v1/intake | |
| 400 | too_many_products | More than 100 products. | maxProducts | POST /api/v1/intake |
| 401 | missing_api_key | No key was sent. | all | |
| 401 | invalid_api_key | The key is unknown. | all | |
| 401 | revoked_api_key | The key was revoked. | all | |
| 403 | insufficient_scope | A read key called the intake. | POST /api/v1/intake | |
| 403 | profile_not_allowed | The key is bound to a different profile. | all | |
| 403 | membership_required | The organisation has no active self-service plan. | POST /api/v1/intake | |
| 404 | profile_not_found | The profile does not exist or belongs to another organisation. | all | |
| 413 | response_too_large | The result would be larger than about 18 MB. Ask for fewer values. | GET /api/v1/products | |
| 413 | payload_too_large | The body is larger than 1 MB. | maxBodyBytes | POST /api/v1/intake |
| 429 | rate_limited | A rate limit was reached. | retryAfterMs + Retry-After header | all |
| 429 | intake_full | The profile's Inbox would pass 50,000 waiting rows. | POST /api/v1/intake | |
| 500 | intake_failed | The request failed part-way; the products before index completed were saved. | completed, results | POST /api/v1/intake |
| 503 | rate_limiter_unavailable | Writes are briefly unavailable. Retry after the Retry-After header. | Retry-After header | POST /api/v1/intake |
Versioning
- The version is in the path (
/api/v1) and in every response body asmeta.apiVersion. - Fields may be added at any time. Build clients that ignore fields they do not know.
- A breaking change changes the version.
meta.apiVersion: "2026-09-10"