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

# Order UK local promo numbers via API

> Order up to 100 UK local promo numbers for one city or area code on a live advertiser campaign with the Network Integration API.

**Network users who manage UK campaigns with the Network Integration API can order local promo numbers for one city or area code on a live advertiser campaign.**

Each call orders numbers for one location on one advertiser campaign. An allocation request is the order Invoca saves for that location.

The response lists `allocation_request_ids` and no phone numbers. Carrier provisioning is the carrier step that assigns the numbers afterward. They show on **Direct Promo Numbers** only after that finishes.

## When to use the UK local promo number orders endpoint

Use `POST .../promo_numbers/orders.json` for local numbers on a UK advertiser campaign, for one city or one area code.

Use [`POST /promo_numbers.json`](https://docs.invoca.com/s/article/create-static-promo-numbers-via-api) to create one static promo number. That endpoint is unchanged. It creates a toll-free number, or a local number from a `local_center` (ZIP code, or city and state).

Invoca rejects a non-UK campaign, including one with no country, and rejects a body that includes `affiliate_id_from_network`. Field tables are in [UK local number orders](https://docs.invoca.com/en/latest/api_documentation/network_integration/promo_numbers/index.md#uk-local-number-orders). If Invoca rejects the call, see [Troubleshoot UK local promo number order rejections](https://docs.invoca.com/s/article/troubleshoot-uk-local-promo-number-order-rejections.md).

## Before you begin

* The campaign country is the UK. See [International Number Support](https://docs.invoca.com/s/article/international-number-support.md). If UK local numbers are not available on the network, contact [Invoca](https://support.invoca.com/s/).
* 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](https://docs.invoca.com/s/article/oauth-authentication-token-generation.md) and [Manage API Credentials](https://docs.invoca.com/en/latest/api_documentation/manage_api_credentials.md).
* 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:

   ```json theme={null}
   {
     "description": "UK tracking number",
     "media_type": "Online: Display",
     "city": "London",
     "count": 5
   }
   ```

   Area-code order:

   ```json theme={null}
   {
     "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](https://docs.invoca.com/en/latest/api_documentation/manage_api_credentials.md) 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.

   ```json theme={null}
   {
     "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](https://docs.invoca.com/s/article/retrieve-all-promo-numbers-via-api.md).

## Handle a UK local shortfall or an order over 100

`allocated_count` can be lower than `requested_count`, including when one carrier saves a request and a later carrier fails. Invoca still returns HTTP 200 for the quantity it saved.

> **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`.

Invoca rejects a count over 100, such as 110, before lookup. To order more than 100 numbers, send separate requests of 100 or fewer. Each request is a new order. For any other invalid `count`, Invoca returns HTTP 422 with `count must be between 1 and 100`.


## Related topics

- [Troubleshoot UK local promo number order rejections](https://docs.invoca.com/s/article/troubleshoot-uk-local-promo-number-order-rejections.md)
- [How to Create Static Promo Numbers via API](https://docs.invoca.com/s/article/create-static-promo-numbers-via-api.md)
- [International Number Support](https://docs.invoca.com/s/article/international-number-support.md)
- [Promo Numbers](https://docs.invoca.com/developers/2026-02-01/api_documentation/network_integration/promo_numbers/index.md)