Overview

O.N.E API 1.0.0

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. The two versions differ only in the Opt-Out List values (see Versions):

Parameter	Version 1	Version 2
`action`	`client_sync`	`client_sync`
`ref`	`pqmpg`	`pqmpg`
`onid`	`662b824d577c74b57bf1c4fc647b79c7`	`662b824d577c74b57bf1c4fc647b79c7`
`advertiser_id`	`C12412`	`C12412`
`advertiser_name`	`BlockBuster`	`BlockBuster`
`optout_id`	`O39232`	`f3k93kda3`
`optout_name`	`Master List`	not sent
`campaign_id`	`K3K3`	`K3K3`
`campaign_name`	`Spring Offer`	`Spring Offer`
`mailer_id`	`311111`	`311111`
`mailer_name`	`Acme Mailing`	`Acme Mailing`
`mailer_email`	`ops@acmemailing.example`	`ops@acmemailing.example`

Version 1:

check_hash = md5("client_syncpqmpg662b824d577c74b57bf1c4fc647b79c7C12412BlockBusterO39232Master ListK3K3Spring Offer311111Acme Mailingops@acmemailing.example" + "a1b2c3d4e5f6a7b8")
           = 7583f2e660997b8d1c224a8d74260c51

Version 2:

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

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

Versions

A platform is registered as version 1 or version 2. The only difference is how an Opt-Out List is identified:

Version 1: optout_id is your platform’s own id for the list. The list is created in SUPPRESS the first time the id is seen, named by optout_name, and renamed when the name changes.
Version 2: the advertiser creates its 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 renamed through the API.

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 normally answer with an HTTP redirect to the page (Manage Opt-Out Lists answers with a sign-in page instead, for a browser that blocks third-party cookies); 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.

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.

Limits

Ids (advertiser_id, campaign_id, mailer_id, submailer_id, optout_id) may be up to 40 characters; longer ids are rejected with failed,The following input values were too long = <names>. 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