Tapfiliate REST API
REST API for managing affiliate programs, affiliates, conversions, commissions, customers, payments, and click tracking. Base URL is https://api.tapfiliate.com/1.6/ and authentication is via the X-Api-Key header.
REST API for managing affiliate programs, affiliates, conversions, commissions, customers, payments, and click tracking. Base URL is https://api.tapfiliate.com/1.6/ and authentication is via the X-Api-Key header.
openapi: 3.0.3
info:
title: Tapfiliate REST API
description: >-
Tapfiliate is an affiliate tracking and management platform. This REST API
allows you to create and manage affiliate programs, track conversions,
manage affiliates, handle commission payouts, and record clicks. The API
is versioned at V1.6 and uses API key authentication via the X-Api-Key header.
version: "1.6"
contact:
name: Tapfiliate Support
url: https://tapfiliate.com/docs/rest/
termsOfService: https://tapfiliate.com/terms/
servers:
- url: https://api.tapfiliate.com/1.6
description: Tapfiliate REST API v1.6
security:
- ApiKeyAuth: []
tags:
- name: Customers
description: Manage customers and their metadata
- name: Conversions
description: Track and manage conversions and commissions
- name: Commissions
description: Manage individual commissions
- name: Affiliates
description: Manage affiliates, their groups, notes, and payout methods
- name: Affiliate Groups
description: Manage affiliate groups
- name: Affiliate Prospects
description: Manage affiliate prospects (pending applicants)
- name: Programs
description: Manage affiliate programs and program affiliates
- name: Balances
description: View affiliate balances
- name: Payments
description: Manage affiliate payments
- name: Clicks
description: Track and manage clicks
paths:
/customers/{id}/:
get:
operationId: getCustomer
summary: Retrieve a Customer
description: Retrieve a single customer by their ID.
tags:
- Customers
parameters:
- $ref: '#/components/parameters/customerId'
responses:
"200":
description: Customer retrieved successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
patch:
operationId: updateCustomer
summary: Update a Customer
description: Update an existing customer's data.
tags:
- Customers
parameters:
- $ref: '#/components/parameters/customerId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
customer_id:
type: string
description: The external customer identifier
meta_data:
type: object
additionalProperties: true
description: Arbitrary metadata for this customer
responses:
"200":
description: Customer updated successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteCustomer
summary: Delete a Customer
description: Delete a customer record.
tags:
- Customers
parameters:
- $ref: '#/components/parameters/customerId'
responses:
"204":
description: Customer deleted successfully
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
/customers/:
get:
operationId: listCustomers
summary: List all Customers
description: Retrieve a paginated list of all customers.
tags:
- Customers
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/limit'
responses:
"200":
description: List of customers
headers:
Link:
$ref: '#/components/headers/PaginationLink'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Customer'
"401":
$ref: '#/components/responses/Unauthorized'
post:
operationId: createCustomer
summary: Create a Customer
description: Create a new customer record.
tags:
- Customers
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- customer_id
properties:
customer_id:
type: string
description: Your unique external identifier for this customer
meta_data:
type: object
additionalProperties: true
responses:
"201":
description: Customer created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
"401":
$ref: '#/components/responses/Unauthorized'
"422":
$ref: '#/components/responses/UnprocessableEntity'
/customers/{id}/status/:
put:
operationId: cancelCustomer
summary: Cancel or Uncancel a customer
description: >-
Set or update the status of a customer. Use to cancel or uncancel.
tags:
- Customers
parameters:
- $ref: '#/components/parameters/customerId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- status
properties:
status:
type: string
enum:
- trial
- paid
- cancelled
responses:
"200":
description: Customer status updated
content:
application/json:
schema:
$ref: '#/components/schemas/Customer'
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
/customers/{id}/meta-data/:
get:
operationId: getCustomerMetaData
summary: Retrieve meta data for a Customer
description: Retrieve all metadata for a given customer.
tags:
- Customers
parameters:
- $ref: '#/components/parameters/customerId'
responses:
"200":
description: Customer metadata
content:
application/json:
schema:
type: object
additionalProperties: true
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
put:
operationId: replaceCustomerMetaData
summary: Update (replace) meta data for a Customer
description: Replace all metadata for a customer.
tags:
- Customers
parameters:
- $ref: '#/components/parameters/customerId'
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
"200":
description: Metadata replaced
content:
application/json:
schema:
type: object
additionalProperties: true
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
/customers/{id}/meta-data/{key}/:
get:
operationId: getCustomerMetaDataByKey
summary: Retrieve meta data by key for a Customer
description: Retrieve a specific metadata key for a customer.
tags:
- Customers
parameters:
- $ref: '#/components/parameters/customerId'
- $ref: '#/components/parameters/metaDataKey'
responses:
"200":
description: Metadata value
content:
application/json:
schema:
type: object
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
put:
operationId: setCustomerMetaDataByKey
summary: Set meta data by key for a Customer
description: Set a specific metadata key for a customer.
tags:
- Customers
parameters:
- $ref: '#/components/parameters/customerId'
- $ref: '#/components/parameters/metaDataKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Metadata set
content:
application/json:
schema:
type: object
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteCustomerMetaDataByKey
summary: Delete meta data by key for a Customer
description: Delete a specific metadata key for a customer.
tags:
- Customers
parameters:
- $ref: '#/components/parameters/customerId'
- $ref: '#/components/parameters/metaDataKey'
responses:
"204":
description: Metadata deleted
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
/conversions/{conversion_id}/:
get:
operationId: getConversion
summary: Retrieve a Conversion
description: Retrieve a single conversion by its ID.
tags:
- Conversions
parameters:
- $ref: '#/components/parameters/conversionId'
responses:
"200":
description: Conversion retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/Conversion'
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
patch:
operationId: updateConversion
summary: Update a Conversion
description: Update an existing conversion record.
tags:
- Conversions
parameters:
- $ref: '#/components/parameters/conversionId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
amount:
type: number
format: float
external_id:
type: string
meta_data:
type: object
additionalProperties: true
responses:
"200":
description: Conversion updated
content:
application/json:
schema:
$ref: '#/components/schemas/Conversion'
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteConversion
summary: Delete a Conversion
description: Delete a conversion record.
tags:
- Conversions
parameters:
- $ref: '#/components/parameters/conversionId'
responses:
"204":
description: Conversion deleted
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
/conversions/:
get:
operationId: listConversions
summary: List all conversions
description: Retrieve a paginated list of all conversions.
tags:
- Conversions
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/limit'
- name: date_from
in: query
schema:
type: string
format: date
description: Filter conversions from this date (YYYY-MM-DD)
- name: date_to
in: query
schema:
type: string
format: date
description: Filter conversions to this date (YYYY-MM-DD)
- name: affiliate_id
in: query
schema:
type: string
description: Filter by affiliate ID
- name: program_id
in: query
schema:
type: string
description: Filter by program ID
responses:
"200":
description: List of conversions
headers:
Link:
$ref: '#/components/headers/PaginationLink'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Conversion'
"401":
$ref: '#/components/responses/Unauthorized'
post:
operationId: createConversion
summary: Create a conversion
description: Record a new conversion event.
tags:
- Conversions
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- program_id
properties:
program_id:
type: string
description: The ID of the program for this conversion
external_id:
type: string
description: Your unique reference for this conversion
amount:
type: number
format: float
description: The conversion amount (for revenue-based commissions)
click_id:
type: string
description: The click ID to attribute this conversion to
customer_id:
type: string
description: The external customer identifier
commission_type:
type: string
description: The commission type to apply
meta_data:
type: object
additionalProperties: true
responses:
"201":
description: Conversion created
content:
application/json:
schema:
$ref: '#/components/schemas/Conversion'
"401":
$ref: '#/components/responses/Unauthorized'
"422":
$ref: '#/components/responses/UnprocessableEntity'
/conversions/{conversion_id}/commissions/:
post:
operationId: addCommissionsToConversion
summary: Add commissions to a conversion
description: Add additional commission entries to an existing conversion.
tags:
- Conversions
parameters:
- $ref: '#/components/parameters/conversionId'
requestBody:
required: true
content:
application/json:
schema:
type: array
items:
type: object
properties:
affiliate_id:
type: string
commission_type:
type: string
amount:
type: number
format: float
responses:
"200":
description: Commissions added
content:
application/json:
schema:
$ref: '#/components/schemas/Conversion'
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
/conversions/{conversion_id}/meta-data/:
get:
operationId: getConversionMetaData
summary: Retrieve meta data for a Conversion
description: Retrieve all metadata for a given conversion.
tags:
- Conversions
parameters:
- $ref: '#/components/parameters/conversionId'
responses:
"200":
description: Conversion metadata
content:
application/json:
schema:
type: object
additionalProperties: true
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
put:
operationId: replaceConversionMetaData
summary: Update (replace) meta data for a Conversion
description: Replace all metadata for a conversion.
tags:
- Conversions
parameters:
- $ref: '#/components/parameters/conversionId'
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
"200":
description: Metadata replaced
content:
application/json:
schema:
type: object
additionalProperties: true
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
/conversions/{conversion_id}/meta-data/{key}/:
get:
operationId: getConversionMetaDataByKey
summary: Retrieve meta data by key for a Conversion
description: Retrieve a specific metadata key for a conversion.
tags:
- Conversions
parameters:
- $ref: '#/components/parameters/conversionId'
- $ref: '#/components/parameters/metaDataKey'
responses:
"200":
description: Metadata value
content:
application/json:
schema:
type: object
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
put:
operationId: setConversionMetaDataByKey
summary: Set meta data by key for a Conversion
description: Set a specific metadata key for a conversion.
tags:
- Conversions
parameters:
- $ref: '#/components/parameters/conversionId'
- $ref: '#/components/parameters/metaDataKey'
requestBody:
required: true
content:
application/json:
schema:
type: object
responses:
"200":
description: Metadata set
content:
application/json:
schema:
type: object
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteConversionMetaDataByKey
summary: Delete meta data by key for a Conversion
description: Delete a specific metadata key for a conversion.
tags:
- Conversions
parameters:
- $ref: '#/components/parameters/conversionId'
- $ref: '#/components/parameters/metaDataKey'
responses:
"204":
description: Metadata deleted
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
/commissions/{commission_id}/:
get:
operationId: getCommission
summary: Retrieve a commission
description: Retrieve a single commission by its ID.
tags:
- Commissions
parameters:
- $ref: '#/components/parameters/commissionId'
responses:
"200":
description: Commission retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/Commission'
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
patch:
operationId: updateCommission
summary: Update a commission
description: Update an existing commission.
tags:
- Commissions
parameters:
- $ref: '#/components/parameters/commissionId'
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
amount:
type: number
format: float
responses:
"200":
description: Commission updated
content:
application/json:
schema:
$ref: '#/components/schemas/Commission'
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
/commissions/:
get:
operationId: listCommissions
summary: List all commissions
description: Retrieve a paginated list of all commissions.
tags:
- Commissions
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/limit'
- name: affiliate_id
in: query
schema:
type: string
description: Filter by affiliate ID
- name: approved
in: query
schema:
type: boolean
description: Filter by approval status
responses:
"200":
description: List of commissions
headers:
Link:
$ref: '#/components/headers/PaginationLink'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Commission'
"401":
$ref: '#/components/responses/Unauthorized'
/commissions/{commission_id}/approved/:
put:
operationId: approveCommission
summary: Approve a commission
description: Approve a pending commission.
tags:
- Commissions
parameters:
- $ref: '#/components/parameters/commissionId'
responses:
"200":
description: Commission approved
content:
application/json:
schema:
$ref: '#/components/schemas/Commission'
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
delete:
operationId: disapproveCommission
summary: Disapprove a commission
description: Disapprove an approved commission.
tags:
- Commissions
parameters:
- $ref: '#/components/parameters/commissionId'
responses:
"200":
description: Commission disapproved
content:
application/json:
schema:
$ref: '#/components/schemas/Commission'
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
/affiliates/{affiliate_id}/:
get:
operationId: getAffiliate
summary: Retrieve an affiliate
description: Retrieve a single affiliate by their ID.
tags:
- Affiliates
parameters:
- $ref: '#/components/parameters/affiliateId'
responses:
"200":
description: Affiliate retrieved
content:
application/json:
schema:
$ref: '#/components/schemas/Affiliate'
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteAffiliate
summary: Delete an affiliate
description: Delete an affiliate record.
tags:
- Affiliates
parameters:
- $ref: '#/components/parameters/affiliateId'
responses:
"204":
description: Affiliate deleted
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
/affiliates/:
get:
operationId: listAffiliates
summary: List all affiliates
description: Retrieve a paginated list of all affiliates.
tags:
- Affiliates
parameters:
- $ref: '#/components/parameters/page'
- $ref: '#/components/parameters/limit'
- name: email
in: query
schema:
type: string
description: Filter by affiliate email
- name: affiliate_group_id
in: query
schema:
type: string
description: Filter by affiliate group
responses:
"200":
description: List of affiliates
headers:
Link:
$ref: '#/components/headers/PaginationLink'
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Affiliate'
"401":
$ref: '#/components/responses/Unauthorized'
post:
operationId: createAffiliate
summary: Create an affiliate
description: Create a new affiliate.
tags:
- Affiliates
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- email
- firstname
- lastname
properties:
email:
type: string
format: email
firstname:
type: string
lastname:
type: string
meta_data:
type: object
additionalProperties: true
responses:
"201":
description: Affiliate created
content:
application/json:
schema:
$ref: '#/components/schemas/Affiliate'
"401":
$ref: '#/components/responses/Unauthorized'
"422":
$ref: '#/components/responses/UnprocessableEntity'
/affiliates/{affiliate_id}/group/:
put:
operationId: setAffiliateGroup
summary: Set affiliate group
description: Assign an affiliate to a group.
tags:
- Affiliates
parameters:
- $ref: '#/components/parameters/affiliateId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- group
properties:
group:
type: object
required:
- id
properties:
id:
type: string
responses:
"200":
description: Affiliate group set
content:
application/json:
schema:
$ref: '#/components/schemas/Affiliate'
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
delete:
operationId: removeAffiliateGroup
summary: Remove affiliate group
description: Remove the group assignment from an affiliate.
tags:
- Affiliates
parameters:
- $ref: '#/components/parameters/affiliateId'
responses:
"200":
description: Affiliate group removed
content:
application/json:
schema:
$ref: '#/components/schemas/Affiliate'
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
/affiliates/{affiliate_id}/notes/{id}/:
patch:
operationId: updateAffiliateNote
summary: Update note
description: Update an existing note for an affiliate.
tags:
- Affiliates
parameters:
- $ref: '#/components/parameters/affiliateId'
- name: id
in: path
required: true
schema:
type: string
description: Note ID
requestBody:
required: true
content:
application/json:
schema:
type: object
properties:
note:
type: string
responses:
"200":
description: Note updated
content:
application/json:
schema:
$ref: '#/components/schemas/Note'
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
delete:
operationId: deleteAffiliateNote
summary: Delete note
description: Delete a note from an affiliate.
tags:
- Affiliates
parameters:
- $ref: '#/components/parameters/affiliateId'
- name: id
in: path
required: true
schema:
type: string
description: Note ID
responses:
"204":
description: Note deleted
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
/affiliates/{affiliate_id}/notes/:
get:
operationId: listAffiliateNotes
summary: List notes
description: List all notes for an affiliate.
tags:
- Affiliates
parameters:
- $ref: '#/components/parameters/affiliateId'
responses:
"200":
description: List of notes
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Note'
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
post:
operationId: createAffiliateNote
summary: Create note
description: Create a new note for an affiliate.
tags:
- Affiliates
parameters:
- $ref: '#/components/parameters/affiliateId'
requestBody:
required: true
content:
application/json:
schema:
type: object
required:
- note
properties:
note:
type: string
responses:
"201":
description: Note created
content:
application/json:
schema:
$ref: '#/components/schemas/Note'
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
/affiliates/{affiliate_id}/meta-data/:
get:
operationId: getAffiliateMetaData
summary: Retrieve meta data for an Affiliate
description: Retrieve all metadata for a given affiliate.
tags:
- Affiliates
parameters:
- $ref: '#/components/parameters/affiliateId'
responses:
"200":
description: Affiliate metadata
content:
application/json:
schema:
type: object
additionalProperties: true
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
put:
operationId: replaceAffiliateMetaData
summary: Update (replace) meta data for an Affiliate
description: Replace all metadata for an affiliate.
tags:
- Affiliates
parameters:
- $ref: '#/components/parameters/affiliateId'
requestBody:
required: true
content:
application/json:
schema:
type: object
additionalProperties: true
responses:
"200":
description: Metadata replaced
content:
application/json:
schema:
type: object
additionalProperties: true
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$ref: '#/components/responses/NotFound'
/affiliates/{affiliate_id}/meta-data/{key}/:
get:
operationId: getAffiliateMetaDataByKey
summary: Retrieve meta data by key for an Affiliate
description: Retrieve a specific metadata key for an affiliate.
tags:
- Affiliates
parameters:
- $ref: '#/components/parameters/affiliateId'
- $ref: '#/components/parameters/metaDataKey'
responses:
"200":
description: Metadata value
content:
application/json:
schema:
type: object
"401":
$ref: '#/components/responses/Unauthorized'
"404":
$r
# --- truncated at 32 KB (72 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/tapfiliate/refs/heads/main/openapi/tapfiliate-rest-api-openapi.yml