Skip to content
Optizmo API

Sync an advertiser, list, campaign and affiliate

GET
/api.cgi?action=client_sync
curl --request GET \
  --url 'https://one.optizmo.net/api.cgi?ref=pqmpg&onid=662b824d577c74b57bf1c4fc647b79c7&advertiser_id=C12412&advertiser_name=BlockBuster&optout_id=O39232&optout_name=Master%20List&campaign_id=K3K3&campaign_name=Spring%20Offer&mailer_id=311111&mailer_name=Acme%20Mailing&mailer_email=ops%40acmemailing.example&check_hash=7583f2e660997b8d1c224a8d74260c51&campaign_set_expiry=2027-01-31&return_format=csv&test_only=success&action=client_sync%3Fref%3Dpqmpg'

Creates or updates the records that describe an offer in a SUPPRESS account and, when an affiliate is named, issues that affiliate’s Mailer Access Key and Opt-Out link. Call it whenever an offer or an affiliate’s access to it is created or changed in your platform, and whenever you need the keys again: repeating a request is safe and returns the same keys.

The request is processed in this order, each step matching on your id and creating the record if it does not exist yet:

  1. Advertiser (advertiser_id, advertiser_name). Always required. On an Enterprise account the account itself is the advertiser.
  2. Opt-Out List (optout_id, optout_name). Version 1 creates the list in the advertiser; version 2 selects a list the advertiser created in SUPPRESS. On an account that holds SMS lists only, new lists are SMS lists. A list found under a different advertiser of the same account is moved to the advertiser in the request, with its opt-outs and statistics. This is not supported on accounts that hold both email and SMS lists, which answer failed,Moving optout lists between advertisers is not supported on email & SMS accounts. Nor is it done for a very large list: failed,Opt-out list '<name>' (optout_id <optout_id>) has more than <limit> rows, the limit for moving a list to another advertiser, so it cannot be moved., with no way to override it. A list another request is already moving answers failed,Opt-Out List <optout_id> is being moved by another request. Please retry.; a request with too little time left to make the move answers failed,Opt-Out List <optout_id> could not be moved in the time this request has left, and nothing was moved. Please retry.; a check of the list that could not be made answers failed,The Opt-Out List could not be checked just now. Please retry.; an unexpected failure answers failed,Opt-Out List <optout_id> could not be moved to this advertiser, and nothing was moved. Admin has been notified. (<optout_id> is the optout_id you sent). Whichever of these it is, nothing changes.
  3. Affiliate (mailer_id, mailer_name, mailer_email). Affiliates belong to the account and are added to the advertiser as needed.
  4. Campaign (campaign_id, campaign_name, campaign_set_expiry). Created on the list in the request. Requires optout_id; without it the response is failed,Campaign import requires Opt-Out List data.
  5. Campaign affiliate. When both campaign_id and mailer_id are sent, the affiliate is attached to the campaign and its access key and Opt-Out link are returned. If the list is a linked list (a list that downloads another account’s list through an access key), the affiliate is registered on the source campaign, one level down its linked list chain, and receives an SMAK (sm-...) instead of a MAK (m-...). Attaching an affiliate to a linked list whose own source key a move has since replaced is refused rather than built on: failed,The access key this Opt-Out List was linked from was replaced on <date> when campaign '<name>' moved to another opt-out list. Ask <mover> for the campaign's current access key and link the Opt-Out List to it. (<mover> is whoever moved the campaign, given only to an account that owns a linked list created from that key; to any other account, or when the move named none, it reads “the network or advertiser that gave you the campaign”, with the sentence otherwise unchanged. When the move recorded no campaign name, campaign '<name>' reads its campaign. A campaign that left for another account’s list reads ...was switched off on <date> when campaign '<name>' moved to another account. Ask <mover> ..., and a repair of a campaign on the list it is already on reads ...was replaced on <date> by a chain repair of campaign '<name>'. Ask <mover> ....) A source key switched off by hand is refused as failed,The access key this Opt-Out List was linked from has been disabled. Ask the network or advertiser that gave you the key for a current access key and link the Opt-Out List to it., and one that is out of service for another reason, such as an expired campaign, as failed,The access key this Opt-Out List was linked from has expired (<reason>). When the source key could not be read, failed,The access key this Opt-Out List was linked from could not be checked just now. Please retry. A source key that is replaced in the moment between that check and the write answers failed,The access key this Opt-Out List was linked from changed while this sync ran. Please retry., and a concurrent move of the campaign the source key belongs to answers failed,The campaign that issued the access key this Opt-Out List was linked from is being moved. Please retry. (the wording differs from Sync onto a linked list’s own key check, which names the access_link you sent, because this call sends none). Retrying after any of these three retry answers re-reads the source as it is now.

A request may stop after any step: advertiser only, advertiser and list, or the full set. Without a campaign and affiliate pair the response is success with no keys.

Values in the check_hash

In this order, skipping any parameter you do not send: action, ref, onid, advertiser_id, advertiser_name, optout_id, optout_name (version 1 only), campaign_id, campaign_name, mailer_id, mailer_name, mailer_email.

Changing a campaign’s Opt-Out List

Sending an existing campaign_id with a different optout_id moves the campaign, its affiliates and its creatives onto that list. The campaign move is checked in full before anything about it is written, and then written as one unit: a refused or failed campaign move changes nothing about the campaign. When the list named also has to move to another advertiser first (step 2 above), an obviously-refusable campaign move is checked, and the request refused, before that list move runs, so a campaign move that was always going to be refused does not move the list either; but the list move is its own unit, committed before the campaign move starts, so a campaign move that fails for another reason once the list move has committed leaves the list moved. Retry the request to move the campaign onto the list it is now on.

What you get back. The response carries the Opt-Out link for the affiliate in the request on the new list: the link already issued for that list, if the campaign has held one there before (including a move between two lists linked from the same access key, when the affiliate has already had a link on the specific new list), or a newly minted one otherwise. Opt-Out links issued before the move keep working, but they keep collecting into the list they were issued for; they are not redirected, and opt-outs already collected are not copied to the new list. The new list’s suppression file therefore holds only what that list already had. Replace the link in the affiliate’s creatives, and if the opt-outs that keep arriving through the old links should also reach the new list, ask the list’s owner to set up a transfer between the two lists in SUPPRESS.

Access keys.

Move Affiliate’s access key
Standard list to standard list Unchanged. It now downloads the new list.
Standard list to linked list The MAK (m-...) is replaced and the response carries a new SMAK (sm-...). Anyone still using the old key is told: The advertiser has changed the access to this campaign. You will need to go back to your tracking system to receive your new access key to this campaign. If it is not there yet, ask the network or advertiser that gave you this campaign; they have been sent the new key.
Linked list to standard list, or to a list linked from a different source The SMAK is replaced with the same message and the response carries the new key. The replaced entry stays visible to the source account, marked Access Key Replaced, with its download counts.
Between two lists linked from the same access key, or onto the list the campaign is already on Keys unchanged.
Back onto a list linked from the same source as before The previous SMAK and Opt-Out link for that source come back into use, not a freshly minted pair.

Every affiliate on the campaign receives an Opt-Out link on the new list, on the same terms as above, whether or not it is the affiliate this request named, even on a standard-to-standard move, where the affiliate’s access key is unchanged and nothing prompts it to notice: it is handed the new link on its next sync, download or cleanse. Where the key type also changed, it gets a new access key the same way. Sync each affiliate (one request per affiliate) to retrieve its pair directly instead of waiting for that; Optizmo also emails each affiliate a daily digest the next day listing the campaigns whose link or key changed.

Networks downstream of the campaign. A network that linked its own list from this campaign’s access key has that key replaced by the move and a replacement stored on its list, except when the campaign moves between two standard lists, which leaves the key as it is. The network does not have to wait to be told: its next Sync onto a linked list call presenting the replaced key is healed onto the replacement automatically, provided the network still owns the linked list built from it (see “When the key you hold was replaced” there for the refusals given when it cannot heal). Until it syncs, the network’s affiliates’ downloads for the campaign fail and their existing Opt-Out links keep collecting into the previous source list. The networks that build linked lists from one another’s keys form a linked list chain, with the source at its first level. The move re-sources every level of the linked list chain below the campaign in the same transaction, so no network has to wait for the one above it to re-sync first; each is simply healed independently on its own next sync, whenever that happens.

The move’s own check on a linked target walks to the source of its linked list chain for whether a list or account there has been deleted or archived, but reads only the immediate source row’s own access: an expired, stopped or hand-disabled key or campaign further up the linked list chain is not evaluated here, so the move can succeed and the new key still be refused on its first download. Recreate the linked list chain from a valid key at whichever level that turns out to be.

Notices. Optizmo emails a summary of what changed to the account named by onid (the account performing the move, since a request through this API always moves a campaign the calling network manages). Where a linked list on either side of the move records into a list a different account owns, that account is separately emailed its half of the transfer (also sent for a standard new list in another account; not sent for a same-list move or one that keeps the same source key). Where the move re-keys a downstream linked list, that list’s owner is emailed the replacement key directly, capped at once per list per campaign per day unless the key that notice carried has itself been replaced since. A campaign that returns, for the second time within 7 days, to a list it left is “flapping”: every notice these two paragraphs describe is held until it stops, except the hand-over notice under Generate an SMAK, which still goes out. Outside a flap, the account and owner notices above do not repeat for the same exact move (the same previous list to the same new list) within 30 days, so a campaign moved back and forth on a longer cycle is not re-announced every time it repeats; the current key and link on the list are always current regardless of whether a notice was sent for the move that produced them.

Refusals. A move that cannot be made is refused with failed,Unable to change the opt-out list for this campaign, because <reason>. and nothing is changed. A reason marked temporary is followed by Please retry., as in failed,Unable to change the opt-out list for this campaign, because <reason>. Please retry.; retrying reads the rows as they are then.

Reason Meaning
the campaign could not be found The campaign was deleted between this request reading it and the move starting.
the target list id is not valid Internal-only: this call always resolves a real list id before this check runs.
the target list could not be found The target list was deleted in the same window. This call creates the target list first, so it can only arise from that race.
the target list has been deleted / the target list has been archived The list can no longer take campaigns.
the target list (phone numbers) is a different type to the source list (emails) A campaign cannot change between an email list and an SMS list, on any account type.
an affiliate on this campaign holds an access key that was disabled by hand. Optizmo staff must re-enable or repair that access key before the campaign can move Refused before anything is written, and before a new target list is created. Retrying does not help: Optizmo staff must re-enable or repair the key first.
the target linked list has no source access key / the target linked list's source access key does not resolve The linked list’s connection to its source is broken. Recreate the list from a valid key.
the target linked list's source access key has been disabled The key the linked list was created from was switched off by hand. Ask whoever gave you the key for a current one.
the target linked list's source access has expired (<reason>) The source has stopped, expired or deleted the campaign the list is linked from.
the target linked list's source list has been deleted / the target linked list's source list has been archived / the target linked list's source account has been deleted The linked list’s source key still resolves, but the list or account it belongs to is gone.
the target linked list's source access key could not be traced Tracing the linked list’s source ran long enough to suspect a cycle. Contact support.
the target linked list is linked from this campaign's own access key The list was created from a key issued for this same campaign, so the campaign would become its own source.
the linked list chain of an affiliate on this campaign records into no live Opt-Out List A linked list chain below the campaign has no live list left for a new Opt-Out link to record into. Contact support.
the target list could not be checked (temporary) A temporary error while reading the target list.
the campaign's access keys could not be checked (temporary) A temporary error while reading the keys of the campaign’s affiliates, before a new target list was created.
the move could not be started (temporary) A temporary error setting up the move’s own time limit.
this request has too little time left to make the move (temporary) The request, which is ended after 30 minutes, did not have the time the move needs left. Nothing was written.
the campaign could not be locked for the move (temporary) The campaign itself, a list it is leaving or joining, or a campaign or list further down its linked list chain is held by another move or list move, and the move’s time limit (up to 10 minutes) ended while it waited.
the list the campaign is on was moved to another advertiser while this move waited (temporary) A list move of the campaign’s list committed while this move waited for it. Retrying reads the campaign under its new advertiser.
the target list was moved to another advertiser while this move waited (temporary) A list move of the target list committed while this move waited for it. Retrying reads the list under its new advertiser.
the opt-out link of an affiliate on this campaign could not be created just now (temporary) A read that a new Opt-Out link needs failed. The move was rolled back.
a list below this campaign is being moved to another advertiser (temporary) A list move of a list further down the linked list chain is running. The move was rolled back.
the move could not be completed. Admin has been notified. A move that ran for several minutes without finishing, or any other error while writing it, is rolled back and Optizmo is alerted. Retrying immediately is safe.

Concurrency. Requests that move the same campaign onto the same list at the same time (one request per affiliate is the usual shape) wait on each other rather than running together, and are otherwise processed one after the other. The campaign is moved once, every request answers success with that affiliate’s keys for the new list, and a request that names the list the campaign is already on does not move it. Requests that move the same campaign onto different lists at the same time are each applied in turn instead: both moves happen, the second one moving the campaign from wherever the first left it, so the campaign ends on the list the request that ran last named. Requests that create the same advertiser, list, campaign or affiliate at the same time are also processed in turn, so each id creates exactly one record; one that waits more than a few seconds behind another request creating the same one is refused rather than left waiting: failed,Another sync for this tracking id is still creating the same <entity>. Please retry., or failed,The <entity> for this tracking id could not be checked just now. Please retry. on a database error, where <entity> is advertiser, Opt-Out List, campaign or affiliate. Retrying either finds the record the other request created.

Adding or updating a campaign’s affiliate is refused rather than made against a campaign mid-move: failed,The campaign is being moved to another Opt-Out List. Please retry. if a move of it is still running, failed,The campaign could not be checked just now. Please retry. if its lock or its list could not be read, or failed,The campaign moved to another Opt-Out List while this sync ran, so the affiliate was not added to it. Please retry. if the move finished while this request was in progress. Retrying picks the campaign up on its current list.

Cache. A move clears the stored responses of the account that made the move, and of every network below it that built its own linked list from this campaign’s key, at every level of the linked list chain: whether that network’s list was re-sourced onto a new key or kept its own key and was simply handed a new Opt-Out link, its next request runs live rather than being answered from the cache. Every move is recorded with who requested it and which lists were involved, so Optizmo support can trace it.

Failures

Response Meaning
failed,Missing the following input values = <names> A required parameter is missing or empty.
failed,Missing one of the following input values = <names> An id was sent without its name, for example campaign_id without campaign_name.
failed,The following input values were too long = <names> An id exceeds 40 characters.
failed,Tracking system does not exist. ref is not a registered Reference Code.
failed,Check Hash Failed. check_hash does not match. Check the value order and that only sent values are hashed.
failed,Value for 'onid' does not exist in our system onid does not belong to any account.
failed,Invalid optout_id. Version 2 of this API requires an optout_id from the get_optoutlists API call. Version 2 platforms must send the id returned by Get Opt-Out Lists.
failed,Could not find Opt-Out List from optout_id = <id> Version 2: no list has that id in this account.
failed,Campaign Expiry ('campaign_set_expiry') incorrect format (YYYY-MM-DD) - <value> The expiry date is not YYYY-MM-DD.
failed,Request timed out. Please retry. An identical request was still being processed after 10 minutes.
failed,The opt-out link for this access key could not be created just now. Please retry. A read that the affiliate’s Opt-Out link needs failed. Nothing was written for the link.
failed,The opt-out link for this access key could not be created, because the linked list chain it belongs to records into no live Opt-Out List. The linked list chain’s source link has no live list left for a new Opt-Out link to record into. Contact support.
failed,Internal Error. Admin has been notified. An unexpected error. Optizmo has been alerted.

Parameters

Section titled “ Parameters ”

Query Parameters

Section titled “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. The advertiser is matched on this id within the account. On an Enterprise account (a single advertiser) the account itself is the advertiser and this id is not used for matching, but it is still required and hashed.

Example
C12412
advertiser_name
required
string
<= 80 characters

Name of the advertiser. Creates the advertiser on first sight and renames it when the name changes. Longer values are truncated.

Example
BlockBuster
optout_id
string

The Opt-Out List. Unlike the other ids, its length is not checked or truncated.

  • Version 1: your platform’s id for the list. The list is created in the advertiser on first sight and matched on this id afterwards.
  • Version 2: the optoutlist_id of a list the advertiser created in SUPPRESS, as returned by Get Opt-Out Lists. The list must exist.

Required when campaign_id is sent.

Examples

Version 1

O39232
optout_name
string

Name of the Opt-Out List. Version 1 only: required whenever optout_id is sent; the list is renamed when the name changes. Version 2 platforms do not send it; if sent, it is ignored but still part of the check_hash.

Example
Master List
campaign_id
string
<= 40 characters

Your platform’s id for the campaign (offer). The campaign is created on the list named by optout_id on first sight and matched on this id within the advertiser afterwards. Requires optout_id. Sending an existing campaign with a different optout_id moves the campaign to that list; see Changing a campaign’s Opt-Out List.

Example
K3K3
campaign_name
string
<= 150 characters

Name of the campaign. Required when campaign_id is sent; the campaign is renamed when the name changes. Longer values are truncated.

Example
Spring Offer
mailer_id
string
<= 40 characters

Your platform’s id for the affiliate. Affiliates belong to the account, not to an advertiser: the same id names the same affiliate across every advertiser in the account. Created on first sight.

Example
311111
mailer_name
string
<= 80 characters

Company name of the affiliate. Required when mailer_id is sent; updated when it changes. Longer values are truncated.

Example
Acme Mailing
mailer_email
string
<= 500 characters

Contact email of the affiliate. Hashed when sent. Optizmo uses it to tell the affiliate when a campaign’s Opt-Out link or access key changes.

Example
ops@acmemailing.example
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
advertiser_email
string
<= 80 characters

Contact email stored on the advertiser. Not hashed.

advertiser_phone
string
<= 20 characters

Contact phone number stored on the advertiser. Not hashed.

advertiser_contact
string
<= 70 characters

Contact name stored on the advertiser. Not hashed.

campaign_set_expiry
string format: date

Expiry date of the campaign in YYYY-MM-DD format. Access keys for an expired campaign stop working.

  • Sent with a date: sets the expiry.
  • Sent empty (campaign_set_expiry=): clears the expiry.
  • Omitted: leaves the current expiry as it is.

Not hashed. An unrecognised format is rejected with failed,Campaign Expiry ('campaign_set_expiry') incorrect format (YYYY-MM-DD) - <value>.

Example
2027-01-31
mailer_phone
string
<= 80 characters

Contact phone number of the affiliate. Not hashed.

mailer_creativetrackingid1
string

Tracking id that identifies this affiliate in the creative provided to them. Up to four independent ids are accepted, mailer_creativetrackingid1 to mailer_creativetrackingid4; none of them is required. Not hashed.

mailer_creativetrackingid2
string

See mailer_creativetrackingid1. Not hashed.

mailer_creativetrackingid3
string

See mailer_creativetrackingid1. Not hashed.

mailer_creativetrackingid4
string

See mailer_creativetrackingid1. Not hashed.

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

Section titled “ Responses ”

200

Section titled “200”

The request was processed. The body says whether it succeeded; failures are also returned with HTTP 200.

  • success,<mailer_url>,<optout_url>: the affiliate’s access URL and Opt-Out link. The access URL’s last path segment is a MAK (m-...) on a standard list or an SMAK (sm-...) on a linked list.
  • success,<mailer_url>,: an access URL with no Opt-Out link, a deliberate trailing comma rather than a shorter body.
  • success: the records were created or updated, but no campaign_id and mailer_id pair was sent, so no keys were issued.
  • failed,<message>: nothing was changed by the failing step. The messages are listed with each action.

A client_sub_sync call healed onto a replacement key (see Sync onto a linked list) carries a fourth value, access_link, and is never served from the cache; every other response served from the cache carries the header X-Status: cached.

string
Examples

Access key and Opt-Out link issued

success,https://www.affiliateaccesskey.com/m-tbjt-j53-b4f8dfbb7f76d3bd0fd92a9f39ba5387,https://www.optout-tbjt.net/o-tbjt-j53-eeedade91ab3043dea9edcc260d983ef

503

Section titled “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