v1 to v2 Migration

Migrating from v1 to v2 of the CEIPAL ATS API is straightforward. This guide walks you through every change so your integration keeps working smoothly with improved performance, stronger security, and more predictable responses.

1. URL Structure

Update your base URL from /v1/ to /v2/. A trailing slash is now required on all endpoints — requests without it will not be accepted.

2. Request Parameter Naming

All request parameters have been renamed from snake_case to camelCase. Update the parameters you send in your API requests.

3. Resume Token — Secure Document Download

In V1, resume download links never expired. In V2, a resumeToken is returned that expires after 30 minutes, keeping candidate documents secure.

How to download a resume in V2:

Step 1 — Call the List or Detail API. The response will include a resumeToken.

Step 2 — Send a POST request to /v2/documentDownload/ with the token within 30 minutes.

POST /v2/documentDownload/ Body: { "resumeToken": "eyJ...{encrypted}" }

4. Enhanced Encryption

V2 uses AES-256-CBC — an industry-standard encryption algorithm. This replaces the simpler encryption used in V1 and ensures your data exchange meets modern security standards.

5. Consistent Error Handling

V1 sometimes returned HTTP 200 OK even when errors occurred. V2 now returns proper HTTP status codes, making error handling simpler and more reliable.

6. POST Endpoint Responses

All POST endpoints now return a structured JSON response including a status code, encrypted record ID, status, timestamp, and a confirmation message.

{ "statusCode": 201, "jobId": "WmFsNWNhTkd...", "status": "created", "createdAt": "2026-04-01 10:00:00", "message": "Job created successfully." }

Using returned IDs with Detail APIs:

The encrypted IDs returned in List API responses can be passed directly in the URL path to the corresponding Detail API — no query parameters needed.

Migration Checklist

Before going live with v2, make sure you have completed the following:

• [ ] Updated all endpoint URLs from /v1/ to /v2/ with trailing slash
• [ ] Renamed all request parameters from snake_case to camelCase
• [ ] Updated resume download logic to use the two-step resumeToken flow
• [ ] Updated error handling to use standard HTTP status codes
• [ ] Updated POST response parsing to read statusCode, createdAt, and encrypted ID fields