Get customer referrals
A referral program is a customer acquisition technique in which existing customers invite others to register. Each participating customer receives a unique referral code to share. When a new customer registers using that code, a link is recorded between the two accounts and any configured incentives are applied according to the referral campaign rules.
The technique is known under several names in the industry:
- Member get member (MGM) - the most common term in loyalty and CRM programs; emphasises that an existing member recruits a new one.
- Refer a friend - the consumer-facing label most often used in marketing communications.
- Friend referral - a variant of the above, common in mobile and e-commerce contexts.
- Referral marketing - the broader marketing discipline term for advocacy-driven acquisition.
In CareCloud, the referral program is configured at the campaign level. A referral campaign defines the code generation method, validity period, and the customer relation type created on a successful referral. This endpoint returns the referral code assigned to a customer for a given campaign.
Get the referral code assigned to a customer. Each referral record contains a unique code that the customer can share to invite others to register. When a new customer registers using the code, a customer relation is created between the new customer and the referral code holder.
Default campaign behaviour
When no referral_campaign_id filter is provided, the result contains the code for the project's default referral campaign. To retrieve a code for a specific campaign, pass the referral_campaign_id filter.
Related: GET /customers
Path parameters
The unique ID of the customer.
Query parameters
The number of records to return in API response.
⚠️ We recommended adjust the batch size based on processing time. Depending on the response time of the request. Default value of 100 records is used if count parameter is not set.
The number of records from a collection to skip. Default value of 0 is used when parameter offset is not set.
Name of the sorting parameter. You can sort by any of the first level parameters from the resource response. Response is sorted by the specified field.
Direction of sorting the response list.
Filters referral codes by validity.
- true or not set (default) - only valid, currently usable referral codes are returned. A code is valid when it is within its own validity period, and its internal state and referral campaign are both active.
- false - only invalid referral codes are returned: codes that are expired, deactivated, or whose referral campaign is no longer active.
The unique ID of the referral campaign. Filters results to the code belonging to this campaign. If omitted, the project's default referral campaign is used.
Filters the result to the referral record matching this specific code. Use this to confirm that a known code belongs to the given customer. If the code does not exist, or does not belong to the given customer, the response returns an empty result set rather than an error.
Headers
The unique ID of the language code by ISO 639-1.
Response
OK
Example response
{
"data": {
"referrals": [
{
"referral_id": "82dbab4209c44c5b04dc3e3d47",
"code": "FRIEND2024",
"customer_id": "8ea2591121e636086a4a9c0992",
"referral_campaign_id": "8bed991c68a470e7aaeffbf048",
"valid_to": "2025-12-31 23:59:59"
}
],
"total_items": 1
}
}