Querying network registrations

All calls should be authenticated, as explained in Using the Routty API.

Use the network registration API to check whether a company is registered on Peppol and which document types it can receive before submitting a document. This page covers the /network-api endpoints.

Authentication and endpoint

Send Authorization: ApiKey [INSERT_API_KEY_HERE] with every request. Both input and output connector API keys can use this endpoint.

GET /network-api/registrations

The base URL is https://connector-api.routty.io. The endpoint currently checks Peppol. A lookup does not submit a document or register the company on a network.

Query parameters

Parameter	Required	Description
`identifier`	Yes	Company identifier, such as a VAT number or GLN. Between 1 and 100 characters.
`identifierType`	No	Identifier scheme, such as `VAT` or `GLN`, or a raw ISO 6523 ICD such as `0088`. Maximum 20 characters. Supply it where possible: omitting it searches on the identifier value alone and can match across schemes.
`country`	No	Two-letter country filter, such as `NL`. It narrows the matches; it does not identify the company in place of the identifier scheme.

Example request

Replace the example GLN and API key with your values. Use --data-urlencode to encode query parameters correctly.

Bash

curl --get 'https://connector-api.routty.io/network-api/registrations' \
  -H 'Authorization: ApiKey [INSERT_API_KEY_HERE]' \
  -H 'Accept: application/json' \
  --data-urlencode 'identifier=1234567890128' \
  --data-urlencode 'identifierType=GLN' \
  --data-urlencode 'country=NL'

Understanding the response

A successful lookup returns HTTP 200. The response echoes identifier, identifierType, and country, and contains a networks array.

Field in each network entry	Meaning
`networkType`	The checked network, currently `Peppol`.
`registered`	Whether the lookup found matching capabilities on this network.
`participantId`	Network participant identifier in `scheme::value` form. May be `null` even for a registered company when the matched data has no participant identifier.
`documentTypes`	Document types the company can receive, each with an `identifier` and human-readable `description`. When multiple records match, their document types are combined and duplicate identifiers are removed.

Registered company

Illustrative response; identifiers and capabilities vary by company.

JSON

{
  "identifier": "1234567890128",
  "identifierType": "GLN",
  "country": "NL",
  "networks": [
    {
      "networkType": "Peppol",
      "registered": true,
      "participantId": "0088::1234567890128",
      "documentTypes": [
        {
          "identifier": "urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:cen.eu:en16931:2017#compliant#urn:fdc:peppol.eu:2017:poacc:billing:3.0::2.1",
          "description": "Sales Invoice"
        }
      ]
    }
  ]
}

No matching registration

JSON

{
  "identifier": "1234567890128",
  "identifierType": "GLN",
  "country": "NL",
  "networks": [
    {
      "networkType": "Peppol",
      "registered": false,
      "participantId": null,
      "documentTypes": []
    }
  ]
}

A checked network is still listed when no registration is found. registered: false is a successful lookup result, not an HTTP error. An absent network has not been reported by this API. If no match is found, check the identifier, scheme, and country filter before changing your integration.

The lookup reports available registration and capability data. Registration alone does not guarantee that a particular document can be delivered: check the document type identifier against the returned capabilities as well.

Errors and retries

400: missing or invalid query parameters. Check the validation details before retrying.
401 or 403: check the API key and access.
429: wait for the number of seconds in the Retry-After header, then retry with backoff.
500 or another service failure: treat the lookup as unavailable. Do not interpret a failed request as registered: false.

See Swagger for the API schema.