e-invoicing

Configuration

Use the Configuration v2 endpoints for setting up companies and branches, and managing existing entities.

Download OpenAPI specification

Some countries and features require using the Configuration v2 resource before you can send documents through Indirect Tax API.

Note:

For countries that require Configuration v1, see this documentation page.

Organizations

These are the available endpoints in the Organizations subresource from Configuration v2:

HTTP Method Endpoint Description
GET /v2/configurations/organizations Retrieves details from all configured organizations.
POST /v2/configurations/organizations Creates an organization.
GET /v2/configurations/organizations/{organizationId} Retrieves details from a given organization using its organizationId.
PUT /v2/configurations/organizations/{organizationId} Updates an organization.
GET /v2/configurations/organizations/{organizationId}/products Retrieves a list of all the products that have been assigned to an organization.
PUT /v2/configurations/organizations/{organizationId}/products Assigns available products to a given organization.
DELETE /v2/configurations/organizations/{organizationId}/products/{productId} Removes a product from a given organization.

Companies

These are the available endpoints in the Companies subresource from Configuration v2:

HTTP Method Endpoint Description
GET /v2/configurations/organizations/{organizationId}/companies Lists all companies configured in a given organization.
POST /v2/configurations/organizations/{organizationId}/companies Creates a company in a given organization.
PATCH /v2/configurations/organizations/{organizationId}/companies/{companyId} Updates a company from a given organization.
PATCH /v2/configurations/organizations/{organizationId}/companies/{companyId}/lock Locks a company to block POST v1/documents requests for the associated taxId.
PATCH /v2/configurations/organizations/{organizationId}/companies/{companyId}/unlock Unlocks a company to allow POST v1/documents requests for the associated taxId.
PATCH /v2/configurations/organizations/{organizationId}/companies/{taxId}/identity-validation Updates the identity-validation flag of a company identified by tax ID. Use true to mark the company as validated and false to revoke validation. This endpoint is restricted to workspace and Sovos administrators. Company-level users are not permitted.
PUT /v2/configurations/organizations/{organizationId}/companies/{companyId}/products Assigns products to a given company.

Company Endpoints

These are the available endpoints in the Company Endpoints subresource from Configuration v2:

HTTP Method Endpoint Description
GET /v2/configurations/organizations/{organizationId}/companies/{companyId}/endpoints Retrieves a list of endpoints for a given company.
POST /v2/configurations/organizations/{organizationId}/companies/{companyId}/endpoints

Creates an endpoint for a company with an optional ERP system identifier.

Note:

The request fails with a 409 status code if an endpoint with the same Pan-European Public Procurement On-Line (PEPPOL) identifier (endpoint code and scheme) has a PEPPOL activation or another change in progress.

PATCH /v2/configurations/organizations/{organizationId}/companies/{companyId}/endpoints/peppol-migration/inbound

Attaches the inbound PEPPOL migration key from the former PEPPOL Access Point (PA) to the company endpoints of a participant, identified by endpointCode and endpointScheme.

You must create the company endpoint first, then call this operation before the endpoint's start date. Call this operation again to replace the key if the former PA reissues it.

This operation stores the key on every endpoint of this participant that is waiting for PEPPOL activation (peppolRegistrationState is Scheduled or Failed) and returns these endpoint IDs in endpointIds. The API never returns the key.

The PEPPOL Service Metadata Locator (SML) switch runs on the endpoint's start date. You receive its success or failure as an asynchronous notification. If you attach the key after the activation has failed, the API stores the key but doesn't run the activation again automatically.

POST /v2/configurations/organizations/{organizationId}/companies/{companyId}/endpoints/peppol-migration/outbound

Requests an outbound PEPPOL migration key for one participant, identified by endpointCode and endpointScheme.

A participant can have several company endpoints. The API stores the key in all of them and returns the IDs of the affected company endpoints in endpointIds.

If the Service Metadata Publisher (SMP) or its extension is unavailable, the API retries the request before it returns a 503 status code. The response can take about 70 seconds, so use a client timeout of at least 90 seconds.

POST /v2/configurations/organizations/{organizationId}/companies/{companyId}/endpoints/peppol-migration/outbound/bulk

Sends an asynchronous request for the outbound PEPPOL migration keys of all company participants.

The request has no body, and the API registers and processes it asynchronously, with one item per participant (code and scheme).

The response contains an asynchronous request identifier (asyncRequestId). Use this identifier as the requestId path parameter to poll the status at /v2/configurations/organizations/{organizationId}/companies/{companyId}/endpoints/peppol-migration/outbound/bulk/{requestId}.

The API accepts only one active bulk request per company. A second request while the first is in the Created or Processing state returns 400 with the subcode AlreadyExists.

GET /v2/configurations/organizations/{organizationId}/companies/{companyId}/endpoints/peppol-migration/outbound/bulk/{requestId} Retrieves the status of an asynchronous request for the outbound PEPPOL migration keys of all company participants, including the result for each participant.
GET /v2/configurations/organizations/{organizationId}/companies/{companyId}/endpoints/{endpointId} Retrieves details from a given endpoint using its ID.
PUT /v2/configurations/organizations/{organizationId}/companies/{companyId}/endpoints/{endpointId}

Updates details from a given endpoint using its ID.

The schedulePeppolRegistration field controls when PEPPOL changes take effect. The behavior depends on the current PEPPOL state of the endpoint:

Live on PEPPOL

If you send false or omit the field, the update takes effect immediately. If you send true, the API schedules the registration for the start date.

PEPPOL registration scheduled

If you send true, the API moves the scheduled registration to the new start date. If you send false or omit the field, the request fails with 409 PeppolRegistrationScheduleRequired.

PEPPOL registration failed

If you send true, the API schedules the registration again, on every update, including contact-only changes. If you send false or omit the field, the request fails with 409 PeppolRegistrationScheduleRequired.

Not on PEPPOL

The API updates the endpoint with no PEPPOL effect.

A scheduled registration takes effect at midnight UTC on the start date, unless the market applies its own time. For example, France uses midnight French time. You receive the result as an asynchronous notification.

The request fails with 409 PeppolActivationInProgress if a PEPPOL activation or another change is in progress for any endpoint with the same PEPPOL identifier (endpoint code and scheme), whether it is a receiving or a sending-only endpoint.

DELETE /v2/configurations/organizations/{organizationId}/companies/{companyId}/endpoints/{endpointId}

Deletes a given endpoint using its ID. If the endpoint has a scheduled PEPPOL activation, the API cancels it.

The request fails with 409 if a PEPPOL activation or another change is in progress for any endpoint with the same PEPPOL identifier (endpoint code and scheme), whether it is a receiving or a sending-only endpoint.

POST /v2/configurations/organizations/{organizationId}/companies/{companyId}/endpoints/async Sends an asynchronous company endpoint registration. Returns an asynchronous request identifier (asyncRequestId) that you can use to poll the status.
DELETE /v2/configurations/organizations/{organizationId}/companies/{companyId}/endpoints/async Sends an asynchronous request to delete all company endpoints. Returns a request identifier (asyncRequestId) that you can use to poll status at /v2/configurations/organizations/{organizationId}/companies/{companyId}/endpoints/async/removal/{requestId}.
GET /v2/configurations/organizations/{organizationId}/companies/{companyId}/endpoints/async/removal/{requestId} Retrieves the status of an asynchronous request to delete all company endpoints, including per-endpoint progress and any errors.
GET /v2/configurations/organizations/{organizationId}/companies/{companyId}/endpoints/async/{requestId} Retrieves the status of an asynchronous company endpoint registration request using the asyncRequestId returned by the send operation.

Branches

These are the available endpoints in the Branches subresource from Configuration v2:

HTTP Method Endpoint Description
GET /v2/configurations/organizations/{organizationId}/companies/{companyId}/branches Retrieves a list of branches configured in a given company.
POST /v2/configurations/organizations/{organizationId}/companies/{companyId}/branches Creates a branch in a given company.
GET /v2/configurations/organizations/{organizationId}/companies/branches Retrieves a list of branches configured in the companies from a given organization.
POST /v2/configurations/organizations/{organizationId}/companies/branches Provisions the branch configuration from a given organization to the tax authority.

Users

These are the available endpoints in the Users subresource from Configuration v2:

HTTP Method Endpoint Description
GET /v2/configurations/organizations/{organizationId}/users Retrieves all users from a given organization.
POST /v2/configurations/organizations/{organizationId}/users Creates an organization user and assigns them a role.
DELETE /v2/configurations/organizations/{organizationId}/users/{userId} Deletes a given organization user.

Settings

These are the available endpoints in the Settings subresource from Configuration v2:

HTTP Method Endpoint Description
GET /v2/configurations/organizations/{organizationId}/setting-contexts Retrieves the setting contexts assigned to a given organization.
GET /v2/configurations/organizations/{organizationId}/setting-contexts/{contextName} Retrieves the organization settings from a specific context.
POST /v2/configurations/workspaces/settings Creates settings for a specified workspace to configure multiple customers at the workspace level.
GET /v2/configurations/workspaces/setting-contexts Retrieves all setting contexts available at the workspace level with their total entry counts.
GET /v2/configurations/workspaces/setting-contexts/{contextName} Retrieves all settings for a specific context at the workspace level.
POST /v2/configurations/organizations/{organizationId}/settings Creates settings under a predefined context with a variable scope. The scope can be on the organization level, company level, or even system level.
GET /v2/configurations/organizations/{organizationId}/settings/{settingId} Retrieves a specific setting from an organization.
PUT /v2/configurations/organizations/{organizationId}/settings/{settingId} Updates values from an existing setting.

Roles

This is the available endpoint in the Roles subresource from Configuration v2:

HTTP Method Endpoint Description
GET /v2/configurations/roles Retrieves a list of roles available to a given organization.

ERP Systems

These are the available endpoints in the ERP Systems subresource from Configuration v2:

HTTP Method Endpoint Description
GET /v2/configurations/organizations/{organizationId}/erpSystem/{erpSystemId}/webhook Retrieves the Svix Consumer App Portal Link for a specific ERP system to configure endpoints and manage webhook messages. Configure SystemId with PushingV2 before calling this endpoint.
GET /v2/configurations/erp-systems Retrieves a list of ERP System configurations for the workspace.
POST /v2/configurations/erp-systems Creates an ERP System configuration for the workspace.
PUT /v2/configurations/erp-systems/{id} Updates an existing ERP System configuration in the workspace.

Networks

These are the available endpoints in the Networks subresource from Configuration v2:

HTTP Method Endpoint Description
GET /v2/configurations/networks Retrieves a list of networks using the available filters.
POST /v2/configurations/networks/{networkId}/trading-partners/endpoints Creates a trading partner endpoint for a specific network.
GET /v2/configurations/networks/{networkId}/trading-partners/endpoints/{endpointId} Retrieves a trading partner endpoint by its ID within a given network.
PUT /v2/configurations/networks/{networkId}/trading-partners/endpoints/{endpointId} Updates a trading partner endpoint for a given network.
DELETE /v2/configurations/networks/{networkId}/trading-partners/endpoints/{endpointId} Deletes a trading partner endpoint by its ID within a given network.

Reports

These are the available endpoints in the Reports subresource from Configuration v2:

HTTP Method Endpoint Description
GET /v2/configurations/report-setup/{categoryId}

Retrieves the available report definition options for the given category. Each definition includes its current selection state that indicates whether it is currently active for the supplied scope. The selection state controls how documents are collected, when the report is consolidated, and how it is transmitted to the tax authority.

For French e-reporting, set categoryId to FR_RPT .

POST /v2/configurations/report-setup/{categoryId}

Configures which report definitions are active for the given category and scope. Newly selected definitions are activated immediately. Previously active definitions that are no longer selected are deactivated. The response summarizes how many definitions were activated, deactivated, or left unchanged.

For French e-reporting, set categoryId to FR_RPT .

Under Construction

These are the available endpoints in the Under Construction subresource from Configuration v2:

HTTP Method Endpoint Description
GET /v2/configurations/organizations/{organizationId}/groups Retrieves a list of groups available to a given organization.
POST /v2/configurations/organizations/{organizationId}/groups Creates a group for a given organization.
Note:

These endpoints will be moved to a specific resource when they are fully implemented.