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

pause_date

string

date string (ex. ‘2015-01-01 15:59:00 -0700’).

expiration_date

string

date string. Read only. Alias of “pause_date”.

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

connect_timeout

Forwards the call to a selected phone number after optionally reading a prompt. If ringing_rollover is enabled for the network, a connect_timeout value can be configured along with a “Failover” child node.

Failover

*destination_phone_number

Forwards the call to a fallback destination number if the original destination configured on the parent node returns a busy signal OR if the configured connect_timeout value on the parent node is exceeded. Can only be configured as the child of another node, and not as a standalone node.

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

prompt

*dynamic_route_destination

asr_phrases

behave_like_ring_group

ring_group_connect_timeout

distribution_method

call_acceptance

ring_group_destination_total_limit

max_simultaneous_calls

Forwards the call to a destination that is extracted from a marketing 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. If behave_like_ring_group is enabled, then the marketing data field selected as the dynamic_route_destination may contain a comma-separated string of values, where each value represents a phone number that will be dialed as part of a RingGroup. RingGroup settings, such as ring_group_connect_timeout, distribution_method, call_acceptance, ring_group_destination_total_limit, and max_simultaneous_calls will also be made available.

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.

RingGroup

prompt

*ring_group_destinations

*ring_group_connect_timeout

distribution_method

call_acceptance

ring_group_destination_total_limit

max_simultaneous_calls

Forwards the call to a group of numbers defined in the ring_group_destinations array of hashes. The destinations will be in the order determined by the distribution_method. If a destination plays a busy signal OR the ring_group_connect_timeout value is exceeded before the call is answered, the next destination will be dialed. When call_acceptance is enabled, the call must be expressly accepted instead of answered. The ring_group_destination_total_limit may only be configured when the distribution_type is set to Random. This node type also allows for the configuration of max_simultaneous_calls when simultaneous calling is enabled for the network.

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 unless ringing_rollover is enabled for the network. The prompt will be read before connecting to the provided phone number. If ringing_rollover is enabled for the network, a connect_timeout value can be configured along with a “Failover” child node.

Failover

May not have any children. The provided phone number will be dialed if the destination configured on the parent node returns a busy signal when dialed OR if the connect_timeout value configured on the parent node is exceeded. Can only be configured as the child of another node, and not as a standalone node.

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

May have exactly 1 child node. We will evaluate the marketing 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. If the node is enabled to behave like a RingGroup, then the marketing data field selected as the dynamic_route_destination may contain a comma-separated string of values, where each value represents a phone number that will be dialed as part of a RingGroup.

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

RingGroup

Forwards the call to a group of numbers that will be dialed in the order determined by the distribution method. If a destination plays a busy signal OR the ring_group_connect_timeout value is exceeded before the call is answered (or accepted), the next destination will be dialed. This node type also allows for simultaneous calling when it is enabled.

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.

behave_like_ring_group

Boolean

When enabled, the given node will behave like a RingGroup node and additional settings may become available. See the “Node Parameters and Usage” and “Node Details” tables for more details.

call_acceptance

Boolean

When enabled, the agent / call recipient must press 1 on their keypad to accept the call or can press 2 to decline. If speech recognition is also enabled, the agent can also say ‘yes’ to accept or ‘no’ to decline the call. This is only available for RingGroup nodes or nodes that have the behave_like_ring_group setting enabled.

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

connect_timeout

Integer

The number of seconds we will wait before dialing the fallback number configured in the “Failover” node if the call is not answered or a busy signal is detected.

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

distribution_method

String

The method used to determine which order the numbers in a RingGroup are dialed. Default is “InOrder”. For RingGroup nodes, the available methods are “InOrder”, “Random” and “Weighted”. For nodes that have the behave_like_ring_group setting enabled, only methods “InOrder” and “Random” are available. When set to “Random”, all enabled numbers are equally likely to be near the top of the list. When set to “Weighted”, numbers with a higher distribution weight are more likely to be near the top of the list. (See the ring_group_destinations parameter details for how to configure “distriubiton_weight”).

dynamic_route_destination

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.

max_simultaneous_calls

Integer

The maximum amount of ring group numbers that we will attempt to dial at one time. Default is 1.

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.

ring_group_connect_timeout

Integer

The number of seconds we will wait before dialing the next number in a RingGroup if the call is not answered or a busy signal is detected. When call_acceptance is enabled, this will represent the amount of time we will wait for the call to be accepted instead of answered.

ring_group_destinations

Array of hashes

A list of destination hashes for the RingGroup node. Each hash must contain a “ring_group_number” parameter at minimum. Other optional parameters are “description” (string), “destination_disabled” (boolean, default: false), and “distribution_weight” (integer, default: 1). “destination_disabled” when set to true, will prohibit the destination from being dialed as part of the RingGroup. “distribution_weight” may only be used when the distribution_method of the RingGroup node is set to “Weighted”. For example, ring_group_destinations may have a value of [{“ring_group_number”: “800-444-1111”, “description”: “Call Center 1”, “distribution_weight”: 2 }, {“ring_group_number”: “800-444-2222”, “description”: “Call Center 2”, “distribution_weight”: 1 }].

ring_group_destination_total_limit

Integer

The total amount of phone numbers in the RingGroup that we will try dialing before giving up. For example, if you have configured 10 ring group numbers and the limit is set to 4, we will only dial the first 4 dynamically chosen numbers.

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