API
Introduction
Optimise Network API for Publishers & Advertisers allows programmatic access to the functionality of Insights Dashboard. This documentaton is written according to Open API 3.0 specifications.
API Reference
Full API endpoint documentation can be found here: API Reference Docs
Add the Optimise API Skill to your agent to assist with integration.
Authentication
To authenticate an apikey must be specified in the header of the request.
The API Key can be generated by creating a Service Account in Insights Dashboard. Navigate to Admin > Service Accounts
In addition you must include the following 2 query string parameters with every request:
?contactId={AID/MID}&agencyId={agencyId}
You can locate your AID or MID from within your account here:
And lookup your agencyId here.
Reference Tables
The following reference tables may be required when querying the API.
CountryId
| Country Name | Country Code | CountryID |
|---|---|---|
| Afghanistan | AF | 31 |
| Albania | AL | 32 |
| Algeria | DZ | 33 |
| American Samoa | AS | 34 |
| Andorra | AD | 35 |
| Angola | AO | 36 |
| Anguilla | AI | 37 |
| Antarctica | AQ | 38 |
| Antigua & Barbuda | AG | 39 |
| Argentina | AR | 40 |
| Armenia | AM | 41 |
| Aruba | AW | 42 |
| Australia | AU | 22 |
| Austria | AT | 14 |
| Azerbaijan | AZ | 43 |
| Bahamas | BS | 44 |
| Bahrain | BH | 45 |
| Bangladesh | BD | 30 |
| Barbados | BB | 46 |
| Belarus | BY | 47 |
| Belgium | BE | 11 |
| Belize | BZ | 48 |
| Benin | BJ | 49 |
| Bermuda | BM | 50 |
| Bhutan | BT | 51 |
| Bolivia | BO | 52 |
| Bosnia & Herzegowina | BA | 53 |
| Botswana | BW | 54 |
| Bouvet Island | BV | 55 |
| Brazil | BR | 56 |
| Brunei Darussalam | BN | 57 |
| Bulgaria | BG | 58 |
| Burkina Faso | BF | 59 |
| Burundi | BI | 60 |
| Cambodia | KH | 61 |
| Cameroon | CM | 62 |
| Canada | CA | 23 |
| Cape Verde | CV | 63 |
| Cayman Islands | KY | 64 |
| Central African Republic | CF | 65 |
| Chad | TD | 66 |
| Channel Islands | GB | 229 |
| Chile | CL | 67 |
| China | CN | 68 |
| Christmas Island | CX | 69 |
| Colombia | CO | 70 |
| Congo | CG | 71 |
| Cook Islands | CK | 72 |
| Costa Rica | CR | 73 |
| Cote D'ivoire | CI | 74 |
| Croatia | HR | 75 |
| Cuba | CU | 76 |
| Curaçao | CW | 234 |
| Cyprus | CY | 77 |
| Czech Republic | CZ | 15 |
| Denmark | DK | 9 |
| Djibouti | DJ | 78 |
| Dominica | DM | 233 |
| Dominican Republic | DO | 79 |
| East Timor | TL | 80 |
| Ecuador | EC | 81 |
| Egypt | EG | 82 |
| El Salvador | SV | 83 |
| Equatorial Guinea | GQ | 84 |
| Eritrea | ER | 85 |
| Estonia | EE | 86 |
| Ethiopia | ET | 87 |
| Falkland Islands | FK | 88 |
| Faroe Islands | FO | 89 |
| Fiji | FJ | 90 |
| Finland | FI | 91 |
| France | FR | 2 |
| French Guiana | GF | 92 |
| French Polynesia | PF | 93 |
| French Southern Territories | TF | 94 |
| Gabon | GA | 95 |
| Gambia | GM | 96 |
| Georgia | GE | 97 |
| Germany | DE | 3 |
| Ghana | GH | 98 |
| Gibraltar | GI | 28 |
| Global | GO | 228 |
| Greece | GR | 25 |
| Greenland | GL | 99 |
| Grenada | GD | 100 |
| Guadeloupe | GP | 101 |
| Guam | GU | 102 |
| Guatemala | GT | 103 |
| Guinea | GN | 104 |
| Guinea-bissau | GW | 105 |
| Guyana | GY | 106 |
| Haiti | HT | 107 |
| Honduras | HN | 108 |
| Hong Kong | HK | 27 |
| Hungary | HU | 16 |
| Iceland | IS | 109 |
| India | IN | 26 |
| Indonesia | ID | 110 |
| Iran | IR | 111 |
| Iraq | IQ | 112 |
| Ireland | IE | 10 |
| Israel | IL | 113 |
| Italy | IT | 4 |
| Ivory Coast | ||
| CI | 232 | |
| Jamaica | JM | 114 |
| Japan | JP | 115 |
| Jordan | JO | 116 |
| Kazakhstan | KZ | 117 |
| Kenya | KE | 118 |
| Kiribati | KI | 119 |
| Kuwait | KW | 121 |
| Kyrgyzstan | KG | 122 |
| Lao People's Democratic Republic | LA | 123 |
| Latvia | LV | 124 |
| Lebanon | LB | 125 |
| Lesotho | LS | 126 |
| Liberia | LR | 127 |
| Libya | LY | 128 |
| Liechtenstein | LI | 129 |
| Lithuania | LT | 130 |
| Luxembourg | LU | 19 |
| Macau | MO | 131 |
| Macedonia | MK | 132 |
| Madagascar | MG | 133 |
| Malawi | MW | 134 |
| Malaysia | MY | 135 |
| Maldives | MV | 136 |
| Mali | ML | 137 |
| Malta | MT | 138 |
| Marshall Islands | MH | 139 |
| Martinique | MQ | 140 |
| Mauritania | MR | 141 |
| Mauritius | MU | 142 |
| Mayotte | YT | 143 |
| Mexico | MX | 144 |
| Micronesia | FM | 145 |
| Moldova | MD | 146 |
| Monaco | MC | 147 |
| Mongolia | MN | 148 |
| Montenegro | ME | 230 |
| Montserrat | MS | 149 |
| Morocco | MA | 150 |
| Mozambique | MZ | 151 |
| Myanmar | MM | 152 |
| Namibia | NA | 153 |
| Nauru | NR | 154 |
| Nepal | NP | 155 |
| Netherlands | NL | 12 |
| New Caledonia | NC | 156 |
| New Zealand | NZ | 24 |
| Nicaragua | NI | 157 |
| Niger | NE | 158 |
| Nigeria | NG | 159 |
| Niue | NU | 160 |
| Norfolk Island | NF | 161 |
| Northern Mariana Islands | MP | 162 |
| Norway | NO | 8 |
| Oman | OM | 163 |
| Pakistan | PK | 29 |
| Palau | PW | 164 |
| Palestinian Territory | NULL | 166 |
| Panama | PA | 165 |
| Papua New Guinea | PG | 167 |
| Paraguay | PY | 168 |
| Peru | PE | 169 |
| Philippines | PH | 170 |
| Pitcairn | PN | 171 |
| Poland | PL | 21 |
| Portugal | PT | 13 |
| Puerto Rico | PR | 173 |
| Qatar | QA | 174 |
| Reunion | RE | 175 |
| Romania | RO | 176 |
| Russian Federation | RU | 177 |
| Rwanda | RW | 178 |
| Saint Kitts & Nevis | KN | 179 |
| Saint Lucia | LC | 180 |
| Saint Vincent & The Grenadines | VC | 181 |
| Samoa | WS | 182 |
| San Marino | SM | 183 |
| Sao Tome & Principe | ST | 184 |
| Saudi Arabia | SA | 185 |
| Senegal | SN | 186 |
| Serbia | RS | 225 |
| Seychelles | SC | 187 |
| Sierra Leone | SL | 188 |
| Singapore | SG | 189 |
| Slovakia (Slovak Republic) | SK | 190 |
| Slovenia | SI | 191 |
| Solomon Islands | SB | 192 |
| Somalia | SO | 193 |
| South Africa | ZA | 194 |
| South Georgia & The S. S. Islands | GS | 195 |
| South Korea | KR | 120 |
| Spain | ES | 5 |
| Sri Lanka | LK | 196 |
| St. Helena | SH | 197 |
| St. Pierre & Miquelon | PM | 198 |
| Sudan | SD | 199 |
| Swaziland | SZ | 200 |
| Sweden | SE | 7 |
| Switzerland | CH | 18 |
| Syrian Arab Republic | SY | 201 |
| Taiwan | TW | 202 |
| Tajikistan | TJ | 203 |
| Tanzania | TZ | 204 |
| Thailand | TH | 205 |
| Togo | TG | 206 |
| Tokelau | TK | 207 |
| Tonga | TO | 208 |
| Trinidad & Tobago | TT | 209 |
| Tunisia | TN | 210 |
| Turkey | TR | 211 |
| Turkmenistan | TM | 212 |
| Turks & Caicos Islands | TC | 213 |
| Tuvalu | TV | 214 |
| Uganda | UG | 215 |
| Ukraine | UA | 216 |
| United Arab Emirates | AE | 217 |
| United Kingdom | GB | 1 |
| United States | US | 20 |
| Uruguay | UY | 218 |
| Uzbekistan | UZ | 219 |
| Vanuatu | VU | 220 |
| Venezuela | VE | 221 |
| Vietnam | VN | 222 |
| Virgin Islands | VG | 223 |
| Yemen | YE | 224 |
| Zambia | ZM | 226 |
| Zimbabwe | ZW | 227 |
CurrencyId
| Currencycode | CurrencyID |
|---|---|
| AED | 33 |
| ARS | 41 |
| AUD | 8 |
| BDT | 28 |
| BGN | 49 |
| BHD | 36 |
| BND | 43 |
| BRL | 18 |
| CAD | 9 |
| CHF | 13 |
| CLP | 30 |
| CNY | 23 |
| COP | 32 |
| CZK | 15 |
| DKK | 5 |
| DZD | 62 |
| EGP | 40 |
| EUR | 2 |
| GBP | 1 |
| GHS | 54 |
| HKD | 12 |
| HRK | 66 |
| HUF | 22 |
| IDR | 19 |
| ILS | 21 |
| INR | 11 |
| JMD | 46 |
| JOD | 38 |
| JPY | 27 |
| KES | 55 |
| KHR | 69 |
| KRW | 25 |
| KWD | 56 |
| KZT | 70 |
| LBP | 57 |
| MAD | 35 |
| MOP | 44 |
| MUR | 58 |
| MXN | 31 |
| MYR | 16 |
| NGN | 59 |
| NOK | 4 |
| NZD | 10 |
| OMR | 37 |
| PEN | 42 |
| PHP | 20 |
| PKR | 34 |
| PLN | 7 |
| QAR | 39 |
| RON | 67 |
| RSD | 65 |
| RUB | 26 |
| SAR | 60 |
| SEK | 3 |
| SGD | 14 |
| THB | 17 |
| TND | 63 |
| TRY | 52 |
| TTD | 47 |
| TWD | 45 |
| UAH | 68 |
| UGX | 61 |
| USD | 6 |
| UYU | 50 |
| VND | 24 |
| XAF | 53 |
| XCD | 51 |
| XOF | 64 |
| ZAR | 48 |
AgencyId
| Agency Name | AgencyId |
|---|---|
| Optimise Australia & New Zealand | 47 |
| Optimise MENA | 172 |
| Optimise SE Asia | 118 |
| Optimise UK | 1 |
| Optimise Global | 131 |
SectorId
| Sector Name | SectorId |
|---|---|
| Activities | 155 |
| Airport Parking | 11 |
| Animal Charities | 92 |
| Appliances | 166 |
| Beauty Products | 85 |
| Betting & Gaming | 13 |
| Books, Films & Music | 49 |
| Breakdown Insurance | 14 |
| Broadband | 47 |
| Bus Tickets | 124 |
| Business Credit Cards | 97 |
| Business Finance | 96 |
| Business Insurance | 95 |
| Business Loans | 99 |
| Business Mortgages | 98 |
| Business to Business Services | 110 |
| Car Hire | 16 |
| Car Insurance | 1 |
| Caravan Insurance | 43 |
| Cars | 81 |
| Children's Charities | 91 |
| Children's Clothes | 116 |
| Clothes | 18 |
| Commerical Vehicle Insurance | 80 |
| Computers & Software | 55 |
| Consumer deals | 104 |
| Credit Cards | 19 |
| Currency Exchange | 112 |
| Current Accounts | 40 |
| Cycling | 173 |
| Dating | 76 |
| Debt Management | 20 |
| Digital TV & VoD | 21 |
| DIY | 171 |
| Domain Name Registration | 22 |
| Education & Courses | 121 |
| Electronics | 82 |
| Energy Providers | 23 |
| EventTickets | 150 |
| Eyewear | 164 |
| Fashion Accessories | 84 |
| Ferries | 24 |
| Flights | 25 |
| Flowers | 170 |
| Food & Drink | 58 |
| Footwear | 163 |
| Furniture & Accessories | 64 |
| Games, Consoles & Toys | 83 |
| Garden Supplies | 169 |
| Health & Fitness Services | 61 |
| Health Insurance | 36 |
| Holidays | 26 |
| Home Appliance Cover | 8 |
| Home Insurance | 2 |
| Horoscopes | 115 |
| Hostels | 125 |
| Hotels | 28 |
| Household | 175 |
| International Aid | 93 |
| Investments & Shares | 29 |
| Jewellery & Watches | 86 |
| Job Listings | 154 |
| Leasing | 109 |
| Life Insurance | 3 |
| Loans | 113 |
| Miscellaneous | 105 |
| Mobile - Pay as You Go | 158 |
| Mobile - Sim only | 156 |
| Mobile Contract | 32 |
| Mobilty Accessories | 174 |
| Mortgages | 9 |
| Motorbike Insurance | 6 |
| Motorbikes | 172 |
| News Media | 153 |
| Office Supplies | 111 |
| Payday Loans | 107 |
| Payment Protection Insurance | 7 |
| Pet Insurance | 33 |
| Pet Supplies | 168 |
| Phones, Tablets & Accessories | 157 |
| Photos | 167 |
| Pre-paid Cards | 101 |
| Rail | 88 |
| Real Estate | 119 |
| Savings | 75 |
| Secured Loans | 30 |
| Society & Health | 94 |
| Specialist Insurance | 103 |
| Sport & Fitness Equipment | 87 |
| Sportswear | 165 |
| Surveys | 117 |
| Takeaway/Restaurant | 123 |
| Tax | 114 |
| Taxi | 122 |
| Telecoms | 27 |
| Travel Insurance | 4 |
| Travel Money Services | 102 |
| Unsecured Loans | 31 |
| Web Hosting | 35 |
Rejection Codes
| rejectionCode | Description |
|---|---|
| 202 | Goods returned, transaction voided |
| 204 | Another marketing channel was credited with the sale |
| 205 | Order cancelled or returned |
| 207 | Transaction not fully completed online |
| 208 | Another marketing channel was credited with the sale due to a voucher/discount code |
| 209 | Did not meet the terms and conditions set by the merchant |
| 214 | Breach of IAB Voucher Code code of conduct |
| 216 | No transaction recorded / cannot be traced |
| 217 | No voucher or discount codes so commission not paid for these transactions |
| 218 | Non qualifying discount code so commission only paid for qualifying discount codes |
| 220 | Account payment issues |
| 223 | Exceeded sales per year limit |
| 224 | Suspicious activity |
| 225 | Other |
| 226 | Duplicate sale |
| 227 | Test Sale |
| 234 | No commissionable items purchased |
File Explorer CategoryId
| CategoryName | CategoryID |
|---|---|
| Validation | 1 |
| Transaction Enquiries | 2 |
| Misc | 3 |
| Cashback Enquiries | 4 |
| Reward Enquiries | 5 |
| Validations Return | 6 |
| Campaign Performance | 7 |
| Conversion Enquiries | 8 |
| TQM | 9 |
| Converison Enquiries Export | 10 |
| Validation File Export | 11 |
| Media Packs | 12 |
| Third Party Validations | 13 |
| Third Party Validation Items | 14 |
Voucher CategoryId
| CategoryName | CategoryID |
|---|---|
| Apparel and Accessories | 32 |
| Automotive | 33 |
| Beauty and Personal Care | 34 |
| Books and Stationary | 35 |
| Bus Tickets | 36 |
| Cameras and Accessories | 37 |
| Cashback | 72 |
| Computers, Laptops and Gaming | 38 |
| Dinning | 67 |
| Electronics | 39 |
| Entertainment | 40 |
| Fashion | 64 |
| Finance | 65 |
| Flowers and Gifts | 41 |
| Food and Beverages | 42 |
| Footwear | 43 |
| Grocery | 44 |
| Health | 45 |
| Home and Decor | 46 |
| Home and Kitchen | 47 |
| Hotels | 48 |
| Industrial Supplies | 60 |
| Innerwear and Swimwear | 49 |
| Insurance | 66 |
| Jewellery and Coins | 50 |
| Kids and Babies | 51 |
| Lifestyle | 69 |
| Miscellaneous | 61 |
| Mobile Recharge and Bill Payment | 52 |
| Mobiles and Tablets | 53 |
| Musical Instruments | 54 |
| Other | 63 |
| Retail | 70 |
| Shopping | 71 |
| Spa & Wellness | 68 |
| Sports and Fitness | 56 |
| Travel and Tours | 57 |
| Utility Appliances | 58 |
Reporting Measures
Measures which can be passed to the reporting endpoint. As noted below, some measures may be restricted according to your account type or settings.
| Measure | Restrictions |
|---|---|
| applicationDeclineEvent | Advertisers only |
| applicationEndEvent | Advertisers only |
| applicationReferralEvent | Advertisers only |
| applicationStartEvent | Advertisers only |
| assistedConversionRate | None |
| assistedConversions | None |
| averageCommission | May be restricted based on your account settings |
| averageCost | Advertisers only |
| averageOrderValue | None |
| averageValidatedCost | Advertisers only |
| basketEvent | Advertisers only |
| clickCommission | May be restricted based on your account settings |
| clickCost | Advertisers only |
| clicks | None |
| commissionpending | None |
| completedApplications | May be restricted based on your account settings |
| contentPageEvent | Advertisers only |
| conversionRate | None |
| ctr | None |
| ecpm | None |
| epc | None |
| estimatedValidatedCommission | None |
| estimatedValidatedConversions | None |
| estimatedValidatedNetCost | Advertisers only |
| homepageEvent | Advertisers only |
| impressions | None |
| landingPageEvent | Advertisers only |
| originalOrderValue | None |
| pendingCommission | May be restricted based on your account settings |
| pendingConversions | None |
| pendingNetCost | Advertisers only |
| pendingReturnOnAdSpend | None |
| pendingReturnOnInvestment | None |
| quoteEvent | Advertisers only |
| quoteStartEvent | Advertisers only |
| rejectedCommission | May be restricted based on your account settings |
| rejectedConversionRate | None |
| rejectedConversions | None |
| rejectedNetCost | Advertisers only |
| returnOnAdSpend | Advertisers only |
| returnOnInvestment | Advertisers only |
| totalCommission | None |
| totalConversions | None |
| totalNetCost | Advertisers only |
| uniqueVisitors | None |
| validatedCommission | May be restricted based on your account settings |
| validatedConversionCommission | May be restricted based on your account settings |
| validatedConversionCost | Advertisers only |
| validatedConversionRate | None |
| validatedConversions | None |
| validatedCost | None |
| validatedNetCost | Advertisers only |
| validationRate | None |
| sourcestatus (Validated Order Value) | None |
Reporting Dimensions
Dimensions which can be passed to the reporting endpoint. As noted below, some dimensions may be restricted according to your account type or settings.
| Dimension | Restrictions |
|---|---|
| adContainerId | None |
| adContainerName | None |
| adUnitHeight | None |
| adUnitId | None |
| adUnitPath | None |
| adUnitTypeName | None |
| adUnitWidth | None |
| advertiserId | None |
| advertiserName | None |
| agencyId | None |
| campaignCountry | None |
| campaignGroup | Advertisers only |
| campaignGroupId | None |
| campaignId | None |
| campaignName | None |
| campaignStatus | None |
| campaignType | Advertisers only |
| campaignTypeId | None |
| city | None |
| countryCode | None |
| countryName | None |
| currencyCode | None - Campaign Currency |
| customerType | None |
| date | None |
| dateId | None |
| dayName | None |
| deviceType | None |
| deviceTypeCount | None |
| hour | None |
| invoiceDate | None |
| invoiceDateId | None |
| InvoiceDayName | None |
| invoiceMonth | None |
| invoiceMonthName | None |
| invoiceMonthNo | None |
| invoiceQuarter | None |
| invoiceWeek | None |
| invoiceWeekCommencing | None |
| invoiceYear | None |
| itemCategory | None |
| itemPolicyType | None |
| minute | None |
| month | None |
| monthName | None |
| monthNo | None |
| operatingSystem | None |
| partnerType | None |
| PID | None |
| placementDesc | None |
| placementId | None |
| placementName | None |
| placementType | None |
| primaryVertical | None |
| primaryVerticalId | None |
| publisherId | None |
| publisherName | May be restricted based on your account settings |
| publisherType | None |
| quarter | None |
| quoteAction | None |
| regionName | None |
| secondaryVertical | None |
| secondaryVerticalId | None |
| trackingType | None |
| voucherCode | None |
| websiteName | May be restricted based on your account settings |
| websiteUrl | May be restricted based on your account settings |
| week | None |
| weekCommencing | None |
| year | None |
Rate Limits & Quotas
By default all users are restricted to a maximum of 5 requests per minute. In addition, user accounts using excessive resources may have additional rate limiting applied.
If you have a use-case for these limits to be raised please raise a support ticket.