Onboarding a business

Four steps. The first three are always yours; the fourth depends on whether the business will talk to us directly.

1. Create the company — the business as a legal entity.
2. Register its participant — the Peppol address others will send to.
3. Declare its capabilities — which document types it sends and receives.
4. Issue credentials, if it is going to connect itself.

1. Create the company

curl -sS -X POST https://api.businessgateway.se/v1/companies \
  -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
  -d '{
    "name": "Kinnefrukt AB",
    "identifier": "kinnefrukt",
    "countryCode": "SE",
    "registrationNumber": "5561234567"
  }'

Only name is required. countryCode falls back to your account's, and identifier is derived from the name when you leave it out.

Set identifier deliberately anyway. It is the customer-facing name of the company: it names the SFTP directory, it can appear in file names, and it shows up in lists. It must be unique under your account and safe in a file path, and changing it later moves directories your customer may already be writing into.

The response carries the company's id. Keep it — it is the companyId every later call uses.

2. Register the Peppol address

A participant is an address on the network, written scheme:value. Swedish organisation numbers are scheme 0007; Norwegian are 0192; GLN is 0088.

curl -sS -X POST https://api.businessgateway.se/v1/participants \
  -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
  -d '{
    "companyId": "'"$COMPANY_ID"'",
    "scheme": "0007",
    "value": "5561234567",
    "name": "Kinnefrukt AB",
    "identifier": "kinnefrukt",
    "capabilities": [
      {"documentTypeId": "invoice", "direction": "BOTH"}
    ]
  }'

countryCode is derived from the scheme where the scheme implies one, and only needs supplying for schemes that do not — GLN and DUNS among them. identifier is the participant's filesystem-safe name, unique within the company, used the same way the company's is.

Passing capabilities here creates them in the same transaction as the participant; you can also add them afterwards (step 3).

Registration is not instant

A new participant starts at PENDING_APPROVAL and has to be approved before anything is published to the network. After approval it moves through REGISTERING — where its address is published to the SMP so other access points can find it — and only then reaches ACTIVE.

Poll GET /v1/participants/{id}, or subscribe to the participant events on the stream. Do not build an onboarding flow that assumes a participant is usable the moment you create it — sending from one that is not READY or ACTIVE is refused.

3. Declare capabilities

A capability says "this participant handles this document type, in this direction". It is what the network reads to decide whether the business can be sent an invoice, and what we check before accepting a submission.

curl -sS -X POST "https://api.businessgateway.se/v1/participants/$PARTICIPANT_ID/capabilities" \
  -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
  -d '{"documentTypeId": "invoice", "direction": "BOTH"}'

direction is SEND, RECEIVE or BOTH. Adding SEND where RECEIVE already exists merges to BOTH rather than creating a second row.

documentTypeId takes a short alias — see Document types — or a full Peppol document type identifier with its processId.

Getting this wrong is the most common reason a document that should have worked does not. A business that can receive invoices but has no RECEIVE capability for credit notes will have credit notes rejected by the sending side before they ever reach us.

4. Issue credentials

Skip this if you are going to broker every document yourself. Otherwise, give the business one of the two:

An API key confined to the company

curl -sS -X POST https://api.businessgateway.se/v1/api-keys \
  -H "X-API-Key: $KEY" -H 'Content-Type: application/json' \
  -d '{
    "name": "Kinnefrukt ERP",
    "companyId": "'"$COMPANY_ID"'",
    "permissions": ["read", "send", "receive"]
  }'

The key is in the response and is never shown again. permissions is any of read, send, receive, manage; omitted or empty means all four. Leave manage out unless the business should be able to change its own webhooks and participants.

A key with companyId cannot see the rest of your account. Ids from other companies answer 404, not 403, so it cannot enumerate what else exists.

An SFTP login

For businesses whose systems produce files. GET /v1/sftp/connection returns the host, port, host key fingerprint and the directory layout each login sees — hand those to the customer along with the credentials. The SFTP guide is written for them.

What to hand over

Whichever you issue, the business needs:

• The credential itself, transmitted somewhere other than email if you can.
• Its Peppol address, so it can tell its trading partners.
• A link to For businesses — those pages assume exactly this starting point.