Start outbound migration

---

Generate a one-time migration key so an existing Docnova participant can be migrated to another Peppol provider.

Endpoint

Property	Value
URL	POST /peppol/migration/outbound/start
Method	POST
Auth	R-Auth: <partner-jwt> (the associated company must have a user with SUPER_OWNER admin authority)
Content-Type	application/json
Base URL	Stage Environment https://api-stage.docnova.ai/ Production Environment https://api.docnova.ai/

Country-specific hosts

During testing this was observed against a France-hosted company on https://api-fr-stage.docnova.ai/; the host may vary by the company's country deployment.

Example Request

curl --location '{{baseUrl}}/peppol/migration/outbound/start' \
--header 'Content-Type: application/json' \
--header 'R-Auth: {{partnerJwt}}' \
--data '{
  "companyId": "0ddae57b-673a-45fa-ad1f-e7c52827b44a",
  "icd": "0225",
  "specialIdentifier": "",
  "businessIdentifier": "271688503"
}'

Request body

{
  "companyId": "string (UUID)",
  "icd": "string",
  "specialIdentifier": "string",
  "businessIdentifier": "string"
}

Request fields

Field	Type	Required	Description
companyId	UUID	Yes	The Docnova company that owns the participant being migrated out.
icd	string	Yes	The Peppol identifier scheme (ICD) for the participant, e.g. 0225 for the French SIRENE registry.
specialIdentifier	string	No	An optional prefix combined with businessIdentifier to form the full identifier value. Leave empty for the base identifier.
businessIdentifier	string	Yes	The business identifier value under the given icd (e.g. the SIREN).

Response

200 OK

A8F5D2K9L7YHD56FVO0PAZ

Response fields

Plain text body — the generated migration key itself. Hand this key to the participant's new provider; they will submit it via their own inbound-migration request.

Important

• The key is one-time use and expires in 30 days. If migration is not completed within that window, it is automatically cancelled.
• Generating a key cannot be undone / re-issued for the same request while it is still pending — cancel the pending migration first (/peppol/migration/outbound/cancel) if a new key is needed.
• Until the new provider completes the migration, the participant remains active on Docnova — invoices continue to be sent/received normally.
• Docnova periodically checks whether the participant has actually moved to another SMP; once detected, the migration is finalized automatically (or it can be finalized manually via /peppol/migration/outbound/confirm).

Error Codes

HTTP Status	Error	Description
400	Validation error	companyId, icd, or businessIdentifier missing.
401 / 403	Unauthorized	Missing/invalid R-Auth token, or the associated user lacks SUPER_OWNER admin authority.
500	PEPPOL_PARTICIPANT_OUTBOUND_MIGRATION_FAILED	"Peppol participant outbound migration failed! Error: %s" — the SMP could not generate a key for this participant, or the participant ID could not be resolved.

Related

• Start inbound migration — the reverse flow: registering a participant on Docnova using a migration key issued by another provider.