Migrate from v5 to v2026-03-15

This guide outlines the key changes when migrating your integration from the v5 API to the v2026-03-15 API.

Generic changes

Base URL

v5: https://api.omnisend.com/v5/
v2026-03-15: https://api.omnisend.com/api/

All endpoints, including products, categories, batches, and events, have moved to the /api/ base path.

Authentication

The API key header name has changed:

	v5	v2026-03-15
Header	`X-API-KEY: {key}`	`Authorization: Omnisend-API-Key {key}`
Version header	Not required	`Omnisend-Version: 2026-03-15` (required on every request)

v5 example:

curl --request GET \
  --url 'https://api.omnisend.com/v5/contacts' \
  --header 'X-API-KEY: YOUR-API-KEY'

v2026-03-15 example:

curl --request GET \
  --url 'https://api.omnisend.com/api/contacts' \
  --header 'Authorization: Omnisend-API-Key YOUR-API-KEY' \
  --header 'Omnisend-Version: 2026-03-15'

Pagination

Pagination changed from URL-link-based to cursor-based:

	v5	v2026-03-15
Next page	`paging.next` (full URL)	`paging.cursors.after` (opaque token)
Previous page	`paging.previous` (full URL)	`paging.cursors.before` (opaque token)
More results indicator	Value in `paging.next`	`paging.hasMore: true`

v5 response:

{
  "contacts": [...],
  "paging": {
    "next": "https://api.omnisend.com/v5/contacts?after=abc123",
    "previous": null,
    "limit": 100
  }
}

v2026-03-15 response:

{
  "contacts": [...],
  "paging": {
    "limit": 100,
    "hasMore": true,
    "cursors": {
      "after": "eyJpZCI6IjEyMyJ9",
      "before": "eyJpZCI6IjEifQ=="
    }
  }
}

Pass the cursor token as a query parameter: GET /api/contacts?after=eyJpZCI6IjEyMyJ9

Error responses

	v5	v2026-03-15
Format	`{error, fields}`	RFC 9457 `{type, title, status, detail, errors[]}`

Resource changes

Contacts

Base path: /v5/contacts → /api/contacts

Endpoint changes

v5	v2026-03-15	Notes
`GET /v5/contacts/{contactID}`	`GET /api/contacts/{id}`	Path parameter renamed
`PATCH /v5/contacts/{contactID}`	`PATCH /api/contacts/{id}`	Path parameter renamed
`POST /v5/contacts`	`POST /api/contacts`	No longer upserts; always creates. Returns `201`.
—	`POST /api/contacts/tags`	New: batch add tags
—	`DELETE /api/contacts/tags`	New: batch remove tags

POST upsert behavior removed

In v5, POST /contacts with a contactID body field performed an upsert (update if exists, create if not). This behavior is removed. POST /contacts no longer accepts contactID and always creates a new contact.

Use PATCH /api/contacts/{id} as a direct replacement for the v5 upsert behavior.

Legacy top-level request fields removed

The following top-level fields are no longer accepted on POST /contacts and PATCH /contacts:

email, phone, phoneNumber, status, statusDate, optInDate, optInIP, creationDate, source

Use the identifiers array with per-identifier channels and consent instead.

`sendWelcomeEmail` removed

The sendWelcomeEmail field is removed. Welcome messages are now sent automatically when an identifier's channel is set to subscribed. To suppress welcome messages (e.g. during imports), use the per-identifier sendWelcomeMessage field.

`tags` field now replaces instead of appends

Behavior	v5	v2026-03-15
`"tags": ["a"]`	Appends `"a"` to existing tags	Replaces the entire tags array with `["a"]`
`"tags": []`	No-op	Clears all tags
`tags` omitted	Tags unchanged	Tags unchanged

Response field renames

v5 field	v2026-03-15 field
`ContactStatus.date`	`ContactStatus.statusChangedAt`
`OptIn.date`	`OptIn.optInAt`
`Channel.statusDate`	`Channel.statusChangedAt`

Other field changes

Field	v5	v2026-03-15	Notes
`contactID`	Response field	Removed	Use `id` instead
`state`	Free-form string	ISO 3166-2 subdivision code (e.g., `"CA"`)	Format is now validated

Campaigns

Base path: /v5/campaigns → /api/campaigns

Endpoint changes

v5 exposed campaigns as read-only. v2026-03-15 introduces full CRUD and lifecycle management:

v5	v2026-03-15	Notes
`GET /v5/campaigns`	`GET /api/campaigns`	List campaigns
`GET /v5/campaigns/{campaignID}`	`GET /api/campaigns/{id}`	Path parameter renamed
—	`POST /api/campaigns`	New: create campaign
—	`PATCH /api/campaigns/{id}`	New: update campaign
—	`DELETE /api/campaigns/{id}`	New: delete campaign
—	`POST /api/campaigns/{id}/send`	New: send campaign
—	`POST /api/campaigns/{id}/cancel`	New: cancel campaign
—	`POST /api/campaigns/{id}/copy`	New: copy campaign

Response structure changes

Field	v5	v2026-03-15	Notes
`subjectLine`	Top-level string	Removed	Moved to `content.email.subjectLine`
`tzoEnabled`	Top-level boolean	Removed	Moved to `sendingSettings.isTZOptimizationEnabled`
`startDate`	Top-level timestamp	Removed	Renamed to `startedAt`
`endDate`	Top-level timestamp	Removed	Renamed to `endedAt`
`sendStartDate`	Top-level timestamp	Removed	Moved to `sendingSettings.scheduledAt`
`sendEndDate`	Top-level timestamp	Removed	—
`startedAt`	—	Top-level timestamp	Renamed from `startDate`
`endedAt`	—	Top-level timestamp	Renamed from `endDate`
`audience`	—	Object	New: `includedSegmentIDs`, `excludedSegmentIDs`
`content`	—	Object	New: email/sms/push content configuration
`sendingSettings`	—	Object	New: `strategy`, `isTZOptimizationEnabled`, `scheduledAt`
`language`	—	String (locale `xx_XX`)	New
`brandID`	—	String	New

Status enum changes

v5	v2026-03-15
`draft`	`draft`
`pending`	— (removed)
`started`	`started`
`canceled`	`canceled`
`paused`	`paused`
`sent`	`sent`
`error`	`error`
`onHold`	`onHold`
`archived`	— (removed)
`splitTestingStarted`	— (removed)
`splitTestingStopped`	— (removed)
`splitTestingExpired`	— (removed)
—	`stopped` (new)
—	`expired` (new)
—	`scheduled` (new)

Type enum changes

v5	v2026-03-15
`standart`	`regular`
`abTest`	`abTest`
—	`booster` (new)

Product Categories

Base path: /v5/product-categories → /api/product-categories

Field	v5	v2026-03-15	Notes
`title`	maxLength: 100	maxLength: 255	Extended limit