Step 1: Review the API Documentation
To understand how each endpoint works, review the API documentation:
This documentation explains all available endpoints, required fields, authentication rules, and response structures.
Step 2: Get Your API Access Token
To authenticate all API requests, you will need your API Access Token.
Go to Settings → Webhooks & API
Locate the API Access Token.
Copy it and save it in your configuration. This token must be included in every API call.
Step 3: Find Your Campaign ID
Your campaign ID is required for creating users via API.
Go to the Campaigns page
Select Edit Campaign from the Actions menu.
Navigate to the Integration tab at the top.
Open the API section.
Copy your Campaign ID and save it in your configuration.
Step 4: Create a User Using the API
Creating a user through the API automatically generates a unique referral link for that user.
Use the Create a User endpoint:
In the “Body Params” section of the documentation, you will see all required fields. At minimum, you must provide:
campaign_id (from Step 3)
first_name
email
When the user is created, the API response will include a user_id. It is strongl recommended that you save this user_id, as you will need it to retrieve the user later.
If you do not save it, you will need to search for the user using the Search API.
Step 5: Confirm the User Was Created
You can verify the user in your Referral Factory account in the Users tab.
Search for the user by email to ensure the API request was successful.
Step 6: Retrieve the User and Display Their Referral Link
To display the user’s referral link inside your logged-in experience, you need to retrieve the user’s details.
Use the Retrieve a User endpoint:
This request requires the user_id that you received during user creation.
In the API response, you will find a field called url, which contains the user’s unique referral link.
Step 7: If You Did Not Save the User ID
If you didn’t store the user_id at the time of creation, you can look it up using the Search API.
Search API documentation:
In the “Body Params” section, you will see a filters object.
Use the filters to search for the user by their email address and campaign ID.
Once the correct user is returned in the response, you can extract the id and then use the Retrieve a User endpoint (Step 6) to access their referral link.
It is important to include the campaign_id in your search because the same email can exist in multiple campaigns.
Step 8: Access the Referral Link
After retrieving the user via the Retrieve a User endpoint, you will see the field:
url
This value represents the user’s unique referral link, which you can now display inside your own app or website.
Step 9: Retrieve Analytics Data
You can easily retrieve analytics data for a user by including the appropriate parameters in the request body.
Or you can use the same in Retrieve a User.
curl --request GET \
--header 'Authorization: Bearer AqpahiuuTDlgiwme85ZvDtrxzAD7gIx0qnoFsusGrKfoE38qz9S12oDnkZ9IIkIcV4QPcDNnoXqS0bIn' \
--header 'content-type: application/json' \
--data '
{
"with": "user.analytics"
}
'
Note that the response will include an analytics object, which contains key metrics about the user.
More about analytics: https://developers.referral-factory.com/reference/user-relations
If you need any help, just email [email protected]