curl -X POST "https://api.affonso.io/v1/affiliates" \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Jane Smith",
"email": "jane@example.com",
"company_name": "Jane LLC",
"country_code": "US",
"payout_method": "paypal",
"payout_details": {
"email": "jane@example.com"
},
"external_user_id": "user_123",
"metadata": {
"plan": "pro",
"signup_source": "landing_page"
}
}'
curl -X POST "https://api.affonso.io/v1/affiliates" \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Alex Rivera",
"email": "alex@example.com",
"status": "pending"
}'
curl -X POST "https://api.affonso.io/v1/affiliates" \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Jane Smith",
"email": "jane@example.com",
"tracking_id": "janesmith-2024",
"payout_method": "paypal",
"payout_details": {
"email": "jane@example.com"
}
}'
{
"success": true,
"data": {
"id": "cmj8q1wau0003sb01lpvka478",
"name": "Jane Smith",
"email": "jane@example.com",
"tracking_id": "jane-smith",
"source": "api",
"partnership_status": "APPROVED",
"onboarding_completed": false,
"group_id": null,
"external_user_id": "user_123",
"metadata": {
"plan": "pro",
"signup_source": "landing_page"
},
"created_at": "2024-01-25T09:15:00Z"
}
}
{
"success": true,
"data": {
"id": "cmj8q1wau0003sb01lpvka478",
"name": "Jane Smith",
"email": "jane@example.com",
"tracking_id": "janesmith-2024",
"source": "api",
"partnership_status": "APPROVED",
"onboarding_completed": false,
"group_id": null,
"external_user_id": null,
"metadata": null,
"created_at": "2024-01-25T09:15:00Z"
}
}
Affiliates
Create Affiliate
Create a new affiliate Account and program contact
POST
/
v1
/
affiliates
curl -X POST "https://api.affonso.io/v1/affiliates" \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Jane Smith",
"email": "jane@example.com",
"company_name": "Jane LLC",
"country_code": "US",
"payout_method": "paypal",
"payout_details": {
"email": "jane@example.com"
},
"external_user_id": "user_123",
"metadata": {
"plan": "pro",
"signup_source": "landing_page"
}
}'
curl -X POST "https://api.affonso.io/v1/affiliates" \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Alex Rivera",
"email": "alex@example.com",
"status": "pending"
}'
curl -X POST "https://api.affonso.io/v1/affiliates" \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Jane Smith",
"email": "jane@example.com",
"tracking_id": "janesmith-2024",
"payout_method": "paypal",
"payout_details": {
"email": "jane@example.com"
}
}'
{
"success": true,
"data": {
"id": "cmj8q1wau0003sb01lpvka478",
"name": "Jane Smith",
"email": "jane@example.com",
"tracking_id": "jane-smith",
"source": "api",
"partnership_status": "APPROVED",
"onboarding_completed": false,
"group_id": null,
"external_user_id": "user_123",
"metadata": {
"plan": "pro",
"signup_source": "landing_page"
},
"created_at": "2024-01-25T09:15:00Z"
}
}
{
"success": true,
"data": {
"id": "cmj8q1wau0003sb01lpvka478",
"name": "Jane Smith",
"email": "jane@example.com",
"tracking_id": "janesmith-2024",
"source": "api",
"partnership_status": "APPROVED",
"onboarding_completed": false,
"group_id": null,
"external_user_id": null,
"metadata": null,
"created_at": "2024-01-25T09:15:00Z"
}
}
Body Parameters
string
required
The affiliate’s full display name. Must be between 1 and 100 characters.
string
required
The affiliate’s email address. Must be a valid email format. Creates or resolves an affiliate Account and a durable program contact for this email. Does not create a merchant User.
string
Custom tracking ID for the affiliate. Must contain only lowercase letters, numbers, and hyphens. Maximum 100 characters. If not provided, a tracking ID will be automatically generated from the affiliate’s name. Must be unique within your team.
string
Optional affiliate group ID.
string
default:"approved"
Partnership status at create time. No follow-up update call is required. Valid values:
pending, approved, rejected. Omit to keep the existing auto-approve behavior (approved).string
Company name for invoice. Maximum 100 characters.
string
2-letter ISO country code.
string
Payout method (lowercase with underscores). Valid values:
paypal, wise, payoneer, paxum, webmoney, skrill, wire_transfer, bitcoin, ethereum, alipay, wechat, manual, none.object
Payout details (fields vary by method, all snake_case). The required fields depend on the
payout_method:- Email-based methods (
paypal,wise,payoneer,paxum,skrill):email(string, valid email) - ID-based methods (
webmoney,alipay,wechat):account_id(string) - Crypto methods (
bitcoin,ethereum):address(string, wallet address) - Wire transfer (
wire_transfer):bank_name,account_number,swift_code,iban,routing_number,account_name(all strings) - Manual (
manual): No details required
string
Your external user ID for linking referral users to your own user system. Useful for matching affiliates back to users in your application. Maximum 255 characters.
object
Custom key-value data for storing additional information about the affiliate. You can store any JSON-serializable data here (e.g.,
{"plan": "pro", "signup_source": "landing_page"}).Response
The response includes the created affiliate object with the following fields:boolean
Always
true for successful responsesobject
The created affiliate object.
Show Data Object Properties
Show Data Object Properties
string
Unique identifier for the affiliate
string
The affiliate’s display name
string
The affiliate’s email address
string
Unique tracking ID for the affiliate. If a custom
tracking_id was provided in the request, it will be used. Otherwise, it’s automatically generated from the name (with a random suffix if needed for uniqueness).string
Source of the affiliate creation, always
"api" for API-created affiliatesstring
Partnership status with the program. Uppercase:
"PENDING", "APPROVED", "REJECTED", or null. Matches the status you sent. Defaults to "APPROVED" when status is omitted.boolean
Whether the affiliate has completed their onboarding process. Always
false for newly created affiliates.string | null
The affiliate group ID if assigned, otherwise
nullstring | null
Your external user ID if provided, otherwise
nullobject | null
Custom key-value data if provided, otherwise
nullstring
ISO 8601 timestamp of when the affiliate was created
curl -X POST "https://api.affonso.io/v1/affiliates" \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Jane Smith",
"email": "jane@example.com",
"company_name": "Jane LLC",
"country_code": "US",
"payout_method": "paypal",
"payout_details": {
"email": "jane@example.com"
},
"external_user_id": "user_123",
"metadata": {
"plan": "pro",
"signup_source": "landing_page"
}
}'
curl -X POST "https://api.affonso.io/v1/affiliates" \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Alex Rivera",
"email": "alex@example.com",
"status": "pending"
}'
curl -X POST "https://api.affonso.io/v1/affiliates" \
-H "Authorization: Bearer sk_live_your_api_key" \
-H "Content-Type: application/json" \
-d '{
"name": "Jane Smith",
"email": "jane@example.com",
"tracking_id": "janesmith-2024",
"payout_method": "paypal",
"payout_details": {
"email": "jane@example.com"
}
}'
{
"success": true,
"data": {
"id": "cmj8q1wau0003sb01lpvka478",
"name": "Jane Smith",
"email": "jane@example.com",
"tracking_id": "jane-smith",
"source": "api",
"partnership_status": "APPROVED",
"onboarding_completed": false,
"group_id": null,
"external_user_id": "user_123",
"metadata": {
"plan": "pro",
"signup_source": "landing_page"
},
"created_at": "2024-01-25T09:15:00Z"
}
}
{
"success": true,
"data": {
"id": "cmj8q1wau0003sb01lpvka478",
"name": "Jane Smith",
"email": "jane@example.com",
"tracking_id": "janesmith-2024",
"source": "api",
"partnership_status": "APPROVED",
"onboarding_completed": false,
"group_id": null,
"external_user_id": null,
"metadata": null,
"created_at": "2024-01-25T09:15:00Z"
}
}
Notes
- Creates an affiliate Account and durable program contact. Existing program IDs, tracking, and financial relations stay intact. Does not create a customer/merchant User.
- Set
statuson create when the affiliate should start aspendingorrejected. You do not need a secondPATCHto change status after create. - To retrieve related data like promo codes, commission overrides, invoice details, and payout methods, use
GET /v1/affiliates/{id}?expand=promoCodes,commissionOverrides,invoiceDetails,payoutMethod. - If you provide a custom
tracking_idthat is already in use by another affiliate in your team, the API will return a409 Conflicterror with the codeDUPLICATE_ERROR. - The
tracking_idmust contain only lowercase letters (a-z), numbers (0-9), and hyphens (-). Any other characters will result in a400 Bad Requestvalidation error.
Was this page helpful?