Referral Factory referral program software logoReferral Factory
Start free trial
Help HomeCategories✨ Ask AI
Back to Help Hub
IntegrationsHow-To1 min readUpdated 2026-03-04

Referral Factory API — qualifying leads via API

Use the qualification endpoint to programmatically mark a lead as qualified from your own system when a conversion event occurs.

Send this article context to support so a human can pick up quickly.
Browse topics and support
Navigation

Topics

Integrations
56 articles
Getting Started
18 articles
Promoting Your Program
18 articles
Qualification
16 articles
Rewards
14 articles
Emails
12 articles
Referrers
10 articles
Billing
9 articles
Referral Link Page
7 articles
Leads
6 articles
Campaign Settings
4 articles
Analytics
3 articles
Industry Use Cases
0 articles
Article

On this page

EndpointQualifying a leadUnqualifying a leadIdentifier optionsBest practices
Support

Ask AI

Ask a product or setup question without leaving this page.

Need human help?

Still stuck?

If this article does not solve the problem, send the context to support or book time with a human.

Book a support callEnterprise rollout help
We will keep the article or page context with your request so support can respond faster.
Read this page as a quick path: scan the headings, use the step blocks, and escalate if the expected result does not happen.
Need help applying this to your account?

Contact support and we will keep this article attached to your request.

Use the qualification endpoint to programmatically mark a lead as qualified from your own system when a conversion event occurs.

Endpoint

Qualifying a lead

Unqualifying a lead

Set "qualified": false to revert a lead to Pending status — useful for handling refunds or cancellations.

Identifier options

You can identify the lead using:
  • email + campaign_id
  • id (Referral Factory internal user ID)
  • code (the referral code embedded in their link)

Best practices

Full reference: developers.referral-factory.com
  • Call this endpoint from your server-side payment processing code, immediately after a successful payment is confirmed
  • Build in idempotent behaviour: if your system retries on failure, ensure the same lead isn't qualified twice
  • Log API responses for debugging — a 200 response confirms the status change was applied
Related strategy reading

Go deeper with Learn

This help article explains the setup. These Learn guides explain the bigger strategy, planning, and real-world use of referral programs.

Referral Program
Referral Program
Go beyond setup and learn how to structure, launch, and improve a referral program.
Tracking and Attribution
HubSpot Referral Program: How To Connect Your Referral Program To HubSpot
HubSpot Referral Program: How To Connect Your Referral Program To HubSpot on Referral Factory Learn. Topics include HubS…
Tracking and Attribution
Why Referred Leads Are the Secret to Skyrocketing Your Conversion Rates
Boost your business with a referral program that delivers high ROI. Discover how referred leads, with a 3x higher conver…
Tracking and Attribution
How to Build a Successful Referral Partner Program
Learn how to build a referral partner program that drives growth, strengthens relationships, and delivers measurable ROI…
Still need help?

Send this article to support

A human can review the article you were reading and help with the exact next step.

Recommended next

Read the next best article

Integrations•How-To
Referral Factory API — adding referrers via API

Use the API to programmatically enrol users as referrers in your campaign — for example, automatically adding a customer as a referrer the moment they complete.

1 min read
Integrations•How-To
Referral Factory API — getting started

The Referral Factory REST API lets you programmatically manage your referral program — adding referrers, qualifying leads, and retrieving campaign data from.

2 min read
Integrations•FAQ
FAQ: What Intercom permissions does Referral Factory need?

When you connect Intercom to Referral Factory, you’ll be asked to authorize the following permissions on Intercom’s OAuth page:

1 min read
Integrations•How-To
How to connect Intercom to Referral Factory

Connecting Intercom to Referral Factory lets you automatically send new leads and referrers to Intercom, sync Intercom contacts into your campaigns, and.

2 min read
Article feedback

Did this answer your question?

Your vote helps support spot weak articles, fix missing steps, and decide when a person should step in.

Return to Help Hub