Schemes Guide

Introduction

This guide aims to provide a clear and comprehensive overview of the various identification schemes (scheme) that govern company codes via the B2Brouter API. It explains the concepts of TIN, CIN, PIN, and taxcode, as well as the EAS and ICD schemes and the country field, so that any integrator knows exactly what information to supply in each scenario.

Every official company identification number has a corresponding scheme to indicate the type of TIN, CIN, or PIN it represents.

You can review each identifier using the GET /users/schemes.{format} endpoint, which returns the scheme number, whether it is a fiscal identifier, and whether it is included in the valid identifiers lists for EAS and ICD.

Example Response from /users/schemes Endpoint:

{
  "code": "9914",
  "name": "UID",
  "country": "at",
  "eas": true,
  "icd": false,
  "taxcode": true
}

• code: Scheme identification number (in this case 9914).
• name: Official name of the identifier (in this case UID).
• country: Country corresponding to the identifier (at for Austria).
• eas: Indicates if it belongs to the EAS list (in this case true).
• icd: Indicates if it belongs to the ICD list (in this case false).
• taxcode: Indicates whether the identifier is a TIN (true) or CIN (false). Here, true means it is a TIN (Tax Identification Number).

Basic Definitions

TIN (Tax Identifier Number)

The primary fiscal identifier for a company, valid for both domestic and international invoicing. To verify whether an identifier is the Tax Identifier Number for a given country, use the B2Brouter schemes endpoint.

For Europe, the VIES portal validates identifiers of EU member states. All European TINs begin with the country’s ISO code.

If "taxcode": true, the identifier is considered a TIN and can be used for fiscal invoicing.

Examples:

1. German VAT ID:

   JSON

   "tin_scheme": 9930,
   "tin_value": "DE123456789"
   

2. Spanish NIF:

   JSON

   "tin_scheme": 9920,
   "tin_value": "ESB12345678"
   

3. French VAT number:

   JSON

   "tin_scheme": 9957,
   "tin_value": "FR12345678901"
   

4. Italian Partita IVA:

   JSON

   "tin_scheme": 9906,
   "tin_value": "IT12345678901"
   

Note: If the ISO 3166-1 alpha-2 country code is not already included in the tin_value, it will be automatically prepended when saving a TIN.

CIN (Company Identifier Number)

Any valid company identifier other than the Tax Identifier Number, such as identifiers for subdivisions, public administrations, bank accounts, etc. To create an account or contact without specifying a TIN, set "taxcode": false. All schemes with taxcode: false are treated as CINs. A company can have multiple CINs.

Examples:

1. French SIRET:

   JSON

   "cin_scheme": 0009,
   "cin_value": "1234567890"
   

2. Global Location Number (GLN):

   JSON

   "cin_scheme": 0088,
   "cin_value": "1234567890"
   

3. Swedish Organisationsnummer:

   JSON

   "cin_scheme": 0007,
   "cin_value": "1234567890"
   

Note: In Sweden, to invoice at the fiscal level you must enable the registered_for_empl_tax boolean once approved for F-tax.

PIN (Peppol Identifier Number)

Used for the business terms “Seller electronic address ID” (BT‑34) and “Buyer electronic address ID” (BT‑49), where scheme indicates the identifying scheme (e.g., KVK with code 0088).

The company identifier used as the Peppol mailbox address. A PIN can be either a TIN or a CIN, provided it appears in the EAS list. You may retrieve PINs via the schemes endpoint. A company can have multiple PINs and connect to Peppol through multiple billing software.

Implementation:

• Peppol Transport: Add your PIN in the Transports settings by enabling your Peppol connection.
  API Reference - POST create-transport
• Contacts and Invoices: Specify a PIN when creating the contact or directly on the invoice.
  API Reference - POST create-contact
  Example:

"pin_scheme": 0208,
"pin_value": "BCE/KBO/ZDU"

Supported Schemes

1. EAS (EN 16931 – Electronic Address Scheme)
   Official list of electronic address identifier schemes recognized by the European e‑invoicing standard (EN 16931). Maintained by Digital Europe (successor to CEF since January 2022) and updated twice yearly to add new schemes or ISO 6523 ICD‑registered codes relevant to electronic addressing. This list enables new Peppol identifiers.

2. ICD (ISO 6523 – International Code Designator)
   Global registry of entity identifier schemes maintained by ISO. Each assigning authority (e.g., government registries or coding services) has a unique numeric code (ICD). This serves as the basis for unique organization identification worldwide, including Peppol. Many EAS schemes come from this catalog, since only ISO 6523 entries can be promoted to EAS.

   Examples:

   • DUNS Number (D&B – global):

     JSON

     "cin_scheme": "0060",
     "cin_value": "123456789"
     

   • French SIRENE:

     JSON

     "cin_scheme": "0002",
     "cin_value": "12345678900000"
     

3. B2Brouter Internal Schemes
   For countries without official ISO 6523 ICD or EAS entries, B2Brouter defines internal schemes. These numeric codes start with 8XXX and allow fiscal or commercial identifiers not covered by any global registry. Note that these codes may be temporary until an official scheme is approved.

4. Universal Scheme (0001)
   A generic fallback scheme for cases where a company’s fiscal ID does not belong to any recognized official scheme (EAS, ISO 6523 ICD, or internal). Can be used as tin_scheme or cin_scheme for national or commercial identifiers without formal assignment.

   Warning: Avoid using scheme 0001 whenever possible. It may cause validation or legal issues if authorities require officially regulated coding. Always verify if an official scheme exists first.

API Usage Examples

1. Create a Peppol Transport
   POST /accounts/{account}/transports

   JSON

   {
     "transport": {
       "code": "peppol",
       "enabled": true,
       "reception": true,
       "pin_scheme": 9934,
       "pin_value": "123456789"
     }
   }
   

2. Create an Account with CIN
   POST /accounts

   JSON

   {
     "name": "Example B.V.",
     "cin_scheme": "0106",
     "cin_value": "12345678",
     "country": "nl",
     "address": "Uitgevonden Straat 123",
     "city": "Amsterdam",
     "postalcode": "1015 BS",
     "email": "[email protected]"
   }
   

3. Lookup Directory by Scheme
   GET /api/v1/directory/{scheme}/{value}.json

   Shell

   curl --request GET \
        --url https://app-staging.b2brouter.net/api/v1/directory/9920/ESP0801900B.json \
        --header 'X-B2B-API-Key: {YOUR_API_KEY}' \
        --header 'accept: application/json'
   

Resources

1. API Reference for Lookup “Schemes”: https://developer.b2brouter.net/reference/get-schemes
2. EAS Codes List (EN 16931): https://peppol.eu/specs/eas
3. ICD Codes List (ISO 6523): https://docs.peppol.eu/poacc/billing/3.0/codelist/ICD/
4. VIES Portal for EU VAT ID Validation: https://ec.europa.eu/taxation_customs/vies/#/vat-validation