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_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”)

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/2019-05-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/2019-05-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/2019-05-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/2019-05-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers_by_id/4531.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/2019-05-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/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/2019-05-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/2019-05-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/2019-05-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/2019-05-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/2019-05-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/2019-05-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers_by_id/4531.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/2019-05-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/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.

Examples

Delete an Advertiser Campaign Promo NumberEndpoint:

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

Format: application/jsonResponse Code: 200Response Body:

{
}

Delete an Affiliate Campaign Promo NumberEndpoint:

https://invoca.net/api/2019-05-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/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/2019-05-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/2019-05-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/2019-05-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/2019-05-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/2019-05-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/2019-05-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/2019-05-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/2019-05-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/2019-05-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/2019-05-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"
  }
}

Examples

Update an Advertiser Campaign Promo NumberEndpoint:

https://invoca.net/api/2019-05-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/2019-05-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.

Examples

Delete an Advertiser Campaign Promo NumberEndpoint:

https://invoca.net/api/2019-05-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/2019-05-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:

{
}

​Advertiser Campaign and Affiliate Campaign Promo Numbers

​Custom Data

​API Endpoints

​Examples

​Examples

​Examples

​Examples

​Examples

​Examples

​Examples

​Examples

​Examples

​Examples

Advertiser Campaign and Affiliate Campaign Promo Numbers

Custom Data

API Endpoints

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples

Examples