REST API documentation

The Directory can be automatically queried using a public REST API.

URL handling

The basic URL to query is /search/1.0/format where "format" can be one of xml or json depending on the output format needed. If no format is provided, xml is used as the default. The response Content-Type for "xml" is application/xml and for "json" it is application/json.

Only HTTP GET requests are accepted. Other HTTP verbs are rejected with HTTP status code 405. Query parameters must be appended to the URL as parameters.

The XML Schema for the XML responses can be downloaded from /files/directory-search-result-list-v1.xsd.

Request parameters

This section outlines the available request parameters and there meaning. If multiple search terms are used, only results matching all request parameters are returned (so it is handled like a boolean AND query). If the combination of query parameters resulted in an empty search result, an HTTP status code 200 with an empty result body is returned!

Name: q
Description: Generic query term. It queries all fields and the results equal the ones that can be obtained when using the simple search. The query term is split into pieces internally and subwords may be found.
Note This parameter can occur more than once
Example /search/1.0/xml?q=Austrian+Government Try it
Example /search/1.0/json?q=Austrian+Government Try it

Name: participant
Description: Searches for exact matches in the Peppol participant identifier field (the identifier scheme must be part of the value).
Note This parameter can occur more than once but it makes no sense to do so, because all query parameters must match and each business card has exactly one participant identifier.
Warning If the provided parameter value cannot be converted to a Peppol participant identifier (as e.g. in iso6523-actorid-upis::9915:test) the search will return HTTP status code 400.
Warning Pay special attention to request parameter encoding because of the special characters # (%23) and : (%3A) that can be contained in search values.
Example /search/1.0/xml?participant=iso6523-actorid-upis::9915:test Try it
Example /search/1.0/json?participant=iso6523-actorid-upis::9915:test Try it

Name: name
Description: Searches for partial matches in business entity names.
Note This parameter can occur more than once.
Warning If the provided parameter value has ≤ 2 characters the search will return HTTP status code 400.
Example /search/1.0/xml?name=Government Try it
Example /search/1.0/json?name=Government Try it

Name: country
Description: Searches for exact matches in business entity country codes.
Note This parameter can occur more than once but it makes no sense to do so, because all query parameters must match and each business entity has exactly one country code.
Example /search/1.0/xml?country=BE Try it
Example /search/1.0/json?country=BE Try it

Name: geoinfo
Description: Searches for partial matches in the geographical information.
Note This parameter can occur more than once.
Warning If the provided parameter value has ≤ 2 characters the search will return HTTP status code 400.
Example /search/1.0/xml?geoinfo=Italy Try it
Example /search/1.0/json?geoinfo=Italy Try it

Name: identifierScheme
Description: Searches for exact matches in the additional identifier schemes. Combine it with identifierValue for fine grained search results.
Note This parameter can not occur more than once.
Note This field is only used for the additional identifiers and not for participant and document type identifiers!
Example /search/1.0/xml?identifierScheme=GLN Try it
Example /search/1.0/json?identifierScheme=GLN Try it

Name: identifierValue
Description: Searches for exact matches in the additional identifier values. Combine it with identifierScheme for fine grained search results.
Note This parameter can not occur more than once.
Note This field is only used for the additional identifiers and not for participant and document type identifiers!
Example /search/1.0/xml?identifierValue=1234567 Try it
Example /search/1.0/json?identifierValue=1234567 Try it

Name: website
Description: Searches for partial matches in the business entity websites.
Note This parameter can occur more than once.
Warning If the provided parameter value has ≤ 2 characters the search will return HTTP status code 400.
Example /search/1.0/xml?website=erechnung.gv.at Try it
Example /search/1.0/json?website=erechnung.gv.at Try it

Name: contact
Description: Searches for partial matches in the business entity contact information. It searches in all sub-fields of contact (type, name, phone number and email address).
Note This parameter can occur more than once.
Warning If the provided parameter value has ≤ 2 characters the search will return HTTP status code 400.
Example /search/1.0/xml?contact=support Try it
Example /search/1.0/json?contact=support Try it

Name: addinfo
Description: Searches for partial matches in the business entity additional information.
Note This parameter can occur more than once.
Warning If the provided parameter value has ≤ 2 characters the search will return HTTP status code 400.
Example /search/1.0/xml?addinfo=peppol Try it
Example /search/1.0/json?addinfo=peppol Try it

Name: regdate
Description: Searches for exact matches on a business card registration date. The parameter to be searched must have the layout YYYY-MM-DD without a time and without a time zone.
Note This parameter can not occur more than once.
Warning If the provided parameter value can not be converted to a valid date the search will return HTTP status code 400.
Example /search/1.0/xml?regdate=2012-01-01 Try it
Example /search/1.0/json?regdate=2012-01-01 Try it

Name: doctype
Description: Searches for exact matches in the Peppol document type identifiers field (the identifier scheme must be part of the value).
Note This parameter can not occur more than once.
Note The provided parameter values is case sensitive!
Warning If the provided parameter value cannot be converted to a Peppol document type identifier (as e.g. in busdox-docid-qns::urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol5a:ver2.0::2.1) the search will return HTTP status code 400.
Warning Pay special attention to request parameter encoding because of the special characters # (%23) and : (%3A) that can be contained in search values.
Example /search/1.0/xml?doctype=busdox-docid-qns%3A%3Aurn%3Aoasis%3Anames%3Aspecification%3Aubl%3Aschema%3Axsd%3AInvoice-2%3A%3AInvoice%23%23urn%3Awww.cenbii.eu%3Atransaction%3Abiitrns010%3Aver2.0%3Aextended%3Aurn%3Awww.peppol.eu%3Abis%3Apeppol5a%3Aver2.0%3A%3A2.1 Try it
Example /search/1.0/json?doctype=busdox-docid-qns%3A%3Aurn%3Aoasis%3Anames%3Aspecification%3Aubl%3Aschema%3Axsd%3AInvoice-2%3A%3AInvoice%23%23urn%3Awww.cenbii.eu%3Atransaction%3Abiitrns010%3Aver2.0%3Aextended%3Aurn%3Awww.peppol.eu%3Abis%3Apeppol5a%3Aver2.0%3A%3A2.1 Try it

Name: resultPageIndex or rpi
Description: Defines the 0-based index for the result page to be returned. If not provided, the first page is returned. By default only 20 entries are returned and this entry can be used to browse the results. Use this in combination with resultPageCount to define the number of results.
Warning Values < 0 are not accepted and lead to an HTTP status code 400.
Note It is not possible to return more than 1000 entries. Combinations of resultPageIndex and resultPageCount that would lead to such a result lead to an HTTP status code 400.

Name: resultPageCount or rpc
Description: Defines the number of items to be returned per page. If not provided 20 entries are returned. Use this in combination with resultPageIndex to define the number of results.
Warning Values ≤ 0 are not accepted and lead to an HTTP status code 400.
Note It is not possible to return more than 1000 entries. Combinations of resultPageIndex and resultPageCount that would lead to such a result lead to an HTTP status code 400.

Name: beautify
Description: Format the results so that they are more human readable? This should only be used for debugging purposes as it increases the transferred data volume. By default the returned code is minified.
Note Any other value than true will disable output beautification.

Response document layout

This section defines the response document layout. Special header parameters are present in all result representations and have the following semantics:

The above mentioned indices relate to the found Business Entities and not to Business Cards! Internally each Business Entity is stored separately and they are combined on-the-fly for the result representation to avoid providing duplication data.

XML

XML responses are always encoded in UTF-8.

The response MIME type is always application/xml.

Responses should not be cached.

The XML Schema for the XML responses can be downloaded from /files/directory-search-result-list-v1.xsd.

Example response:

<?xml version="1.0" encoding="UTF-8"?>
<resultlist version="1.0"
            total-result-count="4"
            used-result-count="4"
            result-page-index="0"
            result-page-count="20"
            first-result-index="0"
            last-result-index="3"
            query-terms="q=9915:test" 
            creation-dt="2017-09-20T18:13:07.468Z">
  <match>
    <participantID scheme="iso6523-actorid-upis">9915:test</participantID>
    <docTypeID scheme="busdox-docid-qns">urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol4a:ver2.0:extended:urn:www.erechnung.gv.at:ver1.0::2.1</docTypeID>
    <docTypeID scheme="busdox-docid-qns">urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:www.cenbii.eu:transaction:biitrns014:ver2.0:extended:urn:www.peppol.eu:bis:peppol5a:ver2.0::2.1</docTypeID>
    <docTypeID scheme="busdox-docid-qns">urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol5a:ver2.0::2.1</docTypeID>
    <docTypeID scheme="busdox-docid-qns">urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:www.cenbii.eu:transaction:biitrns014:ver2.0:extended:urn:www.peppol.eu:bis:peppol5a:ver2.0:extended:urn:www.erechnung.gv.at:ver1.0::2.1</docTypeID>
    <docTypeID scheme="busdox-docid-qns">urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol4a:ver2.0::2.1</docTypeID>
    <docTypeID scheme="busdox-docid-qns">urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol5a:ver2.0:extended:urn:www.erechnung.gv.at:ver1.0::2.1</docTypeID>
    <entity>
      <name>Austrian Government</name>
      <countryCode>AT</countryCode>
      <website>https://test.e-rechnung.gv.at</website>
      <additionalInfo>This is the test endpoint for the whole Austrian Government</additionalInfo>
      <regDate>2012-01-01</regDate>
    </entity>
  </match>
  <match>
    <participantID scheme="iso6523-actorid-upis">9915:digit_test</participantID>
    <entity>
      <name>DG DIGIT</name>
      <countryCode>BE</countryCode>
      <geoInfo>Brussels Rue Belliard 28</geoInfo>
    </entity>
    <entity>
      <name>Second entity name</name>
      <countryCode>AU</countryCode>
      <identifier scheme="GLN">123454321</identifier>
      <additionalInfo>Whatever it takes - Peppol Directory will index this</additionalInfo>
    </entity>
    <entity>
      <name>Third entity - to the rescue</name>
      <countryCode>DE</countryCode>
      <geoInfo>Germany, Baden-Württemberg</geoInfo>
      <identifier scheme="PLZ">79110</identifier>
      <additionalInfo>We need more German Peppol endpoints</additionalInfo>
    </entity>
  </match>
</resultlist>

JSON

JSON responses are always encoded in UTF-8.

The response MIME type is always application/json.

Responses should not be cached.

Example response:

{
  "version":"1.0",
  "total-result-count":4,
  "used-result-count":4,
  "result-page-index":0,
  "result-page-count":20,
  "first-result-index":0,
  "last-result-index":3,
  "query-terms":"q=9915:test",
  "creation-dt":"2017-09-20T18:15:00.438Z",
  "matches":[
    {
      "participantID":{
        "scheme":"iso6523-actorid-upis",
        "value":"9915:test"
      },
      "docTypes":[
        {
          "scheme":"busdox-docid-qns",
          "value":"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol4a:ver2.0:extended:urn:www.erechnung.gv.at:ver1.0::2.1"
        },
        {
          "scheme":"busdox-docid-qns",
          "value":"urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:www.cenbii.eu:transaction:biitrns014:ver2.0:extended:urn:www.peppol.eu:bis:peppol5a:ver2.0::2.1"
        },
        {
          "scheme":"busdox-docid-qns",
          "value":"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol5a:ver2.0::2.1"
        },
        {
          "scheme":"busdox-docid-qns",
          "value":"urn:oasis:names:specification:ubl:schema:xsd:CreditNote-2::CreditNote##urn:www.cenbii.eu:transaction:biitrns014:ver2.0:extended:urn:www.peppol.eu:bis:peppol5a:ver2.0:extended:urn:www.erechnung.gv.at:ver1.0::2.1"
        },
        {
          "scheme":"busdox-docid-qns",
          "value":"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol4a:ver2.0::2.1"
        },
        {
          "scheme":"busdox-docid-qns",
          "value":"urn:oasis:names:specification:ubl:schema:xsd:Invoice-2::Invoice##urn:www.cenbii.eu:transaction:biitrns010:ver2.0:extended:urn:www.peppol.eu:bis:peppol5a:ver2.0:extended:urn:www.erechnung.gv.at:ver1.0::2.1"
        }
      ],
      "entities":[
        {
          "name":"Austrian Government",
          "countryCode":"AT",
          "websites":[
            "https://test.e-rechnung.gv.at"
          ],
          "additionalInfo":"This is the test endpoint for the whole Austrian Government",
          "regDate":"2012-01-01"
        }
      ]
    },
    {
      "participantID":{
        "scheme":"iso6523-actorid-upis",
        "value":"9915:digit_test"
      },
      "entities":[
        {
          "name":"DG DIGIT",
          "countryCode":"BE",
          "geoInfo":"Brussels Rue Belliard 28"
        },
        {
          "name":"Second entity name",
          "countryCode":"AU",
          "identifiers":[
            {
              "scheme":"GLN",
              "value":"123454321"
            }
          ],
          "additionalInfo":"Whatever it takes - Peppol Directory will index this"
        },
        {
          "name":"Third entity - to the rescue",
          "countryCode":"DE",
          "geoInfo":"Germany, Baden-Württemberg",
          "identifiers":[
            {
              "scheme":"PLZ",
              "value":"79110"
            }
          ],
          "additionalInfo":"We need more German Peppol endpoints"
        }
      ]
    }
  ]
}