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.

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: In­Call 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_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”

promo_number_looks_like string (optional) For international local promo number creation, a string phone number to try to match can be included. The first five digits will be used. (ex. “805”, “80561”)
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”)

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/2018-11-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 array

Endpoint:

https://invoca.net/api/2018-11-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:

[
  {
    "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/2018-11-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:

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

Endpoint:

https://invoca.net/api/2018-11-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers_by_id/4531.json

Format: application/json

Response Code: 200

Response 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 Number

Endpoint:

https://invoca.net/api/2018-11-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/4531.json

Format: application/json

Response Code: 200

Response 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 Number

Endpoint:

https://invoca.net/api/2018-11-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:

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

Response Code: 201

Response 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_prefix

Endpoint:

https://invoca.net/api/2018-11-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:

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

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

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

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

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

Response Code: 201

Response 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 Number

Endpoint:

https://invoca.net/api/2018-11-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:

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

Response Code: 201

Response 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 Number

Endpoint:

https://invoca.net/api/2018-11-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers_by_id/4531.json

Format: application/json

Request Body:

{
  "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/2018-11-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/4531.json

Format: application/json

Request Body:

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

Examples

Delete an Advertiser Campaign Promo Number

Endpoint:

https://invoca.net/api/2018-11-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers_by_id/4531.json

Format: application/json

Response Code: 200

Response Body:

{
}

Delete an Affiliate Campaign Promo Number

Endpoint:

https://invoca.net/api/2018-11-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/4531.json

Format: application/json

Response Code: 200

Response 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/2018-11-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 array

Endpoint:

https://invoca.net/api/2018-11-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:

[
  {
    "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/2018-11-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:

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

Endpoint:

https://invoca.net/api/2018-11-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:

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

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

Endpoint:

https://invoca.net/api/2018-11-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers.json

Format: application/json

Request Body:

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

Response Code: 201

Response 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_prefix

Endpoint:

https://invoca.net/api/2018-11-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers.json

Format: application/json

Request Body:

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

Response Code: 201

Response 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/state

Endpoint:

https://invoca.net/api/2018-11-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers.json

Format: application/json

Request Body:

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

Response Code: 201

Response 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 Number

Endpoint:

https://invoca.net/api/2018-11-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:

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

Response Code: 201

Response 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 Number

Endpoint:

https://invoca.net/api/2018-11-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers.json

Format: application/json

Request Body:

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

Response Code: 201

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

Examples

Update an Advertiser Campaign Promo Number

Endpoint:

https://invoca.net/api/2018-11-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:

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

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

Examples

Delete an Advertiser Campaign Promo Number

Endpoint:

https://invoca.net/api/2018-11-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:

{
}

Delete an Affiliate Campaign Promo Number

Endpoint:

https://invoca.net/api/2018-11-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:

{
}