This application programming interface lets you integrate the Sokordia iSpis services into your own software, e.g. screening in the central enforcement registers as part of your decision process.

The API is based on HTTPS GET/POST. To use it you must:

• Access it only over the secure HTTPS protocol.
• Be registered in the system.
• Authenticate with one of the allowed methods.

1. Login e-mail and password in the query parameters email/password.
2. HTTP Basic authentication, with the login and password sent in the standard header Authorization.
3. OAuth 2.0 authentication: obtain an access token from the /oauth/token endpoint with your login and password, then pass the token in the Authorization: Bearer header.

   TOKEN=$(curl -s -X POST https://ispis.cz/oauth/token -H 'Content-Type: application/x-www-form-urlencoded' -d 'grant_type=client_credentials&client_id=(email)&client_secret=(password)' | jq -r .access_token) && curl -s https://ispis.cz/api/... -H "Authorization: Bearer $TOKEN"

For production access we recommend creating a dedicated account with permissions limited to the given service and using OAuth 2.0. Contact us if you want to restrict API access to specific IP addresses or set other access parameters.

Single queries

The API can be used for on-line queries or for bulk (batch) screenings. For single queries the lustraceSearchSubject function is enough: you pass a person and a screening profile, and the result is returned immediately as a list of key/value pairs, e.g. the key CEEPocet with the value 0.

Bulk (batch) processing

For bulk screenings you create a batch and then poll its processing status periodically.

The batch is created with lustraceCreateBatch, which takes an array (set) of persons and a screening profile and returns a batch identifier generated by the system, e.g. 20150101.100. With lustraceBatchDetails you can then poll the processing status of the batch and, once it is finished, download all results.

Input parameters and output format

The input is typically a person, given by first name, surname and date of birth, or by the personal identification number, or by the company ID. Some registers accept other inputs as well (e.g. a file number for a file detail, or a document number for a document validity check).

The screening profile is one of the preconfigured lists of registers you want to query. They are listed in the screening form on the Screening page, e.g. Zakladni,CEE or ExeSR. If you want a single register, its code can be used as the profile (see the list of registers). On request we can create a custom profile (a combination of registers) for you.

The particular keys that may appear in the output are described in the documentation of the registers you queried.

The overview and description of all available REST API functions (cases, claims, payments, screening, ...) is in the API documentation.

Input parameters:

• profile – screening profile (e.g. "CEE", "ISIR", "Devel", ...).
• Jmeno, Prijmeni, Narozen, RC, IC, ... – a meaningful subset identifying the person.

Output values:

• batchId: our ID assigned to the screening (also shown in Billing etc.).
• done: always 1 for single screenings.
• warnings: errors, if any, to be shown to the user.
• files: names of the attachments of the screening output.
• detail: list of key/value pairs with the screening result itself.
• costCents: price of the query in hundredths (hellers / cents) including VAT. A contractual flat fee for the service (typically for bailiff offices) is not included.
• balanceCents: credit balance in hundredths including VAT after the query has been charged.

Example

curl -o output.json 'https://ispis.cz/api/lustraceSearchSubject?username=...&password=...&profile=Devel&Jmeno=Jan&Prijmeni=Svoboda&Narozen=14.6.1983'

{
  "batchId": "20151123.5",
  "detail": {
    "CasLustrace": "2014-11-23T22:29:59",
    "Complex_JSON": "[{"Date":"2014-11-23"},{"Time":"22:29:59"}]",
    "Devel": "test",
    "Jmeno": "Jan",
    "Narozen": "1981-03-14",
    "Osloveni": "Svobodo",
    "Prijmeni": "Svoboda"
  },
  "done": 1,
  "files": [],
  "warnings": null,
  "costCents": 3025,
  "balanceCents": 1241075
}

The output itself is in the detail field. The particular keys that may appear there are described in the documentation of the registers you queried.

For historical reasons, keys ending in JSON are given as text values in JSON format.

We recommend storing the detail field on your side again as a list of key/value pairs (or as JSON).

For development and testing of the screening API you can use theDevel register, which is free of charge.

For a natural person on input, this register returns the surname in the vocative form and a Complex_JSON structure.

For a legal entity (company ID) it returns one PDF document.