FBM Affiliates APIs

(last update 2018.02.07)

FBM Affiliates support various API's to help use its features. All API's are RESTful.

API Keys
To access public API's you ened to generate Webmaster specific API key. To do that log into
appropriate Affiliates program and head to “API Keys” section. Use provided tools to generate and
remove API keys. Each key is platform specific. i.e. - if you generate key for Singlescash, it can't be
used for Lovercash.

Format
All data (request and response) is exchanged only in JSON.

Versions
When constructing API request, you need to specify API version. Once new version of API gets
created, previous one goes into deprecated state. API consumers should switch to new version in 2
months. If there are objective reasons why migration can’t be done in 2 months, notify Affiliates
team to request extra time. API consumers will be notified about new versions and will be provided
with information on how to make migration to new API.

API URL
To use APIs you need to make HTTP requests to API specific URLs. They are built in following
format: https://api.affbackend.com/<version>/<api_type>
Replace <version> with appropriate version. For example: v2
Replace <api_type> with appropriate type. For example: websites.
Some APIs require you to add parameters after URL, some do not. For example, if you request data
from StatsAPI you do not need to pass anything in URL. That’s because all required data will be in
POST body. However if you want to request information from WebsitesAPI you need to pass
additional information as those are GET requests. To request list of all websites that are added to
affiliates.dvipaff.com make GET request to:
https://api.affbackend.com/v2/websites/affiliates.dvipaff.com
Requests should be made to https://api.affbackend.com . Make sure to use https, to
avoid forced redirects.
Available API types
• websites - to request data about all websites in platform
• website - to request data about particular website
• stats – to request statistics data
 Requests and responses

Website Api
Currently supported API version: v2.

To get information about specific website (in this case examplewebsite.com) issue GET request in
such form:

GET https://api.affbackend.com/v2/website/examplewebsite.com

Response example in case examplewebsite.com is found:

{
"httpStatus": 200,
"httpTitle": "OK",
"apiCode": 200,
"apiDescription": "OK",
"data": {
"title": "Example website",
"domain": "examplewebsite.com",
"version": "Mainstream",
"platform": "Singlescash"
}
}

In case website is not found:

{
"httpStatus": 400,
"httpTitle": "Bad Request",
"apiCode": 400,
"apiDescription": "Validation error",
"apiErrors": {
"website": "Website not found."
}
}

In case search domain is not provided

{
"httpStatus": 400,
"httpTitle": "Bad Request",
"apiCode": 400,
"apiDescription": "Validation error",
"apiErrors": {
"domain": "Domain not provided."
}
}

Websites API
Currently supported API version: v2.
To get full list of all added and enabled websites issue GET request in such form:

GET https://api.affbackend.com/v2/websites/<platform>

Replace <platform> with platform that you are interested in. To get data about Singlescash, put
singlescash.com , to get data about Affiliates Dvipaff use affiliates.dvipaff.com .

Response example:

{
"httpStatus": 200,
"httpTitle": "OK",
"apiCode": 200,
"apiDescription": "OK",
"data": {
"firstwebsite.com": {
"title": "First website",
"domain": "firstwebsite.com",
"version": "Mainstream"
},
"secondwebsite.com": {
"title": "Second website",
"domain": "secondwebsitge.com",
"version": "Mainstream"
}
}
}

To get full list of all added and enabled websites that start with 'sec':

GET https://api.affbackend.com/v2/websites/singlescash.com/?
query=sec

Response example:

{
"httpStatus": 200,
"httpTitle": "OK",
"apiCode": 200,
"apiDescription": "OK",
"data": {
"secondwebsite.com": {
"title": "Second website",
"domain": "secondwebsitge.com",
"version": "Mainstream"
}
}
}

To get full list of all added and enabled websites with their aliases (alias is returned as key value in
response array):

GET https://api.affbackend.com/v2/websites/singlescash.com/?
with_aliases=1
Response example:

{
"httpStatus": 200,
"httpTitle": "OK",
"apiCode": 200,
"apiDescription": "OK",
"data": {
"secondwebsite.com": {
"title": "Second website",
"domain": "secondwebsitge.com",
"version": "Mainstream"
},
"join.secondwebsite.com": {
"title": "Second website",
"domain": "secondwebsitge.com",
"version": "Mainstream"
}
}
}

Response example in case no websites match query

{
"httpStatus": 200,
"httpTitle": "OK",
"apiCode": 200,
"apiDescription": "OK",
"data": {}
}

CustomPayoutRates API
Currently supported API version: v2. This API is available only with webmaster specific API keys.

To retrieve information about any custom payout rates for webmaster submit GET request in such
form:

GET https://api.affbackend.com/v2/custom_payout_rates/<platform>

Replace <platform> with platform that you are interested in. To get data about Singlescash, put
singlescash.com , to get data about Affiliates Dvipaff use affiliates.dvipaff.com .

Response example:

{
"httpStatus": 200,
"httpTitle": "OK",
"apiCode": 200,
"apiDescription": "OK",
"data": {
"0": {
"program": "Pay Per Upgrade (PPU)",
 "action": "Upgrade",
"site_version": "",
"website": "bikerplanet.com",
"payout_type": "Country",
"payout": "40.00 – 50.00",
"description": "CA 40.00, US 50.00"
},
"1": {
"program": "Pay Per Upgrade (PPU)",
"action": "Upgrade",
"site_version": "",
"website": "",
"payout_type": "Fixed",
"payout": "50.00",
"description": "Fixed: 50.00"
}
}
}

Stats API
Currently supported API version: v2.

StatsAPI provides simple access to statistics data in automated way. To query data issue POST
request to:

POST https://api.affbackend.com/v2/stats/<response_type>

In POST body provide JSON object with request variables. Such request variables are supported:

• start_date. Start date (yyyy-mm-dd). Mandatory field.

• end_date . End date (yyyy-mm-dd).
• platform . Platform that you are interested in. Example: singlescash.com .
Mandatory field.
• program . Program that you are interested in. Example: PPU . Mandatory field.
• group_by . Array of fields by which to group data. Default is program. In all situations
it’s allowed to group data by such fields: program, date, website, campaign,
adgroup, keywords, source, gender, age, age_bucket, lander,
country . You can provide multiple fields by which to group data. Example:
['website', 'adgroup']
• sort_by . Array of fields by which to sort data. If not provided, sort is done by one of
group columns. Available options – any of returned fields. To specify sort order, use ASC or
DESC. Example: ['profile' => 'DESC', 'earned' => 'DESC'].
• filters . Array of fields and values by which to filter data. Supported filters: website,
adgroup, campaign, source, keywords, age, age_bucket, gender,
lander, country. To set up filter use filter name as key. Values can be string or array.
Example: ['website' => 'bikerplanet.com', 'campaign' =>
['campaign1', 'campaign2']]
• compare_start_date . If you want to retrieve data by comparing stats in two periods
you need to set period with which to compare (yyyy-mm-dd). Compare period should be
older than stats period (i.e. start_date > compare_start_date).
• compare_end_date . To specify more than 1 day for compare period, use this field
 (yyyy-mm-dd).
• offset. How many records to skip. Integer.
• limit. How many records to return. Integer. Default is 100. Max is 1000.

Several <response_types> are supported. If none is provided, simplest data set will be returned.
Usually used if you want to query data that will be used in CSV files.
• decorated . Similar to default response type. Only difference is that earned values will
have $ sign attached to them.
• full . This is most useful in situations where you want to use response in some grids.
That’s because in addition to row data, this will also include information about total count of
records (so that you could know if you need to request one more page), totals for returned
rows as well as totals for full data set (when offset and limit are ignored).
• compared . If you set compare_start_date/compare_end_date and want to retrieve data in
compared format, use this response type. In this format you will get row data with
information about each period as well as difference calculated in % shift, total record count
and calculated totals for full data sets.
Example of full query:
POST https://api.affbackend.com/v2/stats/

{
"start_date": "2014-04-01",
"end_date": "2014-04-30",
"program": "PPU",
"platform": "singlescash.com",
"group_by": ["website"],
"sort_by": [
"profile": "DESC"
]
"offset": 200,
"limit": 400
}

This query translates to: give me statistics data for all users in Singlescash PPU (Pay Per Upgrade)
program, for April 2014, group data by website, sort by profile descending, skip 200 records and
return next 400.

In case of bad input data StatsAPI tends to fallback to defaults where that’s available. However we
encourage to set values even for fields, where defaults are used. That’s because defaults can change.

Example of successful data request:

{
"httpStatus": 200,
"httpTitle": "OK",
"apiCode": 200,
"apiDescription": "OK",
"data": {
"0": {
 "website": "bikerplanet.com",
"raw_click": 87,
"unique_click": 74,
"profile": 8,
"profile|unique_click": "1:8",
"upgrade": 1,
"upgrade|profile": "1:8",
"earned": "45"
},
"1": {
"website": "dateamillionaire.com",
"raw_click": 30,
"unique_click": 30,
"profile": 3,
"profile|unique_click": "1:10",
"upgrade": 0,
"upgrade|profile": "0:3",
"earned": "0"
}
}
}

Status codes
When possible, API will try to return appropriate HTTP codes and special API codes.

List of special API codes:

• 200 => OK
• 201 => Resource created
• 202 => Data accepted for further processing
• 207 => Partial data accepted for further processing
• 400 => Validation error
• 401 => Unauthorized
• 409 => Duplicate request detected
• 500 => Server error
• 999 => Unknown error

Supported gender IDs

• Male : male
• Female : female
• Transsexual : transsexual
• Crossdresser : crossdresser
• Group : group
• Couple : couple
• Couple Females : couple_females
• Couple Males: couple_males
• Sugar Daddy: sugar_daddy
 • Sugar Momma: sugar_momma
• Sugar Baby Female: sug_baby_female
• Sugar Baby Male: sugar_baby_male
• Sugar Baby TS: sugar_baby_ts
• Bull: bull
• Cuckoldress: cuckoldress
• Cuckold: cuckold
• Cuckold Couple: cuckold_couple
• Cuckquean: cuckquean
• Cuckcake: cuckcake
• Cuckquean Couple: cuckqueancouple
• Cougar: cougar
• Cub: cub
• Dominatrix: dominatrix
• Dom Male: dom_male
• Male with STD: male_with_std
• Female with STD: female_with_std
• Couple with STD: couple_with_std
• Male Alternative: male_alternativ
• Male Devotee: male_devotee
• Female Devotee: female_devotee
• Attached Male: attached_male
• Attached Female: attached_female
• FTM Transsexual: ftm_transsexual

SDK
To make it easy to use FBM Affiliates API's, special SDK is provided. However it's completely fine
to use API without SDK. If you are using SDK you can be sure, that it will always support all
newest features of FBM Affiliates APIs. And as SDK abstracts all API calls, you do not need to
know how to build requests and parse responses.
examples folder contains various SDK usage examples.

Requirements
PHP version 5.4 or higher
SDK is fully PSR-4 compliant. All you need to do is include the "Fbmaff/autoload.php" file
and you are ready to go.

Supported APIs
Following APIs are supported by SDK: WebsiteApi, WebsitesApi, StatsApi.

Overview about instantianting the API classes

Instantiation of all API classes happen in the same way. For example, to instantiate WebsiteAPI
class call $api = new Api\WebsiteApi($client, 2); and you are done. All other API
classes follow the same naming convention. First argument ($client) should be an instance of
Client\ApiClient . This class needs two objects passed to its constructor. First one should
implement an Transport\ITransport , but second should implement Auth\IBase.
Currently only Curl transport and Basic authentication are supported. Second argument for API
instantiation is API version. At the moment of writing only version 2 is supported.
To create an instance of Curl transport instantiate Transport\Curl and pass API hostname to its
constructor. If the provided value is not a string or an empty one an Exceptions\
InvalidHostnameException exception will be thrown.

To create an instance of Basic auth instantiate Auth\Basic and pass in username as first
parameter. API key should be supplied as second parameter. If the username is not provided or is
empty an Exceptions\MissingUsernameException exception will be thrown.

When API class is instantiated and you have done setup of all mandatory fields, you can use
$api→send() or $api->fetch(); method to actually perform request. After request is
sent you can use $api→success(); to check if call execution was successful.

WebsiteAPI
To get information about specific website which is added to Affiliates platform you need to use
Api\WebsiteApi. Once instantiated you will have access to following methods:
• setDomain(string $domain) to specify domain of dating website.
• fetch() to request data from API
• getData() to access data returned by API

WebsitesAPI
To retrieve all websites which are added in Affiliates platform you need to use Api\
WebsitesApi . Once instantiated you will have access to following methods:
• setQuery(string $query) to set query for websites (part of domain name). If not
set, all websites will be retrieved.
• setPlatform(string $platform) . To set up platform. This is mandatory.
• fetch() to request data from API
• fetchWithDomainAliases() to request data with domain aliases.
• getData() to retrieve returned data

CustomPayoutRatesAPI
To get information about custom payout rates for webmaster you need to use Api\
CustomPayoutRatesApi. Once instantiated you will have access to following methods:
• setPlatform(string $platform) to specify platform.
• fetch() to request data from API
• getData() to access data returned by API
StatsApi
To retrieve statistics information you need to use Api\StatsApi. After instantiation you will have
such methods available:
• setProgram(string $program) to specify program. This is mandatory field.
• setPlatform(string $platform) to specify platform.
• setDates(string $start_date, string $end_date = null)to specify
date range you are interested in .
• setGroupBy(array $group) to specify fields by which to group data.
• setSortBy(array $sort) to specify by which fields to sort data.
• setFilters(array $filters) to specify filters.
• setCompareDates(string $start_date, string $end_date = null)to
specify date range for compare period.
• setLimit(int $limit) to specify how many results to retrieve.
• setOffset(int $offset) to specify how many results to skip
• fetch()to send request to Affiliates API.
• fetchDecorated() to set response type to decorated and send request to API.
• fetchCompared() to set response type to compared and send request to API.
• fetchFull() to set response type to full and send request to API.
• getData() to parse data that was returned by API and retrieve it as array.

Status info
To getting status info from the API requests you can use following methods:
• getStatusMessage() - Returns the HTTP status (such as Bad Request)

• getStatusCode() - Returns the HTTPS status code (e.g. 400, 404, etc.)

• getApiMessage() - Returns the API status message (e.g. "Validation error", "Data
accepted for further processing")
• getApiCode() - Returns the API status code (e.g. 400, 404, etc.)

◦ Available codes:
◦ Success
▪ 200 - Status OK
▪ 201 - Status created
▪ 202 - Data accepted for further processing
▪ 207 - Partial data accepted for further processing
◦ Error
▪ 400 - Bad request (returned when some mandatory fields are missing for instance)
▪ 404 - Not found

• getApiErrors() - Returns a list of the errors. Please note that each API provides a
method getApiErrorsAsString() which is suitable for displaying a summary of the
errors.