Migrating from v1

Migration Checklist

Use this checklist to plan and validate a v1-to-v2 integration migration. Your progress is saved in this browser.

Migration progress

0 / 4

Inventory v1 endpoints currently used by the integration.
Identify which v2 resources and workflows replace each v1 call.
Mark whether each call is read, create, replace, partial update, delete, or command-style.
Identify batch jobs, webhooks, retries, export jobs, and support tooling that parse API responses or errors.

0 / 5

Create or obtain v2 client credentials.
Implement /api/v2/auth/token.
Store access_token, refresh_token, expires_in, and scope according to your security requirements.
Send Authorization: Bearer ... on protected requests.
Handle 401 errors and token refresh paths.

0 / 14

0 / 5

Re-map response parsing from the v2 response schema.
Allow additive response fields.
Do not send response bodies back as write payloads without mapping through the write schema.
Update list parsing for content, size, hasMore, page, and nextCursor.
Choose the pagination mode exposed by each endpoint; the element list is cursor-only.

0 / 5

Parse RFC 9457 Problem Details.
Use type for error category handling.
Parse validation errors[] when present.
Log traceId for support.
Update retry logic so validation, authentication, authorization, and business-conflict errors are not retried blindly.

0 / 8

Verify element aggregate create/read/update behavior using Elements.
Verify task creation, assignment, status, format, content behavior, done-state action, and delete behavior using Element Tasks.
Verify publication creation, scheduling, publishing, delete behavior, and CMS metadata behavior using Element Publications.
Verify task-publication linking behavior using Task-Publication Link Migration.
Verify custom-field definition, option, and value behavior using Custom-Field Migration.
Verify platform schedule configuration and time-slot behavior using Platform Schedule Configuration Migration.
Verify platform, group, category, type, status, and task-format behavior using Configuration Resource Migration.
Verify user, absence, shift, and shift-day-note behavior using People And Scheduling Migration.

0 / 5

Run integration tests against a v2 test environment.
Compare representative v1 and v2 workflows at the business-rule level.
Confirm support staff can use traceId values from client logs.
Confirm monitoring and alerting treat expected v2 validation/business errors differently from transient operational failures.
Keep a rollback or dual-run plan until critical workflows have been verified in production-like data.

Last modified on June 24, 2026