Most API errors are caused by an invalid API key, a malformed request, or incorrectly formatted data.
Authentication errors (401 Unauthorized)
A 401 error means APLYiD could not authenticate your request.
Check that your API key is included in the Authorization header using the format:
Bearer YOUR_API_KEYMake sure you are using the correct key for your environment (live vs test)
If you have recently regenerated your API key, ensure your integration has been updated
Unprocessable entity errors (422)
A 422 error means the request was received but the data provided was invalid or incomplete.
Check that all required fields are included (e.g. first_name, last_name, and either email or mobile)
Make sure phone numbers include the full international dialling code (e.g.
+6421...for NZ,+614...for AU,+447...for UK)Confirm the Content-Type header is set to
application/jsonCheck for formatting issues such as extra spaces or unsupported characters in field values
Not found errors (404)
A 404 error means the resource you are trying to access does not exist.Check the check ID in your request and confirm the check has not been deleted or archived in APLYiD.
Rate limiting (429)
A 429 error means too many requests are being sent in a short period of time.
Reduce the frequency of requests
Implement retry logic using exponential backoff
Webhook not firing
If you are not receiving webhook events:
Confirm the webhook URL is set correctly in your APLYiD account settings
Ensure your endpoint is publicly accessible and returns a 200 OK response
Check that you are listening for the correct event type (e.g.
check.completed)Review your server logs for incoming POST requests — they may be arriving but failing silently
Testing your integration
Use APLYiD’s test mode to send verification requests without triggering live checks or charges. Make sure you are using the correct API key for the selected environment.
You can find your API configuration in your APLYiD account settings. Go to Settings → API & Integrations to view your API keys, select the correct environment (live or test), and configure webhook URLs for event notifications.
Related articles
How to send a verification
Getting started with APLYiD