API key passed as a Bearer token in the Authorization header. You can find your API Key on Your FirstPromoter Dashboard. Navigate to Settings → Integrations → Manage API Keys
Headers
Account-ID
string
required
Account id. You can find your Account ID on Your FirstPromoter Dashboard. Navigate to Settings → Integrations
Body
application/json
promoter_campaign_id
integer
required
The ID of the promoter campaign
email
string<email>
Email address of the referral
uid
string
uid of the referral (This can be your user id from your database)
username
string
Username of the referral.
Note: Reach out to us on support if you need this. It needs to be enabled before you can use it.
split_details
object[]
Distribute the referral's commissions across multiple promoters. Each entry specifies a split partner and the percentage of every commission they receive. The primary promoter (set by the top-level promoter_campaign_id) automatically receives the remainder. The sum of all percentages must not exceed 100.
Entry source of the referral. This shows where the referral was captured from.
Cookie is set if the referral was captured using the tid cookie,
Coupon is for when the referral is captured via a coupon code.
Manual admin is for when the referral is added manually by an admin.
Manual affiliate is for when the referral is added manually by an affiliate.
Available options:
api,
coupon,
cookie,
manual_admin,
manual_affiliate
created_at
string<date-time>
Date and time when the referral was created
customer_since
string<date-time> | null
Date and time when the referral became a customer
promoter_campaign
object
Show child attributes
fraud_check
enum<string>
Fraud check (suspicion) status of the referral. no_suspicion means the referral is clean or was manually cleared. same_ip_suspicion means the referral shares an IP with the promoter. same_promoter_email means the referral email matches the promoter email. ad_source means the referral arrived via a paid ad click.
Available options:
no_suspicion,
same_ip_suspicion,
same_promoter_email,
ad_source
created_by_user_email
string<email> | null
Email address of the user who created the referral
username
string | null
Username chosen by the referral
split_details
object[] | null
The commission split configuration for this referral. Each entry represents a split partner. The primary promoter (the referral owner) receives the remainder of the commission after all split percentages are applied.
Show child attributes
first_name
string | null
last_name
string | null
website
string | null
comment
string | null
Internal note or comment on this referral
is_expired
boolean
Whether the referral has expired
{"docsConfig":{"theme":"mint","$schema":"https://mintlify.com/docs.json","name":"FirstPromoter Docs","description":"FirstPromoter developer docs: set up affiliate and referral tracking, connect billing and payout providers, receive webhooks, and use the REST API and MCP server.","colors":{"primary":"#2497F3","light":"#42A5F5","dark":"#1A1C25"},"logo":{"light":"https://mintcdn.com/firstpromoter/Qml53iAwCwPGiKRZ/logo/light.svg?fit=max\u0026auto=format\u0026n=Qml53iAwCwPGiKRZ\u0026q=85\u0026s=17d35344b27497f795682da8932295c9","dark":"https://mintcdn.com/firstpromoter/Qml53iAwCwPGiKRZ/logo/dark.svg?fit=max\u0026auto=format\u0026n=Qml53iAwCwPGiKRZ\u0026q=85\u0026s=ef23e747176d9a87b5ddf122595793f8"},"favicon":"https://mintcdn.com/firstpromoter/rNk-Jdvp2vdjAvd9/favicon.png?fit=max\u0026auto=format\u0026n=rNk-Jdvp2vdjAvd9\u0026q=85\u0026s=7faf17e323609b0fef661b9a9fe49ebc","navbar":{"links":[{"href":"mailto:support@firstpromoter.com","label":"Support"}],"primary":{"type":"button","label":"Dashboard","href":"https://login.firstpromoter.com/"}},"footer":{"socials":{"x":"https://x.com/firstpromoter","linkedin":"https://www.linkedin.com/company/first-promoter","facebook":"https://www.facebook.com/firstpromoter","github":"https://github.com/firstpromoter"},"links":[{"header":"Product","items":[{"label":"Features","href":"https://firstpromoter.com/features"},{"label":"Integrations","href":"https://firstpromoter.com/integrations"},{"label":"Pricing","href":"https://firstpromoter.com/pricing"},{"label":"Changelog","href":"https://changelog.firstpromoter.com/"},{"label":"Stripe app","href":"https://marketplace.stripe.com/apps/firstpromoter"}]},{"header":"Company","items":[{"label":"About us","href":"https://firstpromoter.com/about-us"},{"label":"Careers","href":"https://firstpromoter.com/careers"},{"label":"Blog","href":"https://firstpromoter.com/blog"},{"label":"Case studies","href":"https://firstpromoter.com/casestudy"},{"label":"Affiliate program","href":"https://firstpromoter.com/affiliate-program"}]},{"header":"Help","items":[{"label":"Help center","href":"https://help.firstpromoter.com/en"},{"label":"Contact support","href":"mailto:support@firstpromoter.com"},{"label":"Log in","href":"https://app.firstpromoter.com/login"}]},{"header":"Legal","items":[{"label":"Privacy policy","href":"https://firstpromoter.com/privacy"},{"label":"Terms of service","href":"https://firstpromoter.com/terms"}]}]},"search":{"prompt":"Search guides, integrations and API endpoints..."},"seo":{"metatags":{"canonical":"https://docs.firstpromoter.com"},"indexing":"navigable"},"contextual":{"options":["copy","view","chatgpt","claude","cursor","mcp"],"display":"header"},"styling":{"latex":false},"navigation":{"pages":[]}},"deployment":{"deploymentMetadataValue":{"subdomain":"firstpromoter","hasAudioNarration":false,"actualSubdomain":"firstpromoter","customDomains":["docs.firstpromoter.com"],"gitSource":{"type":"github","owner":"firstpromoter","repo":"docs","deployBranch":"main","contentDirectory":"","isPrivate":false,"mountPath":"","label":""},"entitlements":{},"buildId":"6b006a04286e5a4832624336","clientVersion":"0.0.4248","searchFilterCounts":[{"language":"default","tag":"Documentation","count":253},{"language":"default","tag":"API Reference","count":83},{"language":"default","tag":"Integration Options","count":43},{"language":"default","tag":"Affiliate API Reference","count":32},{"language":"default","tag":"Promoters","count":25},{"language":"default","tag":"Platform","count":23},{"language":"default","tag":"Custom","count":9},{"language":"default","tag":"Webhooks","count":9},{"language":"default","tag":"Reports","count":8},{"language":"default","tag":"Payouts","count":7}]},"assistantConfig":{},"basePath":"","hasChatPermissions":false,"hasWebMcpPermissions":false,"toggles":[],"googleFontsInlined":false},"customCss":[]}
{"page":{"pagePath":"api-reference-v2/api-admin/referrals/create-referral","slug":"/api-reference-v2/api-admin/referrals/create-referral","pageMetadata":{"description":"Create a referral for a promoter campaign by email, uid or username, optionally splitting its commissions with split_details.","openapi":"openapi-v2-referrals post /referrals","title":"Create referral","href":"/api-reference-v2/api-admin/referrals/create-referral"},"description":{"compiledSource":"\"use strict\";\nconst {jsx: _jsx} = arguments[0];\nconst {useMDXComponents: _provideComponents} = arguments[0];\nfunction _createMdxContent(props) {\n const _components = {\n p: \"p\",\n ..._provideComponents(),\n ...props.components\n };\n return _jsx(_components.p, {\n children: \"Create a referral for a promoter campaign by email, uid or username, optionally splitting its commissions with split_details.\"\n });\n}\nfunction MDXContent(props = {}) {\n const {wrapper: MDXLayout} = {\n ..._provideComponents(),\n ...props.components\n };\n return MDXLayout ? _jsx(MDXLayout, {\n ...props,\n children: _jsx(_createMdxContent, {\n ...props\n })\n }) : _createMdxContent(props);\n}\nreturn {\n default: MDXContent\n};\n","frontmatter":{},"scope":{}},"pageType":"default","mdx":{"mdxSource":{"compiledSource":"\"use strict\";const{Fragment:_Fragment,jsx:_jsx}=arguments[0];const{useMDXComponents:_provideComponents}=arguments[0];function _createMdxContent(props){return _jsx(_Fragment,{})}function MDXContent(props={}){const{wrapper:MDXLayout}={..._provideComponents(),...props.components};return MDXLayout?_jsx(MDXLayout,{...props,children:_jsx(_createMdxContent,{...props})}):_createMdxContent(props)}return{default:MDXContent}","frontmatter":{},"scope":{"config":{},"pageMetadata":{"description":"Create a referral for a promoter campaign by email, uid or username, optionally splitting its commissions with split_details.","openapi":"openapi-v2-referrals post /referrals","title":"Create referral","href":"/api-reference-v2/api-admin/referrals/create-referral"}}},"mdxSourceWithNoJs":null},"mdxExtracts":{"tableOfContents":[],"codeExamples":{}},"jsLinks":["/_mintlify/custom/firstpromoter/8ad42af542d542c7/downloadables/fpr-prox.js"],"openApiReferenceData":{"operation":{"summary":"Create referral","tags":["Referrals"],"description":"Create a referral for a promoter campaign by email, uid or username, optionally splitting its commissions with split_details.","parameters":["21b7e61f-e622-4540-989a-d63957619bb7"],"requestBody":"4279893c-d358-4163-8998-b36574b8e987","responses":{"200":"ad814362-5dd5-4216-ba56-93569eb80925","401":"14109112-099b-47f4-9470-fbcabea5f54b","403":"1980e9bd-70ae-4f52-ae82-2d9162465ae7","422":"ca59cc0c-a8f2-4835-bad8-5f107f0f9116"},"method":"post","type":"path","servers":["ac87d9a9-9c04-4105-b282-5a8446996153"],"security":["d11ac46b-5fd2-43c8-baa4-9088fb1b82a5"],"path":"/referrals","baseUrlOptions":["https://api.firstpromoter.com/api/v2/company"],"title":"Create referral","codeSamples":[],"requiredOnlyExamples":false,"requestExampleType":"generated","responseExampleType":"generated"},"dependencies":{"parameters":{"21b7e61f-e622-4540-989a-d63957619bb7":{"name":"Account-ID","in":"header","required":true,"description":"Account id. You can find your Account ID on Your FirstPromoter Dashboard. Navigate to Settings → Integrations","schema":{"type":"string","isRequired":true,"description":"Account id. You can find your Account ID on Your FirstPromoter Dashboard. Navigate to Settings → Integrations","uniqueKey":"","typeLabel":"string"}}},"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["promoter_campaign_id"],"properties":{"promoter_campaign_id":{"type":"integer","description":"The ID of the promoter campaign","isRequired":true,"uniqueKey":"promoter_campaign_id","typeLabel":"integer"},"email":{"type":"string","format":"email","description":"Email address of the referral","uniqueKey":"email","typeLabel":"string\u003cemail>"},"uid":{"type":"string","description":"uid of the referral (This can be your user id from your database)","uniqueKey":"uid","typeLabel":"string"},"username":{"type":"string","description":"Username of the referral. \n\n **Note**: Reach out to us on support if you need this. It needs to be enabled before you can use it.","uniqueKey":"username","typeLabel":"string"},"split_details":{"type":"array","description":"Distribute the referral's commissions across multiple promoters. Each entry specifies a split partner and the percentage of every commission they receive. The primary promoter (set by the top-level `promoter_campaign_id`) automatically receives the remainder. The sum of all percentages must not exceed 100.","items":{"type":"object","required":["promoter_campaign_id","percentage"],"properties":{"promoter_campaign_id":{"type":"integer","description":"The ID of the split partner's campaign enrollment (`promoter_campaign.id`). This is the ID that links a specific promoter to a specific campaign — not the campaign ID itself.","isRequired":true,"uniqueKey":"split_details.items.[INDEX].promoter_campaign_id","typeLabel":"integer"},"percentage":{"type":"integer","description":"The percentage of each commission this promoter receives. Must be between 0 and 100. The sum across all split entries must not exceed 100.","isRequired":true,"uniqueKey":"split_details.items.[INDEX].percentage","typeLabel":"integer"}},"uniqueKey":"split_details.items.[INDEX]","typeLabel":"object"},"example":[{"promoter_campaign_id":1002,"percentage":25},{"promoter_campaign_id":1003,"percentage":30}],"uniqueKey":"split_details","typeLabel":"object[]"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"promoter_campaign_id":123,"email":"jsmith@example.com","uid":"\u003cstring>","username":"\u003cstring>","split_details":[{"promoter_campaign_id":1002,"percentage":25},{"promoter_campaign_id":1003,"percentage":30}]}}},"exampleType":"generated"}},"exampleType":"generated"},"responses":{"ad814362-5dd5-4216-ba56-93569eb80925":{"description":"Referral created successfully","content":{"application/json":{"schema":{"type":"object","properties":{"id":{"type":"integer","description":"Id of the referral","uniqueKey":"id","typeLabel":"integer"},"email":{"type":"string","format":"email","description":"Email address of the referral","uniqueKey":"email","typeLabel":"string\u003cemail>"},"uid":{"type":"string","description":"uid of the referral","uniqueKey":"uid","typeLabel":"string"},"state":{"type":"string","enum":["subscribed","signup","active","cancelled","refunded","denied","pending","moved"],"description":"State of the referral","uniqueKey":"state","typeLabel":"enum\u003cstring>"},"metadata":{"type":"object","description":"Additional metadata of the referral","uniqueKey":"metadata","typeLabel":"object"},"entry_source":{"type":"string","enum":["api","coupon","cookie","manual_admin","manual_affiliate"],"description":"Entry source of the referral. This shows where the referral was captured from. \n **Cookie** is set if the referral was captured using the tid cookie, \n **Coupon** is for when the referral is captured via a coupon code. \n**Manual admin** is for when the referral is added manually by an admin. \n**Manual affiliate** is for when the referral is added manually by an affiliate.","uniqueKey":"entry_source","typeLabel":"enum\u003cstring>"},"created_at":{"type":"string","format":"date-time","description":"Date and time when the referral was created","uniqueKey":"created_at","typeLabel":"string\u003cdate-time>"},"customer_since":{"oneOf":[{"type":"string","format":"date-time","description":"Date and time when the referral became a customer","uniqueKey":"customer_since.oneOf.0","typeLabel":"string\u003cdate-time>"},{"type":"null","format":"date-time","description":"Date and time when the referral became a customer","uniqueKey":"customer_since.oneOf.1","typeLabel":"null"}],"uniqueKey":"customer_since","typeLabel":"string\u003cdate-time> | null"},"promoter_campaign":{"type":"object","properties":{"id":{"type":"integer","description":"Id of the promoter campaign","uniqueKey":"promoter_campaign.id","typeLabel":"integer"},"campaign_id":{"type":"integer","description":"Id of the campaign","uniqueKey":"promoter_campaign.campaign_id","typeLabel":"integer"},"promoter_id":{"type":"integer","description":"Id of the promoter","uniqueKey":"promoter_campaign.promoter_id","typeLabel":"integer"},"created_at":{"type":"string","format":"date-time","description":"Date and time when the promoter campaign was created","uniqueKey":"promoter_campaign.created_at","typeLabel":"string\u003cdate-time>"},"promoter":{"type":"object","properties":{"id":{"type":"integer","description":"Id of the promoter","uniqueKey":"promoter_campaign.promoter.id","typeLabel":"integer"},"email":{"type":"string","format":"email","description":"Email address of the promoter","uniqueKey":"promoter_campaign.promoter.email","typeLabel":"string\u003cemail>"},"name":{"type":"string","description":"Name of the promoter","uniqueKey":"promoter_campaign.promoter.name","typeLabel":"string"}},"uniqueKey":"promoter_campaign.promoter","typeLabel":"object"},"campaign":{"type":"object","properties":{"id":{"type":"integer","description":"Id of the campaign","uniqueKey":"promoter_campaign.campaign.id","typeLabel":"integer"},"name":{"type":"string","description":"Name of the campaign","uniqueKey":"promoter_campaign.campaign.name","typeLabel":"string"},"color":{"oneOf":[{"type":"string","description":"Color assigned to the campaign","uniqueKey":"promoter_campaign.campaign.color.oneOf.0","typeLabel":"string"},{"type":"null","description":"Color assigned to the campaign","uniqueKey":"promoter_campaign.campaign.color.oneOf.1","typeLabel":"null"}],"uniqueKey":"promoter_campaign.campaign.color","typeLabel":"string | null"}},"uniqueKey":"promoter_campaign.campaign","typeLabel":"object"}},"uniqueKey":"promoter_campaign","typeLabel":"object"},"fraud_check":{"type":"string","enum":["no_suspicion","same_ip_suspicion","same_promoter_email","ad_source"],"description":"Fraud check (suspicion) status of the referral. `no_suspicion` means the referral is clean or was manually cleared. `same_ip_suspicion` means the referral shares an IP with the promoter. `same_promoter_email` means the referral email matches the promoter email. `ad_source` means the referral arrived via a paid ad click.","uniqueKey":"fraud_check","typeLabel":"enum\u003cstring>"},"created_by_user_email":{"oneOf":[{"type":"string","format":"email","description":"Email address of the user who created the referral","uniqueKey":"created_by_user_email.oneOf.0","typeLabel":"string\u003cemail>"},{"type":"null","format":"email","description":"Email address of the user who created the referral","uniqueKey":"created_by_user_email.oneOf.1","typeLabel":"null"}],"uniqueKey":"created_by_user_email","typeLabel":"string\u003cemail> | null"},"username":{"oneOf":[{"type":"string","description":"Username chosen by the referral","uniqueKey":"username.oneOf.0","typeLabel":"string"},{"type":"null","description":"Username chosen by the referral","uniqueKey":"username.oneOf.1","typeLabel":"null"}],"uniqueKey":"username","typeLabel":"string | null"},"split_details":{"oneOf":[{"type":"array","description":"The commission split configuration for this referral. Each entry represents a split partner. The primary promoter (the referral owner) receives the remainder of the commission after all split percentages are applied.","items":{"type":"object","properties":{"promoter_campaign_id":{"type":"integer","description":"The ID of the split partner's campaign enrollment","uniqueKey":"split_details.oneOf.0.items.[INDEX].promoter_campaign_id","typeLabel":"integer"},"promoter_id":{"type":"integer","description":"The ID of the split partner (promoter)","uniqueKey":"split_details.oneOf.0.items.[INDEX].promoter_id","typeLabel":"integer"},"percentage":{"type":"integer","description":"The percentage of each commission this promoter receives","uniqueKey":"split_details.oneOf.0.items.[INDEX].percentage","typeLabel":"integer"}},"uniqueKey":"split_details.oneOf.0.items.[INDEX]","typeLabel":"object"},"uniqueKey":"split_details.oneOf.0","typeLabel":"object[]"},{"type":"null","description":"The commission split configuration for this referral. Each entry represents a split partner. The primary promoter (the referral owner) receives the remainder of the commission after all split percentages are applied.","items":{"type":"object","properties":{"promoter_campaign_id":{"type":"integer","description":"The ID of the split partner's campaign enrollment"},"promoter_id":{"type":"integer","description":"The ID of the split partner (promoter)"},"percentage":{"type":"integer","description":"The percentage of each commission this promoter receives"}}},"uniqueKey":"split_details.oneOf.1","typeLabel":"null"}],"uniqueKey":"split_details","typeLabel":"object[] | null"},"first_name":{"oneOf":[{"type":"string","uniqueKey":"first_name.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"first_name.oneOf.1","typeLabel":"null"}],"uniqueKey":"first_name","typeLabel":"string | null"},"last_name":{"oneOf":[{"type":"string","uniqueKey":"last_name.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"last_name.oneOf.1","typeLabel":"null"}],"uniqueKey":"last_name","typeLabel":"string | null"},"website":{"oneOf":[{"type":"string","uniqueKey":"website.oneOf.0","typeLabel":"string"},{"type":"null","uniqueKey":"website.oneOf.1","typeLabel":"null"}],"uniqueKey":"website","typeLabel":"string | null"},"comment":{"oneOf":[{"type":"string","description":"Internal note or comment on this referral","uniqueKey":"comment.oneOf.0","typeLabel":"string"},{"type":"null","description":"Internal note or comment on this referral","uniqueKey":"comment.oneOf.1","typeLabel":"null"}],"uniqueKey":"comment","typeLabel":"string | null"},"is_expired":{"type":"boolean","description":"Whether the referral has expired","uniqueKey":"is_expired","typeLabel":"boolean"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"id":123,"email":"jsmith@example.com","uid":"\u003cstring>","state":"subscribed","metadata":{},"entry_source":"api","created_at":"2023-11-07T05:31:56Z","customer_since":"2023-11-07T05:31:56Z","promoter_campaign":{"id":123,"campaign_id":123,"promoter_id":123,"created_at":"2023-11-07T05:31:56Z","promoter":{"id":123,"email":"jsmith@example.com","name":"\u003cstring>"},"campaign":{"id":123,"name":"\u003cstring>","color":"\u003cstring>"}},"fraud_check":"no_suspicion","created_by_user_email":"jsmith@example.com","username":"\u003cstring>","split_details":[{"promoter_campaign_id":123,"promoter_id":123,"percentage":123}],"first_name":"\u003cstring>","last_name":"\u003cstring>","website":"\u003cstring>","comment":"\u003cstring>","is_expired":true}}},"exampleType":"generated"}},"exampleType":"generated"},"14109112-099b-47f4-9470-fbcabea5f54b":{"description":"Unauthorized — the Bearer access token is missing, invalid, expired, or revoked. No JSON response body is returned.","content":{"application/json":{"schema":{"type":"object","uniqueKey":"","typeLabel":"object"},"example":{},"examples":{"Example":{"title":"Example","value":{}}},"exampleType":"examples"}},"exampleType":"examples"},"1980e9bd-70ae-4f52-ae82-2d9162465ae7":{"description":"Forbidden","content":{"_mintlify/placeholder":{"schema":{"type":"object","description":""}}}},"ca59cc0c-a8f2-4835-bad8-5f107f0f9116":{"description":"Validation error","content":{"application/json":{"schema":{"type":"object","properties":{"message":{"type":"string","uniqueKey":"message","typeLabel":"string"},"code":{"type":"string","uniqueKey":"code","typeLabel":"string"},"errors":{"type":"object","additionalProperties":{"type":"array","items":{"type":"string","uniqueKey":"errors.additionalProperties.items.[INDEX]","typeLabel":"string"},"uniqueKey":"errors.additionalProperties","typeLabel":"string[]"},"uniqueKey":"errors","typeLabel":"object"}},"uniqueKey":"","typeLabel":"object"},"examples":{"Example":{"title":"Example","value":{"message":"\u003cstring>","code":"\u003cstring>","errors":{}}}},"exampleType":"generated"}},"exampleType":"generated"}},"security":{"d11ac46b-5fd2-43c8-baa4-9088fb1b82a5":{"BearerAuth":{"type":"http","scheme":"bearer","description":"API key passed as a Bearer token in the Authorization header. You can find your API Key on Your FirstPromoter Dashboard. Navigate to Settings → Integrations → Manage API Keys","scopes":[]}}},"servers":{"ac87d9a9-9c04-4105-b282-5a8446996153":{"url":"https://api.firstpromoter.com/api/v2/company","description":"Production server"}},"processedSecurityOptions":[{"schemes":[{"scheme":{"type":"http","scheme":"bearer","description":"API key passed as a Bearer token in the Authorization header. You can find your API Key on Your FirstPromoter Dashboard. Navigate to Settings → Integrations → Manage API Keys","scopes":[]},"schema":{"title":"Bearer Auth","type":"string","isRequired":true,"description":"API key passed as a Bearer token in the Authorization header. You can find your API Key on Your FirstPromoter Dashboard. Navigate to Settings → Integrations → Manage API Keys","format":"bearer","typeLabel":"string\u003cbearer>","deprecated":false},"schemeName":"BearerAuth","name":"Authorization"}],"title":"BearerAuth"}]},"originalFileLocation":"api-reference-v2/api-admin/referrals/openapi-v2-referrals.json"},"subdomain":"firstpromoter","siteName":"FirstPromoter Docs","title":"Create referral - FirstPromoter Docs","navMaps":{"firstHrefInVersion":{"v2":{"href":"/api-reference-v2/api-admin/referrals/create-referral","matchLevel":0},"v1":{"href":"/introduction","matchLevel":4}},"firstHrefInLanguage":{}},"lastModified":"2026-11-20T13:53:59.715Z","originalFileLocation":"api-reference-v2/api-admin/referrals/create-referral.mdx"},"headHtml":"\u003cscript data-mint-head>(function(){var d=document.documentElement,p=null;if(!p){try{p=localStorage.getItem(\"isDarkMode\")}catch(e){}if(p==='true')p='dark';else if(p==='false')p='light';if(p!=='light'\u0026\u0026p!=='dark'\u0026\u0026p!=='system')p=\"system\"}var r=p==='system'?(matchMedia(\"(prefers-color-scheme: dark)\").matches?'dark':'light'):p;d.classList.remove(r==='dark'?'light':'dark');d.classList.add(r);d.setAttribute(\"data-theme-preference\",p)})();\u003c/script>\u003cmeta data-mint-head name=\"description\" content=\"Create a referral for a promoter campaign by email, uid or username, optionally splitting its commissions with split_details.\">\u003cmeta data-mint-head name=\"application-name\" content=\"FirstPromoter Docs\">\u003cmeta data-mint-head name=\"generator\" content=\"Mintlify\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/firstpromoter/NHAuOTz7uXRLkEOr/_generated/favicon/android-chrome-192x192.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"apple-touch-icon\" type=\"image/png\" sizes=\"180x180\" href=\"/mintlify-assets/_mintlify/favicons/firstpromoter/NHAuOTz7uXRLkEOr/_generated/favicon/apple-touch-icon.png\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/firstpromoter/NHAuOTz7uXRLkEOr/_generated/favicon/favicon-16x16.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/firstpromoter/NHAuOTz7uXRLkEOr/_generated/favicon/favicon-32x32.png\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/firstpromoter/NHAuOTz7uXRLkEOr/_generated/favicon/favicon.ico\" media=\"(prefers-color-scheme: light)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"192x192\" href=\"/mintlify-assets/_mintlify/favicons/firstpromoter/NHAuOTz7uXRLkEOr/_generated/favicon-dark/android-chrome-192x192.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"16x16\" href=\"/mintlify-assets/_mintlify/favicons/firstpromoter/NHAuOTz7uXRLkEOr/_generated/favicon-dark/favicon-16x16.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"icon\" type=\"image/png\" sizes=\"32x32\" href=\"/mintlify-assets/_mintlify/favicons/firstpromoter/NHAuOTz7uXRLkEOr/_generated/favicon-dark/favicon-32x32.png\" media=\"(prefers-color-scheme: dark)\">\u003clink data-mint-head rel=\"shortcut icon\" type=\"image/x-icon\" href=\"/mintlify-assets/_mintlify/favicons/firstpromoter/NHAuOTz7uXRLkEOr/_generated/favicon-dark/favicon.ico\" media=\"(prefers-color-scheme: dark)\">\u003cmeta data-mint-head property=\"og:title\" content=\"Create referral - FirstPromoter Docs\">\u003cmeta data-mint-head property=\"og:description\" content=\"Create a referral for a promoter campaign by email, uid or username, optionally splitting its commissions with split_details.\">\u003cmeta data-mint-head property=\"og:site_name\" content=\"FirstPromoter Docs\">\u003cmeta data-mint-head property=\"og:url\" content=\"https://docs.firstpromoter.com/api-reference-v2/api-admin/referrals/create-referral\">\u003cmeta data-mint-head property=\"og:type\" content=\"website\">\u003cmeta data-mint-head property=\"og:image\" content=\"https://firstpromoter.mintlify.site/_mintlify/api/og/v2?division=Referrals\u0026amp;title=Create+referral\u0026amp;description=Create+a+referral+for+a+promoter+campaign+by+email%2C+uid+or+username%2C+optionally+splitting+its+commissions+with+split_details.\u0026amp;theme=fff9650e72028c28308bb6bc\u0026amp;signature=8d6a7cce1bc7a56c49a40bd865f16b8a228a891fb05d1dcac3f4d5919ffcd1ab\">\u003cmeta data-mint-head property=\"og:image:width\" content=\"1200\">\u003cmeta data-mint-head property=\"og:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"twitter:card\" content=\"summary_large_image\">\u003cmeta data-mint-head name=\"twitter:title\" content=\"Create referral - FirstPromoter Docs\">\u003cmeta data-mint-head name=\"twitter:description\" content=\"Create a referral for a promoter campaign by email, uid or username, optionally splitting its commissions with split_details.\">\u003cmeta data-mint-head name=\"twitter:image\" content=\"https://firstpromoter.mintlify.site/_mintlify/api/og/v2?division=Referrals\u0026amp;title=Create+referral\u0026amp;description=Create+a+referral+for+a+promoter+campaign+by+email%2C+uid+or+username%2C+optionally+splitting+its+commissions+with+split_details.\u0026amp;theme=fff9650e72028c28308bb6bc\u0026amp;signature=8d6a7cce1bc7a56c49a40bd865f16b8a228a891fb05d1dcac3f4d5919ffcd1ab\">\u003cmeta data-mint-head name=\"twitter:image:width\" content=\"1200\">\u003cmeta data-mint-head name=\"twitter:image:height\" content=\"630\">\u003cmeta data-mint-head name=\"msapplication-config\" content=\"/mintlify-assets/_mintlify/favicons/firstpromoter/NHAuOTz7uXRLkEOr/_generated/favicon/browserconfig.xml\">\u003cmeta data-mint-head name=\"apple-mobile-web-app-title\" content=\"FirstPromoter Docs\">\u003cmeta data-mint-head name=\"msapplication-TileColor\" content=\"#2497F3\">\u003clink data-mint-head rel=\"canonical\" href=\"https://docs.firstpromoter.com/api-reference-v2/api-admin/referrals/create-referral\">\u003clink data-mint-head rel=\"alternate\" type=\"application/xml\" href=\"/sitemap.xml\">\u003clink data-mint-head rel=\"alternate\" type=\"text/markdown\" href=\"/api-reference-v2/api-admin/referrals/create-referral.md\">\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@graph\":[{\"@type\":\"Organization\",\"@id\":\"https://docs.firstpromoter.com/#organization\",\"name\":\"FirstPromoter Docs\",\"url\":\"https://docs.firstpromoter.com\",\"logo\":{\"@type\":\"ImageObject\",\"url\":\"https://mintcdn.com/firstpromoter/Qml53iAwCwPGiKRZ/logo/light.svg?fit=max\u0026auto=format\u0026n=Qml53iAwCwPGiKRZ\u0026q=85\u0026s=17d35344b27497f795682da8932295c9\"}},{\"@type\":\"WebSite\",\"@id\":\"https://docs.firstpromoter.com#website\",\"name\":\"FirstPromoter Docs\",\"url\":\"https://docs.firstpromoter.com\",\"publisher\":{\"@id\":\"https://docs.firstpromoter.com/#organization\"}},{\"@type\":\"WebPage\",\"@id\":\"https://docs.firstpromoter.com/api-reference-v2/api-admin/referrals/create-referral#webpage\",\"url\":\"https://docs.firstpromoter.com/api-reference-v2/api-admin/referrals/create-referral\",\"name\":\"Create referral\",\"description\":\"Create a referral for a promoter campaign by email, uid or username, optionally splitting its commissions with split_details.\",\"dateModified\":\"2026-11-20T13:53:59.715Z\",\"isPartOf\":{\"@id\":\"https://docs.firstpromoter.com#website\"},\"breadcrumb\":{\"@id\":\"https://docs.firstpromoter.com/api-reference-v2/api-admin/referrals/create-referral#breadcrumb\"}},{\"@type\":\"BreadcrumbList\",\"@id\":\"https://docs.firstpromoter.com/api-reference-v2/api-admin/referrals/create-referral#breadcrumb\",\"itemListElement\":[{\"@type\":\"ListItem\",\"position\":1,\"name\":\"Referrals\",\"item\":\"https://docs.firstpromoter.com/api-reference-v2/api-admin/referrals/get-referrals\"},{\"@type\":\"ListItem\",\"position\":2,\"name\":\"Create referral\",\"item\":\"https://docs.firstpromoter.com/api-reference-v2/api-admin/referrals/create-referral\"}]},{\"@type\":[\"TechArticle\",\"APIReference\"],\"@id\":\"https://docs.firstpromoter.com/api-reference-v2/api-admin/referrals/create-referral#apireference\",\"headline\":\"Create referral\",\"name\":\"Create referral\",\"description\":\"Create a referral for a promoter campaign by email, uid or username, optionally splitting its commissions with split_details.\",\"url\":\"https://docs.firstpromoter.com/api-reference-v2/api-admin/referrals/create-referral\",\"mainEntityOfPage\":{\"@id\":\"https://docs.firstpromoter.com/api-reference-v2/api-admin/referrals/create-referral#webpage\"},\"dateModified\":\"2026-11-20T13:53:59.715Z\",\"publisher\":{\"@id\":\"https://docs.firstpromoter.com/#organization\"},\"isPartOf\":{\"@id\":\"https://docs.firstpromoter.com#website\"}}]}\u003c/script>\u003cscript data-mint-head type=\"application/ld+json\">{\"@context\":\"https://schema.org\",\"@type\":\"WebSite\",\"name\":\"FirstPromoter Docs\",\"publisher\":{\"@type\":\"Organization\",\"name\":\"FirstPromoter Docs\"},\"provider\":{\"@type\":\"Organization\",\"name\":\"Mintlify\",\"url\":\"https://mintlify.com\"}}\u003c/script>","agentPointerHref":"/api-reference-v2/api-admin/referrals/create-referral.md","siteName":"FirstPromoter Docs","nav":{"global":null,"versions":[{"version":"v2","anchors":[{"anchor":"Documentation","icon":"book-open","tabs":[{"tab":"Documentation","pages":[{"title":"Documentation","href":"/introduction"}]},{"tab":"API Reference","groups":[{"group":"API Documentation","pages":[{"title":"FirstPromoter API v2 Introduction","sidebarTitle":"Introduction","href":"/api-reference-v2/api-admin/introduction"},{"title":"FirstPromoter API v2 Authentication","sidebarTitle":"Authentication","href":"/api-reference-v2/api-admin/authentication"}]},{"group":"Batch Processes","pages":[{"openapi":"openapi-v2-batches get /batch_processes","title":"List in progress batch processes.","href":"/api-reference-v2/api-admin/batches/list-inprogress-batch-processes"},{"openapi":"openapi-v2-batches get /batch_processes/{id}","title":"Show batch process","href":"/api-reference-v2/api-admin/batches/show-batch-process"},{"openapi":"openapi-v2-batches get /batch_processes/progress","title":"Show progress","href":"/api-reference-v2/api-admin/batches/show-progress"}]},{"group":"Tracking Api","pages":[{"title":"Tracking leads and sign-ups","openapi":"openapi-v2-tracking POST /signup","href":"/api-reference-v2/api-admin/tracking-api/leads-and-signups"},{"title":"Tracking sales and commissions","openapi":"openapi-v2-tracking POST /sale","href":"/api-reference-v2/api-admin/tracking-api/sales"},{"title":"Tracking refunds and negative commissions","openapi":"openapi-v2-tracking POST /refund","href":"/api-reference-v2/api-admin/tracking-api/refund"},{"title":"Tracking cancellations","openapi":"openapi-v2-tracking POST /cancellation","href":"/api-reference-v2/api-admin/tracking-api/cancellation"}]},{"group":"Referrals","pages":[{"openapi":"openapi-v2-referrals get /referrals","title":"Get available referrals","href":"/api-reference-v2/api-admin/referrals/get-referrals"},{"description":"Get one referral by ID, or by email, uid or username using find_by.","openapi":"openapi-v2-referrals get /referrals/{id}","title":"Get referral","href":"/api-reference-v2/api-admin/referrals/get-referral"},{"openapi":"openapi-v2-referrals post /referrals","title":"Create referral","href":"/api-reference-v2/api-admin/referrals/create-referral"},{"description":"Update a referral's email, uid, username, promoter campaign or commission splits, finding it by ID or by another field.","openapi":"openapi-v2-referrals put /referrals/{id}","title":"Update referral","href":"/api-reference-v2/api-admin/referrals/update-referral"},{"openapi":"openapi-v2-referrals post /referrals/move_to_promoter","title":"Move referrals to promoter","href":"/api-reference-v2/api-admin/referrals/move-referrals-to-promoter"},{"openapi":"openapi-v2-referrals delete /referrals","title":"Delete referrals","href":"/api-reference-v2/api-admin/referrals/delete-referrals"}]},{"group":"Promoters","pages":[{"openapi":"openapi-v2-promoters get /promoters","title":"Get available promoters","href":"/api-reference-v2/api-admin/promoters/get-available-promoters"},{"openapi":"openapi-v2-promoters post /promoters","title":"Create promoter","href":"/api-reference-v2/api-admin/promoters/create-promoter"},{"openapi":"openapi-v2-promoters get /promoters/{id}","title":"Get promoter details","href":"/api-reference-v2/api-admin/promoters/get-promoter-details"},{"openapi":"openapi-v2-promoters put /promoters/{id}","title":"Update promoter","href":"/api-reference-v2/api-admin/promoters/update-promoter"},{"openapi":"openapi-v2-promoters get /promoters/{id}/referral_links","title":"Get promoter referral links","href":"/api-reference-v2/api-admin/promoters/get-promoter-referral-links"},{"openapi":"openapi-v2-promoters get /promoters/{id}/chart_data","title":"Get data used for chart","href":"/api-reference-v2/api-admin/promoters/get-data-used-for-chart"},{"openapi":"openapi-v2-promoters get /promoters/{id}/overview_report","title":"Get reports for promoter overview","href":"/api-reference-v2/api-admin/promoters/get-reports-for-promoter-overview"},{"openapi":"openapi-v2-promoters get /promoters/{id}/traffic_sources_report","title":"Get reports for promoter traffic sources","href":"/api-reference-v2/api-admin/promoters/get-reports-for-promoter-traffic-sources"},{"openapi":"openapi-v2-promoters get /promoters/{id}/urls_report","title":"Get reports for promoter URLs","href":"/api-reference-v2/api-admin/promoters/get-reports-for-promoter-urls"},{"openapi":"openapi-v2-promoters post /promoters/assign_parent","title":"Assign a parent promoter","href":"/api-reference-v2/api-admin/promoters/assign-parent-promoter"},{"openapi":"openapi-v2-promoters post /promoters/add_to_campaign","title":"Add promoters to campaign","href":"/api-reference-v2/api-admin/promoters/add-promoter-to-campaign"},{"openapi":"openapi-v2-promoters post /promoters/move_to_campaign","title":"Move promoters to campaign","href":"/api-reference-v2/api-admin/promoters/move-promoter-to-campaign"},{"openapi":"openapi-v2-promoters post /promoters/accept","title":"Accept promoters","href":"/api-reference-v2/api-admin/promoters/accept-promoters"},{"openapi":"openapi-v2-promoters post /promoters/reject","title":"Reject promoters","href":"/api-reference-v2/api-admin/promoters/reject-promoters"},{"openapi":"openapi-v2-promoters post /promoters/block","title":"Block promoters","href":"/api-reference-v2/api-admin/promoters/block-promoters"},{"openapi":"openapi-v2-promoters post /promoters/archive","title":"Archive promoters","href":"/api-reference-v2/api-admin/promoters/archive-promoters"},{"openapi":"openapi-v2-promoters post /promoters/restore","title":"Restore promoters","href":"/api-reference-v2/api-admin/promoters/restore-unarchived-promoters"}]},{"group":"Promoter Campaigns","pages":[{"openapi":"openapi-v2-promoter-campaigns get /promoter_campaigns","title":"Get available promoter campaigns","href":"/api-reference-v2/api-admin/promoter-campaigns/get-available-promoter-campaigns"},{"openapi":"openapi-v2-promoter-campaigns put /promoter_campaigns/{id}","title":"Update promoter campaign","href":"/api-reference-v2/api-admin/promoter-campaigns/update-promoter-campaign"}]},{"group":"Commissions","pages":[{"openapi":"openapi-v2-commissions get /commissions","title":"Get all commissions","href":"/api-reference-v2/api-admin/commissions/get-all-commissions"},{"openapi":"openapi-v2-commissions post /commissions","title":"Create a commission","href":"/api-reference-v2/api-admin/commissions/create-a-commission"},{"openapi":"openapi-v2-commissions put /commissions/{id}","title":"Update a commission","href":"/api-reference-v2/api-admin/commissions/update-a-commission"},{"openapi":"openapi-v2-commissions post /commissions/approve","title":"Approve commissions","href":"/api-reference-v2/api-admin/commissions/approve-commissions"},{"openapi":"openapi-v2-commissions post /commissions/deny","title":"Deny commissions","href":"/api-reference-v2/api-admin/commissions/deny-commissions"},{"openapi":"openapi-v2-commissions post /commissions/mark_fulfilled","title":"Mark nonmonetary commissions as fulfilled","href":"/api-reference-v2/api-admin/commissions/mark-nonmonetary-commissions-as-fulfilled"},{"openapi":"openapi-v2-commissions post /commissions/mark_unfulfilled","title":"Mark nonmonetary commissions as unfulfilled","href":"/api-reference-v2/api-admin/commissions/mark-nonmonetary-commissions-as-unfulfilled"}]},{"group":"Promo Codes","pages":[{"openapi":"openapi-v2-promocodes get /promo_codes","title":"Get promo codes","href":"/api-reference-v2/api-admin/promo-codes/get-promo-codes"},{"openapi":"openapi-v2-promocodes get /promo_codes/{id}","title":"Get promo code by id","href":"/api-reference-v2/api-admin/promo-codes/get-promo-code-by-id"},{"openapi":"openapi-v2-promocodes post /promo_codes","title":"Create promo code (Stripe Only)","href":"/api-reference-v2/api-admin/promo-codes/create-promo-code"},{"openapi":"openapi-v2-promocodes put /promo_codes/{id}","title":"Update promo code by id","href":"/api-reference-v2/api-admin/promo-codes/update-promo-code-by-id"},{"openapi":"openapi-v2-promocodes delete /promo_codes/{id}","title":"Archive promo code by id","href":"/api-reference-v2/api-admin/promo-codes/archive-promo-code-by-id"}]},{"group":"Payouts","pages":[{"openapi":"openapi-v2-payouts get /payouts","title":"Get all payouts","href":"/api-reference-v2/api-admin/payouts/get-all-payouts"},{"openapi":"openapi-v2-payouts get /payouts/stats","title":"Get payout stats","href":"/api-reference-v2/api-admin/payouts/get-payout-stats"},{"openapi":"openapi-v2-payouts get /payouts/due_stats","title":"Get due payout stats","href":"/api-reference-v2/api-admin/payouts/get-due-payout-stats"},{"openapi":"openapi-v2-payouts get /payouts/group_by_promoters","title":"Get all payouts grouped by promoters","href":"/api-reference-v2/api-admin/payouts/get-all-payouts-grouped-by-promoters"}]},{"group":"Reports","pages":[{"openapi":"openapi-v2-reports get /reports/campaigns","title":"Get reports for campaigns","href":"/api-reference-v2/api-admin/reports/get-reports-for-campaigns"},{"openapi":"openapi-v2-reports get /reports/overview","title":"Get reports for overview","href":"/api-reference-v2/api-admin/reports/get-reports-for-overview"},{"openapi":"openapi-v2-reports get /reports/promoters","title":"Get reports for promoters","href":"/api-reference-v2/api-admin/reports/get-reports-for-promoters"},{"openapi":"openapi-v2-reports get /reports/urls","title":"Get reports for URLs","href":"/api-reference-v2/api-admin/reports/get-reports-for-urls"},{"openapi":"openapi-v2-reports get /reports/traffic_sources","title":"Get reports for traffic sources","href":"/api-reference-v2/api-admin/reports/get-reports-for-traffic-sources"}]}]},{"tab":"Affiliate API Reference","pages":[{"title":"Affiliate API Reference","href":"/api-reference-v2/api-affiliate/introduction"}]},{"tab":"Advanced API Reference","hidden":true,"pages":[{"title":"Advanced API Reference","href":"/api-reference-v2/api-advanced/introduction"}]}]},{"anchor":"API Reference","icon":"webhook","href":"https://docs.firstpromoter.com/api-reference-v2/api-admin/introduction"},{"anchor":"Help Center","icon":"square-question","href":"https://help.firstpromoter.com/en/"}]},{"version":"v1","pages":[{"title":"v1","href":"/introduction"}]}]},"basePath":"","title":"Create referral - FirstPromoter Docs","deploymentId":"dpl_2pTxFtyBudBMYZiCw1MyvoA1wxpd","buildId":"dpl_2pTxFtyBudBMYZiCw1MyvoA1wxpd","dynamics":["c2aa737661","2b790eda92","b0f84f53ff","a9bb46feb3"],"chunks":["OpenApiReferenceProvider-BtG4DSkw.js","snippetPresets-C1k1xDhp.js","utils-PMJoEt4Y.js","style-to-object-BY3JEAdk.js","utils-DW3Pr7Jq.js","v4-DIgz8zy6.js","addUniqueKeysToSchema-DIISLO2w.js","conditional-requirements-CFM0id0Q.js","cloneDeep-BErNCZCm.js","_Uint8Array-f0PCu9f_.js","isObject-FP1Yky1u.js","ApiExamples-OjY-8mqu.js","usePlaygroundInputsStore-B2HS2hUb.js","shallow-DVFuuIDQ.js","isEqual-DG0UKiQC.js","CodeSnippets-Cy6FBgwN.js","CodeSnippet-D1PtG8ed.js","getApiPlaygroundDisplay-Dkx2eNtL.js","Page-C8Cg25if.js","DynamicMarkdown-BvJIe00T.js","SectionHeading-B0rKYV8d.js","icon-yclzBff4.js","MethodPill-DxA11cCF.js","getPastedJson-CpkIDpMk.js","DuplicateIcon-CFCQNJ-D.js","axios-CsQoIw0U.js","Markdown-CK5C-fmV.js","AssistantPageLink-Cw134Dd-.js","dist-3xM3Qrc7.js","lib-DMeTj1gb.js","lib-B8HbPgcC.js","katex-Dbtb6Wk7.js","html-void-elements-mCSPHezU.js","marked.esm-CZWythHk.js"]}