Definitions
Campaigns
A set of configuration settings for publishers. Every campaign has a unique phone number.
Campaigns define Vertical, Call Source, Payout, the IVR prompts and Filters, as well as some other options.
Filters
Filters are questions that Price Shop Media asks callers via IVR prompts. Callers provide answers to filters via touch tone key presses (DTFM codes). Price Shop Media uses the answers to filters to find the right buyer for the call.
Assumed Answers
The answers to the filter questions are already known at the time of the call (for example, when Publisher’s IVR has already asked the customer), an Assumed answer can be configured on the Campaign. A common example of that is the answer to the “Is Insured” filter.
Payout Types
Price Shop Media supports two ways of paying Publishers for the call: Fixed payout and Revenue Share. With Fixed payout, the Publisher gets paid the same amount on every call. In Revenue Share mode, the Publisher gets a percentage of what Price Shop Media gets.
Filter Payout Adjustments
Price Shop Media can vary what it pays to Publishers based on the callers’ answers to Filters. For example, a Campaign can be configured in a way where it accepts both Insured and Uninsured callers, but the payout for uninsured callers is lowered by $1.00.
API Key
A secret key assigned to Publishers. API Keys are used to authenticate and authorize Publishers and are required for all API requests. Publishers can get their API key though Price Shop Media Dashboard by opening the “API” page at https://www.avengehub.com/PublisherApi.
API Endpoints
Price Shop Media offers JSON-over-HTTP API. All API endpoints require an API Key.
PreCall Webhook
Allows passing in ZIP code or External ID for an upcoming call
URL
It should be a POST request and it has to be issued prior to transferring the call. ZipCode and externalId parameters are optional, phoneNumber and apiKey are required
PingV1
Returns information about a campaign, including the current payout. For Revenue Share campaigns, the returned payout is based on the available buyers at the time the request was made.
All parameters are case-sensitive. ApiKey must be passed through the query string, the rest of parameters must be included in the JSON post data.
Required parameters:
● ApiKey: Publisher API Key (passed as query parameter in URL)
● CampaignId: ID of the campaign (passed in JSON body)
● ZipCode: 5 digit US ZIP Code (passed in JSON body) Optional parameters:
● FilterAnswers: a map of answers to predefined filters. See GetFilters API for details.
○ For example, answer 1 to filter with ID 45 means the roof type is Asphalt Shingle.
○ See the table below for current filters
● ExternalId: Jornaya ID or some other identifier
● CallerPhoneNumber: The caller id of the call that will be sent. Use E164 format.
● CallerAreaCode: The area code of the call that will be sent.
● Origin - call origin information (see more details below)
● CustomerData: customer information (see more details below). All of the customer fields are optional.
● MaximumResponseTimeInMilliseconds: maximum response time in milliseconds, must be greater than or equal to 500. If omitted you should expect most responses within 3000 milliseconds
URL
● Production: https://www.avengehub.com/Api/PingV1?apiKey=<API_KEY>
● Test: https://www.test.avengehub.com/Api/PingV1?apiKey=<API_KEY>
HTTP POST Body Format
The body of the post request must be encoded using JSON format.
Content-Type=application/json HTTP header must be provided
{
"CampaignId": 50,
"ZipCode": "90210",
"FilterAnswers": [
{
"FilterId": 45,
"Answer": 1
}
],
"ExternalId": "DE7F3383-5AFC-4035-AC0E-F12943D49D5D",
"CallerPhoneNumber": "+12345551234",
"CallerAreaCode": "234", "Origin": {
"Source": "source of call goes here", "SubSource": "sub-source of call goes here", "Campaign": "campaign of call goes here", "IpAddress": "ip address of call goes here",
"JornayaId": "FA8D1EBB-8CC4-5F0F-3FE2-E1DA6AF2FFA4",
"TrustedFormCertificateUrl": "https://cert.trustedform.com/1234567890123456789012345678901234567890"
},
"CustomerData": { "FirstName": "John",
"LastName": "Smith",
"Address": "7 Elm St",
"City": "San Juan Capistrano", "ZipCode": "92694",
"State": "CA",
"Email": "[email protected]", "Birthdate": "1979-01-24",
"ContactPhoneNumber": "+19163334499", "CreditStatusType": "Good", "SmsOptIn": false,
"HomeServices": { "SubCategoryType": "NewReRoof", "Roofers": {
"RoofType": "AsphaltShingle"
}
}
},
"MaximumResponseTimeInMilliseconds": 5000
}
Response
{
"Id": "77e350d4-7c38-4f66-afdb-67f862e772c8",
"CampaignId": 50,
"PhoneNumber": "+16156148492",
"Expiration": "2024-06-18T02:33:58.2741841Z",
"PayoutType": "RevShare",
"CampaignName": "Test Pest Control Campaign (used in API docs)", "PublisherName": "Test Publisher",
"AssumedFilterAnswers": [
{
"FilterId": 45,
"Answer": 1
}
],
"FilterPayoutAdjustments": [
{
"FilterId": 45,
"Answer": 1,
"Amount": -1
}
],
"Payout": {
"Amount": 25.00,
"QualifiedDurationInSeconds": 120, "CompanyName": null, "IsCustomerDataRequiredForPost": false, "LicenseNumber": "stub_license_number",
}
}
Payout will be null if the ping was not accepted. LicenseNumber or CompanyName will be returned if Price Shop Media has it.
PhoneNumber value will be dynamic and will vary from ping to ping. The call should be transferred to the returned phone number if you intend to sell us the call by the time specified in Expiration.
Response Details
Payout
If Price Shop Media has a buyer, the response will have a non-null Payout property. The fields in Payout object are:
Amount: The amount in USD that Price Shop Media will pay for a qualified call QualifiedDurationInSeconds: minimum duration of the call to be qualified CompanyName: the name of the company where the call be transferred
IsCustomerDataRequiredForPost: true if CustomerData value is required on the consequent PostV1 request (when the buyer requires it).
LicenseNumber: Agent’s license number. It will be returned if we have it.
AssumedFilterAnswers
JSON array of objects that represents assumed answers configured for the campaign. Use GetFilters API to see what each filter represents.
FilterId
ID of the filter
Answer
The assumed answer for the filter
FilterPayoutAdjustments
JSON array that represents adjustments to the payout based on filter answers.
FilterId: ID of the filter
Answer: The required answer
Amount: The amount of adjustment
Error Response Details
Errors will return non-200 response codes with Content-Type of text/plain. The error details will be in the response body as plain text.
Testing
For testing purposes, you can use our test site at https://www.test.avengehub.com/. The URLs are the following:
● PostV1: https://www.test.avengehub.com/Api/PostV1 You need to use the following credentials:
● “ApiKey”: “7c44e7e252b24a9c87014d45a3ce295a”
● “CampaignId”:
○ Bathroom remodeling: 47
○ Kitchen remodeling: 48
○ Pest control: 49
○ Plumbers: 50
○ Roofers: 51
Using any ZIP code outside of the state of Washington will result in a response with a payout. Using a ZIP code in the state of Washington will result in a response without a payout.
You can use the following phone number to test inbound calls: (918) 913-0021
PostV1
This API Endpoint is for publishers to notify Price Shop Media of intent to sell the call and/or provide additional information about the call before transferring it.
Required parameters:
● ApiKey: Publisher API Key (passed as query parameter in URL)
● Id: Id returned by PingV1 API (passed in JSON body)
● CallerPhoneNumber: The caller id of the call that will be sent. Use E164 format. (passed in JSON body)
Optional parameters:
● ExternalId: Jornaya ID or some other identifier
● CustomerData - customer information (see more details below)
● Origin - call origin information (see more details below)
URL
● Production: https://www.avengehub.com/Api/PostV1?apiKey=<API_KEY>
● Test: https://www.test.avengehub.com/Api/PostV1?apiKey=<API_KEY>
HTTP POST Body Format
The body of the post request must be encoded using JSON format.
Content-Type=application/json HTTP header must be provided
{
"Id": "77e350d4-7c38-4f66-afdb-67f862e772c8",
"CallerPhoneNumber": "+11257418518",
"ExternalId": "DE7F3383-5AFC-4035-AC0E-F12943D49D5D",
"CustomerData": { "FirstName": "John",
"LastName": "Smith",
"Address": "7 Elm St",
"City": "San Juan Capistrano", "ZipCode": "92694",
"State": "CA",
"Email": "[email protected]", "Birthdate": "1979-01-24",
"ContactPhoneNumber": "+19163334499", "CreditStatusType": "Good", "SmsOptIn": false,
"HomeServices": { "SubCategoryType": "NewReRoof", "Roofers": {
"RoofType": "AsphaltShingle"
}
}
},
"Origin": {
"Source": "source of call goes here", "SubSource": "sub-source of call goes here", "Campaign": "campaign of call goes here", "Url": "url of call goes here",
"IpAddress": "ip address of call goes here"
}
}
ExternalId field can be any string up to 50 characters long that identifies the lead to the publisher. It’s optional.
Origin
The following fields are supported: (all are optional)
● Source
● SubSource
● SubSource2
● SubSource3
● SubSource4
● SubSource5
● Campaign
● Url
● IpAddress
Response
{
"IsAccepted": true, "Errors": null, "ExpirationInSeconds": 60
}
Response Details
IsAccepted will reflect whether or not the posted request was accepted or not. Errors will contain any errors for valid requests that were not accepted ExpirationInSeconds will indicate how long the response is valid.
Error Response Details
Errors will return non-200 response codes with Content-Type of text/plain. The error details will be in the response body as plain text.
Testing
For testing purposes, you can use our test site at https://www.test.avengehub.com/. The URLs are the following:
● PostV1: https://www.test.avengehub.com/Api/PostV1 You need to use the following credentials:
● “ApiKey”: “7c44e7e252b24a9c87014d45a3ce295a”
CustomerData
Fields:
● FirstName: consumer’s first name (string)
● LastName: consumer’s last name (string)
● Address: consumer’s address (string)
● City: consumer’s city (string)
● ZipCode: 5 digit ZIP code (string)
● Email: consumer’s email address (string)
● ContactPhoneNumber: consumer’s contact phone number. Use E164 format. (string)
● State: consumer’s 2-character state code (string)
● Birthdate consumer’s date of birth in yyyy-MM-dd format (string)
● CreditStatusType: consumer’s current credit status (see below for values)
● IpAddress: consumer’s IP address (string)
● HomeServices: home services information (see below)
CreditStatusType values:
● Good
● Okay
● Poor
● BelowAverage
● Excellent HomeServices fields:
Category | SubCategoryType Values |
Bathroom Remodeling | BathroomRemodeling, BathInstallation, WalkInTubsShowers |
Pest Control | AnimalControl, BedBugExtermination, Exterminator, ExterminatingFumigation, PestControl, PestControlCommercial, PestControlResidential, TermiteControl, TermiteInspections, WildlifeRemoval |
Plumbers | BackflowPreventers, CommercialPlumbing, DrainCleaningUnclogging, FixturesInstalled, FloorLaundryDrains, FrozenPipesDrainsThawed, GarbageDisposals, GasLinesInstalledRepaired, GeneralPlumbingRepair, HydroJettingService, InlineVideoCameraService, LeaksDetectedRepaired, PipeReplacementsRepairs, Plumbers, PlumbingForMobileHomes, PlumbingInspection, PoolSpaJacuzziService, RadiantFloorSystems, SewerLines, ShowersTubs, SinksToiletsFaucets, SumpPumpsInstalledRepaired, UndergroundPipeRepairs, WaterHeatersStandard, WaterHeatersTankless, WaterLinesInstalledRepaired, WaterPressureProblems, WaterPurificationFilters, WellPumpsInstalledRepaired, Winterization |
Roofers | CappingFlashing, CommercialRoofing, GeneralRoofRepairs, NewReRoof, ResidentialRoofing, RoofCertifications, RoofCleaning, RoofDrainageRepitching, Roofers, RoofLeakRepair, Skylights, SprayFoamRoofing, VentilationRidgeVents |
Electrical | Electrical, ContractorsElectrical |
Home Security | HomeSecurity, SafeVaults, Locksmith |
Home Services | AppliancesRepair, Cabinets, CarpetRugInstallation, CarpetRugUpholsteryCleaners, ConstructionSuppliesServices, DamageRestoration, Doors, FireRestoration, FireWaterDamage, FireWaterDamageRestoration, Flooring, GarageDoor, GeneralContractors, Gutters, HandymanServices, Landscaping, MajorServiceRepairInstallation, Painting, ProfessionalMovingService,Siding, SmallServiceRepair, Solar, Tile, TreeService, WasteManagement, WaterDamage, WaterProofing, Windows, WindowGlassRepair, WindowsAluminumMetal, WindowsInstallationSales, WindowsVinyl, WindowsWood |
HVAC | HeatingEquipmentSystems, HeatingEquipmentSystemsRepairing, HeatingVentilatingContractors, HeatingVentilationAirConditioning, HVAC |
Contractors | ContractorsCarpentry, ContractorsConcrete, ContractorsDeckPatio, ContractorsDrywall, ContractorsElectrical, ContractorsFoundation, ContractorsInsulation, ContractorsMasonry, ContractorsPaving, ContractorsSiding, ContractorsTile |
RoofType values |
AsphaltShingle, CompositionShingle, WoodShingle, TileShingle, Metal, Concrete, Other, CedarWood, ClayTile, FlatRubberHotAsphalt, NaturalSlate |
All of the fields are optional on the ping.
The following fields are required on the post for transfers:
● FirstName
● LastName
● Address
● City
● ZipCode
● ContactPhoneNumber
Available Filters
To see what filters we support, please visit “Publisher API” page at https://www.avengehub.com/PublisherApi (you will have to log in with your Publisher account).
Below is a sample list of filters relevant to home services.
Filter ID | Name | Is inverse | Valid answers | Prerequisite |
45 | Roof Type |
| 1 - Asphalt Shingle |
|
|
|
| 2 - Composition Shingle 3 - Wood Shingle 4 - Tile Shingle 5 - Metal 6 - Concrete 7 - Other 8 - Cedar/Wood 9 - Clay/Tile 10 - Flat/Rubber/Hot Asphalt 11 - Natural Slate |
|
Examples
Minimal Ping (Roofers)
{
"CampaignId": 51,
"ZipCode": "90210",
}
Minimal Post (Roofers)
{
"Id": "77e350d4-7c38-4f66-afdb-67f862e772c8",
"CallerPhoneNumber": "+11257418518",
"ExternalId": "DE7F3383-5AFC-4035-AC0E-F12943D49D5D"
}
Full Ping (Roofers)
{
"CampaignId": 51,
"ZipCode": "90210",
"ExternalId": "DE7F3383-5AFC-4035-AC0E-F12943D49D5D",
"CallerPhoneNumber": "+12345551234",
"CallerAreaCode": "234", "CustomerData": {
"FirstName": "John",
"LastName": "Smith",
"Address": "7 Elm St",
"City": "San Juan Capistrano", "ZipCode": "92694",
"State": "CA",
"Email": "[email protected]", "Birthdate": "1979-01-24",
"ContactPhoneNumber": "+19163334499", "CreditStatusType": "Good", "SmsOptIn": false,
"HomeServices": { "SubCategoryType": "NewReRoof", "Roofers": {
"RoofType": "AsphaltShingle"
}
}
},
"MaximumResponseTimeInMilliseconds": 5000
}
Full Post (Roofers)
{
"CampaignId": 50,
"ZipCode": "90210",
"FilterAnswers": [
{
"FilterId": 45,
"Answer": 1
}
],
"ExternalId": "DE7F3383-5AFC-4035-AC0E-F12943D49D5D",
"CallerPhoneNumber": "+12345551234",
"CallerAreaCode": "234", "CustomerData": {
"FirstName": "John",
"LastName": "Smith",
"Address": "7 Elm St",
"City": "San Juan Capistrano", "ZipCode": "92694",
"State": "CA",
"Email": "[email protected]", "Birthdate": "1979-01-24",
"ContactPhoneNumber": "+19163334499", "CreditStatusType": "Good", "SmsOptIn": false,
"HomeServices": { "SubCategoryType": "NewReRoof", "Roofers": {
"RoofType": "AsphaltShingle"
}
}
}
}