Admin API - e-invoice.be

The Admin API is only available to resellers with an organization API key. This is a privileged API for managing multiple customer tenants. If you’re looking for standard invoice operations, see the regular API documentation.

Overview

The Admin API enables resellers to programmatically manage customer organizations (tenants), provision API credentials, and handle Peppol network registration on behalf of customers. This is separate from the standard e-invoice.be API and uses different authentication.

Key Capabilities

Tenant Management - Create and manage customer organizations
API Key Provisioning - Generate and manage API keys for customers
Peppol Registration - Register customers on the Peppol network
Credential Rotation - Update and revoke API keys without customer involvement

Authentication

The Admin API requires an organization API key (also called admin API key), which is different from standard tenant API keys.

curl -X GET "https://api.e-invoice.be/api/admin/tenants" \
     -H "Authorization: Bearer YOUR_ORGANIZATION_API_KEY"

Organization API keys are only provided to approved resellers. Contact support@e-invoice.be to discuss the reseller programme.

Tenant Management

List All Tenants

Retrieve all customer organizations under your reseller account:

curl -X GET "https://api.e-invoice.be/api/admin/tenants?skip=0&limit=100" \
     -H "Authorization: Bearer YOUR_ORGANIZATION_API_KEY"

Query Parameters:

skip - Number of records to skip (default: 0)
limit - Maximum records to return (default: 100)

Response:

{
  "tenants": [
    {
      "id": "ten-9k2m4p7q3w5x8r",
      "name": "customer-company-bvba",
      "description": "Customer Company BVBA",
      "created_at": "2026-04-16T10:00:00.000000Z",
      "updated_at": "2026-04-16T10:00:00.000000Z",
      "is_deleted": false
    }
  ],
  "total": 1
}

Create a Tenant

Create a new customer organization:

curl -X POST "https://api.e-invoice.be/api/admin/tenants" \
     -H "Authorization: Bearer YOUR_ORGANIZATION_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "customer-company-bvba",
       "description": "Customer Company BVBA - Accounting Software Integration",
       "company_number": "0123456789",
       "company_tax_id": "BE0123456789",
       "peppol_ids": ["0208:0123456789"]
     }'

Request Body:

name (required) - Unique identifier for the tenant (lowercase, no spaces)
description (optional) - Human-readable description
company_number (optional) - Company registration number (e.g., CBE/KBO for Belgium, KvK for Netherlands, RCS for Luxembourg)
company_tax_id (optional) - Tax identification number (e.g., VAT number like BE0123456789)
peppol_ids (recommended) - Array containing the tenant’s Peppol ID

Response (201 Created):

{
  "id": "ten-9k2m4p7q3w5x8r",
  "name": "customer-company-bvba",
  "description": "Customer Company BVBA - Accounting Software Integration",
  "company_number": "0123456789",
  "company_tax_id": "BE0123456789",
  "peppol_ids": ["0208:0123456789"],
  "created_at": "2026-04-16T10:00:00.000000Z",
  "updated_at": "2026-04-16T10:00:00.000000Z",
  "is_deleted": false
}

You are responsible for determining and setting the correct Peppol ID for each tenant. Although peppol_ids is an array, the platform currently only supports a single Peppol ID per tenant. Setting the Peppol ID at tenant creation is important for proper Peppol registration later.

Company Number vs Tax ID

The tenant schema now separates company registration identifiers:

company_number - The official company registration number from the national business register:
- Belgium: CBE/KBO number (e.g., 0123456789)
- Netherlands: KvK number (Chamber of Commerce)
- Luxembourg: RCS number (Registre de Commerce et des Sociétés)
- Other countries: Equivalent business registration number
company_tax_id - The actual VAT or tax identification number:
- Format includes country prefix (e.g., BE0123456789, NL123456789B01)
- Used for tax purposes and invoicing
- May be different from the company number in some jurisdictions

For Belgian companies, the CBE number (without “BE” prefix) is typically used in the Peppol ID as 0208:<CBE number>, while the full VAT number (with “BE” prefix) goes in company_tax_id.

Peppol ID Format

The Peppol ID follows the format scheme:identifier: Belgium (most common):

Format: 0208:<CBE number>
Example: 0208:0123456789

For Belgian companies, use scheme 0208 with the CBE/KBO number (enterprise number). Example relationship:

company_number: 0123456789 (CBE number)
company_tax_id: BE0123456789 (VAT number)
peppol_ids: ["0208:0123456789"] (scheme 0208 + CBE number)

Other schemes:

9999 - DUNS number (international)
0088 - Global Location Number (GLN)
0184 - Dutch KVK number
9956 - Belgian company number (alternative)

Why Set Peppol ID During Creation?

The Peppol ID is used when:

Registering on the SMP (Service Metadata Publisher) - Maps the Peppol ID to e-invoice.be’s access point
Writing to the Peppol Directory - Creates a searchable entry for participant lookup
Routing documents - Ensures incoming invoices reach the correct tenant

Every tenant must have exactly one associated Peppol ID. Setting it during tenant creation ensures the tenant is properly configured before Peppol registration.

Use a consistent naming convention for tenant names, such as customer-slug or company-id. This makes it easier to manage multiple customers.

Get a Tenant

Retrieve details for a specific tenant:

curl -X GET "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r" \
     -H "Authorization: Bearer YOUR_ORGANIZATION_API_KEY"

Update a Tenant

Update tenant information:

curl -X PUT "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r" \
     -H "Authorization: Bearer YOUR_ORGANIZATION_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "customer-company-bvba",
       "description": "Updated description",
       "company_number": "0123456789",
       "company_tax_id": "BE0123456789",
       "peppol_ids": ["0208:0123456789"]
     }'

You can update the company_number, company_tax_id, and peppol_ids fields after tenant creation if needed.

Delete a Tenant

Soft-delete a tenant (marks as deleted, doesn’t remove data):

curl -X DELETE "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r" \
     -H "Authorization: Bearer YOUR_ORGANIZATION_API_KEY"

API Key Management

Provision and manage API keys for customer tenants.

Create an API Key

Generate a new API key for a tenant:

curl -X POST "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r/api-keys" \
     -H "Authorization: Bearer YOUR_ORGANIZATION_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "production-key",
       "description": "Production API key for Customer Company"
     }'

Request Body:

name (required) - Identifier for the API key
description (optional) - Purpose or environment

Response:

{
  "id": "api-3h8f5j2k9l4m7n6p1q5r8s2t4v6w9x3y",
  "tenant_id": "ten-9k2m4p7q3w5x8r",
  "name": "production-key",
  "description": "Production API key for Customer Company",
  "created_at": "2026-04-16T10:00:00.000000Z",
  "updated_at": "2026-04-16T10:00:00.000000Z",
  "is_deleted": false
}

The id field IS the API key. There is no separate key field — the value returned in id (e.g. api-3h8f5j2k9l4m7n6p1q5r8s2t4v6w9x3y) is the bearer token your customer must include in the Authorization header of every API request:

Authorization: Bearer api-3h8f5j2k9l4m7n6p1q5r8s2t4v6w9x3y

Treat the id as a secret. Capture it on creation, store it securely (e.g. encrypted at rest), and deliver it to your customer over a secure channel. Never log it, commit it to version control, or expose it in client-side code.

List API Keys

Get all API keys for a tenant:

curl -X GET "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r/api-keys?limit=100" \
     -H "Authorization: Bearer YOUR_ORGANIZATION_API_KEY"

Response:

{
  "api_keys": [
    {
      "id": "api-3h8f5j2k9l4m7n6p1q5r8s2t4v6w9x3y",
      "tenant_id": "ten-9k2m4p7q3w5x8r",
      "name": "production-key",
      "description": "Production API key",
      "created_at": "2026-04-16T10:00:00.000000Z",
      "updated_at": "2026-04-16T10:00:00.000000Z",
      "is_deleted": false
    }
  ],
  "total": 1
}

Because the id is itself the bearer token, listing API keys returns the live credentials for this tenant. Treat the response as sensitive credential material: restrict who can call this endpoint, avoid logging the response body, and never return it to end users.

Get Latest API Key

Retrieve the most recently created API key for a tenant:

curl -X GET "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r/api-keys/latest" \
     -H "Authorization: Bearer YOUR_ORGANIZATION_API_KEY"

Update an API Key

Update API key metadata (name/description):

curl -X PUT "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r/api-keys/api-3h8f5j2k9l4m7n6p1q5r8s2t4v6w9x3y" \
     -H "Authorization: Bearer YOUR_ORGANIZATION_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "name": "production-key-v2",
       "description": "Updated production key"
     }'

Revoke an API Key

Delete (revoke) an API key:

curl -X DELETE "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r/api-keys/api-3h8f5j2k9l4m7n6p1q5r8s2t4v6w9x3y" \
     -H "Authorization: Bearer YOUR_ORGANIZATION_API_KEY"

For credential rotation, create a new API key, update your customer’s configuration, then revoke the old key.

Peppol Registration

Manage Peppol network registration for customer tenants.

Check Registration Status

Check if a tenant is registered on Peppol:

curl -X GET "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r/peppol/" \
     -H "Authorization: Bearer YOUR_ORGANIZATION_API_KEY"

Response:

{
  "peppol_id": "0208:0123456789",
  "state": "e-invoice",
  "smp": {
    "service_group": {
      "participant_identifier": "0123456789",
      "participant_scheme": "0208",
      "service_metadata_references": []
    },
    "business_card": {
      "participant_identifier": "0123456789",
      "participant_scheme": "0208",
      "business_entity": { "name": "Your Company BV", "country_code": "BE" }
    },
    "document_types": [
      {
        "document_type_code": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice",
        "process_identifier": "urn:fdc:peppol.eu:2017:poacc:billing:01:1.0"
      }
    ]
  },
  "last_checked_at": "2026-04-16T10:00:00.000000Z"
}

state reflects the SMP registration status: not_registered, e-invoice (registered on our SMP), or other. smp is a structured object describing the SMP service group, business card, and supported document types (null when not registered).

Register on Peppol

curl -X POST "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r/peppol/register" \
     -H "Authorization: Bearer YOUR_ORGANIZATION_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "peppol_id": "0208:0123456789",
       "company_name": "Customer Company BVBA"
     }'

For Belgian companies, the system can automatically fetch company data from KBO (Crossroads Bank for Enterprises):

curl -X POST "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r/peppol/register" \
     -H "Authorization: Bearer YOUR_ORGANIZATION_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "peppol_id": "0208:0123456789"
     }'

The system will:

Fetch company details from KBO using the CBE number
Register with the SMP (Service Metadata Publisher)
Create a business card on the Peppol network

Peppol operations are not available for organizations in test mode. Calling the Peppol endpoints for a test-mode organization returns 403 Forbidden. Ensure your organization is in production mode before attempting registration.

Update Business Card

Update the business card information on Peppol:

curl -X PUT "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r/peppol/business-card" \
     -H "Authorization: Bearer YOUR_ORGANIZATION_API_KEY" \
     -H "Content-Type: application/json" \
     -d '{
       "company_name": "Updated Company Name BVBA"
     }'

Currently, only company name updates are supported for business cards.

Unregister from Peppol

Remove a tenant from the Peppol network:

curl -X DELETE "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r/peppol/unregister" \
     -H "Authorization: Bearer YOUR_ORGANIZATION_API_KEY"

This will:

Remove SMP registration
Delete the business card
Mark the tenant as unregistered

Testing

Simulate an Inbound Document

Inject a UBL document into a tenant’s inbox as if it had been received over Peppol. This is the supported way to test a customer’s receive-side integration: the document is created in the RECEIVED state, appears in GET /api/inbox/, and any document.received webhooks configured on the tenant fire normally.

Simulation is only available for test-mode tenants. Calling this on a tenant that is not in test mode returns 400 Bad Request.

The request is multipart/form-data with the UBL XML supplied as a ubl_file field (not a raw XML request body). The receiver identifiers in the UBL should match the tenant you are simulating for.

curl -X POST "https://api.e-invoice.be/api/admin/tenants/ten-9k2m4p7q3w5x8r/simulate-inbound" \
     -H "Authorization: Bearer YOUR_ORGANIZATION_API_KEY" \
     -F "ubl_file=@invoice.xml"

Form fields:

ubl_file - The UBL Invoice or Credit Note XML file (required, max 25 MB)

Response (201 Created):

{
  "document_id": "doc-7h3k9m2p4q6r8t",
  "state": "RECEIVED"
}

The sender and receiver Peppol identifiers, document type (invoice vs. credit note), and line-item details are extracted from the uploaded UBL. Use the returned document_id with the standard document endpoints (for example GET /api/documents/{document_id}) to inspect the result.

This endpoint powers the Simulate inbound button shown in a test workspace’s inbox in the e-invoice.be app. See Testing Received Documents for the app-based workflow.

Complete Workflow Example

Here’s a complete Node.js example showing the typical reseller workflow:

const axios = require('axios');

const adminApi = axios.create({
  baseURL: 'https://api.e-invoice.be',
  headers: {
    'Authorization': `Bearer ${process.env.ORGANIZATION_API_KEY}`,
    'Content-Type': 'application/json'
  }
});

async function onboardNewCustomer(customerData) {
  try {
    // 1. Create tenant with company details and Peppol ID
    console.log('Creating tenant...');
    const tenant = await adminApi.post('/api/admin/tenants', {
      name: customerData.slug,
      description: customerData.companyName,
      company_number: customerData.companyNumber,
      company_tax_id: customerData.vatNumber,
      peppol_ids: [customerData.peppolId]
    });
    console.log('✓ Tenant created:', tenant.data.id);
    console.log('✓ Company number:', customerData.companyNumber);
    console.log('✓ Tax ID:', customerData.vatNumber);
    console.log('✓ Peppol ID set:', customerData.peppolId);

    // 2. Create API key for customer
    console.log('Generating API key...');
    const apiKey = await adminApi.post(
      `/api/admin/tenants/${tenant.data.id}/api-keys`,
      {
        name: 'production-key',
        description: 'Production API key'
      }
    );
    // IMPORTANT: The id IS the bearer token — capture it now and store it securely.
    // There is no separate `key` field, and you cannot retrieve the value again later.
    const customerApiKey = apiKey.data.id;
    console.log('✓ API key created (id IS the bearer token):', customerApiKey);

    // 3. Register on Peppol (for Belgian companies)
    console.log('Registering on Peppol...');
    const registration = await adminApi.post(
      `/api/admin/tenants/${tenant.data.id}/peppol/register`,
      {
        peppol_id: customerData.peppolId
      }
    );
    console.log('✓ Peppol registration complete');

    // 4. Return customer credentials
    return {
      tenantId: tenant.data.id,
      apiKey: customerApiKey,
      peppolId: customerData.peppolId,
      status: 'active'
    };

  } catch (error) {
    console.error('Onboarding failed:', error.response?.data || error.message);
    throw error;
  }
}

// Usage
const customerData = {
  slug: 'customer-company-bvba',
  companyName: 'Customer Company BVBA',
  companyNumber: '0123456789',  // CBE/KBO number
  vatNumber: 'BE0123456789',     // Full VAT number
  peppolId: '0208:0123456789'    // Peppol ID (scheme 0208 + CBE number)
};

onboardNewCustomer(customerData)
  .then(credentials => {
    console.log('Customer onboarded successfully:');
    console.log('- Tenant ID:', credentials.tenantId);
    console.log('- API Key:', credentials.apiKey);
    console.log('- Peppol ID:', credentials.peppolId);
  });

Key Rotation Example

Rotate API keys without customer downtime:

async function rotateApiKey(tenantId, oldKeyId) {
  try {
    // 1. Create new API key
    console.log('Creating new API key...');
    const newKey = await adminApi.post(
      `/api/admin/tenants/${tenantId}/api-keys`,
      {
        name: 'production-key-v2',
        description: 'Rotated production key'
      }
    );
    // The id IS the bearer token — capture it now; it cannot be retrieved later.
    const newApiKey = newKey.data.id;
    console.log('✓ New key created:', newApiKey);

    // 2. Provide new key to customer
    // (Send via secure channel, update their configuration)

    // 3. Wait for customer to switch over
    console.log('Waiting for customer to update configuration...');
    await new Promise(resolve => setTimeout(resolve, 3600000)); // 1 hour

    // 4. Revoke old key
    console.log('Revoking old API key...');
    await adminApi.delete(
      `/api/admin/tenants/${tenantId}/api-keys/${oldKeyId}`
    );
    console.log('✓ Old key revoked');

    return newKey.data;

  } catch (error) {
    console.error('Key rotation failed:', error.response?.data || error.message);
    throw error;
  }
}

Error Handling

Common error responses:

401 Unauthorized

{
  "detail": "Invalid authentication credentials"
}

Solution: Verify your organization API key is correct and active.

404 Not Found

{
  "detail": "Tenant not found"
}

Solution: Check the tenant ID is correct and the tenant exists.

409 Conflict

{
  "detail": "A tenant with similar name already exists"
}

Solution: Choose a different tenant name.

422 Validation Error

{
  "detail": [
    {
      "loc": ["body", "name"],
      "msg": "field required",
      "type": "value_error.missing"
    }
  ]
}

Solution: Ensure all required fields are provided.

Best Practices

Secure Key Management

Remember: the id returned from the create-key endpoint IS the bearer token. Treat it as a secret from the moment you receive it.
Never log or display organization API keys
Store customer API keys securely (encrypted database)
Provide keys to customers via secure channels only
Implement key rotation policies (e.g., every 90 days)

// ✓ Good: Secure handling — the id IS the bearer token
const encryptedKey = encrypt(apiKey.data.id);
await database.storeCustomerKey(customerId, encryptedKey);

// ✗ Bad: Insecure handling
console.log('API Key:', apiKey.data.id);
localStorage.setItem('key', apiKey.data.id);

Tenant Naming Convention

Use consistent, predictable tenant names:

// ✓ Good patterns
const tenantName = 'customer-company-bvba';
const tenantName = `cust-${customerId}`;
const tenantName = companyName.toLowerCase().replace(/\s+/g, '-');

// ✗ Bad patterns
const tenantName = 'Customer 1';
const tenantName = Math.random().toString();

Error Recovery

Implement idempotent operations and error recovery:

async function createTenantSafely(name, description) {
  try {
    return await adminApi.post('/api/admin/tenants', { name, description });
  } catch (error) {
    if (error.response?.status === 409) {
      // Tenant already exists, fetch it instead
      console.log('Tenant exists, fetching...');
      const tenants = await adminApi.get('/api/admin/tenants');
      return tenants.data.tenants.find(t => t.name === name);
    }
    throw error;
  }
}

Audit Logging

Log all admin operations for compliance:

async function auditedTenantCreate(tenantData) {
  const result = await adminApi.post('/api/admin/tenants', tenantData);

  await auditLog.create({
    action: 'TENANT_CREATE',
    tenant_id: result.data.id,
    admin_user: currentUser.id,
    timestamp: new Date(),
    details: { name: tenantData.name }
  });

  return result.data;
}

Peppol Registration Checks

Always verify registration prerequisites:

async function registerOnPeppol(tenantId, peppolId) {
  // 1. Verify Peppol ID format
  if (!/^\d{4}:\d+$/.test(peppolId)) {
    throw new Error('Invalid Peppol ID format');
  }

  // 2. Register. Peppol operations are gated at the organization
  // level: a test-mode organization gets 403 Forbidden here.
  return await adminApi.post(
    `/api/admin/tenants/${tenantId}/peppol/register`,
    { peppol_id: peppolId }
  );
}

Environment

The Admin API is available on the single API host:

Base URL
`https://api.e-invoice.be`

To test your integration before going live, create tenants in test mode (the API’s test Organization) and use their API keys. Test-mode tenants divert sends to email, support Simulate an Inbound Document, and never touch the Peppol network. See Environments for details.

Rate Limiting

Rate limits are applied per API key on write and validation endpoints (see API reference — Rate Limiting). When a limit is exceeded, the API returns 429 Too Many Requests with a Retry-After header. Honor Retry-After and use exponential backoff when driving bulk tenant operations.

Support

For Admin API access or technical questions:

Email: support@e-invoice.be
Reseller programme: Learn more

​Overview

​Key Capabilities

​Authentication

​Tenant Management

​List All Tenants

​Create a Tenant

​Company Number vs Tax ID

​Peppol ID Format

​Why Set Peppol ID During Creation?

​Get a Tenant

​Update a Tenant

​Delete a Tenant

​API Key Management

​Create an API Key

​List API Keys

​Get Latest API Key

​Update an API Key

​Revoke an API Key

​Peppol Registration

​Check Registration Status

​Register on Peppol

​Update Business Card

​Unregister from Peppol

​Testing

​Simulate an Inbound Document

​Complete Workflow Example

​Key Rotation Example

​Error Handling

​401 Unauthorized

​404 Not Found

​409 Conflict

​422 Validation Error

​Best Practices

​Environment

​Rate Limiting

​Support

​Related Documentation

Overview

Key Capabilities

Authentication

Tenant Management

List All Tenants

Create a Tenant

Company Number vs Tax ID

Peppol ID Format

Why Set Peppol ID During Creation?

Get a Tenant

Update a Tenant

Delete a Tenant

API Key Management

Create an API Key

List API Keys

Get Latest API Key

Update an API Key

Revoke an API Key

Peppol Registration

Check Registration Status

Register on Peppol

Update Business Card

Unregister from Peppol

Testing

Simulate an Inbound Document

Complete Workflow Example

Key Rotation Example

Error Handling

401 Unauthorized

404 Not Found

409 Conflict

422 Validation Error

Best Practices

Environment

Rate Limiting

Support

Related Documentation