Dashboard Public API
The swagger documentation is available at the link Swagger UI for Public API.
The Public API is organized around REST. Our API has predictable resource-oriented URLs, accepts form-encoded request bodies, returns JSON-encoded responses, and uses standard HTTP response codes, authentication, and verbs.
Authentication
The Public API uses API Keys to authenticate requests. You can view and manage your API Keys in the Dashboard. All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail. Bearer authentication (also called token authentication) is an HTTP authentication scheme that involves security tokens called bearer tokens. The bearer token is a cryptic string, generated by the server. The client must send this token in the Authorization header when making requests to protected resources:
Authorization: Bearer <token>
How to create an API key (bearer token)
Sign in to the Dashboard and browse to page Development/API Keys. Create a new API Key and bind it to the Locations. Please select key type - Private.
After that, you can find it in the list of keys.
In the example above, the generated private key is 03c59a52-8d5c-4601-a9ec-13381a8220eb
and the location is Leasing trailer.
Warning
The request without the private key or with the invalid key will get HTTP code 401 Unauthorized.
How to create a simple call to the Public API
Let's try to create a request for getting all user's Validation Requests for the given Private key:
- add the authorization token to the HTTP header. For the example above it will be:
Authorization: Bearer 03c59a52-8d5c-4601-a9ec-13381a8220eb
- and compose
Http Get
request to the linkhttps://my.checkpointid.com/api/PublicOnboarding/Requests
- if you need to filter, use parameter metadata
Example
Request command line:
curl https://my.checkpointid.com/api/PublicOnboarding/Requests/?metadata={'key1':'value1'} -H "Authorization: Bearer 03c59a52-8d5c-4601-a9ec-13381a8220eb"
Response content:
[
{
"validationRequestId": "17a60536-1b38-4b5e-95e0-08d852ef516a",
"firstName": "FirstName1",
"lastName": "LastName1",
"phone": "+9 999 999-99-99",
"email": "test1@test.com",
"openedLinkTimes": 6,
"createdUtc": "2020-09-07T05:55:52.217",
"completed": true,
"status": 1,
"statusName": "Success",
"lastResponseId": null,
"successResponseId": null,
"attemptsUsed": 1,
"documentExpired": null,
"metadata": {
"key1": "value1"
}
}
]
The input URL-parameter (metadata) can contains a list of key-value pairs. In this case, Validation Requests will be selected if they have all the values of the key-value pairs.
"metadata": {
"key1": "value1",
"ref": "1234"
}
Errors
API uses conventional HTTP response codes to indicate the success or failure of an API request. In general:
- Codes in the 2xx range indicate success.
- Codes in the 4xx range indicate an error based on provided information (e.g., a required parameter was omitted, a document's verification failed, etc.). 4xx errors that could be handled programmatically include an error code that briefly explains the error reported.
- Codes in the 5xx range indicate an error with API server (these are rare).
Error Object Attributes:
- code (string) The type of error returned.
- message (string) A human-readable message about the error.
- propertyErrors (object) Dictionary, which contains the fields from the model where the errors have been found. Key: field name from the model, meaning: error message. The error code will appear as 'ValidationError'.
- multipleErrors (Error's array) a set of errors of the same structure as a describable object. The error code will appear as 'MultipleErrors'.
Error Codes Summary for 4xx HTTP Status Code:
- NotFound The requested resource doesn't exist.
- Forbidden You do not have permission for the requested resource.
- BadRequest Input params have invalid values