Skip to content

Organizations API

The Organizations API is the public One Platform API family for partners and customer-side system integrators that operate in the scope of a specific organization.

Use this API when your integration needs to manage or inspect organization-scoped resources such as customers, business relations, contracts, contract items, service activation groups, consumptions, and product metrics.

Scope

Most endpoints use an organization-scoped route:

/v1/organizations/{id}/<resource>

The {id} path parameter identifies the One Platform organization context. The access token must be authorized for that organization and for the requested operation.

The current reference includes both legacy /v1 consumer endpoints and /v2 consumer endpoints. Use /v2/organizations/{id}/consumers for new French customer and legal-representative flows because v2 exposes taxCode1, taxCode2, taxCode3, PrivateIndividual, and ProfessionalIndividual.

Main Capabilities

AreaExamples
Business relationsRetrieve business relations and related consumer paths.
ConsumersCreate and retrieve organization-scoped customers and legal representatives.
ContractsCreate, retrieve, update, and manage organization contracts.
Contract itemsCreate and manage service lines connected to a contract.
Service activationCreate and confirm service activation groups.
ConsumptionsRetrieve latest and aggregated consumptions.
Product metricsRetrieve product metrics for organization-related consumers.

French Consumer Notes

For French consumers, the Organizations API uses the v2 tax-code model:

FieldFrench meaningNotes
taxCode1TVA / VATOptional for Corporate and ProfessionalIndividual; must be empty for PrivateIndividual.
taxCode2SIRENOptional for Corporate and ProfessionalIndividual; French eInvoice legal-representative temporary SIREN values use T03 + ULID.
taxCode3SIRETOptional for Corporate and ProfessionalIndividual; must match the SIREN when present.
customerTypeFrench customer typeSupported values are PrivateIndividual, ProfessionalIndividual, and Corporate.

For the French eInvoice activation flow:

  • Search the final customer with GET /v2/organizations/{id}/consumers?taxCode1=<TVA>&country=FR&customerType=Corporate&exact=true&pageSize=1.
  • Search the legal representative with GET /v2/organizations/{id}/consumers?taxCode2=<temporary-siren>&country=<country>&customerType=PrivateIndividual&exact=true&pageSize=1.
  • Create the final customer with customerType=Corporate and the TVA/SIREN/SIRET mapping above.
  • Create the legal representative with customerType=PrivateIndividual, firstName, lastName, taxCode2, emails, empty phones and mobilePhones, and billable=false.
  • Use contract-item onboardingExtraParameters.hasDelegate to distinguish delegate onboarding from legal-representative onboarding. Omit it or set it to "false" for the legal representative; set it to "true" when the onboarding person is a delegate.
  • When the French eInvoice contract item includes the dt-portal feature, provide onboardingExtraParameters.adminEmail, adminFirstName, and adminLastName to identify the Portail DT administrator. Do not require these fields when dt-portal is not selected.
  • Provide SAG activation context during contract creation when your API version exposes a native field for it. Otherwise retrieve or create the SAG through the service-activation-group endpoints before confirmation.

The current swagger marks /v2/organizations/{id}/consumers as unstable and under active development. Integrations should keep this endpoint isolated so future schema changes are easy to absorb.

Sections