API Reference
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.
Full API endpoint documentation can be found here: Optimise Network API Docs
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 querystring 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 |
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.