# API v2 to v3 Migration (/start/advanced/migration-v2-v3.md)
  # API v2 to v3 Migration [#api-v2-to-v3-migration]

Migrate your integration from the legacy v2 API to the current v3 API.

## Key Differences [#key-differences]

| Feature | v2 | v3 |
|---------|-----|-----|
| Base URL | `api.sent.dm/v2` | `api.sent.dm/v3` |
| Auth Header | `x-sender-id` + `x-api-key` | `x-api-key` (or `Authorization: Bearer`) |
| Request Body | `phoneNumber` or `contactId`, `templateId`, `templateVariables` | `to`, `template` (object with `id`/`name`/`parameters`), `channel` |
| Response Format | Flat data | Envelope with `success`, `data`, `error`, `meta` |
| Rate Limits | Varies | 10,000 req/min (standard), 10 req/min (sensitive) |
| Sandbox Mode | Not available | `sandbox: true` |
| Templates | Simple text | Structured components |
| Contacts | Basic | Channel intelligence |

## Authentication Changes [#authentication-changes]

### v2 (Legacy) [#v2-legacy]

```http
GET /v2/messages/{id}
x-sender-id: your-sender-id
x-api-key: your-api-key
```

### v3 (Current) [#v3-current]

```http
GET /v3/messages/{id}
x-api-key: your-api-key
```

## Request Format Changes [#request-format-changes]

### Sending Messages [#sending-messages]

#### v2 (Legacy) [#v2-legacy-1]

v2 sends to one recipient per request through separate endpoints. `POST /v2/messages/phone` is shown here; `POST /v2/messages/contact` takes `contactId` instead of `phoneNumber`:

```json
{
  "phoneNumber": "+1234567890",
  "templateId": "9ba7b840-9dad-11d1-80b4-00c04fd430c8",
  "templateVariables": {
    "name": "John",
    "order_id": "12345"
  }
}
```

#### v3 (Current) [#v3-current-1]

```json
{
  "to": ["+1234567890"],
  "template": {
    "id": "9ba7b840-9dad-11d1-80b4-00c04fd430c8",
    "name": "order_confirmation",
    "parameters": {
      "name": "John",
      "order_id": "12345"
    }
  },
  "channel": ["sms"],
  "sandbox": false
}
```

**Key Changes:**
- Separate `/v2/messages/phone` and `/v2/messages/contact` endpoints → single `POST /v3/messages`
- `phoneNumber` (single string) → `to` (array of recipients)
- `templateId` → `template.id` (inside the `template` object)
- `templateVariables` → `template.parameters`
- Added `template.name` (optional)
- Added `channel`: explicit per-request channel selection
- Added `sandbox`: sandbox mode is new in v3; v2 has no equivalent

## Response Format Changes [#response-format-changes]

### v2 (Legacy) [#v2-legacy-2]

`POST /v2/messages/phone` returns `202 Accepted` with a bare message ID:

```json
{
  "messageId": "8ba7b830-9dad-11d1-80b4-00c04fd430c8"
}
```

### v3 (Current) [#v3-current-2]

```json
{
  "success": true,
  "data": {
    "status": "QUEUED",
    "template_id": "9ba7b840-9dad-11d1-80b4-00c04fd430c8",
    "template_name": "order_confirmation",
    "recipients": [
      {
        "message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
        "to": "+1234567890",
        "channel": "sms"
      }
    ]
  },
  "error": null,
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-04T11:28:25.2096416+00:00",
    "version": "v3"
  }
}
```

**Key Changes:**
- Response is now wrapped in an envelope with `success`, `data`, `error`, `meta`
- Bare `messageId` → one entry per recipient and channel in `data.recipients[]`, each with its own `message_id`
- Added `meta.request_id` to quote in support tickets

## Error Format Changes [#error-format-changes]

### v2 (Legacy) [#v2-legacy-3]

v2 returns RFC 9110 problem details with human-readable text only:

```json
{
  "type": "https://www.rfc-editor.org/rfc/rfc9110#section-15.5.1",
  "title": "One or more validation errors occurred.",
  "status": 400,
  "errors": {
    "PhoneNumber": ["Phone number is required"]
  }
}
```

### v3 (Current) [#v3-current-3]

```json
{
  "success": false,
  "status": 402,
  "error": {
    "code": "BUSINESS_003",
    "message": "Account balance is insufficient to send this message",
    "doc_url": "https://docs.sent.dm/reference/api/error-catalog"
  },
  "meta": {
    "request_id": "req_abc123",
    "timestamp": "2026-03-04T11:28:25.2096416+00:00",
    "version": "v3"
  }
}
```

**Key Changes:**
- Errors now use the same envelope as success responses (`success: false`, `error`, `meta`) instead of RFC 9110 problem details
- Added machine-readable `error.code` values prefixed by category (for example, `BUSINESS_003`, `AUTH_001`, `VALIDATION_002`); match on the code instead of parsing message text
- Added `doc_url` with link to error documentation

## Webhook Event Changes [#webhook-event-changes]

### v2 (Legacy) [#v2-legacy-4]

Legacy webhooks delivered a flat body identified by a `type` field with the plural value `messages`:

```json
{
  "type": "messages",
  "timestamp": "2025-01-15T08:30:15Z",
  "message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
  "template_id": "9ba7b840-9dad-11d1-80b4-00c04fd430c8",
  "recipient_phone_number": "+1234567890",
  "message_status": "DELIVERED",
  "channel": "sms"
}
```

### v3 (Current) [#v3-current-4]

```json
{
  "field": "message",
  "event": "message.delivered",
  "timestamp": "2025-01-15T08:30:15Z",
  "payload": {
    "updated_at": "2025-01-15T08:30:15Z",
    "account_id": "7ba7b820-9dad-11d1-80b4-00c04fd430c8",
    "message_id": "8ba7b830-9dad-11d1-80b4-00c04fd430c8",
    "template_id": "9ba7b840-9dad-11d1-80b4-00c04fd430c8",
    "template_name": "order_confirmation",
    "outbound_number": "+1234567890",
    "message_status": "DELIVERED",
    "channel": "sms"
  }
}
```

**Key Changes:**
- `type` renamed to `field`; its value changed from `messages` (plural) to `message` (singular)
- Added `event`: granular sub-type (such as `message.delivered`, `message.failed`)
- Added `payload` wrapper: event data is now nested under `payload`
- `message_id`, `template_id`, `message_status`, and `channel` moved into `payload`
- `recipient_phone_number` → `payload.outbound_number`
- Added `payload.updated_at`, `payload.account_id`, and `payload.template_name`
- Webhooks still subscribed to the legacy `messages` event type keep receiving all `message.*` events; see the [Events Reference](/start/webhooks/event-types) for the full catalog

## Endpoint Mapping [#endpoint-mapping]

| v2 Endpoint | v3 Endpoint | Changes |
|-------------|-------------|---------|
| `POST /v2/messages/contact` | `POST /v3/messages` | Single send endpoint; new request/response format |
| `POST /v2/messages/phone` | `POST /v3/messages` | Single send endpoint; new request/response format |
| `GET /v2/messages/{id}` | `GET /v3/messages/{id}` | Response uses envelope format |
| `GET /v2/contacts` | `GET /v3/contacts` | Response uses envelope format |
| Not available in v2 | `POST /v3/contacts` | New in v3: create contacts through the API |
| `POST /v2/templates` | `POST /v3/templates` | New template structure |

## Idempotency Changes [#idempotency-changes]

### v2 (Legacy) [#v2-legacy-5]

v2 has no idempotency support: retrying a timed-out request can send the same message twice.

### v3 (Current) [#v3-current-5]

```bash
curl -X POST "https://api.sent.dm/v3/messages" \
  -H "x-api-key: $SENT_API_KEY" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: order_123_456" \
  -d '{
    "to": ["+1234567890"],
    "template": {"id": "9ba7b840-9dad-11d1-80b4-00c04fd430c8"}
  }'
```

**Key Changes:**
- Idempotency is new in v3: send an `Idempotency-Key` header on write requests to make retries safe
- Keys are cached for 24 hours

## Migration Steps [#migration-steps]

1. **Update Base URL** - Change from `/v2` to `/v3`
2. **Update Authentication** - Remove the `x-sender-id` header. Keep `x-api-key`, or send the key as `Authorization: Bearer` instead
3. **Update Request Format** - Replace `phoneNumber`/`contactId` with the `to` array, `templateId` with `template.id`, and `templateVariables` with `template.parameters`
4. **Update Response Handling** - Handle the new envelope format with `success`, `data`, `error`, `meta`
5. **Update Error Handling** - Match on the new `error.code` values (for example, `BUSINESS_003`) instead of parsing error text
6. **Update Webhook Handlers** - Adjust for new nested event structure (`payload` wrapper added; use `payload.message_id` and `payload.message_status`)
7. **Add Idempotency** - Send an `Idempotency-Key` header on write requests (new in v3)
8. **Test in Sandbox Mode** - Validate all features with `sandbox: true`
9. **Deploy Gradually** - Use feature flags for rollout

<Callout type="warning">
The v2 API is deprecated for new integrations but remains operational, and no sunset date has been announced. New capabilities such as sandbox mode, idempotency keys, and contact creation ship in v3 only, so plan your migration now rather than against a deadline. Watch the [API changelog](/reference/changelog) for version and deprecation announcements.
</Callout>

---
