Promo Numbers - Invoca

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.

Property	Type	Value
id	integer (read-only)	The internal Invoca id of the promo number.
id_from_network	string	Network specific id of the promo number.
description	string (required)	Arbitrary description
media_type	string (required)	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: InCall Ad” “Offline: Magazine” “Offline: Outdoor” “Offline: Radio” “Offline: TV” “Offline: Other”
object_url	string (read-only)	URL for reaching the promo number in the UI.
local_center	hash	Requires one of the following City & State required together A 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
local_number_preferences	hash	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.
tn_prefix_whitelist	array of strings	an array of stringified limiters on the boundaries of where to look for local numbers given as npas (ex. [“805”, “212”])
promo_type	string (optional)	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”
adwords_account_id	string (optional)	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”)
destination_advertiser_id_from_network	string (optional)	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. Do not include this field if you do not intend to move the promo number.
destination_advertiser_campaign_id_from_network	string (optional)	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. Do not include this field if you do not intend to move the promo number.
destination_affiliate_id_from_network	string (optional)	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. Do not include this field if you do not intend to move the promo number.
hours_of_operation	hash (optional)	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 for full list. “schedules”: array of hashes (required when open_24_7 is false). Each schedule contains: “day_of_week”: string. Day of the week: “Sunday”, “Monday”, “Tuesday”, “Wednesday”, “Thursday”, “Friday”, or “Saturday”. “open_time”: string. Opening time in HH:MM format (15-minute increments, e.g., “09:00”). “close_time”: string. Closing time in HH:MM format (15-minute increments, e.g., “17:00”). Schedules cannot overlap. To remove hours of operation, pass null, empty string, empty array, or empty hash.

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

{
  "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

Examples

Read all Advertiser Campaign Promo Numbers as an arrayEndpoint:

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/jsonResponse Code: 200Response Body:

[
  {
    "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 arrayEndpoint:

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/jsonResponse Code: 200Response Body:

[
  {
    "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"
    }
  }
]

Examples

Read a specific Advertiser Campaign Promo NumberEndpoint:

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/jsonResponse Code: 200Response Body:

{
  "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 NumberEndpoint:

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/jsonResponse Code: 200Response Body:

{
  "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"
  }
}

Examples

Create an Advertiser Campaign Promo NumberEndpoint:

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/jsonRequest Body:

{
  "id_from_network": "1234",
  "description": "Halloween Promo Number 1",
  "media_type": "Online: Display"
}

Response Code: 201Response Body:

{
  "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_prefixEndpoint:

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/jsonRequest Body:

{
  "id_from_network": "1234",
  "description": "Halloween Promo Number 1",
  "media_type": "Online: Display",
  "local_center": {
    "tn_prefix": "805"
  },
  "tn_prefix_whitelist": ["805"]
}

Response Code: 201Response Body:

{
  "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/stateEndpoint:

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/jsonRequest Body:

{
  "id_from_network": "1234",
  "description": "Halloween Promo Number 1",
  "media_type": "Online: Display",
  "local_center": {
    "city": "Santa Barbara",
    "state": "CA"
  }
}

Response Code: 201Response Body:

{
  "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 NumberEndpoint:

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/jsonRequest Body:

{
  "id_from_network": "1234",
  "description": "Halloween Promo Number 1",
  "media_type": "Online: Display"
}

Response Code: 201Response Body:

{
  "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 NumberEndpoint:

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/jsonRequest Body:

{
  "id_from_network": "1234",
  "description": "Google Call Extension Demo",
  "media_type": "Google Call Extension",
  "adwords_account_id": "7567575756755"
}

Response Code: 201Response Body:

{
  "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"
  }
}

Examples

Update an Advertiser Campaign Promo NumberEndpoint:

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/jsonRequest Body:

{
  "description": "Halloween Promo Number 1 Updated",
  "media_type": "Online: Display"
}

Response Code: 200Response Body:Same as a GET response, includes all the promo number properties.

Update Affiliate Campaign Promo NumberEndpoint:

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/jsonRequest Body:

{
  "description": "Halloween Promo Number 1 Updated",
  "media_type": "Online: Display"
}

Response Code: 200Response Body:Same as a GET response, includes all the promo number properties.

Moving an Advertiser Campaign Promo NumberEndpoint:

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/jsonRequest Body:

{
  "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: 200Response Body:Same as a GET response, includes all the promo number properties.

Moving an Affiliate Campaign Promo NumberEndpoint:

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/jsonRequest Body:

{
  "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: 200Response Body:Same as a GET response, includes all the promo number properties.

Examples

Delete an Advertiser Campaign Promo NumberEndpoint:

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/jsonResponse Code: 200Response Body:

{
}

Delete an Affiliate Campaign Promo NumberEndpoint:

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/jsonResponse Code: 200Response Body:

{
}

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

Examples

Read all Advertiser Campaign Promo Numbers as an arrayEndpoint:

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/jsonResponse Code: 200Response Body:

[
  {
    "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 arrayEndpoint:

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/jsonResponse Code: 200Response Body:

[
  {
    "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"
    }
  }
]

Examples

Read a specific Advertiser Campaign Promo NumberEndpoint:

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/jsonResponse Code: 200Response Body:

{
  "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 NumberEndpoint:

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/jsonResponse Code: 200Response Body:

{
  "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"
  }
}

Examples

Create an Advertiser Campaign Promo NumberEndpoint:

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/jsonRequest Body:

{
  "description": "Halloween Promo Number 1",
  "media_type": "Online: Display"
}

Response Code: 201Response Body:

{
  "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_prefixEndpoint:

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/jsonRequest Body:

{
  "description": "Halloween Promo Number 1",
  "media_type": "Online: Display",
  "local_center": {
    "tn_prefix": "805"
  },
  "tn_prefix_whitelist": ["805"]
}

Response Code: 201Response Body:

{
  "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/stateEndpoint:

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/jsonRequest Body:

{
  "description": "Halloween Promo Number 1",
  "media_type": "Online: Display",
  "local_center": {
    "city": "Santa Barbara",
    "state": "CA"
  }
}

Response Code: 201Response Body:

{
  "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 NumberEndpoint:

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/jsonRequest Body:

{
  "description": "Halloween Promo Number 1",
  "media_type": "Online: Display"
}

Response Code: 201Response Body:

{
  "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 NumberEndpoint:

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/jsonRequest Body:

{
  "description": "Google Call Extension Demo",
  "media_type": "Google Call Extension",
  "adwords_account_id": "7567575756755"
}

Response Code: 201Response Body:

{
  "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 OperationEndpoint:

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/jsonRequest Body:

{
  "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: 201Response Body:

{
  "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"
      }
    ]
  }
}

Examples

Update an Advertiser Campaign Promo NumberEndpoint:

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/jsonRequest Body:

{
  "description": "Halloween Promo Number 1 Updated",
  "media_type": "Online: Display"
}

Response Code: 200Response Body:Same as a GET response, includes all the promo number properties.

Update Affiliate Campaign Promo NumberEndpoint:

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/jsonRequest Body:

{
  "description": "Halloween Promo Number 1 Updated",
  "media_type": "Online: Display"
}

Response Code: 200Response Body:Same as a GET response, includes all the promo number properties.

Moving an Advertiser Campaign Promo NumberEndpoint:

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/jsonRequest Body:

{
  "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: 200Response Body:Same as a GET response, includes all the promo number properties.

Moving an Affiliate Campaign Promo NumberEndpoint:

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/jsonRequest Body:

{
  "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: 200Response Body:Same as a GET response, includes all the promo number properties.

Examples

Delete an Advertiser Campaign Promo NumberEndpoint:

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/jsonResponse Code: 200Response Body:

{
}

Delete an Affiliate Campaign Promo NumberEndpoint:

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/jsonResponse Code: 200Response Body:

{
}

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

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). This call doesn’t return the phone number. The number appears on the campaign once carrier provisioning completes.Rejection messages lists validation failures, the affiliate and locale rejections, and the order in which those checks run.

Request parameters

Property	Type	Value
description	string (optional)	Description applied to the allocation request.
media_type	string (optional)	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`.
adwords_account_id	string (optional)	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”`.
city	string (conditional)	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.
area_code	integer or numeric string (conditional)	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.
count	integer or numeric string (required)	How many local numbers to order for this location. Accepted values and the over-100 rejection are under Rejection messages.

Response (HTTP 200)

Property	Type	Value
city	string	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.
area_code	string	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”`.
requested_count	integer	The `count` from the request, as an integer.
allocated_count	integer	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.
allocation_request_ids	array of integers	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.

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.

Authentication. An unauthenticated caller receives HTTP 401, the shared Network Integration API challenge, before any of the checks below.
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>"}}.
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.
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.
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.
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

Status	Meaning
200	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`.
401	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.
403	Checked after authentication and before the 422 affiliate and locale rejections. The campaign cannot add promo numbers. `errors.invalid_data` is one of: `Promo Numbers cannot be assigned to syndicated campaigns` `This advertiser campaign, <name>, is paused and you can no longer add promo numbers` `This advertiser campaign, <name>, is not live yet. Please go live with this campaign before requesting promo numbers.` `This advertiser, <name>, is suspended and you can no longer add promo numbers` `Promo numbers are not allowed for this advertiser`
404	The advertiser or advertiser campaign in the URL was not found. The body is `{“errors”:{“class”:“RecordNotFound”,“invalid_data”:“<message>“}}`.
422	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.

Examples

Order local promo numbers by cityEndpoint:

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/jsonRequest Body:

{
  "description": "UK tracking number",
  "media_type": "Online: Display",
  "city": "London",
  "count": 5
}

Response Code: 200Response Body:

{
  "city": "London",
  "requested_count": 5,
  "allocated_count": 5,
  "allocation_request_ids": [1001]
}

Order local promo numbers by area codeEndpoint:

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/jsonRequest Body:

{
  "description": "UK tracking number",
  "media_type": "Online: Display",
  "area_code": 121,
  "count": 2
}

Response Code: 200Response Body:

{
  "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/jsonRequest Body:

{
  "city": "London",
  "count": 110
}

Response Code: 422Response Body:

{
  "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/jsonRequest Body:

{
  "city": "XYZtown",
  "count": 3
}

Response Code: 422Response Body:

{
  "errors": {
    "city": ["City 'XYZtown' not found in UK area code database"]
  }
}

Order with an AdWords accountEndpoint:

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/jsonRequest Body:

{
  "description": "UK tracking number",
  "media_type": "Google Call Extension",
  "adwords_account_id": "627-345-9815",
  "city": "London",
  "count": 1
}

Response Code: 200Response Body:

{
  "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/jsonRequest Body:

{
  "media_type": "Google Call Extension",
  "adwords_account_id": "999",
  "city": "London",
  "count": 1
}

Response Code: 422Response Body:

{
  "errors": {
    "adwords_account_id": ["Adwords account must exist as an account in your AdWords integration."]
  }
}

​Advertiser Campaign and Affiliate Campaign Promo Numbers

​Custom Data

​API Endpoints

​Examples

​Examples

​Examples

​Examples

​Examples

​Examples

​Examples

​Examples

​Examples

​Examples

​UK local number orders

​Request parameters

​Response (HTTP 200)

​Rejection messages

​HTTP status codes

​Examples

Advertiser Campaign and Affiliate Campaign Promo Numbers

Custom Data

API Endpoints

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

UK local number orders

Request parameters

Response (HTTP 200)

Rejection messages

HTTP status codes

Examples