Basics

The following API articles provide an understanding for high level API methodology across the different Invoca APIs.

Design Principles

REST

All interfaces use REST. This makes them easy to predict as they use HTTP and its existing verbs to Create, Read, Update, and Delete objects. Any language that supports HTTP can access these interfaces. Create and Update are idempotent operations.

Action HTTP Verb Notes
Create POST Object is created. If it already exists, it is updated.
Read GET Object is read.
Update PUT Object is created. If it already exists, it is updated.
Delete DELETE Object is deleted. If the object has already been deleted, does nothing.

Status Codes

HTTP Status codes are used to indicate success or failure. The set of status codes returned by the Network Integration API are:

Status Code Meaning
200, 201 Success
401 Failure. Access is not authorized.
403 Failure. Request arguments are invalid.
404 Failure. The resource was not found.
500 Failure. Internal Service Error.

* See the section on Error Handling for greater detail on response bodies for failure codes.

Security

HTTPS is required for all API requests.

Authentication is performed using one of several approaches.

The preferred approach is to use Invoca API tokens, which are created and managed on the Manage API Credentials page of the platform.

Some API endpoints will accept HTTP(S) Basic Authentication, which authenticates using a username and password in the request header.

Additionally, session login authentication is sufficient as an alternative. This is so that you can test an API URL simply by logging in to the platform first as a Network Role of ‘Super’ (full access user) and then pasting the URL into the browser.

Using OAuth token to Access Invoca APIs

Requests are authenticated using HTTPS basic authentication with an Invoca API Token, which can be created and managed on the Manage API Credentials page in the platform.

Step by step guide using API token to access APIs

  1. Obtain OAuth 2.0 credentials from the Manage API Credentials.

    Visit your API Credentials page to obtain OAuth 2.0 credentials for your Network Integration API.

  2. Send the access token to an API.

After you obtain a token, include it in the HTTP header of your request, as a URL string parameter, or as a key/value pair in the JSON body.

Example using API token as URL parameter:

https://<vanity>.invoca.net/api/2015-12-09/advertisers.json?oauth_token=YbcFHZ38FNfptfZMB0RZ6dk9dOJCaCfU

Example using Curl to make an API call with token-based authentication:

curl -X POST -H "Accept: application/json" -H "Content-Type: application/json" 'https://\<vanity\>.invoca.net/api/2015-12-09/advertisers/1111.json' -d '{"oauth_token":"YbcFHZ38FNfptfZMB0RZ6dk9dOJCaCfU"}'

Guidelines * Users should generate their own API tokens. Tokens should be treated like passwords and not be emailed or transmitted over other insecure mediums, nor should they be stored in a source code repository. * As a network user, you should not generate a token on behalf of Advertisers or Publishers because tokens inherit the privileges of the user generating it. * Invoca does not use OAuth refresh tokens.

Idempotency

Most interfaces are designed to be idempotent, meaning that it is harmless to call them more than once with the same parameters. Subsequent calls to an interface have no side effects, and return the same result.

Self‐Correction

Most updates expect a complete copy of the object, making Update and Create interchangeable. This means that errors tend to be corrected over time. Campaign Terms are an exception to this due to their complexity (see Advertiser Campaigns for more).

Versioning

The API version is given as a date in the path.

Dedicated Subdomain

All APIs are accessed through the dedicated subdomain of invoca.net that is used for the network. For example, a network named “LeadTrust” might be assigned leadtrust.invoca.net. We recommend that, when making your API calls, you place your <network_id> after the API version in the url.

Request Parameter Format & Response Body Format

Previous versions of the API accepted form‐encoded style parameters in the request and used XML as the output format. As of 2015-12-09, all new feature development has switched to JSON format for both request and response. Previous XML functionality will continue to be supported via the 2013‐03‐22 version of the API (please contact questions@invoca.com for more information on previous versions).

Error Handling

Common RingPool errors:

Not found – 404:

https://invoca.net/api/2014­-01-­01/<network_id>/advertisers/1/advertiser_campaigns/100/ring_pools/123.json

{
  "errors": {
    "invalid_data": "Could not find RingPool 123 for advertiser campaign 100 and advertiser 1",
    "class": "RecordNotFound"
  }
}

Validation failed – 403 – Body contains a json with validation errors for each field:

{
  "errors": {
    "pool_type": [
      "can't be blank"
    ],
    "destination_type": [
      "can't be blank"
    ],
    "name": [
      "can't be blank"
    ]
  }
}

Service error – 500 – Body contains a json Error with a unique handle (to use as a cross‐reference with Invoca):

{
  "errors": {
    "invalid_data": "refer to error handle 1228118400",
    "class": "InternalServiceError"
  }
}

PPC Platform Authentication Access Tokens

The PPC Platform provides an interface to get a one‐time use access token authenticating a Network, Advertiser, or Affiliate user. The access token must then be appended to a PPC Platform destination URL.

The network authenticates an organization by doing the following:

  1. Authenticates the user on the network Platform.
  2. Makes a server‐to‐server request for a one‐time use access token.
  3. Appends the returned access token to the PPC Platform destination URL access_token=<ProvidedAccessToken>
  4. Redirects to the PPC Platform destination URL.

The format of the API URL is in (2):

https://invoca.net/api/2014-­01-­01/<network_id>/network/<email>/create_access_token.json

https://invoca.net/api/2014­-01-­01/<network_id>/advertisers/<advertiser_id_from_network>/<email>/create_access_token.json

https://invoca.net/api/2014­-01-­01/<network_id>/affiliates/<affiliate_id_from_network>/<email>/create_access_token.json

The success response is an JSON document with a root element of Response that contains a single AccessToken element whose content is the access token:

Response JSON Element Value
AccessToken The access token

Example URLs

Create access token for “sy@young.com” network user:

POST

https://invoca.net/api/2014­-01-­01/<network_id>/network/sy%40young.com/create_access_token.json HTTP/1.1

Response:

{
  "token": "bpD8HmLcCxzSiOX01v­4XbZr4_s",
  "id": 1
}

Create access token for “sy@young.com” user in advertiser id 354:

POST

https://invoca.net/api/2014­-01-­01/<network_id>/advertisers/354/sy%40young.com/create_access_token.json HTTP/1.1

Response:

{
  "token": "bpD8HmLcCxzSiOX01v­4XbZr4_s",
  "id": 1
}

Create access token for “sy@young.com” user in affiliate id 976:

POST

https://invoca.net/api/2014­-01-­01/<network_id>/affiliates/976/sy%40young.com/create_access_token.json HTTP/1.1

Response:

{
  "token": "bpD8HmLcCxzSiOX01v­4XbZr4_s",
  "id": 1
}

On-The-Fly Authentication

The PPC Platform supports “On-The-Fly Authentication”: if a user types in a URL, or clicks on a link in an email, or chooses a bookmarked link and they are not currently logged in (“authenticated”), they must first log in and then are redirected to their original destination URL.

When using the API, all authentication is by the network on behalf of the replicated users. So in this case the PPC Platform redirects to a network authentication URL such as http://www.network.com/loginwith with the following query parameters:

Query Parameter Description
destination The ultimate PPC Platform destination URL to redirect to once authentication has been established.
type Either advertiseror affiliate, or empty if unknown.

For example:

http://www.network.com/login?destination=http%3A%2F%2Finvoca.net%2Faffiliates%2F1&type=advertiser

The network authenticates the user either by using existing session credentials or by prompting for login credentials. It generates an access token using a server‐to‐server POST:

POST

https://invoca.net/api/2014­-01-­01/<network_id>/advertisers/354/sy%40young.com/create_access_token.json

The returned value is an access token, for example 9AC23B903F4. The network then appends this token to the destination URL and redirects there:

http://invoca.net/affiliates/1?access_token=9AC23B903F4

CURL examples:

Here are some basic examples on how to use the API using CURL.

Create

curl -v ­XPOST -H “Content­Type: application/json” -u ‘<username>:<password>’ ‘https://www.invoca.net/api/2014­-01-­01/<network_id>/<url>’ -d ‘<valid JSON>’

Read

curl -v -u ‘<username>:<password> ‘https://www.invoca.net/api/2014­-01­-01/<network_id>/<url>’

Update

curl­ -v -XPUT -H “Content­Type: application/json” -u ‘<username>:<password> ‘https://www.invoca.net/api/2014­-01-­01/<network_id>/<url>’ -d ‘<valid JSON>’

Delete

curl -v -XDELETE -H “Content­Type: application/json” -u ‘<username>:<password> ‘https://www.invoca.net/api/2014­-01­-01/<network_id>/<url>’ -d ‘<valid JSON>’

API Documentation

The platform provides the following APIs:

Transactions API - provides read-only access to call transaction data.

Network Integration - supports the replication and synchronization of advertiser, publisher and campaign data between partner platforms.

Conversion Reporting - provides the ability to report completed order information (or other conversion events) from a server back into the platform.

Ringpool - allocates a dynamic, trackable promo phone number from a RingPool.

Bulk Ringpool API - allocates a dynamic, trackable promo phone number from a RingPool (designed to handle a high volume of requests per second).

Signal API - used to report signals that occur on a specific call (transaction).

The Transactions API and Network Integration API are accessible using the API credentials generated on the platform. See Manage API Credentials for more information.

The Conversion Reporting API is accessible using credentials provided by Invoca. Contact questions@invoca.com to request Conversion Reporting API credentials.

The RingPool and Bulk RingPool APIs are accessible using the API keys provided in the RingPool wizard. (Note: the Bulk RingPool API is only available after being enabled by Customer Success. Contact questions@invoca.com to request the Bulk RingPool API.)

The RingPool wizard includes a section showing the correct API URL for your organization:

RP_API.png

Manage API Credentials

Invoca’s self-serve API token access is OAuth-compliant. Accessing APIs using the API token enables customers to access and in some cases modify information through a third-party app or APIs without the risk of compromising security. It also ensures that secure, sensitive customer-related information is not exposed to the third-party app.

Currently, users can generate API credentials for the Transactions API and Network Integration API (the Network Integration API is available to Network users only).

Create an API Token

To create an API token:

  1. From the Navigation Bar, hover on Integrations and select “Invoca APIs”

    _images/manage_api_credentials.png

  2. On the “Invoca API Credentials” page, click “New API Credential”

  3. Enter Description and click Save.

Note: It is recommended to provide a description that identifies the API type and use.

Delete an API Token

To delete or remove an API token from your platform:

  1. From the Navigation Bar, hover on Integrations and select “Invoca APIs”

    _images/manage_api_credentials.png

  2. On the “Invoca API Credentials” page, click the delete icon associated to the API token to delete.

API Guidelines

  • Users should generate their own API tokens. Tokens should be treated like passwords and not be emailed or transmitted over other insecure mediums, nor should they be stored in a customer’s source code repository.
  • As a network user, you should not generate a token on behalf of Advertisers or Publishers as tokens inherit the privileges of the user generating it.
  • Invoca does not use OAuth refresh tokens.

Network Integration

Invoca customers and partners can integrate with the Invoca Marketing Automation platform through use of the Invoca Network Integration API. The API offers interfaces for managing: Single sign on from network partner web sites into the Invoca Marketing Automation platform. Replication between network partner platforms and the Invoca platform via REST style Create, Read, Update and Delete operations. Including: Advertisers and their Users Affiliates and their Users Advertiser Campaigns Campaign Terms RingPools Promo Numbers Auto-Approve Affiliate to Campaigns

Terminology

The API uses the following terms and their aliases: “advertiser” (also known as “merchant”) “affiliate” (also known as “publisher”) “campaign” (also known as “offer”)

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/2015-12-09/<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
name string Campaign name.
campaign_type string 2 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.
description string Campaign Description.
url string Click URL Template.
timezone string Supported Time Zones: http://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html
campaign_language string Supported Campaign Languages: “English”, “French”, “Spanish”.
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.
max_promo_numbers integer Maximum Promo Numbers.
concurrent_call_cap_alert    
budget_amount decimal (required) Budget Amount.

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

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

*prompt

*sms_promo_copy

sms_promo_delay

sms_promo_sender

 Provide the option for a user to receive a text message with a special promotion.
Condition *condition If/else option for a call based on the qualities of the call/caller.
VerifyLocation prompt Prompt 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 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.

Node Details

Node Type Details
Menu Can have 1‐9 child nodes, with each child corresponding to the 1‐9 buttons.
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 is executed. If they are not met then the second child plays. 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.

Parameter Details

Property Type Value
condition String The boolean condition that decided if the first or second child will be executed in a condition node.
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.
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)

Endpoint

https://invoca.net/api/2015-12-09/<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/2015-12-09/<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/2015-12-09/<network_id>/advertisers/2/advertiser_campaigns/100.json

Response Body:

{
    "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",
      "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",
      "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"
          }
        ]
      },
      "status": "Entry",
      "name": "PostSeason Promotion 11 fJauFbSEGHKw8ADEGv",
      "max_promo_numbers": 10
    }
  }

Examples

Example POST to non‐existing Advertiser Campaign fJauFbSEGHKw8ADEGv under Advertiser cFUyYnFHyiYA42TrpM in the Demo Network.

POST

https://demo.invoca.net/api/2015-12-09/123/advertisers/cFUyYnFHyiYA42TrpM/advertiser_campaigns/fJauFbSEGHKw8ADEGv.json

With an existing advertiser, the IVR tree may be updated independently of other attributes. Below is a curl command that only needs network API credentials, a network id and an advertiser id. This will create an advertiser campaign with id 445566. The campaign id may be changed freely.

Endpoint:

https://demo.invoca.net/api/2015-12-09/123/advertisers/cFUyYnFHyiYA42TrpM/advertiser_campaigns/fJauFbSEGHKw8ADEGv.json

curl­ -XPOST­ -H "Content­Type: application/json"­ -u 'login:pass'
'https://vanity.invoca.net/api/2015-12-09/123/advertisers/advertiser_id/advertiser_campaigns/445566.json' \
-d '
{
  "hours": {
    "tuesday_close": 61200,
    "wednesday_close": 61200,
    "saturday_open": 28800,
    "wednesday_closed": false,
    "friday_open": 28800,
    "thursday_close": 61200,
    "thursday_closed": false,
    "friday_close": 61200,
    "monday_close": 61200,
    "wednesday_open": 28800,
    "sunday_open": 28800,
    "thursday_open": 28800,
    "friday_closed": false,
    "monday_open": 28800,
    "tuesday_closed": false,
    "monday_closed": false,
    "saturday_close": 61200,
    "saturday_closed": false,
    "sunday_close": 61200,
    "sunday_closed": false,
    "tuesday_open": 28800
  },
  "name": "NFLCampaign",
  "timezone": "Pacific Time (US & Canada)",
  "description": "Augustpromotion tosellpost­seasonticketsathalf price.",
  "campaign_language": "English",
  "ivr_tree": {
    "root": {
      "children": [

      ],
      "condition": "",
      "node_type": "Connect",
      "destination_phone_number": "8052844300",
      "destination_country_code": "1"
    },
    "record_calls": true
  },
  "named_regions": [
    {
      "name": "WestCoast",
      "regions": [
        {
          "value": "CA",
          "region_type": "State"
        },
        {
          "value": "OR",
          "region_type": "State"
        },
        {
          "value": "WA",
          "region_type": "State"
        }
      ]
    },
    {
      "name": "EastCoast",
      "regions": [
        {
          "value": "NY",
          "region_type": "State"
        },
        {
          "value": "NJ",
          "region_type": "State"
        }
      ]
    }
  ],
  "operating_24_7": false,
  "url": "http://www.nfltix.com/postseasonnow"
}
' -v

Create Campaign fJauFbSEGHKw8ADEGv for Advertiser cFUyYnFHyiYA42TrpM on network 1 (POST)

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/cFUyYnFHyiYA42TrpM/advertiser_campaigns/fJauFbSEGHKw8ADEGv.json

Request Body

{
  "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",
  "max_promo_numbers": 6,
  "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": ""
        }
      ]
    }
  }
}

Examples

Assuming you used the curl command to create the campaign with id 445566, the following commands will update that campaign to have a new IVR tree.

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/2015-12-09/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/2015-12-09/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/2015-12-09/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

Examples

Read Campaign 100 for Advertiser 2

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_>/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.

Use this request url format:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/go_live.json

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.

Use this request url format:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/go_live.json

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:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/archive.json

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:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/archive.json

Advertiser Users

For convenience, the API provides an interface for performing operations on specific advertiser users. This is useful for situations where it is inconvenient to send an array of all existing advertiser users.

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>/users/<user_id_from_network>.json

Examples

Read all advertiser users for advertiser e0Fv6YEk

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/e0Fv6YEk/users.json

Format: application/json

Response Code: 200

Response Body:

[
  {
    "email_address": "chris@nfltix.com",
    "id_from_network": "549494858585Dxlj2uCX0ijqXP4nAW",
    "first_name": "Chris",
    "contact_country_code": "1",
    "last_name": "Dean",
    "role": "Manager",
    "oauth_refresh_token": "556588585858585858585858858",
    "contact_phone_number": "8886033760"
  }
]

Examples

Read a specific advertiser user

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/e0Fv6YEk/users/549494858585Dxlj2uCX0ijqXP4nAW.json

Format: application/json

Response Code: 200

Response Body:

{
  "email_address": "chris@nfltix.com",
  "id_from_network": "549494858585Dxlj2uCX0ijqXP4nAW",
  "first_name": "Chris",
  "contact_country_code": "1",
  "last_name": "Dean",
  "role": "Manager",
  "oauth_refresh_token": "556588585858585858585858858",
  "contact_phone_number": "8886033760"
}

Examples

Create an advertiser user

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/e0Fv6YEk/users.json

Request Body:

{
  "user": {
    "id_from_network": "549494858585Dxlj2uCX0ijqXP4nAW",
    "email_address": "chris@nfltix.com",
    "first_name": "Chris",
    "last_name": "Dean",
    "contact_phone_number": "8055555555",
    "oauth_refresh_token": "556588585858585858585858858",
    "role": "Manager"
  }
}

Examples

Update an Advertiser User

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/e0Fv6YEk/users/<user_id>

Request Body:

{
  "user": {
    "first_name": "Chris",
    "last_name": "Dean",
    "contact_phone_number": "8055555555",
    "role": "Manager"
  }
}

Examples

Delete an advertiser user

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/e0Fv6YEk/users/549494858585Dxlj2uCX0ijqXP4nAW.json

Format: application/json

Response Code: 200

Response Body:

{
}

Advertisers

The operations on Advertiser are similar to Network, in that the interface is fully idempotent, and the create and update commands both expect the full set of advertiser sites and users each time. You are not allowed to delete an advertiser if it has one or more campaigns.

Property Type Value
id_from_network string (Required) The network id for this Advertiser. Unique within network.
name string (Required) The name of the Advertiser. Unique within network.
oauth_refresh_token string For internal use only.
approval_status string (one of): Applied, Approved (default), Declined, Suspended, Archived Approval status for this advertiser.
web_integration_phone_number string  
default_creative_id_from_network integer  
sites json array of hashes 1 or more pairs of id_from_network [and name].
id_from_network integer site_id (PID) The site_id (PID). At least one is required. The first becomes the default.
name string The site name that matches site_id.
users json array of hashes 0 or more users for the organization. Each must have first 5 fields below.
id_from_network string The network id for this User.
email_address string in RFC 2822 addr-spec format The user’s email address. Unique for this user.
first_name string (Required) The user’s first name.
last_name string (Required) The user’s last name.
contact_phone_number string in ITU E.164 format or 10-digit US form (no punctuation) The user’s phone number.
oauth_refresh_token string Not used. Reserved.
role One of: Super (default), Manager, Member, Observer This user’s role in this organization. (A user may have different roles in different organizations)

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>.json

Examples

Read all advertisers for this network

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers.json

Format: application/json

Response Code: 200

Response Body:

[
  {
    "id_from_network": "cFUyYnFHy",
    "web_integration_phone_number": "8004377950",
    "approval_status": "Approved",
    "sites": [
      {
        "id_from_network": "315",
        "name": "315.blog.com"
      }
    ],
    "name": "NFL Tickets Exchange",
    "users": [
      {
        "id_from_network": "549494858585cFUyYnFHyiYA42TrpM",
        "email_address": "chris1@nfltix.com",
        "first_name": "Chris",
        "phone_number": "888‐603‐3760",
        "last_name": "Dean",
        "role": "Manager",
        "oauth_refresh_token": "556588585858585858585858858"
      }
    ],
    "default_creative_id_from_network": "222",
    "oauth_refresh_token": "7464644784457575757494930303"
  }
]

Examples

Read a single advertiser

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/cFUyYnFHy.json

Format: application/json

Response Code: 200

Response Body:

{
  "id_from_network": "cFUyYnFHy",
  "web_integration_phone_number": "8004377950",
  "approval_status": "Approved",
  "sites": [
    {
      "id_from_network": "315",
      "name": "315.blog.com"
    },
    {
      "id_from_network": "996",
      "name": "996.blog.com"
    }
  ],
  "name": "NFL Tickets Exchange",
  "users": [
    {
      "id_from_network": "549494858585cFUyYnFHyiYA42TrpM",
      "email_address": "chris@nfltix.com",
      "first_name": "Chris",
      "phone_number": "888‐603‐3760",
      "last_name": "Dean",
      "role": "Manager",
      "oauth_refresh_token": "556588585858585858585858858"
    },
    {
      "id_from_network": "694940505055cFUyYnFHyiYA42TrpM",
      "email_address": "jim@nfltix.com",
      "first_name": "Jim",
      "phone_number": "888‐603‐3760",
      "last_name": "Williams",
      "role": "Observer",
      "oauth_refresh_token": "4222424241628298228222"
    }
  ],
  "default_creative_id_from_network": "222",
  "oauth_refresh_token": "7464644784457575757494930303"
}

Examples

Delete a single advertiser

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/cFUyYnFHy.json

Format: application/json

Response Code: 200

Response Body:

{
}

Examples

Create an advertiser with users

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/cFUyYnFHy.json

Format: application/json

Response Body:

{
  "name": "NFL Tickets Exchange",
  "oauth_refresh_token": "7464644784457575757494930303",
  "approval_status": "Approved",
  "web_integration_phone_number": "8004377950",
  "default_creative_id_from_network": "222",
  "users": [
    {
      "id_from_network": "549494858585cFUyYnFHyiYA42TrpM",
      "email_address": "chris@nfltix.com",
      "first_name": "Chris",
      "last_name": "Dean",
      "contact_phone_number": "8055555555",
      "oauth_refresh_token": "556588585858585858585858858",
      "role": "Manager"
    },
    {
      "id_from_network": "694940505055cFUyYnFHyiYA42TrpM",
      "email_address": "jim@nfltix.com",
      "first_name": "Jim",
      "last_name": "Williams",
      "contact_phone_number": "2135555555",
      "oauth_refresh_token": "4222424241628298228222",
      "role": "Observer"
    }
  ],
  "sites": [
    {
      "id_from_network": "315",
      "name": "315.blog.com"
    },
    {
      "id_from_network": "996",
      "name": "996.blog.com"
    }
  ]
}

Examples

Update a user from advertiser

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/cFUyYnFHy.json

Format: application/json

Request Body:

{
  "name": "NFL Tickets Exchange",
  "oauth_refresh_token": "7464644784457575757494930303",
  "approval_status": "Approved",
  "web_integration_phone_number": "8004377950",
  "default_creative_id_from_network": "222",
  "users": [
    {
      "id_from_network": "549494858585cFUyYnFHyiYA42TrpM",
      "email_address": "chris@nfltix.com",
      "first_name": "Chris",
      "last_name": "Dean",
      "contact_phone_number": "8055555555",
      "oauth_refresh_token": "556588585858585858585858858",
      "role": "Manager"
    }
  ],
  "sites": [
    {
      "id_from_network": "315",
      "name": "315.blog.com"
    }
  ]
}

Affiliate Campaigns

Affiliate Campaign status can be replicated using this API. You are not allowed to delete affiliate campaigns.

Relationship properties are shown below

Property Type Value
affiliate_id_from_network string (read only) Network specific id of the affiliate.
status string (read and write) One of: Applied, Approved, Suspended, Declined.
affiliate_campaign_id_from_network string (read and write) Network specific id of the affiliate campaign.
max_promo_numbers integer (read only) Promo number limit.
current_terms (read only)  
advertiser_payin    
max decimal Maximum payin amount (base + bonuses).
min decimal Minimum payin amount (base).
pricing string Human‐friendly representation of the payin pricing (eg. “$5.07 per call”).
currency string USD, GBP, EUR.
range string Formatted string including min and max payin values.
policies    
amount decimal Payin policy amount.
currency string USD, GBP, EUR.
type string Base, Bonus.
condition string Condition options used to determine the base or bonus payout (eg. “duration >= 1 min 30 sec”).
pricing_type string Fixed, OverallMargin, IndividualMargin.
ivr_tree hash Interactive Voice Response tree.
affiliate_payout    
max decimal Maximum payout amount (base + bonuses).
min decimal Minimum payout amount (base).
pricing string Human‐friendly representation of the payout pricing (eg. “$5.07 per call”).
currency string USD, GBP, EUR.
range string Formatted string including min and max payin values policies.
policies    
amount decimal Payout policy amount.
currency string USD, GBP, EUR.
type string Base, Bonus.
condition string Condition options used to determine the base or bonus payout (eg. “duration >= 1 min 30 sec”).

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/affiliates/<affiliate_id_from_network>/affiliate_campaigns/<affiliate_campaign_id_from_network>.json

Examples

Get all Affiliate Campaigns

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/affiliates.json

Examples

GET of Affiliate Campaign status for Advertiser 354 Campaign 12 to Affiliate 976

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/354/advertiser_campaigns/12/affiliates/976/affiliate_campaigns.json

Format: application/json

Response Body:

{
  "max_promo_numbers": 10,
  "current_terms": {
    "advertiser_payin": {
      "max": 3.5,
      "min": 3.5,
      "pricing": "$3.50 per call",
      "currency": "USD",
      "range": "$3.50 per call",
      "policies": [
        {
          "amount": 3.5,
          "currency": "USD",
          "type": "Base",
          "condition": ""
        }
      ]
    },
    "pricing_type": "Fixed",
    "ivr_tree": {
      "root": {
        "children": [
          {
            "destination_country_code": "",
            "destination_phone_number": "",
            "node_type": "Connect",
            "prompt": ""
          },
          {
            "destination_country_code": "",
            "destination_phone_number": "",
            "node_type": "Connect",
            "prompt": ""
          }
        ],
        "node_type": "Menu",
        "prompt": "Press one for transfer to a normal campaign (scottad pro 0903), press two for normal campaign (scott ad pro 3122), press three for transfer to a syndicated campaign!"
      },
      "record_calls": false
    },
    "affiliate_payout": {
      "max": 3.5,
      "min": 3.5,
      "pricing": "$3.50 per call",
      "currency": "USD",
      "range": "$3.50 per call",
      "policies": [
        {
          "amount": 3.5,
          "currency": "USD",
          "type": "Base",
          "condition": ""
        }
      ]
    }
  },
  "status": "Approved_NotActive",
  "affiliate_campaign_id_from_network": "11",
  "affiliate_id_from_network": "976"
}

Examples

Create Affiliate Campaign with status for Advertiser 354 Campaign 12 to Affiliate 975

Please note - The Network Integration API only provides the ability to create an affiliate campaign with status “Applied”. If the Advertiser Campaign is set to “Approve All”, the campaign will automatically transition to “Approved”.

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/354/advertiser_campaigns/12/affiliates/975/affiliate_campaigns.json

Format: application/json

Request Body:

{
  "status": "Applied",
  "affiliate_campaign_id_from_network": "2234"
}

Not Found - 404

Endpoint:

https://invoca.net/api/api/2015-12-09/<network_id>/advertisers/354/advertiser_campaigns/13/affiliates/976/affiliate_campaigns.json

Format: application/json

Request Body:

{
  "status": "Approved"
}

Response Code: 403

Response Body:

{
  "errors": {
    "status": [
      "cannot transition from 'Approved'"
    ]
  },
  "status": "Applied"
}

Examples

Update Affiliate Campaign status for Advertiser 354 Campaign 12 to Affiliate 976

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/354/advertiser_campaigns/12/affiliates/976/affiliate_campaigns.json

Format: application/json

Request Body:

{
  "status": "Approved"
}

Examples

You are not allowed to delete an Affiliate Campaign.

Affiliates

The operations on Affiliate are similar to Network, in that the interface is fully idempotent, and the create and update commands both expect the full set of affiliate sites and users each time. Similar to advertisers, you are not allowed to delete if one or more campaigns exist for this affiliate.

Property Type Value
id_from_network string The network object_id for this Affiliate. Unique within network.
name string The name of the Affiliate. Unique within the network.
status string (one of): Applied, Approved (default), Declined, Suspended, Archived Approval status for this affiliate.
sites json array of hashes 1 or more pairs of id_from_network [and name].
id_from_network string The site id (PID).
name string The site name that matches site id_from_network.
users json array of hashes 0 or more users for the organization. Each must have the first 5 fields below.
id_from_network string The network object_id for this user.
email_address string in RFC 2822 addr-spec format The user’s email address. Unique for this user.
first_name string(must not be blank) The user’s first name.
last_name string(must not be blank) The user’s last name.
phone_number string in ITU E.164 format or 10-digit US form (no punctuation) The user’s phone number.
role One of: Super (default), Manager, Member, Observer This user’s role in this organization. (A user may have different roles in different organizations)

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/affiliates/<affiliate_id_from_network>.json

Examples

Read all Affiliates for this network

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/affiliates.json

Request Body:

[
  {
    "id_from_network": "222",
    "sites": [
      {
        "id_from_network": "33567",
        "name": "http://www.surfoz.au"
      },
      {
        "id_from_network": "44920",
        "name": "http://www.blogspot.com/surfoz"
      }
    ],
    "name": "Surf Oz Magazine",
    "users": [
      {
        "email_address": "userx@invoca.com",
        "id_from_network": "1231",
        "first_name": "User",
        "phone_number": "805‐708‐9876",
        "last_name": "Affiliate",
        "role": "Super"
      }
    ],
    "status": "Approved"
  }
]

Examples

Read a specific affiliate

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/affiliates/222.json

Response Body:

{
  "id_from_network": "222",
  "sites": [
    {
      "id_from_network": "33567",
      "name": "http://www.surfoz.au"
    },
    {
      "id_from_network": "44920",
      "name": "http://www.blogspot.com/surfoz"
    }
  ],
  "name": "Surf Oz Magazine",
  "users": [
    {
      "email_address": "userx@invoca.com",
      "id_from_network": "1231",
      "first_name": "User",
      "phone_number": "805‐708‐9876",
      "last_name": "Affiliate",
      "role": "Super"
    }
  ],
  "status": "Approved"
}

Examples

Delete a single affiliate

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/affiliates/222.json

Response Body:

{
}

Examples

Create an affiliate with users

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/affiliates/222.json

Format: application/json

Request Body:

{
  "name": "Surf Oz Magazine",
  "status": "Approved",
  "users": [
    {
      "phone_number": "805‐708‐9876",
      "id_from_network": 123,
      "role": "Super",
      "last_name": "Affiliate",
      "first_name": "User",
      "email_address": "userx@invoca.com"
    }
  ],
  "sites": [
    {
      "id_from_network": 33567,
      "name": "http://www.surfoz.au"
    },
    {
      "id_from_network": 44920,
      "name": "http://www.blogspot.com/surfoz"
    }
  ]
}

Response Body:

{
}

Examples

Update a single affiliate

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/affiliates/222.json

Request Body:

{
  "name": "Updated Surf Oz Magazine"
}

Auto-Approve Affiliate to Campaigns

Changes to the Relationship between Advertiser and Affiliate on the network platform are replicated to the Invoca platform using this API. The operations on Advertiser‐Affiliate Relationships are similar to Network, in that the interface is fully idempotent, and the create and update commands will act as “create or update”.

When setting the Relationship between an Advertiser and Affiliate to Approved, all current and future campaign applications made between the Affiliate and Advertiser will be auto-approved. If the Relationship is set to any status other than Approved, all current and future applications will be declined and any active affiliate campaigns will be suspended.

Relationship status is set individually but reading is available for one or all relationships for an advertiser.

Parameters for the relationships are shown below

Property Type Value
affiliate_id_from_network string The network id for the affiliate. (read only)
status One of: Pending, Approved, Suspended, Declined, Deactivated Status of the advertiser ‐ affiliate relationship.

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>/affiliates/<affiliate_id_from_network>.json

Examples

Read all relationships for advertiser id from network 1

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/1/affiliates.json

Format: application/json

Response Code: 200

Response Body:

[
  {
    "status": "Approved",
    "affiliate_id_from_network": "222"
  },
  {
    "status": "Approved",
    "affiliate_id_from_network": "34518"
  }
]

Examples

Read a single relationship

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/1/affiliates/222.json

Format: application/json

Response Code: 200

Response Body:

{
  "status": "Approved",
  "affiliate_id_from_network": "222"
}

Examples

Create relationship between Advertiser id from network 1 and Affiliate id from network 222

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/1/affiliates/222.json

Format: application/json

Request Body:

{
  "status": "Approved"
}

Response Code: 201

Response Body:

{
}

Examples

Update an Advertiser-Affiliate relationship with id from network 1 and Affiliate id from network 222

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/1/affiliates/222.json

Format: application/json

Request Body:

{
  "status": "Approved"
}

Response Code: 200

Response Body:

{
}

Examples

Delete a relationship

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/1/affiliates/222.json

Response Code: 200

Networks

Network users are replicated to and retrieved from the Invoca Marketing Automation Platform using this API.

The network interface is fully idempotent, and the create and update commands both expect the full set of users each time. For instance, if on one POST two users, user1@invoca.com and user2@invoca.com are specified, but on the next POST, only user1@invoca.com is specified, then as a result of that second post, user2@invoca.com will be deleted. For this reason, POST and PUT requests are identical in their effect, although they return 201 and 200 codes respectively for ease of integration.

Parameters

Property Type Value
name string Network name (read only).
users json array of hashes 0 or more users for the network. User attributes are listed below.
id_from_network string The network’s id for this User.
email_address string in RFC 2822 addr_spec format The user’s email address. Unique for this user. (mandatory field)
first_name string The user’s first name.
last_name string The user’s last name.
phone_number string in ITU E.164 format or 10-digit US form (no punctuation) The user’s phone number.
role One of: Super (default), Manager, Member, Observer, Reporting The user’s role within the network.

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/network.json

Examples

Read network and its users

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/network.json

Format: application/json

Response Code: 200

Response Body:

{
  "name": "Invoca",
  "users": [
    {
      "id_from_network": "549494858585cFUyYnFHyiYA42TrpM",
      "email_address": "chris@nfltix.com",
      "first_name": "Chris",
      "last_name": "Dean",
      "phone_number": "800‐437‐7950",
      "role": "Manager"
    },
    {
      "id_from_network": "694940505055cFUyYnFHyiYA42TrpM",
      "email_address": "jim@nfltix.com",
      "first_name": "Jim",
      "last_name": "Williams",
      "phone_number": "800‐437‐7950",
      "role": "Observer"
    }
  ]
}

Examples

Create network users

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/network.json

Format: application/json

Request Body:

{
  "users": [
    {
      "id_from_network": "549494858585cFUyYnFHyiYA42TrpM",
      "email_address": "chris@nfltix.com",
      "first_name": "Chris",
      "last_name": "Dean",
      "phone_number": "8004377950",
      "role": "Manager"
    },
    {
      "id_from_network": "694940505055cFUyYnFHyiYA42TrpM",
      "email_address": "jim@nfltix.com",
      "first_name": "Jim",
      "last_name": "Williams",
      "phone_number": "8004377950",
      "role": "Observer"
    }
  ]
}

Response Code: 201

Examples

Update a network and its user with invalid email address

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/network.json

Format: application/json

Request Body:

{
  "users": [
    {
      "id_from_network": "549494858585cFUyYnFHyiYA42TrpM",
      "email_address": "chris@",
      "first_name": "Chris",
      "last_name": "Dean",
      "phone_number": "8004377950",
      "role": "Manager"
    }
  ]
}

Response Code: 403

Response Body:

{
  "errors": {
    "users": [
      {
        "email_address": [
          "is invalid"
        ]
      }
    ]
  }
}

Delete network users by putting an empty user hash

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/network.json

Format: application/json

Request Body:

{
  "users": [
  ]
}

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

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers/<promo_number>.json

Examples

Read all Advertiser Campaign Promo Numbers as an array

Endpoint:

https://invoca.net/api/2015-12-09/<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:

{
  "media_type": "Online: Display",
  "description": "Halloween Promo Number 1",
  "promo_number": "8001234567"
}

Read all Affiliate Campaign Promo Numbers as an array

Endpoint:

https://invoca.net/api/2015-12-09/<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:

{
  "media_type": "Online: Display",
  "description": "Halloween Promo Number 1",
  "promo_number": "8001234567"
}

Examples

Read a specific Advertiser Campaign Promo Number

Endpoint:

https://invoca.net/api/2015-12-09/<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:

{
  "media_type": "Online: Display",
  "description": "Halloween Promo Number 1",
  "promo_number": "8001234567"
}

Read a specific Affiliate Campaign Promo Number

Endpoint:

https://invoca.net/api/2015-12-09/<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:

{
  "media_type": "Online: Display",
  "description": "Halloween Promo Number 1",
  "promo_number": "8001234567"
}

Examples

Create an Advertiser Campaign Promo Number

Endpoint:

https://invoca.net/api/2015-12-09/<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:

{
  "media_type": "Online: Display",
  "promo_number": "8777657743",
  "description": "Halloween Promo Number 1"
}

Create an Affiliate Campaign Promo Number

Endpoint:

https://invoca.net/api/2015-12-09/<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:

{
  "media_type": "Online: Display",
  "promo_number": "8777657743",
  "description": "Halloween Promo Number 1"
}

Examples

Update an Advertiser Campaign Promo Number

Endpoint:

https://invoca.net/api/2015-12-09/<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:

{
}

Update Affiliate Campaign Promo Number

Endpoint:

https://invoca.net/api/2015-12-09/<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:

{
}

Examples

Delete an Advertiser Campaign Promo Number

Endpoint:

https://invoca.net/api/2015-12-09/<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/2015-12-09/<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:

{
}

Prompt Recordings

Assign prompts to campaigns

Professional prompt recordings can be assigned to advertiser campaigns. The prompts uploaded at Network level can be assigned to any advertiser campaign from that network. The prompts at Advertiser level can be assigned only to the campaigns of that specific advertiser.

Retrieve available prompts

It’s possible to retrieve all the prompts assigned to a network or an advertiser. The attributes returned for a prompt are:

id_from_network the network’s id for this prompt
prompt_text the text of the recording
prompt_url the url of the prompt recording file
prompt_received the date when the professional prompt was created

Example: Network prompt recordings

GET

https://invoca.net/api/2015-12-09/<network_id>.json

Response

{
  "name": "Invoca",
  "users": [],
  "prompt_recordings": [
    {
      "id_from_network": "a1b2",
      "prompt_text": "Thank you. Your call is being connected.",
      "prompt_url": "http://example.com/recording.wav",
      "prompt_received": "2015-08-02 08:49:28 -0700"
    },
    {
      "id_from_network": "pr_342",
      "prompt_text": "This prompt is on order",
      "prompt_url": "http://example.com/recording_order.wav",
      "prompt_received": null
    }
  ]
}

Example: Advertiser prompt recordings

GET

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>.json

Response

{
  "id_from_network": "11",
  "name": "Travel Agency",
  "oauth_refresh_token": null,
  "approval_status": "Approved",
  "web_integration_phone_number": "5555551234",
  "default_creative_id_from_network": "1234",
  "sites": [],
  "users": [],
  "prompt_recordings": [
    {
      "id_from_network": "rec736",
      "prompt_text": "Thank you for calling.",
      "prompt_url": "http://example.com/recording.wav",
      "prompt_received": "2015-08-02 08:49:28 -0700"
    }
  ]
}
Assign prompt to advertiser campaign

A prompt can be assigned to an advertiser campaign IVR tree by specifying its id_from_network at the specific node. The same request can be used to assign a new prompt or replace an existing one.

Example: assign prompt recording

POST

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>.json

Request Body

{
  "ivr_tree": {
    "record_calls": false,
    "root": {
      "node_type": "Connect",
      "destination_phone_number": "8056173768",
      "destination_country_code": "",
      "prompt_id_from_network": "rec34"
    }
  }
}

Example: list the prompts by retrieving the advertiser campaign

GET

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>.json

Response (complete response not shown)

{
  "name": "Selling Shoes",
  "status": "Activated",
  "future_terms": {
    "ivr_tree": {
      "record_calls": false,
      "root": {
        "node_type": "Connect",
        "destination_phone_number": "8056173768",
        "destination_country_code": "",
        "prompt": "Thank you. We appreciate your interest in our product.",
        "prompt_id_from_network": "rec34",
        "prompt_url": "http://example.com/recording.wav",
        "prompt_received": "2015-08-02 08:49:28 -0700"
      }
    }
  }
}

Example: remove prompt recording from a campaign

Just specify an empty id_from_network and the prompt will get unassigned from the campaign.

POST

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>.json

Request Body

{
  "ivr_tree": {
    "record_calls": false,
      "root": {
        "node_type": "Connect",
        "destination_phone_number": "8056173768",
        "destination_country_code": "",
        "prompt_id_from_network": ""
      }
  }
}

Whisper Prompts

Manage whisper prompts for campaigns

A whisper prompt can be created from provided text or a professional prompt recordings can be assigned as whisper prompt.

Create whisper prompt

Example: create whisper prompt

POST

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>.json

Request Body

{
  "ivr_tree": {
    "record_calls": false,
    "whisper_prompt_text": "How are you today?",
    "root": {
      "node_type": "Connect",
      "destination_phone_number": "8056173768",
      "destination_country_code": ""
    }
  }
}
Assign prompt recording as whisper prompt

Example: assign prompt recording as whisper prompt

POST

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>.json

Request Body

{
  "ivr_tree": {
    "record_calls": false,
    "whisper_prompt_id_from_network": "rec34",
    "root": {
      "node_type": "Connect",
      "destination_phone_number": "8056173768",
      "destination_country_code": ""
    }
  }
}
Retrieve whisper prompt for a campaign

Example: retrieve whisper prompt for a campaign

GET

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>.json

Response (complete response not shown)

{
  "name": "Selling Shoes",
  "status": "Activated",
  "future_terms": {
    "ivr_tree": {
      "record_calls": false,
      "whisper_prompt_text": "How are you today?",
      "whisper_prompt_id_from_network": "rec34",
      "root": {
        "node_type": "Connect",
        "destination_phone_number": "8056173768",
        "destination_country_code": ""
      }
    }
  }
}

Ringpools

Similar to Promo Numbers, because these are generated by Invoca, the interface is idempotent.

Property Type Value
name string Arbitrary string. Names the RingPool.
pool_type string (Required) One of: Search, SearchKeyword, Custom, CustomWithSearchTracking, ReferralDomain, ReferralDomainWithSearchTracking.
destination_type string (Required) one of: Advertiser, API.
destination_url url like, https://www.invoca.com.
lifetime_seconds integer The guaranteed minimum time that the number will be allocated for this RingPool.
max_pool_size integer The maximum amount of phone numbers to be allotted at one time.
param1 string Dynamic number pools have attributes named param1 through param10 for custom use by the user.
preferred boolean true or false. Selects this RingPool if the advertiser has multiple RingPools for the campaign and the web integration code does not specifiy which pool to use.
test_click_url string RingPool tracking link.
sample_api_url string RingPool API endpoint.
is_first_preference boolean Designates the preferred RingPool to be used for general traffic.

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/ring_pools/<ring_pool_id_from_network>.json

Examples

Read all RingPools as an array

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/ring_pools.json

Response Code: 200

Response Body:

{
  "id": "value",
  "pool_type": "value",
  "is_first_preference": true,
  "destination_url": "",
  "preferred": true,
  "sample_api_url": "value",
  "destination_type": "value",
  "lifetime_seconds": 1800,
  "name": "value",
  "param1": "",
  "param2": "",
  "param3": "",
  "param4": "",
  "param5": "",
  "param6": "",
  "param7": "",
  "param8": "",
  "param9": "",
  "param10": "",
  "max_pool_size": 15,
  "tracking_url": "value",
  "test_click_url": "value",
  "api_key": "value"
}

Examples

Read a RingPool

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/ring_pools/<ring_pool_id_from_network>.json

Response Code: 200

Response Body:

{
  "id": "value",
  "pool_type": "value",
  "is_first_preference": true,
  "destination_url": "",
  "preferred": true,
  "sample_api_url": "value",
  "destination_type": "value",
  "lifetime_seconds": 1800,
  "name": "value",
  "param1": "",
  "param2": "",
  "param3": "",
  "param4": "",
  "param5": "",
  "param6": "",
  "param7": "",
  "param8": "",
  "param9": "",
  "param10": "",
  "max_pool_size": 15,
  "tracking_url": "value",
  "test_click_url": "value",
  "api_key": "value"
}

Examples

Create a RingPool

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/ring_pools/<ring_pool_id_from_network>.json

Format: application/json

Request Body:

{
  "param1": "q",
  "param2": "test",
  "param3": "param3",
  "param4": "param4",
  "param5": "param5",
  "param6": "param6",
  "param7": "param7",
  "param8": "param8",
  "param9": "param9",
  "param10": "param10",
  "pool_type": "SearchKeyword",
  "api_key": "1234567890",
  "preferred": true,
  "name": "Invoca Example RingPool",
  "destination_url": "https://www.invoca.com",
  "max_pool_size": 15,
  "tracking_url": "https://www.invoca.com",
  "destination_type": "Advertiser",
  "lifetime_seconds": 1800
}

Response Code: 201

Response Body:

{
}

Examples

Update a RingPool

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/ring_pools/<ring_pool_id_from_network>.json

Format: application/json

Request Body:

{
  "param1": "updated",
  "param2": "test",
  "param3": "param3",
  "param4": "param4",
  "param5": "param5",
  "param6": "param6",
  "param7": "param7",
  "param8": "param8",
  "param9": "param9",
  "param10": "param10",
  "pool_type": "SearchKeyword",
  "api_key": "1234567890",
  "preferred": true,
  "name": "Invoca Example RingPool Updated",
  "destination_url": "https://www.invoca.com",
  "max_pool_size": 15,
  "tracking_url": "https://www.invoca.com",
  "destination_type": "Advertiser",
  "lifetime_seconds": 1800
}

Response Code: 200

Response Body:

{
}

Examples

Delete a RingPool

Endpoint:

https://invoca.net/api/2015-12-09/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/ring_pools/<ring_pool_id_from_network>.json

Format: application/json

Response Code: 200

Response Body:

{
}

Local RingPool API

Local RingPool Creation

The API provides the ability to create RingPools with additional information that specifies them as being ‘Local’ RingPools. These Local RingPools use local numbers that are determined by the parameters passed in by the user of the API. If a local phone number cannot be found the pool fills those slots (max_pool_size) with toll free numbers instead. When you POST with the correct parameters the Local RingPool is created and the allocation of local numbers happens later (approx. 10 minutes). This capability is JSON-only.

POST

https://invoca.net/api/2015-12-09/<network_id>/advertiser/<advertiser_id_from_network>/advertiser_campaign/<advertiser_campaign_id_from_network>/ring_pools/<desired_id_from_network>.json

Content Type: application/json

Property Type Value
name string Arbitrary string. Names the RingPool.
pool_type string (Required)

One of:

Search,

SearchKeyword,

Custom,

CustomWithSearchTracking,

ReferralDomain,

ReferralDomainWithSearchTracking
destination_type string (Required)

One of:

Advertiser,

API
destination_url url like, https://www.invoca.com
lifetime_seconds integer The guaranteed minimum time that the number will be allocated for this RingPool
max_pool_size integer The maximum amount of phone numbers to be allotted at one time
param1 string Dynamic number pools have attributes named param1 through param10 for custom use by the user
preferred boolean true or false. Selects this RingPool if the advertiser has multiple RingPools for the campaign and the web integration code does not specifiy which pool to use.
test_click_url string RingPool tracking link.
sample_api_url string RingPool API endpoint.
is_first_preference boolean Designates the preferred RingPool to be used for general traffic.
local_center hash

Requires one of the following

Latitude & Longitude required together

A filled field determines the center to start looking for local numbers at.

“tn_prefix”: an npa

“zipcode”: a valid zipcode

“latitude”: a valid latitude

“longitude”: a valid longitude
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”])

Response Code: 200

Request Body

{
 "param1": "gclid",
 "pool_type": "Custom",
 "preferred": "true",
 "name": "India DNP",
 "destination_url": "https://www.invoca.com",
 "tracking_url": "https://www.invoca.com",
 "max_pool_size": "3",
 "destination_type": "Advertiser",
 "local_center": {"latitude": 45, "longitude": 45},
 "tn_prefix_whitelist": ["455"]
}

Response Body

{}
Error Handling

Forbidden – 403:

POST

https://invoca.net/api/2015-12-09/<network_id>/advertiser/<advertiser_id_from_network>/advertiser_campaign/<advertiser_campaign_id_from_network>/ring_pools/<desired_id_from_network>.json

Content Type: application/json

Response Code: 403

Request Body

{
  "param1": "gclid",
  "pool_type": "Custom",
  "preferred": "true",
  "name": "India DNP",
  "destination_url": "https://www.invoca.com",
  "tracking_url": "https://www.invoca.com",
  "max_pool_size": "3",
  "destination_type": "Advertiser",
  "local_center": {"bad_key": ""},
  "tn_prefix_whitelist": ["455"]
}

Response Body

{
  "errors": {
    "class": "RecordInvalid",
    "invalid_data": "Invalid Key in Local Center."
  }
}

Conversion Reporting

The Conversion Reporting API (formerly referred to as the “Call Center” or “Sales Reporting” API) is used to report completed order information (or other conversion events) from a server back into the platform. Reporting order information through the API allows advertisers to compensate publishers for sales that convert over the phone (or on the web). Additionally, Advertiser Direct campaigns using the Conversion Reporting API with search campaigns can report back revenue generated for each phone call so that search bids can be optimized.

Before using the Conversion Reporting API, request credentials from questions@invoca.com

Client API Wrappers

The following working examples with wrapper code to integrate in Ruby, Java, PHP or .NET are available:

POST (or PUT) to a URL

Send call results to Invoca servers in the form of an HTTP POST. cURL is recommended because it is simple and preinstalled on most machines. The extended example later in this document breaks down each part of a cURL POST.

Here is an example of a URL POST:

https://api0.invoca.net/api/2014-04-15/calls/23.xml

where “” is the API version and “23” is the Conversion Reporting ID (previously known as Call Center ID) for your account on the platform.

For “Publisher Promotion” or Fixed Price “Bundled” campaigns, the Conversion Reporting ID is found on the Campaign Summary tab, Integration section.

Remember to check the HTTP status code returned for error checking. This helps greatly when debugging.

Parameters

Passed in standard HTML “application/form-url-encoded” format. Put quotes around all parameter values being passed in the API call.

Report a sale/conversion on a call

Required

start_time_t: 10 digit start time of the call in UTC seconds since 1/1/70, also known as Unix time_t. The start time does not have to be exact since clocks will not be perfectly synchronized.

Additionally, one of the following two parameters is highly recommended:

calling_phone_number: ANI in E.164 format +country national_number; example: ‘+18885551212’.

duration_in_seconds: Length of the call. Used for finding the call that drove the sale, not used to check against payout conditions. Like start time, duration_in_seconds does not have to be exact, we use it find the closest match.

Optional

reference_id: (call_center_call_id): This ID must be unique for each call across a call center’s calls. The ID is set the first time the call result is POSTed for a call. To update the call result, use the same ID.

called_phone_number: DNIS in E.164 format +country national_number; example: ‘+18885551212’. UK and Spanish numbers are also supported. Their country codes are +44 and +34 respectively.

use_http_status: 1 or blank will use HTTP status corresponding to success/failure. If set to 0, the HTTP status will always be 200 OK and the actual status and error message will be in the response body. See the Status section below.

Report a new web conversion

Required

web_conversion: Set to “1” to indicate a conversion that is not tied to a call (default is 0).

reference_id: This ID must be unique for each conversion.

advertiser_campaign_id: The ID of the advertiser campaign in the platform.

affiliate_id_from_network: The affiliate or publisher ID (of the main network) that is credited for the web conversion; the publisher must be approved to the advertiser campaign specified above.

Optional

use_http_status: 1 or blank will use HTTP status corresponding to success/failure. If set to 0, the HTTP status will always be 200 OK and the actual status and error message will be in the response body. See the Status section below.

Add to an existing web conversion

Required

web_conversion: Set to “1” to indicate a conversion that is not tied to a call (default is 0).

parent_reference_id: This is the reference_id that was passed in when creating the initial web conversion.

Optional

use_http_status: 1 or blank will use HTTP status corresponding to success/failure. If set to 0, the HTTP status will always be 200 OK and the actual status and error message will be in the response body. See the Status section below.

Shared parameters for sales and web conversions

Optional (for Tracking Sales)

reason_code: the conversion event specified in the payout conditions in the campaign. This code is free form and left to the advertiser to decide.

(For example, ‘R’ for Referred to customer service, or ‘info’ for requesting information. Or simply “Y” for a lead was generated and “N” if not.)

sku_list[]: Product SKU (repeat this parameter for multiple products). Like the reason_code, the sku_list is a free form description of the product or service sold and can be used as a payout condition.

Note: when reporting via email, the CSV header name should be “sku_list” and a single comma separated list should be provided.

quantity_list[]: Quantity 1 or greater for the corresponding product SKU listed in the sku_list (Quantities must appear in same order as the SKUs listed in the sku_list.)

Note: when reporting via email, the CSV header name should be “quantity_list” and a single comma separated list should be provided.

sale_currency: USD, GBP, EUR, etc.

sale_amount: Amount to 2 decimal places, or 0.00 if no sale (does not include shipping).

Optional (for Remarketing)

email_address: email address in RFC2822 format or empty string

name: first last name

address1: Address line 1.

address2: Address line 2.

order_city: City

state_or_province: State of Province

country: Country

zip_code: Postal Code

home_phone_number: Home phone in case there are any questions, in E.164 format.

cell_phone_number: Cell phone in case there are any questions, in E.164 format.

opt_in_SMS: 1 if authorized to send SMS reply or 0 or empty if not.

Status

The HTTP status returned is 201 Created for a successful POST (or a 200 OK for a successful PUT), a 4xx code if one of the parameters is incorrect, or a 5xx code if a server error occurred. In the latter two error cases, a detailed error class and message are returned in XML in the body, for example:

<?xml version="1.0" encoding="UTF-8"?>
<Error>
    <Class>NotFound</Class>
    <Message>Couldn't find call around time 1262895406 from caller +1 8053825533
     </Message>
</Error>

If &use_http_status=0 is given, the status is always returned as 200 Ok or 201 Created. This can be helpful in order to see the detailed error message in the body when working with HTTP libraries that just return the status code when there are errors without exposing the body.

Security

All posts must use HTTPS BASIC authentication and use pre-assigned usernames and passwords. Contact questions@invoca to request Conversion Reporting API credentials.

High availability

The initial POST should choose randomly (or alternately) between api0.invoca.net and api1.invoca.net. If a POST fails for any reason, retry the POST on the other one.

Idempotency

Sales are considered unique using a combination of start_time_t + SKU_list + reason code. POSTs with duplicate keys (same call, sku list, reason code) behave as follows:

  1. If the values passed are unchanged, the reported conversion remains unchanged and is not duplicated.
  2. If different values are passed, the original conversion is updated with the new values.

POSTs with unique keys always create new conversion transactions.

Frequency

Updates can be sent at any frequency from once a minute to once a day. Customers prefer to get their data as fast as possible, so the best practice is to get as close to once a minute as practical.

Example

The example below uses cURL to demonstrate a POST that updates a call.

curl -u 'example@callcenter.api:secretPW'` \
'https://api0.invoca.net/api/2014-04-15/calls/23.xml' -k -v \` \
-d reference_id='2935812450'             \
-d start_time_t='1273589993'             \
-d duration_in_seconds=300               \
-d called_phone_number='+18773593504'    \
-d calling_phone_number='+12143283408'   \
-d reason_code='S'                       \
-d sku_list[]='DVD'                      \
-d quantity_list[]=2                     \
-d sku_list[]='cleaner'                  \
-d quantity_list[]=1                     \
-d sale_currency='USD'                   \
-d sale_amount='60.50'                   \
-d email_address='jane@doe.com'          \
-d opt_in_SMS='1'                        \
-d name='Jane Doe'                       \
-d address1='123 Mockingbird Lane'       \
-d address2='Unit 2'                     \
-d order_city='Chicago'                  \
-d state_or_province='IL'                \
-d country='US'                          \
-d cell_phone_number='+13125170488'      \
-d use_http_status='1'</code></pre>

Output:

HTTP/1.1 201 Created
Date: Fri, 25 Jun 2010 18:22:45 GMT
Server: Mongrel 1.1.5
Status: 201
X-Runtime: 189
Cache-Control: no-cache
Content-Type: application/xml; charset=utf-8
Content-Length: 1
Set-Cookie: SERVERID=; Expires=Thu, 01-Jan-1970 00:00:01 GMT; path=/
Via: 1.1 www.invoca.net
Vary: Accept-Encoding

Example Breakdown

This is a description of some of the parameters in the previous cURL example.

curl -u ‘example@callcenter.api:secretPW’ If using cURL, this is how credentials are passed. The username is ‘example@callcenter.api’ and the password is ‘secretPW’. The two strings need to be separated with a colon character.

‘https://api0.invoca.net/api/2014-04-15/calls/23.xml’ -k -v The URL where the call result is sent. The API version is “2016-01-25” and the unique Conversion Reporting ID is “23”.

-d reference_id=‘2935812450’ This ID (if provided) needs to be unique for each call within a call center, and is the handle for future updates on this call or conversion.

-d start_time_t=‘1273589993’ The call start time in UTC.

-d called_phone_number=’+18773593504’ The phone number the caller dialed.

-d calling_phone_number=’+12143283408’ The phone number the caller is calling from.

-d sku_list[]=’DVD’

-d quantity_list[]=2

-d sku_list[]=’cleaner’

-d quantity_list[]=1 sku_list and quantity_list are closely related. The quantity_list must appear in the same order as the sku_list. For this example, the sku DVD has a quantity value of 2 while cleaner is 1.

Search Algorithm to Find Matching Call

We look for an exact match for calls associated with the call center, using these parameters, if given:

reference_id calling_phone_number

If more than one call is found with those exact parameters (or the parameters are not provided), we then look for calls that are closest to the start_time_t and duration_in_seconds, if provided. Due to the distribution of call attribute data, the start_time_t parameter is given a different weight than duration_in_seconds so that a call with a start time difference of 20 seconds is equivalent to a call with a duration difference of 1 second.

Please note that the Conversion Reporting API is idempotent (if you repost sales data already captured, it is not accidentally counted twice), so repost any sales that receive a failure.

Endpoint:

https://invoca.net/api/2014-04-15/calls/<converstion_reporting_id>.xml

Conversion Reporting Pixel

A conversion pixel is placed on an advertiser’s web page to report a conversion event that triggers payouts on the platform. Typically, the pixel is placed on a shopping cart confirmation page or lead form thank you page.

To report conversions using a pixel

Verify that you have received the Conversion Reporting credentials email from support, including your Upload Email Address and Conversion Reporting ID.

For “Publisher Promotion” or Fixed Price “Bundled” Campaigns, view your Conversion Reporting credentials in the Campaign Summary tab, Integration section.

Advantages:

  • Easy to integrate - simply add a 1x1 image tag with a specific URL.

Disadvantages:

  • Requires that the visitor came to the site via an Invoca tracking link.
  • Pixel must be hit in a browser (it can not be done in a redirect, or from a background process).

Pixel URL

http://api.invoca.net/pixels/conversion/ADVERTISER_ID.gif?SALES_PARAMS

For “Publisher Promotion” or Fixed Price “Bundled” Campaigns, the Advertiser_ID is listed on the Campaign Summary, Integration panel.

For all other campaign types, the Advertiser_ID is accessible from the Advertiser Home Page. Note the address b in the ar the browswer in t he rD follows /as/ in the URL.

The Sales_Params available are documented in Conversion Reporting API under the “Shared Parameters for Sales and Web Conversions” section.

The advertiser campaign and publisher are determined based on what link drove the traffic to the advertiser’s site, and are calculated automatically.

We support tying a web pixel to a subsequent server-side conversion. In order to tie the conversions together, you must have passed a reference_id to the original web pixel, and also pass that same reference_id to the Conversion Reporting API.

Example URLs

(assuming that Advertiser_ID = 1) Most basic URL, just reports that a conversion occurred, but without a sale or any additional data:

http://api.invoca.net/pixels/conversion/1.gif

Report a conversion where a $10 sale occurred:

http://api.invoca.net/pixels/conversion/1.gif?sale_amount=10

Report a conversion with specific sales data:

http://api.invoca.net/pixels/conversion/1.gif?sale_amount=10&reason_code=renewal&sku_list[]=34657

Report a conversion with multiple sku items:

http://api.invoca.net/pixels/conversion/1.gif?sale_amount=10&sku_list[]=dog&sku_list[]=cat

Report a conversion with unique identifier to track later (in the Transactions API or future pixel-based conversions):

http://api.invoca.net/pixels/conversion/1.gif?sale_amount=0&reason_code=new_signup&reference_id=2012994455

Update a conversion that was reported earlier:

http://api.invoca.net/pixels/conversion/1.gif?sale_amount=95.0&reason_code=confirmed_order&parent_reference_id=2012994455

Web pixel example

<!DOCTYPE html>

<html>
  <head>
    <title>Order Confirmation</title>
  </head>

  <body>
    <img src="PIXEL_URL" width="1" height="1">

    Your order has been placed.
  </body>
</html>

Old version (before December 2012)

This version is only supported for existing installations. Conversions generated by this version can not be tied to future server-based conversions.

http://api.invoca.net/tracked_actions/web_sale/ADVERTISER_ID?SALES_PARAMS

The following sales params are supported:

  • amount (sale amount)
  • currency (sale currency, defaults to USD)
  • external_data (string, shown in reports)

Conversion Reporting Email

Conversion events can be reported using an email message with an attached CSV file.

To report conversions using email

Verify that you have received the Conversion Reporting credentials email from support, including your Upload Email Address and Conversion Reporting ID.

For “Publisher Promotion” or Fixed Price “Bundled” Campaigns, view Conversion Reporting credentials in the Campaign Summary tab, Integration section.

Note or copy the Upload Email Address.

Conversion Report Message Format:

Conversion Reporting sent via email must be in a CSV (comma-separated values) file format with the sale reporting parameters as the column headers and each sale transaction on a single row. Attach the CSV file to an empty message and send it to the Upload Email Address.

Two example files are shown at the bottom of this article. Feel free to contact your Program Manager or questions@invoca.com for a skeleton file that suits your needs. Removing un-used columns reduces mistakes, so trim the skeleton file to include only the parameters you need.

For Call Based Conversions

Only one parameter is absolutely required: the start time of the call. Any entry missing the start time of the call causes an error and is not processed. Including the calling phone number is also recommended.

Start time

Start time is used to associate the sales transaction to a call. There are two types of time parameters: start_time and start_time_t. Start_time_t is in the universal “Unix time_t” format while start_time is in human-readable format: YYYY/MM/DD HH:MM:SS. Note that skeleton files have an example of this format but be sure to look at them in a plain text editor like Notepad. If you open the file with Excel, Excel reformats that column to match its preference!

Start_time_t has precedence over start_time so if you are planning to just use start_time, remove the start_time_t column from the skeleton file.

Best practices encourage using the 10-digit start_time_t.

If you are using the start_time parameter, contact us to set the time zone of your sale reporting at questions@invoca.com.

For more information on possible parameters and how the matching call is found, see Conversion Reporting.

For Web Based Conversions

The affiliate or publisher ID and advertiser campaign ID are required.

For more information on possible parameters and how the matching call is found, see Conversion Reporting.

Reply Message

Conversion Reporting emails are processed on a nightly basis and a reply message is sent once the task is completed. The reply message includes the number of conversions processed, the number of conversions that did not match up with a transaction and the number of errors. For each error encountered, the row number, the content of that row and the error it caused is returned. Please note that only up to 10 errors per batch are allowed before processing is stopped.

Examples:

  1. Conversions reported include the call Start Time in Human Readable Time Format, the Calling Phone Number and the Reason Code.
  1. Conversions reported include the call Start Time in Unix Time Format, the calling phone number and the Sku List.

Idempotency:

Sales are considered unique using a combination of start_time_t + SKU_list + reason code. Reported conversions duplicate keys (same call, sku list, reason code) behave as follows:

  • If the values passed are unchanged, the reported conversion remains unchanged and is not duplicated.
  • If different values are passed, the original conversion is updated with the new values.

Reported conversions with unique keys always create new conversion transactions.

Transactions API

The Transactions API and Network Integration API are accessible using the API credentials generated on the platform.

Network / Brand - provides read-only access to call transaction data.

Advertiser / Merchant - supports the replication and synchronization of advertiser, publisher and campaign data between partner platforms.

Publisher / Affiliate - provides the ability to report completed order information (or other conversion events) from a server back into the platform.

The Transactions API provides an interface for retrieving call transactions for your organization. This provides you with a superset of the information available on the Reporting Details tab. The API is designed to be polled at any interval over 5 minutes. You should store the last transaction id you have downloaded in order to pass it as the start_after_transaction_id with the next request. Typical usage on the polling interval is to repeatedly call the API until no rows are returned, meaning you have downloaded all transactions. If an existing transaction is corrected, the correction will appear as a new transaction that refers to the original through the corrects_transaction_id field. When you receive a correction, replace the original transaction’s attributes with the new attributes from the correction. The data returned depends on your account type. To see which fields you will see, select an account type. Please note, results will show a superset of fields available. Your response may differ depending on the features enabled on the platform being accessed. Make a sample request to the API to identify the fields returned.

RP_API.png

Network / Brand

URL

The API follows REST conventions. Perform an HTTPS GET to the URL with the format in which you’d like to receive data. The following response formats are supported, where 33 is the network id.

Format Description and URL
csv Comma-Separated Values, or really Anything-Separated Values (see column_separator= below). Returns an optional header row followed by one row for each transaction, with delimited values for each row. https://mynetwork.invoca.net/api/2016-01-25/networks/transactions/33.csv
xml Returns an XML document with an array of Transaction elements. https://mynetwork.invoca.net/api/2016-01-25/networks/transactions/33.xml
json Returns a JSON array of transaction objects. https://mynetwork.invoca.net/api/2016-01-25/networks/transactions/33.json

Authentication

The API uses OAuth Authentication to authenticate that access is allowed. Pass the OAuth Token like any other query parameter, however, please note that the OAuth token is a required parameter. OAuth Tokens may be generated from the Manage API Credentials page.

Query Parameters

The API takes the following optional query parameters:

Parameter Description
from= Starting date in user’s time zone, in format YYYY-MM-DD. Example: 2011-06-01. Inclusive.
to= Ending date in user’s time zone, in format YYYY-MM-DD. Example: 2011-06-07. Inclusive.
limit= Max number of transactions to return at a time. Defaults to 1000. Limited to at most 4000.
start_after_transaction_id= Transaction_id to start retrieving after. This should be the last value retrieved previously. Default (or empty string) means start at the oldest.
column_separator= [.csv format only] Separator between columns. Default is , for comma-separated values. (Can be set to any other separator like | for pipe-separated values or %09 for tab-separated values.)
row_separator= [.csv format only] Separator between lines. Defaults to %0A for n (line feed). Use %0D%0A for rn (carriage return + line feed).
include_header= [.csv format only] 1 to include a header row; 0 to omit the header row. Default is 1.
force_quotes= [.csv format only] 1 to quote all CSV fields; 0 to only quote fields that contain separators. Default is 0.
transaction_type= Filters for the type of transaction. Valid inputs are Call, PostCallEvent, Sale, or Signal. Sale maps to the Reported Conversion type.

In order to ensure that all transactions are returned when using the from= and to= date query parameters, you should store the last transaction id you have downloaded and pass it as the start_after_transaction_id to the next request. Typical usage on the polling interval is to repeatedly call the API until no rows are returned, meaning you have downloaded all transactions. Please note, the “to” and “from” date range parameters are both necessary, providing only one or the other will not filter the results.

Example:

Send request 1:

https://yourcompany.invoca.net/api/2016-01-25/networks/transactions/706.csv?limit=500&oauth_token=<YOUR_OAUTH_TOKEN>&from=2015-03-26&to=2015-03-27

returns 500 rows, grab the last transaction_id (in this example 500) and send request 2:

https://yourcompany.invoca.net/api/2016-01-25/networks/transactions/706.csv?limit=500&oauth_token=<YOUR_OAUTH_TOKEN>U&from=2015-03-26&to=2015-03-27&start_after_transaction_id=500

then repeat as necessary to get all call records within date range.

Response

The data returned has the following fields:

Field Name in Reports Description
advertiser_call_fee_localized Advertiser Fees Advertiser Telecommunications fee associated with transaction
advertiser_campaign_id Advertiser Campaign ID (Invoca ID) The Invoca identifier of the campaign.
advertiser_campaign_id_from_network Advertiser Campaign ID The Campaign ID from the network as set on the advertiser campaign.
advertiser_campaign_name Advertiser Campaign Name of the campaign.
advertiser_id Advertiser ID (Invoca ID) The Invoca identifier of the advertiser
advertiser_id_from_network Advertiser ID Advertiser ID from the network as set on the Invoca advertiser.
advertiser_name Advertiser Name of the advertiser.
advertiser_payin_localized Earned Amount paid in by advertiser
affiliate_call_volume_ranking Affiliate Volume Ranking Network ranking of affiliate’s call volume (0 to 5, and -1 being ‘new’). Blank if no affiliate.
affiliate_commissions_ranking Affiliate Commissions Ranking Network ranking of affiliate’s commissions (0 to 5, and -1 being ‘new’). Blank if no affiliate.
affiliate_conversion_rate_ranking Affiliate Conversion Rate Ranking Network ranking of affiliate’s conversion rate (0 to 5, and -1 being ‘new’). Blank if no affiliate.
affiliate_id Affiliate ID (Invoca ID) The Invoca identifier of the affiliate
affiliate_id_from_network Affiliate ID Affiliate ID from the network as set on the Invoca affiliate.
affiliate_name Affiliate Name of the affiliate
affiliate_payout_localized Paid Amount paid out to the affiliate
call_fee_localized Fees Telecommunications fee associated with transaction
call_result_description_detail Call Result Status of the transaction
call_source_description Source Source of the transaction
calling_phone_number Caller ID Caller ID. Formatted as 12 characters like 866-555-1234
city City City where transaction originated
complete_call_id Call Record ID Globally unique identifier for the call this transaction is part of. Up-to 32 character string, can contain alphanumeric characters (i.e. 0-9A-Z) and the -.
connect_duration Connected Duration (HH:MM:SS) Duration in seconds that the call that was connected to the call center.
corrected_at Corrected At [Correction only] Date and time the transaction was corrected, in user’s time zone, followed by offset from GMT.
corrects_transaction_id Corrects Call [Correction only] Id of the original transaction that this transaction updates. Values in this row are the corrected ones and should replace the original values. Same format as transaction_id. Up-to 32 character string, can contain alphanumeric characters (i.e. 0-9A-Z) and the -.
destination_phone_number Destination Phone Number The phone number where the call was transferred to (useful if an IVR transfers to multiple destinations). Up-to 20 character string, can contain numeric characters (i.e. 0-9) and the following additional characters: ‘-‘, ‘#’, ‘*’, ‘x’, and ‘,’. ‘
duration Total Duration (HH:MM:SS) Duration of the call in seconds. Includes any time spent in an IVR tree before transferring to the call center.
ivr_duration IVR Duration (HH:MM:SS) Duration in seconds that the call spent in the IVR tree.
keypress_1 Key 1 Name of the first key that was pressed
keypress_2 Key 2 Name of the second key that was pressed
keypress_3 Key 3 Name of the third key that was pressed
keypress_4 Key 4 Name of the fourth key that was pressed
keypresses Keypresses List of unique keynames that were pressed during the call
margin_localized Margin Difference between advertiser_payin_localized and affiliate_payout_localized
matching_advertiser_payin_policies Matching Advertiser Payin Policies List of advertiser policies that matched (base, bonus1, bonus2, etc.) to determine the advertiser payin, separated by +. For example, base+bonus1+bonus3. Note that if there was any advertiser payin, this field guaranteed to start with base.
matching_affiliate_payout_policies Matching Affiliate Payout Policies List of affiliate policies that matched (base, bonus1, bonus2, etc.) to determine the affiliate payout, separated by +. For example, base+bonus2. Note that if there was any affiliate payout, this field guaranteed to start with base.
media_type Media Type Media type of the transaction source
mobile Phone Type Landline or Mobile or empty string if type is unknown
notes Notes Free-form notations on transaction
opt_in_SMS Opt In Sms Whether the caller opted in to receive an SMS promotion.
original_order_id Order ID [Sales reporting only] Id of the original transaction that this row is in reference to. Up-to 32 character string, can contain alphanumeric characters (i.e. 0-9A-Z) and the -.
payin_conditions Payin Conditions Base condition with highlighting around the term(s) that disqualified advertiser payin. For example: duration > 1 min and in_region
payout_conditions Payout Conditions Base condition with highlighting around the term(s) that disqualified affiliate payout. For example: duration > 1 min and in_region
qualified_regions Qualified Regions The list of regions that that the caller matched
recording Recording URL to the call recording, if available
region Region Region (state, province or country) where transaction originated
repeat_calling_phone_number Repeat Caller Whether the call was a repeat call. Repeat call detection is not applied to shared or unavailable caller ids.
start_time_local Call Start Time Start of the call in the API user’s time zone, followed by offset from GMT.
start_time_utc Call Start Time (UTC timestamp) Start of the call in milliseconds since Jan 1, 1970. Divide by 1000 to get Unix epoch time.
start_time_xml Call Start Time (XML formatted) Start of the call in Soap XML formatted time.
transaction_id Transaction ID Globally unique identifier for this transaction. Up-to 32 character string, can contain alphanumeric characters (i.e. 0-9A-Z) and the -. This is the Primary Key of the results.
transaction_type Type The type of transaction - Call, Post Call Event, Reported Conversion, or Signal.
transfer_from_type Transfer Type Where the call came from
verified_zip Verified Zip Code Zip Code entered by callers when prompted during call treatment
virtual_line_id Promo Number ID The Promo Number ID from the network

Optional Parameters

The following fields are optional based on your account type:

RingPool Parameters
Field Name in Reports Description
dynamic_number_pool_id Pool ID The ID of the pool.
dynamic_number_pool_pool_type Pool Type The type of pool: Search, SearchKeyword or Custom
dynamic_number_pool_referrer_param1_name Pool Param 1 Name The name for parameter 1
dynamic_number_pool_referrer_param1_value Pool Param 1 Value The value for parameter 1
dynamic_number_pool_referrer_param2_name Pool Param 2 Name The name for parameter 2
dynamic_number_pool_referrer_param2_value Pool Param 2 Value The value for parameter 2
dynamic_number_pool_referrer_param3_name Pool Param 3 Name The name for parameter 3
dynamic_number_pool_referrer_param3_value Pool Param 3 Value The value for parameter 3
dynamic_number_pool_referrer_param4_name Pool Param 4 Name The name for parameter 4
dynamic_number_pool_referrer_param4_value Pool Param 4 Value The value for parameter 4
dynamic_number_pool_referrer_param5_name Pool Param 5 Name The name for parameter 5
dynamic_number_pool_referrer_param5_value Pool Param 5 Value The value for parameter 5
dynamic_number_pool_referrer_param6_name Pool Param 6 Name The name for parameter 6
dynamic_number_pool_referrer_param6_value Pool Param 6 Value The value for parameter 6
dynamic_number_pool_referrer_param7_name Pool Param 7 Name The name for parameter 7
dynamic_number_pool_referrer_param7_value Pool Param 7 Value The value for parameter 7
dynamic_number_pool_referrer_param8_name Pool Param 8 Name The name for parameter 8
dynamic_number_pool_referrer_param8_value Pool Param 8 Value The value for parameter 8
dynamic_number_pool_referrer_param9_name Pool Param 9 Name The name for parameter 9
dynamic_number_pool_referrer_param9_value Pool Param 9 Value The value for parameter 9
dynamic_number_pool_referrer_param10_name Pool Param 10 Name The name for parameter 10
dynamic_number_pool_referrer_param10_value Pool Param 10 Value The value for parameter 10
dynamic_number_pool_referrer_param11_name Pool Param 11 Name The name for parameter 11
dynamic_number_pool_referrer_param11_value Pool Param 11 Value The value for parameter 11
dynamic_number_pool_referrer_param12_name Pool Param 12 Name The name for parameter 12
dynamic_number_pool_referrer_param12_value Pool Param 12 Value The value for parameter 12
dynamic_number_pool_referrer_param13_name Pool Param 13 Name The name for parameter 13
dynamic_number_pool_referrer_param13_value Pool Param 13 Value The value for parameter 13
dynamic_number_pool_referrer_param14_name Pool Param 14 Name The name for parameter 14
dynamic_number_pool_referrer_param14_value Pool Param 14 Value The value for parameter 14
dynamic_number_pool_referrer_param15_name Pool Param 15 Name The name for parameter 15
dynamic_number_pool_referrer_param15_value Pool Param 15 Value The value for parameter 15
dynamic_number_pool_referrer_param16_name Pool Param 16 Name The name for parameter 16
dynamic_number_pool_referrer_param16_value Pool Param 16 Value The value for parameter 16
dynamic_number_pool_referrer_param17_name Pool Param 17 Name The name for parameter 17
dynamic_number_pool_referrer_param17_value Pool Param 17 Value The value for parameter 17
dynamic_number_pool_referrer_param18_name Pool Param 18 Name The name for parameter 18
dynamic_number_pool_referrer_param18_value Pool Param 18 Value The value for parameter 18
dynamic_number_pool_referrer_param19_name Pool Param 19 Name The name for parameter 19
dynamic_number_pool_referrer_param19_value Pool Param 19 Value The value for parameter 19
dynamic_number_pool_referrer_param20_name Pool Param 20 Name The name for parameter 20
dynamic_number_pool_referrer_param20_value Pool Param 20 Value The value for parameter 20
dynamic_number_pool_referrer_param21_name Pool Param 21 Name The name for parameter 21
dynamic_number_pool_referrer_param21_value Pool Param 21 Value The value for parameter 21
dynamic_number_pool_referrer_param22_name Pool Param 22 Name The name for parameter 22
dynamic_number_pool_referrer_param22_value Pool Param 22 Value The value for parameter 22
dynamic_number_pool_referrer_param23_name Pool Param 23 Name The name for parameter 23
dynamic_number_pool_referrer_param23_value Pool Param 23 Value The value for parameter 23
dynamic_number_pool_referrer_param24_name Pool Param 24 Name The name for parameter 24
dynamic_number_pool_referrer_param24_value Pool Param 24 Value The value for parameter 24
dynamic_number_pool_referrer_param25_name Pool Param 25 Name The name for parameter 25
dynamic_number_pool_referrer_param25_value Pool Param 25 Value The value for parameter 25
dynamic_number_pool_referrer_search_engine Traffic Source Search engine used.
dynamic_number_pool_referrer_search_keywords Keywords Search keywords used
dynamic_number_pool_referrer_search_type Search Type Paid or Organic.
AdWords Parameters
Field Name in Reports Description
dynamic_number_pool_referrer_ad AdWords Ad AdWords Ad Headline copy, provided by Google
dynamic_number_pool_referrer_ad_group AdWords Ad Group AdWords Ad Group name, provided by Google
dynamic_number_pool_referrer_ad_group_id AdWords Ad Group ID AdWords Ad Group ID, provided by Google
dynamic_number_pool_referrer_ad_id AdWords Ad ID AdWords Ad ID, provided by Google
dynamic_number_pool_referrer_referrer_campaign AdWords Campaign AdWords Campaign name, provided by Google
dynamic_number_pool_referrer_referrer_campaign_id AdWords Campaign ID AdWords Campaign ID, provided by Google
dynamic_number_pool_referrer_search_keywords_id AdWords Keywords ID AdWords Keyword ID, provided by Google
Conversion Reporting Parameters
Field Name in Reports Description
address1 Address (Reported) Customer’s street address as given to the call center (first line).
address2 Address 2 (Reported) Customer’s street address as given to the call center (second line).
cell_phone_number Cell Phone (Reported) Customer’s cell phone number as given to the call center.
country Country (Reported) Customer’s country as given to the call center.
email_address Email Address (Reported) Email address as given to the call center.
home_phone_number Home Phone (Reported) Customer’s home phone number as given to the call center.
name Name (Reported) Customer’s full name as given to the call center.
order_city City (Reported) Customer’s city as given to the call center.
quantity_list Quantity List Comma-separated list of order quantities as reported by the call center. Each quantity in the list matches the sku_list entry in that same position.
reason_code Reason Code Call center-specific status code giving the disposition of the call.
sale_amount Sale Amount Total order amount (not including shipping) as reported by the call center.
sku_list SKU List Comma-separated list of order SKUs as reported by the call center.
state_or_province State or Province (Reported) Customer’s state or province as given to the call center.
zip_code Zip Code (Reported) Customer’s zip code as given to the call center.
Signal Parameters
signal_name Signal Name The name describing the signal event.
signal_description Signal Description Free form text for providing additional details about the signal.
signal_partner_unique_id Signal Partner ID Unique identifier, to distinguish between updating an existing signal (for example correcting a sale that was reported) versus adding a second sale to the call (for example a reservation made while on the call and then an add on item purchased later).
signal_occurred_at Signal Occurred At 10 digit time that the signal occurred, in UTC seconds since 1/1/70, also known as Unix time_t.
signal_source Signal Source The source of the signal. Possible values are :UserOverride, :Api, :Import, :Expression, :Ivr, and :Machine
signal_value Signal Value True or false as to whether or not the signal was met and null if it is not a signal transaction.
Voice Signal Parameters
Field Name in Reports Description
signal_1_value Voice Signal: Credit Card Voice Signals are configurable metrics that are tracked across calls, configured with rules about when the Voice Signal is met (1 if Voice Signal is met, 0 if Voice Signal was applied to the call but not met, null if Voice Signal was not applied to call)
signal_2_value Voice Signal: Competitors Voice Signals are configurable metrics that are tracked across calls, configured with rules about when the Voice Signal is met (1 if Voice Signal is met, 0 if Voice Signal was applied to the call but not met, null if Voice Signal was not applied to call)
signal_3_value Voice Signal: Rack Server Voice Signals are configurable metrics that are tracked across calls, configured with rules about when the Voice Signal is met (1 if Voice Signal is met, 0 if Voice Signal was applied to the call but not met, null if Voice Signal was not applied to call)
signal_4_value Voice Signal: Blade Server Voice Signals are configurable metrics that are tracked across calls, configured with rules about when the Voice Signal is met (1 if Voice Signal is met, 0 if Voice Signal was applied to the call but not met, null if Voice Signal was not applied to call)
signal_5_value Voice Signal: Power Play Voice Signals are configurable metrics that are tracked across calls, configured with rules about when the Voice Signal is met (1 if Voice Signal is met, 0 if Voice Signal was applied to the call but not met, null if Voice Signal was not applied to call)
signal_6_value Voice Signal: Amazon Voice Signals are configurable metrics that are tracked across calls, configured with rules about when the Voice Signal is met (1 if Voice Signal is met, 0 if Voice Signal was applied to the call but not met, null if Voice Signal was not applied to call)
signal_7_value Voice Signal: 7 Voice Signals are configurable metrics that are tracked across calls, configured with rules about when the Voice Signal is met (1 if Voice Signal is met, 0 if Voice Signal was applied to the call but not met, null if Voice Signal was not applied to call)
signal_8_value Voice Signal: Competitors Voice Signals are configurable metrics that are tracked across calls, configured with rules about when the Voice Signal is met (1 if Voice Signal is met, 0 if Voice Signal was applied to the call but not met, null if Voice Signal was not applied to call)
signal_9_value Voice Signal: 9 Voice Signals are configurable metrics that are tracked across calls, configured with rules about when the Voice Signal is met (1 if Voice Signal is met, 0 if Voice Signal was applied to the call but not met, null if Voice Signal was not applied to call)
signal_10_value Voice Signal: 10 Voice Signals are configurable metrics that are tracked across calls, configured with rules about when the Voice Signal is met (1 if Voice Signal is met, 0 if Voice Signal was applied to the call but not met, null if Voice Signal was not applied to call)
Enhanced Caller Profile Parameters
Field Name in Reports Description
address_city_data_append City (Data Append) Data from caller demographics lookup
address_country_data_append Country (Data Append) Data from caller demographics lookup
address_full_street_data_append Street Address (Data Append) Data from caller demographics lookup
address_state_data_append State (Data Append) Data from caller demographics lookup
address_type_data_append Address Type (Data Append) Data from caller demographics lookup
address_zip_data_append Zip (Data Append) Data from caller demographics lookup
age_range_data_append Age Range (Data Append) Data from caller demographics lookup
carrier_data_append Carrier (Data Append) Data from caller demographics lookup
display_name_data_append Display Name (Data Append) Data from caller demographics lookup
do_not_call_data_append Do Not Call (Data Append) Data from caller demographics lookup
first_name_data_append First Name (Data Append) Data from caller demographics lookup
gender_data_append Gender (Data Append) Data from caller demographics lookup
is_prepaid_data_append Is Prepaid (Data Append) Data from caller demographics lookup
last_name_data_append Last Name (Data Append) Data from caller demographics lookup
line_type_data_append Line Type (Data Append) Data from caller demographics lookup
Additional Feature Parameters
Field Name in Reports Description
affiliate_campaign_id_from_network Affiliate Campaign ID The Campaign ID from the network as set on the affiliate campaign.
promo_line_description Promo Number Description Additional details about the transaction source

Example

For example, if you have this OAuth API token:

OAuth API token
YbcFHZ38FNfptfZMB0RZ6dk9dOJCaCfU

Here is an example using curl to get the next 20 transactions that occurred after transaction id C624DA2C-CF3367C3:

curl -k "https://mynetwork.invoca.net/networks/transactions/33.csv?limit=20&start_after_transaction_id=C624DA2C-CF3367C3&oauth_token=YbcFHZ38FNfptfZMB0RZ6dk9dOJCaCfU"

The -k option asks curl to not bother checking the SSL certificate authority chain as that requires extra configuration.

Example 4: Get All Transactions from a specific time period that are of transaction_type Signal:

curl -k 'https://mynetwork.invoca.net/api/2016-01-25/networks/transactions/33.csv?transaction_type=Signal&from=2015-03-24&to=2015-03-27&oauth_token=YbcFH'

Example 5: Get All Transactions from a specific time period that are of transaction_type Post Call Event:

curl -k 'https://mynetwork.invoca.net/api/2016-01-25/networks/transactions/33.csv?transaction_type=PostCallEvent&from=2015-03-24&to=2015-03-27&oauth_token=YbcFH'

Example 6: Get All Transactions from a specific time period that are of transaction_type Call and Signal:

curl -k 'https://mynetwork.invoca.net/api/2016-01-25/networks/transactions/33.csv?transaction_type[]=Call&transaction_type[]=Signal&from=2015-03-24&to=2015-03-27&oauth_token=YbcFH'

Endpoint:

https://invoca.net/api/2016-01-25/networks/transactions/

Advertiser / Merchant

URL

The API follows REST conventions. Perform an HTTPS GET to the URL with the format in which you’d like to receive data. The following response formats are supported, where 33 is the advertiser id.

Format Description and URL
csv Comma-Separated Values, or really Anything-Separated Values (see column_separator= below). Returns an optional header row followed by one row for each transaction, with delimited values for each row. https://mynetwork.invoca.net/api/2016-01-25/advertisers/transactions/33.csv
xml Returns an XML document with an array of Transaction elements. https://mynetwork.invoca.net/api/2016-01-25/advertisers/transactions/33.xml
json Returns a JSON array of transaction objects. https://mynetwork.invoca.net/api/2016-01-25/advertisers/transactions/33.json

Authentication

The API uses OAuth Authentication to authenticate that access is allowed. Pass the OAuth Token like any other query parameter, however, please note that the OAuth token is a required parameter. OAuth Tokens may be generated from the Manage API Credentials page.

Query Parameters

The API takes the following optional query parameters:

Parameter Description
from= Starting date in user’s time zone, in format YYYY-MM-DD. Example: 2011-06-01. Inclusive.
to= Ending date in user’s time zone, in format YYYY-MM-DD. Example: 2011-06-07. Inclusive.
limit= Max number of transactions to return at a time. Defaults to 1000. Limited to at most 4000.
start_after_transaction_id= Transaction_id to start retrieving after. This should be the last value retrieved previously. Default (or empty string) means start at the oldest.
column_separator= [.csv format only] Separator between columns. Default is , for comma-separated values. (Can be set to any other separator like | for pipe-separated values or %09 for tab-separated values.)
row_separator= [.csv format only] Separator between lines. Defaults to %0A for n (line feed). Use %0D%0A for rn (carriage return + line feed).
include_header= [.csv format only] 1 to include a header row; 0 to omit the header row. Default is 1.
force_quotes= [.csv format only] 1 to quote all CSV fields; 0 to only quote fields that contain separators. Default is 0.
transaction_type= Filters for the type of transaction. Valid inputs are Call, PostCallEvent, Sale, or Signal. Sale maps to the Reported Conversion type.

In order to ensure that all transactions are returned when using the from= and to= date query parameters, you should store the last transaction id you have downloaded and pass it as the start_after_transaction_id to the next request. Typical usage on the polling interval is to repeatedly call the API until no rows are returned, meaning you have downloaded all transactions. Please note, the “to” and “from” date range parameters are both necessary, providing only one or the other will not filter the results.

Example:

Send request 1:

https://yourcompany.invoca.net/api/2016-01-25/advertisers/transactions/706.csv?limit=500&oauth_token=<YOUR_OAUTH_TOKEN>&from=2015-03-26&to=2015-03-27

returns 500 rows, grab the last transaction_id (in this example 500) and send request 2:

https://yourcompany.invoca.net/api/2016-01-25/advertisers/transactions/706.csv?limit=500&oauth_token=<YOUR_OAUTH_TOKEN>U&from=2015-03-26&to=2015-03-27&start_after_transaction_id=500

then repeat as necessary to get all call records within date range.

Response

The data returned has the following fields:

Field Name in Reports Description
advertiser_campaign_id Advertiser Campaign ID (Invoca ID) The Invoca identifier of the campaign.
advertiser_campaign_id_from_network Advertiser Campaign ID The Campaign ID from the network as set on the advertiser campaign.
advertiser_campaign_name Advertiser Campaign Name of the campaign.
advertiser_payin_localized Earned Amount paid in by advertiser
advertiser_promo_line_description Promo Number Description Additional details about the transaction source
affiliate_call_volume_ranking Affiliate Volume Ranking Network ranking of affiliate’s call volume (0 to 5, and -1 being ‘new’). Blank if no affiliate.
affiliate_commissions_ranking Affiliate Commissions Ranking Network ranking of affiliate’s commissions (0 to 5, and -1 being ‘new’). Blank if no affiliate.
affiliate_conversion_rate_ranking Affiliate Conversion Rate Ranking Network ranking of affiliate’s conversion rate (0 to 5, and -1 being ‘new’). Blank if no affiliate.
affiliate_id Affiliate ID (Invoca ID) The Invoca identifier of the affiliate
affiliate_id_from_network Affiliate ID Affiliate ID from the network as set on the Invoca affiliate.
affiliate_name Affiliate Name of the affiliate
call_result_description_detail_managed_advertiser Call Result Status of the transaction
call_source_description Source Source of the transaction
calling_phone_number Caller ID Caller ID. Formatted as 12 characters like 866-555-1234
city City City where transaction originated
complete_call_id Call Record ID Globally unique identifier for the call this transaction is part of. Up-to 32 character string, can contain alphanumeric characters (i.e. 0-9A-Z) and the -.
connect_duration Connected Duration (HH:MM:SS) Duration in seconds that the call that was connected to the call center.
corrected_at Corrected At [Correction only] Date and time the transaction was corrected, in user’s time zone, followed by offset from GMT.
corrects_transaction_id Corrects Call [Correction only] Id of the original transaction that this transaction updates. Values in this row are the corrected ones and should replace the original values. Same format as transaction_id. Up-to 32 character string, can contain alphanumeric characters (i.e. 0-9A-Z) and the -.
destination_phone_number Destination Phone Number The phone number where the call was transferred to (useful if an IVR transfers to multiple destinations). Up-to 20 character string, can contain numeric characters (i.e. 0-9) and the following additional characters: ‘-‘, ‘#’, ‘*’, ‘x’, and ‘,’. ‘
duration Total Duration (HH:MM:SS) Duration of the call in seconds. Includes any time spent in an IVR tree before transferring to the call center.
ivr_duration IVR Duration (HH:MM:SS) Duration in seconds that the call spent in the IVR tree.
keypress_1 Key 1 Name of the first key that was pressed
keypress_2 Key 2 Name of the second key that was pressed
keypress_3 Key 3 Name of the third key that was pressed
keypress_4 Key 4 Name of the fourth key that was pressed
keypresses Keypresses List of unique keynames that were pressed during the call
matching_advertiser_payin_policies Matching Advertiser Payin Policies List of advertiser policies that matched (base, bonus1, bonus2, etc.) to determine the advertiser payin, separated by +. For example, base+bonus1+bonus3. Note that if there was any advertiser payin, this field guaranteed to start with base.
media_type Media Type Media type of the transaction source
mobile Phone Type Landline or Mobile or empty string if type is unknown
notes Notes Free-form notations on transaction
opt_in_SMS Opt In Sms Whether the caller opted in to receive an SMS promotion.
original_order_id Order ID [Sales reporting only] Id of the original transaction that this row is in reference to. Up-to 32 character string, can contain alphanumeric characters (i.e. 0-9A-Z) and the -.
payin_conditions Payin Conditions Base condition with highlighting around the term(s) that disqualified advertiser payin. For example: duration > 1 min and in_region
qualified_regions Qualified Regions The list of regions that that the caller matched
recording Recording URL to the call recording, if available
region Region Region (state, province or country) where transaction originated
repeat_calling_phone_number Repeat Caller Whether the call was a repeat call. Repeat call detection is not applied to shared or unavailable caller ids.
start_time_local Call Start Time Start of the call in the API user’s time zone, followed by offset from GMT.
start_time_utc Call Start Time (UTC timestamp) Start of the call in milliseconds since Jan 1, 1970. Divide by 1000 to get Unix epoch time.
start_time_xml Call Start Time (XML formatted) Start of the call in Soap XML formatted time.
syndicated_ident Syndicated ID The syndicated id for this call. Uniquely identifies syndication sources for a campaign.
transaction_id Transaction ID Globally unique identifier for this transaction. Up-to 32 character string, can contain alphanumeric characters (i.e. 0-9A-Z) and the -. This is the Primary Key of the results.
transaction_type Type The type of transaction - Call, Post Call Event, Reported Conversion, or Signal.
transfer_from_type Transfer Type Where the call came from
verified_zip Verified Zip Code Zip Code entered by callers when prompted during call treatment
virtual_line_id Promo Number ID The Promo Number ID from the network

Optional Parameters

The following fields are optional based on your account type:

RingPool Parameters
Field Name in Reports Description
dynamic_number_pool_id Pool ID The ID of the pool.
dynamic_number_pool_pool_type Pool Type The type of pool: Search, SearchKeyword or Custom
dynamic_number_pool_referrer_param1_name Pool Param 1 Name The name for parameter 1
dynamic_number_pool_referrer_param1_value Pool Param 1 Value The value for parameter 1
dynamic_number_pool_referrer_param2_name Pool Param 2 Name The name for parameter 2
dynamic_number_pool_referrer_param2_value Pool Param 2 Value The value for parameter 2
dynamic_number_pool_referrer_param3_name Pool Param 3 Name The name for parameter 3
dynamic_number_pool_referrer_param3_value Pool Param 3 Value The value for parameter 3
dynamic_number_pool_referrer_param4_name Pool Param 4 Name The name for parameter 4
dynamic_number_pool_referrer_param4_value Pool Param 4 Value The value for parameter 4
dynamic_number_pool_referrer_param5_name Pool Param 5 Name The name for parameter 5
dynamic_number_pool_referrer_param5_value Pool Param 5 Value The value for parameter 5
dynamic_number_pool_referrer_param6_name Pool Param 6 Name The name for parameter 6
dynamic_number_pool_referrer_param6_value Pool Param 6 Value The value for parameter 6
dynamic_number_pool_referrer_param7_name Pool Param 7 Name The name for parameter 7
dynamic_number_pool_referrer_param7_value Pool Param 7 Value The value for parameter 7
dynamic_number_pool_referrer_param8_name Pool Param 8 Name The name for parameter 8
dynamic_number_pool_referrer_param8_value Pool Param 8 Value The value for parameter 8
dynamic_number_pool_referrer_param9_name Pool Param 9 Name The name for parameter 9
dynamic_number_pool_referrer_param9_value Pool Param 9 Value The value for parameter 9
dynamic_number_pool_referrer_param10_name Pool Param 10 Name The name for parameter 10
dynamic_number_pool_referrer_param10_value Pool Param 10 Value The value for parameter 10
dynamic_number_pool_referrer_param11_name Pool Param 11 Name The name for parameter 11
dynamic_number_pool_referrer_param11_value Pool Param 11 Value The value for parameter 11
dynamic_number_pool_referrer_param12_name Pool Param 12 Name The name for parameter 12
dynamic_number_pool_referrer_param12_value Pool Param 12 Value The value for parameter 12
dynamic_number_pool_referrer_param13_name Pool Param 13 Name The name for parameter 13
dynamic_number_pool_referrer_param13_value Pool Param 13 Value The value for parameter 13
dynamic_number_pool_referrer_param14_name Pool Param 14 Name The name for parameter 14
dynamic_number_pool_referrer_param14_value Pool Param 14 Value The value for parameter 14
dynamic_number_pool_referrer_param15_name Pool Param 15 Name The name for parameter 15
dynamic_number_pool_referrer_param15_value Pool Param 15 Value The value for parameter 15
dynamic_number_pool_referrer_param16_name Pool Param 16 Name The name for parameter 16
dynamic_number_pool_referrer_param16_value Pool Param 16 Value The value for parameter 16
dynamic_number_pool_referrer_param17_name Pool Param 17 Name The name for parameter 17
dynamic_number_pool_referrer_param17_value Pool Param 17 Value The value for parameter 17
dynamic_number_pool_referrer_param18_name Pool Param 18 Name The name for parameter 18
dynamic_number_pool_referrer_param18_value Pool Param 18 Value The value for parameter 18
dynamic_number_pool_referrer_param19_name Pool Param 19 Name The name for parameter 19
dynamic_number_pool_referrer_param19_value Pool Param 19 Value The value for parameter 19
dynamic_number_pool_referrer_param20_name Pool Param 20 Name The name for parameter 20
dynamic_number_pool_referrer_param20_value Pool Param 20 Value The value for parameter 20
dynamic_number_pool_referrer_param21_name Pool Param 21 Name The name for parameter 21
dynamic_number_pool_referrer_param21_value Pool Param 21 Value The value for parameter 21
dynamic_number_pool_referrer_param22_name Pool Param 22 Name The name for parameter 22
dynamic_number_pool_referrer_param22_value Pool Param 22 Value The value for parameter 22
dynamic_number_pool_referrer_param23_name Pool Param 23 Name The name for parameter 23
dynamic_number_pool_referrer_param23_value Pool Param 23 Value The value for parameter 23
dynamic_number_pool_referrer_param24_name Pool Param 24 Name The name for parameter 24
dynamic_number_pool_referrer_param24_value Pool Param 24 Value The value for parameter 24
dynamic_number_pool_referrer_param25_name Pool Param 25 Name The name for parameter 25
dynamic_number_pool_referrer_param25_value Pool Param 25 Value The value for parameter 25
dynamic_number_pool_referrer_search_engine Traffic Source Search engine used.
dynamic_number_pool_referrer_search_keywords Keywords Search keywords used
dynamic_number_pool_referrer_search_type Search Type Paid or Organic.
AdWords Parameters
Field Name in Reports Description
dynamic_number_pool_referrer_ad AdWords Ad AdWords Ad Headline copy, provided by Google
dynamic_number_pool_referrer_ad_group AdWords Ad Group AdWords Ad Group name, provided by Google
dynamic_number_pool_referrer_ad_group_id AdWords Ad Group ID AdWords Ad Group ID, provided by Google
dynamic_number_pool_referrer_ad_id AdWords Ad ID AdWords Ad ID, provided by Google
dynamic_number_pool_referrer_referrer_campaign AdWords Campaign AdWords Campaign name, provided by Google
dynamic_number_pool_referrer_referrer_campaign_id AdWords Campaign ID AdWords Campaign ID, provided by Google
dynamic_number_pool_referrer_search_keywords_id AdWords Keywords ID AdWords Keyword ID, provided by Google
Conversion Reporting Parameters
Field Name in Reports Description
address1 Address (Reported) Customer’s street address as given to the call center (first line).
address2 Address 2 (Reported) Customer’s street address as given to the call center (second line).
cell_phone_number Cell Phone (Reported) Customer’s cell phone number as given to the call center.
country Country (Reported) Customer’s country as given to the call center.
email_address Email Address (Reported) Email address as given to the call center.
home_phone_number Home Phone (Reported) Customer’s home phone number as given to the call center.
name Name (Reported) Customer’s full name as given to the call center.
order_city City (Reported) Customer’s city as given to the call center.
quantity_list Quantity List Comma-separated list of order quantities as reported by the call center. Each quantity in the list matches the sku_list entry in that same position.
reason_code Reason Code Call center-specific status code giving the disposition of the call.
sale_amount Sale Amount Total order amount (not including shipping) as reported by the call center.
sku_list SKU List Comma-separated list of order SKUs as reported by the call center.
state_or_province State or Province (Reported) Customer’s state or province as given to the call center.
zip_code Zip Code (Reported) Customer’s zip code as given to the call center.
Signal Parameters
signal_name Signal Name The name describing the signal event.
signal_description Signal Description Free form text for providing additional details about the signal.
signal_partner_unique_id Signal Partner ID Unique identifier, to distinguish between updating an existing signal (for example correcting a sale that was reported) versus adding a second sale to the call (for example a reservation made while on the call and then an add on item purchased later).
signal_occurred_at Signal Occurred At 10 digit time that the signal occurred, in UTC seconds since 1/1/70, also known as Unix time_t.
signal_source Signal Source The source of the signal. Possible values are :UserOverride, :Api, :Import, :Expression, :Ivr, and :Machine
signal_value Signal Value True or false as to whether or not the signal was met and null if it is not a signal transaction.
Voice Signal Parameters
Field Name in Reports Description
signal_1_value Voice Signal: Credit Card Voice Signals are configurable metrics that are tracked across calls, configured with rules about when the Voice Signal is met (1 if Voice Signal is met, 0 if Voice Signal was applied to the call but not met, null if Voice Signal was not applied to call)
signal_2_value Voice Signal: Competitors Voice Signals are configurable metrics that are tracked across calls, configured with rules about when the Voice Signal is met (1 if Voice Signal is met, 0 if Voice Signal was applied to the call but not met, null if Voice Signal was not applied to call)
signal_3_value Voice Signal: Rack Server Voice Signals are configurable metrics that are tracked across calls, configured with rules about when the Voice Signal is met (1 if Voice Signal is met, 0 if Voice Signal was applied to the call but not met, null if Voice Signal was not applied to call)
signal_4_value Voice Signal: Blade Server Voice Signals are configurable metrics that are tracked across calls, configured with rules about when the Voice Signal is met (1 if Voice Signal is met, 0 if Voice Signal was applied to the call but not met, null if Voice Signal was not applied to call)
signal_5_value Voice Signal: Power Play Voice Signals are configurable metrics that are tracked across calls, configured with rules about when the Voice Signal is met (1 if Voice Signal is met, 0 if Voice Signal was applied to the call but not met, null if Voice Signal was not applied to call)
signal_6_value Voice Signal: Amazon Voice Signals are configurable metrics that are tracked across calls, configured with rules about when the Voice Signal is met (1 if Voice Signal is met, 0 if Voice Signal was applied to the call but not met, null if Voice Signal was not applied to call)
signal_7_value Voice Signal: 7 Voice Signals are configurable metrics that are tracked across calls, configured with rules about when the Voice Signal is met (1 if Voice Signal is met, 0 if Voice Signal was applied to the call but not met, null if Voice Signal was not applied to call)
signal_8_value Voice Signal: Competitors Voice Signals are configurable metrics that are tracked across calls, configured with rules about when the Voice Signal is met (1 if Voice Signal is met, 0 if Voice Signal was applied to the call but not met, null if Voice Signal was not applied to call)
signal_9_value Voice Signal: 9 Voice Signals are configurable metrics that are tracked across calls, configured with rules about when the Voice Signal is met (1 if Voice Signal is met, 0 if Voice Signal was applied to the call but not met, null if Voice Signal was not applied to call)
signal_10_value Voice Signal: 10 Voice Signals are configurable metrics that are tracked across calls, configured with rules about when the Voice Signal is met (1 if Voice Signal is met, 0 if Voice Signal was applied to the call but not met, null if Voice Signal was not applied to call)
Additional Feature Parameters
Field Name in Reports Description
advertiser_call_fee_localized Fees Advertiser Telecommunications fee associated with transaction
affiliate_campaign_id_from_network Affiliate Campaign ID The Campaign ID from the network as set on the affiliate campaign.
margin_localized Margin Difference between advertiser_payin_localized and affiliate_payout_localized
promo_line_description Promo Number Description Additional details about the transaction source

Example

For example, if you have this OAuth API token:

OAuth API token
YbcFHZ38FNfptfZMB0RZ6dk9dOJCaCfU

Here is an example using curl to get the next 20 transactions that occurred after transaction id C624DA2C-CF3367C3:

curl -k "https://mynetwork.invoca.net/advertisers/transactions/33.csv?limit=20&start_after_transaction_id=C624DA2C-CF3367C3&oauth_token=YbcFHZ38FNfptfZMB0RZ6dk9dOJCaCfU"

The -k option asks curl to not bother checking the SSL certificate authority chain as that requires extra configuration.

Example 4: Get All Transactions from a specific time period that are of transaction_type Signal:

curl -k 'https://mynetwork.invoca.net/api/2016-01-25/advertisers/transactions/33.csv?transaction_type=Signal&from=2015-03-24&to=2015-03-27&oauth_token=YbcFH'

Example 5: Get All Transactions from a specific time period that are of transaction_type Post Call Event:

curl -k 'https://mynetwork.invoca.net/api/2016-01-25/advertisers/transactions/33.csv?transaction_type=PostCallEvent&from=2015-03-24&to=2015-03-27&oauth_token=YbcFH'

Example 6: Get All Transactions from a specific time period that are of transaction_type Call and Signal:

curl -k 'https://mynetwork.invoca.net/api/2016-01-25/advertisers/transactions/33.csv?transaction_type[]=Call&transaction_type[]=Signal&from=2015-03-24&to=2015-03-27&oauth_token=YbcFH'

Endpoint:

https://invoca.net/api/2016-01-25/advertisers/transactions/

Publisher / Affiliate

URL

The API follows REST conventions. Perform an HTTPS GET to the URL with the format in which you’d like to receive data. The following response formats are supported, where 33 is the affiliate id.

Format Description and URL
csv Comma-Separated Values, or really Anything-Separated Values (see column_separator= below). Returns an optional header row followed by one row for each transaction, with delimited values for each row. https://mynetwork.invoca.net/api/2016-01-25/affiliates/transactions/33.csv
xml Returns an XML document with an array of Transaction elements. https://mynetwork.invoca.net/api/2016-01-25/affiliates/transactions/33.xml
json Returns a JSON array of transaction objects. https://mynetwork.invoca.net/api/2016-01-25/affiliates/transactions/33.json

Authentication

The API uses OAuth Authentication to authenticate that access is allowed. Pass the OAuth Token like any other query parameter, however, please note that the OAuth token is a required parameter. OAuth Tokens may be generated from the Manage API Credentials page.

Query Parameters

The API takes the following optional query parameters:

Parameter Description
from= Starting date in user’s time zone, in format YYYY-MM-DD. Example: 2011-06-01. Inclusive.
to= Ending date in user’s time zone, in format YYYY-MM-DD. Example: 2011-06-07. Inclusive.
limit= Max number of transactions to return at a time. Defaults to 1000. Limited to at most 4000.
start_after_transaction_id= Transaction_id to start retrieving after. This should be the last value retrieved previously. Default (or empty string) means start at the oldest.
column_separator= [.csv format only] Separator between columns. Default is , for comma-separated values. (Can be set to any other separator like | for pipe-separated values or %09 for tab-separated values.)
row_separator= [.csv format only] Separator between lines. Defaults to %0A for n (line feed). Use %0D%0A for rn (carriage return + line feed).
include_header= [.csv format only] 1 to include a header row; 0 to omit the header row. Default is 1.
force_quotes= [.csv format only] 1 to quote all CSV fields; 0 to only quote fields that contain separators. Default is 0.
transaction_type= Filters for the type of transaction. Valid inputs are Call, PostCallEvent, Sale, or Signal. Sale maps to the Reported Conversion type.

In order to ensure that all transactions are returned when using the from= and to= date query parameters, you should store the last transaction id you have downloaded and pass it as the start_after_transaction_id to the next request. Typical usage on the polling interval is to repeatedly call the API until no rows are returned, meaning you have downloaded all transactions. Please note, the “to” and “from” date range parameters are both necessary, providing only one or the other will not filter the results.

Example:

Send request 1:

https://yourcompany.invoca.net/api/2016-01-25/affiliates/transactions/706.csv?limit=500&oauth_token=<YOUR_OAUTH_TOKEN>&from=2015-03-26&to=2015-03-27

returns 500 rows, grab the last transaction_id (in this example 500) and send request 2:

https://yourcompany.invoca.net/api/2016-01-25/affiliates/transactions/706.csv?limit=500&oauth_token=<YOUR_OAUTH_TOKEN>U&from=2015-03-26&to=2015-03-27&start_after_transaction_id=500

then repeat as necessary to get all call records within date range.

Response

The data returned has the following fields:

Field Name in Reports Description
advertiser_campaign_id Advertiser Campaign ID (Invoca ID) The Invoca identifier of the campaign.
advertiser_campaign_id_from_network Advertiser Campaign ID The Campaign ID from the network as set on the advertiser campaign.
advertiser_campaign_name Advertiser Campaign Name of the campaign.
advertiser_id Advertiser ID (Invoca ID) The Invoca identifier of the advertiser
advertiser_id_from_network Advertiser ID Advertiser ID from the network as set on the Invoca advertiser.
advertiser_name Advertiser Name of the advertiser.
affiliate_payout_localized Earnings Amount paid out to the affiliate
call_result_description_detail Call Result Status of the transaction
call_source_description Source Source of the transaction
city City City where transaction originated
complete_call_id Call Record ID Globally unique identifier for the call this transaction is part of. Up-to 32 character string, can contain alphanumeric characters (i.e. 0-9A-Z) and the -.
connect_duration Connected Duration (HH:MM:SS) Duration in seconds that the call that was connected to the call center.
corrected_at Corrected At [Correction only] Date and time the transaction was corrected, in user’s time zone, followed by offset from GMT.
corrects_transaction_id Corrects Call [Correction only] Id of the original transaction that this transaction updates. Values in this row are the corrected ones and should replace the original values. Same format as transaction_id. Up-to 32 character string, can contain alphanumeric characters (i.e. 0-9A-Z) and the -.
duration Total Duration (HH:MM:SS) Duration of the call in seconds. Includes any time spent in an IVR tree before transferring to the call center.
ivr_duration IVR Duration (HH:MM:SS) Duration in seconds that the call spent in the IVR tree.
keypress_1 Key 1 Name of the first key that was pressed
keypress_2 Key 2 Name of the second key that was pressed
keypress_3 Key 3 Name of the third key that was pressed
keypress_4 Key 4 Name of the fourth key that was pressed
keypresses Keypresses List of unique keynames that were pressed during the call
matching_affiliate_payout_policies Matching Affiliate Payout Policies List of affiliate policies that matched (base, bonus1, bonus2, etc.) to determine the affiliate payout, separated by +. For example, base+bonus2. Note that if there was any affiliate payout, this field guaranteed to start with base.
media_type Media Type Media type of the transaction source
mobile Phone Type Landline or Mobile or empty string if type is unknown
notes Notes Free-form notations on transaction
opt_in_SMS Opt In Sms Whether the caller opted in to receive an SMS promotion.
original_order_id Order ID [Sales reporting only] Id of the original transaction that this row is in reference to. Up-to 32 character string, can contain alphanumeric characters (i.e. 0-9A-Z) and the -.
payout_conditions Payout Conditions Base condition with { highlighting } around the term(s) that disqualified affiliate payout. For example: duration > 1 min and {in_region}
promo_line_description Promo Number Description Additional details about the transaction source
qualified_regions Qualified Regions The list of regions that that the caller matched
region Region Region (state, province or country) where transaction originated
start_time_local Call Start Time Start of the call in the API user’s time zone, followed by offset from GMT.
start_time_utc Call Start Time (UTC timestamp) Start of the call in milliseconds since Jan 1, 1970. Divide by 1000 to get Unix epoch time.
start_time_xml Call Start Time (XML formatted) Start of the call in Soap XML formatted time.
syndicated_ident Syndicated ID The syndicated id for this call. Uniquely identifies syndication sources for a campaign.
transaction_id Transaction ID Globally unique identifier for this transaction. Up-to 32 character string, can contain alphanumeric characters (i.e. 0-9A-Z) and the -. This is the Primary Key of the results.
transaction_type Type The type of transaction - Call, Post Call Event, Reported Conversion, or Signal.
transfer_from_type Transfer Type Where the call came from
verified_zip Verified Zip Code Zip Code entered by callers when prompted during call treatment
virtual_line_id Promo Number ID The Promo Number ID from the network

Optional Parameters

The following fields are optional based on your account type:

RingPool Parameters
Field Name in Reports Description
dynamic_number_pool_id Pool ID The ID of the pool.
dynamic_number_pool_pool_type Pool Type The type of pool: Search, SearchKeyword or Custom
dynamic_number_pool_referrer_param1_name Pool Param 1 Name The name for parameter 1
dynamic_number_pool_referrer_param1_value Pool Param 1 Value The value for parameter 1
dynamic_number_pool_referrer_param2_name Pool Param 2 Name The name for parameter 2
dynamic_number_pool_referrer_param2_value Pool Param 2 Value The value for parameter 2
dynamic_number_pool_referrer_param3_name Pool Param 3 Name The name for parameter 3
dynamic_number_pool_referrer_param3_value Pool Param 3 Value The value for parameter 3
dynamic_number_pool_referrer_param4_name Pool Param 4 Name The name for parameter 4
dynamic_number_pool_referrer_param4_value Pool Param 4 Value The value for parameter 4
dynamic_number_pool_referrer_param5_name Pool Param 5 Name The name for parameter 5
dynamic_number_pool_referrer_param5_value Pool Param 5 Value The value for parameter 5
dynamic_number_pool_referrer_param6_name Pool Param 6 Name The name for parameter 6
dynamic_number_pool_referrer_param6_value Pool Param 6 Value The value for parameter 6
dynamic_number_pool_referrer_param7_name Pool Param 7 Name The name for parameter 7
dynamic_number_pool_referrer_param7_value Pool Param 7 Value The value for parameter 7
dynamic_number_pool_referrer_param8_name Pool Param 8 Name The name for parameter 8
dynamic_number_pool_referrer_param8_value Pool Param 8 Value The value for parameter 8
dynamic_number_pool_referrer_param9_name Pool Param 9 Name The name for parameter 9
dynamic_number_pool_referrer_param9_value Pool Param 9 Value The value for parameter 9
dynamic_number_pool_referrer_param10_name Pool Param 10 Name The name for parameter 10
dynamic_number_pool_referrer_param10_value Pool Param 10 Value The value for parameter 10
dynamic_number_pool_referrer_param11_name Pool Param 11 Name The name for parameter 11
dynamic_number_pool_referrer_param11_value Pool Param 11 Value The value for parameter 11
dynamic_number_pool_referrer_param12_name Pool Param 12 Name The name for parameter 12
dynamic_number_pool_referrer_param12_value Pool Param 12 Value The value for parameter 12
dynamic_number_pool_referrer_param13_name Pool Param 13 Name The name for parameter 13
dynamic_number_pool_referrer_param13_value Pool Param 13 Value The value for parameter 13
dynamic_number_pool_referrer_param14_name Pool Param 14 Name The name for parameter 14
dynamic_number_pool_referrer_param14_value Pool Param 14 Value The value for parameter 14
dynamic_number_pool_referrer_param15_name Pool Param 15 Name The name for parameter 15
dynamic_number_pool_referrer_param15_value Pool Param 15 Value The value for parameter 15
dynamic_number_pool_referrer_param16_name Pool Param 16 Name The name for parameter 16
dynamic_number_pool_referrer_param16_value Pool Param 16 Value The value for parameter 16
dynamic_number_pool_referrer_param17_name Pool Param 17 Name The name for parameter 17
dynamic_number_pool_referrer_param17_value Pool Param 17 Value The value for parameter 17
dynamic_number_pool_referrer_param18_name Pool Param 18 Name The name for parameter 18
dynamic_number_pool_referrer_param18_value Pool Param 18 Value The value for parameter 18
dynamic_number_pool_referrer_param19_name Pool Param 19 Name The name for parameter 19
dynamic_number_pool_referrer_param19_value Pool Param 19 Value The value for parameter 19
dynamic_number_pool_referrer_param20_name Pool Param 20 Name The name for parameter 20
dynamic_number_pool_referrer_param20_value Pool Param 20 Value The value for parameter 20
dynamic_number_pool_referrer_param21_name Pool Param 21 Name The name for parameter 21
dynamic_number_pool_referrer_param21_value Pool Param 21 Value The value for parameter 21
dynamic_number_pool_referrer_param22_name Pool Param 22 Name The name for parameter 22
dynamic_number_pool_referrer_param22_value Pool Param 22 Value The value for parameter 22
dynamic_number_pool_referrer_param23_name Pool Param 23 Name The name for parameter 23
dynamic_number_pool_referrer_param23_value Pool Param 23 Value The value for parameter 23
dynamic_number_pool_referrer_param24_name Pool Param 24 Name The name for parameter 24
dynamic_number_pool_referrer_param24_value Pool Param 24 Value The value for parameter 24
dynamic_number_pool_referrer_param25_name Pool Param 25 Name The name for parameter 25
dynamic_number_pool_referrer_param25_value Pool Param 25 Value The value for parameter 25
dynamic_number_pool_referrer_search_engine Traffic Source Search engine used.
dynamic_number_pool_referrer_search_keywords Keywords Search keywords used
dynamic_number_pool_referrer_search_type Search Type Paid or Organic.
Additional Feature Parameters
Field Name in Reports Description
signal_name Signal Name The name describing the signal event.
external_data External Data Additional data associated with the transaction
recording Recording URL to the call recording, if available
calling_phone_number Caller ID Caller ID. Formatted as 12 characters like 866-555-1234
repeat_calling_phone_number Repeat Caller Whether the call was a repeat call. Repeat call detection is not applied to shared or unavailable caller ids.

Example

For example, if you have this OAuth API token:

OAuth API token
YbcFHZ38FNfptfZMB0RZ6dk9dOJCaCfU

Here is an example using curl to get the next 20 transactions that occurred after transaction id C624DA2C-CF3367C3:

curl -k "https://mynetwork.invoca.net/affiliates/transactions/33.csv?limit=20&start_after_transaction_id=C624DA2C-CF3367C3&oauth_token=YbcFHZ38FNfptfZMB0RZ6dk9dOJCaCfU"

The -k option asks curl to not bother checking the SSL certificate authority chain as that requires extra configuration.

Example 4: Get All Transactions from a specific time period that are of transaction_type Signal:

curl -k 'https://mynetwork.invoca.net/api/2016-01-25/affiliates/transactions/33.csv?transaction_type=Signal&from=2015-03-24&to=2015-03-27&oauth_token=YbcFH'

Example 5: Get All Transactions from a specific time period that are of transaction_type Post Call Event:

curl -k 'https://mynetwork.invoca.net/api/2016-01-25/affiliates/transactions/33.csv?transaction_type=PostCallEvent&from=2015-03-24&to=2015-03-27&oauth_token=YbcFH'

Example 6: Get All Transactions from a specific time period that are of transaction_type Call and Signal:

curl -k 'https://mynetwork.invoca.net/api/2016-01-25/affiliates/transactions/33.csv?transaction_type[]=Call&transaction_type[]=Signal&from=2015-03-24&to=2015-03-27&oauth_token=YbcFH'

Endpoint:

https://invoca.net/api/2016-01-25/affiliates/transactions/

Ringpool

The RingPool API allocates a dynamic, trackable promo phone number from a RingPool. A valid call to the RingPool API returns a promo number and a formatted click-through URL.

Example API URL:

https://<NETWORK>.invoca.net/api/2015-12-09/ring_pools/16/allocate_number.xml?ring_pool_key=<KEY>&site=<VALUE1>&location=<VALUE2>

<NETWORK>.invoca.net is the vanity URL for your platform. Note that your platform may exist on invoca.net or ringrevenue.com, and both are supported.

<RingPool_ID> is a unique identifier for the RingPool.

<KEY> is the RingPool key, which is provided through the RingPool wizard UI on the platform and should be kept a secret. The parameters are explained in detail below in the “API Parameters” section.

The parameter names should match those chosen in the RingPool wizard, or you can use generic parameter names “param1”, “param2”, etc. Here is the same API URL with the generic parameter names:

https://<NETWORK>.invoca.net/api/2015-12-09/ring_pools/16/allocate_number.xml?ring_pool_key=<KEY>&param1=<VALUE1>&param2=<VALUE2>

Note: To access the campaign RingPool’s API URL navigate to the Campaign Summary’s RingPool tab and click “get api url” under Actions.

_images/ringpool_actions.png
_images/ringpool_get_api_url.png

Response Formats

The response can be in any of these formats: xml, json or csv. To choose the format, change the “.xml” shown in the URL to “.json” or “.csv”. Below are example responses for each format:

xml

<?xml version="1.0" encoding="UTF-8"?>
<Response>
  <PromoNumberFormatted>888-390-6665</PromoNumberFormatted>
  <PromoNumber>8883906665</PromoNumber>
  <TrackingUrl> https://invoca.net/c/1/14-11-109?us=http%3A%2F%2Fwww2.invoca.net%2Fdemo%2F8x8_staging.html%3Fsid%3D8883906665%26PPCPN%3D8883906665</TrackingUrl>
</Response>

json

{"promo_number_formatted":"888-390-6665","tracking_url":" https://invoca.net/c/1/14-11-109?us=http%3A%2F%2Fwww2.invoca.net.com%2Fdemo%2F8x8_staging.html%3Fsid%3D8883906665%26PPCPN%3D8883906665","promo_number":"8883906665"}

csv

PromoNumberFormatted,PromoNumber,TrackingUrl
888-390-6665,8883906665, https://invoca.net/c/1/14-11-109?us=http%3A%2F%2Fwww2.invoca.net%2Fdemo%2F8x8_staging.html%3Fsid%3D8883906665%26PPCPN%3D8883906665

As an advertiser, you can allocate promo numbers from your RingPool on behalf of your affiliates in order to credit them for calls. Just include an affiliate id in the query string of the API URL. Note that the parameter name depends on your network and the value must match what is set on the affiliate account. Here is an example URL for tracking affiliate 5567 on a network that calls the affiliate id a pid:

https://<NETWORK>.invoca.net/api/2015-12-09/ring_pools/16/allocate_number.xml?ring_pool_key=<KEY>&pid=5567&sid=adwords

Errors

The RingPool API clearly identifies errors when a request can not be processed. If the number pool is exhausted, the API still succeeds because an overflow number is returned. If a parameter is not passed correctly, an XML error response is returned as shown below:

<?xml version="1.0" encoding="UTF-8"?>
<Error>
  <Class>InvalidKey</Class>
  <Message>API Key 'A329F4DC002168' is not valid for resource '1'</Message>
</Error>

Or for json or csv, the following text is returned:

InvalidKey: API Key ‘A329F4DC002168’ is not valid for resource ‘1’

If a system error occurs, an InternalServiceError is returned in XML (or simple text for json or csv) with an integer error handle. Contact questions@invoca.com to determine the root cause of the error.

RingPool Types

All 6 RingPool types are supported by the API:

Custom

Custom + Search keywords

Search Engine + Keywords

Search Engine + Keyword ID

Referral Domains

Referral Domains + search

API Parameters

The API supports the following parameters:

Parameter Description
ring_pool_key= The required authentication key unique for each RingPool.
param1= [Custom RingPools only] The first custom parameter of a Custom RingPool. This parameter can also be represented by the custom name.
param2= [Custom RingPools only] The second custom parameter of a Custom RingPool.
…  
param10= [Custom RingPools only] The 10th custom parameter of a Custom RingPool.
search_engine= [All Search RingPool types] The search engine name used to process the search query.
search_keywords= [All Search RingPool types] The search query that the user searched for.
search_keyword_id= [Keyword ID Search RingPool only] The keyword ID that is associated to the query string.
landing_page= [Optional] The landing page URL to be shown in reporting.
referrer= [All Referral Domain types, otherwise Optional] Can be used instead of search_engine= and search_keyword. Those values will be inferred by parsing the referrer URL. Referral Domains + search will use referrer as the Traffic Source if either the search_engine or search_keywords are omitted.
mobile_click_to_call= [Optional] Option to return mobile enabled links that populate the smartphone’s dialer when clicked.
<NETWORK_AFFILIATE_ID_NAME> [Optional] This parameter name is determined by the network and is used to allocate a promo number on behalf of the publisher. For example, pid=2341

Endpoint:

https://invoca.net/api/2015-12-09/ring_pools/16/allocate_number.xml?ring_pool_key=<KEY>&param1=<VALUE1>&param2=<VALUE2>

Bulk Ringpool API

Before using the Bulk RingPool API, contact questions@invoca.com to enable the Bulk RingPool API feature. It is recommended that before you enable the feature on your production platform, testing occurs on a demo or test platform.

Overview

The Bulk RingPool API is designed to efficiently handle a high volume of requests per second. A persistent connection is strongly recommended.

The Bulk RingPool API can be enabled on the Network, Advertiser, or Publisher level. Note that once enabled, all new or edited RingPools are served by the Bulk RingPool API and not the RingPool API. Therefore, if the Bulk RingPool API is enabled for your organization, attempting to access a RingPool with the RingPool API results in an error.

Finally, also note that only the custom RingPool type is supported by the Bulk RingPool API.

Example API URL:

POST https://pnapi.invoca.net/api/2013-07-01/bulk.json

Request Body

The JSON POST body of the request has a top level key “request” which maps to an array of hashes, where each hash contains a RingPool API URL. The array must contain at least one entry. The requests follow a similar format to the RingPool API, which can be found here.

Each hash in the array must contain a key/value pair with a key of “api_suffix”. The value must be the suffix of the RingPool API URL after /api/<date>.

At least one RingPool parameter must be present in each allocation request, even if the value is an empty string.

Each element may also include a key/value pair with a key of “request_id”. If provided, it is echoed in the response for context. This parameter is optional and does not have to be unique across the hashes.

Individual responses and request IDs are returned in the same order as the requests.

Below is an example of the JSON request body:

{
 "requests":[
  {"api_suffix":"<RING_POOL_ID>/allocate_number.json?ring_pool_key=<RING_POOL_KEY>&m1=autos&m2=ford","request_id":"193C5F"},
  {"api_suffix":"<RING_POOL_ID>/allocate_number.json?ring_pool_key=<RING_POOL_KEY>&m1=antiques","request_id":"58CD4F"},
  {"api_suffix":"<RING_POOL_ID>/allocate_number.json?ring_pool_key=<RING_POOL_KEY>&m1=electronics","request_id":"E3901B"}
 ]
}

Response Body

The response format is in JSON.

Below is an example response (whitespace added for clarity):

{
 "responses":[
  {"request_id":"193C5F","promo_number_formatted":"888-390-6665","promo_number":"8883906665","tracking_url":"http://ringrevenue.com/c/1/14-11-109?us=http%3A%2F%2Fwww2.ringrevenue.com.com%2Fdemo%2F8x8_staging.html%3Fsid%3D8883906665%26PPCPN%3D8883906665"},
  {"request_id":"58CD4F","promo_number_formatted":"877-455-1120","promo_number":"8774551120","tracking_url":"http://ringringrevenue.com/c/1/19-99-210?us=http%3A%2F%2Fwww2.ringrevenue.com%2Fdemo%2F8x8_staging.html%3Fsid%3D8774551120%26PPCPN%3D8774551120"},
  {"request_id":"E3901B","promo_number_formatted":"866-971-5703","promo_number":"8669715703","tracking_url":"http://ringringrevenue.com/c/1/38-240-19?us=http%3A%2F%2Fwww2.ringrevenue.com%2Fdemo%2F8x8_staging.html%3Fsid%3D8669715703%26PPCPN%3D8669715703","overflow":true}
 ]
}

Note the last response above has “overflow”:true. This indicates that the number returned is the overflow number for that RingPool. To simplify the normal case when the number is not overflow, the key-value pair is omitted when the value would be false.

Additionally, Bulk API responses return the total server processing (this does not include transit) time for the request in the header under the key “processing-time”, and is reported in milliseconds.

Errors

The Bulk RingPool API clearly identifies errors when a request can not be processed. For example, when the parameters are incorrect, an error response will be returned for that row in the response as shown below:

{
   "responses":[
    {"request_id":"193C5F","promo_number_formatted":"888-390-6665","promo_number":"8883906665","tracking_url":"http://ringrevenue.com/c/1/14-11-109?us=http%3A%2F%2Fwww2.ringrevenue.com.com%2Fdemo%2F8x8_staging.html%3Fsid%3D8883906665%26PPCPN%3D8883906665"},
    {"request_id":"58CD4F","error_class":"InvalidKey","message":"API Key 'A329F4DC002168' is not valid for resource '1'"},
    {"request_id":"E3901B","promo_number_formatted":"866-971-5703","promo_number":"8669715703","tracking_url":"http://ringringrevenue.com/c/1/38-240-19?us=http%3A%2F%2Fwww2.ringrevenue.com%2Fdemo%2F8x8_staging.html%3Fsid%3D8669715703%26PPCPN%3D8669715703"}
  ]
}

As another example, the following exception occurs when attempting to allocate a number with the RingPool API against a RingPool that has been set up to use the Bulk RingPool API:

{
    "errors":
    {
        "invalid_data":"Numbers are automatically allocated by the PNAPI server",
        "class”:”OnlyBulkNumberAllocationAllowed"
    }
}

If a system error occurs, an InternalServiceError will be returned with an integer error handle.

Contact questions@invoca.com to determine the root cause of such an error.

Signal API

The Signal API is used to report signals that occur on a specific call (transaction).

Signals may be anything an organization would like to track such as sales, quotes, etc.

Response Codes

Remember to check the HTTP status code returned. This helps greatly when debugging.

Status Code Meaning
200 OK An existing signal was found and updated
201 Created A new signal was created
401 Not Authorized Invalid or missing oauth token
403 Forbidden Attempted to access an invalid resource or provided invalid data. Check the errors object in the response.
404 Not Found Provided a transaction ID that was not found, or if using call start time and other search filters, no matching call found

Request Parameters

Passed in “application/json” format.

Search Parameters

Used to find the call associated with the signal.

Required

transaction_id: The ID of the transaction (Call leg) being reported on.

or

call_record_id: The ID of the complete call being reported on.

or

start_time_t: The start time does not have to be exact since clocks will not be perfectly synchronized. We will find the closest match (in combination with duration_in_seconds, if provided). See Timestamp Formats section below for descriptions of supported timestamps.

Note: If using start_time_t to match, instead of transaction_id, one or more of the following optional parameters is highly recommended. The optional parameters are ignored when using the transaction_id:

Optional

calling_phone_number: ANI in E.164 format +country national_number; example: ‘+18885551212’.

duration_in_seconds: Length of the call. Used for finding the call that drove the sale. Like start time, duration_in_seconds does not have to be exact, we use it to find the closest match.

advertiser_id_from_network: ID from network field on advertiser; only calls within this advertiser will be considered (only allowed when reporting as network user, and advertiser must be in same network).

advertiser_campaign_id_from_network: ID from network field on advertiser campaign; only calls within this advertiser campaign will be considered (campaign must be in the organization accessed via API).

network_id: ID of the network.

Signal Parameters

Used to create the fields of a signal.

Required

name: The name describing the signal event. For reporting a sale happened on a call, “Sale” is recommended. Other examples include “Free Trial”, “2yr Subscription”, “Cancellation.” This can be used elsewhere in the system and should be a small list of values meaningful to your organization. Names are matched case-insensitively, but we will preserve and use the casing of the first time the signal name is reported.

Optional

partner_unique_id: Unique identifier, to distinguish between updating an existing signal (for example correcting a sale that was reported) versus adding a second sale to the call (for example a reservation made while on the call and then an add on item purchased later). Note: this ID only needs to be unique within the given transaction and name, so it can be as simple as “1”, “2”… or it can be a globally unique ID if desired. Defaults to empty string if not passed.

description: Free form text for providing additional details about the signal (for example: a sales order ID or a specific product being purchased or inquired about).

occurred_at_time_t: This allows batching of signal results at a later time and still capture the exact time the signal event happened. See Timestamp Formats section below for descriptions of supported timestamps. Defaults to the time of the API request if not provided.

sale_amount: Money with up to 2 decimal places (period separated). Assumed to be in the same currency as the organization that owns the signal being reported. Defaults to null if not passed. (Recommended to omit parameter if no sale occurred, instead of passing 0). Do not include formatting such as currency symbol or separators (i.e. commas).

value: True or false as to whether the signal was met or not. Defaults to true if not passed. Can be a string ‘true’ or ‘false’, or 1 (true) or 0 (false), Yes (true), or No (false). These values are not case sensitive.

Additional Parameters

Required

oauth_token: API token for authentication

call_in_progress: True or false as to whether the call may still be in progress. Invoca will immediately return a 201 and empty response body when this is set to true. When the call finishes, Invoca will apply the signal.

Note: call_in_progress can be passed, even when the call has already finished. However, Invoca will only check for required fields and all other errors will not be returned. It is highly recommended to use transaction_id in the search parameters. If call_start_time is used, please provide the calling_phone_number, as well as any other information you can provide, to help avoid matching with an earlier call.

Endpoint:

https://invoca.net/api/2015-08-17/transactions/signals

Examples

Example using transaction_id (of the call to associate the signal to) and providing all signal fields:

Endpoint:

https://invoca.net/api/2015-08-17/transactions/signals.json

Request Body

{
  "search": {
    "transaction_id": "00000000-00000001"
  },
  "signal": {
    "name": "sale",
    "partner_unique_id": "1",
    "description": "1 year contract",
    "occurred_at_time_t": "1440607313",
    "sale_amount": "100.00",
    "value": "true"
  },
  "oauth_token": "<YOUR OAUTH TOKEN>"
}

Response Body

{
  "signal": {
    "transaction_id": "00000000-0000000A",
    "corrects_transaction_id": null,
    "name": "sale",
    "partner_unique_id": "1",
    "description": "1 year contract",
    "occurred_at_time_t": "1440607313",
    "sale_amount": "100.0",
    "value": "true"
  },
  "call": {
    "transaction_id": "00000000-00000001",
    "start_time_t": "1435993200"
  }
}

Example using start_time_t, all optional search fields, and all signal fields:

Endpoint:

https://invoca.net/api/2015-08-17/transactions/signals.json

Request Body

{
  "search": {
    "start_time_t": "1440607313",
    "calling_phone_number": "1234567890",
    "duration_in_seconds": "60",
    "advertiser_id_from_network": "1",
    "advertiser_campaign_id_from_network": "2",
    "network_id": "3"
  },
  "signal": {
    "name": "sale",
    "partner_unique_id": "1",
    "description": "1 year contract",
    "occurred_at_time_t": "1440607313",
    "sale_amount": "100.00",
    "value": "true"
  },
  "oauth_token": "<YOUR OAUTH TOKEN>"
}

Response Body:

{
  "signal": {
    "transaction_id": "00000000-0000000A",
    "corrects_transaction_id": null,
    "name": "sale",
    "partner_unique_id": "1",
    "description": "1 year contract",
    "occurred_at_time_t": "1440607313",
    "sale_amount": "100.0",
    "value": "true"
  },
  "call": {
    "transaction_id": "00000000-00000001",
    "start_time_t": "1435993200"
  }
}

Examples

Example using transaction_id and providing all signal fields:

Endpoint:

https://invoca.net/api/2015-08-17/transactions/signals.json

Request Body # HTTP PUT

{
  "search": {
    "transaction_id": "00000000-00000001"
  },
  "signal": {
    "name": "sale",
    "partner_unique_id": "1",
    "description": "Updated description and sale amount",
    "sale_amount": "200.00"
  },
  "oauth_token": "<YOUR OAUTH TOKEN>"
}

Response Body:

When an update occurs, a 200 status code is returned, otherwise the response body looks the same as a create. # 200 OK

{
  "signal": {
    "transaction_id": "00000000-0000000B",
    "corrects_transaction_id": "00000000-0000000A",
    "name": "sale",
    "partner_unique_id": "1",
    "description": "Updated description and sale amount",
    "occurred_at_time_t": "1440607313",
    "sale_amount": "200.0",
    "value": "true"
  },
  "call": {
    "transaction_id": "00000000-00000001",
    "start_time_t": "1435993200"
  }
}

Note: It’s necessary to use the transaction_id of the transaction (call leg) that the signal was originally reported on. The name and partner_unique_id must also match the signal being updated.

Timestamp Formats

The following formats are supported for both start_time_t and occurred_at_time_t.

All examples below correspond to a date time of 11 April 2016 at 1 PM Pacific Time.

Epoch: 10 digit timestamp in UTC seconds since 1/1/70, also known as Unix time_t. UTC milliseconds since 1/1/70 (which is the default in Javascript) are also supported, i.e. a 13 digit start time.

Example (10 digits): 1460404800

Example (13 digits): 1460404800000

Compressed: 17 digit timestamp always parsed in UTC.

Format: YYYYMMDDHHMMSSsss

Example: 20160411130000000

ISO 8601: Timestamp with +/- UTC offset or Z to indicate time is in UTC. Milliseconds are optional.

Format: YYYY/MM/DDTHH:MM:SS.sss+hh:mm

Example (UTC offset of +3 hours): 2016/04/11T23:00:00.000+03:00

Example (UTC offset of -7 hours): 2016/04/11T13:00:00.000-07:00

Example (UTC): 2016/04/11T20:00:00.000Z

Example (no milliseconds): 2016/04/11T13:00:00-07:00

Excel Compatible: Timestamp parsed in the timezone of the oauth token’s associated network. Milliseconds are optional.

Format: YYYY/MM/DD HH:MM:SS.sss AM/PM

Example: 2016/04/11 13:00:00.000 PM

Example (no milliseconds): 2016/04/11 13:00:00 PM

Note: The file upload user interface includes a timezone dropdown feature, which allows users to select which timezone this format is parsed in. Use the following to format Excel date cells: yyyy/mm/dd hh:mm:ss.000 AM/PM.

Example POST Request Using cURL

You can send call results to Invoca servers in the form of an HTTP POST or PUT. cURL is recommended because it is simple and preinstalled on most machines. Below is an example of a cURL request:

curl -k -H "Content-Type: application/json" -X POST -d '{"search": {"transaction_id": "00000000-00000001"},"signal": {"name": "sale","partner_unique_id": "1","description": "1 year contract","occurred_at_time_t": "1440607313","sale_amount": "100.00","value": "true"},"oauth_token": <YOUR OAUTH TOKEN>}'  https://invoca.net/api/<API_VERSION>/transcations/signals.json

Errors

The Signal API clearly identifies errors when a request cannot be processed.

Validation Errors

If invalid parameters are passed an error will be returned with a 403 response code. For example, if a transaction_id or start_time_t are not passed in the request, the following error will be returned.

{
  "errors": {
    "class": "RecordInvalid",
    "invalid_data": "Validation failed: transaction_id or start_time_t must be present"
  }
}

Record Not Found Error

If no record is found for the search parameters that are passed in the request an error will be returned with a 404 response code. For example, if a call cannot be found for the search parameters passed, the following error will be returned.

{
  "errors": {
    "class": "RecordNotFound",
    "invalid_data": "No call found. Please refer to the documentation."
  }
}

Permission Errors

If you do not have access to the Signal API, the following error will be returned with a 403 response code.

{
  "errors": {
    "class": "UnauthorizedOperation",
    "invalid_data": "You do not have permissions to perform the requested operation."
  }
}

Authorization Errors

If you do not have access to the advertiser_id_from_network, advertiser_campaign_id_from_network, or the network_id an error will be returned with a 403 response code. For example, if you pass an advertiser_id_from_network that you do not have access to, the following error will be returned.

{
  "errors": {
    "class": "UnauthorizedAdvertiser",
    "invalid_data": "You do not have access to this advertiser"
  }
}

Updates and Idempotency

Signals are considered unique by a combination of name and partner_unique_id. For example, if you make two requests with the same name and partner_unique_id, the other params in the second request will update the original signal’s fields

Therefore, if you make two requests with the same params, the signal will not be updated nor will a new one be made. It is safe then to re-post API requests without fear of duplicate data.

If you change the partner_unique_id, a second signal of the same name will be associated with the transaction.

Example of creating two signals (on a single call) then updating one

Initial request (creates first signal):

{
  "search": {
    "transaction_id": "00000000-00000001"
  },
  "signal": {
    "name": "Quote",
    "partner_unique_id": "1",
    "description": "Honda Accord 2015"
  },
  "oauth_token": "<YOUR OAUTH TOKEN>"
}

Response:

{
  "signal": {
    "transaction_id": "00000000-0000000A",
    "corrects_transaction_id": null,
    "name": "Quote",
    "partner_unique_id": "1",
    "description": "Honda Accord 2015",
    "occurred_at_time_t": "1440607999",
    "value": "true"
  },
  "call": {
    "transaction_id": "00000000-00000001",
    "start_time_t": "1435993200"
  }
}

Second request (creates another signal):

{
  "search": {
    "transaction_id": "00000000-00000001"
  },
  "signal": {
    "name": "Quote",
    "partner_unique_id": "2",
    "description": "Toyota Camry 2015"
  },
  "oauth_token": "<YOUR OAUTH TOKEN>"
}

Response:

{
  "signal": {
    "transaction_id": "00000000-0000000B",
    "corrects_transaction_id": null,
    "name": "Quote",
    "partner_unique_id": "2",
    "description": "Toyota Camry 2015",
    "occurred_at_time_t": "1440607800",
    "value": "true"
  },
  "call": {
    "transaction_id": "00000000-00000001",
    "start_time_t": "1435993200"
  }
}

Third request (updates first request):

{
  "search": {
    "transaction_id": "00000000-00000001"
  },
  "signal": {
    "name": "Quote",
    "partner_unique_id": "1",
    "description": "Honda Civic 2012"
  },
  "oauth_token": "<YOUR OAUTH TOKEN>"
}

Response:

{
  "signal": {
    "transaction_id": "00000000-0000000C",
    "corrects_transaction_id": "00000000-0000000A",
    "name": "Quote",
    "partner_unique_id": "1",
    "description": "Honda Civic 2012",
    "occurred_at_time_t": "1440607999",
    "value": "true"
  },
  "call": {
    "transaction_id": "00000000-00000001",
    "start_time_t": "1435993200"
  }
}

Note: even though this third request was an update to the first and will appear in reports as updating the first signal, a new transaction ID is returned. This is because a correction has been made to the first signal, and this new transaction ID is what will appear in webhooks and the Transactions API.

Web Integration

Web Integration dynamically displays a unique phone number for each source driving traffic to landing pages, both for publishers and advertisers.

See the following technical documentation for details on how to setup Web Integration:

Advertiser Web Integration

Please Note: This documentation references invoca.net in the Web Integration examples below. However, previous installations referencing ringrevenue.com are still valid.

Advertiser Web Integration is a platform feature that uses JavaScript to switch the advertiser’s phone number with a campaign’s tracking phone number (promo number). When the advertiser and their marketing partners send online traffic to the advertiser’s landing page, their tracking phone number appears on the page and attributes the marketing source for any resulting phone calls.

Campaign promo numbers can be static or they can be dynamically generated using the RingPool API feature.

Installation Instructions

  1. Before beginning, make sure your campaign has a landing page defined in the campaign wizard Creatives step.
  2. From the Advertiser Home Page, choose Tools gear, Web Integration.
  1. In the Web Integration, Settings tab, enter the phone number to replace on your website.
  1. Click Update.
  2. Click “Get Code” tab to access your custom generated web integration code.
  3. Place the web integration code on your website (every page where you want to display the promo number) in the footer just above the </body> tag. This step only has to be done once.

Testing the code

  1. To test web integration inside the platform, from the Web Integration panel, click Integration Test. Select “Open Test”.

Click “Start Test”.

If the test is successful, the results return a green checkmark.

If the test is unsuccessful, the results return with a red exclamation. The web integration code is not installed properly or the landing page cannot be found. See Web Integration Troubleshooting below.

  1. To test web integration outside the platform, in a browser enter the landing page URL, or other web integrated page’s URL, and append PPCPN=9999999999.

    If the URL has a query string, use an “&” to append the PPCPN, for example:

    http://www.invoca.com/corporate/landhere/?r=1&PPCPN=9999999999

    If the URL does not have a query string, use a “?” to append the PPCPN, for example:

    http://www.invoca.com?PPCPN=9999999999

    If the test is successful, the number or numbers on the page change to 999-999-9999.

    If test is unsuccessful, the number or numbers do not change to 999-999-9999. See Web Integration Troubleshooting below.

Web Integration Troubleshooting

  1. Check that the phone number is entered in the Web Integration, Settings tab and matches the phone number on your website.
  2. If you display other phone numbers in addition to the number entered in Web Integration, Settings tab, make sure you are using additional client side Web Integration settings to accommodate multiple phone numbers. See below for examples.
  3. Check for syntax errors on the page, for example, missing commas or brackets.

Web Integration Settings

Web Integration settings can be set on the server or the client side (browser side). As an example, the NumberToReplace field can be set on the platform(server side) and in the JavaScript function(client side). A large majority of advertisers only need to configure the settings on the platform or server side. Including Web Integration settings on the client side should only be done if the Web Integration’s behavior needs to be customized. The client side settings always takes precedence over the server side.

Server Side Integration

All of the server side settings are defined in the Web Integration, Settings tab.

Click on “Advanced Tracking Settings” to view and configure advanced settings.

Advertisers can have campaign traffic and general traffic going to the same integrated landing pages. The Web Integration code distinguishes between the two types of traffic and behaves accordingly. Campaign traffic arrives on the landing page by clicking on a link supplied by the Invoca platform. The link loads the promo number dynamically with the web integration code. General traffic arrives on the landing page without clicking on an Invoca platform link.

To track and report on all general traffic, select “Track all calls”. Select the Campaign to track general traffic. Select or create the RingPool to use for general traffic and click Update.

Client Side Integration & Parameters

The client side settings are listed in the table below. Most installations do not require any client side changes. To initialize the Web Integration code, pass the integration settings in a hash to the Invoca.advertiser_integration function.

Invoca.advertiser_integration = {
  id : 'YOUR_ID_HERE'
};
Required parameters: &nbsp; &nbsp;
id String Unique Advertiser ID. (Auto Populated in Tools, Web Integration, Get Code tab)
Optional parameters:    
numberToReplace String

Default: ‘’

Note: This field can be specified on the server side on the Web Integration, Settings tab.

It is recommended to use this and not add this parameter to the Javascript.

The phone number on the page to replace with an Invoca promo number.

Prefix international numbers with ‘+’ and separate the country code with a space. Other punctuation is ignored but can be used for readability. The number is replaced in the same format as is used on the page.

Example values:

‘805-555-5784’, ‘+1 8055555784’, ‘020 8905 1456’, or ‘+44 020 8905 1456’
numberSelector String

Default: ‘’

The selector of the HTML elements where you want phone number inserted.

Prefix IDs with ‘#’ and classes with ‘.’

For example, ‘.promoNumber’ replaces the number in all HTML elements having class=”promoNumber”.
campaignId String

Default: null

Note: This option can be specified on the server side on the Web Integration, Settings tab (default campaign for general site traffic). It is recommended to use the server side settings and not add this parameter to the Javascript.

Unique campaign ID.

If you need separate settings per landing page, then this field is required.
ringPoolId String

Default: null

Note: This can be specified on the server side on the Web Integration, Settings tab (default RingPool for general site traffic). It is recommended to use the server side settings and not add this parameter to the Javascript.

Unique RingPool ID.

If you need separate settings per landing page, then this field is required.

For general traffic coming to the site, the RingPool specified in Advanced Tracking Settings is used to allocate a number. If the RingPool is not specified, the campaign ID is used to find a valid RingPool.
numberSeparator String

Default: ‘-‘

Character to separate phone digit groups.
numberLeadingOne Boolean

Default: true.

If true, inserts a leading ‘1’ then the separator in front of the number.
showSelector String

Default: ‘’

The selector of the HTML elements you want to set to visible (using jQuery.show) when a promo number is swapped out. Prefix IDs with ‘#’ and classes with ‘.’ .

This is useful for having a span that says “call now:” which should only be displayed if a valid phone number is inserted. See also hideSelector. (The elements are not shown if Click to Call is being used and ctcUseButton is set to true.)
hideSelector String

Default: ‘’

The selector of the HTML elements you want to have set to display:none (removed from the page visually). Prefix IDs with ‘#’ and classes with ‘.’

This is useful for hiding the image that has the default company phone number embedded in it, when a valid promo number is found. See also showSelector and notVisibleSelector.
notVisibleSelector String

Default: ‘’

The selector of the HTML elements you want to have set to visibility:hidden (hide on page in place). Prefix IDs with ‘#’ and classes with ‘.’

This is useful for hiding an element when a valid promo number is found but keeping the page layout the same. See also hideSelector and showSelector.
onLoadWithNumber Function

Default: null

A callback function called after web integration has run and modified the DOM using the selectors specified in the parameters.

Called with the following arguments:

is_ctc boolean - true if CTC is enabled

phone_number string - formatted phone number (empty if CTC is enabled and a promo number is not available).
onLoadNoNumber Function

Default: null

A callback function called after Web Integration runs and no modification is made.
mobileClickToCall Boolean

Default: true

When true, automatically wraps valid promo numbers in tel links when viewed on a mobile browser, so they are clickable and launch a dialer. Non-mobile browsers will get the default behavior of just a phone number.

If your site already has dynamic behavior specified on the phone number DOM element, you may want to set this to false to prevent conflicts.
networkParamName String

Default: ‘sid’

The query parameter name used for passing promo numbers through click-tracking URLs. (Configured within your main network, if available)
ctcUseButton Boolean

Default: true

Applicable when web integration is set to use the online click-to-call form. When true, modifies the elements specified by numberSelector to contain a “Call Me!” button (or ctcButtonContent if set), otherwise inserts the phone number (when available) and wires up a click handler on the element.

A class of click_to_call_button is added to the element specified by numberSelector. You can add CSS styling to that class to customize the look to match your website.
ctcButtonContent String

Default: ‘<button type=”button”>Call Now!</button>’

Applicable when Web Integration is using the online click-to-call form. HTML content to override the default online CTC call to action (button or hyperlink is recommended).
debug Boolean

Default: false

When true, debug information is printed to the console in browsers that support console.log() and console.error()

Safari & Chrome using the Developer JavaScript Console

Firefox with Firebug enabled

IE8+ with Developer Tools enabled

Client Settings (Advanced)

numberToReplace vs. numberSelector

There are two ways for the Web Integration code to know where to insert a tracking phone number. Note that you should only use one or the other, not both.

  1. The numberToReplace option, which is the easy to use option, looks for the advertiser’s phone number on the web page and replaces it with the affiliate or publisher tracking phone number(promo number).
  2. The numberSelector option, which is the robust option used for customizing the Web Integration’s behavior, looks for an HTML element that has the same ID or class name and replaces the entire element with the affiliate or publisher tracking phone number(promo number) or a click-to-call button. Click-to-call only works with this option.

Selector information

All “selector” parameters are a comma separated list of IDs or classes, where IDs are prefixed with a “#” and classes are prefixed with a “.” (similar to referencing a class or ID using jQuery or prototype). Only a single class or single ID per selector is supported, no other jQuery selector syntax is supported.

  • Valid:

    A single class: .promoNumber

    A single ID: #number

    A list of classes: .promoNumber, .mainNumber

  • Not valid:

    table > .promoNumber

    .promoNumber:first

    span#number

Simple Examples

Default example of replacing multiple phone numbers on a page, with no additional options specified: ( ‘YOUR_ID_HERE’ represents where the unique advertiser ID is inserted.)

<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Landing Page</title>
  </head>

  <body>
    Call Now! 1-800-555-1234

    <div class="content">
      Here is the content of your website.
    </div>

    <div class="footer">
      Contact us: 1-800-555-1234
    </div>
    <!-- Omit http from path to ensure protocol is same as current request -->
    <script src="//js14.invoca.net/14/integration.js"></script>
    <script type="text/javascript">
      try {
        Invoca.advertiser_integration = {
          id : 'YOUR_ID_HERE'
        };
      } catch( e ){ }
    </script>
  </body>
</html>

Example with NumberToReplace options specified on the client side, replacing multiple phone numbers on a page:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Landing Page</title>
  </head>

  <body>
    Call Now! 1-800-555-1234

    <div class="content">
      Here is the content of your website.
    </div>

    <div class="footer">
      Contact us: 1-800-555-1234
    </div>
    <!-- Omit http from path to ensure protocol is same as current request -->
    <script src="//js14.invoca.net/14/integration.js"></script>
    <script type="text/javascript">
      try {
        Invoca.advertiser_integration = {
          id : 'YOUR_ID_HERE',
          numberToReplace : '1-800-555-1234'
        };
      } catch( e ){ }
    </script>
  </body>
</html>

Advanced Examples

Example changing the phone number presentation using the NumberSelector option on the client side:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Landing Page</title>
  </head>

  <body>
    Sales:<br />
    <strong><span id="site_phone_number">800.555.1234</span></strong>

    <div class="content">
      Here is the content of your website.
    </div>
    <!-- Omit http from path to ensure protocol is same as current request -->
    <script src="//js14.invoca.net/14/integration.js"></script>
    <script type="text/javascript">
      try {
          Invoca.advertiser_integration = {
            id : 'YOUR_ID_HERE',
            numberSelector : '#site_phone_number',
            numberLeadingOne : false,
            numberSeparator : '.'
          };
      } catch( e ){ }
    </script>
  </body>
</html>

Example website that has the default phone number embedded in an image:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Landing Page with Phone Number in Image</title>
  </head>

  <body>
    <div class="header">
      <img src="http://support.invoca.net/sites/default/files/admin/company_logo.gif" />
      <img src="http://support.invoca.net/sites/default/files/admin/header_phone_number.gif" id="header_phone" />
      <span class="promoNumber"></span>
    </div>

    <div class="content">
      Here is the content of your website.
    </div>
    <!-- Omit http from path to ensure protocol is same as current request -->
    <script src="//js14.invoca.net/14/integration.js"></script>
    <script type="text/javascript">
      try {
        Invoca.advertiser_integration = {
          id             : 'YOUR_ID_HERE',
          numberSelector : '.promoNumber',
          hideSelector   : '#header_phone'
        };
      } catch( e ){ }
    </script>
  </body>
</html>

Example website that has no default phone number, and wants to show a call to action when a promo number is used:

<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Landing Page with No Default Phone Number</title>
  </head>

  <body>
    <div class="header">
      <img src="http://support.invoca.net/sites/default/files/admin/company_logo.gif" />
      <span class="promoCallNow" style="display: none">Call now: </span>
      <span class="promoNumber"></span>
    </div>

    <div class="content">
      Here is the content of your website.
    </div>
<!-- Omit http from path to ensure protocol is same as current request -->
    <script src="//js14.invoca.net/14/integration.js"></script>
    <script type="text/javascript">
      try {
        Invoca.advertiser_integration = {
          id : 'YOUR_ID_HERE',
          numberSelector : '.promoNumber',
          showSelector   : '.promoCallNow'
        };
      } catch( e ){ }
    </script>
  </body>
</html>

* For sites with dynamic numbers through a third party, the Invoca code can still swap promo numbers over the third party numbers by placing the span tags around the code: <span class=”promoNumber”>INSERT THIRD PARTY CODE HERE</span>


Example using callbacks for custom behavior. (Note that adding tel links to numbers now happens automatically, so using a callback is no longer necessary!)

<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Landing Page with Callback Functions</title>
    <script type="text/javascript">
      function showNumber( is_ctc, phoneNumber )
      {
        alert( 'The following number was returned and displayed: ' + phoneNumber + '. CTC enabled: ' + is_ctc );
      }

      function hideNumber( )
      {
        alert( 'No number was returned' );
      }
    </script>
  </head>

  <body>
    <div class="header">
      Call <span id="number" class="promoNumber">1-800-555-1234</span>
    </div>

    <div class="content">
      Here is the content of your website.
    </div>

    <!-- Omit http from path to ensure protocol is same as current request -->
    <script src="//js14.invoca.net/14/integration.js"></script>
    <script type="text/javascript">
      try {
        Invoca.advertiser_integration = {
          id               : 'YOUR_ID_HERE',
          numberSelector   : '.promoNumber',
          onLoadWithNumber : showNumber,
          onLoadNoNumber   : hideNumber
        };
      } catch( e ){ }
    </script>
  </body>
</html>

Capturing Additional Parameters with JavaScript

You can capture additional RingPool parameters through client-side JavaScript using the poolParams option. In the following example, the visitor’s landing page timestamp is set to the poolParam “landingTime”.

<script src="//js14.invoca.net/14/integration.js"></script>
<script type="text/javascript">
  var d = new Date();
  var timeStamp = d.toUTCString();

  Invoca.advertiser_integration = {
    id : 'YOUR_ID_HERE',
        campaignId : YOUR_CAMPAIGN_ID,
        ringPoolId : YOUR_RINGPOOL_ID,
        poolParams : { landingTime : timeStamp }
    };
</script>

Displaying Different Numbers on Other Pages

Typically a visitor is “cookied” at a domain level and therefore is served the same number as they visit various web-integrated pages on the same domain. Use the “cookieId” option to set a unique cookie on different pages of a website. This allows different numbers to be served to the same visitor, depending on the page they visit. This example demonstrates how to allocate a unique number for the same user on two different pages. Any page that uses cookieId: “A” displays one number, and any page that uses cookieId: “B” displays another. Note: The cookie names (e.g. A, B) can be a custom name of your choosing.

<!-- Page 1: Cookie "A" -->
<script src="//js14.invoca.net/14/integration.js"></script>
<script type="text/javascript">
  Invoca.advertiser_integration = {
     id : 'YOUR_ID_HERE',
        campaignId : YOUR_CAMPAIGN_ID,
        ringPoolId : YOUR_RINGPOOL_ID,
        cookieId: 'A'
    };
</script>

<!-- Page 1: Cookie "B" -->
<script src="//js14.invoca.net/14/integration.js"></script>
<script type="text/javascript">
  Invoca.advertiser_integration = {
    id : 'YOUR_ID_HERE',
    campaignId : YOUR_CAMPAIGN_ID,
    ringPoolId : YOUR_RINGPOOL_ID,
    cookieId: 'B'
  };
</script>

Online Click-To-Call (CTC) Form Settings

When online CTC is enabled, the default behavior is for the phone number on the page to be replaced by a “Call now” button. When clicked, a lightbox window pops up over the page prompting the user to enter their phone number. The logo shown in the lightbox can be customized in the platform on the Customize Online Click-to-Call Form page accessed from Tools, Web Integration, Settings tab, Advanced Tracking Settings link.

Example of customizing the “Call now” button when using online CTC.

<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Landing Page with Customized CTC Button</title>
  </head>

  <body>
    <div class="header">
      <span class="promoNumber">1-800-555-1234</span>
    </div>

    <div class="content">
      Here is the content of your website.
    </div>
    <!-- Omit http from path to ensure protocol is same as current request -->
    <script src="//js14.invoca.net/14/integration.js"></script>
    <script type="text/javascript">
      try {
        Invoca.advertiser_integration = {
          id               : 'YOUR_ID_HERE',
          numberSelector   : '.promoNumber',
          ctcUseButton     : true,
          ctcButtonContent : '<a href="#">Click Here to Call</a>'
        };
      } catch( e ){ }
    </script>
  </body>
</html>

That example results in a “Click Here to Call” link in the header, and when clicked would show the online CTC form.


Example of Multiple RingPools™ on a Single Landing Page

It is possible to have a single landing page with one installation of the web integration code that chooses different RingPools based on the criteria of your choosing (a query param or referring site, etc.).

  1. On the server, you can have a list of RingPool / Campaign ID pairs, and associate each pair with a key. In the example below, the key is the referring page’s domain.
  2. Find the correct ID pairs for a given request, and make them available for the view template.
  3. Insert the ID pair into the web integration code using the template.

The following is an example using Ruby on Rails as the web technology. Regardless of how you are generating the landing pages, the concepts are the same.

Server code (controller/action):

class LandingPageController < ApplicationController
  RING_POOL_BY_REFERRER = { "google"   : [ 7, 8  ],
                            "facebook" : [ 7, 10 ],
                            "bing"     : [ 8, 31 ] }
  def show
    @page = LandingPage.find( params[:id] )
    ids = RING_POOL_BY_REFERRER[ domain_name_from_referrer( request.env["HTTP_REFERER"] ) ]
    @campaign_id  = ids[0]
    @ring_pool_id = ids[1]
  end

  private

  \# parses string and returns "google", "facebook", etc
  def domain_name_from_referrer( referrer )
    ...
  end
end

HTML page (template):

<!DOCTYPE HTML PUBLIC "-//W3C//DTD XHTML 1.0 Transitional//EN"
                      "http://www.w3.org/TR/xhtml1/DTD/xhtml1-transitional.dtd">
<html xmlns="http://www.w3.org/1999/xhtml">
  <head>
    <title>Landing Page with Multiple RingPools</title>
  </head>

  <body>
    <div class="header">
      <span class="promoNumber"></span>
    </div>

    <div class="content">
      <%= @page.body %>
    </div>
    <!-- Omit http from path to ensure protocol is same as current request -->
    <script src="//js14.invoca.net/14/integration.js"></script>
    <script type="text/javascript">
      try {
        Invoca.advertiser_integration = {
          id               : 'YOUR_ID_HERE',
          numberSelector   : '.promoNumber',
          campaignId       : '<%= @campaign_id %>',
          ringPoolId       : '<%= @ring_pool_id %>'
        };
      } catch( e ){ }
    </script>
  </body>
</html>

Notice that there is only ever one installation of the Web Integration code, and the only thing that needs to be set up on the server side are the IDs of the RingPool and Campaign.

Elegantly Swap Phone Number with jQuery

By default, the Advertiser Web Integration code swaps a static phone number with a campaign number when a landing page loads. Occasionally, visitors may notice that the number changes.

The following example shows how to hide the static number on a landing page, and only show the Promo Number after the code runs. Additionally, in the event that no promo number is available, the code displays the original static number.

Directions:

Update var PHONE_SELECTOR to be the selector wrapping the phone number to be replaced.

Update var FADE_SPEED to be the length of the fade in milliseconds.

In the HTML, wrap your phone numbers in a span tag with the class “phone-number”. <span class=”phone-number”>STATIC NUMBER HERE</span>.

<!-- Omit http from path to ensure protocol is same as current request -->
<script src="//js11.invoca.net/11/integration.js"></script>
<script type="text/javascript">

/* -- Invoca Custom Code -- */

  // Fade in tracking number on success, or original number on fail
  function showNumber()
  {
    jQuery(PHONE_SELECTOR).fadeIn(FADE_SPEED);
  }

  // Settings
  var PHONE_SELECTOR = '.example';
  var FADE_SPEED     = 250; // Miliseconds

  // Hide default number
  jQuery(PHONE_SELECTOR).css({'display':'none'});

  // Our number swapping code
  Invoca.advertiser_integration = {
    id               : 'YOUR_ID_HERE',
    numberSelector   : PHONE_SELECTOR,
    onLoadWithNumber : showNumber,
    onLoadNoNumber   : showNumber
  };

/* -- End of Invoca Custom Code -- */

</script>
<!-- End Call Tracking Code -->

Developers Note

While testing the Web Integration code, especially advanced cases including RingPool or Campaign IDs, it is recommended that you set “debug: true”. If a RingPool ID is specified but is invalid, an error message is logged to the browser’s JavaScript console stating that the RingPool ID is invalid (note that a working phone number may still be returned, it just will not be for the correct RingPool). If both RingPool and Campaign ID are invalid, an error message is logged stating the Campaign ID is invalid.