Utility Endpoints
There are a few utility endpoints to help developers use, test, and understand the APIs. All endpoints are authenticated and require valid credentials to access, except for /health Endpoints:- / - The API root / endpoint returns basic IP info, versions, etc. It’s designed to let you know the API is up and running, plus basic information. It’s a good test point for basic flow, authentication, correlation IDs, etc.
- /health - The health endpoint is designed for API client, monitoring, etc. to periodically confirm the API system is up and healthy. Note this is not an authenticated endpoint for now. When healthy, this endpoint returns an HTTP code 200 and the string “OK”. It will return a 503 or other 5xx errors iif unhealthy.
Deleted or Archived Data
Most endpoints only return ‘active’ and non-deleted data, without any options to access soft-deleted or inactive data elements. In a few very specific cases, special options may be provided to access these elements. For example, inactive or archived rooms or request templates are never returned via the API.Filtering
Filtering is handled by each endpoint’s specification, as these are highly-variable.Paging
Some endpoints support simple paging, with a page, offset, and size. Note these are not cursors, so the underlying data can change during page retrieval, though this is not common; however, you should read the necessary pages as quickly as you can.Sorting
Some endpoints support sorting, and nearly all endpoints have default sorts, as specified. Note that some default sorts are complext, such as some guest endpoints will default to sorting by status and relationship, where in-house guests are first, followed by due-in guests, guests coming soon, guests who recently checked-out, etc.Size Limits
Most endpoints have a built-in hard size limit, often 100 or 1,000 items.Best Practices
Please follow these best practices when using the KYC API.- Avoid Polling - Please do not poll the API frequently.
- Avoid Concurrent Requests - Please make requests serially, not concurrently, to reduce load on the system and avoid throttling or concurrency errors.
- Do Not Ignore Errors - Please do not ignore repeated 4xx and 5xx error codes. Instead, please check your code and ensure you are making proper requests, such as the right path, arguments, types, etc. Ignoring repeated errors may result in the suspension of your API key.
Troubleshooting
Below are a list of common problems, but there are also some best practices such as:- Check and log HTTP Response Codes
- Check and log Error Codes
- Check, log, and READ the response messages
Common Problems
Below are some common issues and troubleshooting suggestions:- Authentication
- Includes all error codes.
- Missing Results
- 4xx Errors
- More coming soon, including including bad JSON, bad args.