---
title: "Create setup link"
method: POST
path: "/customers/{customer_id}/setup_links"
tags: ["Setup Links"]
---

# Create setup link

`POST /customers/{customer_id}/setup_links`

Generate a hosted onboarding page for customers to connect their WhatsApp number.

The link guides them through Meta's embedded signup and optionally provisions a new number.

## Request body

- SetupLinkCreateRequest
  - `setup_link` object, required
    - `success_redirect_url` string, uri, nullable
    - `failure_redirect_url` string, uri, nullable
    - `provision_phone_number` boolean — Requires Twilio credentials for non-US numbers
    - `phone_number_area_code` string, nullable — US only
    - `allowed_connection_types` string[] — Single value auto-selects for customer
    - `meta_billing_mode` 'customer_managed' | 'partner_managed' — Meta billing policy for the WABA. This value cannot be changed after the link is created. `partner_managed` requires Kapso-managed Meta credentials. Final WABA eligibility is checked after connection; setup can complete even when billing attachment needs attention.
    - `theme_config` object, nullable
      - `primary_color` string
      - `primary_foreground_color` string
      - `background_color` string
      - `text_color` string
      - `muted_text_color` string
      - `card_color` string
      - `muted_color` string
      - `border_color` string
      - `secondary_color` string
      - `secondary_foreground_color` string
      - `destructive_color` string
      - `destructive_foreground_color` string
    - `phone_number_country_isos` string[]
    - `reconnect_phone_number` string, nullable — Existing WhatsApp number for this customer to reconnect. Phone numbers are normalized to E.164 digits. When set: - The number must match an existing production WhatsApp config on the customer - `provision_phone_number` must be `false` (or omitted) - `allowed_connection_types` must match the existing config (`["dedicated"]` or `["coexistence"]`)
    - `language` 'en' | 'es' | 'pt' | 'hi' | 'id' | 'ar' | 'null', nullable — ISO 639-1 language code for setup link UI

## Response `201`

Setup link created

- SetupLinkResponse
  - `data` SetupLink, required
    - `id` string, uuid, required
    - `status` 'active' | 'used' | 'expired' | 'revoked', required
    - `created_at` string, date-time, required
    - `expires_at` string, date-time, nullable — Expires 30 days after creation by default
    - `url` string, uri, required
    - `success_redirect_url` string, uri, nullable
    - `failure_redirect_url` string, uri, nullable
    - `allowed_connection_types` string[] — `coexistence` - Use with WhatsApp Business App (5 msg/sec) `dedicated` - API-only through Kapso (up to 1000 msg/sec) Provide one value to auto-select for customer
    - `meta_billing_mode` 'customer_managed' | 'partner_managed', required — Policy selected when the setup link was created. `customer_managed` uses the WABA's Meta payment method. `partner_managed` requests Kapso billing for the entire WABA after Meta returns the connected account.
    - `theme_config` object, nullable — Hex colors for hosted onboarding page
      - `primary_color` string — Primary action buttons (default
      - `primary_foreground_color` string — Text on primary buttons (default
      - `background_color` string — Page background (default
      - `text_color` string — Body text (default
      - `muted_text_color` string — Secondary text (default
      - `card_color` string — Card backgrounds (defaults to background_color)
      - `muted_color` string — Disabled elements (default
      - `border_color` string — Borders and dividers (default
      - `secondary_color` string — Secondary buttons (default
      - `secondary_foreground_color` string — Text on secondary buttons (default
      - `destructive_color` string — Error/danger buttons (default
      - `destructive_foreground_color` string — Text on destructive buttons (default
    - `provision_phone_number` boolean, nullable — Auto-provision number during onboarding
    - `phone_number_area_code` string, nullable — US area code for provisioned numbers
    - `phone_number_country_isos` string[] — Allowed countries for provisioning (defaults to ["US"])
    - `reconnect_phone_number` string, nullable — Normalized E.164 digits of the customer's existing WhatsApp number this link is targeting for reconnect. Set this on create to scope the setup flow to a specific existing WhatsApp config for the same customer (token refresh / re-auth). When present, `provision_phone_number` is forced to `false` and `allowed_connection_types` is locked to match the existing config (`["dedicated"]` or `["coexistence"]`).
    - `language` 'en' | 'es' | 'pt' | 'hi' | 'id' | 'ar' | 'null', nullable — ISO 639-1 language code for setup link UI (en, es, pt, hi, id, ar). Defaults to user's browser language.
    - `whatsapp_setup_status` 'pending' | 'processing' | 'completed' | 'failed'
    - `whatsapp_setup_error` string, nullable
    - `provisioned_phone_number` PhoneNumberReference
      - `id` string, uuid, required
      - `phone_number` string, required
      - `status` string, required
      - `area_code` string, nullable
      - `country_iso` string, required
      - `country_dial_code` string, required
      - `display_number` string, nullable

## Other responses

- `401` — Missing or invalid API key
- `404` — Resource not found
- `422` — Request validation failed

---

[API](https://skmtc.net/kapso/apis/kapso-platform-api.md) · [All operations](https://skmtc.net/kapso/apis/kapso-platform-api/llms.txt) · [OpenAPI document](https://skmtc-service-staging.skmtc.workers.dev/v1/apis/kapso/kapso-platform-api/revisions/18ff5548a33f/schema)