A reference guide to the Tapfiliate REST API.

The Tapfiliate API is based around REST. Our API has predictable, resource-oriented URLs, and uses HTTP response codes to indicate API errors. We use built-in HTTP features, like HTTP authentication and HTTP verbs, which are understood by off-the-shelf HTTP clients. We support cross-origin resource sharing, allowing you to interact securely with our API from a client-side web application (though you should never expose your secret API key in any public website’s client-side code). JSON is returned by all API responses, including errors. We keep our customers up to date on new changes on the Tapfiliate API through our changelog.

Version

The current version of the API is V1.6. A changelog from 1.5 can be found here: https://tapfiliate.com/blog/new-api-version-v1-6-released/

Authentication

Authentication with the Tapfiliate API is achieved by sending your X-Api-Key along in the header of every request:

X-Api-Key: “YOUR_API_KEY”

You can find and manage your Api Key in your account settings. Your API keys can approve commissions, so be sure to keep them secret! You should not share your API key anywhere where other people can see them (frontend javascript code, public repo’s, blogs et cetera).

All of your API requests must be made over HTTPS. Plain HTTP calls will fail. API requests without authentication will also fail.

Pagination

Requests that return multiple items will be paginated to 25 items by default. You can specify further pages with the ?page parameter.

$ curl 'https://api.tapfiliate.com/1.6/conversions/?page=2'

Page numbering is 1-based. Omitting the ?page parameter will return the first page.

The pagination info is included in the Link header.

Link: <https://api.tapfiliate.com/1.6/conversions/?page=3>; rel="next",
  <https://api.tapfiliate.com/1.6/conversions/?page=51>; rel="last"

Linebreak is included for readability.

The possible rel values are:

NameDescription
nextShows the URL of the immediate next page of results.
lastShows the URL of the last page of results.
firstShows the URL of the first page of results.
prevShows the URL of the immediate previous page of results.

Rate Limiting

Most endpoints have rate limits. Rate limits are communicated through the following headers:

HeaderDescription
X-Ratelimit-LimitThe number of total allowed requests within a given period
X-Ratelimit-RemainingThe number of requests you have left before exceeding the rate limit
X-Ratelimit-ResetWhen your number of requests will reset (Unix Timestamp in seconds)

Misc

  • Note that we do output NULL properties as of V1.3

Retrieve a Customer

GET/customers/{id}/
Response:200

URI Parameters

id
required
string
Example: cu_eXampl3

The Tapfiliate generated id of the Customer to perform action with.

GET https://api.tapfiliate.com/1.6/customers/cu_eXampl3/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/customers/{id}/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "id": "cu_eXampl3",
  "customer_id": "USER123",
  "status": "trial",
  "created_at": "2021-07-02T09:55:20+00:00",
  "click": {
    "created_at": "2021-03-03T12:39:19+0000",
    "referrer": "https://example-blog.inc/check-out-johns-product/",
    "landing_page": "https://tapper.inc/johns-cool-product/"
  },
  "program": {
    "id": "johns-affiliate-program",
    "title": "John's affiliate program",
    "currency": "USD"
  },
  "affiliate": {
    "id": "janejameson",
    "firstname": "Jane",
    "lastname": "Jameson"
  },
  "affiliate_meta_data": null,
  "meta_data": {
    "foo": "bar"
  },
  "warnings": null
}

Update a Customer

PATCH/customers/{id}/
Response:200

URI Parameters

id
required
string
Example: cu_eXampl3

The Tapfiliate generated id of the Customer to perform action with.

Arguments

customer_id
optional
string

The id for this customer in your system. The customer id should be unique for each customer.

meta_data
optional
object

Meta data for this resource

Child Arguments

PATCH https://api.tapfiliate.com/1.6/customers/cu_eXampl3/

Code Example

const request = require('request');

const options = {
  method: 'PATCH',
  url: 'https://api.tapfiliate.com/1.6/customers/{id}/',
  headers: {'content-type': 'application/json', 'X-Api-Key': 'SOME_STRING_VALUE'},
  body: {customer_id: '<ADD STRING VALUE>', meta_data: {}},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Request

{
  "customer_id": "USER456",
  "meta_data": {
    "buz": "baz"
  }
}

Example Response

{
  "id": "cu_eXampl3",
  "customer_id": "USER456",
  "status": "trial",
  "created_at": "2021-07-02T09:55:20+00:00",
  "click": {
    "created_at": "2021-03-03T12:39:19+0000",
    "referrer": "https://example-blog.inc/check-out-johns-product/",
    "landing_page": "https://tapper.inc/johns-cool-product/"
  },
  "program": {
    "id": "johns-affiliate-program",
    "title": "John's affiliate program",
    "currency": "USD"
  },
  "affiliate": {
    "id": "janejameson",
    "firstname": "Jane",
    "lastname": "Jameson"
  },
  "affiliate_meta_data": null,
  "meta_data": {
    "buz": "baz"
  },
  "warnings": null
}

Delete a Customer

DELETE/customers/{id}/
Response:204

URI Parameters

id
required
string
Example: cu_eXampl3

The Tapfiliate generated id of the Customer to perform action with.

DELETE https://api.tapfiliate.com/1.6/customers/cu_eXampl3/

Code Example

const request = require('request');

const options = {method: 'DELETE', url: 'https://api.tapfiliate.com/1.6/customers/{id}/'};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

List all Customers

GET/customers/{?program_id,customer_id,affiliate_id,date_from,date_to}
Response:200

URI Parameters

program_id
optional
string
Example: johns-affiliate-program

The program Id

customer_id
optional
string
Example: USER123

The id for this customer in your system. The customer id should be unique for each customer.

affiliate_id
optional
string
Example: janejameson

The affiliate Id

date_from
optional
string
Example: 2022-01-01

Date From

date_to
optional
string
Example: 2025-12-31

Date To

GET https://api.tapfiliate.com/1.6/customers/?program_id=johns-affiliate-program&customer_id=USER123&affiliate_id=janejameson&date_from=2022-01-01&date_to=2025-12-31

Example Response

[
  {
    "id": "cu_eXampl3",
    "customer_id": "USER123",
    "status": "trial",
    "created_at": "2021-07-02T09:55:20+00:00",
    "click": {
      "created_at": "2021-03-03T12:39:19+0000",
      "referrer": "https://example-blog.inc/check-out-johns-product/",
      "landing_page": "https://tapper.inc/johns-cool-product/"
    },
    "program": {
      "id": "johns-affiliate-program",
      "title": "John's affiliate program",
      "currency": "USD"
    },
    "affiliate": {
      "id": "janejameson",
      "firstname": "Jane",
      "lastname": "Jameson"
    },
    "affiliate_meta_data": null,
    "meta_data": {
      "foo": "bar"
    },
    "warnings": null
  }
]

Create a Customer

POST/customers/{?override_max_cookie_time}
Response:200

You are required to use either a Tracking id, referral code, click id, coupon code, or asset_id & source_id combination. If more than one of these is sent, the precedence will be as follows (highest to lowest): Coupon, Referral Code, Click Id, Asset id + Source id, Tracking id

Please refer to our REST API integration guide for more info.

URI Parameters

override_max_cookie_time
optional
boolean
Default: false 

Arguments

referral_code
optional
string

An affiliate’s referral code. This corresponds to the value of ref= in their referral link

tracking_id
optional
string

XXX-XXXX-XXXX-XXXXX (string) - The tracking id, to be retrieved from our javascript library. Please refer to our REST API integration guide for more info.

click_id
optional
string

abc (string, optional) - The click id. Used to add additional reporting information.

coupon
optional
string

A coupon code to track the conversion by

asset_id
optional
string

The asset id

source_id
optional
string

The source id

customer_id
required
string

The id for this customer in your system. The customer id should be unique for each customer.

status
optional
string

Determines the intial status for the customer. You can read more about statuses here. Defaults to “new” if none is passed.

user_agent
optional
string

The client’s user agent string. Used for statistics and fraud detection.

ip
optional
string

The client’s ip. Used for fraud detection.

meta_data
optional
object

Meta data for this resource

Child Arguments

POST https://api.tapfiliate.com/1.6/customers/?override_max_cookie_time=

Example Request

{
  "coupon": "JANE10OFF",
  "customer_id": "USER789",
  "status": "trial",
  "meta_data": {
    "tim": "tam"
  },
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.100 Safari/537.36",
  "ip": "111.11.11.111"
}

Example Response

{
  "id": "cu_0Th3r",
  "customer_id": "USER789",
  "status": "trial",
  "created_at": "2021-07-02T09:55:20+00:00",
  "click": null,
  "program": {
    "id": "johns-affiliate-program",
    "title": "John's affiliate program",
    "currency": "USD"
  },
  "affiliate": {
    "id": "janejameson",
    "firstname": "Jane",
    "lastname": "Jameson"
  },
  "affiliate_meta_data": null,
  "meta_data": {
    "tim": "tam"
  },
  "warnings": null
}

Approve or disapprove a commission

Cancel a customer

DELETE/customers/{id}/status/
Response:200

URI Parameters

id
required
string
Example: cu_eXampl3Pay1ng

The Tapfiliate generated id of the customer.

DELETE https://api.tapfiliate.com/1.6/customers/cu_eXampl3Pay1ng/status/

Code Example

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://api.tapfiliate.com/1.6/customers/{id}/status/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "id": "cu_eXampl3Pay1ng",
  "customer_id": "USER666",
  "status": "canceled",
  "created_at": "2021-07-02T09:55:20+00:00",
  "click": {
    "created_at": "2021-03-03T12:39:19+0000",
    "referrer": "https://example-blog.inc/check-out-johns-product/",
    "landing_page": "https://tapper.inc/johns-cool-product/"
  },
  "program": {
    "id": "johns-affiliate-program",
    "title": "John's affiliate program",
    "currency": "USD"
  },
  "affiliate": {
    "id": "janejameson",
    "firstname": "Jane",
    "lastname": "Jameson"
  },
  "affiliate_meta_data": null,
  "meta_data": {
    "foo": "bar"
  },
  "warnings": null
}

Uncancel a customer

PUT/customers/{id}/status/
Response:200

The customer will jump back to the appropriate status. You can read more about status statuses here

URI Parameters

id
required
string
Example: cu_eXampl3Pay1ng

The Tapfiliate generated id of the customer.

PUT https://api.tapfiliate.com/1.6/customers/cu_eXampl3Pay1ng/status/

Code Example

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.tapfiliate.com/1.6/customers/{id}/status/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "id": "cu_eXampl3Pay1ng",
  "customer_id": "USER666",
  "status": "paying",
  "created_at": "2021-07-02T09:55:20+00:00",
  "click": {
    "created_at": "2021-03-03T12:39:19+0000",
    "referrer": "https://example-blog.inc/check-out-johns-product/",
    "landing_page": "https://tapper.inc/johns-cool-product/"
  },
  "program": {
    "id": "johns-affiliate-program",
    "title": "John's affiliate program",
    "currency": "USD"
  },
  "affiliate": {
    "id": "janejameson",
    "firstname": "Jane",
    "lastname": "Jameson"
  },
  "affiliate_meta_data": null,
  "meta_data": {
    "foo": "bar"
  },
  "warnings": null
}

Retrieve meta data

GET/customers/{id}/meta-data/
Response:200

URI Parameters

id
required
string
Example: cu_eXampl3

The Tapfiliate generated id of the customer.

GET https://api.tapfiliate.com/1.6/customers/cu_eXampl3/meta-data/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/customers/{id}/meta-data/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "foo": "bar"
}

Update (replace) meta data

PUT/customers/{id}/meta-data/
Response:200

URI Parameters

id
required
string
Example: cu_eXampl3

The Tapfiliate generated id of the customer.

PUT https://api.tapfiliate.com/1.6/customers/cu_eXampl3/meta-data/

Code Example

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.tapfiliate.com/1.6/customers/{id}/meta-data/',
  headers: {'content-type': 'application/json', 'X-Api-Key': 'SOME_STRING_VALUE'},
  body: {key: '<ADD STRING VALUE>'},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Request

{
  "foo": "bar",
  "baz": "qux"
}

Example Response

{
  "foo": "bar",
  "baz": "qux"
}

Retrieve meta data by key

GET/customers/{id}/meta-data/{key}/
Response:200

URI Parameters

id
required
string
Example: cu_eXampl3

The Tapfiliate generated id of the customer.

key
required
string
Example: foo

The meta data key.

GET https://api.tapfiliate.com/1.6/customers/cu_eXampl3/meta-data/foo/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/customers/{id}/meta-data/{key}/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "value": "bar"
}

Set meta data by key

PUT/customers/{id}/meta-data/{key}/
Response:200

URI Parameters

id
required
string
Example: cu_eXampl3

The Tapfiliate generated id of the customer.

key
required
string
Example: foo

The meta data key.

PUT https://api.tapfiliate.com/1.6/customers/cu_eXampl3/meta-data/foo/

Code Example

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.tapfiliate.com/1.6/customers/{id}/meta-data/{key}/',
  headers: {'content-type': 'application/json', 'X-Api-Key': 'SOME_STRING_VALUE'},
  body: {value: '<ADD STRING VALUE>'},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Request

{
  "value": "bar"
}

Example Response

{
  "value": "bar"
}

Delete meta data by key

DELETE/customers/{id}/meta-data/{key}/
Response:204

URI Parameters

id
required
string
Example: cu_eXampl3

The Tapfiliate generated id of the customer.

key
required
string
Example: foo

The meta data key.

DELETE https://api.tapfiliate.com/1.6/customers/cu_eXampl3/meta-data/foo/

Code Example

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://api.tapfiliate.com/1.6/customers/{id}/meta-data/{key}/'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Retrieve a Conversion

GET/conversions/{conversion_id}/
Response:200

URI Parameters

conversion_id
required
number
Example: 1

Numeric id of the conversion to perform action with.

GET https://api.tapfiliate.com/1.6/conversions/1/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/conversions/{conversion_id}/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "id": 1,
  "external_id": "ORD123",
  "amount": 550,
  "click": {
    "created_at": "2021-03-03T12:39:19+0000",
    "referrer": "https://example-blog.inc/check-out-johns-product/",
    "landing_page": "https://tapper.inc/johns-cool-product/"
  },
  "commissions": [
    {
      "id": 1,
      "conversion_sub_amount": 550,
      "amount": 55,
      "commission_type": "standard",
      "approved": true,
      "affiliate": {
        "id": "janejameson",
        "firstname": "Jane",
        "lastname": "Jameson"
      },
      "kind": "regular",
      "currency": "USD",
      "created_at": null,
      "payout": null,
      "comment": null,
      "final": null,
      "commission_name": "standard"
    }
  ],
  "program": {
    "id": "johns-affiliate-program",
    "title": "John's affiliate program",
    "currency": "USD"
  },
  "affiliate": {
    "id": "janejameson",
    "firstname": "Jane",
    "lastname": "Jameson"
  },
  "customer": {
    "id": "cu_eXampl30th3r",
    "customer_id": "USER999",
    "status": "paying"
  },
  "affiliate_meta_data": null,
  "meta_data": {
    "foo": "bar",
    "tap": "awesome"
  },
  "created_at": "2021-03-03T12:39:19+0000",
  "warnings": null
}

Update a Conversion

PATCH/conversions/{conversion_id}/{?recalculate_commissions}
Response:200

URI Parameters

conversion_id
required
number
Example: 1

Numeric id of the conversion to perform action with.

recalculate_commissions
optional
bool
Example: false

Also re-calculate commissions when changing the Conversion amount

Arguments

amount
optional
number

The new amount for the commission

external_id
optional
string

A unique id for this conversion. It can be anything that is meaningful to you, like an order number, user id, email adres etc… After a conversion has taken place, you can find this id alongside the conversion on our platform.

meta_data
optional
object

Meta data for this resource

Child Arguments

PATCH https://api.tapfiliate.com/1.6/conversions/1/?recalculate_commissions=false

Example Request

{
  "amount": 17.95,
  "external_id": "ORD123",
  "meta_data": {
    "baz": "qux"
  }
}

Example Response

{
  "id": 1,
  "external_id": "ORD123",
  "amount": 17.95,
  "click": {
    "created_at": "2021-03-03T12:39:19+0000",
    "referrer": "https://example-blog.inc/check-out-johns-product/",
    "landing_page": "https://tapper.inc/johns-cool-product/"
  },
  "commissions": [
    {
      "id": 1,
      "conversion_sub_amount": 550,
      "amount": 55,
      "commission_type": "standard",
      "approved": true,
      "affiliate": {
        "id": "janejameson",
        "firstname": "Jane",
        "lastname": "Jameson"
      },
      "kind": "regular",
      "currency": "USD",
      "created_at": null,
      "payout": null,
      "comment": null,
      "final": null,
      "commission_name": "standard"
    }
  ],
  "program": {
    "id": "johns-affiliate-program",
    "title": "John's affiliate program",
    "currency": "USD"
  },
  "affiliate": {
    "id": "janejameson",
    "firstname": "Jane",
    "lastname": "Jameson"
  },
  "customer": {
    "id": "cu_eXampl30th3r",
    "customer_id": "USER999",
    "status": "paying"
  },
  "affiliate_meta_data": null,
  "meta_data": {
    "baz": "qux"
  },
  "created_at": "2021-03-03T12:39:19+0000",
  "warnings": null
}

Delete a Conversion

DELETE/conversions/{conversion_id}/
Response:204

URI Parameters

conversion_id
required
number
Example: 1

Numeric id of the conversion to perform action with.

DELETE https://api.tapfiliate.com/1.6/conversions/1/

Code Example

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://api.tapfiliate.com/1.6/conversions/{conversion_id}/'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

List all conversions

GET/conversions/{?program_id,external_id,affiliate_id,pending,date_from,date_to}
Response:200

URI Parameters

program_id
optional
string
Example: johns-affiliate-program

The program Id

external_id
optional
string
Example: ORD123

The external Id. This is the unique id from your system or shopping cart. This id was passed when the conversions was first tracked.

affiliate_id
optional
string
Example: janejameson

The affiliate Id

pending
optional
bool
Example: false

Only show conversions that have pending commissions

date_from
optional
string
Example: 2022-01-01

Date From

date_to
optional
string
Example: 2025-12-31

Date To

GET https://api.tapfiliate.com/1.6/conversions/?program_id=johns-affiliate-program&external_id=ORD123&affiliate_id=janejameson&pending=false&date_from=2022-01-01&date_to=2025-12-31

Example Response

[
  {
    "id": 1,
    "external_id": "ORD123",
    "amount": 550,
    "click": {
      "created_at": "2021-03-03T12:39:19+0000",
      "referrer": "https://example-blog.inc/check-out-johns-product/",
      "landing_page": "https://tapper.inc/johns-cool-product/"
    },
    "commissions": [
      {
        "id": 1,
        "conversion_sub_amount": 550,
        "amount": 55,
        "commission_type": "standard",
        "approved": true,
        "affiliate": {
          "id": "janejameson",
          "firstname": "Jane",
          "lastname": "Jameson"
        },
        "kind": "regular",
        "currency": "USD",
        "created_at": null,
        "payout": null,
        "comment": null,
        "final": null,
        "commission_name": "standard"
      }
    ],
    "program": {
      "id": "johns-affiliate-program",
      "title": "John's affiliate program",
      "currency": "USD"
    },
    "affiliate": {
      "id": "janejameson",
      "firstname": "Jane",
      "lastname": "Jameson"
    },
    "customer": {
      "id": "cu_eXampl30th3r",
      "customer_id": "USER999",
      "status": "paying"
    },
    "meta_data": {
      "foo": "bar",
      "tap": "awesome"
    },
    "created_at": "2021-03-03T12:39:19+0000",
    "warnings": null,
    "affiliate_meta_data": null
  }
]

Create a conversion

POST/conversions/{?override_max_cookie_time}
Response:200

You are required to use either a referral code, customer_id, click id, coupon code, tracking id, or asset_id & source_id combination. If more than one of these is sent, the precedence will be as follows (highest to lowest): Customer id, Coupon, Referral Code, Click Id, Asset id + Source id, Tracking id

URI Parameters

override_max_cookie_time
optional
boolean
Default: false 

Arguments

referral_code
optional
string

An affiliate’s referral code. This corresponds to the value of ref= in their referral link.

tracking_id
optional
string

XXX-XXXX-XXXX-XXXXX (string) - The tracking id, to be retrieved from our javascript library. Please refer to our REST API integration guide for more info.

click_id
optional
string

The click id. Used to add additional reporting information.

coupon
optional
string

A coupon code to track the conversion by

currency
optional
string

The three letter ISO currency code. Override the program’s default currency for this conversion by explicitely passing a currency code.

asset_id
optional
string

The asset id

source_id
optional
string

The source id

external_id
optional
string

A unique id for this conversion. It can be anything that is meaningful to you, like an order number, user id, email adres etc… After a conversion has taken place, you can find this id alongside the conversion on our platform. This makes it very easy to cross-reference data on our platform with your own administration. This id has to be unique for every conversion.

amount
optional
number

The conversion amount

customer_id
optional
string

The id for the current customer in your system. Depending on your program settings, this can be used for recurring / lifetime commissions. You can read more about this here

commission_type
optional
string

If no commission type is supplied, the programs default commission type is used

commissions
optional
array

Will override “amount” and “commission_type” if set

meta_data
optional
object

Meta data for this resource

Child Arguments

program_group
optional
string

The program group id

user_agent
optional
string

The client’s user agent string. Used for statistics and fraud detection.

ip
optional
string

The client’s ip. Used for fraud detection.

POST https://api.tapfiliate.com/1.6/conversions/?override_max_cookie_time=

Example Request

{
  "coupon": "JANE10OFF",
  "external_id": "ORD005",
  "amount": 100,
  "currency": "EUR",
  "meta_data": {
    "foo": "bar"
  },
  "program_group": "my-group",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X 10_14_1) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/75.0.3770.100 Safari/537.36",
  "ip": "111.11.11.111"
}

Example Response

{
  "id": 2,
  "external_id": "ORD005",
  "amount": 100,
  "click": null,
  "commissions": [
    {
      "id": 2,
      "conversion_sub_amount": 100,
      "amount": 10,
      "commission_type": "standard",
      "approved": null,
      "affiliate": {
        "id": "janejameson",
        "firstname": "Jane",
        "lastname": "Jameson"
      },
      "kind": "regular",
      "currency": "EUR",
      "created_at": "2021-03-03T12:39:19+0000",
      "payout": null,
      "comment": null,
      "final": null,
      "commission_name": "standard"
    },
    {
      "id": 3,
      "conversion_sub_amount": 100,
      "amount": 5,
      "commission_type": "level-2",
      "approved": null,
      "kind": "level",
      "affiliate": {
        "id": "sandrasanderson",
        "firstname": "Sandra",
        "lastname": "Sanderson"
      },
      "currency": "EUR",
      "created_at": "2021-03-03T12:39:19+0000",
      "payout": null,
      "comment": null,
      "final": null,
      "commission_name": "Level 2"
    }
  ],
  "program": {
    "id": "johns-affiliate-program",
    "title": "John's affiliate program",
    "currency": "USD"
  },
  "affiliate": {
    "id": "janejameson",
    "firstname": "Jane",
    "lastname": "Jameson"
  },
  "customer": null,
  "meta_data": {
    "foo": "bar"
  },
  "created_at": "2021-03-03T12:39:19+0000",
  "warnings": null,
  "affiliate_meta_data": null
}

Add commissions to a conversion

POST/conversions/{conversion_id}/commissions/
Response:200

URI Parameters

conversion_id
required
number
Example: 1

Numeric id of the conversion to add the commission(s) to.

Arguments

conversion_sub_amount
required
number

The amount on which the commission should be calculated using the supplied, or the program’s default commission type

commission_type
optional
string

If no commission type is supplied, the programs default commission type is used

comment
optional
string

A comment for this commission. The comment will be visible to the affiliate

POST https://api.tapfiliate.com/1.6/conversions/1/commissions/

Code Example

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://api.tapfiliate.com/1.6/conversions/{conversion_id}/commissions/',
  headers: {'content-type': 'application/json', 'X-Api-Key': 'SOME_STRING_VALUE'},
  body: {
    conversion_sub_amount: 0,
    commission_type: '<ADD STRING VALUE>',
    comment: '<ADD STRING VALUE>'
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Request

{
  "conversion_sub_amount": 50,
  "commission_type": "mycommissiontype",
  "comment": "Awesome!"
}

Example Response

[
  {
    "id": 3,
    "conversion_sub_amount": 20,
    "amount": 2,
    "commission_type": "standard",
    "approved": null,
    "kind": "regular",
    "affiliate": {
      "id": "janejameson",
      "firstname": "Jane",
      "lastname": "Jameson"
    },
    "currency": "USD",
    "created_at": "2021-03-03T12:39:19+0000",
    "payout": null,
    "comment": "Awesome!",
    "final": null,
    "commission_name": "standard"
  },
  {
    "id": 4,
    "conversion_sub_amount": 20,
    "amount": 1,
    "commission_type": "level-2",
    "approved": null,
    "kind": "level",
    "affiliate": {
      "id": "sandrasanderson",
      "firstname": "Sandra",
      "lastname": "Sanderson"
    },
    "currency": "USD",
    "created_at": "2021-03-03T12:39:19+0000",
    "payout": null,
    "comment": null,
    "final": null,
    "commission_name": "Level 2"
  }
]

Retrieve meta data

GET/conversions/{conversion_id}/meta-data/
Response:200

URI Parameters

conversion_id
required
number
Example: 1

The id of the conversion.

GET https://api.tapfiliate.com/1.6/conversions/1/meta-data/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/conversions/{conversion_id}/meta-data/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "foo": "bar",
  "tap": "awesome"
}

Update (replace) meta data

PUT/conversions/{conversion_id}/meta-data/
Response:200

URI Parameters

conversion_id
required
number
Example: 1

The id of the conversion.

PUT https://api.tapfiliate.com/1.6/conversions/1/meta-data/

Code Example

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.tapfiliate.com/1.6/conversions/{conversion_id}/meta-data/',
  headers: {'content-type': 'application/json', 'X-Api-Key': 'SOME_STRING_VALUE'},
  body: {key: '<ADD STRING VALUE>'},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Request

{
  "foo": "bar",
  "baz": "qux"
}

Example Response

{
  "foo": "bar",
  "baz": "qux"
}

Retrieve meta data by key

GET/conversions/{conversion_id}/meta-data/{key}/
Response:200

URI Parameters

conversion_id
required
number
Example: 1

The id of the conversion.

key
required
string
Example: foo

The meta data key.

GET https://api.tapfiliate.com/1.6/conversions/1/meta-data/foo/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/conversions/{conversion_id}/meta-data/{key}/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "value": "bar"
}

Set meta data by key

PUT/conversions/{conversion_id}/meta-data/{key}/
Response:200

URI Parameters

conversion_id
required
number
Example: 1

The id of the conversion.

key
required
string
Example: foo

The meta data key.

PUT https://api.tapfiliate.com/1.6/conversions/1/meta-data/foo/

Code Example

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.tapfiliate.com/1.6/conversions/{conversion_id}/meta-data/{key}/',
  headers: {'content-type': 'application/json', 'X-Api-Key': 'SOME_STRING_VALUE'},
  body: {value: '<ADD STRING VALUE>'},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Request

{
  "value": "bar"
}

Example Response

{
  "value": "bar"
}

Delete meta data by key

DELETE/conversions/{conversion_id}/meta-data/{key}/
Response:204

URI Parameters

conversion_id
required
number
Example: 1

The id of the conversion.

key
required
string
Example: foo

The meta data key.

DELETE https://api.tapfiliate.com/1.6/conversions/1/meta-data/foo/

Code Example

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://api.tapfiliate.com/1.6/conversions/{conversion_id}/meta-data/{key}/'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Retrieve a commission

GET/commissions/{commission_id}/
Response:200

URI Parameters

commission_id
required
number
Example: 1

Numeric id of the commission to perform action with.

GET https://api.tapfiliate.com/1.6/commissions/1/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/commissions/{commission_id}/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "id": 1,
  "conversion_sub_amount": 550,
  "amount": 55,
  "commission_type": "standard",
  "approved": true,
  "affiliate": {
    "id": "janejameson",
    "firstname": "Jane",
    "lastname": "Jameson"
  },
  "conversion": {
    "id": 1
  },
  "kind": "regular",
  "currency": "USD",
  "created_at": null,
  "payout": null,
  "comment": null,
  "final": null,
  "finalization_date": null,
  "commission_name": "standard"
}

Update a commission

PATCH/commissions/{commission_id}/
Response:200

URI Parameters

commission_id
required
number
Example: 1

Numeric id of the commission to perform action with.

Arguments

amount
required
number

The new amount for the commission

comment
optional
string

A comment for this commission. The comment will be visible to the affiliate

PATCH https://api.tapfiliate.com/1.6/commissions/1/

Code Example

const request = require('request');

const options = {
  method: 'PATCH',
  url: 'https://api.tapfiliate.com/1.6/commissions/{commission_id}/',
  headers: {'content-type': 'application/json', 'X-Api-Key': 'SOME_STRING_VALUE'},
  body: {amount: 0, comment: '<ADD STRING VALUE>'},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Request

{
  "amount": 30.55,
  "comment": "\"foo bar\""
}

Example Response

{
  "id": 1,
  "amount": 30.55,
  "approved": true,
  "created_at": "2021-03-31T08:21:02+0000",
  "commission_type": "standard",
  "conversion_sub_amount": 550,
  "comment": "Amount adjusted because of returned item",
  "conversion": {
    "id": 1
  },
  "payout": null,
  "affiliate": {
    "id": "janejameson",
    "firstname": "Jane",
    "lastname": "Jameson"
  },
  "kind": "regular",
  "currency": "USD",
  "final": null,
  "finalization_date": null,
  "commission_name": "standard"
}

List all commissions

GET/commissions/{?affiliate_id,status,paid}
Response:200

URI Parameters

affiliate_id
optional
string
Example: janejameson

The affiliate Id

status
optional
string
Example: approved

An optional approval status to filter by. Valid values are: approved | disapproved | pending

paid
optional
bool
Example: 0

Only show commissions that are paid out. Valid values are: 1 | 0

GET https://api.tapfiliate.com/1.6/commissions/?affiliate_id=janejameson&status=approved&paid=0

Example Response

[
  {
    "id": 111,
    "amount": 5,
    "approved": true,
    "created_at": "2021-04-01T04:23:02+0000",
    "commission_type": "sales-bonus",
    "comment": null,
    "conversion": null,
    "payout": null,
    "affiliate": {
      "id": "janejameson",
      "firstname": "Jane",
      "lastname": "Jameson"
    },
    "kind": "bonus",
    "currency": "EUR",
    "final": null,
    "finalization_date": null,
    "commission_name": "Sales bonus"
  },
  {
    "id": 2,
    "amount": 30,
    "approved": true,
    "created_at": "2021-04-01T04:23:02+0000",
    "commission_type": "standard",
    "conversion_sub_amount": 300,
    "comment": null,
    "conversion": {
      "id": 2
    },
    "payout": null,
    "affiliate": {
      "id": "janejameson",
      "firstname": "Jane",
      "lastname": "Jameson"
    },
    "kind": "regular",
    "currency": "EUR",
    "final": null,
    "finalization_date": null,
    "commission_name": "standard"
  },
  {
    "id": 1,
    "amount": 55,
    "approved": true,
    "created_at": "2021-03-31T08:21:02+0000",
    "commission_type": "standard",
    "conversion_sub_amount": 550,
    "comment": null,
    "conversion": {
      "id": 1
    },
    "payout": null,
    "affiliate": {
      "id": "janejameson",
      "firstname": "Jane",
      "lastname": "Jameson"
    },
    "kind": "regular",
    "currency": "USD",
    "final": null,
    "finalization_date": null,
    "commission_name": "standard"
  }
]

Approve or disapprove a commission

Approve a commission

PUT/commissions/{commission_id}/approved/
Response:200

URI Parameters

commission_id
required
number
Example: 1

Numeric id of the commission to perform action with.

PUT https://api.tapfiliate.com/1.6/commissions/1/approved/

Code Example

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.tapfiliate.com/1.6/commissions/{commission_id}/approved/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "id": 1,
  "conversion_sub_amount": 550,
  "amount": 55,
  "commission_type": "standard",
  "approved": true,
  "affiliate": {
    "id": "janejameson",
    "firstname": "Jane",
    "lastname": "Jameson"
  },
  "conversion": {
    "id": 1
  },
  "kind": "regular",
  "currency": "USD",
  "created_at": null,
  "payout": null,
  "comment": null,
  "final": null,
  "finalization_date": null,
  "commission_name": "standard"
}

Disapprove a commission

DELETE/commissions/{commission_id}/approved/
Response:200

URI Parameters

commission_id
required
number
Example: 1

Numeric id of the commission to perform action with.

DELETE https://api.tapfiliate.com/1.6/commissions/1/approved/

Code Example

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://api.tapfiliate.com/1.6/commissions/{commission_id}/approved/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "id": 1,
  "conversion_sub_amount": 550,
  "amount": 55,
  "commission_type": "standard",
  "approved": false,
  "affiliate": {
    "id": "janejameson",
    "firstname": "Jane",
    "lastname": "Jameson"
  },
  "conversion": {
    "id": 1
  },
  "kind": "regular",
  "currency": "USD",
  "created_at": null,
  "payout": null,
  "comment": null,
  "final": null,
  "finalization_date": null,
  "commission_name": "standard"
}

Retrieve an affiliate

GET/affiliates/{affiliate_id}/
Response:200

URI Parameters

affiliate_id
required
string
Example: janejameson

The id of the affiliate.

GET https://api.tapfiliate.com/1.6/affiliates/janejameson/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/affiliates/{affiliate_id}/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "id": "janejameson",
  "firstname": "Jane",
  "lastname": "Jameson",
  "email": "jane@example-blog.inc",
  "company": {
    "name": "Example blog Inc.",
    "description": "Best blog ever"
  },
  "address": {
    "address": "Rapenburgerstraat 173",
    "address_two": null,
    "postal_code": "1011 VM",
    "city": "Amsterdam",
    "state": "Noord-Holland",
    "country": {
      "code": "NL",
      "name": "Netherlands"
    }
  },
  "meta_data": {
    "foo": "bar",
    "meta": "data"
  },
  "parent_id": "sandrasanderson",
  "affiliate_group_id": null,
  "created_at": "2021-03-03T12:39:19+0000",
  "promoted_at": null,
  "promotion_method": null,
  "custom_fields": {
    "field1": "value1"
  }
}

Delete an affiliate

DELETE/affiliates/{affiliate_id}/
Response:204

URI Parameters

affiliate_id
required
string
Example: janejameson

The id of the affiliate.

DELETE https://api.tapfiliate.com/1.6/affiliates/janejameson/

Code Example

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://api.tapfiliate.com/1.6/affiliates/{affiliate_id}/'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

List all affiliates

GET/affiliates/{?click_id,source_id,email,referral_code,parent_id,affiliate_group_id}
Response:200

URI Parameters

click_id
optional
string
Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

A click id

source_id
optional
string
Example: 1-ssssss

A source id

email
optional
string
Example: jane@example-blog.inc

An email address

referral_code
optional
string
Example: nwjinmy

An affiliate’s referral code. This corresponds to the value of ref= in their referral link.

parent_id
optional
string
Example: sandrasanderson

Retrieves children for a certain parent affiliate

affiliate_group_id
optional
string
Example: ag_eXampl3

Retrieves affiliates for a certain affiliate group

GET https://api.tapfiliate.com/1.6/affiliates/?click_id=aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee&source_id=1-ssssss&email=jane@example-blog.inc&referral_code=nwjinmy&parent_id=sandrasanderson&affiliate_group_id=ag_eXampl3

Example Response

[
  {
    "id": "janejameson",
    "firstname": "Jane",
    "lastname": "Jameson",
    "email": "jane@example-blog.inc",
    "company": {
      "name": "Example blog Inc.",
      "description": "Best blog ever"
    },
    "address": {
      "address": "Rapenburgerstraat 173",
      "address_two": null,
      "postal_code": "1011 VM",
      "city": "Amsterdam",
      "state": "Noord-Holland",
      "country": {
        "code": "NL",
        "name": "Netherlands"
      }
    },
    "meta_data": {
      "foo": "bar",
      "meta": "data"
    },
    "parent_id": "sandrasanderson",
    "created_at": null,
    "affiliate_group_id": null,
    "promoted_at": null,
    "promotion_method": null,
    "custom_fields": {
      "field1": "value1"
    }
  }
]

Create an affiliate

POST/affiliates/
Response:200

Arguments

firstname
required
string

The affiliate’s firstname

lastname
required
string

The affiliate’s lastname

email
optional
string

blog.inc (string, required) - The affiliate’s email

password
optional
string

The password for the new account. If no password is given, one is generated and passed in the response

company
optional
object

The affiliate’s company data

Child Arguments

name
optional
string

The company’s name

address
optional
object

The affiliate’s address

Child Arguments

address
required
string

The company’s address

postal_code
required
string

The company’s postal code

city
required
string

The company’s city

state
optional
string

Holland (string, optional) - The company’s state

country
required
object

The company’s contry data

Child Arguments

code
required
string

The country’s ISO_3166-1 code (https://en.wikipedia.org/wiki/ISO_3166-1)

custom_fields
optional
object

Custom fields

Child Arguments

POST https://api.tapfiliate.com/1.6/affiliates/

Code Example

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://api.tapfiliate.com/1.6/affiliates/',
  headers: {'X-Api-Key': 'SOME_STRING_VALUE'},
  body: {
    firstname: '<ADD STRING VALUE>',
    lastname: '<ADD STRING VALUE>',
    email: '<ADD STRING VALUE>',
    password: '<ADD STRING VALUE>',
    company: {name: '<ADD STRING VALUE>'},
    address: {
      address: '<ADD STRING VALUE>',
      postal_code: '<ADD STRING VALUE>',
      city: '<ADD STRING VALUE>',
      state: '<ADD STRING VALUE>',
      country: {code: '<ADD STRING VALUE>'}
    },
    custom_fields: {}
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Request

{
  "firstname": "Ramone",
  "lastname": "Referra",
  "email": "ramona@referra.com",
  "password": "password1234",
  "company": {
    "name": "Referra Inc.",
    "description": "Best referrer ever"
  },
  "address": {
    "address": "Rapenburgerstraat 173",
    "address_two": null,
    "postal_code": "1011 VM",
    "city": "Amsterdam",
    "state": "Noord-Holland",
    "country": {
      "code": "NL"
    }
  },
  "custom_fields": {
    "field1": "value1"
  }
}

Example Response

{
  "id": "ramonereferra",
  "firstname": "Ramone",
  "lastname": "Referra",
  "email": "ramona@referra.com",
  "password": null,
  "company": {
    "name": "Referra Inc.",
    "description": "Best referrer ever"
  },
  "address": {
    "address": "Rapenburgerstraat 173",
    "address_two": null,
    "postal_code": "1011 VM",
    "city": "Amsterdam",
    "state": "Noord-Holland",
    "country": {
      "code": "NL",
      "name": "Netherlands"
    }
  },
  "meta_data": {},
  "parent_id": null,
  "affiliate_group_id": null,
  "created_at": "2021-03-03T12:39:19+0000",
  "promoted_at": null,
  "promotion_method": null,
  "custom_fields": {
    "field1": "value1"
  }
}

Set affiliate group

PUT/affiliates/{affiliate_id}/group/
Response:200

URI Parameters

affiliate_id
required
string
Example: janejameson

The id of the affiliate.

PUT https://api.tapfiliate.com/1.6/affiliates/janejameson/group/

Code Example

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.tapfiliate.com/1.6/affiliates/{affiliate_id}/group/',
  headers: {'X-Api-Key': 'SOME_STRING_VALUE'},
  body: {group_id: '<ADD STRING VALUE>'},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Request

{
  "group_id": "ag_eXampl3"
}

Example Response

{
  "id": "janejameson",
  "firstname": "Jane",
  "lastname": "Jameson",
  "email": "jane@example-blog.inc",
  "company": {
    "name": "Example blog Inc.",
    "description": "Best blog ever"
  },
  "address": {
    "address": "Rapenburgerstraat 173",
    "address_two": null,
    "postal_code": "1011 VM",
    "city": "Amsterdam",
    "state": "Noord-Holland",
    "country": {
      "code": "NL",
      "name": "Netherlands"
    }
  },
  "meta_data": {
    "foo": "bar",
    "meta": "data"
  },
  "parent_id": "sandrasanderson",
  "affiliate_group_id": "ag_eXampl3",
  "created_at": "2021-03-03T12:39:19+0000",
  "promoted_at": null,
  "promotion_method": null,
  "custom_fields": {
    "field1": "value1"
  }
}

Remove affiliate group

DELETE/affiliates/{affiliate_id}/group/
Response:204

URI Parameters

affiliate_id
required
string
Example: janejameson

The id of the affiliate.

DELETE https://api.tapfiliate.com/1.6/affiliates/janejameson/group/

Code Example

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://api.tapfiliate.com/1.6/affiliates/{affiliate_id}/group/'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Update note

PUT/affiliates/{affiliate_id}/notes/{id}/
Response:200

URI Parameters

affiliate_id
required
string
Example: janejameson

The id of the affiliate.

id
required
int
Example: 1

The id of the note.

PUT https://api.tapfiliate.com/1.6/affiliates/janejameson/notes/1/

Code Example

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.tapfiliate.com/1.6/affiliates/{affiliate_id}/notes/{id}/',
  headers: {'content-type': 'application/json', 'X-Api-Key': 'SOME_STRING_VALUE'},
  body: {message: '<ADD STRING VALUE>'},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Request

{
  "message": "Greatest person ever!"
}

Example Response

{
  "id": 1,
  "created_at": "2021-09-12T13:34:18+0000",
  "message": "Greatest person ever!",
  "created_by": {
    "id": "johntapper",
    "firstname": "John",
    "lastname": "Tapper"
  }
}

Delete note

DELETE/affiliates/{affiliate_id}/notes/{id}/
Response:204

URI Parameters

affiliate_id
required
string
Example: janejameson

The id of the affiliate.

id
required
int
Example: 1

The id of the note.

DELETE https://api.tapfiliate.com/1.6/affiliates/janejameson/notes/1/

Code Example

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://api.tapfiliate.com/1.6/affiliates/{affiliate_id}/notes/{id}/'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

List notes

GET/affiliates/{affiliate_id}/notes/
Response:200

URI Parameters

affiliate_id
required
string
Example: janejameson

The id of the affiliate.

GET https://api.tapfiliate.com/1.6/affiliates/janejameson/notes/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/affiliates/{affiliate_id}/notes/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

[
  {
    "id": 1,
    "created_at": "2021-09-12T13:34:18+0000",
    "message": "Great person!",
    "created_by": {
      "id": "johntapper",
      "firstname": "John",
      "lastname": "Tapper"
    }
  }
]

Create note

POST/affiliates/{affiliate_id}/notes/
Response:200

URI Parameters

affiliate_id
required
string
Example: janejameson

The id of the affiliate.

POST https://api.tapfiliate.com/1.6/affiliates/janejameson/notes/

Code Example

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://api.tapfiliate.com/1.6/affiliates/{affiliate_id}/notes/',
  headers: {'content-type': 'application/json', 'X-Api-Key': 'SOME_STRING_VALUE'},
  body: {message: '<ADD STRING VALUE>'},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Request

{
  "message": "Great person!"
}

Example Response

{
  "id": 1,
  "created_at": "2021-09-12T13:34:18+0000",
  "message": "Great person!",
  "created_by": {
    "id": "johntapper",
    "firstname": "John",
    "lastname": "Tapper"
  }
}

Retrieve meta data

GET/affiliates/{affiliate_id}/meta-data/
Response:200

URI Parameters

affiliate_id
required
string
Example: janejameson

The id of the affiliate.

GET https://api.tapfiliate.com/1.6/affiliates/janejameson/meta-data/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/affiliates/{affiliate_id}/meta-data/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "foo": "bar",
  "meta": "data"
}

Update (replace) meta data

PUT/affiliates/{affiliate_id}/meta-data/
Response:200

URI Parameters

affiliate_id
required
string
Example: janejameson

The id of the affiliate.

PUT https://api.tapfiliate.com/1.6/affiliates/janejameson/meta-data/

Code Example

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.tapfiliate.com/1.6/affiliates/{affiliate_id}/meta-data/',
  headers: {'content-type': 'application/json', 'X-Api-Key': 'SOME_STRING_VALUE'},
  body: {key: '<ADD STRING VALUE>'},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Request

{
  "foo": "bar",
  "baz": "qux"
}

Example Response

{
  "foo": "bar",
  "baz": "qux"
}

Retrieve meta data by key

GET/affiliates/{affiliate_id}/meta-data/{key}/
Response:200

URI Parameters

affiliate_id
required
string
Example: janejameson

The id of the affiliate.

key
required
string
Example: foo

The meta data key.

GET https://api.tapfiliate.com/1.6/affiliates/janejameson/meta-data/foo/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/affiliates/{affiliate_id}/meta-data/{key}/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "value": "bar"
}

Set meta data by key

PUT/affiliates/{affiliate_id}/meta-data/{key}/
Response:200

URI Parameters

affiliate_id
required
string
Example: janejameson

The id of the affiliate.

key
required
string
Example: foo

The meta data key.

PUT https://api.tapfiliate.com/1.6/affiliates/janejameson/meta-data/foo/

Code Example

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.tapfiliate.com/1.6/affiliates/{affiliate_id}/meta-data/{key}/',
  headers: {'content-type': 'application/json', 'X-Api-Key': 'SOME_STRING_VALUE'},
  body: {value: '<ADD STRING VALUE>'},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Request

{
  "value": "My value"
}

Example Response

{
  "value": "My value"
}

Delete meta data by key

DELETE/affiliates/{affiliate_id}/meta-data/{key}/
Response:204

URI Parameters

affiliate_id
required
string
Example: janejameson

The id of the affiliate.

key
required
string
Example: foo

The meta data key.

DELETE https://api.tapfiliate.com/1.6/affiliates/janejameson/meta-data/foo/

Code Example

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://api.tapfiliate.com/1.6/affiliates/{affiliate_id}/meta-data/{key}/'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Get payout method

GET/affiliates/{affiliate_id}/payout-methods/{payout_method_id}/
Response:200

URI Parameters

affiliate_id
required
string
Example: janejameson

The id of the affiliate

payout_method_id
required
string
Example: paypal

The id of the payout method

GET https://api.tapfiliate.com/1.6/affiliates/janejameson/payout-methods/paypal/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/affiliates/{affiliate_id}/payout-methods/{payout_method_id}/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "title": "Paypal",
  "id": "paypal",
  "details": {
    "paypal_address": "jane@example-blog.inc"
  },
  "primary": true
}

Set payout method

PUT/affiliates/{affiliate_id}/payout-methods/{payout_method_id}/
Response:200

The body of the request should contain the appropriate data for the payout method you are setting. The field ids can be found by exporting payouts as .csv on the payouts page.

URI Parameters

affiliate_id
required
string
Example: janejameson

The id of the affiliate

payout_method_id
required
string
Example: paypal

The id of the payout method

PUT https://api.tapfiliate.com/1.6/affiliates/janejameson/payout-methods/paypal/

Code Example

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.tapfiliate.com/1.6/affiliates/{affiliate_id}/payout-methods/{payout_method_id}/',
  headers: {'content-type': 'application/json', 'X-Api-Key': 'SOME_STRING_VALUE'},
  body: {paypal_address: '<ADD STRING VALUE>'},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Request

{
  "paypal_address": "jane@example-blog.inc"
}

Example Response

{
  "title": "Paypal",
  "id": "paypal",
  "details": {
    "paypal_address": "jane@example-blog.inc"
  },
  "primary": true
}

List payout methods

GET/affiliates/{affiliate_id}/payout-methods/
Response:200

URI Parameters

affiliate_id
required
string
Example: janejameson

The id of the affiliate

GET https://api.tapfiliate.com/1.6/affiliates/janejameson/payout-methods/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/affiliates/{affiliate_id}/payout-methods/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

[
  {
    "title": "Paypal",
    "id": "paypal",
    "details": {
      "paypal_address": "jane@example-blog.inc"
    },
    "primary": true
  }
]

Set parent

POST/affiliates/{child_affiliate_id}/parent/
Response:200

URI Parameters

child_affiliate_id
required
string
Example: janejameson

The id of the affiliate whoms parent is being set.

Arguments

affiliate_id
optional
string

The letter id of the parent affiliate

Arguments

via
optional
string

The numeral id of the parent affiliate

POST https://api.tapfiliate.com/1.6/affiliates/janejameson/parent/

Code Example

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://api.tapfiliate.com/1.6/affiliates/{child_affiliate_id}/parent/',
  headers: {'content-type': 'application/json', 'X-Api-Key': 'SOME_STRING_VALUE'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Request

{
  "affiliate_id": "sandrasanderson"
}

Example Response

{
  "id": "janejameson",
  "firstname": "Jane",
  "lastname": "Jameson",
  "email": "jane@example-blog.inc",
  "company": {
    "name": "Example blog Inc.",
    "description": "Best blog ever"
  },
  "address": {
    "address": "Rapenburgerstraat 173",
    "address_two": null,
    "postal_code": "1011 VM",
    "city": "Amsterdam",
    "state": "Noord-Holland",
    "country": {
      "code": "NL",
      "name": "Netherlands"
    }
  },
  "meta_data": {
    "foo": "bar",
    "meta": "data"
  },
  "parent_id": "sandrasanderson",
  "created_at": "2021-03-03T12:39:19+0100",
  "affiliate_group_id": null,
  "promoted_at": null,
  "promotion_method": null,
  "custom_fields": {
    "field1": "value1"
  }
}

Example Request

{
  "via": "3"
}

Example Response

{
  "id": "janejameson",
  "firstname": "Jane",
  "lastname": "Jameson",
  "email": "jane@example-blog.inc",
  "company": {
    "name": "Example blog Inc.",
    "description": "Best blog ever"
  },
  "address": {
    "address": "Rapenburgerstraat 173",
    "address_two": null,
    "postal_code": "1011 VM",
    "city": "Amsterdam",
    "state": "Noord-Holland",
    "country": {
      "code": "NL",
      "name": "Netherlands"
    }
  },
  "meta_data": {
    "foo": "bar",
    "meta": "data"
  },
  "parent_id": "sandrasanderson",
  "created_at": "2021-03-03T12:39:19+0100",
  "affiliate_group_id": null,
  "promoted_at": null,
  "promotion_method": null,
  "custom_fields": {
    "field1": "value1"
  }
}

Remove parent

DELETE/affiliates/{child_affiliate_id}/parent/
Response:204

URI Parameters

child_affiliate_id
required
string
Example: janejameson

The id of the affiliate whoms parent is being set.

DELETE https://api.tapfiliate.com/1.6/affiliates/janejameson/parent/

Code Example

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://api.tapfiliate.com/1.6/affiliates/{child_affiliate_id}/parent/'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

The following section describes the endpoints for our new Payments system, rolled out early 2019. You can check which version of our payments system you’re on, by looking at the name of the menu item when logged in to the platform. The current system is called “Payments”, and the legacy system is called “Payouts”.

Retrieve affiliate's balances

GET/affiliates/{affiliate_id}/balances/
Response:200

URI Parameters

affiliate_id
required
string
Example: janejameson

The id of the affiliate whoms balances to retrieve.

GET https://api.tapfiliate.com/1.6/affiliates/janejameson/balances/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/affiliates/{affiliate_id}/balances/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "USD": 5,
  "EUR": 35
}

The following section describes the endpoints for our new Payments system, rolled out early 2019. You can check which version of our payments system you’re on, by looking at the name of the menu item when logged in to the platform. The current system is called “Payments”, and the legacy system is called “Payouts”.

List affiliate's payments

GET/affiliates/{affiliate_id}/payments/
Response:200

URI Parameters

affiliate_id
required
string
Example: janejameson

The id of the affiliate whoms payments to list.

GET https://api.tapfiliate.com/1.6/affiliates/janejameson/payments/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/affiliates/{affiliate_id}/payments/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

[
  {
    "id": "pa_eXampl3",
    "created_at": "2021-03-29T08:36:07+00:00",
    "affiliate": {
      "id": "janejameson",
      "firstname": "Jane",
      "lastname": "Jameson"
    },
    "amount": 50,
    "currency": "USD"
  }
]

Get affiliations

GET/affiliates/{id}/programs/
Response:200

URI Parameters

id
required
string
Example: u_JaN3-J0n

The id of the affiliate.

GET https://api.tapfiliate.com/1.6/affiliates/u_JaN3-J0n/programs/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/affiliates/{id}/programs/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

[
  {
    "applied_at": "2021-07-06T12:25:21+00:00",
    "approved": true,
    "coupon": "JANE10OFF",
    "id": "johns-affiliate-program",
    "referral_link": {
      "asset_id": "1-aaaaaa",
      "link": "https://tapper.inc/johns-cool-product/?ref=nwjinmy",
      "source_id": "1-ssssss"
    },
    "title": "John's affiliate program",
    "assets_amount": 2
  }
]

Get custom fields

GET/affiliates/custom-fields/
Response:200
GET https://api.tapfiliate.com/1.6/affiliates/custom-fields/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/affiliates/custom-fields/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

[
  {
    "id": "field1",
    "title": "field1",
    "choices": []
  }
]

List all affiliate groups

GET/affiliate-groups/
Response:200
GET https://api.tapfiliate.com/1.6/affiliate-groups/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/affiliate-groups/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

[
  {
    "id": "ag_eXampl3",
    "title": "Gold affiliates",
    "affiliate_count": 0
  }
]

Create new affiliate group

POST/affiliate-groups/
Response:200
POST https://api.tapfiliate.com/1.6/affiliate-groups/

Code Example

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://api.tapfiliate.com/1.6/affiliate-groups/',
  headers: {'Api-Key': 'SOME_STRING_VALUE'},
  body: {title: '<ADD STRING VALUE>'},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Request

{
  "title": "Silver Affiliates"
}

Example Response

{
  "id": "ag_nK6qZzk0JgnXJFsHQ-",
  "title": "Silver Affiliates",
  "affiliate_count": 0
}

Update affiliate group

PATCH/affiliate-groups/{affiliate_group_id}/
Response:200

URI Parameters

affiliate_group_id
optional
string
Example: ag_eXampl3

Retrieves affiliates for a certain affiliate group

PATCH https://api.tapfiliate.com/1.6/affiliate-groups/ag_eXampl3/

Code Example

const request = require('request');

const options = {
  method: 'PATCH',
  url: 'https://api.tapfiliate.com/1.6/affiliate-groups/{affiliate_group_id}/',
  headers: {'Api-Key': 'SOME_STRING_VALUE'},
  body: {title: '<ADD STRING VALUE>'},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Request

{
  "title": "Gold members"
}

Example Response

{
  "id": "ag_eXampl3",
  "title": "Gold members",
  "affiliate_count": 0
}

List all affiliate prospects

GET/affiliate-prospects/{?email,referral_code,program_id,group_id}
Response:200

URI Parameters

email
optional
string
Example: peter@example-existing-customer.inc

An email address

referral_code
optional
string
Example: yza5njg

An affiliate prospect’s referral code. This corresponds to the value of ref= in their referral link.

program_id
optional
string
Example: johns-affiliate-program

Retrieves affiliate prospects for a certain program

group_id
optional
string

Retrieves affiliate prospects for a certain affiliate group

GET https://api.tapfiliate.com/1.6/affiliate-prospects/?email=peter@example-existing-customer.inc&referral_code=yza5njg&program_id=johns-affiliate-program&group_id=

Example Response

[
  {
    "id": "peterpeterson",
    "firstname": "Peter",
    "lastname": "Peterson",
    "email": "peter@example-existing-customer.inc",
    "company": {
      "name": "Example prospect Inc.",
      "description": "Great affiliate prospect"
    },
    "address": {
      "address": "1 Holywood Drive",
      "address_two": null,
      "postal_code": "90210",
      "city": "Los Angeles",
      "state": "CA",
      "country": {
        "code": "US",
        "name": "United States"
      }
    },
    "signup_source": "stripe-integration",
    "referral_link": {
      "link": "https://tapper.inc/johns-cool-product/?ref=yza5njg",
      "asset_id": "1-aaaaaa",
      "source_id": "3-rrrrrr"
    },
    "created_at": "2021-05-27T11:39:03+00:00",
    "promoted_at": null,
    "promotion_method": null
  }
]

Create an affiliate prospect

POST/affiliate-prospects/
Response:200

Arguments

firstname
required
string

The affiliate prospect’s firstname

lastname
required
string

The affiliate prospect’s lastname

email
optional
string

blog.inc (string, required) - The affiliate’s email

company
optional
object

The affiliate prospect’s company data

Child Arguments

name
optional
string

The company’s name

address
optional
object

The affiliate prospect’s address

Child Arguments

address
required
string

The company’s address

postal_code
required
string

The company’s postal code

city
required
string

The company’s city

state
optional
string

Holland (string, optional) - The company’s state

country
required
object

The company’s contry data

Child Arguments

code
required
string

The country’s ISO_3166-1 code (https://en.wikipedia.org/wiki/ISO_3166-1)

program_id
optional
string

affiliate-program (string, optional) - The program to add the affiliate prospect to. If none is passed, the affiliate prospect will be added to the default program

affiliate_group_id
optional
string

The affiliate group to add the affiliate prospect to

POST https://api.tapfiliate.com/1.6/affiliate-prospects/

Code Example

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://api.tapfiliate.com/1.6/affiliate-prospects/',
  headers: {'X-Api-Key': 'SOME_STRING_VALUE'},
  body: {
    firstname: '<ADD STRING VALUE>',
    lastname: '<ADD STRING VALUE>',
    email: '<ADD STRING VALUE>',
    company: {name: '<ADD STRING VALUE>'},
    address: {
      address: '<ADD STRING VALUE>',
      postal_code: '<ADD STRING VALUE>',
      city: '<ADD STRING VALUE>',
      state: '<ADD STRING VALUE>',
      country: {code: '<ADD STRING VALUE>'}
    },
    program_id: '<ADD STRING VALUE>',
    affiliate_group_id: '<ADD STRING VALUE>'
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Request

{
  "firstname": "Peter",
  "lastname": "Prospect",
  "email": "jane@example",
  "company": {
    "name": "Tapfiliate"
  },
  "address": {
    "address": "Rapenburgerstraat 173",
    "postal_code": "1011VM",
    "city": "Amsterdam",
    "state": "Noord",
    "country": {
      "code": "NL"
    }
  },
  "program_id": "johns",
  "affiliate_group_id": "ag_1234"
}

Example Response

{
  "id": "jimprosper",
  "firstname": "Jim",
  "lastname": "Prosper",
  "email": "jim@prosper.inc",
  "company": {
    "name": "Prosper Inc.",
    "description": "Live long and.."
  },
  "address": {
    "address": "41153.7 Star avenue",
    "address_two": null,
    "postal_code": "1011 VM",
    "city": "Nebula 5",
    "state": "Milky Way",
    "country": {
      "code": "US",
      "name": "United States"
    }
  },
  "referral_link": {
    "link": "https://tapper.inc/johns-cool-product/?ref=zme1nmu",
    "asset_id": "1-aaaaaa",
    "source_id": "3-rrrrrr"
  },
  "created_at": "2021-05-27T11:39:03+00:00",
  "promoted_at": null,
  "promotion_method": null,
  "signup_source": "by-advertiser-api"
}

Retrieve an affiliate prospect

GET/affiliate-prospects/{affiliate_prospect_id}/
Response:200

URI Parameters

affiliate_prospect_id
required
string
Example: peterpeterson

The id of the affiliate prospect.

GET https://api.tapfiliate.com/1.6/affiliate-prospects/peterpeterson/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/affiliate-prospects/{affiliate_prospect_id}/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "id": "peterpeterson",
  "firstname": "Peter",
  "lastname": "Peterson",
  "email": "peter@example-existing-customer.inc",
  "company": {
    "name": "Example prospect Inc.",
    "description": "Great affiliate prospect"
  },
  "address": {
    "address": "1 Holywood Drive",
    "address_two": null,
    "postal_code": "90210",
    "city": "Los Angeles",
    "state": "CA",
    "country": {
      "code": "US",
      "name": "United States"
    }
  },
  "signup_source": "stripe-integration",
  "referral_link": {
    "link": "https://tapper.inc/johns-cool-product/?ref=yza5njg",
    "asset_id": "1-aaaaaa",
    "source_id": "3-rrrrrr"
  },
  "created_at": "2021-05-27T11:39:03+00:00",
  "promoted_at": null,
  "promotion_method": null
}

Delete an affiliate prospect

DELETE/affiliate-prospects/{affiliate_prospect_id}/
Response:204

URI Parameters

affiliate_prospect_id
required
string
Example: peterpeterson

The id of the affiliate prospect.

DELETE https://api.tapfiliate.com/1.6/affiliate-prospects/peterpeterson/

Code Example

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://api.tapfiliate.com/1.6/affiliate-prospects/{affiliate_prospect_id}/'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Retrieve a Program

GET/programs/{program_id}/
Response:200

URI Parameters

program_id
required
string
Example: johns-affiliate-program

The id of the Program. This id can be found as part of the url when viewing the program on the platform.

GET https://api.tapfiliate.com/1.6/programs/johns-affiliate-program/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/programs/{program_id}/'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "id": "johns-affiliate-program",
  "currency": "USD",
  "title": "John's affiliate program",
  "cookie_time": 45,
  "default_landing_page_url": "https://tapper.inc/johns-cool-product/",
  "recurring": true,
  "recurring_cap": null,
  "recurring_period_days": null,
  "program_category": {
    "id": 1,
    "identifier": "admitad_test",
    "title": "Parent category",
    "is_admitad_suitable": false
  },
  "currency_symbol": "$"
}

List all programs

GET/programs/{?asset_id}
Response:200

URI Parameters

asset_id
optional
string
Example: 1-aaaaaa

An asset id

GET https://api.tapfiliate.com/1.6/programs/?asset_id=1-aaaaaa

Example Response

[
  {
    "id": "johns-affiliate-program",
    "currency": "USD",
    "title": "John's affiliate program",
    "cookie_time": 45,
    "default_landing_page_url": "https://tapper.inc/johns-cool-product/",
    "recurring": true,
    "recurring_cap": null,
    "recurring_period_days": null,
    "program_category": {
      "id": 1,
      "identifier": "admitad_test",
      "title": "Parent category",
      "is_admitad_suitable": false
    },
    "currency_symbol": "$"
  }
]

List all affiliates in program

GET/programs/{program_id}/affiliates/{?source_id,email,parent_id,affiliate_group_id}
Response:200

URI Parameters

program_id
required
string
Example: johns-affiliate-program

The id of the Program to add the affiliate too. This id can be found as part of the url when viewing the program on the platform.

source_id
optional
string
Example: 1-ssssss

A source id

email
optional
string
Example: jane@example-blog.inc

An email address

parent_id
optional
string
Example: sandrasanderson

Retrieves children for a certain parent affiliate

affiliate_group_id
optional
string
Example: ag_eXampl3

Retrieves affiliates for a certain affiliate group

GET https://api.tapfiliate.com/1.6/programs/johns-affiliate-program/affiliates/?source_id=1-ssssss&email=jane@example-blog.inc&parent_id=sandrasanderson&affiliate_group_id=ag_eXampl3

Example Response

[
  {
    "id": "janejameson",
    "firstname": "Jane",
    "lastname": "Jameson",
    "email": "jane@example-blog.inc",
    "company": {
      "name": "Example blog Inc.",
      "description": "Best blog ever"
    },
    "address": {
      "address": "Rapenburgerstraat 173",
      "address_two": null,
      "postal_code": "1011 VM",
      "city": "Amsterdam",
      "state": "Noord-Holland",
      "country": {
        "code": "NL",
        "name": "Netherlands"
      }
    },
    "meta_data": {
      "foo": "bar",
      "meta": "data"
    },
    "parent_id": "sandrasanderson",
    "referral_link": {
      "link": "https://tapper.inc/johns-cool-product/?ref=nwjinmy",
      "asset_id": "1-aaaaaa",
      "source_id": "1-ssssss"
    },
    "coupon": "JANE10OFF",
    "approved": true,
    "affiliate_group_id": null,
    "created_at": null,
    "applied_at": "2021-05-27T11:39:03+00:00",
    "promoted_at": null,
    "promotion_method": null,
    "custom_fields": {
      "field1": "value1"
    }
  }
]

Add an affiliate to a program

POST/programs/{program_id}/affiliates/
Response:200

URI Parameters

program_id
required
string
Example: johns-affiliate-program

The id of the Program to add the affiliate too. This id can be found as part of the url when viewing the program on the platform.

Arguments

affiliate
required
object

Child Arguments

id
required
string

The id of the affiliate

approved
optional
boolean,null

An optional approval status. Valid values are: true (Approved, default) | false (Disapproved) | null (Pending)

coupon
optional
string

An optional coupon for this affiliate

POST https://api.tapfiliate.com/1.6/programs/johns-affiliate-program/affiliates/

Code Example

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://api.tapfiliate.com/1.6/programs/{program_id}/affiliates/',
  headers: {'content-type': 'application/json', 'X-Api-Key': 'SOME_STRING_VALUE'},
  body: {affiliate: {id: '<ADD STRING VALUE>'}, coupon: '<ADD STRING VALUE>'},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Request

{
  "affiliate": {
    "id": "billmurray"
  },
  "approved": true,
  "coupon": "JANE10OFF"
}

Example Response

{
  "id": "sandrasanderson",
  "firstname": "Mike",
  "lastname": "Mikerson",
  "email": "mike@example-parent.inc",
  "company": null,
  "address": null,
  "meta_data": {},
  "parent_id": null,
  "referral_link": {
    "link": "https://tapper.inc/johns-cool-product/?ref=ztdkzgf",
    "asset_id": "1-aaaaaa",
    "source_id": null
  },
  "coupon": "MIKEFREESHIPPING",
  "approved": null,
  "created_at": null,
  "affiliate_group_id": null,
  "applied_at": "2021-05-27T11:30:38+00:00",
  "promoted_at": null,
  "promotion_method": null,
  "custom_fields": null
}

Retrieve an affiliate and their (program specific) details.

Note: Before V1.6, this endpoint would only return data for approved affiliates.

Retrieve an affiliate in a program

GET/programs/{program_id}/affiliates/{affiliate_id}/
Response:200

URI Parameters

program_id
required
string
Example: johns-affiliate-program

The id of the Program.

affiliate_id
required
string
Example: janejameson

The id of the affiliate.

GET https://api.tapfiliate.com/1.6/programs/johns-affiliate-program/affiliates/janejameson/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/programs/{program_id}/affiliates/{affiliate_id}/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "id": "janejameson",
  "firstname": "Jane",
  "lastname": "Jameson",
  "email": "jane@example-blog.inc",
  "company": {
    "name": "Example blog Inc.",
    "description": "Best blog ever"
  },
  "address": {
    "address": "Rapenburgerstraat 173",
    "address_two": null,
    "postal_code": "1011 VM",
    "city": "Amsterdam",
    "state": "Noord-Holland",
    "country": {
      "code": "NL",
      "name": "Netherlands"
    }
  },
  "meta_data": {
    "foo": "bar",
    "meta": "data"
  },
  "parent_id": "sandrasanderson",
  "referral_link": {
    "link": "https://tapper.inc/johns-cool-product/?ref=nwjinmy",
    "asset_id": "1-aaaaaa",
    "source_id": "1-ssssss"
  },
  "coupon": "JANE10OFF",
  "approved": true,
  "affiliate_group_id": null,
  "created_at": "2021-05-27T11:39:03+00:00",
  "applied_at": "2021-05-27T11:39:03+00:00",
  "promoted_at": null,
  "promotion_method": null,
  "custom_fields": {
    "field1": "value1"
  }
}

Update an affiliate in a program

PATCH/programs/{program_id}/affiliates/{affiliate_id}/
Response:200

URI Parameters

program_id
required
string
Example: johns-affiliate-program

The id of the Program.

affiliate_id
required
string
Example: janejameson

The id of the affiliate.

Arguments

coupon
required
string

The affiliate’s coupon code for this program

PATCH https://api.tapfiliate.com/1.6/programs/johns-affiliate-program/affiliates/janejameson/

Code Example

const request = require('request');

const options = {
  method: 'PATCH',
  url: 'https://api.tapfiliate.com/1.6/programs/{program_id}/affiliates/{affiliate_id}/',
  headers: {'content-type': 'application/json', 'X-Api-Key': 'SOME_STRING_VALUE'},
  body: {coupon: '<ADD STRING VALUE>'},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Request

{
  "coupon": "JANE20OFF"
}

Example Response

{
  "id": "janejameson",
  "firstname": "Jane",
  "lastname": "Jameson",
  "email": "jane@example-blog.inc",
  "company": {
    "name": "Example blog Inc.",
    "description": "Best blog ever"
  },
  "address": {
    "address": "Rapenburgerstraat 173",
    "address_two": null,
    "postal_code": "1011 VM",
    "city": "Amsterdam",
    "state": "Noord-Holland",
    "country": {
      "code": "NL",
      "name": "Netherlands"
    }
  },
  "meta_data": {
    "foo": "bar",
    "meta": "data"
  },
  "parent_id": "sandrasanderson",
  "referral_link": {
    "link": "https://tapper.inc/johns-cool-product/?ref=nwjinmy",
    "asset_id": "1-aaaaaa",
    "source_id": "1-ssssss"
  },
  "coupon": "JANE20OFF",
  "approved": true,
  "affiliate_group_id": null,
  "created_at": "2021-05-27T11:39:03+00:00",
  "applied_at": "2021-05-27T11:39:03+00:00",
  "promoted_at": null,
  "promotion_method": null,
  "custom_fields": {
    "field1": "value1"
  }
}

Approve an affiliate

PUT/programs/{program_id}/affiliates/{affiliate_id}/approved/
Response:200

URI Parameters

program_id
required
string
Example: johns-affiliate-program

The id of the program to add the affiliate too. This id can be found as part of the url when viewing the program on the platform.

affiliate_id
required
string
Example: janejameson

The id of the affiliate to approve.

PUT https://api.tapfiliate.com/1.6/programs/johns-affiliate-program/affiliates/janejameson/approved/

Code Example

const request = require('request');

const options = {
  method: 'PUT',
  url: 'https://api.tapfiliate.com/1.6/programs/{program_id}/affiliates/{affiliate_id}/approved/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "id": "janejameson",
  "firstname": "Jane",
  "lastname": "Jameson",
  "email": "jane@example-blog.inc",
  "company": {
    "name": "Example blog Inc.",
    "description": "Best blog ever"
  },
  "address": {
    "address": "Rapenburgerstraat 173",
    "address_two": null,
    "postal_code": "1011 VM",
    "city": "Amsterdam",
    "state": "Noord-Holland",
    "country": {
      "code": "NL",
      "name": "Netherlands"
    }
  },
  "meta_data": {
    "foo": "bar",
    "meta": "data"
  },
  "parent_id": "sandrasanderson",
  "referral_link": {
    "link": "https://tapper.inc/johns-cool-product/?ref=nwjinmy",
    "asset_id": "1-aaaaaa",
    "source_id": "1-ssssss"
  },
  "coupon": "JANE10OFF",
  "approved": true,
  "affiliate_group_id": null,
  "created_at": "2021-05-27T11:39:03+00:00",
  "applied_at": "2021-05-27T11:39:03+00:00",
  "promoted_at": null,
  "promotion_method": null,
  "custom_fields": {
    "field1": "value1"
  }
}

Disapprove an affiliate

DELETE/programs/{program_id}/affiliates/{affiliate_id}/approved/
Response:200

URI Parameters

program_id
required
string
Example: johns-affiliate-program

The id of the program to add the affiliate too. This id can be found as part of the url when viewing the program on the platform.

affiliate_id
required
string
Example: janejameson

The id of the affiliate to approve.

DELETE https://api.tapfiliate.com/1.6/programs/johns-affiliate-program/affiliates/janejameson/approved/

Code Example

const request = require('request');

const options = {
  method: 'DELETE',
  url: 'https://api.tapfiliate.com/1.6/programs/{program_id}/affiliates/{affiliate_id}/approved/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "id": "janejameson",
  "firstname": "Jane",
  "lastname": "Jameson",
  "email": "jane@example-blog.inc",
  "company": {
    "name": "Example blog Inc.",
    "description": "Best blog ever"
  },
  "address": {
    "address": "Rapenburgerstraat 173",
    "address_two": null,
    "postal_code": "1011 VM",
    "city": "Amsterdam",
    "state": "Noord-Holland",
    "country": {
      "code": "NL",
      "name": "Netherlands"
    }
  },
  "meta_data": {
    "foo": "bar",
    "meta": "data"
  },
  "parent_id": "sandrasanderson",
  "referral_link": {
    "link": "https://tapper.inc/johns-cool-product/?ref=nwjinmy",
    "asset_id": "1-aaaaaa",
    "source_id": "1-ssssss"
  },
  "coupon": "JANE10OFF",
  "approved": false,
  "affiliate_group_id": null,
  "created_at": "2021-05-27T11:39:03+00:00",
  "applied_at": "2021-05-27T11:39:03+00:00",
  "promoted_at": null,
  "promotion_method": null,
  "custom_fields": {
    "field1": "value1"
  }
}

List program commission types

GET/programs/{program_id}/commission-types/
Response:200

URI Parameters

program_id
required
string
Example: johns-affiliate-program

The id of the Program. This id can be found as part of the url when viewing the program on the platform.

GET https://api.tapfiliate.com/1.6/programs/johns-affiliate-program/commission-types/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/programs/{program_id}/commission-types/'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

[
  {
    "title": "standard",
    "commission_form": "percentage",
    "affiliate_group_overrides": [
      {
        "commission_form": "percentage",
        "commission_value": 20,
        "affiliate_group_id": "ag_eXampl3"
      }
    ],
    "identifier": "standard",
    "commission_value": 10,
    "recurrence": "once",
    "visible": true,
    "count_towards_cap": true
  }
]

List program MLM levels

GET/programs/{program_id}/levels/
Response:200

URI Parameters

program_id
required
string
Example: johns-affiliate-program

The id of the Program. This id can be found as part of the url when viewing the program on the platform.

GET https://api.tapfiliate.com/1.6/programs/johns-affiliate-program/levels/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/programs/{program_id}/levels/'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

[
  {
    "title": "Level 2",
    "commission_form": "percentage",
    "identifier": "level-2",
    "commission_value": 5
  },
  {
    "title": "Level 3",
    "commission_form": "percentage",
    "identifier": "level-3",
    "commission_value": 3
  }
]

List program bonuses

GET/programs/{program_id}/bonuses/
Response:200

URI Parameters

program_id
required
string
Example: johns-affiliate-program

The id of the Program. This id can be found as part of the url when viewing the program on the platform.

GET https://api.tapfiliate.com/1.6/programs/johns-affiliate-program/bonuses/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/programs/{program_id}/bonuses/'
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

[
  {
    "title": "Sales bonus",
    "commission_form": "percentage",
    "identifier": "sales-bonus",
    "interval": "calmo",
    "target_type": "conversion_count",
    "active": true,
    "start_date": null,
    "end_date": null
  }
]

The following section describes the endpoints for our new Payments system, rolled out early 2019. You can check which version of our payments system you’re on, by looking at the name of the menu item when logged in to the platform. The current system is called “Payments”, and the legacy system is called “Payouts”.

List all balances

GET/balances/
Response:200

Returns a non-paginated list of all non-zero affiliate balances.

GET https://api.tapfiliate.com/1.6/balances/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/balances/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

[
  {
    "affiliate_id": "janejameson",
    "balances": {
      "USD": 5,
      "EUR": 35
    }
  },
  {
    "affiliate_id": "peterpeterson",
    "balances": {
      "USD": -50
    }
  }
]

Retrieve payment

GET/payments/{id}/
Response:200

URI Parameters

id
required
string
Example: pa_eXampl3

The id of the payment.

GET https://api.tapfiliate.com/1.6/payments/pa_eXampl3/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/payments/{id}/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "id": "pa_eXampl3",
  "created_at": "2021-03-29T08:36:07+00:00",
  "affiliate": {
    "id": "janejameson",
    "firstname": "Jane",
    "lastname": "Jameson"
  },
  "amount": 50,
  "currency": "USD"
}

Cancel payment

DELETE/payments/{id}/
Response:204

Cancels the payment and re-adds the amount to the affiliate’s balance

URI Parameters

id
required
string
Example: pa_eXampl3

The id of the payment.

DELETE https://api.tapfiliate.com/1.6/payments/pa_eXampl3/

Code Example

const request = require('request');

const options = {method: 'DELETE', url: 'https://api.tapfiliate.com/1.6/payments/{id}/'};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

List all payments

GET/payments/
Response:200
GET https://api.tapfiliate.com/1.6/payments/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/payments/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

[
  {
    "id": "pa_eXampl32",
    "created_at": "2021-03-29T08:36:07+00:00",
    "affiliate": {
      "id": "peterpeterson",
      "firstname": "Peter",
      "lastname": "Peterson"
    },
    "amount": 50,
    "currency": "USD"
  },
  {
    "id": "pa_eXampl3",
    "created_at": "2021-03-29T08:36:07+00:00",
    "affiliate": {
      "id": "janejameson",
      "firstname": "Jane",
      "lastname": "Jameson"
    },
    "amount": 50,
    "currency": "USD"
  }
]

Create a payment

POST/payments/
Response:200

Create a single payment or multiple (using an array of payments)

Arguments

affiliate_id
required
string

The affiliate id

amount
required
number

The payment amount

currency
required
string

The payment currency

POST https://api.tapfiliate.com/1.6/payments/

Code Example

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://api.tapfiliate.com/1.6/payments/',
  headers: {'content-type': 'application/json', 'X-Api-Key': 'SOME_STRING_VALUE'},
  body: {affiliate_id: '<ADD STRING VALUE>', amount: 0, currency: '<ADD STRING VALUE>'},
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Request

{
  "affiliate_id": "janejameson",
  "amount": 30.55,
  "currency": "USD"
}

Example Response

[
  {
    "id": "pa_eXampl3",
    "created_at": "2021-03-29T08:36:07+00:00",
    "affiliate": {
      "id": "janejameson",
      "firstname": "Jane",
      "lastname": "Jameson"
    },
    "amount": 50,
    "currency": "USD"
  }
]

The method is available only for the clients of Enterprise plan.

List all clicks

GET/clicks/{?program_id,affiliate_id,date_from,date_to}
Response:200

URI Parameters

program_id
optional
string
Example: johns-affiliate-program

The program Id

affiliate_id
optional
string
Example: janejameson

The affiliate Id

date_from
optional
string
Example: 2022-01-01

Date From

date_to
optional
string
Example: 2025-12-31

Date To

meta_data (optional, array) ... Meta Data value filter, example meta_data[key]
required
string
Default: subid1&meta_data[value]=baz 
GET https://api.tapfiliate.com/1.6/clicks/?program_id=johns-affiliate-program&affiliate_id=janejameson&date_from=2022-01-01&date_to=2025-12-31

Example Response

[
  {
    "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
    "created_at": "2023-12-14T00:00:00+00:00",
    "meta_data": [
      {
        "key": "subid1",
        "value": "baz"
      }
    ],
    "details": {
      "os": "Mac OS X",
      "os_version": "10.15.1",
      "browser": "Chrome",
      "browser_version": "81",
      "referrer": "https://duckduckgo.com",
      "platform": "Desktop",
      "landing_page_url": "https://dev.tap/"
    },
    "geolocation": {
      "country": "United States"
    }
  }
]

Create a Click

POST/clicks/
Response:200

In case you elect to use a REST-only implementation, you can use the “Create a Click” endpoint to obtain a click id. This click id can be used to create a conversion, by passing it as the click_id. You can learn how to set up a full REST-only integration in our REST integration guide

Arguments

referral_code
required
string

The affiliate’s referral code. Obtained from the url

source_id
optional
string

aaaaaa (string, optional) - The source id used by the affiliate (if any). Obtained from the url

meta_data
optional
object

Any meta data parameters passed by the affiliate.

Child Arguments

key
required
string

A key value pair. Multiple allowedtype

referrer
optional
string

The HTTP referrer. Will be used in reporting

landing_page
optional
string

The current page. Will be used in reporting

user_agent
optional
string

The full user agent string for the client. Will be used in reporting

ip
optional
string

The user IP address. Will be used in reporting

POST https://api.tapfiliate.com/1.6/clicks/

Code Example

const request = require('request');

const options = {
  method: 'POST',
  url: 'https://api.tapfiliate.com/1.6/clicks/',
  headers: {'X-Api-Key': 'SOME_STRING_VALUE'},
  body: {
    referral_code: '<ADD STRING VALUE>',
    source_id: '<ADD STRING VALUE>',
    meta_data: {key: '<ADD STRING VALUE>'},
    referrer: '<ADD STRING VALUE>',
    landing_page: '<ADD STRING VALUE>',
    user_agent: '<ADD STRING VALUE>',
    ip: '<ADD STRING VALUE>'
  },
  json: true
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Request

{
  "referral_code": "janejameson",
  "source_id": "1",
  "meta_data": {
    "key": "value"
  },
  "referrer": "https://averycoolblog.com",
  "landing_page": "https://tapfiliate.com/signup",
  "user_agent": "Mozilla/5.0 (Macintosh; Intel Mac OS X x.y; rv:42.0) Gecko/20100101 Firefox/42.0",
  "ip": "8.8.8.8"
}

Example Response

{
  "id": "ab885a1c-8ad9-11ea-bc55-0242ac130003"
}

The method is available only for the clients of Enterprise plan.

Get detailed information about click

GET/clicks/{id}/
Response:200

URI Parameters

id
required
string
Example: aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee

The id of the click.

GET https://api.tapfiliate.com/1.6/clicks/aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee/

Code Example

const request = require('request');

const options = {
  method: 'GET',
  url: 'https://api.tapfiliate.com/1.6/clicks/{id}/',
  headers: {'content-type': 'application/json'}
};

request(options, function (error, response, body) {
  if (error) throw new Error(error);

  console.log(body);
});

Example Response

{
  "id": "aaaaaaaa-bbbb-cccc-dddd-eeeeeeeeeeee",
  "created_at": "2023-12-14T00:00:00+00:00",
  "meta_data": [
    {
      "key": "subid1",
      "value": "baz"
    }
  ],
  "details": {
    "os": "Mac OS X",
    "os_version": "10.15.1",
    "browser": "Chrome",
    "browser_version": "81",
    "referrer": "https://duckduckgo.com",
    "platform": "Desktop",
    "landing_page_url": "https://dev.tap/"
  },
  "geolocation": {
    "country": "United States"
  },
  "affiliate": {
    "id": "janejameson",
    "firstname": "Jameson",
    "lastname": "Jane"
  },
  "program": {
    "id": "johns-affiliate-program",
    "title": "John's affiliate program",
    "currency": "USD"
  },
  "link": {
    "asset_id": "1-aaaaaa",
    "source_id": "1-ssssss"
  }
}