> ## 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.

# Promo Numbers

## Advertiser Campaign and Affiliate Campaign Promo Numbers

The API provides the ability to manage promo numbers for a given campaign. Promo numbers are uniquely identified by the phone number itself and these numbers are always generated by the Invoca platform. Therefore, the operations on the promo numbers interface are not idempotent. When you POST a promo number, we return the promo\_number in the response body. This capability is JSON‐only.

<table><thead><tr><th>Property</th><th>Type</th><th>Value</th></tr></thead><tbody><tr><td>id</td><td>integer (read-only)</td><td>The internal Invoca id of the promo number.</td></tr><tr><td>id\_from\_network</td><td>string</td><td>Network specific id of the promo number.</td></tr><tr><td>description</td><td>string (required)</td><td>Arbitrary description</td></tr><tr><td>media\_type</td><td>string (required)</td><td>one of:“Online: Content / Review Site”“Online: Discount / Coupon Site”“Online: Display”“Online: Email”“Online: Rewards / Incentive”“Online: Lead Form / Co Reg”“Online: Search”“Online: Social Media”“Online: Software”“Online: Other”“Mobile: Apps”“Mobile: Display”“Mobile: Search”“Mobile: SMS”“Mobile: Other”“Offline: Business Publication”“Offline: Call Center”“Offline: Direct Mail”“Offline: Directory”“Offline: Newspaper”“Offline: In­Call Ad”“Offline: Magazine”“Offline: Outdoor”“Offline: Radio”“Offline: TV”“Offline: Other”</td></tr><tr><td>object\_url</td><td>string (read-only)</td><td>URL for reaching the promo number in the UI.</td></tr><tr><td>local\_center</td><td>hash</td><td>Requires one of the followingCity & State required togetherA filled field determines the center to start looking for local numbers at.**“tn\_prefix”**: an npa**“zipcode”**: a valid zipcode**“city”**: a valid city**“state”**: a valid state</td></tr><tr><td>local\_number\_preferences</td><td>hash</td><td>Both are optional**“search\_radius\_miles”**: An integer, greater than or equal to 0. Default is 240. Represents the number of miles from the location to search.**“restrict\_search\_to\_state”**: A boolean. Default: True. Used to restrict search to be within state boundaries.</td></tr><tr><td>tn\_prefix\_whitelist</td><td>array of strings</td><td>an array of stringified limiters on the boundaries of where to look for local numbers given as npas (ex. \[“805”, “212”])</td></tr><tr><td>promo\_type</td><td>string (optional)</td><td>For international campaigns that support local or mobile numbers. If not passed then promo numbers will default to the organizational default. (US/CA campaigns will continue to use local\_center for local numbers)“Local”“Mobile”</td></tr><tr><td>adwords\_account\_id</td><td>string (optional)</td><td>The ID of the AdWords client account to be associated with this promo number. Requires media type to be set to ‘Google Call Extension’. (ex. “627-345-9815”)</td></tr><tr><td>destination\_advertiser\_id\_from\_network</td><td>string (optional)</td><td>The ID of the advertiser in which the promo number is intended to be moved to.  If this field is used, **destination\_advertiser\_campaign\_id\_from\_network** also must be included.<ul><li>Do not include this field if you do not intend to move the promo number.</li></ul></td></tr><tr><td>destination\_advertiser\_campaign\_id\_from\_network</td><td>string (optional)</td><td>The ID of the advertiser campaign in which the promo number is intended to be moved to.  If this field is used, **destination\_advertiser\_id\_from\_network** also must be included.<ul><li>Do not include this field if you do not intend to move the promo number.</li></ul></td></tr><tr><td>destination\_affiliate\_id\_from\_network</td><td>string (optional)</td><td>The ID of the affiliate in which the promo number is intended to be moved to. Only to be used when moving promo numbers between affiliate campaigns. If this field is used, both **destination\_advertiser\_campaign\_id\_from\_network** and **destination\_advertiser\_id\_from\_network** also must be included.<ul><li>Do not include this field if you do not intend to move the promo number.</li></ul></td></tr><tr><td>hours\_of\_operation</td><td>hash (optional)</td><td>Configures when the destination is available to receive calls. If not provided, the campaign’s hours of operation settings will apply.**Requirements:** This field is only available for promo numbers that belong to an advertiser campaign (not affiliate campaigns).**“open\_24\_7”**: boolean. When true, the destination is always available. When false, schedules must be provided.**“time\_zone”**: string (required). Rails ActiveSupport timezone name (e.g., “Pacific Time (US & Canada)”, “Eastern Time (US & Canada)”, “Central Time (US & Canada)”, “Mountain Time (US & Canada)”, “Arizona”). See [[https://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html](https://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html)](https://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html) for full list.**“schedules”**: array of hashes (required when open\_24\_7 is false). Each schedule contains:<ul><li>**“day\_of\_week”**: string. Day of the week: “Sunday”, “Monday”, “Tuesday”, “Wednesday”, “Thursday”, “Friday”, or “Saturday”.</li><li>**“open\_time”**: string. Opening time in HH:MM format (15-minute increments, e.g., “09:00”).</li><li>**“close\_time”**: string. Closing time in HH:MM format (15-minute increments, e.g., “17:00”).</li></ul>Schedules cannot overlap. To remove hours of operation, pass null, empty string, empty array, or empty hash.</td></tr></tbody></table>

## Custom Data

Promo numbers may have Custom Data Fields applied to them, which will be applied to calls originating through the promo number. To apply Custom Data Values to a promo number, the top level parameter `custom_data` should be assigned a hash with each pair’s key corresponding to a partner name. The value of the pair should be the value to be applied.

For the following example, we would apply the value “Offline newspaper” to the Custom Data Field “channel”.

```json theme={null}
{
  "custom_data": {
    "channel": "Offline newspaper"
  }
}
```

## API Endpoints

The following endpoints are for use when you have your own ID’s (id\_from\_network) and wish to use that as the identifier.

`https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers_by_id/<promo_number_id_from_network>.json`

> [accordion] Get all Promo Numbers
>
> #### Examples
>
> Read all Advertiser Campaign Promo Numbers as an array
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers_by_id.json`
>
> Format: application/json
>
> Response Code: 200
>
> Response Body:
>
> ```json theme={null}
> [
>   {
>     "id": 21,
>     "id_from_network": "4531",
>     "media_type": "Online: Display",
>     "description": "Halloween Promo Number 1",
>     "promo_number": "8001234567",
>     "object_url": "https://invoca.net/a_campaigns/promo_numbers/11",
>     "custom_data": {
>       "channel": "Online lead"
>     }
>   }
> ]
> ```
>
> ***
>
> Read all Affiliate Campaign Promo Numbers as an array
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/affiliates/<affiliate_id_from_network>/affiliate_campaigns/promo_numbers_by_id.json`
>
> Format: application/json
>
> Response Code: 200
>
> Response Body:
>
> ```json theme={null}
> [
>   {
>     "id": 21,
>     "id_from_network": "4531",
>     "media_type": "Online: Display",
>     "description": "Halloween Promo Number 1",
>     "promo_number": "8001234567",
>     "object_url": "https://invoca.net/p_campaigns/promo_numbers/14/11",
>     "custom_data": {
>       "channel": "Online lead"
>     }
>   }
> ]
> ```

> [accordion] Read a Promo Number
>
> #### Examples
>
> Read a specific Advertiser Campaign Promo Number
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers_by_id/<promo_number_id_from_network>.json`
>
> Format: application/json
>
> Response Code: 200
>
> Response Body:
>
> ```json theme={null}
> {
>   "id": 21,
>   "id_from_network": "4531",
>   "media_type": "Online: Display",
>   "description": "Halloween Promo Number 1",
>   "promo_number": "8001234567",
>   "object_url": "https://invoca.net/a_campaigns/promo_numbers/11",
>   "custom_data": {
>     "channel": "Online lead"
>   }
> }
> ```
>
> ***
>
> Read a specific Affiliate Campaign Promo Number
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/affiliates/<affiliate_id_from_network>/affiliate_campaigns/promo_numbers_by_id/<promo_number_id_from_network>.json`
>
> Format: application/json
>
> Response Code: 200
>
> Response Body:
>
> ```json theme={null}
> {
>   "id": 21,
>   "id_from_network": "4531",
>   "media_type": "Online: Display",
>   "description": "Halloween Promo Number 1",
>   "promo_number": "8001234567",
>   "object_url": "https://invoca.net/p_campaigns/promo_numbers/14/11",
>   "custom_data": {
>     "channel": "Online lead"
>   }
> }
> ```

> [accordion] Create an Advertiser/Affiliate Promo Number
>
> #### Examples
>
> Create an Advertiser Campaign Promo Number
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers_by_id.json`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "id_from_network": "1234",
>   "description": "Halloween Promo Number 1",
>   "media_type": "Online: Display"
> }
> ```
>
> Response Code: 201
>
> Response Body:
>
> ```json theme={null}
> {
>   "id": 12,
>   "id_from_network": "1234",
>   "media_type": "Online: Display",
>   "promo_number": "8777657743",
>   "description": "Halloween Promo Number 1",
>   "object_url": "https://invoca.net/a_campaigns/promo_numbers/12",
>   "custom_data": {
>     "channel": "Online lead"
>   }
> }
> ```
>
> ***
>
> Create an Advertiser Campaign Local Promo Number with tn\_prefix
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers_by_id.json`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "id_from_network": "1234",
>   "description": "Halloween Promo Number 1",
>   "media_type": "Online: Display",
>   "local_center": {
>     "tn_prefix": "805"
>   },
>   "tn_prefix_whitelist": ["805"]
> }
> ```
>
> Response Code: 201
>
> Response Body:
>
> ```json theme={null}
> {
>   "id": 12,
>   "id_from_network": "1234",
>   "media_type": "Online: Display",
>   "promo_number": "8057657743",
>   "description": "Halloween Promo Number 1",
>   "object_url": "https://invoca.net/a_campaigns/promo_numbers/12",
>   "custom_data": {
>     "channel": "Online lead"
>   }
> }
> ```
>
> ***
>
> Create an Advertiser Campaign Local Promo Number with city/state
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers_by_id.json`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "id_from_network": "1234",
>   "description": "Halloween Promo Number 1",
>   "media_type": "Online: Display",
>   "local_center": {
>     "city": "Santa Barbara",
>     "state": "CA"
>   }
> }
> ```
>
> Response Code: 201
>
> Response Body:
>
> ```json theme={null}
> {
>   "id": 12,
>   "id_from_network": "1234",
>   "media_type": "Online: Display",
>   "promo_number": "8057657743",
>   "description": "Halloween Promo Number 1",
>   "object_url": "https://invoca.net/a_campaigns/promo_numbers/12",
>   "custom_data": {
>     "channel": "Online lead"
>   }
> }
> ```
>
> ***
>
> Create an Affiliate Campaign Promo Number
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/affiliates/<affiliate_id_from_network>/affiliate_campaigns/promo_numbers_by_id.json`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "id_from_network": "1234",
>   "description": "Halloween Promo Number 1",
>   "media_type": "Online: Display"
> }
> ```
>
> Response Code: 201
>
> Response Body:
>
> ```json theme={null}
> {
>   "id": 12,
>   "id_from_network": "1234",
>   "media_type": "Online: Display",
>   "promo_number": "8777657743",
>   "description": "Halloween Promo Number 1",
>   "object_url": "https://invoca.net/p_campaigns/promo_numbers/14/11",
>   "custom_data": {
>     "channel": "Online lead"
>   }
> }
> ```
>
> ***
>
> Create a Google Call Extension Promo Number
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers_by_id.json`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "id_from_network": "1234",
>   "description": "Google Call Extension Demo",
>   "media_type": "Google Call Extension",
>   "adwords_account_id": "7567575756755"
> }
> ```
>
> Response Code: 201
>
> Response Body:
>
> ```json theme={null}
> {
>   "id": 12,
>   "id_from_network": "1234",
>   "media_type": "Google Call Extension",
>   "promo_number": "8777657743",
>   "description": "Google Call Extension Demo",
>   "object_url": "https://invoca.net/a_campaigns/promo_numbers/12",
>   "custom_data": {
>     "channel": "Online lead"
>   }
> }
> ```

> [accordion] Update a Campaign Promo Number
>
> #### Examples
>
> Update an Advertiser Campaign Promo Number
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers_by_id/<promo_number_id_from_network>.json`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "description": "Halloween Promo Number 1 Updated",
>   "media_type": "Online: Display"
> }
> ```
>
> Response Code: 200
>
> Response Body:
>
> Same as a GET response, includes all the promo number properties.
>
> ***
>
> Update Affiliate Campaign Promo Number
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/affiliates/<affiliate_id_from_network>/affiliate_campaigns/promo_numbers_by_id/<promo_number_id_from_network>.json`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "description": "Halloween Promo Number 1 Updated",
>   "media_type": "Online: Display"
> }
> ```
>
> Response Code: 200
>
> Response Body:
>
> Same as a GET response, includes all the promo number properties.
>
> ***
>
> Moving an Advertiser Campaign Promo Number
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers_by_id/<promo_number_id_from_network>.json`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "description": "Halloween Promo Number 1 Updated",
>   "media_type": "Online: Display",
>   "destination_advertiser_id_from_network": "123",
>   "destination_advertiser_campaign_id_from_network": "456"
> }
> ```
>
> Response Code: 200
>
> Response Body:
>
> Same as a GET response, includes all the promo number properties.
>
> ***
>
> Moving an Affiliate Campaign Promo Number
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/affiliates/<affiliate_id_from_network>/affiliate_campaigns/promo_numbers_by_id/<promo_number_id_from_network>.json`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "description": "Halloween Promo Number 1 Updated",
>   "media_type": "Online: Display",
>   "destination_advertiser_id_from_network": "123",
>   "destination_advertiser_campaign_id_from_network": "456",
>   "destination_affiliate_id_from_network": "789"
> }
> ```
>
> Response Code: 200
>
> Response Body:
>
> Same as a GET response, includes all the promo number properties.

> [accordion] Delete a Campaign Promo Number
>
> #### Examples
>
> Delete an Advertiser Campaign Promo Number
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers_by_id/<promo_number_id_from_network>.json`
>
> Format: application/json
>
> Response Code: 200
>
> Response Body:
>
> ```json theme={null}
> {
> }
> ```
>
> ***
>
> Delete an Affiliate Campaign Promo Number
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/affiliates/<affiliate_id_from_network>/affiliate_campaigns/promo_numbers_by_id/<promo_number_id_from_network>.json`
>
> Format: application/json
>
> Response Code: 200
>
> Response Body:
>
> ```json theme={null}
> {
> }
> ```

The following endpoints are for use when you do **not** have your own ID’s (id\_from\_network) and you treat the phone number as the identifier.

`https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers/<promo_number>.json`

> [accordion] Get all Promo Numbers
>
> #### Examples
>
> Read all Advertiser Campaign Promo Numbers as an array
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers.json`
>
> Format: application/json
>
> Response Code: 200
>
> Response Body:
>
> ```json theme={null}
> [
>   {
>     "id": 21,
>     "id_from_network": "4531",
>     "media_type": "Online: Display",
>     "description": "Halloween Promo Number 1",
>     "promo_number": "8001234567",
>     "object_url": "https://invoca.net/a_campaigns/promo_numbers/11",
>     "custom_data": {
>       "channel": "Online lead"
>     }
>   }
> ]
> ```
>
> ***
>
> Read all Affiliate Campaign Promo Numbers as an array
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/affiliates/<affiliate_id_from_network>/affiliate_campaigns/promo_numbers.json`
>
> Format: application/json
>
> Response Code: 200
>
> Response Body:
>
> ```json theme={null}
> [
>   {
>     "id": 21,
>     "id_from_network": "4531",
>     "media_type": "Online: Display",
>     "description": "Halloween Promo Number 1",
>     "promo_number": "8001234567",
>     "object_url": "https://invoca.net/p_campaigns/promo_numbers/14/11",
>     "custom_data": {
>       "channel": "Online lead"
>     }
>   }
> ]
> ```

> [accordion] Read a Promo Number
>
> #### Examples
>
> Read a specific Advertiser Campaign Promo Number
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers/<promo_number>.json`
>
> Format: application/json
>
> Response Code: 200
>
> Response Body:
>
> ```json theme={null}
> {
>   "id": 21,
>   "id_from_network": "4531",
>   "media_type": "Online: Display",
>   "description": "Halloween Promo Number 1",
>   "promo_number": "8001234567",
>   "object_url": "https://invoca.net/a_campaigns/promo_numbers/11",
>   "custom_data": {
>     "channel": "Online lead"
>   }
> }
> ```
>
> ***
>
> Read a specific Affiliate Campaign Promo Number
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/affiliates/<affiliate_id_from_network>/affiliate_campaigns/promo_numbers/<promo_number>.json`
>
> Format: application/json
>
> Response Code: 200
>
> Response Body:
>
> ```json theme={null}
> {
>   "id": 21,
>   "id_from_network": "4531",
>   "media_type": "Online: Display",
>   "description": "Halloween Promo Number 1",
>   "promo_number": "8001234567",
>   "object_url": "https://invoca.net/p_campaigns/promo_numbers/14/11",
>   "custom_data": {
>     "channel": "Online lead"
>   }
> }
> ```

> [accordion] Create an Advertiser/Affiliate Promo Number
>
> #### Examples
>
> Create an Advertiser Campaign Promo Number
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers.json`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "description": "Halloween Promo Number 1",
>   "media_type": "Online: Display"
> }
> ```
>
> Response Code: 201
>
> Response Body:
>
> ```json theme={null}
> {
>   "id": 12,
>   "id_from_network": "12",
>   "media_type": "Online: Display",
>   "promo_number": "8777657743",
>   "description": "Halloween Promo Number 1",
>   "object_url": "https://invoca.net/a_campaigns/promo_numbers/12",
>   "custom_data": {
>     "channel": "Online lead"
>   }
> }
> ```
>
> ***
>
> Create an Advertiser Campaign Local Promo Number with tn\_prefix
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers.json`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "description": "Halloween Promo Number 1",
>   "media_type": "Online: Display",
>   "local_center": {
>     "tn_prefix": "805"
>   },
>   "tn_prefix_whitelist": ["805"]
> }
> ```
>
> Response Code: 201
>
> Response Body:
>
> ```json theme={null}
> {
>   "id": 12,
>   "id_from_network": "12",
>   "media_type": "Online: Display",
>   "promo_number": "8057657743",
>   "description": "Halloween Promo Number 1",
>   "object_url": "https://invoca.net/a_campaigns/promo_numbers/12",
>   "custom_data": {
>     "channel": "Online lead"
>   }
> }
> ```
>
> ***
>
> Create an Advertiser Campaign Local Promo Number with city/state
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers.json`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "description": "Halloween Promo Number 1",
>   "media_type": "Online: Display",
>   "local_center": {
>     "city": "Santa Barbara",
>     "state": "CA"
>   }
> }
> ```
>
> Response Code: 201
>
> Response Body:
>
> ```json theme={null}
> {
>   "id": 12,
>   "id_from_network": "12",
>   "media_type": "Online: Display",
>   "promo_number": "8057657743",
>   "description": "Halloween Promo Number 1",
>   "object_url": "https://invoca.net/a_campaigns/promo_numbers/12",
>   "custom_data": {
>     "channel": "Online lead"
>   }
> }
> ```
>
> ***
>
> Create an Affiliate Campaign Promo Number
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/affiliates/<affiliate_id_from_network>/affiliate_campaigns/promo_numbers.json`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "description": "Halloween Promo Number 1",
>   "media_type": "Online: Display"
> }
> ```
>
> Response Code: 201
>
> Response Body:
>
> ```json theme={null}
> {
>   "id": 12,
>   "id_from_network": "12",
>   "media_type": "Online: Display",
>   "promo_number": "8777657743",
>   "description": "Halloween Promo Number 1",
>   "object_url": "https://invoca.net/p_campaigns/promo_numbers/14/11",
>   "custom_data": {
>     "channel": "Online lead"
>   }
> }
> ```
>
> ***
>
> Create a Google Call Extension Promo Number
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers.json`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "description": "Google Call Extension Demo",
>   "media_type": "Google Call Extension",
>   "adwords_account_id": "7567575756755"
> }
> ```
>
> Response Code: 201
>
> Response Body:
>
> ```json theme={null}
> {
>   "id": 12,
>   "id_from_network": "12",
>   "media_type": "Google Call Extension",
>   "promo_number": "8777657743",
>   "description": "Google Call Extension Demo",
>   "object_url": "https://invoca.net/a_campaigns/promo_numbers/12",
>   "custom_data": {
>     "channel": "Online lead"
>   }
> }
> ```
>
> ***
>
> Create an Advertiser Campaign Promo Number with Hours of Operation
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers.json`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "description": "My Promo Number",
>   "media_type": "Online: Email",
>   "hours_of_operation": {
>     "open_24_7": false,
>     "time_zone": "Pacific Time (US & Canada)",
>     "schedules": [
>       {
>         "day_of_week": "Monday",
>         "open_time": "09:00",
>         "close_time": "17:00"
>       },
>       {
>         "day_of_week": "Tuesday",
>         "open_time": "09:00",
>         "close_time": "17:00"
>       },
>       {
>         "day_of_week": "Wednesday",
>         "open_time": "09:00",
>         "close_time": "17:00"
>       },
>       {
>         "day_of_week": "Thursday",
>         "open_time": "09:00",
>         "close_time": "17:00"
>       },
>       {
>         "day_of_week": "Friday",
>         "open_time": "09:00",
>         "close_time": "17:00"
>       }
>     ]
>   }
> }
> ```
>
> Response Code: 201
>
> Response Body:
>
> ```json theme={null}
> {
>   "id": 12,
>   "id_from_network": "12",
>   "media_type": "Online: Email",
>   "promo_number": "8777657743",
>   "description": "My Promo Number",
>   "object_url": "https://invoca.net/a_campaigns/promo_numbers/12",
>   "hours_of_operation": {
>     "open_24_7": false,
>     "time_zone": "Pacific Time (US & Canada)",
>     "schedules": [
>       {
>         "day_of_week": "Monday",
>         "open_time": "09:00",
>         "close_time": "17:00"
>       },
>       {
>         "day_of_week": "Tuesday",
>         "open_time": "09:00",
>         "close_time": "17:00"
>       },
>       {
>         "day_of_week": "Wednesday",
>         "open_time": "09:00",
>         "close_time": "17:00"
>       },
>       {
>         "day_of_week": "Thursday",
>         "open_time": "09:00",
>         "close_time": "17:00"
>       },
>       {
>         "day_of_week": "Friday",
>         "open_time": "09:00",
>         "close_time": "17:00"
>       }
>     ]
>   }
> }
> ```

> [accordion] Update a Campaign Promo Number
>
> #### Examples
>
> Update an Advertiser Campaign Promo Number
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers/<promo_number>.json`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "description": "Halloween Promo Number 1 Updated",
>   "media_type": "Online: Display"
> }
> ```
>
> Response Code: 200
>
> Response Body:
>
> Same as a GET response, includes all the promo number properties.
>
> ***
>
> Update Affiliate Campaign Promo Number
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/affiliates/<affiliate_id_from_network>/affiliate_campaigns/promo_numbers/<promo_number>.json`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "description": "Halloween Promo Number 1 Updated",
>   "media_type": "Online: Display"
> }
> ```
>
> Response Code: 200
>
> Response Body:
>
> Same as a GET response, includes all the promo number properties.
>
> ***
>
> Moving an Advertiser Campaign Promo Number
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers/<promo_number>.json`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "description": "Halloween Promo Number 1 Updated",
>   "media_type": "Online: Display",
>   "destination_advertiser_id_from_network": "123",
>   "destination_advertiser_campaign_id_from_network": "456"
> }
> ```
>
> Response Code: 200
>
> Response Body:
>
> Same as a GET response, includes all the promo number properties.
>
> ***
>
> Moving an Affiliate Campaign Promo Number
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/affiliates/<affiliate_id_from_network>/affiliate_campaigns/promo_numbers/<promo_number>.json`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "description": "Halloween Promo Number 1 Updated",
>   "media_type": "Online: Display",
>   "destination_advertiser_id_from_network": "123",
>   "destination_advertiser_campaign_id_from_network": "456",
>   "destination_affiliate_id_from_network": "789"
> }
> ```
>
> Response Code: 200
>
> Response Body:
>
> Same as a GET response, includes all the promo number properties.

> [accordion] Delete a Campaign Promo Number
>
> #### Examples
>
> Delete an Advertiser Campaign Promo Number
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers/<promo_number>.json`
>
> Format: application/json
>
> Response Code: 200
>
> Response Body:
>
> ```json theme={null}
> {
> }
> ```
>
> ***
>
> Delete an Affiliate Campaign Promo Number
>
> Endpoint:
>
> `https://invoca.net/api/2026-02-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/affiliates/<affiliate_id_from_network>/affiliate_campaigns/promo_numbers/<promo_number>.json`
>
> Format: application/json
>
> Response Code: 200
>
> Response Body:
>
> ```json theme={null}
> {
> }
> ```

## UK local number orders

Orders UK local promo numbers for one location on one advertiser campaign. Only UK campaigns are supported. This call doesn't return the phone number.

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

> [accordion] Order UK local promo numbers for one location on an advertiser campaign
>
> Orders UK local promo numbers for one location on one advertiser campaign. Only UK campaigns are supported. The request supplies exactly one of `city` or `area_code`, plus `count`.
>
> A successful order returns the fields under [Response (HTTP 200)](#response-http-200). This call doesn't return the phone number. The number appears on the campaign once carrier provisioning completes.
>
> [Rejection messages](#rejection-messages) lists validation failures, the affiliate and locale rejections, and the order in which those checks run.
>
> #### Request parameters
>
> <table><thead><tr><th>Property</th><th>Type</th><th>Value</th></tr></thead><tbody><tr><td>description</td><td>string (optional)</td><td>Description applied to the allocation request.</td></tr><tr><td>media\_type</td><td>string (optional)</td><td>Media type applied to the allocation request. Same values as the promo number `media_type` property. `Google Call Extension` is also valid here. See `adwords_account_id`.</td></tr><tr><td>adwords\_account\_id</td><td>string (optional)</td><td>The ID of the AdWords client account to associate with this promo number. Requires `media_type` to be set to `Google Call Extension`. For example, `"627-345-9815"`.</td></tr><tr><td>city</td><td>string (conditional)</td><td>Exactly one of `city` or `area_code` is required. UK city name matched case-insensitively against the UK area-code data (for example, `"London"`, `"Manchester"`). The response echoes this string as sent. An empty string is treated as absent.</td></tr><tr><td>area\_code</td><td>integer or numeric string (conditional)</td><td>Exactly one of `city` or `area_code` is required. Numeric UK dialing code (for example, `20` or `"20"` for London, `121` or `"121"` for Birmingham). An empty string is treated as absent. A string of only whitespace, or any other string that is not all digits, is rejected (see Rejection messages).The response `area_code` is the matched dial-code string from the UK area-code data, not the raw submitted value. Integer `121` and `"020"` are returned as `"121"` and `"20"`. Every distinct carrier prefix for that dial code is eligible. Carriers are tried in priority order.</td></tr><tr><td>count</td><td>integer or numeric string (required)</td><td>How many local numbers to order for this location. Accepted values and the over-100 rejection are under Rejection messages.</td></tr></tbody></table>
>
> #### Response (HTTP 200)
>
> <table><thead><tr><th>Property</th><th>Type</th><th>Value</th></tr></thead><tbody><tr><td>city</td><td>string</td><td>For a city order, the city string from the request. For an area-code order, the city that area code maps to in the UK area-code data.</td></tr><tr><td>area\_code</td><td>string</td><td>Present only for an area-code order. The matched UK dial-code string from the UK area-code data. Integer `121` is returned as `"121"`. `"020"` is returned as `"20"`.</td></tr><tr><td>requested\_count</td><td>integer</td><td>The `count` from the request, as an integer.</td></tr><tr><td>allocated\_count</td><td>integer</td><td>Quantity saved on this call: the sum of the allocation-request quantities. Compare it with `requested_count`. It can be lower when one carrier saves a request and a later carrier fails.Retrying only the shortfall is not idempotent. Each call creates new allocation requests, so a retry orders more numbers instead of returning the requests already created. Account for this in your client.</td></tr><tr><td>allocation\_request\_ids</td><td>array of integers</td><td>IDs of the allocation requests created for this call. One call can have more than one ID. This call doesn't return the phone number.</td></tr></tbody></table>
>
> #### Rejection messages
>
> HTTP 422 rejections use the body shape `{ "errors": { "<key>": ["<message>"] } }`.
>
> Checks run in this order. The first failure is the only one returned.
>
> 1. Authentication. An unauthenticated caller receives HTTP 401, the shared Network Integration API challenge, before any of the checks below.
> 2. The advertiser and advertiser campaign in the URL must exist. A missing one returns HTTP 404 with the body `{"errors":{"class":"RecordNotFound","invalid_data":"<message>"}}`.
> 3. Authorization. The caller must be allowed to add promo numbers on the campaign. This runs before the affiliate and locale rejections. A paused, not-live, suspended, or otherwise unauthorized campaign returns HTTP 403 even when the locale is not UK or the request includes `affiliate_id_from_network`. The 403 messages are in the status table.
> 4. `affiliate_id_from_network`, when present, returns HTTP 422 `promo number orders are only available for the advertiser campaign`. This route orders for the advertiser campaign only.
> 5. A campaign whose locale is not UK, including a locale with no country code, returns HTTP 422 on `errors.locale` with `promo number orders are only available for UK campaigns`. No city or area code is looked up.
> 6. Location shape, then `count`, then the UK area-code lookup, then allocation. Inside allocation, Invoca checks the network promo number limit first, then the AdWords and Google Call Extension rules.
>
> Rejection keys and messages:
>
> * `affiliate_id_from_network`: `promo number orders are only available for the advertiser campaign`
> * `locale`: `promo number orders are only available for UK campaigns`
> * `city`: `city must be a string`
> * `area_code`: `area_code must be an integer or a numeric string`. This includes a whitespace-only `area_code`. An empty string is treated as absent, not invalid.
> * `city`: `Specify exactly one of 'city' or 'area_code', not both`
> * `city`: `Specify exactly one of 'city' or 'area_code'`
> * `count`: `Total requested count (N) exceeds maximum of 100`. Returned for an integer over 100, before lookup.
> * `count`: `count must be between 1 and 100`. Returned for anything else that is not an integer from 1 to 100. A numeric string such as `"5"` is accepted.
> * `city`: `City '<city>' not found in UK area code database`
> * `area_code`: `Area code '<area_code>' not found in UK area code database`. The message quotes the submitted value.
> * `city` or `area_code`: `Your network has reached its promo number limit based on its current allocation. To request more promo numbers, please contact us.` The last words are the network's contact-support text, or a link to it. Allocation returns this on `city` when the request did not send an area code, otherwise on `area_code`.
> * `city` or `area_code`: `Number allocation failed`
> * `city` or `area_code`: `Number allocation did not produce an allocation request`
> * `adwords_account_id`: Returned when the campaign owner is AdWords-integrated and the account isn't in the owner's AdWords integration. The message contains `must exist as an account in your AdWords integration`.
> * `media_type`: Returned when the campaign owner is AdWords-integrated, the request sends `Google Call Extension`, and there is no account. No account means none was sent and there is no default. The message contains `requires a Google Ads account be set`.
> * `media_type`: Returned when the campaign owner isn't AdWords-integrated and the request sends `Google Call Extension` or an `adwords_account_id`. The message contains `cannot be Google Call Extension unless you are integrated with AdWords`.
> * `adwords_account_id`: Returned when the campaign owner is AdWords-integrated and the request sends an account with a `media_type` other than `Google Call Extension`. An omitted `media_type` counts as not `Google Call Extension`. The message contains `can only be set when media type is 'Google Call Extension'`.
>
> #### HTTP status codes
>
> <table><thead><tr><th>Status</th><th>Meaning</th></tr></thead><tbody><tr><td>200</td><td>The location was ordered. The body is one object: `city`, `requested_count`, `allocated_count`, `allocation_request_ids`, and `area_code` when the request used an area code. `area_code` is the matched dial-code string. `allocated_count` can be lower than `requested_count`. Retrying the shortfall is not idempotent. See `allocated_count`.</td></tr><tr><td>401</td><td>The caller is not authenticated. This is the shared Network Integration API challenge (HTTP Basic), not the `errors` object used by 403, 404, and 422.</td></tr><tr><td>403</td><td>Checked after authentication and before the 422 affiliate and locale rejections. The campaign cannot add promo numbers. `errors.invalid_data` is one of:<ul><li>`Promo Numbers cannot be assigned to syndicated campaigns`</li><li>`This advertiser campaign, <name>, is paused and you can no longer add promo numbers`</li><li>`This advertiser campaign, <name>, is not live yet. Please go live with this campaign before requesting promo numbers.`</li><li>`This advertiser, <name>, is suspended and you can no longer add promo numbers`</li><li>`Promo numbers are not allowed for this advertiser`</li></ul></td></tr><tr><td>404</td><td>The advertiser or advertiser campaign in the URL was not found. The body is `{"errors":{"class":"RecordNotFound","invalid_data":"<message>"}}`.</td></tr><tr><td>422</td><td>One rejection from Rejection messages: affiliate ID, non-UK locale, location shape, count, unknown location, allocation failure, the network promo-number limit, or a Google Call Extension or AdWords account rejection.</td></tr></tbody></table>
>
> #### Examples
>
> Order local promo numbers by city
>
> 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`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "description": "UK tracking number",
>   "media_type": "Online: Display",
>   "city": "London",
>   "count": 5
> }
> ```
>
> Response Code: 200
>
> Response Body:
>
> ```json theme={null}
> {
>   "city": "London",
>   "requested_count": 5,
>   "allocated_count": 5,
>   "allocation_request_ids": [1001]
> }
> ```
>
> ***
>
> Order local promo numbers by area code
>
> 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`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "description": "UK tracking number",
>   "media_type": "Online: Display",
>   "area_code": 121,
>   "count": 2
> }
> ```
>
> Response Code: 200
>
> Response Body:
>
> ```json theme={null}
> {
>   "city": "Birmingham",
>   "area_code": "121",
>   "requested_count": 2,
>   "allocated_count": 2,
>   "allocation_request_ids": [1003]
> }
> ```
>
> ***
>
> Count over 100 (HTTP 422)
>
> A count over 100 is rejected before lookup or allocation. To order more than 100 numbers, send another request.
>
> 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`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "city": "London",
>   "count": 110
> }
> ```
>
> Response Code: 422
>
> Response Body:
>
> ```json theme={null}
> {
>   "errors": {
>     "count": ["Total requested count (110) exceeds maximum of 100"]
>   }
> }
> ```
>
> ***
>
> Unknown city (HTTP 422)
>
> 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`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "city": "XYZtown",
>   "count": 3
> }
> ```
>
> Response Code: 422
>
> Response Body:
>
> ```json theme={null}
> {
>   "errors": {
>     "city": ["City 'XYZtown' not found in UK area code database"]
>   }
> }
> ```
>
> ***
>
> Order with an AdWords account
>
> 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`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "description": "UK tracking number",
>   "media_type": "Google Call Extension",
>   "adwords_account_id": "627-345-9815",
>   "city": "London",
>   "count": 1
> }
> ```
>
> Response Code: 200
>
> Response Body:
>
> ```json theme={null}
> {
>   "city": "London",
>   "requested_count": 1,
>   "allocated_count": 1,
>   "allocation_request_ids": [1005]
> }
> ```
>
> ***
>
> AdWords account not in the integration (HTTP 422)
>
> 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`
>
> Format: application/json
>
> Request Body:
>
> ```json theme={null}
> {
>   "media_type": "Google Call Extension",
>   "adwords_account_id": "999",
>   "city": "London",
>   "count": 1
> }
> ```
>
> Response Code: 422
>
> Response Body:
>
> ```json theme={null}
> {
>   "errors": {
>     "adwords_account_id": ["Adwords account must exist as an account in your AdWords integration."]
>   }
> }
> ```


## Related topics

- [Deleting Promo Numbers](https://docs.invoca.com/s/article/deleting-promo-numbers.md)
- [Adding Local Promo Numbers](https://docs.invoca.com/s/article/adding-local-promo-numbers.md)
- [Promo Number Usage and Attribution Logs](https://docs.invoca.com/s/article/promo-number-usage-attribution-logs.md)
- [Reclaiming Your Unused Promo Numbers](https://docs.invoca.com/s/article/reclaiming-unused-promo-numbers.md)
- [Customize Call Treatment by Promo Number](https://docs.invoca.com/s/article/customize-call-treatment-promo-number.md)