API reference

The PassportReader API is a JSON-encoded restful API, with a strong focus on integration simplicity. It accepts JSON-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and expressive URLs.
PassportReader has no sandbox API, integration and testing is done in production.
When you sign up for an account you are given free credit to be used for this.
The PassportReader API uses a credential pair, a public key and a secret, to authenticate all requests. To help you distinguish between them, the public key is prefixed with “public-key-” and the secret is prefixed with “secret-”. To generate new credentials or manage existing ones, sign in to your account and go to the settings tab. Remember to keep your secret safe and never store it in publicly accessible areas such as in git repositories, client code or in apps.
Authentication to the API is performed via HTTP Basic Auth. Provide your public key as the basic auth username value and your secret as the password value.
curl -u PUBLIC_KEY:SECRET
Most http clients have built-in support for basic auth in which case you only have to provide the credentials (like in the example above). If you have to construct the basic auth header manually, the formula is base64(public key + : + secret).
# python example from base64 import standard_b64encode headers.append({ 'Authorization': 'Basic %s' % standard_b64encode( b'PUBLIC_KEY' + b':' + b'SECRET' ).decode() })
API requests without authentication will fail.
All API requests must be POST requests made over HTTPS.
The request body must be a JSON-encoded string containing the request properties. If no properties are required, the request body can be omitted completely. For integration simplicity, the encoding of any valid JSON object, including empty ones, is always guaranteed to be accepted. Extraneous properties are automatically omitted.
All request properties have a required type, such as string or integer. Make sure to use the correct types when constructing requests, and consult the API reference if needed. The API will return an error if the wrong type is used, and the error message will point to the correct type or format.
All requests return a response in the form of a JSON-encoded string containing the response data. If the response is empty, an empty JSON object is returned. As such, the response is always safe to JSON-decode.
PassportReader uses conventional HTTP response codes to indicate the success or failure of an API request. Codes in the 2xx range indicate success. Codes in the 4xx range indicate an error due to the request itself (e.g., a required property was omitted, or an invalid property value was provided). Codes in the 5xx range indicate an internal error with PassportReader. Some errors include a message that briefly explains the error and how to resolve it.
# error example { "error_message": "No session found with id: agZmNxlcV...", "error_name": "SessionNotFound" }
Possible codes are:
• 200 OK: Everything worked as expected.
• 400 Bad Request: The request was rejected, usually because a required property is missing in the request.
• 401 Unauthorized: No valid API credentials were provided in the request.
• 500 Internal Server Error: The request was accepted, but something went wrong on our end (should be rare).
We recommend retrying failed requests, but only if they failed due to network issues (i.e. the request did not reach PassportReader) or on 5xx errors. On failure, retry up to 4 times using an exponential backoff algorithm (e.g. retry after 2, 4, 8 and finally after 16 seconds).
The timeout for a given request is 60 seconds.
To keep the API simple to understand and integrate, we re-use the same design principles and common patterns throughout.
The URL structure is always:
http://localhost:4000/api/[class].[method]
For example http://localhost:4000/api/session.create
All methods that operate on the same class (or object) are bundled together. Most classes have the same common methods, such as:
• create for creating a new object
• get for retrieving an object by id
• list for retrieving a filtered list of objects
• update for updating an existing object by id
• delete for deleting an object by id
A method is always returning an object or a list of objects of the class that is being requested. Responses are always flat and do not contain nested objects. Property names, such as id, always refer to the same class. If referring to another class, the property name is prefixed with that class.
# a session object retrieved with /api/session.get { "id": "agZmTrqZx..." # refers to the same class, i.e. the session id } # a verification object retrieved with /api/verification.get { "id": "agRNsZMnQ..." # refers to the same class, i.e. the verification id "session_id": "agZmTrqZx..." # refers to the session id }
Some properties are guaranteed to always have the same type and format:
• Id’s are always strings
• Enum’s are always strings
• Timestamps are always strings, with the format YYYY-MM-DD HH:MM:SS
• Dates have the format YYYY-MM-DD
• Times are always expressed in UTC
• Float, double or decimal values are always strings (e.g. “10.50”)
• Countries are denominated by two-letter ISO 3166 codes (e.g. “US”)
• Currencies are denominated by three-letter ISO 4217 codes (e.g. “USD”)

Session API

Verification API