Overview

O.N.E API v2

This is version 2 of the O.N.E API. In version 2, the advertiser creates its Opt-Out Lists in SUPPRESS (see Manage Opt-Out Lists), your platform fetches them with Get Opt-Out Lists, and sends the returned optoutlist_id as optout_id. optout_name is not sent, and lists are never created or renamed through the API. If your platform is registered as version 1, read O.N.E API v1 instead.

Which version am I? Optizmo sets the version when your platform is registered, and it applies to every request your Reference Code (ref) makes. Ask Optizmo support if you are not sure. One sign you can read without changing anything: the Account report lists an optizmo_id for each Opt-Out List only for a version 2 platform.

The Optizmo Network Engagement (O.N.E) API lets an affiliate tracking platform keep a SUPPRESS account in step with the advertisers, offers and affiliates it manages. Your platform creates and updates advertisers, Opt-Out Lists, campaigns and affiliates in the account, and receives for each affiliate on each campaign the two things the affiliate needs: a Mailer Access Key to download the suppression list, and an Opt-Out link to place in creatives. On a standard list the key is a MAK (m-...); on a linked list, which downloads another account’s list, it is an SMAK (sm-...).

Base URL

Every call is an HTTP GET to

https://one.optizmo.net/api.cgi

with the operation selected by the action query parameter and all other values passed as query parameters. Values must be URL-encoded.

Authentication

When your platform is registered with Optizmo you receive two values:

a Reference Code (PRC), sent with every request as ref;
an Access Key (PAK), which is never sent. It is the secret that signs each request.

Each SUPPRESS account that connects to your platform gives you its ONID, found on the account’s Account Settings page under Affiliate Tracking System. It is sent as onid and identifies the account a request is for.

Every request carries a check_hash: the MD5 hex digest of the request’s hashed values concatenated in order, with no separator, followed by the PAK. Each action lists its hashed values in order. Only values you actually send are included, so omit a parameter rather than sending it empty. The values are hashed as sent, before URL encoding; UTF-8 values are accepted either as bytes or as decoded characters.

For example, a full client_sync request with PAK a1b2c3d4e5f6a7b8:

Parameter	Value
`action`	`client_sync`
`ref`	`pqmpg`
`onid`	`662b824d577c74b57bf1c4fc647b79c7`
`advertiser_id`	`C12412`
`advertiser_name`	`BlockBuster`
`optout_id`	`f3k93kda3`
`campaign_id`	`K3K3`
`campaign_name`	`Spring Offer`
`mailer_id`	`311111`
`mailer_name`	`Acme Mailing`
`mailer_email`	`ops@acmemailing.example`

check_hash = md5("client_syncpqmpg662b824d577c74b57bf1c4fc647b79c7C12412BlockBusterf3k93kda3K3K3Spring Offer311111Acme Mailingops@acmemailing.example" + "a1b2c3d4e5f6a7b8")
           = 84f163e7281cbb63026a5750ef1a7ce8

A request whose hash does not match answers failed,Check Hash Failed.

Response format

return_format selects the body format; it defaults to csv and is not hashed.

`return_format`	Content type	Success	Failure
`csv`	`text/plain`	`success,<mailer_url>,<optout_url>`, `success,<mailer_url>,` when no Opt-Out link was issued, `success` alone when no keys were issued, or, only for a `client_sub_sync` healed onto a replacement key, a fourth field carrying it (`success,,,<access_link>` when that call issued no keys of its own)	`failed,<message>`
`xml`	`text/xml`	`<output><result>success</result><data><mailer_url>…</mailer_url><optout_url>…</optout_url></data></output>`, with an empty element for whichever of `mailer_url`/`optout_url` is absent	`<output><result>failed</result><error>…</error></output>`
`json`	`application/json`	`{"output":{"result":"success","data":{"mailer_url":"…","optout_url":"…"}}}`, with a `null` value for whichever of `mailer_url`/`optout_url` is absent	`{"output":{"result":"failed","error":"…"}}`

Failures are returned with HTTP 200; read the body. The exceptions are HTTP 503 while the system is in maintenance (failed,System currently under maintenance, in the format return_format selects); the report and list actions, which return XML documents of their own; the page actions (Manage Opt-Out Lists and the profile actions), which answer with an HTTP redirect to the page (see Embedded pages); and client_config and add_emails, which answer with an HTML page.

test_only is described alongside its parameter definition: it is honoured only by the synchronisation actions, the report, Get Opt-Out Lists, and client_config/add_emails; every other action ignores it and makes its real change regardless.

Embedded pages

The page actions sign the user into SUPPRESS and show a SUPPRESS page: the profile actions and Manage Opt-Out Lists answer with a redirect whose URL carries the session as a token, and the page it opens then stores the session in a cookie set from JavaScript with SameSite=None; Secure. Inside an iframe on your platform’s domain that is a third-party cookie, which browsers that block third-party cookies drop, so the page can lose its sign-in as soon as the user moves within it. Manage Opt-Out Lists can also show a Log Me In page first; its description says when, and why it does not open signed in inside an iframe. Open these pages in a popup or a new tab rather than an iframe.

Caching

Responses to the synchronisation actions are stored for 60 minutes, keyed on the action, onid, advertiser_id, optout_id, campaign_id, check_hash and return_format. A request identical to one made within the last hour is answered with the stored response and the header X-Status: cached, without being processed again. Because any change to a hashed value changes the check_hash, a changed request is always processed. Concurrent identical requests wait for the first to finish rather than being processed twice; a request still waiting after 10 minutes answers failed,Request timed out. Please retry. A client_sub_sync call healed onto a replacement key is always processed rather than answered from the cache, and its own response is never stored, so a caller that keeps presenting a replaced key is resolved again on every request.

When a list or campaign is moved, the stored responses of the account that moved it are cleared, and so are those of every network below it whose own linked list the move re-sourced or simply handed a new Opt-Out link, so each of them gets current keys on its next request.

The API sends no rate-limit headers; the cache above is what absorbs repeated requests.

Limits

Ids (advertiser_id, campaign_id, mailer_id, submailer_id) may be up to 40 characters, so a 36-character UUID fits; a longer id is rejected with failed,The following input values were too long = <names>. optout_id is the optoutlist_id from Get Opt-Out Lists, sent as returned; it is always within the limit. Names and contact details longer than their limit are truncated: campaign_name 150, advertiser_name and mailer_name 80, mailer_email 500, mailer_phone 80, advertiser_email 80, advertiser_contact 70, advertiser_phone 20.

Information

OpenAPI version: 3.0.0