> ## Documentation Index
> Fetch the complete documentation index at: https://support.tapfiliate.com/llms.txt
> Use this file to discover all available pages before exploring further.

# How to integrate with Tapfiliate via the REST API

> If you are looking for the most powerful and flexible integration type to connect your website/app with Tapfiliate, REST API is your choice.

November 9, 2026

Tapfiliate’s REST API integration lets you automate and manage affiliates, commissions, and conversions in real time from any platform.

**✏️ In this article, we'll discuss:**

* [What makes the REST API your best and all-purpose tool for tracking](#h_be358528b6)
* [Requirements to install REST to Tapfiliate](#h_ef663f85d0)
* [Core Setup steps](#h_e0fab88d51)
* [Verifying your REST API integration](#h_c3f687579c)
* [Advanced use-cases that can be covered with the REST API](#h_1fb2cc6bd1)
* **[A complete REST API library (Dev section)](#h_6b415d07c1)**

### Why REST API is the most flexible tracking solution😍

REST API ensures robust and adaptable integration between systems due to its unique aspects:

* 🔒 **Secure authorization** (via the [API key](https://support.tapfiliate.com/getting-started/essential-account-settings/how-to-find-account-id-and-api-key.md)) - The system will only accept the authorized calls to the Tapfiliate API. Any attempts to create an action without a secret API key will fail, ensuring the safety of your setup.
* 🎨 **Customizable requests** (you can collect more data when tracking) - Unlike some of our pre-made integrations, the REST API is very flexible in terms of data that can be passed along with your API requests - whether it defines an alternate commission type, referrer information, or any additional data passed within the `meta_data` parameter.
* 🥊 **Ad-blockers resistant** (accurate tracking) - REST API is a backend (server-side) integration, which means you don't have to add any tracking script inside your website pages. Therefore, any ad-blocking software or extension will not affect the tracking process, as it only applies to the third-party tracking codes on the website.
* **💻 No need to install the tracking code** — This factor makes the REST API an excellent fit for CMS-based websites where it's not allowed to add custom code. It also makes it an excellent solution for connecting the applications (if your affiliate campaign is not website-oriented), so you can integrate the web/mobile app with Tapfiliate via API endpoints.
* ↕️ **Avoids cross-domain limitations** - Assuming you don't need to rely on the tracking code, the REST API also helps cover the cases where your customer's flow includes multiple instances located on different domains/systems, which is not natively possible within code-based integrations.

### What do you need to set up the REST API tracking in Tapfiliate 🔧

**To successfully integrate, ensure you have the following:**

* A live Tapfiliate account with access to your *API key*. Your API key is generated and stored at the bottom of your *Profile Settings* page:

  ![](https://mintcdn.com/tapfiliate-help/Q52FWBFGgBPv4--Y/images/12682358/01-image.png?fit=max\&auto=format\&n=Q52FWBFGgBPv4--Y\&q=85\&s=ef9979c042f500f0c7090390bc81b838)

* Admin/developer access to your server - required to process the API scenarios and send the data on tracking events from your side to the Tapfiliate server.

* A test affiliate added to your account ( 👉 [here's how you can create one](https://support.tapfiliate.com/integrations/test-your-integration/how-to-validate-your-tracking.md)).

### The essential integration steps ⚙️

###### Step 1. Locate your affiliate referral link

In your *Affiliates* overview, you can choose a test affiliate and copy their referral link. You will need the code that goes after `?ref=abcdefg` to attribute the further actions to a specific affiliate in the program.

![](https://mintcdn.com/tapfiliate-help/Q52FWBFGgBPv4--Y/images/12682358/02-image.png?fit=max\&auto=format\&n=Q52FWBFGgBPv4--Y\&q=85\&s=77cfed98e2c5fb977fcabd1140d92bc6)

###### Step 2. Create a click

Using your affiliate's referral code, create a click via this API endpoint:

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

**Request example:**

```json theme={null}
{
  "referral_code":"ytg4zwq",
}
```

A response to this endpoint will contain the `click_id` value - you can use it in subsequent steps when associating a particular click with a tracked customer/conversion.

![](https://mintcdn.com/tapfiliate-help/Q52FWBFGgBPv4--Y/images/12682358/03-image.png?fit=max\&auto=format\&n=Q52FWBFGgBPv4--Y\&q=85\&s=a162e23aa7a23d1a9b599fcb1d2d4f26)

💡 Store the `click_id` value for further actions on your database end.

###### Step 3. Create a conversion

Now that you have a click\_id that records the visitor's data upon their access to the website/app, you can attach a conversion action via the REST API.

Here is an endpoint to call:

```
https://api.tapfiliate.com/1.6/conversions/
```

###### Attach and save more information within the conversion API call

* **referral\_code (optional) -** An affiliate’s referral code. This corresponds to the value of `ref=` in their referral link.

* **tracking\_id (optional) -** Used if you are tracking a conversion with the help of a hybrid (REST API + JavaScript) integration.

* **click\_id (optional) -** The value that was created within the click event. If you have attached any additional information to a click event, it will also be included in the conversion call response.

* **coupon (optional)** - An alternative parameter to track the conversion by (used in cases when you attribute conversions not by a referral code or a click\_id, but via the affiliate coupon value).

* **currency (optional)** - The three-letter ISO currency code. Override the program’s default currency for this conversion by explicitly passing a currency code.

* **asset\_id (optional)** - Matching the `tap_a` parameter, if you are using anonymized referral links.

* **source\_id (optional)** - Matching the `tap_s` parameter, if you are using anonymized referral links.

* **external\_id (optional)** - A unique identifier for this conversion. It can be anything meaningful to you, like an order number, user ID, or email address. After a conversion occurs, 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 database. This ID must be unique for each conversion.

* **amount (optional)** - The conversion amount

* **customer\_id (optional)** - The ID for the current customer in your system. Depending on your program settings, this can be used for recurring / lifetime commissions.

* **commission\_type (optional)** - If no commission type is supplied, the program's default commission type is used.

* **commissions (optional)** - Will override the `amount` and `commission_type` parameters if set.

* **meta\_data (optional)** - Metadata for this transaction, used if you need to attach additional information to a conversion (such as product characteristics, category, quantity, etc.) that is not listed within the existing parameters above.

  **Child Arguments**

* **user\_agent (optional)** - The client’s user agent string. Used for statistics and fraud detection.

* **ip (optional)** - The client’s IP address. Used for fraud detection and recording the information on the GEOs.

###### An example of the conversion API request

```json theme={null}
{
  "click_id":"5d879dea-b4dc-11f0-819f-df0029755135",
  "external_id": "SUB020",
  "amount": 75,
  "currency": "USD",
  "meta_data": {
    "product_qty": "4"
  },
  "user_agent": "Mozilla/5.0 (Windows; U; Windows NT 10.0;; en-US) Gecko/20100101 Firefox/45.2",
  "ip": "198.15.139.1"
}
```

###### The API response example

```json theme={null}
{
    "id": 29870167,
    "created_at": "2025-10-29T15:32:16+00:00",
    "click": {
        "created_at": "2025-10-29T15:31:40+00:00",
        "referrer": null,
        "landing_page": null
    },
    "affiliate_meta_data": {
        "product_qty": "4"
    },
    "program": {
        "id": "another-store",
        "title": "Another store",
        "currency": "USD"
    },
    "affiliate": {
        "id": "testpolzin1",
        "firstname": "Biba",
        "lastname": "Boba"
    },
    "warnings": null,
    "amount": 75.0,
    "meta_data": {
        "product_qty": "4"
    },
    "customer": null,
    "external_id": "SUB020",
    "commissions": [{
        "kind": "regular",
        "affiliate": {
            "id": "testpolzin1",
            "firstname": "Biba",
            "lastname": "Boba"
        },
        "currency": "USD",
        "id": 39137693,
        "created_at": "2025-10-29T15:32:16+00:00",
        "payout": null,
        "commission_type": "standard",
        "commission_name": "Standard",
        "approved": null,
        "amount": 7.5,
        "comment": null,
        "conversion_sub_amount": 75.0,
        "final": false
    }]
}
```

You will be able to see the results of your API calls inside the *Conversions* section of your Tapfiliate account:

![](https://mintcdn.com/tapfiliate-help/Q52FWBFGgBPv4--Y/images/12682358/04-image.png?fit=max\&auto=format\&n=Q52FWBFGgBPv4--Y\&q=85\&s=c43f3768bd658d77cdc551d77ba2d9d1)

### Verify your REST API connection 👍

The REST API integration requires you to make a test purchase via an affiliate's referral code. You can use it during testing and follow [the Steps 1-3 we described above](#h_b8d0858ea6). If you'll see the integration step marked as completed in the Getting Started Guide, and the conversion/click data populating in your *Tapfiliate Reporting*, you're all set 🎊

### What else can be covered by the REST API (Advanced Use-Cases) 🆙

As highlighted above, the REST API supports a wide range of advanced tracking scenarios. Below, we will go over some of these.

##### Tracking different commissions per product/different actions

When you need to [assign a conversion with a *different commission rate*](https://support.tapfiliate.com/advanced-configurations-automation/scale-plan/how-to-apply-extra-commissions-to-affiliates.md) (for example, if this conversion represents a different in-platform action, a separate product, or a category), add the commission\_type identifier to your API request when tracking the conversion.

API endpoint URL:\

[`https://api.tapfiliate.com/1.6/conversions/`](https://api.tapfiliate.com/1.6/conversions/)

###### Request example:

```json theme={null}
{
  "coupon": "CRAIG10",
  "external_id": "SUB021",
  "amount": 900,
  "commission_type": "boyjacket",
  "currency": "GBP",
  "meta_data": {
    "product_type": "Stainless Cord"
  },
  "user_agent": "Mozilla/5.0 (X11; CrOS aarch64 13505.15.0) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/87.0.4280.24 Safari/537.36",
  "ip": "61.168.33.16"
}
```

Here, we have added the **commission type identifier** you created to the API request to override the standard commission rate. In a response, you will see the respective commission amount. 👌

##### Pass additional information with a conversion/customer data

If you need to attach additional information to a conversion or a customer while tracking, the best solution is to **include metadata** in the conversion/customer creation call. You can also add metadata when tracking a click, and it will be included in the conversion metadata if a conversion is associated with this click.

API endpoint URL:

* For conversion metadata: [`https://api.tapfiliate.com/1.6/conversions/`](https://api.tapfiliate.com/1.6/conversions/)
* For customer metadata: [`https://api.tapfiliate.com/1.6/customers/`](https://api.tapfiliate.com/1.6/customers/)
* For click metadata: [`https://api.tapfiliate.com/1.6/clicks/`](https://api.tapfiliate.com/1.6/clicks/)

###### Request example:

```json theme={null}
{
  "coupon": "RITA25",
  "customer_id": "user_018",
  "status": "trial",
  "meta_data": {
```

**`"age": "29"`**\

**`},`**

```
  "user_agent": "Mozilla/5.0 (Linux; Android 10; Infinix X682B) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.61 Mobile Safari/537.36",
  "ip": "11.106.78.125"
}
```

You can view the metadata attached to the *Customer details* in your Tapfiliate account.

![](https://mintcdn.com/tapfiliate-help/Q52FWBFGgBPv4--Y/images/12682358/05-image.png?fit=max\&auto=format\&n=Q52FWBFGgBPv4--Y\&q=85\&s=6f9210d3e02173d3a62f35d775170a56)

##### Manage affiliate payouts

It's possible to **automate affiliate payments** through Tapfiliate's REST API as follows:

1. Get the outstanding balances via this endpoint: [`https://api.tapfiliate.com/1.6/balances/`](https://api.tapfiliate.com/1.6/balances/) (GET method)
2. Get the affiliate’s payout information: [https://api.tapfiliate.com/1.6/affiliates/janejameson/payout-methods/](https://api.tapfiliate.com/1.6/affiliates/janejameson/payout-methods/)
3. Complete the payment with your preferred payment provider using its API.
4. Create a new payment for the affiliate for the paid out amount using this endpoint:\

   [https://api.tapfiliate.com/1.6/payments/](https://api.tapfiliate.com/1.6/payments/) (POST method)

## Complete REST API library 📚

Here, you will find all endpoints available in Tapfiliate's REST API, grouped by the areas they affect and the actions they process.

## General 🌐

### Authentication

You should authenticate your API request by adding your API key, as **`X-Api-Key`** along in the header of every request:

```
X-Api-Key: “YOUR_API_KEY”
```

You can find and copy your API key in your account settings. To prevent unwanted interference with your tracking, you should not share your API key anywhere where others can see it (e.g., frontend JavaScript code, public repositories, screenshots, blogs, etc.).\

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

### 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.

**Possible ref values:**

| Name | Description |
| - | - |
| next | Shows the URL of the immediate next page of results. |
| last | Shows the URL of the last page of results. |
| first | Shows the URL of the first page of results. |
| prev | Shows the URL of the immediate previous page of results. |

👉 If you need to view over 400 pages, you can use a special pagination parameter from the X-Pagination-Cursor header.

###### How it works:

1. Make an initial API call to the required endpoint (for example, List all clicks: [https://api.tapfiliate.com/1.6/clicks/](https://api.tapfiliate.com/1.6/clicks/))
2. A successful API response will return the X-Pagination-Cursor: XXXXXXXXXXXXX (digital value).
3. To view the next page, you can use the value you received in the next API call, as `https://api.tapfiliate.com/1.6/clicks/?searchFrom=XXXXXXXXXXXXX`.
4. The API will return the new batch of clicks and a new X-Pagination-Cursor value.
5. Using the new pagination value, you can repeat steps 2-4 as long as required to list all data.

### Limits

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

| Header | Description |
| - | - |
| X-Ratelimit-Limit | The total number of allowed requests within a given period |
| X-Ratelimit-Remaining | The number of requests you have left before exceeding the rate limit |
| X-Ratelimit-Reset | When your number of requests will reset (Unix Timestamp in seconds) |

## By account sections 📄

### Clicks

* [Create a click](#h_068c11c9f2)
* [List all clicks (Enterprise endpoint)](#h_95897575bc)
* [Get detailed information about the click (Enterprise endpoint)](#h_de16871d39)

##### Сreate a click

Method: POST\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/clicks/`](https://api.tapfiliate.com/1.6/clicks/)

###### Request example:

```json theme={null}
{
  "referral_code": "zwiwztl",
  "meta_data": {
    "visitor_time": "average"
  },
  "referrer": "https://myblog.com",
  "landing_page": "https://tapfiliate.com/signup",
  "user_agent": "Dalvik/2.1.0 (Linux; U; Android 5.1; MELROSE S9 Build/LMY47I)",
  "ip": "214.179.20.61"
}
```

###### Response example:

```json theme={null}
{
    "id": "07fabc34-b57e-11f0-8223-358ef8c71026"
}
```

###### Arguments you can add to the request:

* **referral\_code (required) -** The affiliate’s referral code, obtained from the URL
* **source\_id (optional) -** `aaaaaa` (string, optional) - The source ID used by the affiliate (if any). Obtained from the URL.
* **meta\_data (optional) -** Any metadata parameters passed by the affiliate.\

  **Child Arguments**
  * **key (required) -** A key value pair. Multiple allowed types.
* **referrer (optional) -** The HTTP referrer. Will be used in reporting.
* **landing\_page (optional) -** The current page. Will be used in reporting.
* **user\_agent (optional) -** The whole user agent string for the client, which identifies their browser and device. Will be used in reporting.
* **ip (optional) -** The user's IP address. Will be used in reporting.

##### List all clicks (Enterprise plan only)

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/clicks/?program_id=my-business&affiliate_id=craigstanford&date_from=2025-01-01&date_to=2025-12-31`](https://api.tapfiliate.com/1.6/clicks/?program_id=my-business\&affiliate_id=craigstanford\&date_from=2025-01-01\&date_to=2025-12-31)

The request body will be empty, as all required parameters will be added to the request URL as query parameters.

###### URI parameters you can add to the request:

* **program\_id (optional) -** *Example: my-business*. The program ID, located in your account's Advanced settings.
* **affiliate\_id (optional) -** *Example: craigstanford.* The affiliate's ID in the API.
* **date\_from (optional) -** Example: 2025-01-01. Date From, a day in UTC.
* **date\_to (optional) -** *Example: 2025-12-31.* Date To, a day in UTC.

###### Response example

```json theme={null}
[{
    "id": "07fabc34-b57e-11f0-8223-358ef8c71026",
    "created_at": "2025-10-30T10:48:55+00:00",
    "meta_data": [{
        "key": "visitor_time",
        "value": "average"
    }],
    "details": {
        "landing_page_url": "https://tapfiliate.com/signup",
        "platform": "MELROSE S9",
        "os": "Android",
        "os_version": "5.1",
        "browser": "Android",
        "browser_version": "5.1",
        "referrer": "https://myblog.com"
    },
    "geolocation": {
        "country": "United States"
    }
}
```

##### Get detailed information about the click (Enterprise plan only)

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/clicks/ded3f4be-aa8e-11f0-8664-a90a6859c602/`](https://api.tapfiliate.com/1.6/clicks/ded3f4be-aa8e-11f0-8664-a90a6859c602/)

###### URI parameters:

* **id (required)** - The ID of a click you want to get the info.

The request body will be empty, as all required parameters will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "id": "ded3f4be-aa8e-11f0-8664-a90a6859c602",
    "created_at": "2025-10-16T12:51:44+00:00",
    "meta_data": [{
        "key": "qty",
        "value": "4"
    }],
    "details": {
        "landing_page_url": "https://mysupersite.com/signup",
        "platform": "iPad",
        "os": "iOS",
        "os_version": "11.6",
        "browser": "Chrome Mobile",
        "browser_version": "49.0",
        "referrer": "https://blogpost.com"
    },
    "geolocation": {
        "country": "United States"
    },
    "affiliate": {
        "id": "craigstanford",
        "firstname": "Stanford",
        "lastname": "Craig"
    },
    "program": {
        "id": "my-business",
        "title": "My Business",
        "currency": "USD"
    },
    "link": {
        "asset_id": "154981-02c363",
        "source_id": "8132920-95b896"
    }
}
```

### Conversions

* [Create a conversion](#h_58f0844152)
* [Retrieve a conversion](#h_c5cb7f1917)
* [Update a conversion](#h_ea64c30212)
* [Delete a conversion](#h_12067f5763)
* [List all conversions](#h_6a4a5426aa)
* [Add commissions to a conversion](#h_d4edc65376)
* [Retrieve metadata](#h_c75a04a56c)
* [Update (replace) metadata](#h_0381075e20)
* [Retrieve metadata by key](#h_2db709b024)
* [Set metadata by key](#h_d7ffbe2bed)
* [Delete metadata by key](#h_9b0b23cad6)

##### Create a conversion

To create a conversion, you must provide one of the following parameters: `referral code`, `customer_id`, `click_id`, `coupon`, `tracking_id`, or a combination of `asset_id` and `source_id`.\

If multiple identifiers are included, the system will prioritize them in this order (highest to lowest): customer\_id, coupon code, referral code, click ID, asset\_id + source\_id, and tracking ID.

Method: POST\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/conversions/`](https://api.tapfiliate.com/1.6/conversions/)

###### URI parameters:

* **override\_max\_cookie\_time (optional) -** A boolean value that defines whether your program's cookie lifetime should be overridden when creating a conversion. If set to `False`, a conversion will not be created outside the cookie lifetime; if set to `True`, a conversion will be recorded regardless of the cookie lifetime. Set to `False` by default.

Arguments you can use in the request [are listed above 👆](#h_92d6a431d7)

Request example - [see above.](#h_6857b4ac88)\

Response example - [see above.](#h_0069c3adcf)

##### Retrieve a conversion

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/conversions/29877192/`](https://api.tapfiliate.com/1.6/conversions/29877192/)

###### URI parameters:

* **conversion\_id (required) -** *Example:* `29877192`. The numeric identifier of the conversion to apply the action to. Retrieved from the API, does not match the External ID in Tapfiliate.

![](https://mintcdn.com/tapfiliate-help/Q52FWBFGgBPv4--Y/images/12682358/06-image.png?fit=max\&auto=format\&n=Q52FWBFGgBPv4--Y\&q=85\&s=bb4fd51dd1efd739b6d07d3470c9a36a)

The request body will be empty, as all required parameters will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "id": 29877192,
    "created_at": "2025-10-30T12:37:28+00:00",
    "click": null,
    "affiliate_meta_data": null,
    "program": {
        "id": "my-business",
        "title": "My Business",
        "currency": "USD"
    },
    "affiliate": {
        "id": "sonyanaum",
        "firstname": "Sonya",
        "lastname": "Naum"
    },
    "warnings": null,
    "amount": 100.0,
    "meta_data": {},
    "customer": {
        "id": "cu_Y_T_f5wEjmthuGLC10",
        "customer_id": "customer-SUB022",
        "status": "active"
    },
    "external_id": "SUB022",
    "commissions": [{
        "kind": "regular",
        "affiliate": {
            "id": "sonyanaum",
            "firstname": "Sonya",
            "lastname": "Naum"
        },
        "currency": "USD",
        "id": 39145948,
        "created_at": "2025-10-30T12:37:28+00:00",
        "payout": null,
        "commission_type": "standard",
        "commission_name": "Standard",
        "approved": null,
        "amount": 10.0,
        "comment": null,
        "conversion_sub_amount": 100.0,
        "final": false
    }]
}
```

##### Update a conversion

Method: PATCH\

Endpoint URL:

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

###### URI parameters:

* **conversion\_id (required) - Example:** 1 The numeric identifier of the conversion to apply the action to. Retrieved from the API, does not match the External ID in Tapfiliate.
* **recalculate\_commissions (optional) -** recalculates commissions when the Conversion amount changes.

###### Arguments for this API request:

* **amount (optional) -** The new commission amount, if you want to update it.
* **external\_id (optional) -** A unique ID for this conversion. You can use any identifier that is meaningful to you, such as an order number, user ID, email address, etc. After the conversion occurs, this ID will be displayed alongside the conversion on our platform.
* **meta\_data (optional) -** Metadata for this resource

###### Request example:

```json theme={null}
{
  "amount": 420,
  "external_id": "SUB022",
  "meta_data": {
    "product_type": "new sample"
  }
}
```

###### Response example:

```json theme={null}
{
    "id": 29877192,
    "created_at": "2025-10-30T12:37:28+00:00",
    "click": null,
    "affiliate_meta_data": null,
    "program": {
        "id": "my-business",
        "title": "My Business",
        "currency": "USD"
    },
    "affiliate": {
        "id": "sonyanaum",
        "firstname": "Sonya",
        "lastname": "Naum"
    },
    "warnings": null,
    "amount": 420.0,
    "meta_data": {
        "product_type": "new sample"
    },
    "customer": {
        "id": "cu_Y_T_f5wEjmthuGLC10",
        "customer_id": "customer-SUB022",
        "status": "active"
    },
    "external_id": "SUB022",
    "commissions": [{
        "kind": "regular",
        "affiliate": {
            "id": "sonyanaum",
            "firstname": "Sonya",
            "lastname": "Naum"
        },
        "currency": "USD",
        "id": 39145948,
        "created_at": "2025-10-30T12:37:28+00:00",
        "payout": null,
        "commission_type": "standard",
        "commission_name": "Standard",
        "approved": null,
        "amount": 10.0,
        "comment": null,
        "conversion_sub_amount": 100.0,
        "final": false
    }]
}
```

##### Delete a conversion

Method: DELETE\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/conversions/29877192/`](https://api.tapfiliate.com/1.6/conversions/29877192/)

###### URI parameters:

* **conversion\_id (required) -** *Example:* `29877192`. The numeric identifier of the conversion to apply the action to. Retrieved from the API, does not match the External ID in Tapfiliate.

Both the request and response bodies will be empty, as all required data will be added to the request URL as query parameters. The successful request will return the `204` code.

##### List all conversions

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/conversions/?program_id=my-business&external_id=SUB019&affiliate_id=ritabailando&pending=true`](https://api.tapfiliate.com/1.6/conversions/?program_id=my-business\&external_id=SUB019\&affiliate_id=ritabailando\&pending=true)

###### URI parameters:

* **program\_id (optional) -** *Example: my-business*. The program's ID, located in the Advanced settings.
* **external\_id (optional) -** *Example: SUB019.* This is the unique order/transaction ID from your system or shopping cart. This ID was passed when the conversions were first tracked.
* **affiliate\_id (optional) -** *Example: ritabailando.* The affiliate ID.
* **pending (optional) -** *Example: false.* Defines whether the approved/disapproved commissions will be included in the response.
* **date\_from (optional) -** *Example: 2025-01-01*. Date From, a day in UTC.
* **date\_to (optional) -** *Example: 2025-12-31.* Date To, a day in UTC.
* **use\_profile\_timezone (optional) -** Deprecated, has no effect: dates in Tapfiliate are in UTC for every account.

###### Response example:

```json theme={null}
{
    "id": 28905353,
    "created_at": "2025-06-24T09:58:48+00:00",
    "click": null,
    "affiliate_meta_data": null,
    "program": {
        "id": "my-business",
        "title": "My Business",
        "currency": "USD"
    },
    "affiliate": {
        "id": "ritabailando",
        "firstname": "Rita",
        "lastname": "Bailando"
    },
    "warnings": null,
    "amount": 250.0,
    "meta_data": {
        "product": "Sample Item Option 5"
    },
    "customer": null,
    "external_id": "SUB004",
    "commissions": [{
        "kind": "regular",
        "affiliate": {
            "id": "ritabailando",
            "firstname": "Rita",
            "lastname": "Bailando"
        },
        "currency": "USD",
        "id": 38080490,
        "created_at": "2025-06-24T09:58:48+00:00",
        "payout": null,
        "commission_type": "standard",
        "commission_name": "Standard",
        "approved": false,
        "amount": 25.0,
        "comment": null,
        "conversion_sub_amount": 250.0,
        "final": false
    }]
```

##### Add commissions to a conversion

Used when you want to attach additional commission to an existing conversion.

Method: POST\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/conversions/28905353/commissions/`](https://api.tapfiliate.com/1.6/conversions/28905353/commissions/)

###### URI parameters:

* **conversion\_id (required) -** *Example:* `28905353`. The numeric identifier of the conversion to apply the action to. Retrieved from the API, do not match the External ID in Tapfiliate.

###### Arguments for the request:

* **conversion\_sub\_amount (required) -** The amount used to calculate the commission, according to the given or default commission type.
* **commission\_type (optional) -** If no commission type is supplied, the programs default commission type is used
* **comment (optional) -** A comment for this commission. The comment will be visible to the affiliate - great way to explain the changes made.

###### Request example:

```json theme={null}
{
  "conversion_sub_amount": 50,
  "commission_type": "frienddonation",
  "comment": "Upsell for the order"
}
```

###### Response example:

```json theme={null}
[{
    "kind": "regular",
    "affiliate": {
        "id": "lindaquark",
        "firstname": "Linda",
        "lastname": "Quark"
    },
    "currency": "USD",
    "id": 39147267,
    "created_at": "2025-10-30T15:31:03+00:00",
    "payout": null,
    "commission_type": "frienddonation",
    "commission_name": "Donation",
    "approved": null,
    "amount": 3.0,
    "comment": "Upsell for the order",
    "conversion_sub_amount": 50.0,
    "final": false
}]
```

> [!WARNING]
>
> **Who can receive the commission**\\
>
> The commission goes to the affiliate of the conversion. That affiliate must be **approved** in the conversion's program. If the affiliate is **disapproved**, still pending, not a member of that program, or deleted, the request is refused with a `400` response and no commission is created – including MLM commissions for the affiliate's parent affiliates.
>
> Error response example:
>
> ```json theme={null}
> {"errors":[{"message":"Affiliate is not approved for this program"}]}
> ```
>
> For a **deleted** affiliate the message is `Affiliate is deleted`.
>
> 💡 Tip: to check an affiliate's status before sending the request, use **Retrieve an affiliate in a program** and look at the `approved` field.

##### Retrieve metadata

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/conversions/28905353/meta-data/`](https://api.tapfiliate.com/1.6/conversions/28905353/meta-data/)

###### URI parameters:

* **conversion\_id (required) -** *Example:* `29877192`. The numeric identifier of the conversion to apply the action to. Retrieved from the API, does not match the External ID in Tapfiliate.

The request body will be empty, as all required parameters will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "product": "Sample Item Option 5"
}
```

##### Update (replace) metadata

Method: PUT\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/conversions/28905353/meta-data/`](https://api.tapfiliate.com/1.6/conversions/28905353/meta-data/)

###### URI parameters:

* **conversion\_id (required) -** *Example:* `29877192`. The numeric identifier of the conversion to apply the action to. Retrieved from the API, does not match the External ID in Tapfiliate.

###### Arguments for the request body:

* **metadata** - You will require a key and the value, for example "product": "Sample Item Option 73".

###### Request example:

```json theme={null}
{
  "product": "Sample Item Option 73",
  "product_qty": "4"
}
```

Response example:

```json theme={null}
{
    "product": "Sample Item Option 73",
    "product_qty": "4"
}
```

##### Retrieve metadata by key

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/conversions/28905353/meta-data/product_qty/`](https://api.tapfiliate.com/1.6/conversions/28905353/meta-data/product_qty/)

###### URI parameters:

* **conversion\_id (required) -** *Example:* `29877192`. The numeric identifier of the conversion to apply the action to. Retrieved from the API, does not match the External ID in Tapfiliate.
* **key (required)** - the metadata key. This key will sort the information in the API response.

The request body will be empty, as all the necessary parameters will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "value": "4"
}
```

##### Set metadata by key

Method: PUT\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/conversions/28905353/meta-data/product_qty/`](https://api.tapfiliate.com/1.6/conversions/28905353/meta-data/product_qty/)

###### URI parameters:

* **conversion\_id (required) -** *Example:* `29877192`. The numeric identifier of the conversion to apply the action to. Retrieved from the API, does not match the External ID in Tapfiliate.
* **key (required)** - the metadata key. This key will sort the information in the API response.

###### Request example:

```json theme={null}
{
    "value": "3"
}
```

###### Response example:

```json theme={null}
{
    "value": "3"
}
```

##### Delete metadata by key

Method: DELETE\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/conversions/28905353/meta-data/product_qty/`](https://api.tapfiliate.com/1.6/conversions/28905353/meta-data/product_qty/)

###### URI parameters:

* **conversion\_id (required) -** *Example:* `29877192`. The numeric identifier of the conversion to apply the action to. Retrieved from the API, does not match the External ID in Tapfiliate.
* **key (required)** - the metadata key. This key will sort the information in the API response.

Both the request and response bodies will be empty, as all required data will be added to the request URL as query parameters. The successful request will return the `204` code.

### Commissions

* [Retrieve a commission](#h_b0bef1837f)
* [Update a commission](#h_0db7dab815)
* [List all commissions](#h_2a96d99aab)
* [Approve a commission](#h_e717fd779d)
* [Disapprove a commission](#h_3160aeee80)

##### Retrieve a commission

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/commissions/38080490/`](https://api.tapfiliate.com/1.6/commissions/38080490/)

###### URI parameters:

* **commission\_id (required) -** *Example:* `38080490`. The numeric identifier of the commission to fetch. Retrieved from the API.

The request body will be empty, as all the necessary parameters will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "kind": "regular",
    "affiliate": {
        "id": "lindaquark",
        "firstname": "Linda",
        "lastname": "Quark"
    },
    "currency": "USD",
    "id": 38080490,
    "created_at": "2025-06-24T09:58:48+00:00",
    "conversion": {
        "id": 28905353
    },
    "payout": null,
    "commission_type": "standard",
    "commission_name": "Standard",
    "approved": true,
    "amount": 25.0,
    "comment": null,
    "finalization_date": null,
    "conversion_sub_amount": 250.0,
    "final": false
}
```

##### Update a commission

Method: PATCH\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/commissions/38080490/`](https://api.tapfiliate.com/1.6/commissions/38080490/)

###### URI parameters:

* **commission\_id (required) -** *Example:* `38080490`. The numeric identifier of the commission to fetch. Retrieved from the API.

###### Arguments to use:

* **amount (optional) -** The new commission amount.
* **comment (optional) -** A comment for this commission. The comment will be visible to the affiliate.
* **approved (optional) -** A boolean value (set to true/false) to approve or disapprove commission.
* **conversion\_sub\_amount (optional) -** The new value for the conversion (will be recalculated).

###### Request example:

```json theme={null}
{
  "amount": 30.55,
  "comment": "Recharged",
  "approved": true,
  "conversion_sub_amount": 50.00
}
```

###### Response example:

```json theme={null}
{
    "kind": "regular",
    "affiliate": {
        "id": "lindaquark",
        "firstname": "Linda",
        "lastname": "Quark"
    },
    "currency": "USD",
    "id": 38080490,
    "created_at": "2025-06-24T09:58:48+00:00",
    "conversion": {
        "id": 28905353
    },
    "payout": null,
    "commission_type": "standard",
    "commission_name": "Standard",
    "approved": true,
    "amount": 30.55,
    "comment": "Recharged",
    "finalization_date": null,
    "conversion_sub_amount": 50.0,
    "final": false
}
```

##### List all commissions

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/commissions/?affiliate_id=craigstanford&status=approved&paid=0`](https://api.tapfiliate.com/1.6/commissions/?affiliate_id=craigstanford\&status=approved\&paid=0)

###### URI parameters:

* **affiliate\_id (optional) -** *Example: craigstanford.* The affiliate ID.
* **status (optional) -** *Example: approved.* An optional approval status to filter by. Valid values are: **`approved`** | **`disapproved`** | **`pending`.**
* **paid (optional) -** *Example: 0*. Only shows commissions that are paid out. Valid values are: `1` and `0`.

The request body will be empty, as all required parameters will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "kind": "level",
    "affiliate": {
        "id": "craigstanford",
        "firstname": "Craig",
        "lastname": "Stanford"
    },
    "currency": "USD",
    "id": 38080497,
    "created_at": "2025-06-24T10:00:08+00:00",
    "conversion": {
        "id": 28905358
    },
    "payout": null,
    "commission_type": "level-2",
    "commission_name": "Level 2",
    "approved": true,
    "amount": 10.0,
    "comment": null,
    "finalization_date": null,
    "conversion_sub_amount": 500.0,
    "final": false
}
```

##### Approve a commission

Method: PUT\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/commissions/38080490/approved/`](https://api.tapfiliate.com/1.6/commissions/38080490/approved/)

###### URI parameters:

* **commission\_id (required) -** *Example:* `38080490`. The numeric identifier of the commission to fetch. Retrieved from the API.

The request and response bodies will be empty, as all required data will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "kind": "regular",
    "affiliate": {
        "id": "lindaquark",
        "firstname": "Linda",
        "lastname": "Quark"
    },
    "currency": "USD",
    "id": 38080490,
    "created_at": "2025-06-24T09:58:48+00:00",
    "conversion": {
        "id": 28905353
    },
    "payout": null,
    "commission_type": "standard",
    "commission_name": "Standard",
    "approved": true,
    "amount": 30.55,
    "comment": "Recharged",
    "finalization_date": null,
    "conversion_sub_amount": 50.0,
    "final": false
}
```

##### Disapprove a commission

Method: DELETE\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/commissions/38080490/approved/`](https://api.tapfiliate.com/1.6/commissions/38080490/approved/)

###### URI parameters:

* **commission\_id (required) -** *Example:* `38080490`. The numeric identifier of the commission to fetch. Retrieved from the API.

The request and response bodies will be empty, as all required data will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "kind": "regular",
    "affiliate": {
        "id": "lindaquark",
        "firstname": "Linda",
        "lastname": "Quark"
    },
    "currency": "USD",
    "id": 38080490,
    "created_at": "2025-06-24T09:58:48+00:00",
    "conversion": {
        "id": 28905353
    },
    "payout": null,
    "commission_type": "standard",
    "commission_name": "Standard",
    "approved": false,
    "amount": 30.55,
    "comment": "Recharged",
    "finalization_date": null,
    "conversion_sub_amount": 50.0,
    "final": false
}
```

### Customers

* [Create a customer](#h_a4aa5593c9)
* [Retrieve a customer](#h_842f685791)
* [Update a customer](#h_b4bccdcf9f)
* [List all customers](#h_3fe5a25aa7)
* [Cancel a customer](#h_063a6cc01c)
* [Uncancel a customer](#h_0e44e5daa4)
* [Retrieve metadata](#h_7f8ea0c0cf)
* [Update (replace) metadata](#h_12b59a8f53)
* [Retrieve metadata by key](#h_4869934705)
* [Set metadata by key](#h_2da3594f55)
* [Delete metadata by key](#h_9cf222282b)
* [Delete customer](#h_185ffdcb23)

##### Create a customer

You must provide one of the following identifiers: tracking ID, referral code, click ID, coupon code, or an asset\_id and source\_id pair.\
If multiple identifiers are submitted, they will be prioritized in this order (highest to lowest): coupon code, referral code, click ID, asset\_id + source\_id, tracking ID.

Method: POST\

Endpoint URL:

```
https://api.tapfiliate.com/1.6/customers/
```

###### URI parameters:

* **override\_max\_cookie\_time (optional) -** A boolean value that defines whether your program's cookie lifetime should be overridden when creating a conversion. If set to `False`, a conversion will not be created outside the cookie lifetime; if set to `True`, a conversion will be recorded regardless of the cookie lifetime. Set to `False` by default.

###### Arguments for the request:

* **referral\_code (optional) -** An affiliate’s referral code. This corresponds to the value of `ref=` in their referral link.
* **tracking\_id (optional) -** Used if you are tracking a conversion with the help of a hybrid (REST API + JavaScript) integration.
* **click\_id (optional) -** The value that was created within the click event. If you have attached any additional information to a click event, it will also be included in the customer call response.
* **coupon (optional)** - An alternative parameter to track the conversion by (used in cases when you attribute conversions not by a referral code or a click\_id, but via the affiliate coupon value).
* **asset\_id (optional)** - Matching the `tap_a` parameter, if you are using anonymized referral links.
* **source\_id (optional)** - Matching the `tap_s` parameter, if you are using anonymized referral links.
* **customer\_id (optional)** - The ID for the current customer in your system. Depending on your program settings, this can be used for recurring / lifetime commissions. This ID must be unique for each customer.
* **meta\_data (optional)** - Metadata for this customer record, used if you need to attach additional information to customer details that is not listed within the existing parameters above.
* **status (optional)** - Sets the customer's initial status. You can read more about [statuses here](https://support.tapfiliate.com/advanced-configurations-automation/launch-plan/the-ultimate-guide-to-customers.md#customer-status). Defaults to “new” if none is passed.
* **user\_agent (optional)** - The client’s user agent string. Used for statistics and fraud detection.
* **ip (optional)** - The client’s IP address. Used for fraud detection and recording the information on the GEOs.

###### Request example:

```json theme={null}
{
  "coupon": "10OFF",
  "customer_id": "customer-SUB023",
  "status": "trial",
  "meta_data": {
    "gender": "male"
  },
  "user_agent": "Mozilla/5.0 (Windows NT 6.1; Win64; x64) AppleWebKit/537.36 (KHTML, like Gecko) Chrome/94.0.4606.85 YaBrowser/21.11.2.773 Yowser/2.5 Safari/537.36",
  "ip": "126.149.11.92"
}
```

###### Response example:

```json theme={null}
{
    "id": "cu_-cesNVckkOqi2jTgSH",
    "created_at": "2025-10-31T08:54:50+00:00",
    "click": null,
    "affiliate_meta_data": null,
    "program": {
        "id": "my-business",
        "title": "My Business",
        "currency": "USD"
    },
    "affiliate": {
        "id": "sonyanaum",
        "firstname": "Sonya",
        "lastname": "Naum"
    },
    "warnings": null,
    "meta_data": {
        "gender": "male"
    },
    "customer_id": "customer-SUB023",
    "status": "trial"
}
```

##### Retrieve a customer

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/customers/cu_-cesNVckkOqi2jTgSH/`](https://api.tapfiliate.com/1.6/customers/cu_-cesNVckkOqi2jTgSH/)

###### URI parameters:

* **id (required)** - The Tapfiliate-generated **`id`** of the Customer to act with. Does not match the Customer\_ID in your program. You can find it when creating a customer via the REST API:

  ![](https://mintcdn.com/tapfiliate-help/Q52FWBFGgBPv4--Y/images/12682358/07-image.png?fit=max\&auto=format\&n=Q52FWBFGgBPv4--Y\&q=85\&s=9050def2ac1872dfc82018a188238f9b)

The request body will be empty, as all required data will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "id": "cu_-cesNVckkOqi2jTgSH",
    "created_at": "2025-10-31T08:54:50+00:00",
    "click": null,
    "affiliate_meta_data": null,
    "program": {
        "id": "my-business",
        "title": "My Business",
        "currency": "USD"
    },
    "affiliate": {
        "id": "sonyanaum",
        "firstname": "Sonya",
        "lastname": "Naum"
    },
    "warnings": null,
    "meta_data": {
        "gender": "male"
    },
    "customer_id": "customer-SUB023",
    "status": "trial"
}
```

##### Update a customer

This method allows you to attach metadata to the customer record and update the Tapfiliate Customer\_ID.

Method: PATCH\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/customers/cu_-cesNVckkOqi2jTgSH/`](https://api.tapfiliate.com/1.6/customers/cu_-cesNVckkOqi2jTgSH/)

###### URI parameters:

* **id (required)** - The Tapfiliate-generated **`id`** of the Customer to act with. Does not match the Customer\_ID in your program. You can find it when creating a customer via the REST API.

###### Arguments:

* **customer\_id (optional)** - The ID for the current customer in your system. Depending on your program settings, this can be used for recurring / lifetime commissions. This ID must be unique for each customer.
* **meta\_data (optional)** - Metadata for this customer record, used if you need to attach additional information to customer details that is not listed within the existing parameters above.

###### Request example:

```json theme={null}
{
  "customer_id": "new_cus019",
  "meta_data": {
    "age": "19",
    "gender": "male"
  }
}
```

###### Response example:

```json theme={null}
{
    "id": "cu_-cesNVckkOqi2jTgSH",
    "created_at": "2025-10-31T08:54:50+00:00",
    "click": null,
    "affiliate_meta_data": null,
    "program": {
        "id": "my-business",
        "title": "My Business",
        "currency": "USD"
    },
    "affiliate": {
        "id": "sonyanaum",
        "firstname": "Sonya",
        "lastname": "Naum"
    },
    "warnings": null,
    "meta_data": {
        "age": "19",
        "gender": "male"
    },
    "customer_id": "new_cus019",
    "status": "trial"
}
```

##### List all customers

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/customers/?program_id=my-business&affiliate_id=craigstanford`](https://api.tapfiliate.com/1.6/customers/?program_id=my-business\&affiliate_id=craigstanford)

###### URI parameters:

* **program\_id (optional) -** *Example: my-business*. The program's ID, located in the Advanced settings.
* **customer\_id (optional)** - The ID for the current customer in your system. Depending on your program settings, this can be used for recurring / lifetime commissions. This ID must be unique for each customer.
* **affiliate\_id (optional) -** *Example: craigstanford.* The affiliate ID.
* **date\_from (optional) -** *Example: 2025-01-01*. Date From.
* **date\_to (optional) -** *Example: 2025-12-31.* Date To.

The request body will be empty, as all required data will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
"id": "cu_JN_jSFi02DhnlPf7jr",
    "created_at": "2025-10-16T12:53:37+00:00",
    "click": {
        "created_at": "2025-10-16T12:51:44+00:00",
        "referrer": "https://blogpost.com",
        "landing_page": "https://mysupersite.com/signup"
    },
    "affiliate_meta_data": {
        "qty": "4"
    },
    "program": {
        "id": "my-business",
        "title": "My Business",
        "currency": "USD"
    },
    "affiliate": {
        "id": "craigstanford",
        "firstname": "Craig",
        "lastname": "Stanford"
    },
    "meta_data": {
        "age": "45"
    },
    "customer_id": "user_017",
    "status": "new"
}, {
    "id": "cu_3Hcm4S4ENnj8R_v-BW",
    "created_at": "2025-10-08T12:31:28+00:00",
    "click": null,
    "affiliate_meta_data": null,
    "program": {
        "id": "my-business",
        "title": "My Business",
        "currency": "USD"
    },
    "affiliate": {
        "id": "craigstanford",
        "firstname": "Craig",
        "lastname": "Stanford"
    },
    "meta_data": {},
    "customer_id": "testcus_008",
    "status": "trial"
}
```

##### Cancel a customer

Method: DELETE\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/customers/cu_-cesNVckkOqi2jTgSH/status/`](https://api.tapfiliate.com/1.6/customers/cu_-cesNVckkOqi2jTgSH/status/)

The request body will be empty, as all required data will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "id": "cu_-cesNVckkOqi2jTgSH",
    "created_at": "2025-10-31T08:54:50+00:00",
    "click": null,
    "affiliate_meta_data": null,
    "program": {
        "id": "my-business",
        "title": "My Business",
        "currency": "USD"
    },
    "affiliate": {
        "id": "sonyanaum",
        "firstname": "Sonya",
        "lastname": "Naum"
    },
    "warnings": null,
    "meta_data": {
        "age": "19",
        "gender": "male"
    },
    "customer_id": "new_cus019",
    "status": "canceled"
}
```

##### Uncancel a customer

This method restores a customer's status in the program to its previous value.

Method: DELETE\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/customers/cu_-cesNVckkOqi2jTgSH/status/`](https://api.tapfiliate.com/1.6/customers/cu_-cesNVckkOqi2jTgSH/status/)

The request body will be empty, as all required data will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "id": "cu_-cesNVckkOqi2jTgSH",
    "created_at": "2025-10-31T08:54:50+00:00",
    "click": null,
    "affiliate_meta_data": null,
    "program": {
        "id": "my-business",
        "title": "My Business",
        "currency": "USD"
    },
    "affiliate": {
        "id": "sonyanaum",
        "firstname": "Sonya",
        "lastname": "Naum"
    },
    "warnings": null,
    "meta_data": {
        "age": "19",
        "gender": "male"
    },
    "customer_id": "new_cus019",
    "status": "trial"
}
```

##### Retrieve metadata

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/customers/cu_-cesNVckkOqi2jTgSH/meta-data/`](https://api.tapfiliate.com/1.6/customers/cu_-cesNVckkOqi2jTgSH/meta-data/)

###### URI parameters:

* **id (required)** - The Tapfiliate-generated **`id`** of the Customer to act with. Does not match the Customer\_ID in your program. You can find it when creating a customer via the REST API.

The request body will be empty, as all required data will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "age": "19",
    "gender": "male"
}
```

##### Update (replace) metadata

Method: PUT\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/customers/cu_-cesNVckkOqi2jTgSH/meta-data/`](https://api.tapfiliate.com/1.6/customers/cu_-cesNVckkOqi2jTgSH/meta-data/)

###### URI parameters:

* **id (required)** - The Tapfiliate-generated **`id`** of the Customer to act with. Does not match the Customer\_ID in your program. You can find it when creating a customer via the REST API.

###### Request example:

```json theme={null}
{
    "age": "23",
    "gender": "female"
}
```

Response example:

```json theme={null}
{
    "age": "23",
    "gender": "female"
}
```

##### Retrieve metadata by key

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/customers/cu_-cesNVckkOqi2jTgSH/meta-data/age/`](https://api.tapfiliate.com/1.6/customers/cu_-cesNVckkOqi2jTgSH/meta-data/age/)

###### URI parameters:

* **id (required)** - The Tapfiliate-generated **`id`** of the Customer to act with. Does not match the Customer\_ID in your program. You can find it when creating a customer via the REST API.
* **key (required) -** The metadata **`key`**.

The request body will be empty, as all required data will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "value": "23"
}
```

##### Set metadata by key

Method: PUT\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/customers/cu_-cesNVckkOqi2jTgSH/meta-data/segment/`](https://api.tapfiliate.com/1.6/customers/cu_-cesNVckkOqi2jTgSH/meta-data/segment/)

###### URI parameters:

* **id (required)** - The Tapfiliate-generated **`id`** of the Customer to act with. Does not match the Customer\_ID in your program. You can find it when creating a customer via the REST API.
* **key (required) -** *Example: segment*.The metadata **`key`**.

###### Request example:

```json theme={null}
{
    "value": "newcomers"
}
```

###### Response example:

```json theme={null}
{
    "value": "newcomers"
}
```

##### Delete metadata by key

Method: DELETE\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/customers/cu_-cesNVckkOqi2jTgSH/meta-data/segment/`](https://api.tapfiliate.com/1.6/customers/cu_-cesNVckkOqi2jTgSH/meta-data/segment/)

###### URI parameters:

* **id (required)** - The Tapfiliate-generated **`id`** of the Customer to act with. Does not match the Customer\_ID in your program. You can find it when creating a customer via the REST API.
* **key (required) -** *Example: segment*.The metadata **`key`**.

Both the request and response bodies will be empty, as all required data will be added to the request URL as query parameters. The successful request will return the `204` code.

##### Delete customer

Method: DELETE\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/customers/cu_-cesNVckkOqi2jTgSH/`](https://api.tapfiliate.com/1.6/customers/cu_-cesNVckkOqi2jTgSH/)

###### URI parameters:

* **id (required)** - The Tapfiliate-generated **`id`** of the Customer to act with. Does not match the Customer\_ID in your program. You can find it when creating a customer via the REST API.

Both the request and response bodies will be empty, as all required data will be added to the request URL as query parameters. The successful request will return the `204` code.

### Programs

* [Retrieve a program](#h_c89f11019e)
* [List all programs](#h_8974a75526)
* [List all affiliates in a program](#h_55ff012487)
* [Add an affiliate to a program](#h_1f91f1b213)
* [Retrieve an affiliate in a program](#h_9b617620e4)
* [Update an affiliate in a program](#h_3aa9050830)
* [Approve an affiliate in a program](#h_7306b31d5e)
* [Disapprove an affiliate in a program](#h_58df431ff8)
* [List program commission types](#h_4983e8e891)
* [List program MLM levels](#h_dc40f5b447)
* [List program bonuses](#h_76e553476c)

##### Retrieve a program

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/programs/my-business/`](https://api.tapfiliate.com/1.6/programs/my-business/)

###### URI parameters:

* **program\_id (required) -** *Example: my-business*. The program ID, located in your account's Advanced settings.

The request body will be empty, as all required data will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "id": "my-business",
    "currency": "USD",
    "default_landing_page_url": "https://mybusinesss.me",
    "currency_symbol": "$",
    "title": "My Business",
    "cookie_time": 45,
    "recurring": false,
    "contact_email": null,
    "program_category": null,
    "recurring_cap": null,
    "recurring_period_days": null
}
```

##### List all programs

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/programs/?asset_id=1-aaaaaa`](https://api.tapfiliate.com/1.6/programs/?asset_id=1-aaaaaa)

###### URI parameters:

* **asset\_id (optional)** - Matching the `tap_a` parameter, if you are using anonymized referral links.

The request body will be empty, as all required data will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
[{
    "id": "another-store",
    "currency": "USD",
    "default_landing_page_url": "https://anotherstore.shop",
    "currency_symbol": "$",
    "title": "Another store",
    "cookie_time": 45,
    "recurring": false,
    "contact_email": null,
    "program_category": null,
    "recurring_cap": null,
    "recurring_period_days": null
}, {
    "id": "my-business",
    "currency": "USD",
    "default_landing_page_url": "https://mybusinesss.me",
    "currency_symbol": "$",
    "title": "My Business",
    "cookie_time": 45,
    "recurring": false,
    "contact_email": null,
    "program_category": null,
    "recurring_cap": null,
    "recurring_period_days": null
}]
```

##### List all affiliates in a program

Method: GET\

Endpoint URL:

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

###### URI parameters:

* **program\_id (required) -** *Example: my-business*. The program ID, located in your account's Advanced settings.
* **source\_id (optional) -** *Example:* *8901698-f2cc9f.* An affiliate's source id.
* **email (optional) -** *Example: [jane@example-blog.inc](mailto:jane@example-blog.inc).* An affiliate's email address.
* **parent\_id (optional) -** *Example: craigstanford.* Retrieves child affiliates (MLM downline) for a particular parent affiliate.
* **affiliate\_group\_id (optional) -** *Example: ag\_eXampl3.* Retrieves affiliates for a particular affiliate group.

The request body will be empty, as all required data will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
[{
    "email": "s.naumova+29@tapfiliate.com",
    "created_at": "2025-10-29T12:21:26+00:00",
    "meta_data": {},
    "parent_id": null,
    "affiliate_group_id": null,
    "referral_link": {
        "link": "https://mybusinesss.me?ref=zwiwztl",
        "asset_id": "154981-02c363",
        "source_id": "8901698-f2cc9f"
    },
    "applied_at": "2025-10-29T12:21:27+00:00",
    "approved": true,
    "coupon": "10OFF",
    "id": "sonyanaum",
    "promoted_at": null,
    "promotion_method": null,
    "custom_fields": {
        "your-audience-size": "1k-5k"
    },
    "firstname": "Sonya",
    "lastname": "Naum",
    "company": {
        "name": "Seamless Vibes",
        "description": null
    },
    "address": {
        "address": "Test",
        "address_two": null,
        "postal_code": "440026",
        "city": "Arima",
        "state": null,
        "country": {
            "code": "EE",
            "name": "Estonia"
        }
    }
}
<...>
}]
```

##### Add an affiliate to a program

Method: POST\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/programs/another-store/affiliates/`](https://api.tapfiliate.com/1.6/programs/another-store/affiliates/)

###### URI parameters:

* **program\_id (required) -** *Example: another-store*. The program ID, located in your account's Advanced settings.
* **send\_welcome\_email (optional)** - Set to `True/False` or `1/0`. Ensures an added affiliate receives a welcome email.

###### Arguments for this API request:

* **affiliate (required)**
  * \[Child argument] **id (required)** - An affiliate's ID.
* **approved (optional)** - A boolean value that defines an affiliate's status in the program. `True` sets their status to *Approved*, `False` to *Disapproved*, and `Null` to *Pending*.
* **coupon (optional)** - An affiliate's coupon code for this program (if any is assigned).

###### Request example:

```json theme={null}
{
  "affiliate": {
    "id": "sonyanaum"
  },
  "approved": true,
  "coupon": "SALE25"
}
```

###### Response example:

```json theme={null}
{
    "email": "s.naumova+29@tapfiliate.com",
    "created_at": "2025-10-29T12:21:26+00:00",
    "meta_data": {},
    "parent_id": null,
    "affiliate_group_id": null,
    "referral_link": {
        "link": "https://anotherstore.shop?ref=zwiwztl7",
        "asset_id": "155323-a91e8e",
        "source_id": "8901698-f2cc9f"
    },
    "applied_at": "2025-10-31T10:56:30+00:00",
    "approved": true,
    "coupon": "SALE25",
    "id": "sonyanaum",
    "promoted_at": null,
    "promotion_method": null,
    "custom_fields": {
        "your-audience-size": "1k-5k"
    },
    "firstname": "Sonya",
    "lastname": "Naum",
    "company": {
        "name": "Seamless Vibes",
        "description": null
    },
    "address": {
        "address": "Test",
        "address_two": null,
        "postal_code": "440026",
        "city": "Arima",
        "state": null,
        "country": {
            "code": "EE",
            "name": "Estonia"
        }
    }
```

}

##### Retrieve an affiliate in a program

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/programs/another-store/affiliates/sonyanaum/`](https://api.tapfiliate.com/1.6/programs/another-store/affiliates/sonyanaum/)

###### URI parameters:

* **program\_id (required) -** *Example: another-store*. The program ID, located in your account's Advanced settings.
* **affiliate\_id (optional) -** *Example: sonyanaum.* The affiliate's ID in the API.

The request body will be empty, as all required data will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "email": "s.naumova+29@tapfiliate.com",
    "created_at": "2025-10-29T12:21:26+00:00",
    "meta_data": {},
    "parent_id": null,
    "affiliate_group_id": null,
    "referral_link": {
        "link": "https://anotherstore.shop?ref=zwiwztl7",
        "asset_id": "155323-a91e8e",
        "source_id": "8901698-f2cc9f"
    },
    "applied_at": "2025-10-31T10:56:30+00:00",
    "approved": true,
    "coupon": "SALE25",
    "id": "sonyanaum",
    "promoted_at": null,
    "promotion_method": null,
    "custom_fields": {
        "your-audience-size": "1k-5k"
    },
    "firstname": "Sonya",
    "lastname": "Naum",
    "company": {
        "name": "Seamless Vibes",
        "description": null
    },
    "address": {
        "address": "Test",
        "address_two": null,
        "postal_code": "440026",
        "city": "Arima",
        "state": null,
        "country": {
            "code": "EE",
            "name": "Estonia"
        }
    }
}
```

##### Update an affiliate in a program

Method: PATCH\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/programs/another-store/affiliates/sonyanaum/`](https://api.tapfiliate.com/1.6/programs/another-store/affiliates/sonyanaum/)

###### URI parameters:

* **program\_id (required) -** *Example: another-store*. The program ID, located in your account's Advanced settings.
* **affiliate\_id (optional) -** *Example: sonyanaum.* The affiliate's ID in the API.

###### Arguments for the request:

* **coupon (required)** - An affiliate's coupon code for this program.

###### Request example:

```json theme={null}
{
  "coupon": "SALE15"
}
```

###### Response example:

```json theme={null}
{
    "email": "s.naumova+29@tapfiliate.com",
    "created_at": "2025-10-29T12:21:26+00:00",
    "meta_data": {},
    "parent_id": null,
    "affiliate_group_id": null,
    "referral_link": {
        "link": "https://anotherstore.shop?ref=zwiwztl7",
        "asset_id": "155323-a91e8e",
        "source_id": "8901698-f2cc9f"
    },
    "applied_at": "2025-10-31T10:56:30+00:00",
    "approved": true,
    "coupon": "SALE15",
    "id": "sonyanaum",
    "promoted_at": null,
    "promotion_method": null,
    "custom_fields": {
        "your-audience-size": "1k-5k"
    },
    "firstname": "Sonya",
    "lastname": "Naum",
    "company": {
        "name": "Seamless Vibes",
        "description": null
    },
    "address": {
        "address": "Test",
        "address_two": null,
        "postal_code": "440026",
        "city": "Arima",
        "state": null,
        "country": {
            "code": "EE",
            "name": "Estonia"
        }
    }
}
```

##### Approve an affiliate in a program

Method: PUT\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/programs/another-store/affiliates/sonyanaum/approved`](https://api.tapfiliate.com/1.6/programs/another-store/affiliates/sonyanaum/approved)

###### URI parameters:

* **program\_id (required) -** *Example: another-store*. The program ID, located in your account's Advanced settings.
* **affiliate\_id (optional) -** *Example: sonyanaum.* The affiliate's ID in the API.

The request body will be empty, as all required data will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "email": "s.naumova+29@tapfiliate.com",
    "created_at": "2025-10-29T12:21:26+00:00",
    "meta_data": {},
    "parent_id": null,
    "affiliate_group_id": null,
    "referral_link": {
        "link": "https://anotherstore.shop?ref=zwiwztl7",
        "asset_id": "155323-a91e8e",
        "source_id": "8901698-f2cc9f"
    },
    "applied_at": "2025-10-31T10:56:30+00:00",
    "approved": true,
    "coupon": "SALE15",
    "id": "sonyanaum",
    "promoted_at": null,
    "promotion_method": null,
    "custom_fields": {
        "your-audience-size": "1k-5k"
    },
    "firstname": "Sonya",
    "lastname": "Naum",
    "company": {
        "name": "Seamless Vibes",
        "description": null
    },
    "address": {
        "address": "Test",
        "address_two": null,
        "postal_code": "440026",
        "city": "Arima",
        "state": null,
        "country": {
            "code": "EE",
            "name": "Estonia"
        }
    }
}
```

##### Disapprove an affiliate in a program

Method: DELETE\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/programs/another-store/affiliates/sonyanaum/approved`](https://api.tapfiliate.com/1.6/programs/another-store/affiliates/sonyanaum/approved)

###### URI parameters:

* **program\_id (required) -** *Example: another-store*. The program ID, located in your account's Advanced settings.
* **affiliate\_id (optional) -** *Example: sonyanaum.* The affiliate's ID in the API.

The request body will be empty, as all required data will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "email": "s.naumova+29@tapfiliate.com",
    "created_at": "2025-10-29T12:21:26+00:00",
    "meta_data": {},
    "parent_id": null,
    "affiliate_group_id": null,
    "referral_link": {
        "link": "https://anotherstore.shop?ref=zwiwztl7",
        "asset_id": "155323-a91e8e",
        "source_id": "8901698-f2cc9f"
    },
    "applied_at": "2025-10-31T10:56:30+00:00",
    "approved": false,
    "coupon": "SALE15",
    "id": "sonyanaum",
    "promoted_at": null,
    "promotion_method": null,
    "custom_fields": {
        "your-audience-size": "1k-5k"
    },
    "firstname": "Sonya",
    "lastname": "Naum",
    "company": {
        "name": "Seamless Vibes",
        "description": null
    },
    "address": {
        "address": "Test",
        "address_two": null,
        "postal_code": "440026",
        "city": "Arima",
        "state": null,
        "country": {
            "code": "EE",
            "name": "Estonia"
        }
    }
}
```

##### List program commission types

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/programs/my-business/commission-types/`](https://api.tapfiliate.com/1.6/programs/my-business/commission-types/)

###### URI parameters:

* **program\_id (required) -** *Example: my-business*. The program ID, located in your account's Advanced settings.

The request body will be empty, as all the necessary data will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
[{
    "title": "Standard",
    "commission_form": "fixed",
    "affiliate_group_overrides": [{
        "commission_form": "fixed",
        "commission_value": 50.0,
        "affiliate_group_id": "ag_8jxwhHQEXOm_fgJPoK"
    }],
    "identifier": "standard",
    "commission_value": 10.0,
    "recurrence": "monthly",
    "visible": true,
    "count_towards_cap": true
}, {
    "title": "Additional",
    "commission_form": "fixed",
    "affiliate_group_overrides": [],
    "identifier": "boyjacket",
    "commission_value": 5.0,
    "recurrence": "once",
    "visible": true,
    "count_towards_cap": true
}, {
    "title": "Donation",
    "commission_form": "fixed",
    "affiliate_group_overrides": [],
    "identifier": "frienddonation",
    "commission_value": 3.0,
    "recurrence": "once",
    "visible": true,
    "count_towards_cap": true
}]
```

##### List program MLM levels

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/programs/my-business/levels/`](https://api.tapfiliate.com/1.6/programs/my-business/levels/)

###### URI parameters:

* **program\_id (required) -** *Example: my-business*. The program ID, located in your account's Advanced settings.

The request body will be empty, as all the necessary data will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
[{
    "title": "Level 2",
    "commission_form": "fixed",
    "identifier": "level-2",
    "commission_value": 10.0
}, {
    "title": "Level 3",
    "commission_form": "fixed",
    "identifier": "level-3",
    "commission_value": 5.0
}]
```

##### List program bonuses

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/programs/my-business/bonuses/`](https://api.tapfiliate.com/1.6/programs/my-business/bonuses/)

###### URI parameters:

* **program\_id (required) -** *Example: my-business*. The program ID, located in your account's Advanced settings.

The request body will be empty, as all the necessary data will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
[{
    "title": "New bonus",
    "commission_form": "fixed",
    "identifier": "new-bonus-1",
    "interval": "calmo",
    "target_type": "conversion_amount_sum",
    "active": true,
    "start_date": null,
    "end_date": null
}]
```

### Payments

* [List all balances](#h_ba973f8126)
* [List all payments](#h_e93dfb741d)
* [Retrieve a payment](#h_9570916a26)
* [Create a payment](#h_87686725d3)
* [Cancel a payment](#h_1ba1ccef99)

##### List all balances

This endpoint creates a list of affiliates' current balances in your Tapfiliate account.

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/balances/`](https://api.tapfiliate.com/1.6/balances/)

The request body will be empty, as all necessary data will be included in the request URL as query parameters.

###### Response example:

```json theme={null}
[{
    "affiliate_id": "ritabailando",
    "balances": {
        "USD": 25.0
    }
}, {
    "affiliate_id": "jonahsamuelsonjr",
    "balances": {
        "USD": 25.0
    }
}, {
    "affiliate_id": "craigstanford",
    "balances": {
        "USD": 25.0
    }
}, {
    "affiliate_id": "lindaquark",
    "balances": {
        "USD": -8.0
    }
}]
```

##### List all payments

Method: GET\
Endpoint URL: [`https://api.tapfiliate.com/1.6/payments`](https://api.tapfiliate.com/1.6/payments)

The request body will be empty, as all necessary data will be included in the request URL as query parameters.

###### Response example:

```json theme={null}
[{
    "id": "pa_uPf_7LmUe2gommWYbA",
    "created_at": "2025-10-16T12:43:04+00:00",
    "affiliate": {
        "id": "lindaquark",
        "firstname": "Linda",
        "lastname": "Quark"
    },
    "amount": 15.0,
    "currency": "USD"
}, {
    "id": "pa_qcKriu40sXt947aLxX",
    "created_at": "2025-10-02T10:47:47+00:00",
    "affiliate": {
        "id": "ritabailando",
        "firstname": "Rita",
        "lastname": "Bailando"
    },
<...>
}]
```

##### Retrieve a payment

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/payments/pa_uPf_7LmUe2gommWYbA/`](https://api.tapfiliate.com/1.6/payments/pa_uPf_7LmUe2gommWYbA/)

###### URI parameters:

* **id (required)** - *Example: pa\_uPf\_7LmUe2gommWYbA.* The ID of the current payment.

The request body will be empty, as all necessary data will be included in the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "id": "pa_uPf_7LmUe2gommWYbA",
    "created_at": "2025-10-16T12:43:04+00:00",
    "affiliate": {
        "id": "lindaquark",
        "firstname": "Linda",
        "lastname": "Quark"
    },
    "amount": 15.0,
    "currency": "USD"
}
```

##### Create a payment

Method: POST\

Endpoint:\

[`https://api.tapfiliate.com/1.6/payments/`](https://api.tapfiliate.com/1.6/payments/)

###### Request example:

```json theme={null}
{
  "affiliate_id": "ritabailando",
  "amount": 100,
  "currency": "USD"
}
```

###### Response example:

```json theme={null}
[{
    "id": "pa_AeKrm0KUyLh09cOVCl",
    "created_at": "2025-10-31T13:15:05+00:00",
    "affiliate": {
        "id": "ritabailando",
        "firstname": "Rita",
        "lastname": "Bailando"
    },
    "amount": 100.0,
    "currency": "USD"
}]
```

##### Cancel a payment

Method: DELETE\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/payments/pa_AeKrm0KUyLh09cOVCl`](https://api.tapfiliate.com/1.6/payments/pa_AeKrm0KUyLh09cOVCl)

###### URI parameters:

* **id (required)** - *Example: pa\_AeKrm0KUyLh09cOVCl.* The ID of the current payment.

Both the request and response bodies will be empty, as all required data will be added to the request URL as query parameters. The successful request will return the `204` code.

### Affiliates

* [Create an affiliate](#h_41e0a12441)
* [Retrieve an affiliate](#h_eb00c1921f)
* [Delete an affiliate](#h_636ae5fe6c)
* [List all affiliates](#h_a5c2e29252)
* [Set affiliate group](#h_57081f85fe)
* [Remove the affiliate from a group](#h_4be73dd117)
* [Create a note for an affiliate](#h_0620a20b64)
* [Update note](#h_ab2fea9d1b)
* [List notes](#h_ef3216ab47)
* [Delete note](#h_b48f219cfd)
* [Set affiliate metadata by key](#h_52e0cd91d6)
* [Retrieve metadata by key](#h_cd1b37530a)
* [Delete metadata by key](#h_1aecac234e)
* [Retrieve metadata](#h_d4c689b574)
* [Update (replace) metadata](#h_7cda647a3b)
* [Set the affiliate payout method](#h_3dad60f1b3)
* [Get the affiliate's payout method](#h_1b5a9486d3)
* [List the affiliate's payout methods](#h_ef1b5eaf9a)
* [Retrieve an affiliate's balance](#h_a569d106d4)
* [List an affiliate's payments](#h_bef76fd92b)
* [Set a parent to an affiliate](#h_ebd2b11d41)
* [Remove parent affiliate](#h_b2371aa895)
* [Get affiliations](#h_54ec90de6c)
* [Get affiliate's custom fields](#h_7e4dc167ec)

##### Create an affiliate

At this point, the `affiliate id` will be created. As long as an affiliate is created, but not yet part of any program, **they will be archived**. To add an affiliate to a program, please use [the respective endpoint](#h_1f91f1b213).

Method: POST\
Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliates/`](https://api.tapfiliate.com/1.6/affiliates/)

###### Arguments for this API request:

* **firstname** **(required) -** The affiliate’s first name.
* **lastname** **(required)** *-* The affiliate’s last name.
* **email** **(required)** *-* The affiliate’s email address.
* **password** **(optional)** *-* Password for the new affiliate. If not provided, a password is automatically generated and returned in the response.
* **company** **(optional) -** Company information for the affiliate.\
  **Child fields:**
  * **name** **(optional)** - Company name
* **address** **(optional)** *-* Affiliate’s address details\
  **Child fields:**
  * **address** **(required)** *-* Street address
  * **postal\_code** **(required) -** Postal / ZIP code
  * **city** **(required)** *-* City
  * **state** **(optional) -** State/region
  * **country** **(required)** *-* Country details\
    **Child fields:**
    * **code** **(required)** *-* ISO-3166-1 country code (e.g., “US”, “NL”)
* **custom\_fields** **(optional)** *-* Key/value pairs for custom affiliate fields.

###### Request example:

```json theme={null}
{
  "firstname": "Rusty",
  "lastname": "Goodson",
  "email": "rusty@referra.com",
  "password": "password1234",
  "company": {
    "name": "Goodson and Co., Inc."
  },
  "address": {
    "address": "Rapenburgerstraat 173",
    "postal_code": "1011 VM",
    "city": "Amsterdam",
    "state": "Noord-Holland",
    "country": {
      "code": "NL"
    }
  }
}
```

###### Response example:

```json theme={null}
{
    "email": "rusty@referra.com",
    "password": null,
    "created_at": "2025-10-31T13:27:37+00:00",
    "meta_data": {},
    "parent_id": null,
    "affiliate_group_id": null,
    "id": "rustygoodson",
    "promoted_at": null,
    "promotion_method": null,
    "custom_fields": null,
    "firstname": "Rusty",
    "lastname": "Goodson",
    "company": {
        "name": "Goodson and Co., Inc.",
        "description": null
    },
    "address": {
        "address": "Rapenburgerstraat 173",
        "address_two": null,
        "postal_code": "1011 VM",
        "city": "Amsterdam",
        "state": "Noord-Holland",
        "country": {
            "code": "NL",
            "name": "Netherlands"
        }
    }
}
```

##### Retrieve an affiliate

Method: GET\
Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliates/rustygoodson/`](https://api.tapfiliate.com/1.6/affiliates/rustygoodson/)

###### URI parameters:

* **affiliate\_id (required) -** *Example: rustygoodson.* The affiliate ID.

The request body will be empty, as all required parameters will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "email": "rusty@referra.com",
    "created_at": "2025-10-31T13:27:37+00:00",
    "meta_data": {},
    "parent_id": null,
    "affiliate_group_id": null,
    "id": "rustygoodson",
    "promoted_at": null,
    "promotion_method": null,
    "custom_fields": null,
    "firstname": "Rusty",
    "lastname": "Goodson",
    "company": {
        "name": "Goodson and Co., Inc.",
        "description": null
    },
    "address": {
        "address": "Rapenburgerstraat 173",
        "address_two": null,
        "postal_code": "1011 VM",
        "city": "Amsterdam",
        "state": "Noord-Holland",
        "country": {
            "code": "NL",
            "name": "Netherlands"
        }
    }
}
```

##### Delete an affiliate

Method: DELETE\
Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliates/rustygoodson/`](https://api.tapfiliate.com/1.6/affiliates/rustygoodson/)

###### URI parameters:

* **affiliate\_id (required) -** *Example: rustygoodson.* The affiliate ID.

Both the request and response bodies will be empty, as all required data will be added to the request URL as query parameters. The successful request will return the `204` code.

##### List all affiliates

This endpoint returns all affiliates that match the parameters specified in the request URL.

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliates/?referral_code=mmu0zdy&parent_id=lindaquark/`](https://api.tapfiliate.com/1.6/affiliates/?referral_code=mmu0zdy\&parent_id=lindaquark/)

###### URI parameters:

* **click\_id (optional) -** The value that was created within the click event and stores the visitor's data.
* **email (optional)** - An affiliate's email address.
* **source\_id (optional)** - Matching the `tap_s` parameter, if you are using anonymized referral links.
* **referral\_code (optional) -** *Example: mmu0zdy.* An affiliate’s referral code. This corresponds to the value of **`ref=`** in their referral link.
* **parent\_id (optional) -** *Example: lindaquark.* Retrieves child affiliates for a certain parent affiliate.
* **affiliate\_group\_id (optional) -** *Example: ag\_77WCDy90IMs8m-sXpo.* Retrieves affiliates for a particular affiliate group.

The request body will be empty, as all required data will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
[{
    "email": "rita@sample.com",
    "created_at": "2025-06-24T10:05:36+00:00",
    "meta_data": {},
    "parent_id": "lindaquark",
    "affiliate_group_id": "ag_8jxwhHQEXOm_fgJPoK",
    "id": "ritabailando",
    "promoted_at": null,
    "promotion_method": null,
    "custom_fields": {
        "your-audience-size": "1k-5k"
    },
    "firstname": "Rita",
    "lastname": "Bailando",
    "company": {
        "name": "Baile Music, Inc.",
        "description": "Number one music production across the whole LATAM region"
    },
    "address": {
        "address": "Rio Branco 173",
        "address_two": null,
        "postal_code": "69914220",
        "city": "Rio Branco",
        "state": "Acre",
        "country": {
            "code": "BR",
            "name": "Brazil"
        }
    }
}]
```

##### Set affiliate group

Method: PUT\
Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliates/rustygoodson/group/`](https://api.tapfiliate.com/1.6/affiliates/rustygoodson/group/)

###### URI parameters:

* **affiliate\_id (required) -** *Example: rustygoodson.* The affiliate ID.

###### Arguments:

* **group\_id (required)** - The identifier of an affiliate group, can be found in your *Programs > Affiliate Groups* section.

###### Request example:

```json theme={null}
{
  "group_id": "ag_77WCDy90IMs8m-sXpo"
}
```

###### Response example:

```json theme={null}
{
    "email": "rusty@referra.com",
    "created_at": "2025-10-31T13:27:37+00:00",
    "meta_data": {},
    "parent_id": null,
    "affiliate_group_id": "ag_77WCDy90IMs8m-sXpo",
    "id": "rustygoodson",
    "promoted_at": null,
    "promotion_method": null,
    "custom_fields": null,
    "firstname": "Rusty",
    "lastname": "Goodson",
    "company": {
        "name": "Goodson and Co., Inc.",
        "description": null
    },
    "address": {
        "address": "Rapenburgerstraat 173",
        "address_two": null,
        "postal_code": "1011 VM",
        "city": "Amsterdam",
        "state": "Noord-Holland",
        "country": {
            "code": "NL",
            "name": "Netherlands"
        }
    }
}
```

##### Remove the affiliate from a group

Unassigns an affiliate from a group in your Tapfiliate program.

Method: DELETE\
Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliates/rustygoodson/group/`](https://api.tapfiliate.com/1.6/affiliates/rustygoodson/group/)

###### URI parameters:

* **affiliate\_id (required) -** *Example: rustygoodson.* The affiliate ID.

Both the request and response bodies will be empty, as all required data will be added to the request URL as query parameters. The successful request will return the `204` code.

##### Create a note for an affiliate

Method: POST\
Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliates/rustygoodson/notes/`](https://api.tapfiliate.com/1.6/affiliates/rustygoodson/notes/)

###### URI parameters:

* ###### affiliate\_id (required) - *Example: rustygoodson.* The affiliate ID.

###### Arguments for the request:

* **message (required)** - A note to add to an affiliate profile.

###### Request example:

```json theme={null}
{
  "message": "150 USD owed"
}
```

###### Response example:

```json theme={null}
{
    "id": 49225,
    "created_at": "2025-10-31T13:46:28+00:00",
    "message": "150 USD owed",
    "created_by": {
        "id": "sofya",
        "firstname": "Sofya",
        "lastname": "Naumova"
    }
}
```

##### Update note

Method: PUT\
Endpoint URL:\

[https://api.tapfiliate.com/1.6/affiliates/rustygoodson/notes/49225/](https://api.tapfiliate.com/1.6/affiliates/rustygoodson/notes/49225/)

###### URI parameters:

* **affiliate\_id (required) -** *Example: rustygoodson.* The affiliate ID.
* **id (required)** - A note ID.

###### Arguments for the request:

* **message (required)** - A note to add to an affiliate profile.

###### Request example:

```json theme={null}
{
  "message": "180 USD owed"
}
```

###### Response example:

```json theme={null}
{
    "id": 49225,
    "created_at": "2025-10-31T13:46:28+00:00",
    "message": "180 USD owed",
    "created_by": {
        "id": "sofya",
        "firstname": "Sofya",
        "lastname": "Naumova"
    }
}
```

##### List notes

Method: GET\
Endpoint URL:\

[https://api.tapfiliate.com/1.6/affiliates/rustygoodson/notes/](https://api.tapfiliate.com/1.6/affiliates/rustygoodson/notes/)

###### URI parameters:

* **affiliate\_id (required) -** *Example: rustygoodson.* The affiliate ID.

The request body will be empty, as all required parameters will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
[{
    "id": 49225,
    "created_at": "2025-10-31T13:46:28+00:00",
    "message": "180 USD owed",
    "created_by": {
        "id": "sofya",
        "firstname": "Sofya",
        "lastname": "Naumova"
    }
}]
```

##### Delete note

Method: DELETE\
Endpoint URL:\

[https://api.tapfiliate.com/1.6/affiliates/rustygoodson/notes/49225/](https://api.tapfiliate.com/1.6/affiliates/rustygoodson/notes/49225/)

###### URI parameters:

* **affiliate\_id (required) -** *Example: rustygoodson.* The affiliate ID.
* **id (required)** - A note ID.

Both the request and response bodies will be empty, as all required data will be added to the request URL as query parameters. The successful request will return the `204` code.

##### Set affiliate metadata by key

Method: PUT\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliates/rustygoodson/meta-data/traffic_source/`](https://api.tapfiliate.com/1.6/affiliates/rustygoodson/meta-data/traffic_source/)

###### URI parameters:

* **affiliate\_id (required) -** *Example: rustygoodson.* The affiliate ID.
* **key (required)** - the metadata key. This key will sort the information in the API response.

###### Request example:

```json theme={null}
{
    "value": "content_website"
}
```

###### Response example:

```json theme={null}
{
    "value": "content_website"
}
```

##### Retrieve metadata by key

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliates/rustygoodson/meta-data/traffic_source/`](https://api.tapfiliate.com/1.6/affiliates/rustygoodson/meta-data/traffic_source/)

###### URI parameters:

* **affiliate\_id (required) -** *Example: rustygoodson.* The affiliate ID.
* **key (required)** - the metadata key. This key will sort the information in the API response.

The request body will be empty, as all required parameters will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "value": "content_website"
}
```

##### Delete metadata by key

Method: DELETE\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliates/rustygoodson/meta-data/traffic_source/`](https://api.tapfiliate.com/1.6/affiliates/rustygoodson/meta-data/traffic_source/)

###### URI parameters:

* **affiliate\_id (required) -** *Example: rustygoodson.* The affiliate ID.
* **key (required)** - the metadata key.

Both the request and response bodies will be empty, as all required data will be added to the request URL as query parameters. The successful request will return the `204` code.

##### Retrieve metadata

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliates/`](https://api.tapfiliate.com/1.6/affiliates/)*`jonahsamuelsonjr`*`/meta-data/`

###### URI parameters:

* **affiliate\_id (required) -** *Example: jonahsamuelsonjr.* The affiliate ID.

The request body will be empty, as all required parameters will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "store": "Store1"
}
```

##### Update (replace) metadata

Method: PUT\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliates/jonahsamuelsonjr/meta-data/`](https://api.tapfiliate.com/1.6/affiliates/jonahsamuelsonjr/meta-data/)

###### URI parameters:

* **affiliate\_id (required) -** *Example: jonahsamuelsonjr.* The affiliate ID.

###### Arguments for this request:

* **metadata (required)** - You will have to add a key and a value for this metadata object.

###### Request example:

```json theme={null}
{
    "store": "New Store 456"
}
```

###### Response example:

```json theme={null}
{
    "store": "New Store 456"
}
```

##### Set the affiliate payout method

Method: PUT\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliates/ritabailando/payout-methods/paypal/`](https://api.tapfiliate.com/1.6/affiliates/ritabailando/payout-methods/paypal/)

###### URI parameters:

* **affiliate\_id (required) -** *Example: ritabailando.* The affiliate ID.
* **payout\_method\_id (required)** - The identifier of the payment method.

###### Arguments for this API request:

* **payout method type (required)** - Added based on the payout method. Example: for PayPal, you'll need the `paypal_address` parameter.

###### Request example:

```json theme={null}
{
  "paypal_address": "rita@example-blog.com"
}
```

###### Response example:

```json theme={null}
{
    "title": "Paypal",
    "id": "paypal",
    "details": {
        "paypal_address": "rita@example-blog.com"
    },
    "primary": null
}
```

##### Get the affiliate's payout method

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliates/ritabailando/payout-methods/paypal/`](https://api.tapfiliate.com/1.6/affiliates/ritabailando/payout-methods/paypal/)

###### URI parameters:

* **affiliate\_id (required) -** *Example: ritabailando.* The affiliate ID.
* **payout\_method\_id (required)** - The identifier of the payment method.

The request body will be empty, as all required parameters will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "title": "Paypal",
    "id": "paypal",
    "details": {
        "paypal_address": "rita@example-blog.com"
    },
    "primary": null
}
```

##### List the affiliate's payout methods

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliates/ritabailando/payout-methods/`](https://api.tapfiliate.com/1.6/affiliates/ritabailando/payout-methods/)

###### URI parameters:

* **affiliate\_id (required) -** *Example: ritabailando.* The affiliate ID.

The request body will be empty, as all required parameters will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "title": "Paypal",
    "id": "paypal",
    "details": {
        "paypal_address": "rita@example-blog.com"
    },
    "primary": null
}
```

##### Retrieve an affiliate's balance

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliates/ritabailando/balances/`](https://api.tapfiliate.com/1.6/affiliates/ritabailando/balances/)

###### URI parameters:

* **affiliate\_id (required) -** *Example: ritabailando.* The affiliate ID.

The request body will be empty, as all required parameters will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "USD": 151.75
}
```

##### List an affiliate's payments

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliates/ritabailando/payments/`](https://api.tapfiliate.com/1.6/affiliates/ritabailando/payments/)

###### URI parameters:

* **affiliate\_id (required) -** *Example: ritabailando.* The affiliate ID.

The request body will be empty, as all required parameters will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
[{
    "id": "pa_qcKriu40sXt947aLxX",
    "created_at": "2025-10-02T10:47:47+00:00",
    "affiliate": {
        "id": "ritabailando",
        "firstname": "Rita",
        "lastname": "Bailando"
    },
    "amount": 20.0,
    "currency": "USD"
}, {
    "id": "pa_4DotQQ6EAXovttmpHp",
    "created_at": "2025-08-14T14:18:08+00:00",
    "affiliate": {
        "id": "ritabailando",
        "firstname": "Rita",
        "lastname": "Bailando"
    },
    "amount": 15.0,
    "currency": "USD"
}, {
    "id": "pa_hxl6X-kUKchA1RHlRK",
    "created_at": "2025-07-28T13:36:02+00:00",
    "affiliate": {
        "id": "ritabailando",
        "firstname": "Rita",
        "lastname": "Bailando"
    },
    "amount": 25.0,
    "currency": "USD"
}]
```

##### Set a parent to an affiliate

Method: POST\

Endpoint URL:\

[https://api.tapfiliate.com/1.6/affiliates/sonyanaum/parent/](https://api.tapfiliate.com/1.6/affiliates/sonyanaum/parent/)

###### URI parameters:

* **child\_affiliate\_id (required) -** *Example: sonyanaum.* The affiliate ID.

###### Arguments for this API request:

* **affiliate\_id (optional) -** The affiliate **`id`** of the parent affiliate.

###### Request example:

```json theme={null}
{
  "affiliate_id": "lindaquark"
}
```

###### Response example:

```json theme={null}
{
    "email": "s.naumova+29@tapfiliate.com",
    "created_at": "2025-10-29T12:21:26+00:00",
    "meta_data": {},
    "parent_id": "lindaquark",
    "affiliate_group_id": null,
    "id": "sonyanaum",
    "promoted_at": null,
    "promotion_method": null,
    "custom_fields": {
        "your-audience-size": "1k-5k"
    },
    "firstname": "Sonya",
    "lastname": "Naum",
    "company": {
        "name": "Seamless Vibes",
        "description": null
    },
    "address": {
        "address": "Test",
        "address_two": null,
        "postal_code": "440026",
        "city": "Arima",
        "state": null,
        "country": {
            "code": "EE",
            "name": "Estonia"
        }
    }
}
```

##### Remove parent affiliate

Method: DELETE\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliates/sonyanaum/parent/`](https://api.tapfiliate.com/1.6/affiliates/sonyanaum/parent/)

###### URI parameters:

* **child\_affiliate\_id (required) -** *Example: sonyanaum.* The affiliate ID.

Both the request and response bodies will be empty, as all required data will be added to the request URL as query parameters. The successful request will return the `204` code.

##### Get affiliations

This endpoint retrieves a list of programs to which a given affiliate is (or has been) affiliated.

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliates/lindaquark/programs/`](https://api.tapfiliate.com/1.6/affiliates/lindaquark/programs/)

###### URI parameters:

* **affiliate\_id (required) -** *Example: lindaquark.* The affiliate ID.

The request body will be empty, as all required parameters will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
[{
    "applied_at": "2025-06-11T07:57:56+00:00",
    "assets_amount": 3,
    "title": "My Business",
    "id": "my-business",
    "referral_link": {
        "link": "https://mybusinesss.me?ref=zjk1owi",
        "asset_id": "154981-02c363",
        "source_id": "8085961-53cdeb"
    },
    "approved": true,
    "coupon": "TEST10"
}, {
    "applied_at": "2025-06-23T14:59:30+00:00",
    "assets_amount": 3,
    "title": "Another store",
    "id": "another-store",
    "referral_link": {
        "link": "https://anotherstore.shop?ref=zjk1owi7",
        "asset_id": "155323-a91e8e",
        "source_id": "8085961-53cdeb"
    },
    "approved": true,
    "coupon": null
}]
```

##### Get affiliates' custom fields

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliates/custom-fields/`](https://api.tapfiliate.com/1.6/affiliates/custom-fields/)

The API request body will be empty, as no URI parameters or arguments are required for this endpoint.

###### Response example:

```json theme={null}
[{
    "id": "your-audience-size",
    "title": "Your audience size",
    "choices": ["0-1k", "1k-5k", "5k+"]
}]
```

### Affiliate Groups

* [Create a new affiliate group](#h_f76061497d)
* [List all affiliate groups](#h_89f565c25a)
* [Update an affiliate group](#h_58433551c2)

##### Create a new affiliate group

Method: POST\
Endpoint URL:\

[https://api.tapfiliate.com/1.6/affiliate-groups/](https://api.tapfiliate.com/1.6/affiliate-groups/)

###### Arguments:

* **title (required)** - A name for your new affiliate group.

###### Request example:

```json theme={null}
{
  "title": "Creators"
}
```

###### Response example:

```json theme={null}
{
    "id": "ag_pltAn3i0itr8x6psCp",
    "title": "Creators",
    "affiliate_count": 0
}
```

##### List all affiliate groups

Method: GET\
Endpoint URL:\

[https://api.tapfiliate.com/1.6/affiliate-groups/](https://api.tapfiliate.com/1.6/affiliate-groups/)

The request body will be empty, as all required parameters will be added to the request URL as query parameters.

###### Response example:\[\{

```
    "id": "ag_pltAn3i0itr8x6psCp",
    "title": "Creators",
    "affiliate_count": 0
}, {
    "id": "ag_77WCDy90IMs8m-sXpo",
    "title": "Small influencers",
    "affiliate_count": 0
}, {
    "id": "ag_8jxwhHQEXOm_fgJPoK",
    "title": "VIP",
    "affiliate_count": 2
}]
```

##### Update an affiliate group

Allows changing the group title.

Method: PATCH\
Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliate-groups/ag_8jxwhHQEXOm_fgJPoK/`](https://api.tapfiliate.com/1.6/affiliate-groups/ag_8jxwhHQEXOm_fgJPoK/)

###### URI parameters:

* **affiliate\_group\_id (optional) -** *Example: ag\_8jxwhHQEXOm\_fgJPoK*. Retrieves affiliates for a specific affiliate group.

###### Arguments for this API request:

* **title (required)** - The new name of an affiliate group.

###### Request example:

```json theme={null}
{
  "title": "Big players"
}
```

###### Response example:

```json theme={null}
{
    "id": "ag_8jxwhHQEXOm_fgJPoK",
    "title": "Big players",
    "affiliate_count": 2
}
```

### Affiliate Prospects

* [Create an affiliate prospect](#h_3f5dd09d64)
* [Retrieve an affiliate prospect](#h_5a9801fcc5)
* [List all affiliate prospects](#h_bc1dd71029)
* [Delete an affiliate prospect](#h_18571f34f6)

##### Create an affiliate prospect

Method: POST\
Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliate-prospects/`](https://api.tapfiliate.com/1.6/affiliate-prospects/)

###### Arguments for this API call:

* **firstname** **(required)** *-* The affiliate prospect’s first name.
* **lastname** **(required)** *-* The affiliate prospect’s last name.
* **email** **(optional)** *-* The affiliate’s email address.
* **company** **(optional)** *-* The affiliate prospect’s company data.
  * **name** **(optional)** *-* Company name.
* **address** **(optional)** *-* The affiliate prospect’s address.
  * **address** **(required)** *-* Street address.
  * **postal\_code** **(required)** *-* Postal/ZIP code.
  * **city** **(required)** *-* City.
  * **state** **(optional)** *-* State/region (e.g., Holland).
  * **country** **(required)** *-* Country details.
    * **code** **(required)** *-* ISO-3166-1 country code (e.g., “US”, “NL”).
* **program\_id** **(optional)** *-* The program to add the affiliate prospect to; if none is provided, the prospect is added to the default program.
* **affiliate\_group\_id** **(optional)** *-* The affiliate group to assign the affiliate prospect to.

###### Request example:

```json theme={null}
{
  "firstname": "Peter",
  "lastname": "Laneil",
  "email": "peter@example.com",
  "company": {
    "name": "Tapfiliate"
  },
  "address": {
    "address": "Bronkbond 75",
    "postal_code": "440000",
    "city": "Amsterdam",
    "state": "Noord",
    "country": {
      "code": "NL"
    }
  },
  "program_id": "my-business",
  "affiliate_group_id": "ag_pltAn3i0itr8x6psCp"
}
```

###### Response example:

```json theme={null}
{
    "email": "peter@example.com",
    "created_at": "2025-10-31T16:05:30+00:00",
    "referral_link": {
        "link": "https://mybusinesss.me?ref=mgnmztr",
        "asset_id": "154981-02c363",
        "source_id": "8917802-368684"
    },
    "id": "peterlaneil",
    "promoted_at": null,
    "promotion_method": null,
    "firstname": "Peter",
    "lastname": "Laneil",
    "company": {
        "name": "Tapfiliate",
        "description": null
    },
    "address": {
        "address": "Bronkbond 75",
        "address_two": null,
        "postal_code": "440000",
        "city": "Amsterdam",
        "state": "Noord",
        "country": {
            "code": "NL",
            "name": "Netherlands"
        }
    },
    "signup_source": "by-advertiser-api"
}
```

##### Retrieve an affiliate prospect

Method: GET\

Endpoint URL:\

[https://api.tapfiliate.com/1.6/affiliate-prospects/peterlaneil/](https://api.tapfiliate.com/1.6/affiliate-prospects/peterlaneil/)

###### URI parameters:

* **affiliate\_prospect\_id (required)** - An identifier of an affiliate prospect.

The request body will be empty, as all the necessary data will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
{
    "email": "peter@example.com",
    "created_at": "2025-10-31T16:05:30+00:00",
    "referral_link": {
        "link": "https://mybusinesss.me?ref=mgnmztr",
        "asset_id": "154981-02c363",
        "source_id": "8917802-368684"
    },
    "id": "peterlaneil",
    "promoted_at": null,
    "promotion_method": null,
    "firstname": "Peter",
    "lastname": "Laneil",
    "company": {
        "name": "Tapfiliate",
        "description": null
    },
    "address": {
        "address": "Bronkbond 75",
        "address_two": null,
        "postal_code": "440000",
        "city": "Amsterdam",
        "state": "Noord",
        "country": {
            "code": "NL",
            "name": "Netherlands"
        }
    },
    "signup_source": "by-advertiser-api"
}
```

##### List all affiliate prospects

Method: GET\

Endpoint URL:\

[`https://api.tapfiliate.com/1.6/affiliate-prospects/?email=peter@example.com&referral_code=mgnmztr&program_id=my-business`](https://api.tapfiliate.com/1.6/affiliate-prospects/?email=peter@example.com\&referral_code=mgnmztr\&program_id=my-business)

###### URI parameters:

* **email (optional) -** *Example: [peter@example.com](mailto:peter@example.com)*. An email address of an affiliate prospect.
* **referral\_code (optional) -** *Example: mgnmztr.* An affiliate prospect’s referral code. This corresponds to the value of **`ref=`** in their referral link.
* **program\_id (optional) -** *Example: my-business.* Retrieves affiliate prospects for a particular program.
* **group\_id (optional) -** Retrieves affiliate prospects for a certain affiliate group.

The request body will be empty, as all the necessary data will be added to the request URL as query parameters.

###### Response example:

```json theme={null}
[{
    "email": "peter@example.com",
    "created_at": "2025-10-31T16:05:30+00:00",
    "referral_link": {
        "link": "https://mybusinesss.me?ref=mgnmztr",
        "asset_id": "154981-02c363",
        "source_id": "8917802-368684"
    },
    "id": "peterlaneil",
    "promoted_at": null,
    "promotion_method": null,
    "firstname": "Peter",
    "lastname": "Laneil",
    "company": {
        "name": "Tapfiliate",
        "description": null
    },
    "address": {
        "address": "Bronkbond 75",
        "address_two": null,
        "postal_code": "440000",
        "city": "Amsterdam",
        "state": "Noord",
        "country": {
            "code": "NL",
            "name": "Netherlands"
        }
    },
    "signup_source": "by-advertiser-api"
}]
```

##### Delete an affiliate prospect

Method: DELETE\

Endpoint URL:\

[https://api.tapfiliate.com/1.6/affiliate-prospects/peterlaneil/](https://api.tapfiliate.com/1.6/affiliate-prospects/peterlaneil/)

###### URI parameters:

* **affiliate\_prospect\_id (required)** - An identifier of an affiliate prospect.

Both the request and response bodies will be empty, as all required data will be added to the request URL as query parameters. The successful request will return the `204` code.

***

**Still need help?**\
If you have any questions or if something in this guide is unclear, please don't hesitate to **contact us at [support@tapfiliate.com](mailto:support@tapfiliate.com)**—we're happy to assist!


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.