Skip to main content
POST
/
v1
/
signups
curl -X POST "https://api.affonso.io/v1/signups" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "click_id": "ref_clk_xyz789",
    "email": "jane@example.com",
    "external_user_id": "user_42",
    "name": "Jane Doe"
  }'

{
  "success": true,
  "data": {
    "id": "ref_clk_xyz789",
    "affiliate_id": "aff_abc123",
    "program_id": "prg_456def",
    "email": "jane@example.com",
    "customer_id": null,
    "subscription_id": null,
    "status": "lead",
    "name": "Jane Doe",
    "metadata": null,
    "created_at": "2026-01-25T11:55:00Z",
    "converted_at": null
  }
}
Use this endpoint when you want to record a lead signup from your own backend instead of relying on the browser pixel. The typical flow is:
  1. Track the click with POST /v1/clicks — store the returned id as your clickId.
  2. Once the visitor signs up in your application, call POST /v1/signups with that clickId plus their email and/or your internal user ID.
The endpoint is idempotent: calling it twice with the same clickId returns the existing referral without creating duplicates. If the affiliate’s program has a lead incentive configured, this call also creates the commission transaction and fires the transaction.created webhook in addition to referral.lead.

​
Body Parameters

​
click_id
string
required
The click ID returned by POST /v1/clicks. Must belong to your team.
​
email
string
The lead’s email address. Either email or external_user_id must be provided. Silently ignored when the program has email tracking disabled.
​
external_user_id
string
Your internal identifier for the lead (e.g. database user ID). Either email or external_user_id must be provided.
​
name
string
The lead’s display name. Maximum 255 characters. Silently ignored when the program has name tracking disabled.

​
Response

​
success
boolean
true on success. Returns false only on validation, auth, or not-found errors.
​
data
object
The referral object after conversion.

​
Status codes

CodeMeaning
201 CreatedClick successfully converted to a lead.
200 OKIdempotent re-call — the click was already converted. Returns the existing referral.
400 Bad RequestValidation error (missing click_id, neither email nor external_user_id provided, invalid email format).
401 UnauthorizedMissing or invalid API key.
404 Not FoundThe click_id does not exist or belongs to a different team.
429 Too Many RequestsPer-API-key rate limit exceeded.
curl -X POST "https://api.affonso.io/v1/signups" \
  -H "Authorization: Bearer sk_live_your_api_key" \
  -H "Content-Type: application/json" \
  -d '{
    "click_id": "ref_clk_xyz789",
    "email": "jane@example.com",
    "external_user_id": "user_42",
    "name": "Jane Doe"
  }'

{
  "success": true,
  "data": {
    "id": "ref_clk_xyz789",
    "affiliate_id": "aff_abc123",
    "program_id": "prg_456def",
    "email": "jane@example.com",
    "customer_id": null,
    "subscription_id": null,
    "status": "lead",
    "name": "Jane Doe",
    "metadata": null,
    "created_at": "2026-01-25T11:55:00Z",
    "converted_at": null
  }
}

​
Fraud checks

The same fraud checks that run for browser-side signups (self-referral, disposable email, paid traffic) also apply here. If any check is configured in BLOCK mode and rejects the signup:
  • The referral status is set to rejected instead of lead.
  • The referral.lead webhook is not emitted.
  • No lead-incentive commission is created.
  • The endpoint still returns 201 Created with the rejected referral object — inspect data.status to detect blocks.

​
Webhooks fired

EventWhen
referral.leadConversion succeeded and was not blocked by fraud checks.
transaction.createdConversion succeeded, was not blocked, and the program has a lead incentive configured for this affiliate (via group incentive or override).
  • POST /v1/clicks — track the click that you’ll later convert.
  • POST /v1/referrals — alternative endpoint when you want to skip the click stage and record a referral directly.