Advertiser Campaigns

Advertiser Campaigns can be managed using the Network API. In addition to create, update, and show operations, this interface provides additional endpoints including go_live, archive, and quick_stats.

Note that the <advertiser_id_from_network> and <advertiser_campaign_id_from_network> are the network’s id for those objects, not Invoca’s.

/api/2019-05-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>.json

We support passing back current_terms and future_terms on campaigns. The current properties of the campaign are reflected in current_terms. All changes to the campaign are staged in future_terms. Once the campaign goes live, future_terms transition over to current_terms.

You can set budgets on your campaign. There are three budget types, budget_cap_alert which is based on commissions, periodic_call_cap_alert, which is based on the number of calls in a given period, and concurrent_call_cap_alert, which is based on the number of simultaneous calls. These budget activities are only applicable for AffiliateEnabled campaigns (Known in the platform as a “Publisher Promotion” Campaign Type.)

You are not allowed to delete campaigns.

Property Type Value
id integer (read-only) The internal Invoca id for this Advertiser Campaign.
id_from_network string The network object_id for this Advertiser Campaign. Unique within network. Not required when auto-generation is enabled at network level.
name string Campaign name.
campaign_type string

3 Campaign Types Supported:

  • AffiliateEnabled: Advertiser Campaign that allows Affiliates to promote it. Includes Payin and Payouts for qualified Calls.
  • DirectOnly: Advertiser Campaign used for internal marketing. No ability to promote via Affiliates or setup Payin and Payouts for Calls.
  • ExternalOnly: Advertiser Campaign used for external calls uploaded via the Call Ingestion API. See Call Ingestion API for more details.
description string Campaign Description.
url string Click URL Template.
object_url string (read-only) URL for reaching the advertiser campaign in the UI.
timezone string Supported Time Zones: http://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html
campaign_language string Supported Campaign Languages: “English”, “French”, “Spanish”.
campaign_country string Supported Countries: “US”, “CA”, “UK”, “AU”, “CN”, “FI”, “FR”, “DE”, “HK”, “IT”, “JP”, “NL”, “SG”, “SE”, “CH”.
operating_24_7 boolean  
affiliate_payout    
policies    
currency string USD, GBP, EUR.
amount decimal Payout Amount.
condition string Condition options depend on the following Campaign Setup items being in place: Duration (seconds/minutes) and (greater than, greater than or equal to, less than, less than or equal to, equal to), Connect Duration (seconds/minutes) and (greater than, greater than or equal to, less than, less than or equal to, equal to), Repeat, In Region (specified across multiple Regions), During Hours, Key Press, Is Mobile, Is Landline, Send SMS All may be grouped with logic operators (AND/OR/NOT).
type string One of: Base, Bonus.
advertiser_payin    
policies    
currency string Supported Currencies: ‐ USD, GBP, EUR.
amount integer Advertiser Payin Amount.
condition string Condition options depend on the following Campaign Setup items being in place: Duration (seconds/minutes) and (greater than, greater than or equal to, less than, less than or equal to, equal to), Connect Duration (seconds/minutes) and (greater than, greater than or equal to, less than, less than or equal to, equal to), Repeat, In Region (specified across multiple Regions), During Hours, Key Press, Is Mobile, Is Landline, Send SMS. All may be grouped with logic operators (AND/OR/NOT).
type string One of: Base, Bonus.
hours    
[day of week]_open (e.g. friday_open) string Open Hours. In seconds past midnight (e.g. 0 for midnight, 32400 for 9:00 AM).
[day of week]_close (e.g. friday_close) string Closed Hours. In seconds past midnight (e.g. 0 for midnight, 75600 for 9:00 PM).
[day of week]_closed (e.g. sunday_closed) string true, false, or null. Whether the business is closed that day of the week.
named_regions    
name string Region Name.
regions    
region_type string Region Type. Can be one of: Zone, City, State, Country.
value string Region Value, e.g. “Sacramento, CA”, or just “CA”.
ivr_tree hash See following Advertiser Campaign IVR Section.
budget_activities   Only applicable for AffiliateEnabled campaigns.
budget_cap_alert    
reset_period string (required) Budget will reset based on this entry. One of: Daily, Weekly, Monthly, Quarterly, Ongoing.
starts_at date (required) Budget Start.
budget_currency string (required) Budget Currency.
time_zone string (required) Supported Time Zones: “Pacific Time (US & Canada)”, “Mountain Time (US & Canada)”, “Central Time (US & Canada)”, “Eastern Time (US & Canada)”, “London”, “UTC”.
budget_amount decimal (required) Budget Amount.
include_call_fees boolean True if you want call fees to be included in the budget.
periodic_call_cap_alert    
reset_period string (required) Budget will reset based on this entry. One of: Daily, Weekly, Monthly, Quarterly, Ongoing.
starts_at date (required) Call Cap Start.
budget_currency string (required) Budget Currency.
time_zone string (required) Supported Time Zones: “Pacific Time (US & Canada)”, “Mountain Time (US & Canada)”, “Central Time (US & Canada)”, “Eastern Time (US & Canada)”, “UTC”.
budget_amount decimal (required) Budget Amount.
auto_approve string One of: All, None, Approved_Affiliates Default: None This controls if affiliates are automatically approved when applying to the campaign.
visibility string One of: All, None, Approved_Affiliates Default: All This controls the level of visibility publishers have when applying to campaigns.
expiration_date string date string (ex. ‘2015‐01‐01’). Read only.
default_creative_id_from_network integer Default Creative ID.
concurrent_call_cap_alert    
budget_amount decimal (required) Budget Amount.
timeout integer Seconds to wait for the campaign to go live. Between 2 and 60.

Advertiser Campaign IVRs

When creating an advertiser campaign, you need to provide some call flow logic through an IVR tree. Depending on the advertiser/campaign type (direct, bundled, etc) you may use the following node types:

Node Parameters and Usage

* => required parameter

Node Type Parameters Usage
Menu

*prompt

asr_phrases

confirm_response_enabled

Allows the caller to select from up to 9 choices (e.g. choosing a department, selecting a language, etc).
Connect

prompt

*destination_phone_number

*destination_country_code

*destination_extension

asr_phrases

Forwards the call to a selected phone number after optionally reading a prompt.
EndCall

prompt

asr_phrases

Ends the call after optionally reading a prompt.
SmsPromo

*prompt

*sms_promo_copy

sms_promo_delay

sms_promo_sender

asr_phrases

Provide the option for a user to receive a text message with a special promotion.
Condition

*condition

asr_phrases

If/else option for a call based on the qualities of the call/caller.
VerifyLocation

prompt

asr_phrases

Prompts the caller to verify the guessed location or confirm through input. Useful if geographical data is important or useful in a condition node.
DynamicRoute (beta - read only)

*dynamic_route_destination

asr_phrases

Forwards the call to a destination that is extracted from a custom data field specified in dynamic_route_destination. The destination must be a phone number or if you are SIP integrated, can be a string that is routable by your SIP infrastructure.
AnyKeyPress

*prompt

asr_phrases

Prompts the caller to make any keypress to continue the call.
NumberQuestion

*prompt

*number_question_type

confirm_response_enabled

error_prompt_disabled

custom_error_prompt_text

caller_response_custom_data_partner_name

asr_phrases

Prompts the caller to respond with a multi-digit number (e.g. Phone Number, Date) and validates it if applicable. The caller’s response may be saved to a marketing data field.
YesOrNo

*prompt

confirm_response_enabled

error_prompt_disabled

custom_error_prompt_text

asr_phrases

Prompts the caller to respond with either a yes or no answer. The caller’s response determines how the call will continue.

Node Details

Node Type Details
Menu Can have 1‐9 child nodes, with each child corresponding to keypresses 1-9. At the end of the child list, it can also optionally have failover child nodes designated by a node with a keypress_failover_type parameter (see example below). If speech recognition is enabled, the caller may also respond verbally with their menu choice, including using the phrases that have been configured in field asr_phrases for each of the child nodes. (e.g. the caller can say “sales” or “one” for 1, and “support” or “two” for 2).
Connect May not have any children. The prompt will be read before connecting to the provided phone number.
EndCall May not have any children. The prompt will be read before ending the call.
SmsPromo May have exactly 1 child node. After accepting or declining the promotional sms, the child node will be executed. To accept the promotional sms, the user must push 9 on the phone (this should be added as part of the prompt). Only numbers recognized as mobile phones will be offered the sms option.
Condition May have exactly 2 child nodes. If the conditions are met, the first child node is executed. If they are not met then the second child node is executed. See the conditions section and examples below for details on valid conditions.
NearestBranch May have exactly 1 child node. The caller will be prompted to verify their location prior to forwarding the call. If no branch is within ‘radius_miles’ of the caller then the child node will be executed.
VerifyLocation May have exactly 1 child node. The prompt will play before verifying the callers location. The child node will be executed after verifying the callers location.
DynamicRoute (beta - read only) May have exactly 1 child node. We will evaluate the custom data field value specified on this node’s dynamic_route_destination. With non-SIP integration, if the extracted value is a valid phone number and the destination phone number is in an allowed region given your settings, we will play the prompt and transfer the call, otherwise the child node will be executed without the prompt. When SIP integrated, we also allow transferring to any string (such as an extension), in which case the destination should be routable by your SIP infrastructure.
AnyKeyPress May have exactly 2 child nodes. If any keypress is made, the first child node is executed. If no keypress is made, then the second child node is executed.
NumberQuestion May have exactly 1 child node. Requires a question type to be selected (e.g. Phone Number, Date). The prompt will play before the caller answers the question. The answer may be saved in a marketing data field. At the end of the child list, this node type can also optionally have failover child nodes, designated by a node with a keypress_failover_type parameter (see example below).
YesOrNo May have exactly 2 child nodes. If a keypress of 1 is made, the first child node is executed. If a kepyress of 2 is made, the second child node is executed. If speech recognition is enabled, the caller can also say “yes” for 1 and “no” for 2. At the end of the child list, this node type can also optionally have failover child nodes, designated by a node with a keypress_failover_type parameter (see example below).

Parameter Details

Property Type Value
asr_phrases Array of hashes A list of phrases that apply to the child of a Menu node. Can only be used when speech recognition is enabled. Allows the caller to respond verbally with one of the configured phrases instead of making a keypress. For example, the first child of a Menu node may have a value of [{“phrase”: “sales”}, {“phrase”: “support”}] for “asr_phrases”, where the caller may say “sales” or “support” to select the Menu option instead of pressing 1.
caller_response_custom_data_partner_name String The partner name of the custom data field that will be used to save the caller’s response to the NumberQuestion prompt.
condition String The boolean condition that decided if the first or second child will be executed in a condition node.
confirm_response_enabled Boolean When enabled, the system will read back the caller’s answer to the prompt and ask for confirmation. The caller can press 1 for “yes” and 2 for “no”. If speech recogition is enabled, callers can also confirm their response by saying “yes” or “no”.
custom_error_prompt_text String Custom text that will be played to the caller when they provide an invalid response or no response.
destination_country_code String The country code for the destination_phone_number.
destination_phone_number String The phone number to forward the caller to.
destination_extension String Extension keypresses on the destination number. Commas indicate pause (e.g. 1,,,234 means a keypress of “1” is executed followed by a 3 second pause and an extension keypress of “234”).
dynamic_route_destination (beta - read only) Strings The custom data field partner name you want to use as the destination in a dynamic route node. Typically a phone number in e164 format.
error_prompt_disabled Boolean If set to true, no error sound or prompt will play when the caller provides an invalid response or no response. If set to false, when the caller provides an invalid response or no response, an error sound will play, or you can optionally define a custom error prompt via the parameter custom_error_prompt_text.
keypress_failover_type String The failover type to use for a child node of a Menu. “Wrong” for when a wrong keypress is pressed by the caller on any attempt for the parent menu (shown in reporting as keypress “W”). “None” for when there is no keypress by the caller for all attempts for the parent menu (shown in reporting as keypress “N”). Omit this parameter for normal keypresses. See example below.
number_question_type String The type of question you want to ask as part of the NumberQuestion node type. This may be “Digits”, “Number”, “PhoneNumber”, “Date”, “Currency”, “Time”, or “ZipCode”.
prompt String The text that will be read before a nodes action occurs. An empty string will result in no prompt being read, and the following action will occur immediately.
sms_promo_copy String The text that will be sent to the caller if they accept the promotional sms.
sms_promo_delay Integer The time delay in seconds before sending the promotional sms. This may be 1 (Immediately), 1800 (30 minutes), 86400 (1 day), 604800 (7 days), or 2592000 (30 days).
sms_promo_sender String The email address that will be shown in the sms. This defaults to sms@invoca.net.

Conditions

Condition Details
during_hours True if the caller is calling during the hours specified in the campaign.
in_region True if the caller is calling from the region specified in the campaign.
landline True if the caller is calling from a landline phone.
mobile True if the caller is calling from a mobile phone.
pressed[key] True if the caller pressed the named key.
repeat True if the caller has already called this campaign in the last N days (the interval N can be set on the campaign; the default is 30 days).
sms_sent The caller chose to receive a text message during the call.
and Joins two conditions and is true if both conditions are true.
or Joins two conditions and is true if either condition is true.
not Inverts the following condition.
( ) Used for grouping.

Example Conditions

Example Condition
Call duration was a minute and a half or longer duration >= 1 min 30 sec.
Call came in during business hours during_hours.
Call was from a mobile phone where the caller pressed the 2 key in response to the first menu mobile and pressed[2].
Call was from the selected geographic region or was longer than 12 seconds in_region or duration > 12 sec.
Caller pressed 1 to the first question in a series and was not in the geographic region or calling during business hours pressed[a 1] and not (in_region or during_hours).

Note that and is higher precedence than or. So if you use both in a condition like this:

mobile or in_region and during_hours

it is equivalent to this:

mobile or (in_region and during_hours)

Caller ID options can also be configured by optionally including a caller_id object inside ivr_tree:

Setting Mask Example Details
“original” None { setting: “original” } Display caller’s caller id to call center agent. (Default)
“promo” None { setting: “promo” } Display affiliate promo number to call center agent. (Only if forwarding to a local number.)
“specific” String containing phone number { setting: “specific”, mask: “800-555-5555” } Display a specific caller ID number.
“partial” String containing mask format { setting: “partial”, mask: “800-555-XXXX” } Display caller’s caller ID with digits replaced.

Custom Data

Advertiser campaigns may have Custom Data Fields applied to them, which will be applied to calls originating through the advertiser campaign. To apply Custom Data Values to an advertiser campaign, 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"
  }
}

Endpoint:

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

Examples

Read all campaigns for Advertiser 2 id from network

Endpoint:

https://invoca.net/api/2019-05-01/<network_id>/advertisers/2/advertiser_campaigns.json

Response Body:

An array of campaigns are returned.

Examples

Read Campaign 100 for Advertiser 2

Endpoint:

https://invoca.net/api/2019-05-01/<network_id>/advertisers/2/advertiser_campaigns/100.json

Response Body:

{
    "id": 11,
    "id_from_network": "100",
    "name": "PostSeason Promotion 11 fJauFbSEGHKw8ADEGv",
    "status": "Entry",
    "object_url": "https://invoca.net/a_campaigns/terms/11",
    "current_terms": {
      "description": "August promotion to sell post-season tickets at half price.",
      "timezone": "Pacific Time (US & Canada)",
      "visibility": "All",
      "created_at": "2015-05-13 07:45:08 -0800",
      "id": "215",
      "operating_24_7": false,
      "go_live_date": null,
      "default_creative_id_from_network": "222",
      "campaign_language": "English",
      "campaign_country": "US",
      "advertiser_payin": {
        "min": 7,
        "currency": "EUR",
        "pricing": "€7.00 per call if duration > 2 min 30 sec",
        "max": 7,
        "policies": [
          {
            "type": "Base",
            "currency": "EUR",
            "condition": "duration > 2 min 30 sec",
            "amount": 7
          }
        ],
        "range": "€7.00 per call"
      },
      "pricing_type": "Fixed",
      "ivr_tree": {
        "root": {
          "condition": "during_hours",
          "children": [
            {
              "destination_phone_number": "8004377950",
              "destination_country_code": "1",
              "prompt": "",
              "node_type": "Connect"
            },
            {
              "destination_phone_number": "8004377950",
              "destination_country_code": "1",
              "prompt": "",
              "node_type": "Connect"
            }
          ],
          "node_type": "Condition"
        },
        "record_calls": true
      },
      "auto_approve": "None",
      "expiration_date": null,
      "campaign_type": "AffiliateEnabled",
      "affiliate_payout": {
        "min": 4.5,
        "currency": "USD",
        "pricing": "Base: $4.50 per call Bonus: $2.75 per call if duration > 60",
        "max": 7.25,
        "policies": [
          {
            "type": "Base",
            "currency": "USD",
            "condition": "",
            "amount": 4.5
          },
          {
            "type": "Bonus",
            "currency": "USD",
            "condition": "duration > 60",
            "amount": 2.75
          }
        ],
        "range": "$4.50 - $7.25 per call"
      },
      "updated_at": "2015-05-13 07:45:08 -0800",
      "url": "http://www.nfltix.com/postseasonnow",
      "hours": {
        "saturday_open": 32400,
        "sunday_open": 32400,
        "monday_closed": false,
        "tuesday_open": 32400,
        "thursday_open": 32400,
        "friday_close": 75600,
        "sunday_close": 50999,
        "wednesday_closed": false,
        "thursday_closed": false,
        "tuesday_close": 75600,
        "friday_open": 32400,
        "saturday_closed": true,
        "sunday_closed": true,
        "tuesday_closed": true,
        "wednesday_close": 75600,
        "friday_closed": true,
        "monday_open": 32400,
        "saturday_close": 75600,
        "monday_close": 75600,
        "thursday_close": 75600,
        "wednesday_open": 32400
      },
      "named_regions": [
        {
          "regions": [
            {
              "region_type": "State",
              "value": "CA",
              "text": "TBD"
            },
            {
              "region_type": "State",
              "value": "OR",
              "text": "TBD"
            },
            {
              "region_type": "State",
              "value": "WA",
              "text": "TBD"
            }
          ],
          "name": "West Coast"
        },
        {
          "regions": [
            {
              "region_type": "State",
              "value": "NY",
              "text": "TBD"
            },
            {
              "region_type": "State",
              "value": "NJ",
              "text": "TBD"
            }
          ],
          "name": "East Coast"
        }
      ]
    },
    "future_terms": {
      "description": "August promotion to sell post-season tickets at half price.",
      "timezone": "Pacific Time (US & Canada)",
      "visibility": "All",
      "created_at": "2015-05-13 08:46:43 -0800",
      "id": "",
      "operating_24_7": false,
      "go_live_date": null,
      "default_creative_id_from_network": "123",
      "campaign_language": "English",
      "campaign_country": "US",
      "advertiser_payin": {
        "min": 7,
        "currency": "EUR",
        "pricing": "€7.00 per call if duration > 2 min 30 sec",
        "max": 7,
        "policies": [
          {
            "type": "Base",
            "currency": "EUR",
            "condition": "duration > 2 min 30 sec",
            "amount": 7
          }
        ],
        "range": "€7.00 per call"
      },
      "budget_activities": {
        "periodic_call_cap_alert": {
          "budget_amount": 200.0,
          "budget_currency": "USD",
          "reset_period": "Ongoing",
          "start_at": "2014-04-17T00:00:00-07:00",
          "total_amount": 0.0,
          "time_zone": "Pacific Time (US & Canada)"
        },
        "concurrent_call_cap_alert": {
          "budget_amount": 50.0,
          "budget_currency": "USD",
          "reset_period": "Ongoing",
          "start_at": "2014-04-17T00:00:00-07:00",
          "time_zone": "Pacific Time (US & Canada)"
        },
        "budget_cap_alert": {
          "budget_amount": 100.0,
          "budget_currency": "USD",
          "reset_period": "Monthly",
          "start_at": "2014-04-01T00:00:00-07:00",
          "total_amount": 0.0,
          "time_zone": "Pacific Time (US & Canada)"
        },
        "pricing_type": "Fixed",
        "ivr_tree": {
          "root": {
            "condition": "during_hours",
            "children": [
              {
                "destination_phone_number": "8004377950",
                "destination_country_code": "1",
                "prompt": "",
                "node_type": "Connect"
              },
              {
                "destination_phone_number": "8004377950",
                "destination_country_code": "1",
                "prompt": "",
                "node_type": "Connect"
              }
            ],
            "node_type": "Condition"
          },
          "record_calls": true
        },
        "auto_approve": "None",
        "expiration_date": "2015-05-18T23:59:59-08:00",
        "campaign_type": "AffiliateEnabled",
        "affiliate_payout": {
          "min": 4.5,
          "currency": "USD",
          "pricing": "Base: $4.50 per call Bonus: $2.75 per call if duration > 60",
          "max": 7.25,
          "policies": [
            {
              "type": "Base",
              "currency": "USD",
              "condition": "",
              "amount": 4.5
            },
            {
              "type": "Bonus",
              "currency": "USD",
              "condition": "duration > 60",
              "amount": 2.75
            }
          ],
          "range": "$4.50 - $7.25 per call"
        },
        "updated_at": "2015-05-13 08:46:43 -0800",
        "url": "http://www.nfltix.com/postseasonnow",
        "hours": {
          "saturday_open": 32400,
          "sunday_open": 32400,
          "monday_closed": false,
          "tuesday_open": 32400,
          "thursday_open": 32400,
          "friday_close": 75600,
          "sunday_close": 50999,
          "wednesday_closed": false,
          "thursday_closed": false,
          "tuesday_close": 75600,
          "friday_open": 32400,
          "saturday_closed": true,
          "sunday_closed": true,
          "tuesday_closed": true,
          "wednesday_close": 75600,
          "friday_closed": true,
          "monday_open": 32400,
          "saturday_close": 75600,
          "monday_close": 75600,
          "thursday_close": 75600,
          "wednesday_open": 32400
        },
        "named_regions": [
          {
            "regions": [
              {
                "region_type": "State",
                "value": "CA",
                "text": "TBD"
              },
              {
                "region_type": "State",
                "value": "OR",
                "text": "TBD"
              },
              {
                "region_type": "State",
                "value": "WA",
                "text": "TBD"
              }
            ],
            "name": "West Coast"
          },
          {
            "regions": [
              {
                "region_type": "State",
                "value": "NY",
                "text": "TBD"
              },
              {
                "region_type": "State",
                "value": "NJ",
                "text": "TBD"
              }
            ],
            "name": "East Coast"
          }
        ]
      }
    },
    "custom_data": {
      "channel": "Online lead"
    }
  }

Examples

Create Campaign fJauFbSEGHKw8ADEGv for Advertiser cFUyYnFHyiYA42TrpM

Endpoint:

https://invoca.net/api/2019-05-01/<network_id>/advertisers/cFUyYnFHyiYA42TrpM/advertiser_campaigns.json

Request Body:

{
  "id_from_network": "fJauFbSEGHKw8ADEGv",
  "name": "PostSeason Promotion 11 fJauFbSEGHKw8ADEGv",
  "description": "August promotion to sell post-season tickets at half price.",
  "url": "http://www.nfltix.com/postseasonnow",
  "timezone": "Pacific Time (US & Canada)",
  "operating_24_7": false,
  "campaign_type": "AffiliateEnabled",
  "campaign_country": "US",
  "default_creative_id_from_network": "111",
  "hours": {
    "friday_open": 32400,
    "wednesday_open": 32400,
    "sunday_close": 50999,
    "monday_open": 32400,
    "friday_close": 75600,
    "wednesday_close": 75600,
    "friday_closed": true,
    "thursday_open": 32400,
    "sunday_closed": true,
    "sunday_open": 32400,
    "saturday_open": 32400,
    "monday_closed": false,
    "thursday_close": 75600,
    "tuesday_closed": true,
    "tuesday_close": 75600,
    "tuesday_open": 32400,
    "saturday_closed": true,
    "saturday_close": 75600,
    "monday_close": 75600,
    "thursday_closed": false,
    "wednesday_closed": false
  },
  "named_regions": [
    {
      "name": "West Coast",
      "regions": [
        {
          "region_type": "State",
          "value": "CA"
        },
        {
          "region_type": "State",
          "value": "OR"
        },
        {
          "region_type": "State",
          "value": "WA"
        }
      ]
    },
    {
      "name": "East Coast",
      "regions": [
        {
          "region_type": "State",
          "value": "NY"
        },
        {
          "region_type": "State",
          "value": "NJ"
        }
      ]
    }
  ],
  "advertiser_payin": {
    "policies": [
      {
        "condition": "duration > 2 min 30 sec",
        "type": "Base",
        "currency": "USD",
        "amount": 7.0
      }
    ]
  },
  "affiliate_payout": {
    "policies": [
      {
        "condition": "",
        "amount": 4.5,
        "currency": "USD",
        "type": "Base"
      },
      {
        "condition": "duration > 60",
        "amount": 2.75,
        "currency": "USD",
        "type": "Bonus"
      }
    ]
  },
  "ivr_tree": {
    "record_calls": true,
    "root": {
      "node_type": "Condition",
      "condition": "during_hours",
      "children": [
        {
          "node_type": "Connect",
          "destination_phone_number": "8004377950",
          "destination_country_code": "1",
          "prompt": ""
        },
        {
          "node_type": "Connect",
          "destination_phone_number": "8004377950",
          "destination_country_code": "1",
          "prompt": ""
        }
      ]
    }
  },
  "custom_data": {
    "channel": "Offline leads"
  }
}

Response Body:

Same as a GET response, includes all the advertiser campaign properties.

Examples

Example IVR Tree updates:

  1. Verify the callers location, then if on the West Coast (setup previously) forward to a call center, otherwise hang up after playing a prompt.
curl­ -XPUT -H "Content­Type: application/json" -­u 'login:pass'
'https://vanity.invoca.net/api/2019-05-01/advertisers/:advertiser_id/advertiser_campaigns/445566.json' \
-d '
{"ivr_tree":
 {"root":
   {"node_type":"VerifyLocation",
    "children":
     [{"node_type":"Condition",
       "condition":"in_region[West Coast]",
       "children":
         [{"children":[],
           "condition":"",
           "node_type":"Connect",
           "destination_phone_number":"8004377950",
           "destination_country_code":"1"},
           {"node_type":"EndCall",
            "prompt":"We are sorry, we currently cannot service your area. Goodbye."}]}]
   },
   "record_calls":true}}'  -v
  1. Present the options for multiple departments, if sales is selected check if office is open. If the office is open, forward the call, if not play a prompt and then hangup.
curl -XPUT -H "Content­Type: application/json" -u 'login:pass'
'https://vanity.invoca.net/api/2019-05-01/advertisers/:advertiser_id/advertiser_campaigns/445566.json' \
-d '
{"ivr_tree":{
   "record_calls":true,
   "root":{
     "node_type":"Menu",
     "prompt":"Please press 1 for sales or 2 for 24 hour support",
     "children":[
       { "node_type":"Condition",
         "condition":"during_hours",
         "children":[
           { "node_type":"Connect",
             "destination_phone_number":"8004377950",
             "destination_country_code":"1",
             "prompt":"Thank you, transferring you now"
           },
           { "node_type":"EndCall",
             "prompt":"We are currently closed. Please call back during business hours. Goodbye"
           }]},
       { "node_type":"Connect",
         "destination_phone_number":"8004377950",
         "destination_country_code":"1",
         "prompt":"Thank you, transferring you now"
       }]}}}'  -v
  1. Offer an sms to see current offers and then connect to a call center.
curl­ -XPUT -H "Content­Type: application/json"­ -u 'login:pass'
'https://vanity.invoca.net/api/2019-05-01/advertisers/:advertiser_id/advertiser_campaigns/445566.json' \
-d '
{"ivr_tree":
 {"root":
   {"node_type":"SmsPromo",
    "sms_promo_copy":"Visit us at www.invoca.com to see new promotions.",
    "sms_promo_delay":1,
    "prompt":"If you would like to see information about our current offers, please press 9 now.",
    "children":
     [{"children":[],
       "condition":"",
       "node_type":"Connect",
       "destination_phone_number":"8004377950",
       "destination_country_code":"1"}]
   },
   "record_calls":true}}' -v

Each of the above requests will have a response body similar to a GET request, including all the advertiser campaign properties.

Examples

Read Campaign 100 for Advertiser 2

Endpoint:

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

Response Body:

{
  "stats": {
    "last_30days": {
      "call_avg_total_duration": 0.0,
      "call_count": 0
    },
    "last_7days": {
      "call_avg_total_duration": 0.0,
      "call_count": 0
    },
    "today": {
      "call_avg_total_duration": 0.0,
      "call_count": 0
    }
  }
}

Examples

Advertiser campaigns can have their state controlled through this API. When a campaign is created through the API, its “future terms” are being set, and its state is not yet live. When the go_live endpoint is hit, the “future terms” are promoted to “current terms” and the campaign becomes live. Archived campaigns must be unarchived before calling this endpoint to make them live.

Use this request url format:

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

curl­ -XPOST­ -H "Content­Type: application/json"­ -u 'login:pass'
'https://vanity.invoca.net/api/2019-05-01/123/advertisers/advertiser_id/advertiser_campaigns/445566/go_live.json' \
-d '
{
  "timeout": 10
}
' -v

Examples

If a campaign has previously been set to live, either through the API or through the UI, it can be archived, which effectively shuts it down. An archived campaign can be returned to live at a later time. To archive a campaign use this the following endpoint URL:

Endpoint:

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

Response Body:

{}

Examples

Archived campaigns should be unarchived using this endpoint. It changes campaign status to paused. After that you can activate the campaign using a go_live request.

Endpoint:

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

Response Body:

{}

Keypress Failover Type

Example IVR Tree utilizing keypress_failover_type

"ivr_tree": {
  "root": {
    "node_type":"Menu",
    "prompt":"Press 1 for sales, press 2 for support.",
    "children": [
      {
        "node_type": "Connect",
        "destination_phone_number": "8004377950",
        "destination_country_code": "1",
        "prompt": "Directing you to sales"
      },
      {
        "node_type": "Connect",
        "destination_phone_number": "8004377951",
        "destination_country_code": "1",
        "prompt": "Directing you to support"
      },
      {
        "node_type": "Connect",
        "destination_phone_number": "8004377952",
        "destination_country_code": "1",
        "prompt":"Forwarding you to an operator.",
        "keypress_failover_type":"Wrong"
      },
      {
        "node_type":"EndCall",
        "prompt":"No key was selected, goodbye.",
        "keypress_failover_type":"None"
      }
    ]
  }
}

Error Handling

Forbidden – 403:

PUT/POST

https://invoca.net/api/2019-05-01/<network_id>/advertiser/<advertiser_id_from_network>/advertiser_campaign/<advertiser_campaign_id_from_network>/advertiser_campaigns/<advertiser_campaign_id>.json

Content Type: application/json

Response Code: 403

Request Body

{
  "node_type":"Menu",
  "prompt":"Prompt text",
  "prompt_id_from_network":"",
  "prompt_url":null,
  "prompt_recieved":null,
  "children": [
    {
      "node_type":"Menu",
      "prompt":"",
      "prompt_id_from_network":"",
      "prompt_url":null,
      "prompt_recieved":null,
      "children": [
        {
          "node_type":"EndCall",
          "prompt":"",
          "prompt_id_from_network":"",
          "prompt_url":null,
          "prompt_recieved":null
        }
      ]
    }
  ]
}

Response Body

{
  "error": {
    "ivr_tree": {
      "children": [
        {
          "0": {
            "prompt": [
              "cannot be empty"
            ]
          }
        }
      ]
    }
  }
}

The number in error message represents the index of the child node in the tree, or in other words, it is the keypress of the node containing the error minus one.