Assign a number to a messaging campaign

Assign a sending number to a campaign

Use this operation after your messaging brand and production campaign are registered and the campaign is active. It associates one SMS-enabled number on your account with the campaign. It does not create a brand, create or approve a campaign, buy a number, or send a message.

The current portal uses this route when assigning a campaign to a number. The public API accepts a campaign identifier; it derives the brand from the account-owned campaign rather than accepting a separate brand identifier.

Request

Send a form-encoded POST over HTTPS using your enabled API account and its permitted source IP address. Use the actual number and campaign identifiers from your account. The number in this example is fictional.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'action=add' \
  --data-urlencode "campaign=$CAMPAIGN_ID" \
  --data-urlencode 'number=12025550123' \
  'https://api.multitel.net/v3/campaign'

Campaign assignment parameters
Parameter	Required	Meaning
action	Yes	Use add to assign or delete to remove the number’s current campaign association. Case and surrounding spaces are normalized.
campaign	For add	The campaignId of an ACTIVE campaign owned by the authenticated account. Its brand must also belong to the account. A campaign explicitly marked as sandbox cannot be assigned to live sending numbers. Omit this parameter for delete; removal uses the number’s existing association.
number	Yes	The owned, active, non-void, SMS-enabled sending number. For a North American number, use country code 1 followed by its ten digits, without a plus sign. The handler removes non-digit characters and also looks up plus-prefixed and ten-digit equivalents. This normalization is not a general phone-number validity check.

The operation changes one number. It has no pagination, batch parameter or dry-run option. Do not use a campaign creation endpoint merely to attach a number to an existing campaign.

Remove the current association

Use action=delete with the owned number. This removes its sending-campaign association and clears the saved brand/campaign fields for that number. It does not delete the campaign or brand, release the phone number, cancel the number’s service, or stop the campaign’s recurring billing.

curl --silent --show-error --user "$API_USER:$API_PASSWORD" \
  --data-urlencode 'action=delete' \
  --data-urlencode 'number=12025550123' \
  'https://api.multitel.net/v3/campaign'

Response and verification

This fictional example illustrates the ordinary API response envelope and selected result fields. The returned number preserves the format stored in your account. brandId and campaignId are empty strings after a successful removal.

{
  "status": {"code": 200, "msg": "Campaign assignment updated."},
  "response": {
    "number": "+12025550123",
    "brandId": "BRAND_FROM_ACCOUNT",
    "campaignId": "CAMPAIGN_FROM_ACCOUNT",
    "providerStatus": 200
  }
}

providerStatus is the messaging partner’s HTTP status. The handler accepts a 2xx transport response and then updates the local number record; it does not interpret the partner’s response body for a separate business-level acceptance result. A success response is therefore not proof that messaging registration is complete or that delivery will succeed. Review the number’s campaign status in the portal before sending production traffic.

Do not treat a local association alone as delivery approval. Campaign and brand approval, number provisioning, account permissions, content rules and ordinary messaging limits still apply.

Errors and partial results

401: no authenticated account is available to the handler.
400: action or number is missing/invalid, or an add request has no campaign identifier.
404: the number is not an owned, active, non-void SMS number.
409: the campaign is unavailable to the account, is not ACTIVE, is explicitly sandbox, or its brand is unavailable to the account.
503: the messaging integration is unavailable. Contact support rather than changing account credentials or inventing configuration values.
502: the messaging request failed, timed out or returned a non-2xx HTTP status. providerStatus may be returned. A timeout does not prove that the partner made no change.
500 with partial=true: the messaging partner returned a successful HTTP status, but the local association could not be confirmed. Reconcile the number in the portal or contact support before retrying.

Check the API status code and response body as well as the HTTP result. Do not blindly retry a timeout or partial result. This handler has no request-level idempotency key, transactional rollback or campaign-registration completion check. A repeated matching local assignment can return success even when the database reports no changed rows.

Scope and effects

This operation changes sending-number routing and its saved campaign/brand association. It contains no direct account debit, campaign creation, purchase or message send in the reviewed handler. This is not a price quote or a promise of free service: existing number, campaign and messaging charges continue under your account terms.

In the portal, changing to a different campaign first removes the previous association and then adds the new one. Those are separate requests. If the second request fails, the earlier association may already be removed. Do not assume the two requests roll back together.