> ## Documentation Index
> Fetch the complete documentation index at: https://docs.kapso.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Migrate WhatsApp accounts between solutions

> Move a WhatsApp number to your Multi-partner Solution from another solution

Use your project API key and an active destination [Multi-partner Solution](https://docs.kapso.ai/docs/platform/tech-providers/multi-partner-solutions.md). The `waba_id` in both routes is the **source Meta WABA ID**. Kapso selects the destination solution from your project. Meta creates a destination WABA for the number.

## Move a number from another solution

1. From your backend, create an intent with Meta's [Set solution migration intent API](https://developers.facebook.com/documentation/business-messaging/whatsapp/reference/whatsapp-business-account/set-solution-migration-intent-api). Call `POST /{source_waba_id}/set_solution_migration_intent` with your source business token and the destination Meta `solution_id`. Save the returned ID.

2. Register the intent with Kapso before the business removes access to the source account. Send this body to `POST /platform/v1/whatsapp/accounts/{waba_id}/partner_solution_migrations`.

   ```json theme={null}
   {
     "type": "migrate_between_solutions",
     "migration_intent_id": "123456789012345",
     "business_portfolio_id": "234567890123456",
     "phone_number": "+56912345678",
     "source_business_token": "<source Meta business token>"
   }
   ```

   Keep the token on your backend. Kapso uses it to verify the source account, intent, and number, then discards it. You can omit it if Kapso already has an eligible source connection in your project. For **Kapso infrastructure**, also send the destination Kapso `customer_id`.

3. When the business is ready for cutover, have its admin complete Meta's authorization steps in **Business settings → Requests → Received**. After Meta accepts the intent, Kapso verifies the destination owner and billing before moving the number.

4. [Poll the migration](#check-migration-status). With **Kapso infrastructure**, Kapso verifies messaging access for the selected Meta app before cutover and completes the connection. With **Your infrastructure**, wait for `awaiting_tech_provider`. Use the returned `phone_number_id` to call Meta's `POST /{phone_number_id}/register`, then subscribe your app with `POST /{destination_waba_id}/subscribed_apps` and test sending and receiving from your backend.

> [!NOTE]
>
> Meta copies eligible templates to the new WABA. Check the templates you use before sending. Plan the cutover with the business.

## Check migration status

```bash theme={null}
curl "https://api.kapso.ai/platform/v1/whatsapp/accounts/$SOURCE_WABA_ID/partner_solution_migrations/$MIGRATION_ID" \
  -H "X-API-Key: $KAPSO_API_KEY"
```

Use the same project, source WABA ID, and returned `migration_id` throughout the operation. Resubmit the same Meta intent with the same inputs to recover the operation ID. Reusing a Meta intent with different inputs returns `409`.

| Status | What to do |
| - | - |
| `awaiting_customer_approval` | Ask the business admin to complete the request in Meta. |
| `awaiting_tech_provider` | Finish the number registration and webhook setup on your backend. |
| `completed` | Kapso finished managed setup. Check `funding_status` for billing. |
| `needs_attention` | Check `error_kind` and any destination IDs. Share the migration ID with Kapso Support. |
| `failed`, `expired` | Check the intent in Meta before starting another operation. |

For other statuses, keep polling. If Meta's response to the number move is unclear, Kapso checks the destination for the number before asking for support.


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.