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:

total-result-count the total number of matching documents
used-result-count the number of results contained in the response. This is always ≤ total-result-count as it is based on the paging parameters used.
result-page-index is the 0-based index of the result page.
result-page-count is the number of entities to show on a single page.
first-result-index is the effective 0-based index of the first result item returned (inclusive). This is the result of result-page-index * result-page-count.
last-result-index is the effective 0-based index of the last result item returned (inclusive). This is the result of min ((result-page-index + 1) * result-page-count - 1, total-result-count - 1).
query-terms is the combined query string that was used to perform a search. This is mainly for debugging purposes to cross-check which parameters took effect in searching.
creation-dt the UTC date and time when this response was created. It is formatted according to XML Schema (XSD) rules.

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"
        }
      ]
    }
  ]
}