External API manual

External offer APIs are used in postbacks for external integration and application connection. Using them, you can create a lead by click, change its status, find out the data of the offer and flow, fetch the click ID in the application.

Authorization

The token parameter is responsible for authorization in the sites API. It is of two types:

Site token. Consists of the site ID and the site key separated by a hyphen. For example 123-abcde. The token of any site within the offer is suitable for work - they are equivalent.
Global token. It can be found in the "Control - Settings - Sites" section, the "Technical Settings" block, the "Global API Key" parameter. With it, you can work with any sites. Useful for creating global postbacks.

Which authorization option to choose depends on your situation. It is recommended to use the site token whenever possible, and use the global token only in rare cases.

Creating lead

The function is designed to create a new lead by click ID. Can work with clicks, flows and external IDs. The result will be a new lead. Parameters can be passed in both GET and POST part of the request.

URL: https://domain.com/api/site/click.json?token=123-abcd&click={subid}

Setting up click ID

The function can use these parameters to understand the traffic source:

click - click ID in AlterCPA.
exto - unique order identifier on the side of the target network.
flow - numeric flow ID in AlterCPA.
code - symbolic flow code in AlterCPA.

What combinations can be used:

click - classic lead creation by click ID.
click + exto - creating a lead by click with protection against duplicates and convenient editing.
flow - creating a lead by flow ID without the possibility of further editing.
code - creating a lead by a symbolic flow code, for example, from the name of an advertising campaign inside the application, without the possibility of further editing.
flow + exto or code + exto - creating a lead by flow with the possibility of further editing.

When working with SOI postbacks, you only need to create a lead, further editing is not necessary. In this situation, the unique ID can be neglected.

Adding status

By default, a lead is created in the "New" status. If necessary, you can immediately create a lead in the required status. Useful for SOI traffic when a lead is created already approved.

The function can accept the following variables to work with statuses:

status - character status value, parsed automatically.
accept=1 - approve lead (alias status=approve).
stid - AlterCPA numeric status ID.
reason - numeric code of the cancel reason.

When sending the status of a lead via the status parameter, it is recognized automatically. You can pass the status ID and reason for the rejection directly to stid and reason. But it is more convenient to bypass automatic recognition by directly specifying in the request parameters which statuses should be considered as approving, canceling or trashing.

sta - the status that is recognized as approval
stc - the status that is recognized as cancellation of the lead
stt - the status that is recognized as trash
sth - the status that is recognized as lead on hold
stw - the status that is recognized as lead in processing
stn - status recognized as a new lead (creates a lead instead of changing the status)

If necessary, you can specify more than one status, but several at once, separated by commas. If no matches are found, the status will be recognized automatically.

Important! Quite often, networks use the name hold to denote a simple waiting status, so you need to directly specify stw=hold so that the lead does not fall into the hold or approve.

Adding commissions

Payments can be received directly through the API. The parameters are responsible for this.:

wm - the amount of payment per lead for the affiliate and advertiser.
cc - payment currency.
pd - affiliate network commission in the payment currency (a positive number will reduce the affiliate's payment from wm by the specified amount, a negative number will increase the advertiser's payment).
pp - affiliate network commission as a percentage, works similarly to pd.
pay - the amount of payment only for the advertiser.

In real work, it is recommended to use two combinations:

wm + cc - indication of payment and currency for all at once. The commission is configured through the mechanism of manual payments within the offer.
pay + cc - indication of the advertiser's payment. In this case, the payment for the affiliate is calculated according to the settings inside the offer.

The use of pd and pp in real work is not recommended, since they exclude the possibility of flexible configuration of different commissions for different affiliates.

Adding goal

When working with offers that have advanced goals, it is recommended to pass the goal through the API at the time of creating or modifying a lead. Two parameters are responsible for working with the goal:

goal - character goal ID.
gid - numeric goal ID.

It is recommended to use a character goal identifier. You can configure the goals so that the character IDs on the AlterCPA side match the IDs on the target network side. If the target network uses different character identifiers for the same goal, you can add them to the list of aliases when setting up the goal in the offer.

Additional parameters

These options are rarely used. Their application depends on the task.

name - customer name.
phone - curtomer phone.
email - customer email.
country - two-letter ISO country code.
base - unit price or order cost (not payment!).
curr - numerical identifier of the currency within the platform.
currency - three-character ISO currency code.
count - quantity of goods in the order.
comment - lead comment.
mobile - traffic type (mobile or desktop).
bad - if set to 1, traffic is marked as bad.
time - lead creation time in UNIX timestamp format.

You can pass this values in the mobile parameter:

Desktop: 0, dsk, desk, desktop, pc, laptop.
Mobile: 1, mob, mobile, tablet, any non-empty value.

Tablets are considered mobile traffic. There is no separate category "Tablet". If you need to work with this type of traffic, use goals.

Function response

The function returns a response as a JSON object with the following fields:

status - ok if success and error if failed.
id - lead ID in AlterCPA.
error - error code.

The following errors may occur when the function is running:

auth - authorization problem, check the token.
no-id or bad-id - could not find click or flow ID.
traffic - traffic to the offer is prohibited by privacy settings.
duplicate - duplicated lead.
db - system error while working with database.

You can save the lead ID in the app for further editing. Don't use the presence of the id field to determine success, check against status=ok. The duplicate error also returns the lead ID, but this will be the original ID.

Example of a successful function response:

{ "status": "ok", "id": 1234 }

Error example:

{ "status": "error", "error": "duplicate", "id": 1234 }

Changing lead status

The function is designed to change the status of a previously created lead. Can work with clicks, orders, flows and external IDs. The result will be a lead in the specified status. Parameters can be passed in both GET and POST part of the request.

URL: https://domain.com/api/site/status.json?token=123-abcd&click={subid}&status={status}

Setting up click ID

The function can use these parameters to understand the traffic source:

click - click ID in AlterCPA.
exto - unique order identifier on the side of the target network.
order - lead ID in AlterCPA.
flow - numeric flow ID in AlterCPA.
code - symbolic flow code in AlterCPA.

What combinations can be used:

click - classic change of lead by click ID, works only with one lead.
click + exto - changing a lead by click with the ability to work with several leads with the same click ID.
order - changing a lead by its ID received during creation.
flow + exto or code + exto - changing a lead by flow (ID or code).

Be sure to use the same combination of options when creating and editing a lead. If you create a lead without specifying exto, and edit it already with exto specified, you will get an error.

If no lead found

Sometimes the lead creation postback is lost. In such a situation, the function will not be able to find the desired lead and will end with an error. There are two workarounds for this problem.

Add auto=1 to the request. In this situation, the lost lead will be created automatically and transferred to the desired status.
Use stn=new in the request to specify the status to be considered a new order. This will allow using a single postback for both creating and modifying a lead.

What is the difference between stn=new and auto=1? When using the stn parameter, a lead is created only if the status matches the one specified in stn and enters the "New" status. When using auto=1, the lead will be created immediately in the required status if no other lead with the same click ID was found.

Statuses, payments, goals and additional fields

The function uses the same fields for working with statuses, payments, goals and additional fields as lead creation. Please refer to the documentation above.

Function response

The function returns a response as a JSON object with the following fields:

status - ok if success and error if failed.
id - lead ID in AlterCPA.
error - error code.

The following errors may occur when the function is running:

auth - authorization problem, check the token.
no-id or bad-id - failed to find a lead by the specified ID.
db - system error while working with database.
edit - the lead already is in the right state, there is nothing to change.

Example of a successful function response:

{ "status": "ok", "id": 1234 }

Error example:

{ "status": "error", "error": "edit" }

Fetching click data

The function allows you to get the visitor's click ID by his IP address, offer and flow. The result will be click data. Parameters can be passed in both GET and POST part of the request.

URL: https://domain.com/api/site/fetch.json?token=123-abcd&offer={offer}

Suggested use case: redirect site transfers to the app install page in the store. Immediately after installation and launch, the application tries to get the ID of the click of the visit. The ID is saved for future requests.

Request parameters:

offer - offer identifier, needed when working with a global token.
flow - numeric flow ID to refine your search.
code - character flow ID to refine your search.
ip - use the specified user IP address instead of the automatically determined one.
to - time before which no click search is performed, in UNIX timestamp format. By default, clicks are searched for the last 24 hours.

The function returns a response as a JSON object with the following fields:

status - ok if success and error if failed.
error - error code.
click - found click ID.
offer - offer ID.
site - site ID.
flow - flow ID.
geo - click counrey ISO-code.
ip - click IP-address.
time - click time in UNIX timestamp format.
utms - tag utm_source.
utmc - tag utm_campaign.
utmn - tag utm_content.
utmt - tag utm_term.
utmm - tag utm_medium.

The following errors may occur when the function is running:

auth - authorization problem, check the token.
no-click - failed to find a click by the specified criteria.
no-offer - offer ID not set.

Example of a successful function response:

{ "status": "ok", "click": 1234, "geo": "us" }

Error example:

{ "status": "error", "error": "no-click" }

Fetching flow data

The function allows you to get a flow by its code, ID or click. The result will be the flow data.Parameters can be passed in both GET and POST part of the request.

URL: https://domain.com/api/site/flow.json?token=123-abcd&code={code}

Suggested use case: after installation, the application retrieves the name of the advertising campaign and uses it as the flow code. After receiving data, an iframe is opened by the flow link or the stream code is used for further postbacks.

Request parameters:

click - click ID.
flow - numeric flow ID.
code - character flow ID.

The function returns a response as a JSON object with the following fields:

status - ok if success and error if failed.
id - found flow ID.
code - character flow ID.
link - flow link for redirection.
offer - offer ID.
site - landing ID.
space - prelanding ID.
fb - Facebook pixel ID.
fbe - Facebook conversion event code.
ga - Google Analytics or Tag Manager ID.
gad - Google Analytics conversion event code.
tt - Tik-Tok pixel ID.
lki - Likee pixel ID.
vk - VK pixel ID.
mt - MailTarget counter ID.
mtrk - Yandex.Metrika counter ID.
utms - tag utm_source.
utmc - tag utm_campaign.
utmn - tag utm_content.
utmt - tag utm_term.
utmm - tag utm_medium.

The following errors may occur when the function is running:

auth - authorization problem, check the token.
no-id or bad-id - failed to find a flow for the specified ID.

Example of a successful function response:

{ "status": "ok", "id": 1234, "link": "https://r.domain.com/go1234" }

Error example:

{ "status": "error", "error": "no-click" }

Fetching offer data

The function allows you to get an offer by its ID, flow or click. The result will be the data of the offer. Parameters can be passed in both GET and POST part of the request.

URL: https://domain.com/api/site/offer.json?token=123-abcd&id={offer}

Request parameters:

offer - offer ID (recommended).
click - click ID.
flow - numeric flow ID.
code - character flow ID.

The function returns a response as a JSON object with the following fields:

status - ok if success and error if failed.
id - found offer ID.
name - the name of the offer that can be shown to the visitor.
geo - array of available counries ISO codes.
param - array of offer parameters.
price - array of offer price tags.
site - array of offer sites.

The following errors may occur when the function is running:

auth - authorization problem, check the token.
no-id or bad-id - failed to find an offer for the specified ID.