Skip to main content
Download OpenAPI

Sub-accounts

The French Invoicing API allows you to manage sub-accounts for your legal entities. Sub-accounts are user accounts that can be granted access to documents belonging to your legal entities without sharing your main account credentials.

Creating a sub-account association automatically creates the user in A-Cube if it doesn't already exist, and the sub-account can only view documents (sent/received) related to the legal entities it is associated with.

Features​

  • Sub-account Creation: Associating an email with a legal entity automatically creates a sub-account if the user doesn't already exist in A-Cube.
  • Document Visibility: By default, a sub-account can only view documents related to the single legal entity it is associated with.
  • Association Management: Owners can add or remove the sub-account/legal entity association at any time.
  • Full Visibility Option: to unlock cross-entity visibility, use the UserConfig endpoints (see below).

All endpoints are listed in the LegalEntitySubAccount API reference.

Usage example​

Assuming you already have a legal entity with ID 123e4567-e89b-12d3-a456-426614174000 and want to associate the email foo@bar.com with it:

POST /legal-entities/123e4567-e89b-12d3-a456-426614174000/sub-accounts
Content-Type: application/json

{
  "email": "foo@bar.com",
  "password": "your_secure_password"
}

After a successful request, the sub-account foo@bar.com can access documents related to the specified legal entity. You can obtain a JWT token for the sub-account using the standard authentication endpoint.

To remove the association, use the corresponding delete endpoint:

DELETE /legal-entities/123e4567-e89b-12d3-a456-426614174000/sub-accounts/{uuid}

Some integrations need a sub-account to consult documents belonging to all legal entities on the account, rather than a single one. For this use case, the French API exposes a dedicated UserConfig resource.

Creating a user configuration for a given email registers that email as a sub-account (if it isn't one already) and enables it to consult documents across all your legal entities:

POST /user-configs
Content-Type: application/json

{
  "email": "foo@bar.com",
  "password": "your_secure_password",
  "preferences": {
    "accessAllInvoices": false
  }
}

Existing configurations can be retrieved with GET /user-configs (collection) or GET /user-configs/{uuid} (single resource), and updated with PUT /user-configs/{uuid}. Note that the user a configuration belongs to is immutable: to target a different email, create a separate configuration instead.

Important notes​

  • Using LegalEntitySubAccount, sub-accounts can only be created for existing legal entities.
  • If the email provided during sub-account creation already exists in A-Cube, the API refuses the request with a 409 Conflict error.
  • Sub-accounts cannot create or manage legal entities; this is reserved for the main account holder.
  • A sub-account restricted to a single legal entity (via LegalEntitySubAccount) and one enabled for full visibility (via UserConfig) are configured through two distinct endpoints, make sure you use the one matching the access level you want to grant.
Last updated on