Use the PD Support PIN verification API when your own helpdesk, phone or internal service needs to check a caller’s supplied PIN. It returns a verification result, not the stored PIN. Keep the integration on your backend so the API key is not exposed to a customer’s browser.

Enable the API

1. Open PD Modules → PD Support PIN → Settings and enable Enable the verification API.
2. Open API and choose Generate API key.
3. Copy the Endpoint URL from that installation’s API tab. Use the example shown on the same page rather than building a route from another installation’s address.
4. Store the key in the calling backend’s secret configuration. Do not put it in a URL, client-side script, public repository or screenshot.

The module uses a WHMCS-specific endpoint. Copying the address from the installed module also keeps any billing-site subdirectory correct.

Send a verification request

Send an HTTPS POST to the copied endpoint with these form fields: key for the API key, action=verify, pin for the value the caller supplied, and either client_id or email to identify the client.

When identifying by email, use the exact account email; matching ignores letter case but does not accept a partial email. Keep PINs as strings in your integration so a leading zero is not lost.

The API also supports Authorization: Bearer where your web server forwards that header to PHP. If the header is stripped, use the supported key POST field. A key in a query string is not accepted.

Interpret the response correctly

An HTTP 200 means the check was processed. Read match to decide whether the supplied PIN matched; do not treat ok=true or the HTTP status alone as a successful caller check. The rotated field is true when one-time mode replaced the PIN after a match.

HTTP 400 with pin_required or client_not_found calls for checking the submitted fields and client identity. 401 unauthorized calls for checking authentication. 404 not_found is returned when the API is disabled; check its enabled setting and that you copied the correct endpoint before diagnosing a verification failure. 429 rate_limited means further checks for that client must wait; respect the returned retry_after value rather than retrying in a loop.

Failed staff, API and assistant checks contribute to the same per-client failure count used by the API and assistant lockout. Do not switch channels to keep guessing; follow your alternative identity-check process instead. Each API check appears in Report & Activity → Activity, allowing you to compare the result with the calling system’s time.

Verify and maintain the integration

Use a test client you control. Check one current PIN and confirm your backend reads match correctly. Test its failure handling without repeatedly submitting wrong values until the account is limited. Avoid logging PINs or the API key in request traces.

Regenerating the API key invalidates the previous one immediately. Plan the backend update when rotating it. A match is one step in the support process; it does not authorise an unrelated account change.

Check the integration result

Distinguish authentication failure, an unresolved customer, a processed no-match and a rate limit. Compare the copied Endpoint URL, enabled API setting, authentication method and expected client identity. If a key was deliberately regenerated, update the backend secret. Keep keys and PINs out of logs and do not repeatedly submit wrong PINs to test the integration.

See how Support PIN verification works in WHMCS for the overall workflow, or explore PD Support PIN.