General API rules

The API lets you work with the network from your own scripts and services. You can send leads, pull statistics, manage flows and read the offer catalog. A request has exactly the same rights as your account in the cabinet: you see and change only your own data. This page shows how to make your first request and gives the rules that are the same for every function. The functions themselves are described on separate pages, linked at the end.

Your first request in two minutes#

To check that access works, you need no program or script. A browser is enough.

1. Find your token Open your profile in the cabinet and find the API-interface heading. The API token field holds your token: your account number and the key, joined by a hyphen, like {user}-{key}.

2. Build the request URL For the first try, request the offer list. The offer/names function takes no parameters. The URL is the API address of the network, the section name offer, the function name names, the response format json and your token in the id parameter:

   https://lk.dalead.pro/api/offer/names.json?id={token}

3. Open the URL in a browser Paste the URL into the address bar of the browser. Instead of a page, you get a response in JSON format. It is the list of your offers, with the offer number on the left and its name on the right. You will need the numbers when you start sending leads.

   JSON

   {
     "status": "ok",
     "data": {
       "24": "Hevital BabyBOOM",
       "31": "Meow Nutra",
       "2": "Waist Trainer"
     }
   }

   The response is shortened. The real one lists every offer available to you. You can do the same from the command line:

   BASH

   curl 'https://lk.dalead.pro/api/offer/names.json?id={token}'

If you get an error instead of the list, look at the error field:

• key — the token is missing or wrong. Check that you copied all of it with no spaces, and that you have not reset the key in your profile since then.
• access-denied — the network has hidden the offer catalog from affiliates. To check the token with another request, call wm/flows (see Flows). It returns the list of your flows, or an empty [] if you have no flows yet.
• func, request — the URL has a typo. See Errors.

Request URL#

A request is the API address of your network plus three parts: the application, the function and the response format. The application is a section of the API, the function is an action inside the section, and the format is an extension added to the function name after a dot. The token always goes in the id parameter.

https://lk.dalead.pro/api/{app}/{func}.{format}?id={token}

API applications described in this help.

The application, the function and the format are all required. If any part is missing (for example, you forgot to add .json to the function name), the platform answers with the request error and does not call the function.

Case does not matter in the names of the application, the function and the format: /api/OFFER/Names.JSON works the same as /api/offer/names.json. Parameter names are case-sensitive, so write them as the function description shows. The exception is adding a lead. There the field names are converted to lower case, because the data comes from other people's forms.

Token#

Every account has access to the API, and you do not need to turn it on separately. Sending leads is the exception: ask your manager for it. The token is your account number ({user}) and the API key: 32 characters, digits and the Latin letters a–f. They are joined by a hyphen. Your full token is {token}.

Pass the token in the id parameter of the query string, in every request: ?id={token}. With no token or a wrong one, the platform answers with the key error. If the account is blocked or disabled, the answer is the ban error.

The key is in your profile, in the API token field under the API-interface heading. The Generate new API token link is there too. After you confirm, the old key stops working at once, and the account number stays the same. Update the token in all your scripts and on every site where you wrote it in. For more, see Account and API key.

How to send a request#

You can call most functions with either GET or POST. GET is convenient for functions that read data. Functions that send data are better called with POST, because the URL length is limited.

You can pass parameters in three ways:

• In the query string — right in the URL: ?offer=31&phone=79001234567.
• As a form — in the body of a POST request, in the application/x-www-form-urlencoded format.
• As JSON — in the body of the request, in JSON format with the Content-Type: application/json header. The platform parses it and spreads it over the same fields as a form. The token is still passed in the query string.

If the same parameter arrives in both the URL and the body, the body wins.

Request tag

You can add a tag to any request: the z parameter in the query string, for example ...&z=meow-landing. The platform writes it to the API request log together with the request (the log is on by default). The network keeps the log and you cannot see it, but the tag helps when several landings or scripts work with one token. Tell support the tag and the time of the request, and the Administrator finds the request in question more easily.

A tag keeps lowercase Latin letters, digits, hyphens, underscores and dots. Spaces become hyphens, Russian letters are transliterated into Latin, and other characters are dropped: the tag Meow Привет! is recorded as meow-privet.

Limits and etiquette#

The platform does not limit the rate or the number of API requests, neither per minute nor per day. The API has no versions either, and the function URL has no version number. But every request loads the network, which all affiliates share, so follow these rules:

• Save the offer catalog (offer/list, offer/names, offer/show) on your side and refresh it on a schedule, not before every operation. Request offer/show for one offer at a time.
• Learn about lead status changes from the postbacks of the flow (see Postbacks). Use leads/list for selective checks and narrow it by dates.
• Add the z tag to your requests, so that when you look into errors you can see which script sent them.

Separately from the API, the rules for accepting leads apply: protection from duplicates and from mass sending from one IP address, and traffic filters. They work when a lead is added and are described on the Leads page.

Response format#

The extension in the function URL sets the response format. All examples in this help use json. Use it for your work too.

Response formats.

An unknown extension is not an error. The response comes as pretty-printed JSON with indents and line breaks, so it is easy to read by eye.

Response envelope

Almost all functions answer with an object that starts with the status field. Its value is ok or error. This is the response “envelope”. On success, the other fields depend on the function. On error, the error field holds the error code, and sometimes details: info is the reason, bad is the list of problem fields, and message is the error text from a third-party service.

{
  "status": "error",
  "error": "key"
}

Some functions return data with no envelope. Summary statistics and grouped statistics (wm/stats, wm/click) and the flow list (wm/flows) return the data directly. They have no status field, and an empty result looks like []. The errors of these functions come in the usual envelope. The page of each function says whether it has an envelope.

The result is duplicated in the response headers, which is the most reliable way for functions without an envelope. X-API-Status holds ok or error, X-API-Error holds the error code if there was an error, and X-Status holds the HTTP code that the platform would use to answer an error (200 or 400).

HTTP/1.1 200 OK
Content-Type: application/json; charset=utf-8
X-Status: 400
X-API-Status: error
X-API-Error: key

The real HTTP code is always 200, so the response reaches clients that do not read the body of an error response. If you prefer to catch errors by the HTTP code, add the statuscode=1 parameter to the query string. Then an error comes with code 400, and success still comes with 200.

Errors#

Before a request reaches the function, it passes through the API entry. Its errors are the same for all functions.

Errors at the API entry.

The error codes of the functions themselves are described on the function pages. Two codes appear almost everywhere, and both mean “not allowed”. access means you have no right to the action or the flow is someone else's. access-denied means the function or the data is closed to you (for example, the network has hidden the offer catalog, the offer is not available to you, or the function is meant for another role).

Reference values#

The lists below are common to the whole API. The pages Leads and Statistics and the Postbacks guide refer to them. The numbers and symbolic codes do not depend on the interface language.

Order phases

A phase is the state of an order from the affiliate's point of view, and your money depends on it. Every network has phases. A phase comes as a number in the phase field and as a symbolic code in the stage field. The same values go into the postback macros {phase} and {stage}.

Order phases.

Order statuses

A status is a step of order processing in the CRM of the network, from creation to buyout or decline. The phase and the status describe the same state of the order. The phase is for the affiliate and for money, and the status gives more detail. Which phase a status gives depends on the CPA model of the offer. See below.

There are twelve statuses, with codes from 1 to 12. The basic ones exist in every offer. The additional ones, the detailed steps of calling and delivery, are typical only for networks that sell goods.

Status codes.

The status code comes in the crm field of the leads/list response. It is the status of the order in the CRM, a code from the list above. The wm/stats function counts orders by status in the fields c1–c12.

In the models cps, cod and cor, an order in status 5 goes to “Trash” if its decline reason is in the set of trash reasons, and to “Cancel” in all other cases. See Decline reasons. In the models cpl, cpv and cpa, status 5 with an ordinary reason gives the “Approve” phase. See the table below.

How a status becomes a phase

The phase of an order is set by its status and the CPA model of the offer. The model is the model field in the offer catalog: cps, cpl, cpv, cpa, cod or cor. The model cpx works like cps. The network can assign another model to a single goal, affiliate or team. The table gives the status codes that the model puts into each phase.

CPA models: which status gives which phase. Status 5 is split by decline reason.

If the offer has a hold period, an order that the model should move to “Approve” first goes to “Hold” for that period and is then confirmed automatically.

Decline reasons

The decline reason comes in the reason field and applies only to cancelled orders, that is, orders in status 5. The value 0 means no reason is given. A reason from the set of trash reasons moves the cancel to the “Trash” phase (except in the cpa model), and such an order does not count in the approve rate among valid leads.

The network sets the set of trash reasons. The table marks the standard set that the system is installed with, and the network may have changed it. So rely on the phase of the order: an order with a reason from the set of the network comes in phase 5 (trash).

Decline reasons and the standard set of trash reasons.

Where next#

• Leads — send a lead and check the statuses of the leads you sent.
• Statistics — a summary by day and slices by any dimension.
• Flows — list, create, set up and delete flows, and upload expenses.
• Offers — the catalog, prices, landings and the archive of a ready-made site.

For how the key and the profile work in the cabinet, see Account and API key. For how the platform itself reports a change of lead status, see Postbacks.