Get Referrals (Lookup)

Retrieves the referee details of a customer (referral).

Using Multiple Identifiers

When dual eligibility is enabled in your organisation, the API allows you to send multiple identifiers while fetching details. The system automatically identifies which one is the primary identifier and retrieves the details accordingly. This removes the need for you to know or specify only the primary identifier. This is beneficial in a dual eligibility–enabled scenario, as the feature allows you to register multiple users with the same secondary identifiers.
When you submit multiple identifiers in a lookup request:

  • The service checks that dual eligibility is active.
  • It parses all submitted identifiers, for example email,mobile,externalId
  • It determines which identifier is configured as the primary key.
  • If one of the provided values matches the primary key, the API uses it for the lookup.
  • The API returns the single customer profile associated with the primary identifier.

You can enter multiple identifiers as comma-separated values using the identifierName and identifierValue query parameters. Ensure the order of the identifierName matches the identifierValue.

Note: If you provide only one identifier that is not the primary identifier, the system will return an error, 8015 - Customer not found for given identifiers.

Endpoint Example

https://eu.api.capillarytech.com/v2/customers/lookup/referrals?source=INSTORE&identifierName=mobile&identifierValue=919777785205&campaignToken=SL7UN

curl --location 'https://eu.api.capillarytech.com/v2/customers/lookup/referrals?source=INSTORE&identifierName=mobile&identifierValue=919777785205&campaignToken=SL7UN' \
--header 'accept: application/json' \
--header 'Authorization: Basic c2FudC5wXzEyMzpiMmVhMGFhYWI1ZThmODg5ZTAzNGE2NjA5NTIwM2FlNw==' \
--header 'Cookie: _cfuvid=CO.TllalaHvEQ_7cFWAUCQBOWoNNXWO0HdpDTfBaBek-1751008162917-0.0.1.1-604800000'

Resource Information

URIv2/customers/lookup/referrals
HTTP methodGET
AuthenticationBasic
Pagination supportYes
Batch supportNA

Query Parameter

ParameterTypeRequiredDescription
sourcestringYesSource system where the referral originated
identifierNamestringYesType of identifier used for lookup
identifierValuestringYesValue of the identifier to lookup
campaignTokenstringYesUnique token identifying the referral campaign
limitintNoMaximum records returned per page
offsetintNoNumber of records skipped (zero-based)
totalintNoTotal records available (not just current page)

Response Parameter

ParameterTypeDescription
customerobjectCustomer details
referralCodestringUnique referral code assigned to customer
inviteesarrayCustomers invited by this customer
refereearrayList of referee details
incentivesarrayIncentives earned via referrals
idlongUnique customer ID
profilesarrayArray of customer profile objects
firstNamestringCustomer's first name
lastNamestringCustomer's last name
fieldsobjectCustom fields (key-value pairs)
allFieldsobjectAll available fields (including system fields)
identifiersarrayActive identifiers (e.g., email, mobile)
commChannelsarrayCommunication channels (e.g., email, SMS)
userIdlongUnique user ID (matches customer.id)
accountIdstringAccount ID (for multi-account systems)
autoUpdateTimestringTimestamp of last profile update (ISO 8601) YY-MM-DD-HH-MM-SS
identifiersAllarrayAll identifiers (including inactive ones)
typestringIdentifier type (e.g., "externalId", "email", "mobile")
valuestringIdentifier value (e.g., email address, phone number)
{
    "pagination": {
        "limit": 10,
        "offset": 0,
        "total": 0
    },
    "data": [
        {
            "customer": {
                "id": 564955301,
                "profiles": [
                    {
                        "firstName": "testgrp3",
                        "lastName": "testgrpv2",
                        "fields": {},
                        "allFields": {},
                        "identifiers": [
                            {
                                "type": "externalId",
                                "value": "434547"
                            },
                            {
                                "type": "email",
                                "value": "[email protected]"
                            },
                            {
                                "type": "mobile",
                                "value": "919777785205"
                            }
                        ],
                        "commChannels": [],
                        "userId": 564955301,
                        "accountId": "",
                        "autoUpdateTime": "2025-06-27T07:22:10Z",
                        "identifiersAll": [
                            {
                                "type": "externalId",
                                "value": "434547"
                            },
                            {
                                "type": "email",
                                "value": "[email protected]"
                            },
                            {
                                "type": "mobile",
                                "value": "919777785205"
                            }
                        ]
                    }
                ]
            },
            "referralCode": "testgrp3rp5ZKo",
            "invitees": [],
            "referee": [],
            "incentives": []
        }
    ],
    "warnings": [],
    "errors": []
}

Error Code

Error CodeDescriptionReason
8015Customer not found for the given identifiersThe identifier provided is incorrect. Also occurs when a customer does not exist and when a lookup uses a valid but non-primary identifier.
8003Invalid sourceUnsupported source passed
8013Lookup,Invalid identifier passedUnsupported identifier value passed
1222Internal error with the referral systemcampaigntoken value is invalid
Language
Credentials
Basic
base64
:
URL
Click Try It! to start a request and see the response here!