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

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/2022-08-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

GET

/promo_numbers_by_id

Get all Promo Numbers

Examples

Read all Advertiser Campaign Promo Numbers as an array

Endpoint:

https://invoca.net/api/2022-08-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/2022-08-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"
    }
  }
]

GET

/promo_numbers_by_id/<promo_number_id>

Read a Promo Number

Examples

Read a specific Advertiser Campaign Promo Number

Endpoint:

https://invoca.net/api/2022-08-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:

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

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

POST

/promo_numbers_by_id

Create an Advertiser/Affiliate Promo Number

Examples

Create an Advertiser Campaign Promo Number

Endpoint:

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

PUT

/promo_numbers_by_id/<promo_number_id>

Update a Campaign Promo Number

Examples

Update an Advertiser Campaign Promo Number

Endpoint:

https://invoca.net/api/2022-08-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:

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

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

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

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

DELETE

/promo_numbers_by_id/<promo_number_id>

Delete a Campaign Promo Number

Examples

Delete an Advertiser Campaign Promo Number

Endpoint:

https://invoca.net/api/2022-08-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:

{
}

Delete an Affiliate Campaign Promo Number

Endpoint:

https://invoca.net/api/2022-08-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:

{
}

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/2022-08-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers/<promo_number>.json

GET

/promo_numbers

Get all Promo Numbers

Examples

Read all Advertiser Campaign Promo Numbers as an array

Endpoint:

https://invoca.net/api/2022-08-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/2022-08-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"
    }
  }
]

GET

/promo_numbers/<promo_number>

Read a Promo Number

Examples

Read a specific Advertiser Campaign Promo Number

Endpoint:

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

POST

/promo_numbers.json

Create an Advertiser/Affiliate Promo Number

Examples

Create an Advertiser Campaign Promo Number

Endpoint:

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

PUT

/promo_numbers/<promo_number>

Update a Campaign Promo Number

Examples

Update an Advertiser Campaign Promo Number

Endpoint:

https://invoca.net/api/2022-08-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/2022-08-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.

Moving an Advertiser Campaign Promo Number

Endpoint:

https://invoca.net/api/2022-08-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",
  "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/2022-08-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",
  "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.

DELETE

/promo_numbers/<promo_number>

Delete a Campaign Promo Number

Examples

Delete an Advertiser Campaign Promo Number

Endpoint:

https://invoca.net/api/2022-08-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/2022-08-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:

{
}