> ## Documentation Index > Fetch the complete documentation index at: https://developers.loyaltylion.com/llms.txt > Use this file to discover all available pages before exploring further. # Register Guest Referrer Give a shopper who hasn't joined your program a set of referral links to share. Use this to offer referrals to a visitor before they enrol, for example from a "refer a friend" form that only asks for their name and email. The response carries `referral_urls`, the same set of channel links an enrolled customer has. The shopper is not enrolled by this request: they get a customer record so their referrals have somewhere to be attributed, and if they later enrol with the same email, their referrals carry over. The request is only available when guest referrals are turned on in your referral settings, and your program has an active referral rule. Otherwise it is rejected with `guest_referrals_not_enabled`. The `ip_address` must be the shopper's own address, the one that reached your server, never your server's. Each shopper is rate limited on it, so sending your own address gives every shopper you have one shared allowance. A `429` means that shopper, or your site as a whole, has registered too many guests in a short window: wait and retry. It's safe to retry: registering an address that already holds links returns the same links rather than a second set. If the address belongs to an enrolled member, they keep their membership and the response says nothing about it. When a guest's friend claims the incentive, the claim needs the friend's email address, because there is no membership to attribute the referral to. See `referee_email_required` on [Claim Referee Incentive](/headless-api/2025-06/referrals/claim-referee-incentive). ## OpenAPI ````yaml headless-api/2025-06/openapi.json POST /headless/2025-06/{site_id}/referrals/guest_registrations openapi: 3.1.1 info: title: LoyaltyLion Headless API version: 2025-06 servers: - url: https://api.loyaltylion.com security: [] tags: - name: configuration - name: customers - name: referrals - name: rewards - name: rules paths: /headless/2025-06/{site_id}/referrals/guest_registrations: post: tags: - referrals operationId: referrals.registerGuestReferrer parameters: - name: site_id in: path required: true schema: type: number description: Your LoyaltyLion Site ID requestBody: description: Body content: application/json: schema: $ref: '#/components/schemas/ReferralsRegisterGuestReferrerRequestBody' responses: '200': description: >- The shopper holds referral links. The response is the same whether the address was new or already belonged to a customer, and says nothing about which — a shopper who is already a member keeps the membership they have, and is not enrolled or re-enrolled by this content: application/json: schema: $ref: >- #/components/schemas/ReferralsRegisterGuestReferrerResponseBody '400': $ref: '#/components/responses/ClientErrorBadRequest' '401': description: '401' content: application/json: schema: type: object properties: error: type: object properties: message: type: string code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false required: - error additionalProperties: false '403': description: '403' content: application/json: schema: type: object properties: error: type: object properties: message: type: string code: type: string details: type: object propertyNames: type: string additionalProperties: type: string required: - message additionalProperties: false required: - error additionalProperties: false '422': description: '422' content: application/json: schema: type: object properties: error: oneOf: - $ref: >- #/components/schemas/RegisterGuestReferrerErrorGuestReferralsNotEnabled - $ref: >- #/components/schemas/RegisterGuestReferrerErrorCustomerBlocked - $ref: >- #/components/schemas/RegisterGuestReferrerErrorMerchantCustomerPushFailed type: object discriminator: propertyName: code mapping: guest_referrals_not_enabled: >- #/components/schemas/RegisterGuestReferrerErrorGuestReferralsNotEnabled customer_blocked: >- #/components/schemas/RegisterGuestReferrerErrorCustomerBlocked merchant_customer_push_failed: >- #/components/schemas/RegisterGuestReferrerErrorMerchantCustomerPushFailed required: - error additionalProperties: false '429': description: >- Too many registrations. On top of your program's API rate limit, this route limits registrations per shopper IP address and caps how many one site can take at once, so a request can be rejected here while the rest of your integration is well inside its limit content: application/json: schema: type: object properties: error: type: object properties: code: type: string enum: - rate_limited required: - code additionalProperties: false required: - error additionalProperties: false description: >- Too many registrations. On top of your program's API rate limit, this route limits registrations per shopper IP address and caps how many one site can take at once, so a request can be rejected here while the rest of your integration is well inside its limit security: - ProgramApiKey: - write_customers components: schemas: ReferralsRegisterGuestReferrerRequestBody: type: object properties: email: type: string format: email pattern: >- ^(?!\.)(?!.*\.\.)([A-Za-z0-9_'+\-\.]*)[A-Za-z0-9_+-]@([A-Za-z0-9][A-Za-z0-9\-]*\.)+[A-Za-z]{2,}$ description: >- The email address of the shopper taking a referral link. It is what their referrals are attributed to, and what a later enrollment is matched against Repeating the request with an address that already holds links returns the same ones rather than a second set example: referrer@example.com first_name: type: string minLength: 1 description: >- The shopper's first name, recorded on the customer created for them. Applied only on creation: an address that already belongs to a customer keeps the name it has example: Ada ip_address: anyOf: - type: string format: ipv4 pattern: >- ^(?:(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])\.){3}(?:25[0-5]|2[0-4][0-9]|1[0-9][0-9]|[1-9][0-9]|[0-9])$ - type: string format: ipv6 pattern: >- ^(([0-9a-fA-F]{1,4}:){7}[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,7}:|([0-9a-fA-F]{1,4}:){1,6}:[0-9a-fA-F]{1,4}|([0-9a-fA-F]{1,4}:){1,5}(:[0-9a-fA-F]{1,4}){1,2}|([0-9a-fA-F]{1,4}:){1,4}(:[0-9a-fA-F]{1,4}){1,3}|([0-9a-fA-F]{1,4}:){1,3}(:[0-9a-fA-F]{1,4}){1,4}|([0-9a-fA-F]{1,4}:){1,2}(:[0-9a-fA-F]{1,4}){1,5}|[0-9a-fA-F]{1,4}:((:[0-9a-fA-F]{1,4}){1,6})|:((:[0-9a-fA-F]{1,4}){1,7}|:))$ description: >- The IP address of the shopper taking the link — the one that reached your server, not your server's own. It is the bucket an individual shopper is rate limited on, so sending your own address throttles every shopper you have to a single shared allowance Send a single address. A forwarded-for list is rejected: take the client entry from it yourself example: 203.0.113.42 required: - email - first_name - ip_address additionalProperties: false ReferralsRegisterGuestReferrerResponseBody: type: object properties: referral_urls: type: object properties: direct: type: string description: >- A generic referral link that is not associated with any particular platform facebook: type: string description: A referral link intended for sharing on Facebook twitter: type: string description: A referral link intended for sharing on Twitter email: type: string description: A referral link intended for sharing via email whatsapp: type: string description: A referral link intended for sharing via WhatsApp instagram: type: string description: A referral link intended for sharing on Instagram device_share: type: string description: >- A referral link intended for sharing via a mobile device share prompt required: - direct - facebook - twitter - email - whatsapp - instagram - device_share additionalProperties: false description: >- The links this shopper shares, one per channel — the same set an enrolled customer's `referral_urls` carries required: - referral_urls additionalProperties: false description: >- The shopper holds referral links. The response is the same whether the address was new or already belonged to a customer, and says nothing about which — a shopper who is already a member keeps the membership they have, and is not enrolled or re-enrolled by this RegisterGuestReferrerErrorGuestReferralsNotEnabled: type: object properties: code: type: string const: guest_referrals_not_enabled required: - code additionalProperties: false title: Guest referrals not enabled description: >- This site does not hand referral links to shoppers who have not joined the program, or it has no active referral rule for a referral to pay out against RegisterGuestReferrerErrorCustomerBlocked: type: object properties: code: type: string const: customer_blocked required: - code additionalProperties: false title: Customer blocked description: >- This address belongs to a customer who is blocked from the program. A blocked customer's referrals earn nothing, so no links are issued RegisterGuestReferrerErrorMerchantCustomerPushFailed: type: object properties: code: type: string const: merchant_customer_push_failed required: - code additionalProperties: false title: Merchant customer push failed description: >- Your store is set to receive these shoppers as customers, and we could not create this one there, so no links were issued. The LoyaltyLion customer exists either way, so a retry picks that one up rather than duplicating them responses: ClientErrorBadRequest: description: Bad Request content: application/json: schema: type: object properties: error: type: object properties: message: type: string details: type: object additionalProperties: type: string required: - message required: - error securitySchemes: ProgramApiKey: type: http scheme: bearer description: >- An API key linked to a Program in LoyaltyLion, with a set of permissions (scopes). API keys can be created manually, or acquired through an OAuth2 flow. The API key should be provided as a `Bearer` token in the `Authorization` header ````