Attaching a Number to a Campaign

Before a phone number can send production traffic, it must be attached to an active campaign. The campaign tells carriers who's behind the number and what use case it's registered for.

How attachment works

Surge handles campaign attachment automatically — there's no separate API call to make. Attachment is triggered in two situations:

When you purchase a number while a campaign is already active. Surge attaches the number to the active campaign as part of the purchase transaction. The phone number response will show the campaign ID:

{
  "id": "pn_01jrzhe8d9enptypyx360pcmxm",
  "number": "+18015559876",
  "type": "local",
  "campaign_id": "cpn_01jrzhe8d9enptypyx360pcmxl"
}

When a campaign becomes active while numbers already exist. Once Surge approves a campaign and moves it to active status, any unattached phone numbers on the account are attached to the campaign automatically.

Knowing when attachment completes

Attachment happens asynchronously after the campaign approval. Once complete, Surge fires the phone_number.attached_to_campaign webhook event:

{
  "type": "phone_number.attached_to_campaign",
  "data": {
    "id": "pn_01jrzhe8d9enptypyx360pcmxm",
    "number": "+18015559876",
    "campaign_id": "cpn_01jrzhe8d9enptypyx360pcmxl"
  }
}

Wait for this event before sending production messages from the number. You can also check whether a number is attached by listing your phone numbers (GET /accounts/:account_id/phone_numbers) and inspecting the campaign_id field.

The typical sequence

1. Create an account, submit a campaign (POST /accounts/:account_id/campaigns)
2. Purchase one or more phone numbers (POST /accounts/:account_id/phone_numbers) — campaign_id is null at this point if the campaign isn't yet active
3. Campaign moves through pending → in_review → active
4. Surge auto-attaches all unattached numbers on the account to the newly active campaign
5. phone_number.attached_to_campaign fires for each number — numbers are now ready for production traffic

If you purchase a number after the campaign is already active, steps 4 and 5 happen during the purchase in step 2.

Multiple numbers on one campaign

A campaign can have multiple phone numbers attached. This is common when you need to distribute sending volume or provide dedicated numbers for different teams or use cases under the same registered campaign.

Why there's no manual attachment endpoint

Carriers require that every number be registered under a specific campaign. Surge enforces this by managing attachment automatically during campaign approval, ensuring numbers are never left in a permanently unattached state after a campaign becomes active. The webhook is the intended signal for readiness — listen for phone_number.attached_to_campaign rather than polling.