Skip to main content

API Version 2024-01-16 Released

· 2 min read
Paytient Engineering
Paytient Engineering
Engineering Team

We're excited to announce the release of API version 2024-01-16, which introduces enhanced identity verification capabilities and improved employee onboarding workflows.

What's New​

New CIP Status: NEEDS_EXPANDED_VERIFICATION​

Employees who cannot be verified through standard identity verification will now receive the NEEDS_EXPANDED_VERIFICATION status instead of immediate failure. This allows partners to guide employees through an expanded verification process.

Before:

{
  "onboarding_status": "FAILED"
}

After:

{
  "onboarding_status": "NEEDS_EXPANDED_VERIFICATION"
}

Testing Integration Endpoint​

We've added a new integration endpoint specifically for testing the expanded verification flow in the staging environment:

POST /v1/integration/close-account

This endpoint allows you to reset an employee's verification state and test the expanded verification workflow.

Enhanced Employee Endpoint​

The Get Employee endpoint (GET /v1/employers/{employer_id}/employees/{employee_id}) now includes additional fields to support the expanded verification process:

  • Reset residential address
  • Reset birth date
  • Reset SSN (for testing purposes only)

Migration Guide​

Updating Your Integration​

If you're currently on version 2021-08-10, here's what you need to know:

1. Handle the New Status​

Update your employee onboarding flow to handle the new NEEDS_EXPANDED_VERIFICATION status:

if (employee.onboarding_status === 'NEEDS_EXPANDED_VERIFICATION') {
  // Guide employee to submit additional documentation
  redirectToExpandedVerification(employee.id);
} else if (employee.onboarding_status === 'VERIFIED') {
  // Continue with normal flow
  issueCard(employee.id);
}

2. Test in Staging​

Use the integration endpoint to test the expanded verification flow:

# Close account to reset verification
curl -X POST \
  "https://partner-paytient-staging.paytient.com/v1/integration/close-account" \
  -u "client_id:client_secret" \
  -H "API-Version: 2024-01-16" \
  -d '{"employee_id": "empl_xyz789"}'

3. Update API Version Header​

When you're ready to use the new version, update your API version header:

- API-Version: 2021-08-10
+ API-Version: 2024-01-16

Backward Compatibility​

This version is fully backward compatible with 2021-08-10 with one exception:

  • Employees who would have received FAILED status in the old version will now receive NEEDS_EXPANDED_VERIFICATION

If you don't update your integration, employees with this status will appear as failed. We recommend updating to handle the new status for a better user experience.

Resources​

Questions?​

Contact your Paytient account manager or email support@paytient.com.