# 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:


```http
/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

| Area | Examples |
|  --- | --- |
| Business relations | Retrieve business relations and related consumer paths. |
| Consumers | Create and retrieve organization-scoped customers and legal representatives. |
| Contracts | Create, retrieve, update, and manage organization contracts. |
| Contract items | Create and manage service lines connected to a contract. |
| Service activation | Create and confirm service activation groups. |
| Consumptions | Retrieve latest and aggregated consumptions. |
| Product metrics | Retrieve product metrics for organization-related consumers. |


## French Consumer Notes

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

| Field | French meaning | Notes |
|  --- | --- | --- |
| `taxCode1` | TVA / VAT | Optional for `Corporate` and `ProfessionalIndividual`; must be empty for `PrivateIndividual`. |
| `taxCode2` | SIREN | Optional for `Corporate` and `ProfessionalIndividual`; French eInvoice legal-representative temporary SIREN values use `T03` + ULID. |
| `taxCode3` | SIRET | Optional for `Corporate` and `ProfessionalIndividual`; must match the SIREN when present. |
| `customerType` | French customer type | Supported 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

- [Authentication](/products/oneplatform/one-platform-knowledge-center/04-api-and-integration/organizations-api/authentication)
- [Endpoints](/products/oneplatform/apis/oas/organizations)
- [Integration Guides](/products/oneplatform/one-platform-knowledge-center/04-api-and-integration/organizations-api/integration-guides/overview)