Order UK local promo numbers via API

When to use the UK local promo number orders endpoint

Before you begin

• The campaign country is the UK. See International Number Support. If UK local numbers are not available on the network, contact Invoca.
• The advertiser campaign is live. A syndicated campaign gives your publishers access to a campaign that runs on another network. Invoca does not add promo numbers to a paused campaign, a campaign that is not live yet, a suspended advertiser, or a syndicated campaign.
• You can add promo numbers on that campaign, and you have an API token. In the sidebar, click Integrations > Manage Integrations > Invoca APIs. See OAuth Authentication: Token Generation and Manage API Credentials.
• You know the network ID and the advertiser and advertiser campaign id_from_network values. id_from_network is the identifier your network assigned. The order URL uses that value, not Invoca’s internal id.

Send the UK local order request

1. Send POST to this URL. Replace the three IDs. Use API version 2026-02-01. 2022-08-01 omits this endpoint. https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers/orders.json
2. Send JSON with count and exactly one of city or area_code.
   • city is a UK city name. Invoca matches it without case sensitivity (London, Manchester) and echoes that string.
   • area_code is a numeric UK dialing code, an integer or a numeric string. Examples: 20 or "20" (London) and 121 or "121" (Birmingham). An empty string is missing. Invoca rejects a whitespace-only value or any other non-numeric string.
   • count is an integer from 1 to 100. Invoca accepts a numeric string such as "5".
   City order:
   {
     "description": "UK tracking number",
     "media_type": "Online: Display",
     "city": "London",
     "count": 5
   }
   
   Area-code order:
   {
     "description": "UK tracking number",
     "media_type": "Online: Display",
     "area_code": 121,
     "count": 2
   }
   
3. Optionally set description and media_type. media_type uses the promo number values. Google Call Extension is also valid. With Google Call Extension, send adwords_account_id (for example, "627-345-9815"). The account must be in the campaign owner’s Google Ads integration. Invoca accepts adwords_account_id only with that media type.
4. Authenticate as you do for other Network Integration calls. Manage API Credentials documents the Authorization header. Invoca returns HTTP 401 when the token is missing or not accepted.

Confirm the UK local order

5. Read the HTTP 200 body. requested_count is the count you sent. allocated_count is how many numbers this call saved. allocation_request_ids lists the allocation requests this call created. One call can return more than one ID.
   {
     "city": "London",
     "requested_count": 5,
     "allocated_count": 5,
     "allocation_request_ids": [1001]
   }
   
   An area-code order also returns area_code as the matched dial-code string. Integer 121 comes back as "121". "020" comes back as "20". city is the mapped city (Birmingham for 121).
6. After carrier provisioning, confirm the numbers on Direct Promo Numbers, or retrieve them with the promo numbers API.

Handle a UK local shortfall or an order over 100

Warning: A retry is not idempotent. Each POST creates new allocation requests. Sending the same body again orders more numbers. It does not return the allocation_request_ids from the earlier call. To fill a gap, send a new request for the remaining quantity only after you have checked allocated_count.