API – documentation

API is used for remote communication with your affiliate environment. A good example is conversion approval, where you can also approve a conversion in AffilBox from the comfort of your e-shop or accounting software immediately after receiving payment. There is no longer a need to do this in two places.

NOTICE – HTTPS

POST data. XML queries are used to communicate with the server, and the server returns a response in XML indicating whether everything went well and, in case of an error, the cause.

Sample PHP code with information on how to add a new conversion can be found for PHP here.

Where can I find the API Url and the key?

The API URL and Api key can be found in your AffilBox license under Settings – User Settings.

Conversion:

Adding a conversion

This example adds a conversion with a value of 630:

[sourcecode language=”xml”]
<?xml version=”1.0″ encoding=”UTF-8″?>
<request>
<key>váš API klíč </key>
<method>AddConversion</method>
<partner_id>0c7ef928</partner_id>
<campaign_id>1</campaign_id>
<conversion_id>2589633</conversion_id>
<value>630</value>
</request>
[/sourcecode]

Parameters for API

Replace each parameter with the correct values as follows:

• key –  API key (string). This is your key, which can be found in your profile after logging in. (Settings – User Settings)
• partner_id – Partner’s email or affilId (string). ID of the partner you want to assign the commission to. This can be their affiliate code or email.
• campaign_id – Campaign ID (int). The ID of the campaign to which the commission belongs. The campaign ID can be found in the private campaign edit box with the Tracking Code. Look for the line “var campaign = XXX”.
• conversion_id – transaction ID (string). Most often the transaction ID is the order number or customer email. You will need this ID, for example, when approving a conversion – for comparison with the billing system.
• value – conversion price (double). The final commission value for the partner.
• channelId – promotional channel (string).  To see which source is driving the most conversions to your Affilbox. Learn more about this feature.
• orderValue – order price (double). The order amount, excluding VAT, shipping and handling. If this parameter is used, the classic calculation as in the conversion code will take place.

Mandatory items

<count_value>true</count_value> – Specifies whether to count commission on the order price (true / false) – if this parameter is not filled in, the value false is taken automatically.
<note> – note (string).
<currency> – currency (string). Currency, waiting for the currency label – must have the Currencies plugin activated.

Adding a bonus

XML kód:

[sourcecode language=”xml”]
<?xml version=”1.0″ encoding=”UTF-8″?>
<request>
<key>abcdefghijklm</key>
<method>AddBonus</method>
<partner_id>PARTNER_ID</partner_id>
<text>TEXT</text>
<value>VALUE</value>
</request>
[/sourcecode]

Parameters for API

Replace each parameter with the correct values as follows:

• key – API key (string). This is your key, which can be found in your profile after logging in.
• method – AddBonus – this is the method to add a bonus.
• partner_id – Partner’s email or affilId (string). ID of the partner you want to assign the commission to. It can be their affiliate code or email.
• text – description (string). Here you fill in a description of what the affiliate received the commission for.
• value – amount (double). The total amount of the conversion.

Conversion confirmation/denial

XML code:

[sourcecode language=”xml”]
<?xml version=”1.0″ encoding=”UTF-8″?>
<request>
<key>abcdefghijklm</key>
<method>ConfirmConversion</method>
<conversion_id>CONVERSION_ID</conversion_id>
<value>VALUE</value>
</request>
[/sourcecode]

Parameters for API

Replace each parameter with the correct values as follows:

• key – API key (string). This is your key, which can be found in your profile after logging in.
• method – ConfirmConversion – this is the method to confirm the conversion.
• conversion_id – transaction id (string). ID you assigned to the conversion.
• value – Value true / false depending on whether you want to approve or reject the conversion.
• campaign_id – campaign id (optional – needs to be added if you have the same transaction ID in multiple campaigns)
• note – note (string)

Get information about multiple conversions

XML code:

[sourcecode language=”xml”]
<?xml version=”1.0″ encoding=”UTF-8″?>
<request>
<key>abcdefghijklm</key>
<method>GetConversions</method>
<partner_id>PARTNER_ID</partner_id>
<filter_state>STATE</filter_state>
<filter_date_from>DATE_FROM</filter_date_from>
<filter_date_to>DATE_TO</filter_date_to>
</request>
[/sourcecode]

Parameters for API

Replace each parameter with the correct values as follows:

• key – API key (string). This is your key, which can be found in your profile after logging in.
• method – GetConversions – this is the method to get the list of conversions.
• partner_id– Partner’s email or affilId (string). ID of the advertiser whose conversions we want to get. It can be their affiliate code or email.
• coupon – The coupon that was used to create the conversion.
• filter_state – Selection of conversions of a certain state only – allowed values: pending / rejection / authorized / invoiced.
• filter_date_from – Date from when to list conversions, format “yyyy-mm-dd hh:mm”.
• filter_date_to – Date until when to dump conversions, format “yyyy-mm-dd hh:mm”
• campaign_id – campaign id (int). ID of the campaign to which the commission belongs. The campaign ID can be found in the private campaign edit box with the Tracking code. Look for the line “var campaign = XXX”.
• conversion_id – conversion id (string)
• conversions_id – multiple conversion ids (string). Multiple conversion ids separated by semicolons.

Getting information about one conversion

XML code:

[sourcecode language=”xml”]
<?xml version=”1.0″ encoding=”UTF-8″?>
<request>
<key>abcdefghijklm</key>
<method>GetConversion</method>
<conversion_id>CONVERSION_ID</conversion_id>
</request>
[/sourcecode]

Parameters:

Replace the individual parameters with the correct values as follows:

• key – API key (string). This is your key, which can be found in your profile after logging in.
• method – GetConversion – this is the method to get conversion information.
• conversion_id– transaction id (string). The ID you assigned to the conversion.
• coupon – the coupon that was used to create the conversion.

Changing a conversion

XML code:

[sourcecode language=”xml”]
<?xml version=”1.0″ encoding=”UTF-8″?>
<request>
<key>abcdefghijklm</key>
<method>UpdateConversion</method>
<partner_id>PARTNER_ID</partner_id>
<conversion_id>CONVERSION_ID</conversion_id>
<state>NEW_STATE</filter_state>
<value>NEW_VALUE</value>
<commission>NEW_COMISSION</value>
</request>
[/sourcecode]

Parameters:

Replace the individual parameters with the correct values as follows:

• key – API key (string). This is your key, which can be found in your profile after logging in.
• method – UpdateConversion – change conversion values.
• partner_id – (string) Partner’s email or affilId (string). ID of the partner who owns the conversion.
• conversion_id – (string) ID of the conversion we want to change.
• state – New conversion state – allowed values: pending / rejection / authorized / invoiced.
• value – (double).
• commission – (double). Commission amount.
• campaign_id – campaign id (int) ID  ID of the campaign to which the commission belongs. The campaign ID can be found in the private campaign edit box with the Tracking Code. Look for the line “var campaign = XXX”.
• note – note (string)

for the “update conversion” function you can also change the conversion to Pending  –  “waiting”

Partners:

Getting partner information

XML code:

[sourcecode language=”xml”]
<?xml version=”1.0″ encoding=”UTF-8″?>
<request>
<key>abcdefghijklm</key>
<method>GetPartner</method>
<partner_id>PARTNER_ID</partner_id>
</request>
[/sourcecode]

Parameters:

Replace the individual parameters with the correct values as follows:

• key – API key (string). This is your key, which can be found in your profile after logging in.
• method – GetPartner – this is the method of getting information about the partner.
• partner_id – Partner’s email or affilId (string). ID of the partner whose information you want to get. It can be their affiliate code or email.

Getting a list of affiliates

XML code:

[sourcecode language=”xml”]
<?xml version=”1.0″ encoding=”UTF-8″?>
<request>
<key>abcdefghijklm</key>
<method>GetPartners</method>
</request>
[/sourcecode]

Parameters:

Replace the individual parameters with the correct values as follows:

• key – API key (string). This is your key, which can be found in your profile after logging in.
• method – GetPartners – this is the method to get a list of all partners.
• register_from – register from (YYYY-mm-dd)
• register_to – register by (YYYY-mm-dd)
• last_login_from – last login since (YYYY-mm-dd)
• last_login_to – last login before (YYYY-mm-dd)
• consent_sharing – the date on which your partner consented to receive marketing communications.

Create a new partner or get information about an existing partner

XML code:

[sourcecode language=”xml”]
<?xml version=”1.0″ encoding=”UTF-8″?>
<request>
<key>abcdefghijklm</key>
<method><strong>GetOrCreatePartner</strong></method>
</request>
[/sourcecode]

Parameters:

• key – API key (string). This is your key, which can be found in your profile after logging in.
• affilid – optional parameter (string) to create a custom affiliate ID shape – otherwise it is generated automatically by our system.
• email – email (string)

Adding click-throughs

XML code:

[sourcecode language=”xml”]
<?xml version=”1.0″ encoding=”UTF-8″?>
<request>
<key>abcdefghijklm</key>
<method>AddClick</method>
</request>
[/sourcecode]

Parameters:

• key – API key (string). This is your key, which can be found in your profile after logging in.
• method – AddClick
• partner_id – partner email or affilid (string)
• campaign_id – campaign id (int)
• date – date (YYYY-mm-dd H:i:s)
• count – number (int)

Mandatory parameter for API

• channelId – promotional channel (string). To see from which source you get the most clicks to your Affilbox.

Get a list of campaigns

XML code:

[sourcecode language=”xml”]
<?xml version=”1.0″ encoding=”UTF-8″?>
<request>
<key>abcdefghijklm</key>
<method>GetCampaigns</method>
</request>
[/sourcecode]

Parameters:

• key – API key (string). This is your key, which can be found in your profile after logging in.
• partner_id – you can add a filter only on a specific advertiser. Partner’s email or affilId (string). It can be their affiliate code or email.

Return value NO DATA

If the API returns an error with “NO DATA” information, you probably did not send an XML request in the POST variable “data”. See the examples at the beginning of this article for how to do this in PHP and C#.

API v2

We are preparing a new version of the REST API that will allow you to pull even more information from AffilBox than before.