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. .. list-table:: :widths: 11 34 40 :header-rows: 1 :class: parameters * - 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_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". .. code-block:: json { "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/@@NETWORK_API_VERSION//advertisers//advertiser_campaigns//promo_numbers_by_id/.json`` .. api_endpoint:: :verb: GET :path: /promo_numbers_by_id :description: Get all Promo Numbers :page: get_promo_numbers_by_id .. api_endpoint:: :verb: GET :path: /promo_numbers_by_id/<promo_number_id> :description: Read a Promo Number :page: get_promo_number_by_id .. api_endpoint:: :verb: POST :path: /promo_numbers_by_id :description: Create an Advertiser/Affiliate Promo Number :page: post_promo_numbers_by_id .. api_endpoint:: :verb: PUT :path: /promo_numbers_by_id/<promo_number_id> :description: Update a Campaign Promo Number :page: put_promo_number_by_id_with_id .. api_endpoint:: :verb: DELETE :path: /promo_numbers_by_id/<promo_number_id> :description: Delete a Campaign Promo Number :page: delete_promo_number_by_id_with_id | 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/@@NETWORK_API_VERSION//advertisers//advertiser_campaigns//promo_numbers/.json`` .. api_endpoint:: :verb: GET :path: /promo_numbers :description: Get all Promo Numbers :page: get_promo_numbers .. api_endpoint:: :verb: GET :path: /promo_numbers/<promo_number> :description: Read a Promo Number :page: get_promo_number .. api_endpoint:: :verb: POST :path: /promo_numbers.json :description: Create an Advertiser/Affiliate Promo Number :page: post_promo_numbers .. api_endpoint:: :verb: PUT :path: /promo_numbers/<promo_number> :description: Update a Campaign Promo Number :page: put_promo_number .. api_endpoint:: :verb: DELETE :path: /promo_numbers/<promo_number> :description: Delete a Campaign Promo Number :page: delete_promo_number