API

EPR Clear API reference

Verify seller EPR registrations, read the append-only evidence records, and pull coverage, all over one REST API. This reference is generated from the live route table, so every endpoint below is one the API actually serves.

Download the OpenAPI spec

Authentication

Every request carries a bearer API key in the Authorization header. A test-mode key operates on a shadow organization whose data is fully partitioned from live, so you can integrate without touching production records. An unauthenticated request is always a 401, and a 404 is only ever returned to an authenticated caller, so a key can never be used to enumerate which resources exist.

Test modeepc_test_Live modeepc_live_

Send the key as a bearer token:

Authorization: Bearer epc_live_...

Keys are created in the console, under Settings then API keys. The key is shown once when it is created; rotating one keeps the old key working for 24 hours, and revoking one takes effect immediately.

Idempotency

Every write accepts an Idempotency-Key header. Replaying a request with the same key returns the original result rather than acting twice; reusing a key with a different body is rejected as a conflict. Reads are naturally idempotent and take no key.

Errors

Errors follow RFC 7807 problem+json. The envelope carries a stable type URL, a human title, the HTTP status, and a detail string; a validation failure adds an issues array pinpointing each offending field.

Problem fields

{
  "type": "object",
  "required": [
    "type",
    "title",
    "status",
    "detail"
  ],
  "properties": {
    "type": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer"
    },
    "detail": {
      "type": "string"
    }
  },
  "additionalProperties": true
}

Quickstart

Point your client at the API origin and send your bearer key. A representative call for each resource group is shown inline below.

curl https://api.eprclear.com/v1/coverage \
  -H "Authorization: Bearer epc_test_..."

Endpoints

Grouped by resource. Each endpoint lists its method, path, parameters, request body and the response and error statuses it can return.

Sellers

Example

curl -X POST https://api.eprclear.com/v1/sellers \
  -H "Authorization: Bearer epc_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST/v1/sellers

Create or upsert a sellerBearer key required

ParametersNo parameters.

Request bodyPostSellerBody

Responses

200SuccessSellerEnvelope

401UnauthenticatedProblem

422Validation failed or idempotency key reusedProblem

GET/v1/sellers/{sellerId}/status

Read the verdict matrix for a seller (live, or as-of a past instant)Bearer key required

Parameters

sellerIdpathrequired

as_ofqueryoptional

READ-ONLY Time Machine: an ISO-8601 instant. When present and valid, the matrix is reconstructed AS-OF that past instant from the append-only evidence records (never re-verified); last_record_id is the as-of record id and a cell with no record at-or-before as_of is absent. Omitted: the live read-model matrix.

Responses

200SuccessStatusEnvelope

400Malformed request (e.g. an invalid as_of/from/to query parameter)Problem

401UnauthenticatedProblem

404Not foundProblem

GET/v1/sellers/{sellerId}/timeline

Read the verdict change timeline for a seller (READ-ONLY Time Machine)Bearer key required

Parameters

sellerIdpathrequired

fromqueryoptional

Inclusive ISO-8601 lower bound on a transition's instant.

toqueryoptional

Inclusive ISO-8601 upper bound on a transition's instant.

Responses

200SuccessTimelineEnvelope

400Malformed request (e.g. an invalid as_of/from/to query parameter)Problem

401UnauthenticatedProblem

404Not foundProblem

Registrations

Example

curl -X POST https://api.eprclear.com/v1/sellers/{sellerId}/registrations \
  -H "Authorization: Bearer epc_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST/v1/sellers/{sellerId}/registrations

Declare registration numbers for a sellerBearer key required

Parameters

sellerIdpathrequired

Request bodyPostRegistrationsBody

Responses

201CreatedRegistrationsEnvelope

401UnauthenticatedProblem

404Not foundProblem

422Validation failed or idempotency key reusedProblem

SKUs

Example

curl -X POST https://api.eprclear.com/v1/sellers/{sellerId}/skus \
  -H "Authorization: Bearer epc_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST/v1/sellers/{sellerId}/skus

Declare the trigger-bearing SKU attributes for a sellerBearer key required

Parameters

sellerIdpathrequired

Request bodyPostSkusBody

Responses

201CreatedSkusEnvelope

401UnauthenticatedProblem

404Not foundProblem

422Validation failed or idempotency key reusedProblem

GET/v1/sellers/{sellerId}/skus

Read a seller's declared SKU catalogBearer key required

Parameters

sellerIdpathrequired

Responses

200SuccessSkusEnvelope

401UnauthenticatedProblem

404Not foundProblem

Verifications

Example

curl -X POST https://api.eprclear.com/v1/verifications \
  -H "Authorization: Bearer epc_test_..." \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{ ... }'

POST/v1/verifications

Run verifications for a sellerBearer key required

ParametersNo parameters.

Request bodyPostVerificationBody

Responses

201CreatedVerificationsEnvelope

401UnauthenticatedProblem

403Forbidden (missing scope) or upgrade requiredProblem

404Not foundProblem

422Validation failed or idempotency key reusedProblem

GET/v1/verifications/{recordId}

Read one verification evidence recordBearer key required

Parameters

recordIdpathrequired

Responses

200SuccessVerificationRecordEnvelope

401UnauthenticatedProblem

404Not foundProblem

Evidence

Example

curl https://api.eprclear.com/v1/evidence/records/{recordId} \
  -H "Authorization: Bearer epc_test_..."

GET/v1/evidence/records/{recordId}

Read one evidence record (alias of GET /verifications/{id})Bearer key required

Parameters

recordIdpathrequired

Responses

200SuccessVerificationRecordEnvelope

401UnauthenticatedProblem

404Not foundProblem

Coverage

Example

curl https://api.eprclear.com/v1/coverage \
  -H "Authorization: Bearer epc_test_..."

GET/v1/coverage

Read the register coverage matrixBearer key required

ParametersNo parameters.

Responses

200SuccessCoverageEnvelope

401UnauthenticatedProblem

Entities

Example

curl https://api.eprclear.com/v1/entities/search \
  -H "Authorization: Bearer epc_test_..."

GET/v1/entities/search

Universal entity search (by VAT/SIREN/register id or name)Bearer key required

Parameters

qqueryoptional

The search term: an identifier (VAT, SIREN, register immatriculation) or a company name. The scheme is auto-detected; an empty q is a 400. A search NEVER renders not_found as non-compliance - an unsearchable register cell is labelled not_searchable_by_this_identifier.

countryqueryoptional

Optional ISO-2 country to narrow the coverage summary; accepted for forward-compat (the backbone match itself is country-agnostic).

streamqueryoptional

Optional waste stream to narrow the coverage summary; accepted for forward-compat.

Responses

200SuccessEntitySearchEnvelope

400Malformed request (e.g. an invalid as_of/from/to query parameter)Problem

401UnauthenticatedProblem

GET/v1/entities/{entityId}

Read the entity profile (public node + the tenant's own overlay)Bearer key required

Parameters

entityIdpathrequired

Responses

200SuccessEntityProfileEnvelope

401UnauthenticatedProblem

404Not foundProblem

Schemas

The request and response payload shapes referenced above, as JSON Schema.

EnvelopeMeta

{
  "type": "object",
  "required": [
    "checked_at",
    "ruleset_version",
    "coverage_mode_per_register",
    "legal"
  ],
  "properties": {
    "checked_at": {
      "type": "string",
      "format": "date-time"
    },
    "ruleset_version": {
      "type": "string"
    },
    "coverage_mode_per_register": {
      "type": "object",
      "additionalProperties": {
        "type": "string",
        "enum": [
          "live",
          "ramping",
          "manual"
        ]
      },
      "description": "Modes for the registers relevant to this response (the country/stream cells the operation acted on) when determinable, else the full register matrix. The same seller and scope yield the same map on POST /verifications and GET /sellers/{sellerId}/status."
    },
    "legal": {
      "type": "string",
      "const": "Verification evidence under best-efforts standard; registers remain the authoritative sources."
    }
  }
}

Problem

{
  "type": "object",
  "required": [
    "type",
    "title",
    "status",
    "detail"
  ],
  "properties": {
    "type": {
      "type": "string"
    },
    "title": {
      "type": "string"
    },
    "status": {
      "type": "integer"
    },
    "detail": {
      "type": "string"
    }
  },
  "additionalProperties": true
}

PostSellerBody

{
  "type": "object",
  "required": [
    "external_id",
    "legal_name"
  ],
  "additionalProperties": false,
  "properties": {
    "external_id": {
      "type": "string"
    },
    "legal_name": {
      "type": "string"
    },
    "vat_id": {
      "type": "string"
    },
    "country_of_establishment": {
      "type": "string"
    },
    "marketplaces": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

Seller

{
  "type": "object",
  "required": [
    "id",
    "external_id",
    "legal_name",
    "marketplaces"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "external_id": {
      "type": "string"
    },
    "legal_name": {
      "type": "string"
    },
    "vat_id": {
      "type": "string"
    },
    "country_of_establishment": {
      "type": "string"
    },
    "marketplaces": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

SellerEnvelope

{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Seller"
    },
    "meta": {
      "$ref": "#/components/schemas/EnvelopeMeta"
    }
  }
}

PostRegistrationsBody

{
  "type": "object",
  "required": [
    "registrations"
  ],
  "additionalProperties": false,
  "properties": {
    "registrations": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": [
          "country",
          "stream",
          "number",
          "source"
        ],
        "additionalProperties": false,
        "properties": {
          "country": {
            "type": "string",
            "enum": [
              "DE",
              "FR",
              "AT",
              "ES",
              "NL",
              "BE",
              "IT",
              "PL",
              "IE",
              "SE",
              "CZ",
              "GB",
              "EE",
              "SI",
              "SK",
              "FI",
              "PT"
            ]
          },
          "stream": {
            "type": "string",
            "enum": [
              "packaging",
              "weee",
              "batteries",
              "sup",
              "textiles"
            ]
          },
          "number": {
            "type": "string"
          },
          "source": {
            "type": "string",
            "enum": [
              "declared",
              "collected",
              "imported"
            ]
          }
        }
      }
    }
  }
}

Registrations

{
  "type": "object",
  "required": [
    "registrations"
  ],
  "properties": {
    "registrations": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "country",
          "stream",
          "number_normalized",
          "source",
          "format_provisional"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "country": {
            "type": "string",
            "enum": [
              "DE",
              "FR",
              "AT",
              "ES",
              "NL",
              "BE",
              "IT",
              "PL",
              "IE",
              "SE",
              "CZ",
              "GB",
              "EE",
              "SI",
              "SK",
              "FI",
              "PT"
            ]
          },
          "stream": {
            "type": "string",
            "enum": [
              "packaging",
              "weee",
              "batteries",
              "sup",
              "textiles"
            ]
          },
          "number_normalized": {
            "type": "string"
          },
          "source": {
            "type": "string"
          },
          "format_provisional": {
            "type": "boolean"
          }
        }
      }
    }
  }
}

RegistrationsEnvelope

{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Registrations"
    },
    "meta": {
      "$ref": "#/components/schemas/EnvelopeMeta"
    }
  }
}

PostSkusBody

{
  "type": "object",
  "required": [
    "skus"
  ],
  "additionalProperties": false,
  "properties": {
    "skus": {
      "type": "array",
      "minItems": 1,
      "items": {
        "type": "object",
        "required": [
          "ref",
          "attributes"
        ],
        "additionalProperties": false,
        "properties": {
          "ref": {
            "type": "string"
          },
          "attributes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "packaging",
                "electrical_electronic",
                "battery",
                "single_use_plastic",
                "textile"
              ]
            }
          },
          "market_sold_into": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "DE",
                "FR",
                "AT",
                "ES",
                "NL",
                "BE",
                "IT",
                "PL",
                "IE",
                "SE",
                "CZ",
                "GB",
                "EE",
                "SI",
                "SK",
                "FI",
                "PT"
              ]
            }
          }
        }
      }
    }
  }
}

Skus

{
  "type": "object",
  "required": [
    "skus"
  ],
  "properties": {
    "skus": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "id",
          "seller_id",
          "ref",
          "attributes",
          "updated_at"
        ],
        "properties": {
          "id": {
            "type": "string"
          },
          "seller_id": {
            "type": "string"
          },
          "ref": {
            "type": "string"
          },
          "attributes": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "packaging",
                "electrical_electronic",
                "battery",
                "single_use_plastic",
                "textile"
              ]
            }
          },
          "market_sold_into": {
            "type": "array",
            "items": {
              "type": "string",
              "enum": [
                "DE",
                "FR",
                "AT",
                "ES",
                "NL",
                "BE",
                "IT",
                "PL",
                "IE",
                "SE",
                "CZ",
                "GB",
                "EE",
                "SI",
                "SK",
                "FI",
                "PT"
              ]
            }
          },
          "updated_at": {
            "type": "string",
            "format": "date-time"
          }
        }
      }
    }
  }
}

SkusEnvelope

{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Skus"
    },
    "meta": {
      "$ref": "#/components/schemas/EnvelopeMeta"
    }
  }
}

PostVerificationBody

{
  "type": "object",
  "required": [
    "seller_id",
    "scope"
  ],
  "additionalProperties": false,
  "properties": {
    "seller_id": {
      "type": "string"
    },
    "scope": {
      "oneOf": [
        {
          "type": "string",
          "const": "auto"
        },
        {
          "type": "array",
          "minItems": 1,
          "items": {
            "type": "object",
            "required": [
              "country",
              "stream"
            ],
            "additionalProperties": false,
            "properties": {
              "country": {
                "type": "string",
                "enum": [
                  "DE",
                  "FR",
                  "AT",
                  "ES",
                  "NL",
                  "BE",
                  "IT",
                  "PL",
                  "IE",
                  "SE",
                  "CZ",
                  "GB",
                  "EE",
                  "SI",
                  "SK",
                  "FI",
                  "PT"
                ]
              },
              "stream": {
                "type": "string",
                "enum": [
                  "packaging",
                  "weee",
                  "batteries",
                  "sup",
                  "textiles"
                ]
              }
            }
          }
        }
      ]
    },
    "countries_sold_into": {
      "type": "array",
      "items": {
        "type": "string",
        "enum": [
          "DE",
          "FR",
          "AT",
          "ES",
          "NL",
          "BE",
          "IT",
          "PL",
          "IE",
          "SE",
          "CZ",
          "GB",
          "EE",
          "SI",
          "SK",
          "FI",
          "PT"
        ]
      }
    }
  }
}

VerificationRecord

{
  "type": "object",
  "required": [
    "id",
    "seller_id",
    "country",
    "stream",
    "verdict",
    "registers_consulted",
    "ruleset_version",
    "checked_at",
    "basis",
    "notes"
  ],
  "properties": {
    "id": {
      "type": "string"
    },
    "seller_id": {
      "type": "string"
    },
    "country": {
      "type": "string",
      "enum": [
        "DE",
        "FR",
        "AT",
        "ES",
        "NL",
        "BE",
        "IT",
        "PL",
        "IE",
        "SE",
        "CZ",
        "GB",
        "EE",
        "SI",
        "SK",
        "FI",
        "PT"
      ]
    },
    "stream": {
      "type": "string",
      "enum": [
        "packaging",
        "weee",
        "batteries",
        "sup",
        "textiles"
      ]
    },
    "verdict": {
      "type": "string",
      "enum": [
        "verified",
        "collection_pending",
        "not_found",
        "mismatch",
        "revoked_or_expired",
        "unverifiable_register_pending",
        "manual_review"
      ]
    },
    "registers_consulted": {
      "type": "array",
      "items": {
        "type": "object"
      }
    },
    "ruleset_version": {
      "type": "string"
    },
    "checked_at": {
      "type": "string",
      "format": "date-time"
    },
    "basis": {
      "type": "object"
    },
    "match": {
      "type": [
        "object",
        "null"
      ]
    },
    "notes": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

Verifications

{
  "type": "object",
  "required": [
    "records",
    "orphaned_declarations"
  ],
  "properties": {
    "records": {
      "type": "array",
      "items": {
        "$ref": "#/components/schemas/VerificationRecord"
      }
    },
    "orphaned_declarations": {
      "type": "array",
      "items": {
        "type": "object"
      }
    }
  }
}

VerificationsEnvelope

{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Verifications"
    },
    "meta": {
      "$ref": "#/components/schemas/EnvelopeMeta"
    }
  }
}

VerificationRecordData

{
  "type": "object",
  "required": [
    "record"
  ],
  "properties": {
    "record": {
      "$ref": "#/components/schemas/VerificationRecord"
    }
  }
}

VerificationRecordEnvelope

{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/VerificationRecordData"
    },
    "meta": {
      "$ref": "#/components/schemas/EnvelopeMeta"
    }
  }
}

Status

{
  "type": "object",
  "required": [
    "seller_id",
    "cells"
  ],
  "properties": {
    "seller_id": {
      "type": "string"
    },
    "cells": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "country",
          "stream",
          "verdict",
          "last_record_id"
        ],
        "properties": {
          "country": {
            "type": "string",
            "enum": [
              "DE",
              "FR",
              "AT",
              "ES",
              "NL",
              "BE",
              "IT",
              "PL",
              "IE",
              "SE",
              "CZ",
              "GB",
              "EE",
              "SI",
              "SK",
              "FI",
              "PT"
            ]
          },
          "stream": {
            "type": "string",
            "enum": [
              "packaging",
              "weee",
              "batteries",
              "sup",
              "textiles"
            ]
          },
          "verdict": {
            "type": "string",
            "enum": [
              "verified",
              "collection_pending",
              "not_found",
              "mismatch",
              "revoked_or_expired",
              "unverifiable_register_pending",
              "manual_review"
            ]
          },
          "last_record_id": {
            "type": "string"
          }
        }
      }
    }
  }
}

StatusEnvelope

{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Status"
    },
    "meta": {
      "$ref": "#/components/schemas/EnvelopeMeta"
    }
  }
}

Timeline

{
  "type": "object",
  "required": [
    "seller_id",
    "transitions",
    "confirmations"
  ],
  "properties": {
    "seller_id": {
      "type": "string"
    },
    "transitions": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "country",
          "stream",
          "from_verdict",
          "to_verdict",
          "at",
          "record_id"
        ],
        "properties": {
          "country": {
            "type": "string",
            "enum": [
              "DE",
              "FR",
              "AT",
              "ES",
              "NL",
              "BE",
              "IT",
              "PL",
              "IE",
              "SE",
              "CZ",
              "GB",
              "EE",
              "SI",
              "SK",
              "FI",
              "PT"
            ]
          },
          "stream": {
            "type": "string",
            "enum": [
              "packaging",
              "weee",
              "batteries",
              "sup",
              "textiles"
            ]
          },
          "from_verdict": {
            "oneOf": [
              {
                "type": "string",
                "enum": [
                  "verified",
                  "collection_pending",
                  "not_found",
                  "mismatch",
                  "revoked_or_expired",
                  "unverifiable_register_pending",
                  "manual_review"
                ]
              },
              {
                "type": "null"
              }
            ]
          },
          "to_verdict": {
            "type": "string",
            "enum": [
              "verified",
              "collection_pending",
              "not_found",
              "mismatch",
              "revoked_or_expired",
              "unverifiable_register_pending",
              "manual_review"
            ]
          },
          "at": {
            "type": "string",
            "format": "date-time"
          },
          "record_id": {
            "type": "string"
          }
        }
      }
    },
    "confirmations": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "country",
          "stream",
          "confirmations"
        ],
        "properties": {
          "country": {
            "type": "string",
            "enum": [
              "DE",
              "FR",
              "AT",
              "ES",
              "NL",
              "BE",
              "IT",
              "PL",
              "IE",
              "SE",
              "CZ",
              "GB",
              "EE",
              "SI",
              "SK",
              "FI",
              "PT"
            ]
          },
          "stream": {
            "type": "string",
            "enum": [
              "packaging",
              "weee",
              "batteries",
              "sup",
              "textiles"
            ]
          },
          "confirmations": {
            "type": "integer"
          }
        }
      }
    }
  }
}

TimelineEnvelope

{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Timeline"
    },
    "meta": {
      "$ref": "#/components/schemas/EnvelopeMeta"
    }
  }
}

Coverage

{
  "type": "object",
  "required": [
    "coverage"
  ],
  "properties": {
    "coverage": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "country",
          "stream",
          "mode"
        ],
        "properties": {
          "country": {
            "type": "string",
            "enum": [
              "DE",
              "FR",
              "AT",
              "ES",
              "NL",
              "BE",
              "IT",
              "PL",
              "IE",
              "SE",
              "CZ",
              "GB",
              "EE",
              "SI",
              "SK",
              "FI",
              "PT"
            ]
          },
          "stream": {
            "type": "string",
            "enum": [
              "packaging",
              "weee",
              "batteries",
              "sup",
              "textiles"
            ]
          },
          "register_id": {
            "type": "string"
          },
          "mode": {
            "type": "string",
            "enum": [
              "live",
              "ramping",
              "manual"
            ]
          },
          "last_capture_at": {
            "type": "string",
            "format": "date-time"
          },
          "freshness_slo_hours": {
            "type": "integer"
          }
        }
      }
    }
  }
}

CoverageEnvelope

{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/Coverage"
    },
    "meta": {
      "$ref": "#/components/schemas/EnvelopeMeta"
    }
  }
}

EntitySearch

{
  "type": "object",
  "required": [
    "query",
    "queried_scheme",
    "results"
  ],
  "properties": {
    "query": {
      "type": "string"
    },
    "queried_scheme": {
      "type": "string",
      "enum": [
        "vat",
        "siren",
        "siret",
        "national",
        "register",
        "name_country"
      ]
    },
    "results": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "entity_id",
          "display_name",
          "name_is_identifier",
          "matched_scheme",
          "score",
          "coverage_summary",
          "origin"
        ],
        "properties": {
          "entity_id": {
            "type": "string"
          },
          "display_name": {
            "type": "string"
          },
          "display_country": {
            "type": "string",
            "enum": [
              "DE",
              "FR",
              "AT",
              "ES",
              "NL",
              "BE",
              "IT",
              "PL",
              "IE",
              "SE",
              "CZ",
              "GB",
              "EE",
              "SI",
              "SK",
              "FI",
              "PT"
            ]
          },
          "name_is_identifier": {
            "type": "boolean"
          },
          "matched_scheme": {
            "type": "string",
            "enum": [
              "vat",
              "siren",
              "siret",
              "national",
              "register",
              "name_country"
            ]
          },
          "score": {
            "type": "number"
          },
          "coverage_summary": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "state",
                "count"
              ],
              "properties": {
                "state": {
                  "type": "string",
                  "enum": [
                    "found",
                    "not_found",
                    "not_searchable_by_this_identifier",
                    "registry_unavailable",
                    "manual_evidence_required",
                    "not_applicable",
                    "unknown"
                  ]
                },
                "count": {
                  "type": "integer"
                }
              }
            }
          },
          "origin": {
            "type": "string",
            "enum": [
              "backbone",
              "registers"
            ]
          },
          "register_presence": {
            "type": "array",
            "items": {
              "type": "object",
              "required": [
                "register_id",
                "country",
                "streams",
                "status_category",
                "captured_at",
                "registration_number"
              ],
              "properties": {
                "register_id": {
                  "type": "string"
                },
                "country": {
                  "type": "string",
                  "enum": [
                    "DE",
                    "FR",
                    "AT",
                    "ES",
                    "NL",
                    "BE",
                    "IT",
                    "PL",
                    "IE",
                    "SE",
                    "CZ",
                    "GB",
                    "EE",
                    "SI",
                    "SK",
                    "FI",
                    "PT"
                  ]
                },
                "streams": {
                  "type": "array",
                  "items": {
                    "type": "string"
                  }
                },
                "status_category": {
                  "type": "string"
                },
                "captured_at": {
                  "type": "string",
                  "format": "date-time"
                },
                "registration_number": {
                  "type": "string"
                }
              }
            }
          }
        }
      }
    }
  }
}

EntitySearchEnvelope

{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/EntitySearch"
    },
    "meta": {
      "$ref": "#/components/schemas/EnvelopeMeta"
    }
  }
}

EntityProfile

{
  "type": "object",
  "required": [
    "entity_id",
    "display_name",
    "name_is_identifier",
    "identifiers",
    "coverage",
    "sellers",
    "evidence_refs"
  ],
  "properties": {
    "entity_id": {
      "type": "string"
    },
    "display_name": {
      "type": "string"
    },
    "display_country": {
      "type": "string",
      "enum": [
        "DE",
        "FR",
        "AT",
        "ES",
        "NL",
        "BE",
        "IT",
        "PL",
        "IE",
        "SE",
        "CZ",
        "GB",
        "EE",
        "SI",
        "SK",
        "FI",
        "PT"
      ]
    },
    "name_is_identifier": {
      "type": "boolean"
    },
    "identifiers": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "scheme",
          "value",
          "raw"
        ],
        "properties": {
          "scheme": {
            "type": "string",
            "enum": [
              "vat",
              "siren",
              "siret",
              "national",
              "register",
              "name_country"
            ]
          },
          "value": {
            "type": "string"
          },
          "raw": {
            "type": "string"
          },
          "country": {
            "type": "string",
            "enum": [
              "DE",
              "FR",
              "AT",
              "ES",
              "NL",
              "BE",
              "IT",
              "PL",
              "IE",
              "SE",
              "CZ",
              "GB",
              "EE",
              "SI",
              "SK",
              "FI",
              "PT"
            ]
          }
        }
      }
    },
    "coverage": {
      "type": "object",
      "required": [
        "countries",
        "streams",
        "cells"
      ],
      "properties": {
        "countries": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "DE",
              "FR",
              "AT",
              "ES",
              "NL",
              "BE",
              "IT",
              "PL",
              "IE",
              "SE",
              "CZ",
              "GB",
              "EE",
              "SI",
              "SK",
              "FI",
              "PT"
            ]
          }
        },
        "streams": {
          "type": "array",
          "items": {
            "type": "string",
            "enum": [
              "packaging",
              "weee",
              "batteries",
              "sup",
              "textiles"
            ]
          }
        },
        "cells": {
          "type": "array",
          "items": {
            "type": "object",
            "required": [
              "country",
              "stream",
              "state"
            ],
            "properties": {
              "country": {
                "type": "string",
                "enum": [
                  "DE",
                  "FR",
                  "AT",
                  "ES",
                  "NL",
                  "BE",
                  "IT",
                  "PL",
                  "IE",
                  "SE",
                  "CZ",
                  "GB",
                  "EE",
                  "SI",
                  "SK",
                  "FI",
                  "PT"
                ]
              },
              "stream": {
                "type": "string",
                "enum": [
                  "packaging",
                  "weee",
                  "batteries",
                  "sup",
                  "textiles"
                ]
              },
              "state": {
                "type": "string",
                "enum": [
                  "found",
                  "not_found",
                  "not_searchable_by_this_identifier",
                  "registry_unavailable",
                  "manual_evidence_required",
                  "not_applicable",
                  "unknown"
                ]
              },
              "verdict": {
                "type": "string",
                "enum": [
                  "verified",
                  "collection_pending",
                  "not_found",
                  "mismatch",
                  "revoked_or_expired",
                  "unverifiable_register_pending",
                  "manual_review"
                ]
              },
              "record_id": {
                "type": "string"
              }
            }
          }
        }
      }
    },
    "worst_verdict": {
      "type": "string",
      "enum": [
        "verified",
        "collection_pending",
        "not_found",
        "mismatch",
        "revoked_or_expired",
        "unverifiable_register_pending",
        "manual_review"
      ]
    },
    "sellers": {
      "type": "array",
      "items": {
        "type": "object",
        "required": [
          "seller_id",
          "legal_name",
          "matched_scheme"
        ],
        "properties": {
          "seller_id": {
            "type": "string"
          },
          "legal_name": {
            "type": "string"
          },
          "matched_scheme": {
            "type": "string",
            "enum": [
              "vat",
              "siren",
              "siret",
              "national",
              "register",
              "name_country"
            ]
          },
          "score": {
            "type": "number"
          }
        }
      }
    },
    "evidence_refs": {
      "type": "array",
      "items": {
        "type": "string"
      }
    }
  }
}

EntityProfileEnvelope

{
  "type": "object",
  "required": [
    "data",
    "meta"
  ],
  "properties": {
    "data": {
      "$ref": "#/components/schemas/EntityProfile"
    },
    "meta": {
      "$ref": "#/components/schemas/EnvelopeMeta"
    }
  }
}