FAQ
Here you can find the most common questions and answers for XDENT API integration.
FAQ about the service, plans, and pricing is available here.
Access and authentication
Which header is required for authentication?
Every protected call must include the X-Api-Key header.
Does the API accept alternative header casing?
Yes. The API accepts both X-Api-Key and X-API-Key.
What is the API key value format?
Send the key in KeyId.Secret format.
What happens if X-Api-Key is missing?
The API returns 400 with code MISSING_API_KEY.
Who can create/manage API keys?
Only an administrator account in XDENT can manage API keys.
Keys are managed directly in My Account → API Management.
Can we have multiple API keys?
Yes, a company can have multiple API keys. The number of available keys depends on your plan.
Lost API key
If you lost your API key, you must delete it and create a new one. For security reasons, the full key is shown only once at creation time, so we recommend copying and storing it in a safe place immediately.
IP authorization
Can access be restricted to a whitelist of IP addresses?
Yes, by enabling IP authorization in API Management.
What happens when a call is made from an unauthorized IP?
The API returns 403 with code IP_NOT_AUTHORIZED.
How does the API behave when IP authorization is enabled but the whitelist is empty?
Authorization is not applied until at least one IP address is added.
How quickly do IP whitelist changes take effect?
Changes take effect within 5 minutes.
Endpoints and data
What is the endpoint structure?
The basic route structure is always:
/api/– API base path./v{version}/– version segment (for examplev1)./{Controller}– controller name (for exampleIdentity)./{Endpoint}– specific endpoint/method of that controller (if applicable).
Example:
GET /api/v1/Identity
See API Versioning for details.
What endpoint types are available?
The API provides two endpoint types:
- Live endpoints for direct data reads, such as
Client,Location,Staff. - Queue endpoints for asynchronous processing, typically exports. In this mode, you first create an export request and the API processes it in the background based on current system load.
How are endpoints formatted?
Where data retrieval is needed, these variants are typically used:
Simple: basic paginated list.Extended: paginated list with additional filters.Detail: returns one specific item, usually with details not present inSimpleandExtended.
What pagination is used by endpoints returning lists?
List endpoints use page (default 1) and pageSize (default 25). Maximum pageSize is endpoint-specific.
Exports
Are exports available for all plans?
No. Exports are available only for Business and Enterprise plans.
If your plan does not support exports, the API returns 403 Forbidden with code PLAN_REQUIRED.
How do exports work?
Exports are processed asynchronously via queueing. After you create a request, the export is placed in a queue and processed in the background according to current system load. This prevents API overload and ensures stable operation for all clients.
Can an export be cancelled?
Yes, but only if it is in QUEUED status.
If the export does not exist (for example, incorrect idExportJob), the API returns 404 with code EXPORT_NOT_FOUND. If the export is not in QUEUED status, the API returns 409 Conflict with code EXPORT_NOT_CANCELLABLE.
How is the export result downloaded?
Use GET /api/v1/ExportResult/Download/{idExportJob}.
Which general export query parameters are supported?
For exports, you can set output format and password. To notify your system when the export is ready for download, you can set a callback URL or request email notification.
More information is in Export options.
What export output formats exist?
Currently, we primarily support JSON and CSV, but not every export type supports both formats.
The format offering can be expanded in the future (for example XML) or with custom formats for specific integration scenarios.
Does callback send the resulting export file?
No. Callback sends processing result metadata. Download the file via the download endpoint.
Why is export output delivered as ZIP?
The download endpoint returns a ZIP because output can be password-protected using the password parameter and some exports may contain multiple files in a structured directory.
Are calls to the export status endpoint rate-limited?
Yes. The status-check endpoint is rate-limited to prevent excessive polling. To detect completion, we recommend primarily using callback URL or email notification.
Limits, errors, diagnostics
How does the API signal rate limit exhaustion?
When the call limit is exceeded, the API returns 429 Too Many Requests, Retry-After header, error code RATE_LIMIT_EXCEEDED, and RetryAfterSeconds field.
What is the unified error response format?
Error responses use a unified structure:
{ "Code": "...", "Message": "..." }
For 429 responses, RetryAfterSeconds is also returned and indicates the recommended number of seconds before the next attempt.
What should be logged when investigating an incident?
HTTP status, Code, X-Request-Id, endpoint, and call timestamp.
Is there a health endpoint?
Yes, GET /api/v1/Diagnostics/Ping returns Pong.
Is there an endpoint for testing server errors?
Yes, GET /api/v1/Diagnostics/Exception returns a test 500 error.
Didn’t find what you were looking for?
You can send technical API questions to enterprise@xdent.cz.
For questions about the service, pricing, or commercial terms, please contact our customer support or your sales representative.