Tenants
Manage your tenants (clients)
Onboard a mandataire social (one-call)
Provisions a SASU président (assimilé salarié) end to end from a single call: PayrollEngine tenant/user/employee/payroll + case values, PartnerService association, FilingService declarant identity and payment profile, and the ops onboarding state + activation checklist. Outside the partner sandbox, the exact SIRET, active status, legal category, versioned APE and address are sourced from the official INSEE Sirene API. In the sandbox, only synthetic Luhn-valid SIRETs with the reserved SIREN prefix 999991 are served by a private fixture; the real INSEE API is not called. Registry business refusals return 422; temporary source failures return retryable 503 and persist no onboarding. Idempotent by the declared SIRET — a re-call with the same SIRET resumes where it stopped and never duplicates. The declarant is created inactive; an operator activates it in the ops console once the activation checklist and the EDITEUR probe pass. Forwarded to OpsService (OPS_SERVICE_URL).
path Parameters
partnerIdThe partner identifier
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Onboard a mandataire social (one-call) › Request Body
Officer identity. Ops checks required transport fields and explicit product policies only; a 422 boundary refusal carries error, rule, label and field, with label F (form/presence) or P (Verso product policy). Regulation/PayrollEngine exclusively validates civil, NIR, country and department semantics and produces the canonical DSN identity. A Regulation refusal becomes a 502 provisioning_failed: the body is withheld everywhere and only a recognized machine issue code from the closed identity vocabulary may be relayed. nomUsage is optional and absence is preserved.
Explicit affiliation facts. They are never derived from the mandate or first remuneration date.
Explicit ACRE facts. benefice is always required, including false. When true, activity start and entitlement reference are required for PayrollEngine to decide validity; Ops applies no eligibility, period or evidence-format rule.
Explicit J1 eligibility confirmations. Every answer is required; omission is not false.
Onboard a mandataire social (one-call) › Responses
OK — idempotent re-call: the current onboarding state is returned (no duplicate).
onboardingIdtenantIdNumeric PayrollEngine tenant id used in subsequent public API paths.
tenantIdentifierStable human-readable PayrollEngine tenant identifier.
siret^[0-9]{14}$ · requireddisplayNamestatedeadlineDayemployeeIduserIddivisionIdpayrollIdpayrunIdcreatedAtpaymentReadypaymentMissingItemsblockingItemspartnerIdfailedStepfailureReasonrejectedReasonactivatedAtslaerrormessageretryableList partner tenants
Retrieves all tenants registered to the partner.
path Parameters
partnerIdThe partner identifier
query Parameters
statusLifecycle status filter. Defaults to active.
externalIdHeaders
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
List partner tenants › Responses
OK
idThe durable tenant registration ID
partnerIdtenantIdtenantIdentifierexternalIdnameculturestatuscreatedCreate a payroll tenant
Creates a minimal PayrollEngine tenant and grants the authenticated partner access to it. The partner supplies its stable externalId; Verso generates and persists the internal PayrollEngine identifier. Replaying the same externalId with identical immutable metadata returns the existing tenant. This operation does not create users, employees, payrolls, regulations or DSN configuration. Use POST /partners/{partnerId}/tenants/mandataires for complete mandataire onboarding.
path Parameters
partnerIdThe partner identifier
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Create a payroll tenant › Request Body
externalIdStable tenant/dossier identifier in the partner system. Unique per partner and used as the idempotency key.
nameHuman-readable tenant name. Immutable for a given externalId.
culturePayrollEngine culture name. Immutable for a given externalId.
Create a payroll tenant › Responses
OK — idempotent replay returned the existing active tenant.
Get a partner tenant
Returns the durable tenant registration and lifecycle events for a tenant owned by the authenticated partner.
path Parameters
partnerIdtenantIdHeaders
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Get a partner tenant › Responses
OK
Unregister a tenant
Revokes the partner's access and marks the registration as disassociated. Payroll and DSN data remain in PayrollEngine. Reactivation is an explicit operator-only action.
path Parameters
partnerIdThe partner identifier
tenantIdThe tenant identifier
Headers
AuthorizationThe Authorization header is used to authenticate with the API using your API key. Value is of the format Bearer YOUR_KEY_HERE.
Unregister a tenant › Responses
No Content