Welcome to the Invoca Developer Portal
Leverage the power of Invoca in your app or website. Browse the portal sections for all your documentation needs.
Basics
This section covers the several different fundamental areas of interacting with our APIs and web integration code.
API Documentation
Get documentation for each of the APIs in Invoca's full suite and learn how to access oAuth compliant API tokens.
Web Integration
Invoca's web integration code will dynamically display a unique phone number for each source driving traffic to landing pages.
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¶
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.
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/2017-04-01/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/2017-04-01/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 2017-04-01, 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:
- Authenticates the user on the network Platform.
- Makes a server‐to‐server request for a one‐time use access token.
- Appends the returned access token to the PPC Platform destination URL access_token=<ProvidedAccessToken>
- 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": "bpD8HmLcCxzSiOX01v4XbZr4_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": "bpD8HmLcCxzSiOX01v4XbZr4_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": "bpD8HmLcCxzSiOX01v4XbZr4_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
Network Link to PPC¶
The network platform offers a Marketing Automation hyperlink in the authenticated area for Advertisers and Affiliates. The link uses the same landing page as On-The-Fly authentication does to seamlessly log the user into the Invoca Marketing Automation Platform:
http://www.network.com/login?destination=http%3A%2F%2F<network>.invoca.net%2Fhome
PPC Link to Network¶
The PPC platform offers a “Return from marketing automation” link that returns to an appropriate URL at the network. This URL must be provided by the network. For example:
CURL examples:¶
Here are some basic examples on how to use the API using CURL.
Create
curl -v XPOST -H “ContentType: 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 “ContentType: application/json” -u ‘<username>:<password> ‘https://www.invoca.net/api/2014-01-01/<network_id>/<url>’ -d ‘<valid JSON>’
Delete
curl -v -XDELETE -H “ContentType: 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:
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:
From the Navigation Bar, hover on Integrations and select “Invoca APIs”
On the “Invoca API Credentials” page, click “New API Credential”
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:
From the Navigation Bar, hover on Integrations and select “Invoca APIs”
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/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>.json
We support passing back current_terms and future_terms on campaigns. The current properties of the campaign are reflected in current_terms. All changes to the campaign are staged in future_terms. Once the campaign goes live, future_terms transition over to current_terms.
You can set budgets on your campaign. There are three budget types, budget_cap_alert which is based on commissions, periodic_call_cap_alert, which is based on the number of calls in a given period, and concurrent_call_cap_alert, which is based on the number of simultaneous calls. These budget activities are only applicable for AffiliateEnabled campaigns (Known in the platform as a “Publisher Promotion” Campaign Type.)
You are not allowed to delete campaigns.
| Property | Type | Value |
|---|---|---|
| id | integer (read-only) | The internal Invoca id for this Advertiser Campaign. |
| id_from_network | string | The network object_id for this Advertiser Campaign. Unique within network. Not required when auto-generation is enabled at network level. |
| name | string | Campaign name. |
| campaign_type | string | 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. |
| object_url | string (read-only) | URL for reaching the advertiser campaign in the UI. |
| timezone | string | Supported Time Zones: http://api.rubyonrails.org/classes/ActiveSupport/TimeZone.html |
| campaign_language | string | Supported Campaign Languages: “English”, “French”, “Spanish”. |
| campaign_country | string | Supported Countries: “US”, “CA”, “UK”, “AU”, “CN”, “FI”, “FR”, “DE”, “HK”, “IT”, “JP”, “NL”, “SG”, “SE”, “CH”. |
| operating_24_7 | boolean | |
| affiliate_payout | ||
| policies | ||
| currency | string | USD, GBP, EUR. |
| amount | decimal | Payout Amount. |
| condition | string | Condition options depend on the following Campaign Setup items being in place: Duration (seconds/minutes) and (greater than, greater than or equal to, less than, less than or equal to, equal to), Connect Duration (seconds/minutes) and (greater than, greater than or equal to, less than, less than or equal to, equal to), Repeat, In Region (specified across multiple Regions), During Hours, Key Press, Is Mobile, Is Landline, Send SMS All may be grouped with logic operators (AND/OR/NOT). |
| type | string | One of: Base, Bonus. |
| advertiser_payin | ||
| policies | ||
| currency | string | Supported Currencies: ‐ USD, GBP, EUR. |
| amount | integer | Advertiser Payin Amount. |
| condition | string | Condition options depend on the following Campaign Setup items being in place: Duration (seconds/minutes) and (greater than, greater than or equal to, less than, less than or equal to, equal to), Connect Duration (seconds/minutes) and (greater than, greater than or equal to, less than, less than or equal to, equal to), Repeat, In Region (specified across multiple Regions), During Hours, Key Press, Is Mobile, Is Landline, Send SMS. All may be grouped with logic operators (AND/OR/NOT). |
| type | string | One of: Base, Bonus. |
| hours | ||
| [day of week]_open (e.g. friday_open) | string | Open Hours. In seconds past midnight (e.g. 0 for midnight, 32400 for 9:00 AM). |
| [day of week]_close (e.g. friday_close) | string | Closed Hours. In seconds past midnight (e.g. 0 for midnight, 75600 for 9:00 PM). |
| [day of week]_closed (e.g. sunday_closed) | string | true, false, or null. Whether the business is closed that day of the week. |
| named_regions | ||
| name | string | Region Name. |
| regions | ||
| region_type | string | Region Type. Can be one of: Zone, City, State, Country. |
| value | string | Region Value, e.g. “Sacramento, CA”, or just “CA”. |
| ivr_tree | hash | See following Advertiser Campaign IVR Section. |
| budget_activities | Only applicable for AffiliateEnabled campaigns. | |
| budget_cap_alert | ||
| reset_period | string (required) | Budget will reset based on this entry. One of: Daily, Weekly, Monthly, Quarterly, Ongoing. |
| starts_at | date (required) | Budget Start. |
| budget_currency | string (required) | Budget Currency. |
| time_zone | string (required) | Supported Time Zones: “Pacific Time (US & Canada)”, “Mountain Time (US & Canada)”, “Central Time (US & Canada)”, “Eastern Time (US & Canada)”, “London”, “UTC”. |
| budget_amount | decimal (required) | Budget Amount. |
| include_call_fees | boolean | True if you want call fees to be included in the budget. |
| periodic_call_cap_alert | ||
| reset_period | string (required) | Budget will reset based on this entry. One of: Daily, Weekly, Monthly, Quarterly, Ongoing. |
| starts_at | date (required) | Call Cap Start. |
| budget_currency | string (required) | Budget Currency. |
| time_zone | string (required) | Supported Time Zones: “Pacific Time (US & Canada)”, “Mountain Time (US & Canada)”, “Central Time (US & Canada)”, “Eastern Time (US & Canada)”, “UTC”. |
| budget_amount | decimal (required) | Budget Amount. |
| auto_approve | string | One of: All, None, Approved_Affiliates Default: None This controls if affiliates are automatically approved when applying to the campaign. |
| visibility | string | One of: All, None, Approved_Affiliates Default: All This controls the level of visibility publishers have when applying to campaigns. |
| expiration_date | string | date string (ex. ‘2015‐01‐01’). Read only. |
| default_creative_id_from_network | integer | Default Creative ID. |
| concurrent_call_cap_alert | ||
| budget_amount | decimal (required) | Budget Amount. |
| timeout | integer | Seconds to wait for the campaign to go live. Between 2 and 60. |
Advertiser Campaign IVRs¶
When creating an advertiser campaign, you need to provide some call flow logic through an IVR tree. Depending on the advertiser/campaign type (direct, bundled, etc) you may use the following node types:
Node Parameters and Usage
* => required parameter
| Node Type | Parameters | Usage |
|---|---|---|
| Menu | *prompt | 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)
Caller ID options can also be configured by optionally including a caller_id object inside ivr_tree:
| Setting | Mask | Example | Details |
|---|---|---|---|
| “original” | None | { setting: “original” } | Display caller’s caller id to call center agent. (Default) |
| “promo” | None | { setting: “promo” } | Display affiliate promo number to call center agent. (Only if forwarding to a local number.) |
| “specific” | String containing phone number | { setting: “specific”, mask: “800-555-5555” } | Display a specific caller ID number. |
| “partial” | String containing mask format | { setting: “partial”, mask: “800-555-XXXX” } | Display caller’s caller ID with digits replaced. |
Custom Data¶
Advertiser campaigns may have Custom Data Fields applied to them, which will be applied to calls originating through the advertiser campaign.
To apply Custom Data Values to an advertiser campaign, the top level parameter custom_data should be assigned a hash with each pair’s key corresponding to a partner name.
The value of the pair should be the value to be applied.
For the following example, we would apply the value “Offline newspaper” to the Custom Data Field “channel”.
{
"custom_data": {
"channel": "Offline newspaper"
}
}
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>.json
Examples
Read all campaigns for Advertiser 2 id from network
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/2/advertiser_campaigns.json
Response Body:
An array of campaigns are returned.
Examples
Read Campaign 100 for Advertiser 2
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/2/advertiser_campaigns/100.json
Response Body:
{
"id": 11,
"id_from_network": "100",
"name": "PostSeason Promotion 11 fJauFbSEGHKw8ADEGv",
"status": "Entry",
"object_url": "https://invoca.net/a_campaigns/terms/11",
"current_terms": {
"description": "August promotion to sell post-season tickets at half price.",
"timezone": "Pacific Time (US & Canada)",
"visibility": "All",
"created_at": "2015-05-13 07:45:08 -0800",
"id": "215",
"operating_24_7": false,
"go_live_date": null,
"default_creative_id_from_network": "222",
"campaign_language": "English",
"campaign_country": "US",
"advertiser_payin": {
"min": 7,
"currency": "EUR",
"pricing": "€7.00 per call if duration > 2 min 30 sec",
"max": 7,
"policies": [
{
"type": "Base",
"currency": "EUR",
"condition": "duration > 2 min 30 sec",
"amount": 7
}
],
"range": "€7.00 per call"
},
"pricing_type": "Fixed",
"ivr_tree": {
"root": {
"condition": "during_hours",
"children": [
{
"destination_phone_number": "8004377950",
"destination_country_code": "1",
"prompt": "",
"node_type": "Connect"
},
{
"destination_phone_number": "8004377950",
"destination_country_code": "1",
"prompt": "",
"node_type": "Connect"
}
],
"node_type": "Condition"
},
"record_calls": true
},
"auto_approve": "None",
"expiration_date": null,
"campaign_type": "AffiliateEnabled",
"affiliate_payout": {
"min": 4.5,
"currency": "USD",
"pricing": "Base: $4.50 per call Bonus: $2.75 per call if duration > 60",
"max": 7.25,
"policies": [
{
"type": "Base",
"currency": "USD",
"condition": "",
"amount": 4.5
},
{
"type": "Bonus",
"currency": "USD",
"condition": "duration > 60",
"amount": 2.75
}
],
"range": "$4.50 - $7.25 per call"
},
"updated_at": "2015-05-13 07:45:08 -0800",
"url": "http://www.nfltix.com/postseasonnow",
"hours": {
"saturday_open": 32400,
"sunday_open": 32400,
"monday_closed": false,
"tuesday_open": 32400,
"thursday_open": 32400,
"friday_close": 75600,
"sunday_close": 50999,
"wednesday_closed": false,
"thursday_closed": false,
"tuesday_close": 75600,
"friday_open": 32400,
"saturday_closed": true,
"sunday_closed": true,
"tuesday_closed": true,
"wednesday_close": 75600,
"friday_closed": true,
"monday_open": 32400,
"saturday_close": 75600,
"monday_close": 75600,
"thursday_close": 75600,
"wednesday_open": 32400
},
"named_regions": [
{
"regions": [
{
"region_type": "State",
"value": "CA",
"text": "TBD"
},
{
"region_type": "State",
"value": "OR",
"text": "TBD"
},
{
"region_type": "State",
"value": "WA",
"text": "TBD"
}
],
"name": "West Coast"
},
{
"regions": [
{
"region_type": "State",
"value": "NY",
"text": "TBD"
},
{
"region_type": "State",
"value": "NJ",
"text": "TBD"
}
],
"name": "East Coast"
}
]
},
"future_terms": {
"description": "August promotion to sell post-season tickets at half price.",
"timezone": "Pacific Time (US & Canada)",
"visibility": "All",
"created_at": "2015-05-13 08:46:43 -0800",
"id": "",
"operating_24_7": false,
"go_live_date": null,
"default_creative_id_from_network": "123",
"campaign_language": "English",
"campaign_country": "US",
"advertiser_payin": {
"min": 7,
"currency": "EUR",
"pricing": "€7.00 per call if duration > 2 min 30 sec",
"max": 7,
"policies": [
{
"type": "Base",
"currency": "EUR",
"condition": "duration > 2 min 30 sec",
"amount": 7
}
],
"range": "€7.00 per call"
},
"budget_activities": {
"periodic_call_cap_alert": {
"budget_amount": 200.0,
"budget_currency": "USD",
"reset_period": "Ongoing",
"start_at": "2014-04-17T00:00:00-07:00",
"total_amount": 0.0,
"time_zone": "Pacific Time (US & Canada)"
},
"concurrent_call_cap_alert": {
"budget_amount": 50.0,
"budget_currency": "USD",
"reset_period": "Ongoing",
"start_at": "2014-04-17T00:00:00-07:00",
"time_zone": "Pacific Time (US & Canada)"
},
"budget_cap_alert": {
"budget_amount": 100.0,
"budget_currency": "USD",
"reset_period": "Monthly",
"start_at": "2014-04-01T00:00:00-07:00",
"total_amount": 0.0,
"time_zone": "Pacific Time (US & Canada)"
},
"pricing_type": "Fixed",
"ivr_tree": {
"root": {
"condition": "during_hours",
"children": [
{
"destination_phone_number": "8004377950",
"destination_country_code": "1",
"prompt": "",
"node_type": "Connect"
},
{
"destination_phone_number": "8004377950",
"destination_country_code": "1",
"prompt": "",
"node_type": "Connect"
}
],
"node_type": "Condition"
},
"record_calls": true
},
"auto_approve": "None",
"expiration_date": "2015-05-18T23:59:59-08:00",
"campaign_type": "AffiliateEnabled",
"affiliate_payout": {
"min": 4.5,
"currency": "USD",
"pricing": "Base: $4.50 per call Bonus: $2.75 per call if duration > 60",
"max": 7.25,
"policies": [
{
"type": "Base",
"currency": "USD",
"condition": "",
"amount": 4.5
},
{
"type": "Bonus",
"currency": "USD",
"condition": "duration > 60",
"amount": 2.75
}
],
"range": "$4.50 - $7.25 per call"
},
"updated_at": "2015-05-13 08:46:43 -0800",
"url": "http://www.nfltix.com/postseasonnow",
"hours": {
"saturday_open": 32400,
"sunday_open": 32400,
"monday_closed": false,
"tuesday_open": 32400,
"thursday_open": 32400,
"friday_close": 75600,
"sunday_close": 50999,
"wednesday_closed": false,
"thursday_closed": false,
"tuesday_close": 75600,
"friday_open": 32400,
"saturday_closed": true,
"sunday_closed": true,
"tuesday_closed": true,
"wednesday_close": 75600,
"friday_closed": true,
"monday_open": 32400,
"saturday_close": 75600,
"monday_close": 75600,
"thursday_close": 75600,
"wednesday_open": 32400
},
"named_regions": [
{
"regions": [
{
"region_type": "State",
"value": "CA",
"text": "TBD"
},
{
"region_type": "State",
"value": "OR",
"text": "TBD"
},
{
"region_type": "State",
"value": "WA",
"text": "TBD"
}
],
"name": "West Coast"
},
{
"regions": [
{
"region_type": "State",
"value": "NY",
"text": "TBD"
},
{
"region_type": "State",
"value": "NJ",
"text": "TBD"
}
],
"name": "East Coast"
}
]
}
},
"custom_data": {
"channel": "Online lead"
}
}
Examples
Create Campaign fJauFbSEGHKw8ADEGv for Advertiser cFUyYnFHyiYA42TrpM
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/cFUyYnFHyiYA42TrpM/advertiser_campaigns.json
Request Body:
{
"id_from_network": "fJauFbSEGHKw8ADEGv",
"name": "PostSeason Promotion 11 fJauFbSEGHKw8ADEGv",
"description": "August promotion to sell post-season tickets at half price.",
"url": "http://www.nfltix.com/postseasonnow",
"timezone": "Pacific Time (US & Canada)",
"operating_24_7": false,
"campaign_type": "AffiliateEnabled",
"campaign_country": "US",
"default_creative_id_from_network": "111",
"hours": {
"friday_open": 32400,
"wednesday_open": 32400,
"sunday_close": 50999,
"monday_open": 32400,
"friday_close": 75600,
"wednesday_close": 75600,
"friday_closed": true,
"thursday_open": 32400,
"sunday_closed": true,
"sunday_open": 32400,
"saturday_open": 32400,
"monday_closed": false,
"thursday_close": 75600,
"tuesday_closed": true,
"tuesday_close": 75600,
"tuesday_open": 32400,
"saturday_closed": true,
"saturday_close": 75600,
"monday_close": 75600,
"thursday_closed": false,
"wednesday_closed": false
},
"named_regions": [
{
"name": "West Coast",
"regions": [
{
"region_type": "State",
"value": "CA"
},
{
"region_type": "State",
"value": "OR"
},
{
"region_type": "State",
"value": "WA"
}
]
},
{
"name": "East Coast",
"regions": [
{
"region_type": "State",
"value": "NY"
},
{
"region_type": "State",
"value": "NJ"
}
]
}
],
"advertiser_payin": {
"policies": [
{
"condition": "duration > 2 min 30 sec",
"type": "Base",
"currency": "USD",
"amount": 7.0
}
]
},
"affiliate_payout": {
"policies": [
{
"condition": "",
"amount": 4.5,
"currency": "USD",
"type": "Base"
},
{
"condition": "duration > 60",
"amount": 2.75,
"currency": "USD",
"type": "Bonus"
}
]
},
"ivr_tree": {
"record_calls": true,
"root": {
"node_type": "Condition",
"condition": "during_hours",
"children": [
{
"node_type": "Connect",
"destination_phone_number": "8004377950",
"destination_country_code": "1",
"prompt": ""
},
{
"node_type": "Connect",
"destination_phone_number": "8004377950",
"destination_country_code": "1",
"prompt": ""
}
]
}
},
"custom_data": {
"channel": "Offline leads"
}
}
Response Body:
Same as a GET response, includes all the advertiser campaign properties.
Examples
Example IVR Tree updates:
- 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 "ContentType: application/json" -u 'login:pass'
'https://vanity.invoca.net/api/2017-04-01/advertisers/:advertiser_id/advertiser_campaigns/445566.json' \
-d '
{"ivr_tree":
{"root":
{"node_type":"VerifyLocation",
"children":
[{"node_type":"Condition",
"condition":"in_region[West Coast]",
"children":
[{"children":[],
"condition":"",
"node_type":"Connect",
"destination_phone_number":"8004377950",
"destination_country_code":"1"},
{"node_type":"EndCall",
"prompt":"We are sorry, we currently cannot service your area. Goodbye."}]}]
},
"record_calls":true}}' -v
- 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 "ContentType: application/json" -u 'login:pass'
'https://vanity.invoca.net/api/2017-04-01/advertisers/:advertiser_id/advertiser_campaigns/445566.json' \
-d '
{"ivr_tree":{
"record_calls":true,
"root":{
"node_type":"Menu",
"prompt":"Please press 1 for sales or 2 for 24 hour support",
"children":[
{ "node_type":"Condition",
"condition":"during_hours",
"children":[
{ "node_type":"Connect",
"destination_phone_number":"8004377950",
"destination_country_code":"1",
"prompt":"Thank you, transferring you now"
},
{ "node_type":"EndCall",
"prompt":"We are currently closed. Please call back during business hours. Goodbye"
}]},
{ "node_type":"Connect",
"destination_phone_number":"8004377950",
"destination_country_code":"1",
"prompt":"Thank you, transferring you now"
}]}}}' -v
- Offer an sms to see current offers and then connect to a call center.
curl -XPUT -H "ContentType: application/json" -u 'login:pass'
'https://vanity.invoca.net/api/2017-04-01/advertisers/:advertiser_id/advertiser_campaigns/445566.json' \
-d '
{"ivr_tree":
{"root":
{"node_type":"SmsPromo",
"sms_promo_copy":"Visit us at www.invoca.com to see new promotions.",
"sms_promo_delay":1,
"prompt":"If you would like to see information about our current offers, please press 9 now.",
"children":
[{"children":[],
"condition":"",
"node_type":"Connect",
"destination_phone_number":"8004377950",
"destination_country_code":"1"}]
},
"record_calls":true}}' -v
Each of the above requests will have a response body similar to a GET request, including all the advertiser campaign properties.
Examples
Read Campaign 100 for Advertiser 2
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/quick_stats.json
Response Body:
{
"stats": {
"last_30days": {
"call_avg_total_duration": 0.0,
"call_count": 0
},
"last_7days": {
"call_avg_total_duration": 0.0,
"call_count": 0
},
"today": {
"call_avg_total_duration": 0.0,
"call_count": 0
}
}
}
Examples
Advertiser campaigns can have their state controlled through this API. When a campaign is created through the API, its “future terms” are being set, and its state is not yet live. When the go_live endpoint is hit, the “future terms” are promoted to “current terms” and the campaign becomes live. Archived campaigns must be unarchived before calling this endpoint to make them live.
Use this request url format:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/go_live.json?timeout=<timeout>
Examples
Advertiser campaigns can have their state controlled through this API. When a campaign is created through the API, its “future terms” are being set, and its state is not yet live. When the go_live endpoint is hit, the “future terms” are promoted to “current terms” and the campaign becomes live. Archived campaigns must be unarchived before calling this endpoint to make them live.
Use this request url format:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/go_live.json
curl -XPOST -H "ContentType: application/json" -u 'login:pass'
'https://vanity.invoca.net/api/2017-04-01/123/advertisers/advertiser_id/advertiser_campaigns/445566/go_live.json' \
-d '
{
"timeout": 10
}
' -v
Examples
If a campaign has previously been set to live, either through the API or through the UI, it can be archived, which effectively shuts it down. An archived campaign can be returned to live at a later time. To archive a campaign use this the following endpoint URL:
https://invoca.net/api/2017-04-01/<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/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/archive.json
Examples
Archived campaigns should be unarchived using this endpoint. It changes campaign status to paused. After that you can activate the campaign using a go_live request.
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/unarchive.json
Response Body:
{}
Examples
Archived campaigns should be unarchived using this endpoint. It changes campaign status to paused. After that you can activate the campaign using a go_live request.
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/unarchive.json
Response Body:
{}
Error Handling¶
Forbidden – 403:
PUT/POST¶
https://invoca.net/api/2017-04-01/<network_id>/advertiser/<advertiser_id_from_network>/advertiser_campaign/<advertiser_campaign_id_from_network>/advertiser_campaigns/<advertiser_campaign_id>.json
Content Type: application/json
Response Code: 403
Request Body
{
"node_type":"Menu",
"prompt":"Prompt text",
"prompt_id_from_network":"",
"prompt_url":null,
"prompt_recieved":null,
"children": [
{
"node_type":"Menu",
"prompt":"",
"prompt_id_from_network":"",
"prompt_url":null,
"prompt_recieved":null,
"children": [
{
"node_type":"EndCall",
"prompt":"",
"prompt_id_from_network":"",
"prompt_url":null,
"prompt_recieved":null
}
]
}
]
}
Response Body
{
"error": {
"ivr_tree": {
"children": [
{
"0": {
"prompt": [
"cannot be empty"
]
}
}
]
}
}
}
The number in error message represents the index of the child node in the tree, or in other words, it is the keypress of the node containing the error minus one.
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/2017-04-01/<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/2017-04-01/<network_id>/advertisers/e0Fv6YEk/users.json
Format: application/json
Response Code: 200
Response Body:
[
{
"email_settings": [
{ "email_address": "chris@nfltix.com", "use_for_notifications": true }
],
"id_from_network": "549494858585Dxlj2uCX0ijqXP4nAW",
"first_name": "Chris",
"contact_country_code": "1",
"last_name": "Dean",
"role": "Manager",
"oauth_refresh_token": "556588585858585858585858858",
"contact_phone_number": "888-603-3760",
"notify_on_budgets": true,
"notify_on_campaign_applications": false,
"notify_on_campaign_expirations": false,
"notify_on_creative_duplication_requests": true,
"notify_on_network_announcements": true,
"notify_on_performance_notifications": false,
"notify_on_monthly_campaign_performance_reports": true,
"notify_on_weekly_campaign_performance_reports": false,
"notify_on_call_activities": true
}
]
Examples
Read a specific advertiser user
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/e0Fv6YEk/users/549494858585Dxlj2uCX0ijqXP4nAW.json
Format: application/json
Response Code: 200
Response Body:
{
"email_settings": [
{ "email_address": "chris@nfltix.com", "use_for_notifications": true }
],
"id_from_network": "549494858585Dxlj2uCX0ijqXP4nAW",
"first_name": "Chris",
"contact_country_code": "1",
"last_name": "Dean",
"role": "Manager",
"oauth_refresh_token": "556588585858585858585858858",
"contact_phone_number": "888-603-3760",
"notify_on_budgets": true,
"notify_on_campaign_applications": false,
"notify_on_campaign_expirations": false,
"notify_on_creative_duplication_requests": true,
"notify_on_network_announcements": true,
"notify_on_performance_notifications": false,
"notify_on_monthly_campaign_performance_reports": true,
"notify_on_weekly_campaign_performance_reports": false,
"notify_on_call_activities": true
}
Examples
Create an advertiser user
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/e0Fv6YEk/users.json
Request Body:
{
"user": {
"id_from_network": "549494858585Dxlj2uCX0ijqXP4nAW",
"email_settings": [
{ "email_address": "chris@nfltix.com", "use_for_notifications": true }
],
"first_name": "Chris",
"last_name": "Dean",
"contact_phone_number": "805-555-5555",
"oauth_refresh_token": "556588585858585858585858858",
"role": "Manager",
"notify_on_budgets": true,
"notify_on_campaign_applications": false,
"notify_on_campaign_expirations": false,
"notify_on_creative_duplication_requests": true,
"notify_on_network_announcements": true,
"notify_on_performance_notifications": false,
"notify_on_monthly_campaign_performance_reports": true,
"notify_on_weekly_campaign_performance_reports": false,
"notify_on_call_activities": true
}
}
Examples
Update an Advertiser User
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/e0Fv6YEk/users/<user_id>
Request Body:
{
"user": {
"email_settings": [
{ "email_address": "chris@nfltix.com", "use_for_notifications": true }
],
"id_from_network": "549494858585Dxlj2uCX0ijqXP4nAW",
"first_name": "Chris",
"contact_country_code": "1",
"last_name": "Dean",
"role": "Manager",
"oauth_refresh_token": "556588585858585858585858858",
"contact_phone_number": "888-603-3760",
"notify_on_budgets": true,
"notify_on_campaign_applications": false,
"notify_on_campaign_expirations": false,
"notify_on_creative_duplication_requests": true,
"notify_on_network_announcements": true,
"notify_on_performance_notifications": false,
"notify_on_monthly_campaign_performance_reports": true,
"notify_on_weekly_campaign_performance_reports": false,
"notify_on_call_activities": true
}
}
Examples
Delete an advertiser user
Endpoint:
https://invoca.net/api/2017-04-01/<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 | integer (read-only) | The internal Invoca id for this Advertiser. |
| id_from_network | string (required) | The network id for this Advertiser. Unique within network. Not required when auto-generation is enabled at network level. |
| 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 | |
| object_url | string (read-only) | URL for reaching the advertiser in the UI. |
| 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_settings | JSON array of hashes | Each hash has two required fields:
A user must have at least one email address where |
| 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) |
| notify_on_budgets | boolean, optional, defaults to false | |
| notify_on_campaign_applications | boolean, optional, defaults to false | |
| notify_on_campaign_expirations | boolean, optional, defaults to false | |
| notify_on_creative_duplication_requests | boolean, optional, defaults to false | |
| notify_on_network_announcements | boolean, optional, defaults to false | |
| notify_on_performance_notifications | boolean, optional, defaults to false | |
| notify_on_monthly_campaign_performance_reports | boolean, optional, defaults to false | |
| notify_on_weekly_campaign_performance_reports | boolean, optional, defaults to false | |
| notify_on_call_activities | boolean, optional, defaults to false |
Custom Data¶
Advertisers may have Custom Data Fields applied to them, which will be applied to calls originating through the advertiser.
To apply Custom Data Values to an advertiser, the top level parameter custom_data should be assigned a hash with each pair’s key corresponding to a partner name.
The value of the pair should be the value to be applied.
For the following example, we would apply the value “Offline newspaper” to the Custom Data Field “channel”.
{
"custom_data": {
"channel": "Offline newspaper"
}
}
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>.json
Examples
Read all advertisers for this network
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers.json
Format: application/json
Response Code: 200
Response Body:
[
{
"id": 43838,
"id_from_network": "cFUyYnFHy",
"web_integration_phone_number": "8004377950",
"approval_status": "Approved",
"object_url": "https://invoca.net/as/43838/dashboards/ui",
"sites": [
{
"id_from_network": "315",
"name": "315.blog.com"
}
],
"name": "NFL Tickets Exchange",
"users": [
{
"id_from_network": "549494858585cFUyYnFHyiYA42TrpM",
"email_settings": [
{ "email_address": "chris@nfltix.com", "use_for_notifications": true }
],
"first_name": "Chris",
"phone_number": "888‐603‐3760",
"last_name": "Dean",
"role": "Manager",
"oauth_refresh_token": "556588585858585858585858858",
"notify_on_budgets": true,
"notify_on_campaign_applications": false,
"notify_on_campaign_expirations": false,
"notify_on_creative_duplication_requests": true,
"notify_on_network_announcements": true,
"notify_on_performance_notifications": false,
"notify_on_monthly_campaign_performance_reports": true,
"notify_on_weekly_campaign_performance_reports": false,
"notify_on_call_activities": true
}
],
"default_creative_id_from_network": "222",
"oauth_refresh_token": "7464644784457575757494930303",
"custom_data": {
"channel": "Online lead"
}
}
]
Examples
Read a single advertiser
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/cFUyYnFHy.json
Format: application/json
Response Code: 200
Response Body:
{
"id": 43838,
"id_from_network": "cFUyYnFHy",
"web_integration_phone_number": "8004377950",
"approval_status": "Approved",
"object_url": "https://invoca.net/as/43838/dashboards/ui",
"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_settings": [
{ "email_address": "chris@nfltix.com", "use_for_notifications": true }
],
"first_name": "Chris",
"phone_number": "888‐603‐3760",
"last_name": "Dean",
"role": "Manager",
"oauth_refresh_token": "556588585858585858585858858",
"notify_on_budgets": true,
"notify_on_campaign_applications": false,
"notify_on_campaign_expirations": false,
"notify_on_creative_duplication_requests": true,
"notify_on_network_announcements": true,
"notify_on_performance_notifications": false,
"notify_on_monthly_campaign_performance_reports": true,
"notify_on_weekly_campaign_performance_reports": false,
"notify_on_call_activities": true
},
{
"id_from_network": "694940505055cFUyYnFHyiYA42TrpM",
"email_settings": [
{ "email_address": "jim@nfltix.com", "use_for_notifications": true }
],
"first_name": "Jim",
"phone_number": "888‐603‐3760",
"last_name": "Williams",
"role": "Observer",
"oauth_refresh_token": "4222424241628298228222",
"notify_on_budgets": true,
"notify_on_campaign_applications": false,
"notify_on_campaign_expirations": false,
"notify_on_creative_duplication_requests": true,
"notify_on_network_announcements": true,
"notify_on_performance_notifications": false,
"notify_on_monthly_campaign_performance_reports": true,
"notify_on_weekly_campaign_performance_reports": false,
"notify_on_call_activities": true
}
],
"default_creative_id_from_network": "222",
"oauth_refresh_token": "7464644784457575757494930303",
"custom_data": {
"channel": "Online lead"
}
}
Examples
Delete a single advertiser
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/cFUyYnFHy.json
Format: application/json
Response Code: 200
Response Body:
{
}
Examples
Create an advertiser with users
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers.json
Format: application/json
Request Body:
{
"name": "NFL Tickets Exchange",
"id_from_network": "cFUyYnFHy",
"oauth_refresh_token": "7464644784457575757494930303",
"approval_status": "Approved",
"web_integration_phone_number": "8004377950",
"default_creative_id_from_network": "222",
"users": [
{
"id_from_network": "549494858585cFUyYnFHyiYA42TrpM",
"email_settings": [
{ "email_address": "chris@nfltix.com", "use_for_notifications": true }
],
"first_name": "Chris",
"last_name": "Dean",
"contact_phone_number": "805-555-5555",
"oauth_refresh_token": "556588585858585858585858858",
"role": "Manager",
"notify_on_budgets": true,
"notify_on_campaign_applications": false,
"notify_on_campaign_expirations": false,
"notify_on_creative_duplication_requests": true,
"notify_on_network_announcements": true,
"notify_on_performance_notifications": false,
"notify_on_monthly_campaign_performance_reports": true,
"notify_on_weekly_campaign_performance_reports": false,
"notify_on_call_activities": true
},
{
"id_from_network": "694940505055cFUyYnFHyiYA42TrpM",
"email_settings": [
{ "email_address": "jim@nfltix.com", "use_for_notifications": true }
],
"first_name": "Jim",
"last_name": "Williams",
"contact_phone_number": "2135555555",
"oauth_refresh_token": "4222424241628298228222",
"role": "Observer",
"notify_on_budgets": true,
"notify_on_campaign_applications": false,
"notify_on_campaign_expirations": false,
"notify_on_creative_duplication_requests": true,
"notify_on_network_announcements": true,
"notify_on_performance_notifications": false,
"notify_on_monthly_campaign_performance_reports": true,
"notify_on_weekly_campaign_performance_reports": false,
"notify_on_call_activities": true
}
],
"sites": [
{
"id_from_network": "315",
"name": "315.blog.com"
},
{
"id_from_network": "996",
"name": "996.blog.com"
}
],
"custom_data": {
"channel": "Offline lead"
}
}
Response Body:
Same as a GET response, includes all the advertiser properties.
Examples
Update a user from advertiser
Endpoint:
https://invoca.net/api/2017-04-01/<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_settings": [
{ "email_address": "chris@nfltix.com", "use_for_notifications": true }
],
"first_name": "Chris",
"last_name": "Dean",
"contact_phone_number": "805-555-5555",
"oauth_refresh_token": "556588585858585858585858858",
"role": "Manager",
"notify_on_budgets": true,
"notify_on_campaign_applications": false,
"notify_on_campaign_expirations": false,
"notify_on_creative_duplication_requests": true,
"notify_on_network_announcements": true,
"notify_on_performance_notifications": false,
"notify_on_monthly_campaign_performance_reports": true,
"notify_on_weekly_campaign_performance_reports": false,
"notify_on_call_activities": true
}
],
"sites": [
{
"id_from_network": "315",
"name": "315.blog.com"
}
],
"custom_data": {
"channel": "Offline lead"
}
}
Response Body:
Same as a GET response, includes all the advertiser properties.
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. |
| id | integer (read-only) | The internal Invoca id of the 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. |
| object_url | string (read-only) | URL for reaching the affiliate campaign in the UI. |
| 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”). |
Custom Data¶
Affiliate campaigns may have Custom Data Fields applied to them, which will be applied to calls originating through the affiliate campaign.
To apply Custom Data Values to an affiliate campaign, the top level parameter custom_data should be assigned a hash with each pair’s key corresponding to a partner name.
The value of the pair should be the value to be applied.
For the following example, we would apply the value “Offline newspaper” to the Custom Data Field “channel”.
{
"custom_data": {
"channel": "Offline newspaper"
}
}
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/affiliates/<affiliate_id_from_network>/affiliate_campaigns.json
Examples
Get all Affiliate Campaigns
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/affiliate_campaigns.json
Examples
GET of Affiliate Campaign status for Advertiser 354 Campaign 12 to Affiliate 976
Endpoint:
https://invoca.net/api/2017-04-01/<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",
"id": 1,
"id_from_network": "11",
"affiliate_id_from_network": "976",
"object_url": "https://invoca.net/p_campaigns/terms/19/11",
"custom_data": {
"channel": "Online lead"
}
}
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/2017-04-01/<network_id>/advertisers/354/advertiser_campaigns/12/affiliates/975/affiliate_campaigns.json
Format: application/json
Request Body:
{
"status": "Applied",
"id_from_network": "2234",
"custom_data": {
"channel": "Offline lead"
}
}
Response Body:
Same as a GET response, includes all the affiliate campaign properties.
Not Found - 404
Endpoint:
https://invoca.net/api/api/2017-04-01/<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/2017-04-01/<network_id>/advertisers/354/advertiser_campaigns/12/affiliates/976/affiliate_campaigns.json
Format: application/json
Request Body:
{
"status": "Approved"
}
Response Body:
Same as a GET response, includes all the affiliate campaign properties.
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 | integer (read-only) | The internal Invoca id for this Affiliate. |
| id_from_network | string | The network object_id for this Affiliate. Unique within network. Not required when auto-generation is enabled at network level. |
| 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. |
| object_url | string (read-only) | URL for reaching the affiliate in the UI. |
| 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) |
Custom Data¶
Affiliates may have Custom Data Fields applied to them, which will be applied to calls originating through the affiliate.
To apply Custom Data Values to an affiliate, the top level parameter custom_data should be assigned a hash with each pair’s key corresponding to a partner name.
The value of the pair should be the value to be applied.
For the following example, we would apply the value “Offline newspaper” to the Custom Data Field “channel”.
{
"custom_data": {
"channel": "Offline newspaper"
}
}
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/affiliates/<affiliate_id_from_network>.json
Examples
Read all Affiliates for this network
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/affiliates.json
Request Body:
[
{
"id": 19,
"id_from_network": "222",
"object_url": "https://invoca.net/ps/19/dashboards/ui",
"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_settings": [
{ "email_address": "userx@invoca.com", "use_for_notifications": true }
],
"id_from_network": "1231",
"first_name": "User",
"phone_number": "805‐708‐9876",
"last_name": "Affiliate",
"role": "Super"
}
],
"status": "Approved",
"custom_data": {
"channel": "Online lead"
}
}
]
Examples
Read a specific affiliate
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/affiliates/222.json
Response Body:
{
"id": 19,
"id_from_network": "222",
"object_url": "https://invoca.net/ps/19/dashboards/ui",
"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_settings:" [
{ "email_address": "userx@invoca.com", "use_for_notifications": true }
],
"id_from_network": "1231",
"first_name": "User",
"phone_number": "805‐708‐9876",
"last_name": "Affiliate",
"role": "Super"
}
],
"status": "Approved",
"custom_data": {
"channel": "Online lead"
}
}
Examples
Delete a single affiliate
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/affiliates/222.json
Response Body:
{
}
Examples
Create an affiliate with users
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/affiliates.json
Format: application/json
Request Body:
{
"name": "Surf Oz Magazine",
"status": "Approved",
"id_from_network": "222",
"users": [
{
"phone_number": "805‐708‐9876",
"id_from_network": 123,
"role": "Super",
"last_name": "Affiliate",
"first_name": "User",
"email_settings": [
{ "email_address": "userx@invoca.com", "use_for_notifications": true }
],
}
],
"sites": [
{
"id_from_network": 33567,
"name": "http://www.surfoz.au"
},
{
"id_from_network": 44920,
"name": "http://www.blogspot.com/surfoz"
}
],
"custom_data": {
"channel": "Offline lead"
}
}
Response Body:
Same as a GET response, includes all the affiliate properties.
Examples
Update a single affiliate
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/affiliates/222.json
Request Body:
{
"name": "Updated Surf Oz Magazine"
}
Response Body:
Same as a GET response, includes all the affiliate properties.
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/2017-04-01/<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/2017-04-01/<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/2017-04-01/<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/2017-04-01/<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/2017-04-01/<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/2017-04-01/<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/2017-04-01/<network_id>/network.json
Examples
Read network and its users
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/network.json
Format: application/json
Response Code: 200
Response Body:
{
"name": "Invoca",
"users": [
{
"id_from_network": "549494858585cFUyYnFHyiYA42TrpM",
"email_settings": [
{ "email_address": "chris@nfltix.com", "use_for_notifications": true }
],
"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/2017-04-01/<network_id>/network.json
Format: application/json
Request Body:
{
"users": [
{
"id_from_network": "549494858585cFUyYnFHyiYA42TrpM",
"email_settings": [
{ "email_address": "chris@nfltix.com", "use_for_notifications": true }
],
"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/2017-04-01/<network_id>/network.json
Format: application/json
Request Body:
{
"users": [
{
"id_from_network": "549494858585cFUyYnFHyiYA42TrpM",
"email_settings" : [
{ "email_address": "chris@domain.com", "use_for_notifications": true }
],
"first_name": "Chris",
"last_name": "Dean",
"phone_number": "8004377950",
"role": "Manager"
}
]
}
Response Code: 403
Response Body:
{
"errors": {
"users": [
{
"email_settings": [
{ "email_address": ["is invalid"] }
]
}
]
}
}
Delete network users by putting an empty user hash
Endpoint:
https://invoca.net/api/2017-04-01/<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 |
|---|---|---|
| id | integer (read-only) | The internal Invoca id of the promo number. |
| id_from_network | string | Network specific id of the promo number. |
| description | string (required) | Arbitrary description |
| media_type | string (required) | one of: “Online: Content / Review Site” “Online: Discount / Coupon Site” “Online: Display” “Online: Email” “Online: Rewards / Incentive” “Online: Lead Form / Co Reg” “Online: Search” “Online: Social Media” “Online: Software” “Online: Other” “Mobile: Apps” “Mobile: Display” “Mobile: Search” “Mobile: SMS” “Mobile: Other” “Offline: Business Publication” “Offline: Call Center” “Offline: Direct Mail” “Offline: Directory” “Offline: Newspaper” “Offline: InCall Ad” “Offline: Magazine” “Offline: Outdoor” “Offline: Radio” “Offline: TV” “Offline: Other” |
| object_url | string (read-only) | URL for reaching the promo number in the UI. |
| local_center | hash | Requires one of the following City & State required together A filled field determines the center to start looking for local numbers at. “tn_prefix”: an npa “zipcode”: a valid zipcode “city”: a valid city “state”: a valid state |
| tn_prefix_whitelist | array of strings | an array of stringified limiters on the boundaries of where to look for local numbers given as npas (ex. [“805”, “212”]) |
| promo_type | string (optional) | For international campaigns that support local or mobile numbers. If not passed then promo numbers will default to the organizational default. (US/CA campaigns will continue to use local_center for local numbers) “Local” “Mobile” |
| promo_number_looks_like | string (optional) | For international local promo number creation, a string phone number to try to match can be included. The first five digits will be used. (ex. “805”, “80561”) |
Custom Data¶
Promo numbers may have Custom Data Fields applied to them, which will be applied to calls originating through the promo number.
To apply Custom Data Values to a promo number, the top level parameter custom_data should be assigned a hash with each pair’s key corresponding to a partner name.
The value of the pair should be the value to be applied.
For the following example, we would apply the value “Offline newspaper” to the Custom Data Field “channel”.
{
"custom_data": {
"channel": "Offline newspaper"
}
}
Endpoint:
https://invoca.net/api/2017-04-01/<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/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers.json
Format: application/json
Response Code: 200
Response Body:
[
{
"id": 21,
"id_from_network": "4531",
"media_type": "Online: Display",
"description": "Halloween Promo Number 1",
"promo_number": "8001234567",
"object_url": "https://invoca.net/a_campaigns/promo_numbers/11",
"custom_data": {
"channel": "Online lead"
}
}
]
Read all Affiliate Campaign Promo Numbers as an array
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/affiliates/<affiliate_id_from_network>/affiliate_campaigns/promo_numbers.json
Format: application/json
Response Code: 200
Response Body:
[
{
"id": 21,
"id_from_network": "4531",
"media_type": "Online: Display",
"description": "Halloween Promo Number 1",
"promo_number": "8001234567",
"object_url": "https://invoca.net/p_campaigns/promo_numbers/14/11",
"custom_data": {
"channel": "Online lead"
}
}
]
Examples
Read a specific Advertiser Campaign Promo Number
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers/<promo_number>.json
Format: application/json
Response Code: 200
Response Body:
{
"id": 21,
"id_from_network": "4531",
"media_type": "Online: Display",
"description": "Halloween Promo Number 1",
"promo_number": "8001234567",
"object_url": "https://invoca.net/a_campaigns/promo_numbers/11",
"custom_data": {
"channel": "Online lead"
}
}
Read a specific Affiliate Campaign Promo Number
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/affiliates/<affiliate_id_from_network>/affiliate_campaigns/promo_numbers/<promo_number>.json
Format: application/json
Response Code: 200
Response Body:
{
"id": 21,
"id_from_network": "4531",
"media_type": "Online: Display",
"description": "Halloween Promo Number 1",
"promo_number": "8001234567",
"object_url": "https://invoca.net/p_campaigns/promo_numbers/14/11",
"custom_data": {
"channel": "Online lead"
}
}
Examples
Create an Advertiser Campaign Promo Number
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers.json
Format: application/json
Request Body:
{
"description": "Halloween Promo Number 1",
"media_type": "Online: Display"
}
Response Code: 201
Response Body:
{
"id": 12,
"id_from_network": "12",
"media_type": "Online: Display",
"promo_number": "8777657743",
"description": "Halloween Promo Number 1",
"object_url": "https://invoca.net/a_campaigns/promo_numbers/12",
"custom_data": {
"channel": "Online lead"
}
}
Create an Advertiser Campaign Local Promo Number with tn_prefix
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers.json
Format: application/json
Request Body:
{
"description": "Halloween Promo Number 1",
"media_type": "Online: Display",
"local_center": {
"tn_prefix": "805"
},
"tn_prefix_whitelist": ["805"]
}
Response Code: 201
Response Body:
{
"id": 12,
"id_from_network": "12",
"media_type": "Online: Display",
"promo_number": "8057657743",
"description": "Halloween Promo Number 1",
"object_url": "https://invoca.net/a_campaigns/promo_numbers/12",
"custom_data": {
"channel": "Online lead"
}
}
Create an Advertiser Campaign Local Promo Number with city/state
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers.json
Format: application/json
Request Body:
{
"description": "Halloween Promo Number 1",
"media_type": "Online: Display",
"local_center": {
"city": "Santa Barbara",
"state": "CA"
}
}
Response Code: 201
Response Body:
{
"id": 12,
"id_from_network": "12",
"media_type": "Online: Display",
"promo_number": "8057657743",
"description": "Halloween Promo Number 1",
"object_url": "https://invoca.net/a_campaigns/promo_numbers/12",
"custom_data": {
"channel": "Online lead"
}
}
Create an Affiliate Campaign Promo Number
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/affiliates/<affiliate_id_from_network>/affiliate_campaigns/promo_numbers.json
Format: application/json
Request Body:
{
"description": "Halloween Promo Number 1",
"media_type": "Online: Display"
}
Response Code: 201
Response Body:
{
"id": 12,
"id_from_network": "12",
"media_type": "Online: Display",
"promo_number": "8777657743",
"description": "Halloween Promo Number 1",
"object_url": "https://invoca.net/p_campaigns/promo_numbers/14/11",
"custom_data": {
"channel": "Online lead"
}
}
Examples
Update an Advertiser Campaign Promo Number
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers/<promo_number>.json
Format: application/json
Request Body:
{
"description": "Halloween Promo Number 1 Updated",
"media_type": "Online: Display"
}
Response Code: 200
Response Body:
Same as a GET response, includes all the promo number properties.
Update Affiliate Campaign Promo Number
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/affiliates/<affiliate_id_from_network>/affiliate_campaigns/promo_numbers/<promo_number>.json
Format: application/json
Request Body:
{
"description": "Halloween Promo Number 1 Updated",
"media_type": "Online: Display"
}
Response Code: 200
Response Body:
Same as a GET response, includes all the promo number properties.
Examples
Delete an Advertiser Campaign Promo Number
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/promo_numbers/<promo_number>.json
Format: application/json
Response Code: 200
Response Body:
{
}
Delete an Affiliate Campaign Promo Number
Endpoint:
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/affiliates/<affiliate_id_from_network>/affiliate_campaigns/promo_numbers/<promo_number>.json
Format: application/json
Response Code: 200
Response Body:
{
}
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/2017-04-01/<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/2017-04-01/<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/2017-04-01/<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/2017-04-01/<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/2017-04-01/<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/2017-04-01/<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/2017-04-01/<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/2017-04-01/<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": ""
}
}
}
}
Custom Challenge Prompts¶
Manage custom challenge prompt for campaigns¶
A custom challenge prompt can be created from provided text or a professional prompt recordings can be assigned as custom challenge prompt.
Create custom challenge prompt¶
Example: create custom challenge prompt
POST
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>.json
Request Body
{
"ivr_tree": {
"record_calls": false,
"custom_challenge_prompt_text": "Thank you for calling.",
"root": {
"node_type": "Connect",
"destination_phone_number": "8056173768",
"destination_country_code": ""
}
}
}
Assign prompt recording as custom challenge prompt¶
Example: assign prompt recording as custom challenge prompt
POST
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>.json
Request Body
{
"ivr_tree": {
"record_calls": false,
"custom_challenge_prompt_id_from_network": "rec34",
"root": {
"node_type": "Connect",
"destination_phone_number": "8056173768",
"destination_country_code": ""
}
}
}
Retrieve custom challenge prompt for a campaign¶
Example: retrieve custom challenge prompt for a campaign
GET
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>.json
Response
{
"name": "Selling Shoes",
"status": "Activated",
"future_terms": {
"ivr_tree": {
"record_calls": false,
"custom_challenge_prompt_text": "Thank you for calling.",
"custom_challenge_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 |
|---|---|---|
| id | integer (read-only) | The internal Invoca id of the RingPool. |
| id_from_network | string (required) | Network specific id of the RingPool. Unique within network. Not required when auto-generation is enabled at network level. |
| 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. |
| object_url | string (read-only) | URL for reaching the RingPool in the UI. |
| 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/2017-04-01/<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/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/ring_pools.json
Response Code: 200
Response Body:
[
{
"id": "value",
"id_from_network": "5432",
"pool_type": "value",
"is_first_preference": true,
"destination_url": "",
"object_url": "https://invoca.net/a_campaigns/ring_pools/11",
"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/2017-04-01/<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",
"id_from_network": "5432",
"pool_type": "value",
"is_first_preference": true,
"destination_url": "",
"object_url": "https://invoca.net/a_campaigns/ring_pools/11",
"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/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/ring_pools.json
Format: application/json
Request Body:
{
"id_from_network": "12",
"param1": "q",
"param2": "test",
"param3": "param3",
"param4": "param4",
"param5": "param5",
"param6": "param6",
"param7": "param7",
"param8": "param8",
"param9": "param9",
"param10": "param10",
"pool_type": "SearchKeyword",
"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:
Same as a GET response, includes all the RingPool properties.
Examples
Update a RingPool
Endpoint:
https://invoca.net/api/2017-04-01/<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:
{
"id_from_network": "12",
"param1": "updated",
"param2": "test",
"param3": "param3",
"param4": "param4",
"param5": "param5",
"param6": "param6",
"param7": "param7",
"param8": "param8",
"param9": "param9",
"param10": "param10",
"pool_type": "SearchKeyword",
"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:
Same as a GET response, includes all the RingPool properties.
Examples
Delete a RingPool
Endpoint:
https://invoca.net/api/2017-04-01/<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/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/ring_pools.json
Content Type: application/json
| Property | Type | Value |
|---|---|---|
| id | integer (read-only) | The internal Invoca id of the RingPool. |
| id_from_network | string (required) | Network specific id of the RingPool. Unique within network. Not required when auto-generation is enabled at network level. |
| 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 |
| object_url | string (read-only) | URL for reaching the RingPool in the UI. |
| 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
{
"id_from_network": "395",
"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
Same as a GET response, includes all the RingPool properties.
Error Handling¶
Forbidden – 403:
POST¶
https://invoca.net/api/2017-04-01/<network_id>/advertisers/<advertiser_id_from_network>/advertiser_campaigns/<advertiser_campaign_id_from_network>/ring_pools.json
Content Type: application/json
Response Code: 403
Request Body
{
"id_from_network": "395",
"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.
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:
- 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.
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 “2014-04-15” 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. The conversion pixel is for online traffic only and cannot match to your call data.
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 numbers in the browser URL immediately following the /as/ and before any other punctuation.
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:¶
- Conversions reported include the call Start Time in Human Readable Time Format, the Calling Phone Number and the Reason Code.
- 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.
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.
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/2017-04-01/networks/transactions/33.csv |
| xml | Returns an XML document with an array of Transaction elements. https://mynetwork.invoca.net/api/2017-04-01/networks/transactions/33.xml |
| json | Returns a JSON array of transaction objects. https://mynetwork.invoca.net/api/2017-04-01/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. |
| include_columns= | comma-separated list of field names to be returned in the response for each transaction (if not specified, all available fields for the account will be returned, minus any columns in exclude_columns) |
| exclude_columns= | comma-separated list of field names to be excluded in the response for each transaction |
| 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.
We provide two helpful constants that can be used in the include_columns and exclude_columns options:
$invoca_custom_columns a dynamic constant that represents the current list of your Custom Data Fields. Note: If the list of custom columns changes, those changes will be included in future API calls that use “include_columns=$invoca_custom_columns”, independent of the API version.
$invoca_default_columns represents the default set of columns provided by the Transactions API for your requested version
Response¶
General Parameters¶
| 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_campaign_country | Advertiser Campaign Country | Country 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 | 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 | Duration of the call in seconds. Includes any time spent in an IVR tree before transferring to the call center. |
| ivr_duration | IVR Duration | 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 the API user’s time zone in Soap XML formatted time. |
| start_time_network_timezone | Call Start Time Network Timezone | Start of the call in the networks’s time zone, followed by offset from GMT. |
| start_time_network_timezone_xml | Call Start Time Network Timezone (XML formatted) | Start of the call in the network’s time zone 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 |
| hangup_cause | End of Call Reason | Who ended the call along with how it was ended |
| virtual_line_id | Promo Number ID | The Promo Number ID from the network |
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 |
| dynamic_number_pool_referrer_keyword_match_type | AdWords Keyword Match Type | The match type for the Keyword |
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. |
Custom Data Parameters¶
Please click this link to access the custom data parameters specific to your account. Please note that the Partner (API) Name will represent the field name returned by the Transactions API. Any custom data fields named the same as a standard Invoca Transactions API field will be returned by the API rather than the standard field.
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. |
| revenue | Revenue (Sale Amount) | The revenue to apply to the call if the Signal is evaluated as true. |
| signal_custom_parameter_1 | Signal Custom Param 1 | Up to 255 character string. |
| signal_custom_parameter_2 | Signal Custom Param 2 | Up to 255 character string. |
| signal_custom_parameter_3 | Signal Custom Param 3 | Up to 255 character string. |
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 |
| 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 |
| primary_email_address_data_append | Primary Email Address (Data Append) | Data from caller demographics lookup |
| linked_email_addresses_data_append | Linked Email Addresses (Data Append) | Data from caller demographics lookup |
| household_income_data_append | Household Income (Data Append) | Data from caller demographics lookup |
| marital_status_data_append | Marital Status (Data Append) | Data from caller demographics lookup |
| home_owner_status_data_append | Home Owner Status (Data Append) | Data from caller demographics lookup |
| home_market_value_data_append | Home Market Value (Data Append) | Data from caller demographics lookup |
| length_of_residence_years_data_append | Length of Residence in Years (Data Append) | Data from caller demographics lookup |
| occupation_data_append | Occupation (Data Append) | Data from caller demographics lookup |
| education_data_append | Education (Data Append) | Data from caller demographics lookup |
| has_children_data_append | Has Children (Data Append) | Data from caller demographics lookup |
| high_net_worth_data_append | High Net Worth (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 |
| real_time_response | Real Time Routing Response | Response information returned to Invoca when using the real-time routing webhook. |
Examples¶
These examples use CURL, and are using the following fake OAuth API token:
| OAuth API token |
|---|
| YbcFH |
Note: the -k option asks curl to not bother checking the SSL certificate authority chain as that requires extra configuration.
Example 1: Get the next 20 transactions that occurred after transaction id C624DA2C-CF3367C3:
curl -k 'https://mynetwork.invoca.net/api/2017-04-01/networks/transactions/33.csv?limit=20&start_after_transaction_id=C624DA2C-CF3367C3&oauth_token=YbcFH'
Example 2: Get 50 rows from a specific time period with only the transaction_id and all Custom Data columns:
curl -k 'https://mynetwork.invoca.net/api/2017-04-01/networks/transactions/33.csv?limit=50&include_columns=transaction_id,$invoca_custom_columns&exclude_columns=$invoca_default_columns&from=2015-03-26&to=2015-03-27&oauth_token=YbcFH'
Example 3: Get 50 rows that exclude a few columns such as Caller ID and Call Recordings:
curl -k 'https://mynetwork.invoca.net/api/2017-04-01/networks/transactions/33.csv?limit=50&exclude_columns=calling_phone_number,recording&start_after_transaction_id=C624DA2C-CF3367C3&oauth_token=YbcFH'
Example 4: Get All Transactions from a specific time period that are of transaction_type Signal:
curl -k 'https://mynetwork.invoca.net/api/2017-04-01/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/2017-04-01/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/2017-04-01/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/2017-04-01/networks/transactions/<network_id>.<format>
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/2017-04-01/advertisers/transactions/33.csv |
| xml | Returns an XML document with an array of Transaction elements. https://mynetwork.invoca.net/api/2017-04-01/advertisers/transactions/33.xml |
| json | Returns a JSON array of transaction objects. https://mynetwork.invoca.net/api/2017-04-01/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. |
| include_columns= | comma-separated list of field names to be returned in the response for each transaction (if not specified, all available fields for the account will be returned, minus any columns in exclude_columns) |
| exclude_columns= | comma-separated list of field names to be excluded in the response for each transaction |
| 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.
We provide two helpful constants that can be used in the include_columns and exclude_columns options:
$invoca_custom_columns a dynamic constant that represents the current list of your Custom Data Fields. Note: If the list of custom columns changes, those changes will be included in future API calls that use “include_columns=$invoca_custom_columns”, independent of the API version.
$invoca_default_columns represents the default set of columns provided by the Transactions API for your requested version
Response¶
General Parameters¶
| 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_campaign_country | Advertiser Campaign Country | Country 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 | 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 | Duration of the call in seconds. Includes any time spent in an IVR tree before transferring to the call center. |
| ivr_duration | IVR Duration | 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. |
| start_time_network_timezone | Call Start Time Network Timezone | Start of the call in the networks’s time zone, followed by offset from GMT. |
| start_time_network_timezone_xml | Call Start Time Network Timezone (XML formatted) | Start of the call in the network’s time zone 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 |
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 |
| dynamic_number_pool_referrer_keyword_match_type | AdWords Keyword Match Type | The match type for the Keyword |
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. |
Custom Data Parameters¶
Please click this link to access the custom data parameters specific to your account. Please note that the Partner (API) Name will represent the field name returned by the Transactions API. Any custom data fields named the same as a standard Invoca Transactions API field will be returned by the API rather than the standard field.
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. |
| revenue | Revenue (Sale Amount) | The revenue to apply to the call if the Signal is evaluated as true. |
| signal_custom_parameter_1 | Signal Custom Param 1 | Up to 255 character string. |
| signal_custom_parameter_2 | Signal Custom Param 2 | Up to 255 character string. |
| signal_custom_parameter_3 | Signal Custom Param 3 | Up to 255 character string. |
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 |
| 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 |
| primary_email_address_data_append | Primary Email Address (Data Append) | Data from caller demographics lookup |
| linked_email_addresses_data_append | Linked Email Addresses (Data Append) | Data from caller demographics lookup |
| household_income_data_append | Household Income (Data Append) | Data from caller demographics lookup |
| marital_status_data_append | Marital Status (Data Append) | Data from caller demographics lookup |
| home_owner_status_data_append | Home Owner Status (Data Append) | Data from caller demographics lookup |
| home_market_value_data_append | Home Market Value (Data Append) | Data from caller demographics lookup |
| length_of_residence_years_data_append | Length of Residence in Years (Data Append) | Data from caller demographics lookup |
| occupation_data_append | Occupation (Data Append) | Data from caller demographics lookup |
| education_data_append | Education (Data Append) | Data from caller demographics lookup |
| has_children_data_append | Has Children (Data Append) | Data from caller demographics lookup |
| high_net_worth_data_append | High Net Worth (Data Append) | Data from caller demographics lookup |
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 |
| real_time_response | Real Time Routing Response | Response information returned to Invoca when using the real-time routing webhook. |
Examples¶
These examples use CURL, and are using the following fake OAuth API token:
| OAuth API token |
|---|
| YbcFH |
Note: the -k option asks curl to not bother checking the SSL certificate authority chain as that requires extra configuration.
Example 1: Get the next 20 transactions that occurred after transaction id C624DA2C-CF3367C3:
curl -k 'https://mynetwork.invoca.net/api/2017-04-01/advertisers/transactions/33.csv?limit=20&start_after_transaction_id=C624DA2C-CF3367C3&oauth_token=YbcFH'
Example 2: Get 50 rows from a specific time period with only the transaction_id and all Custom Data columns:
curl -k 'https://mynetwork.invoca.net/api/2017-04-01/advertisers/transactions/33.csv?limit=50&include_columns=transaction_id,$invoca_custom_columns&exclude_columns=$invoca_default_columns&from=2015-03-26&to=2015-03-27&oauth_token=YbcFH'
Example 3: Get 50 rows that exclude a few columns such as Caller ID and Call Recordings:
curl -k 'https://mynetwork.invoca.net/api/2017-04-01/advertisers/transactions/33.csv?limit=50&exclude_columns=calling_phone_number,recording&start_after_transaction_id=C624DA2C-CF3367C3&oauth_token=YbcFH'
Example 4: Get All Transactions from a specific time period that are of transaction_type Signal:
curl -k 'https://mynetwork.invoca.net/api/2017-04-01/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/2017-04-01/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/2017-04-01/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/2017-04-01/advertisers/transactions/<advertiser_id>.<format>
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/2017-04-01/affiliates/transactions/33.csv |
| xml | Returns an XML document with an array of Transaction elements. https://mynetwork.invoca.net/api/2017-04-01/affiliates/transactions/33.xml |
| json | Returns a JSON array of transaction objects. https://mynetwork.invoca.net/api/2017-04-01/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. |
| include_columns= | comma-separated list of field names to be returned in the response for each transaction (if not specified, all available fields for the account will be returned, minus any columns in exclude_columns) |
| exclude_columns= | comma-separated list of field names to be excluded in the response for each transaction |
| 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.
We provide a helpful constant that can be used in the include_columns and exclude_columns options:
$invoca_default_columns represents the default set of columns provided by the Transactions API for your requested version
Response¶
General Parameters¶
| 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 | 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 | Duration of the call in seconds. Includes any time spent in an IVR tree before transferring to the call center. |
| ivr_duration | IVR Duration | 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. |
| start_time_network_timezone | Call Start Time Network Timezone | Start of the call in the networks’s time zone, followed by offset from GMT. |
| start_time_network_timezone_xml | Call Start Time Network Timezone (XML formatted) | Start of the call in the network’s time zone 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 |
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. |
| real_time_response | Real Time Routing Response | Response information returned to Invoca when using the real-time routing webhook. |
Examples¶
These examples use CURL, and are using the following fake OAuth API token:
| OAuth API token |
|---|
| YbcFH |
Note: the -k option asks curl to not bother checking the SSL certificate authority chain as that requires extra configuration.
Example 1: Get the next 20 transactions that occurred after transaction id C624DA2C-CF3367C3:
curl -k 'https://mynetwork.invoca.net/api/2017-04-01/affiliates/transactions/33.csv?limit=20&start_after_transaction_id=C624DA2C-CF3367C3&oauth_token=YbcFH'
Example 2: Get 50 rows from a specific time period with only the transaction_id and duration columns:
curl -k 'https://mynetwork.invoca.net/api/2017-04-01/affiliates/transactions/33.csv?limit=50&include_columns=transaction_id,duration&from=2015-03-26&to=2015-03-27&oauth_token=YbcFH'
Example 3: Get 50 rows that exclude a few columns such as city and region:
curl -k 'https://mynetwork.invoca.net/api/2017-04-01/affiliates/transactions/33.csv?limit=50&exclude_columns=city,region&start_after_transaction_id=C624DA2C-CF3367C3&oauth_token=YbcFH'
Example 4: Get All Transactions from a specific time period that are of transaction_type Signal:
curl -k 'https://mynetwork.invoca.net/api/2017-04-01/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/2017-04-01/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/2017-04-01/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/2017-04-01/affiliates/transactions/<affiliate_id>.<format>
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>¶m1=<VALUE1>¶m2=<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.
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/2017-04-01/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>¶m1=<VALUE1>¶m2=<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
call_start_time: 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 call_start_time 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: 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(deprecated): 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).
revenue: 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.
custom_parameter_1 Custom parameter. Up to 255 character string.
custom_parameter_2 Custom parameter. Up to 255 character string.
custom_parameter_3 Custom parameter. Up to 255 character string.
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/2017-02-01/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/2017-02-01/transactions/signals.json
Request Body:
{
"search": {
"transaction_id": "00000000-00000001"
},
"signal": {
"name": "sale",
"partner_unique_id": "1",
"description": "1 year contract",
"occurred_at_time": "1440607313",
"sale_amount": "100.00",
"revenue": "100.00",
"value": "true",
"custom_parameter_1": "12345",
"custom_parameter_2": "",
"custom_parameter_3": ""
},
"oauth_token": "<YOUR OAUTH TOKEN>"
}
Response Code: 201
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",
"occurred_at_time": "2015-08-26T16:41:53Z",
"sale_amount": "100.0",
"revenue": "100.0",
"value": "true",
"custom_parameter_1": "12345",
"custom_parameter_2": "",
"custom_parameter_3": ""
},
"call": {
"transaction_id": "00000000-00000001",
"start_time_t": "1435993200",
"call_start_time": "2015-07-04T07:00:00Z"
}
}
Example using call_start_time, all optional search fields, and all signal fields:
Endpoint:
https://invoca.net/api/2017-02-01/transactions/signals.json
Request Body:
{
"search": {
"call_start_time": "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": "1440607313",
"sale_amount": "100.00",
"revenue": "100.00",
"value": "true"
},
"oauth_token": "<YOUR OAUTH TOKEN>"
}
Response Code: 201
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",
"occurred_at_time": "2015-08-26T16:41:53Z",
"sale_amount": "100.0",
"revenue": "100.0",
"value": "true"
},
"call": {
"transaction_id": "00000000-00000001",
"start_time_t": "1435993200",
"call_start_time": "2015-07-04T07:00:00Z"
}
}
Examples
Example using transaction_id and providing all signal fields:
Endpoint:
https://invoca.net/api/2017-02-01/transactions/signals.json
Request Body:
{
"search": {
"transaction_id": "00000000-00000001"
},
"signal": {
"name": "sale",
"partner_unique_id": "1",
"description": "Updated description and sale amount",
"sale_amount": "200.00"
"revenue": "200.00"
},
"oauth_token": "<YOUR OAUTH TOKEN>"
}
When an update occurs, a 200 status code is returned, otherwise the response body looks the same as a create.
Response Code: 200
Response Body:
{
"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",
"occurred_at_time": "2015-08-26T16:41:53Z",
"sale_amount": "200.0",
"revenue": "200.0",
"value": "true",
"custom_parameter_1": "",
"custom_parameter_2": "",
"custom_parameter_3": ""
},
"call": {
"transaction_id": "00000000-00000001",
"start_time_t": "1435993200",
"call_start_time": "2015-07-04T07:00:00Z"
}
}
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.
Endpoint:
https://invoca.net/api/2017-02-01/transactions/<transaction_id>/signals
Examples
Example using transaction_id (of the call to associate the signal to) and providing all signal fields:
Endpoint:
https://invoca.net/api/2017-02-01/transactions/00000000-00000001/signals.json
Request Body:
{
"signal": {
"name": "sale",
"partner_unique_id": "1",
"description": "1 year contract",
"occurred_at_time": "1440607313",
"sale_amount": "100.00",
"value": "true",
"custom_parameter_1": "12345",
"custom_parameter_2": "",
"custom_parameter_3": ""
},
"oauth_token": "<YOUR OAUTH TOKEN>"
}
Response Code: 201
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",
"occurred_at_time": "2015-08-26T16:41:53Z",
"sale_amount": "100.0",
"value": "true",
"custom_parameter_1": "12345",
"custom_parameter_2": "",
"custom_parameter_3": ""
},
"call": {
"transaction_id": "00000000-00000001",
"start_time_t": "1435993200",
"call_start_time": "2015-07-04T07:00:00Z"
}
}
Examples
Example using transaction_id and providing all signal fields:
Endpoint:
https://invoca.net/api/2017-02-01/transactions/00000000-00000001/signals.json
Request Body:
{
"signal": {
"name": "sale",
"partner_unique_id": "1",
"description": "Updated description and sale amount",
"sale_amount": "200.00"
},
"oauth_token": "<YOUR OAUTH TOKEN>"
}
When an update occurs, a 200 status code is returned, otherwise the response body looks the same as a create.
Response Code: 200
Response Body:
{
"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",
"occurred_at_time": "2015-08-26T16:41:53Z",
"sale_amount": "200.0",
"value": "true",
"custom_parameter_1": "",
"custom_parameter_2": "",
"custom_parameter_3": ""
},
"call": {
"transaction_id": "00000000-00000001",
"start_time_t": "1435993200",
"call_start_time": "2015-07-04T07:00:00Z"
}
}
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 call_start_time and occurred_at_time.
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": "1440607313","sale_amount": "100.00","revenue": "100.00","value": "true"},"oauth_token": <YOUR OAUTH TOKEN>}' https://invoca.net/api/<API_VERSION>/transactions/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 call_start_time are not passed in the request, the following error will be returned.
Response (403 Forbidden):
{
"errors": {
"class": "RecordInvalid",
"invalid_data": "Validation failed: transaction_id or call_start_time 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.
Response (404 Not Found):
{
"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.
Response (403 Forbidden):
{
"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.
Response (403 Forbidden):
{
"errors": {
"class": "UnauthorizedAdvertiser",
"invalid_data": "You do not have access to this advertiser"
}
}
Updates and Idempotency¶
Signal 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
HTTP POST parameters - first 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 (201 Created):
{
"signal": {
"transaction_id": "00000000-0000000A",
"corrects_transaction_id": null,
"name": "Quote",
"partner_unique_id": "1",
"description": "Honda Accord 2015",
"occurred_at_time_t": "1440607999",
"occurred_at_time": "2015-08-26T16:53:19Z",
"value": "true"
},
"call": {
"transaction_id": "00000000-00000001",
"start_time_t": "1435993200",
"call_start_time": "2015-07-04T07:00:00Z"
}
}
HTTP POST Parameters - 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 (201 Created):
{
"signal": {
"transaction_id": "00000000-0000000B",
"corrects_transaction_id": null,
"name": "Quote",
"partner_unique_id": "2",
"description": "Toyota Camry 2015",
"occurred_at_time_t": "1440607800",
"occurred_at_time": "2015-08-26T16:50:00Z",
"value": "true",
"custom_parameter_1": "",
"custom_parameter_2": "",
"custom_parameter_3": ""
},
"call": {
"transaction_id": "00000000-00000001",
"start_time_t": "1435993200",
"call_start_time": "2015-07-04T07:00:00Z"
}
}
HTTP POST Parameters - 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 (200 OK):
{
"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",
"occurred_at_time": "2015-08-26T16:53:19Z",
"value": "true",
"custom_parameter_1": "",
"custom_parameter_2": "",
"custom_parameter_3": ""
},
"call": {
"transaction_id": "00000000-00000001",
"start_time_t": "1435993200",
"call_start_time": "2015-07-04T07:00:00Z"
}
}
Note: even though this third request was an update to the first and will appear in reports as updating the first signal, a new signal 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:
Invoca Tags¶
Invoca Tags are intended for set up at the Network level (Brands). To set up web integration code at the Advertiser level, see the Advertiser Web Integration page.
Installation Instructions¶
To set up your Invoca Tags, view the following support documentation.
InvocaJS Toolkit Library¶
The InvocaJS Toolkit is a library of JavaScript functions to help facilitate advanced implementations. The following functions can be leveraged only if you have InvocaJS installed on your site and your Invoca network has been properly configured by an Invoca Customer Success or Implementation Manager.
Note: Any method preceded with an underscore is subject to change and should not be used.
Toolkit Functions¶
readInvocaData¶
Description:¶
Searches the "invoca_session" cookie for a cached value. If the request is not found, it returns the default value or null if one is not passed.
Usage:¶
Invoca.Tools.readInvocaData(key, defaultValue)
Arguments:¶
"key" is the name of the parameter to search for.
"defaultValue" is the value returned if “key” is not found.
setCookie¶
Description:¶
Sets a cookie at the current trueDomain.
Usage:¶
Invoca.Tools.setCookie(cookieName, cookieValue, lifetimeInDays)
Arguments:¶
"cookieName" is the name of the cookie to be set.
"cookieValue" is the value of the cookie to be set.
"lifetimeInDays" is the number of days the cookie should live for.
readCookie¶
Description:¶
This function will return the value of a requested cookie by passing the cookie name.
Usage:¶
Invoca.Tools.readCookie(cookieName)
Arguments:¶
"cookieName" is the name of the cookie to read.
parseReferrer¶
Description:¶
This function uses a campaignMapping hash to search the referrer for each key in the hash and will return its value as a campaign ID. If none are found, it will return the default value.
Usage:¶
Invoca.Tools.parseReferrer(campaignMapping, defaultValue)
Arguments:¶
"campaignMapping" is a hash of strings to look for in the referrer. The key is what to look for, the value is the corresponding Campaign ID.
"defaultValue" is a string of the fallback Campaign ID that should be returned when no keys are found.
contains¶
Description:¶
This function will search for a string inside another string. It will return true if it does and false if it does not.
Usage:¶
Invoca.Tools.contains(haystack, needle)
Arguments:¶
"haystack" is the string to look in.
"needle" is the string to look for.
Looking for a needle in a haystack!
readUrl¶
Description:¶
This function will search all query strings the the URL for a key name and return it’s value.
Usage:¶
Invoca.Tools.readUrl(key)
Arguments:¶
"key" = Name of the query string parameter to look for.
deviceType¶
Description:¶
This function will attempt to return the device type of the visitor.
Usage:¶
Invoca.Tools.deviceType()
Response:¶
desktop, mobile, or tablet.
isMobile¶
Description:¶
This function will decide if the visitor is on a mobile device.
Usage:¶
Invoca.Tools.isMobile()
Response:¶
true when visitor is on a mobile phone or tablet.
false when visitor is on desktop or unknown.
waitFor¶
Description:¶
This function will wait for a function to return a value before executing the next code.
Usage:¶
Invoca.Tools.waitFor(inputFunction, callbackFunction, defaultValue, maxWaitTime)
Response:¶
inputFuction must be a function, any value returned by this function will be considered true, so return null to try again.
callbackFunction must be a function, and is called with the found value or default value passed as an argument.
defaultVaule is the value that will be passed into callbackFunction if inputFunction fails to return a value within the maxWaitTime.
maxWaitTime is the maximum amount of miliseconds to wait for inputFunction to return a value.
SolutionsJS Web Integration (Deprecated)¶
Notice: Invoca Tags is the supported way for setting up web integration (which internally uses the InvocaJS library, formerly known as SolutionsJS). View the Invoca Tags support article for installation instructions.
Installation Instructions (Deprecated)¶
Install this generalized code just above the closing </body> tag of your website.
<!-- Begin Invoca Integration -->
<script type="text/javascript" src="//solutions.invocacdn.com/js/pnapi_integration-latest.min.js"></script>
<script type="text/javascript">
Invoca.PNAPI.integration({
networkId: YOUR_NETWORK_ID,
numberSelector: ".YOUR_CLASS_SELECTOR"
});
</script>
<!-- End Invoca Integration -->
Update networkId and numberSelector to match your Invoca Network and current web page settings.
Note:
You may find your networkId pre-populated in sample code available in the Invoca platform:
Choose Tools gear and select Web Integration.
Requirements¶
- Network is PNAPI enabled.
- RingPools are type: “Custom”.
- Invoca Web Integration code installed on page.
- Phone numbers on webpage tagged with a shared numberSelector class (Accepts multiple slectors).
- An Invoca Campaign ID to associate with each number on the page (Or a Campaign ID Override).
Identifying a Campaign¶
There are three methods to identify an Invoca Campaign on your web page, which follow an order of precedence.
1. campaignIdOverrideParam: Specify a query string parameter’s name, the value of which will be used as the Invoca Campaign ID for all phone numbers in a given session.
2. destinationAsId: When true, the phone number’s digits (special characters stripped) from the numberSelector will be used as the Campaign ID.
3. data-invoca-campaign-id:
When no override is passed, a user may assign individual Invoca Campaign IDs to a specific phone number’s HTML element using the data-invoca-campaign-id attribute.
4. defaultCampaignId:
With no override, a defaultCampaignId can be passed to the Invoca.PNAPI.integration settings and will fill in the gaps wherever no data-invoca-campaign-id is found. If there are no data attributes or overrides, this value will apply to all phone numbers on the page.
Additionally, the defaultCampaignId can be assigned dynamically with JavaScript based upon the page’s environment and variables.
Client Side Parameters¶
Note: Any parameter value can be populated with a JavaScript variable.
| Required parameters: | ||
|---|---|---|
| networkId | String | Invoca Network ID |
| Required: One of the following | ||
|---|---|---|
| numberSelector | String | CSS selector for phone number HTML elements Accepts one or many like so “.invocaNumber, .phoneNumber” |
| numberToReplace | String or Hash | Default: null Specify which number(s) to replace. Can accept one or many like so: “888-999-1010, 777-888-9999”. Optionally accepts a hash with the number as a key name, and campaignId as it’s value like so: { “888-999-1010”: ‘campaignIdHere’ } |
| Optional parameters: | ||
|---|---|---|
| autoRun | Bool | Default true determines whether Invoca’s web integration runs when the page loads. If you have a single page application and would like to control when Invoca’s web integration runs, set autoRun to false and call Invoca.PNAPI.run() whenever you are ready. Note: autoRun does not have to be false in order to call Inovca.PNAPI.run(). |
| destinationAsId | Bool | Default false Strips out any special characters and uses found destination phone number’s digits as campaign ID. Warning! Requires Invoca campaign with explicit ID for each number. |
| campaignIdOverrideParam | String | Default: null Query string name used to identify Campaign ID |
| poolParams | Hash | Default: {} Set of JavaScript parameters to be captured where the key name should be RingPool parameter name. These values are updated every subsequent visit. |
| updatePoolParams | Bool | Default: true When false, the integration code will not update poolParams on subsequent page visits. |
| requiredParams | Hash | Default: null A hash of key value pairs that represent query string names and values. For example: {name: value} The integration will run if any of these are met. When a requiredParam’s value is *, any passed value will considered true. |
| cookieNames | Array | Default: null List of cookie names to automatically capture as RingPool Parameters |
| telLinkOnly | Bool | Default: false Used for a “Call Now” button. When true, will only update the tel: link on any numberSelector that is found. |
| cookieDays | Int | Default: 1 Number of days for cache TTL. |
| onComplete | Function | Default: null Name of a function to call when Invoca has finished running. Note: Do not call the function, simply pass reference. For example: functionName not functionName(). |
| debugMode | Boolean | Default: false When true, will display debug logs in the developer console. |
Examples¶
campaignIdOverrideParam¶
To use a query string parameter as the Invoca Campaign ID for all phone numbers found on page, specify the parameter name in this option. To use the value of ?utm_source as the Campaign ID, follow this example:
URL
http://www.example-page.com?utm_source=google
CODE
<!-- Begin Invoca Integration -->
<script type="text/javascript" src="//solutions.invocacdn.com/js/pnapi_integration-latest.min.js"></script>
<script type="text/javascript">
Invoca.PNAPI.integration({
networkId: YOUR_NETWORK_ID,
numberSelector: ".YOUR_CLASS_SELECTOR",
campaignIdOverrideParam: 'utm_source'
});
</script>
<!-- End Invoca Integration -->
RESULT
The caller is assigned and delivered to the “google” campaign in Invoca for any phone number found on the page with data-invoca-campaign-id’s and the defaultCampaignId being overriden.
data-invoca-campaign-id¶
To assign multiple numbers on a page to different Invoca Campaign IDs, simply add this attribute to each phone number element.
URL
http://www.example-page.com?utm_source=google
CODE
<div id="main">
Call customer service at: <span class='number' data-invoca-campaign-id='customer-service'>855-555-5555</span>
Call sales at: <span class='number' data-invoca-campaign-id='sales'>855-555-4444</span>
</div>
<!-- Begin Invoca Integration -->
<script type="text/javascript" src="//solutions.invocacdn.com/js/pnapi_integration-latest.min.js"></script>
<script type="text/javascript">
Invoca.PNAPI.integration({
networkId: YOUR_NETWORK_ID,
numberSelector: ".number"
});
</script>
<!-- End Invoca Integration -->
RESULT
When customer service is called, the call will be assigned and delivered to the ‘customer-service’ campaign in Invoca. When sales is called, it will be assigned and delivered to the ‘sales’ campaign in Invoca.
defaultCampaignId¶
When no campaignIdOverride or data-invoca-campaign-id are found, the default campaign ID will be assigned to the call.
CODE
<div id="main">
Call customer service at: <span class='number' data-invoca-campaign-id='customer-service'>855-555-5555</span>
Call sales at: <span class='number'>855-555-4444</span>
Interested in a demo? Call now! <span class='number'>855-555-4444</span>
</div>
<!-- Begin Invoca Integration -->
<script type="text/javascript" src="//solutions.invocacdn.com/js/pnapi_integration-latest.min.js"></script>
<script type="text/javascript">
Invoca.PNAPI.integration({
networkId: YOUR_NETWORK_ID,
numberSelector: ".number",
defaultCampaignId: "sales"
});
</script>
<!-- End Invoca Integration -->
RESULT
When customer service is called, the call will be assigned and delivered to the ‘customer-service’ campaign in Invoca. When sales is called, it will be assigned to the defaultCampaignId of ‘sales’. When a visitor is interested in a demo, the call will be assigned to the defaultCampaignId of ‘sales’.
poolParams¶
Allows variables from JavaScript to be associated with a call.
CODE
<!-- Begin Invoca Integration -->
<script type="text/javascript" src="//solutions.invocacdn.com/js/pnapi_integration-latest.min.js"></script>
<script type="text/javascript">
var invocaParams = {
currentPage: window.location.href
};
Invoca.PNAPI.integration({
networkId: YOUR_NETWORK_ID,
numberSelector: ".YOUR_NUMBER_SELECTOR",
poolParams: invocaParams
});
</script>
<!-- End Invoca Integration -->
RESULT
When a call is placed, the RingPool parameter with name “currentPage” will show the URL of the page the user called from.
For example, it may look like: http://www.example-page.com/contact-us
requiredParams¶
Conditionally runs Invoca’s web integration.
URL #1
http://www.example-page.com?gclid=1a2b3c4d5e
URL #2
http://www.example-page.com?ref=test
CODE
<!-- Begin Invoca Integration -->
<script type="text/javascript" src="//solutions.invocacdn.com/js/pnapi_integration-latest.min.js"></script>
<script type="text/javascript">
Invoca.PNAPI.integration({
networkId: YOUR_NETWORK_ID,
numberSelector: ".YOUR_NUMBER_SELECTOR",
requiredParams: {gclid: "*"}
});
</script>
<!-- End Invoca Integration -->
RESULT
When URL #1 is visited, the Invoca web integration will run. When URL #2 is visited, the Invoca web integration will not run.
Invoca.PNAPI.run()¶
React
componentDidMount() {
Invoca.PNAPI.run();
}
AngularJS
$scope.$on('$viewContentLoaded', Invoca.PNAPI.run);
Migrating from an older version¶
If you are migrating from SolutionsJS 1.2 or below, please refer to the following guide.
1. Update your namespaces
- Change Solutions.PNAPI.integration to Invoca.PNAPI.integration
- Change any Toolkit functions, like Solutions.PNAPI.readUrl to Invoca.Tools.readUrl
2. Update your data attributes
- Change data-invoca to data-invoca-campaign-id
- Update your integration scripts from this:
<script type="text/javascript" src="//pnapi0.invoca.net/0/pnapi_integration.js"></script>
<script type="text/javascript" src="//cdn.invoca.solutions/js/solutions-1.2.min.js">
to just this:
<script type="text/javascript" src="//solutions.invocacdn.com/js/pnapi_integration-latest.min.js"></script>
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¶
- From the Advertiser Home Page, choose Tools gear, Web Integration.
- In the Web Integration, Settings tab, enter the phone number to replace on your website.
- Click Update.
- Click “Get Code” tab to access your custom generated web integration code.
- 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¶
- 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.
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=9999999999If the URL does not have a query string, use a “?” to append the PPCPN, for example:
http://www.invoca.com?PPCPN=9999999999If 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¶
- Check that the phone number is entered in the Web Integration, Settings tab and matches the phone number on your website.
- 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.
- 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: | | |
|---|---|---|
| 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.
- 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).
- 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.).
- 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.
- Find the correct ID pairs for a given request, and make them available for the view template.
- 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.