Partners

Create a partner

Adds a partner directly (status: active) or into the review queue (status: pending). The handle is derived from the email when omitted. A duplicate answers 409 WITH the existing partner under existing, so you can connect it to your system without a second lookup.

Scope: partners:write (or write)

post/v1/partners

Request

  • Base URL: https://api.affiliaterail.com
  • URL: https://api.affiliaterail.com/v1/partners
  • Auth: HTTP bearer

Request body

program_idstring required

Prefixed id (prg_…)

emailstring email required
first_namestring
last_namestring
company_namestring
website_urlstring uri
country_codestring
handlestring

2 to 32 chars, letters, digits, hyphens. Derived from the email when omitted.

group_idstring

Prefixed id (grp_…)

status'active' | 'pending'

pending puts the partner in the review queue instead of activating them

metadataobject nullable

Your own key/value data, stored as given

Example request

{
  "program_id": "prg_7uSyy9FqVLCFWrdPeZaK",
  "group_id": "grp_7uSyy9FqVLCFWrdPeZaK"
}

Response

The new partner

idstring required

Prefixed id (part_…)

object'partner' required
program_idstring required

Prefixed id (prg_…)

group_idstring nullable required

Prefixed id (grp_…)

emailstring email required
first_namestring nullable required
last_namestring nullable required
display_namestring nullable required
company_namestring nullable required
website_urlstring nullable required
country_codestring nullable required
language_codestring nullable required
handlestring required

The ?ref= value

status'pending' | 'active' | 'declined' | 'suspended' required
decline_reasonstring nullable required
suspension_reasonstring nullable required
currencystring required

The program's currency; every amount on this partner is in it

min_payout_minorinteger nullable required

Per-partner threshold override; null means the program's

terms_accepted_atstring date-time nullable required

ISO-8601, UTC

terms_versionstring nullable required
completed_onboardingboolean required
email_first_referralboolean required
email_new_referralboolean required
email_payout_paidboolean required
metadataobject nullable required

Your own key/value data, stored as given

created_atstring date-time required

ISO-8601, UTC

updated_atstring date-time required

ISO-8601, UTC

Example response

{
  "id": "part_7uSyy9FqVLCFWrdPeZaK",
  "program_id": "prg_7uSyy9FqVLCFWrdPeZaK",
  "group_id": "grp_7uSyy9FqVLCFWrdPeZaK",
  "currency": "USD",
  "min_payout_minor": 2500,
  "terms_accepted_at": "2026-08-21T10:15:30.000Z",
  "stats": {
    "commissions_minor": 2500,
    "paid_minor": 2500,
    "currency": "USD"
  },
  "created_at": "2026-08-21T10:15:30.000Z",
  "updated_at": "2026-08-21T10:15:30.000Z"
}

Changes

No recorded changes to this operation across all 1 revision of this API.