Get Opt-Out Lists

GET

/api.cgi?action=get_optoutlists

curl --request GET \
  --url 'https://one.optizmo.net/api.cgi?ref=pqmpg&onid=662b824d577c74b57bf1c4fc647b79c7&advertiser_id=C12412&check_hash=7583f2e660997b8d1c224a8d74260c51&return_format=csv&test_only=success&action=get_optoutlists%3Fref%3Dpqmpg'

• O.N.E API server

Returns the Opt-Out Lists of an advertiser. Version 2 platforms use the returned optoutlist_id as the optout_id in every other call: the advertiser creates and configures its lists in SUPPRESS (see Manage Opt-Out Lists) and your platform lets the user pick one.

Version 1 platforms must not send a returned optoutlist_id as optout_id. A version 1 optout_id is your platform’s own id, so the call does not match the existing list and creates a new one under that id instead.

On an Enterprise account the account’s own lists are returned and advertiser_id is not used for matching, but it is still required and hashed.

The response is always XML.

Values in the check_hash

action, ref, onid, advertiser_id.

Failures

Failures are returned in the format selected by return_format.

Response	Meaning
failed,advertiser_id does not exist	No advertiser in the account has this id.
failed,Value for 'onid' does not exist in our system	No account has this ONID.
failed,Check Hash Failed.	check_hash does not match.

Parameters

Query Parameters

ref

required

string

<= 5 characters

Your tracking platform’s Reference Code (PRC), issued by Optizmo when the integration was set up.

Example

pqmpg

onid

required

string

The ONID of the SUPPRESS account the request is for. The account holder finds it on the Account Settings page in SUPPRESS under Affiliate Tracking System, and copies it into your platform.

Example

662b824d577c74b57bf1c4fc647b79c7

advertiser_id

required

string

<= 40 characters

Your platform’s id for the advertiser whose lists are wanted.

Example

C12412

check_hash

required

string

/^[0-9a-f]{32}$/

MD5 hex digest of the request’s hashed values, in the order they are listed for this action, followed by your Access Key (PAK). See Authentication for the rules.

Example

7583f2e660997b8d1c224a8d74260c51

return_format

string

default: csv

Allowed values: csv xml json

Sets the format of the success or failed answer on the synchronisation and status actions, and of the failure answer on every action. It does not change the success answer of the report and list actions, which is always their own XML document, or of the actions that answer with a page or a redirect. csv, xml and json are the only recognised values; anything else is answered in the csv format, the default. Not included in the check_hash.

test_only

string

Allowed values: success failed

Only honoured by Sync an advertiser, list, campaign and affiliate, Sync onto a linked list, Generate an SMAK, Account report, Get Opt-Out Lists, Advertiser and list settings page and Add opt-outs page; every other action ignores it and runs as normal, so sending it there does not stop the real change. On the actions that honour it, once the request has authenticated, it answers without creating or changing anything, and before the page renders on the two pages actions: failed,Test Failed Output for test_only=failed everywhere it is honoured. For test_only=success: the sync actions return a fixed key pair (https://TESTONLY.optizmo.net/m-test-a00-410324axc3e1eb7a and https://TESTONLY.optoutsystem.net/o-test-a00-546c4dxa10df19b8) in place of real ones, in the same body shape a real success with keys would have; the account report returns that same fixed key pair, not a report document; Get Opt-Out Lists returns a fixed two-entry list document; and the two pages actions return a bare success with no keys, the same shape as a real one with no campaign_id/mailer_id pair. Not included in the check_hash.

Responses

200

The advertiser’s Opt-Out Lists, ordered by name.

Media typetext/xml

object

optoutlist

Array<object>

object

optoutlist_id

The list’s Optizmo id. Send it as optout_id in other calls.

string

optoutlist_name

string

md5_only

1 when the list stores MD5 hashes only. Absent when the underlying value has never been set; may also be present as 0 rather than absent otherwise, so treat it as false unless it is exactly 1, not by whether the element is present.

integer

Examples

Examplereport

Two lists, one MD5 only

<?xml version="1.0" encoding="utf-8"?>
<list_optoutlists>
  <optoutlist>
    <optoutlist_id>f3k93kda3</optoutlist_id>
    <optoutlist_name>Master List</optoutlist_name>
  </optoutlist>
  <optoutlist>
    <optoutlist_id>f5k690d0a3</optoutlist_id>
    <optoutlist_name>Newsletter Opt-Outs</optoutlist_name>
    <md5_only>1</md5_only>
  </optoutlist>
</list_optoutlists>

503

The system is in maintenance mode. Retry later. The answer follows return_format: csv (also the answer to a return_format that is neither xml nor json) as text/plain, xml as text/xml, json as application/json.

string

Example

failed,System currently under maintenance

string

Example

<?xml version="1.0" encoding="utf-8"?>
<output><result>failed</result>
<error>System currently under maintenance</error></output>

object

output

object

result

required

string

Allowed values: success failed

data

Present when result is success. This action issues no keys, so both values are null.

object

mailer_url

string

nullable

optout_url

string

nullable

error

Present when result is failed.

string

Example

{
  "output": {
    "result": "failed",
    "error": "System currently under maintenance"
  }
}