# Referral Code
Endpoints for working with referral codes: look up a code and its associated reward, or apply a code to a referred account. For background on what referral codes are, see the Referral Code Overview.
## Lookup a referral code
> \*\*Deprecated.\*\* Use the Open Endpoint \*Lookup a referral code\* instead.\
> \
> Returns a referral code along with the referrer's name and the reward the code unlocks.
```json
{"openapi":"3.1.0","info":{"title":"impact.com API - Referral Code","version":"1.0.0"},"tags":[{"name":"Referral Code","description":"Endpoints for working with referral codes: look up a code and its associated reward, or apply a code to a referred account. For background on what referral codes are, see the Referral Code Overview.\n"}],"servers":[{"url":"https://app.referralsaasquatch.com/api/v1"}],"security":[{"APIKey":[]},{"UserJWT":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"basic","description":"Authorize your requests using a tenant's API Key. Use this method only in server-to-server interactions."},"UserJWT":{"type":"apiKey","in":"header","name":"X-SaaSquatch-User-Token","description":"A JWT for a given user. Used by the Mobile and Web SDKs and other client-side contexts via Open Endpoints."}},"parameters":{"TenantAlias":{"name":"tenant_alias","in":"path","description":"Tenant being referenced. E.g. `\"aboih12h16t\"` or `\"test_abo912126tastastt\"`","required":true,"schema":{"type":"string"}}},"schemas":{"Code":{"description":"A referral code, the referrer it belongs to, and details of the reward it unlocks.","type":"object","properties":{"code":{"type":"string","description":"The unique identifier for the code. For example `BOBTESTERSON`."},"dateCreated":{"type":"integer","format":"int64","description":"Unix timestamp (milliseconds) when the code was created."},"programId":{"type":"string","nullable":true,"description":"The ID of the program that the code belongs to. Null if not associated with a specific program."},"referrerName":{"type":"string","description":"The display name of the owner of this code. For example `Bob Testerson`."},"reward":{"$ref":"#/components/schemas/RewardTemplate"}}},"RewardTemplate":{"description":"Details of the reward that could be earned, but is not yet earned.","type":"object","properties":{"type":{"type":"string","description":"The type of reward.","enum":["PCT_DISCOUNT","FUELTANK","CREDIT","INTEGRATION"]},"unit":{"type":"string","description":"An identifier for the unit of the reward. For example `CENTS`, `freemb`, `freemonth`. Only present for `CREDIT` rewards."},"credit":{"type":"integer","description":"The amount of credit this referral code is valid for. For example, for $20 this would be `credit=2000`, `unit=\"CENTS\"`. Only works with `CREDIT`."},"discountPercent":{"type":"integer","description":"The percent discount the referral code is valid for. For example, `10` for `10%`. Only works with `PCT_DISCOUNT`."},"monthsDiscountIsValid":{"type":"integer","description":"The number of months the discount is valid for. Only works with `PCT_DISCOUNT`."},"valueInCents":{"type":"integer","description":"The value of the reward in cents. Works with `INTEGRATION`."},"rewardDetails":{"type":"string","description":"JSON object containing details about the reward. Works with `INTEGRATION`."}}},"Error":{"properties":{"statusCode":{"description":"The HTTP status code of the error.","type":"integer","format":"int32"},"message":{"description":"The human-readable description of what went wrong. Use this to help you debug.","type":"string"},"apiErrorCode":{"description":"A machine-readable error code.","type":"string"},"rsCode":{"description":"A secondary machine-readable error code.","type":"string"}}}},"responses":{"GeneralError":{"description":"Unexpected Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/{tenant_alias}/code/{code}":{"get":{"summary":"Lookup a referral code","description":"**Deprecated.** Use the Open Endpoint *Lookup a referral code* instead.\n\nReturns a referral code along with the referrer's name and the reward the code unlocks.\n","operationId":"getCode","deprecated":true,"tags":["Referral Code","Deprecated"],"parameters":[{"$ref":"#/components/parameters/TenantAlias"},{"name":"code","in":"path","description":"The referral code to look up, for example `BOBTESTERSON`. Can be a user's primary or non-primary referral code.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Referral code found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Code"}}}},"404":{"description":"Referral code NOT found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"default":{"$ref":"#/components/responses/GeneralError"}}}}}}
```
## Lookup a referral code (Open Endpoint)
> Returns a referral code along with the referrer's name and the reward the code unlocks. Use this from client-side contexts such as the Mobile and Web SDKs.\
> \
> This is an \[Open Endpoint]\() and is disabled by default. Contact support to enable open endpoints.
```json
{"openapi":"3.1.0","info":{"title":"impact.com API - Referral Code","version":"1.0.0"},"tags":[{"name":"Referral Code","description":"Endpoints for working with referral codes: look up a code and its associated reward, or apply a code to a referred account. For background on what referral codes are, see the Referral Code Overview.\n"}],"servers":[{"url":"https://app.referralsaasquatch.com/api/v1"}],"security":[{"APIKey":[]},{"UserJWT":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"basic","description":"Authorize your requests using a tenant's API Key. Use this method only in server-to-server interactions."},"UserJWT":{"type":"apiKey","in":"header","name":"X-SaaSquatch-User-Token","description":"A JWT for a given user. Used by the Mobile and Web SDKs and other client-side contexts via Open Endpoints."}},"parameters":{"TenantAlias":{"name":"tenant_alias","in":"path","description":"Tenant being referenced. E.g. `\"aboih12h16t\"` or `\"test_abo912126tastastt\"`","required":true,"schema":{"type":"string"}}},"schemas":{"CodeClassicReward":{"description":"A referral code, the referrer it belongs to, and details of the reward it unlocks (Classic reward format).","type":"object","properties":{"code":{"type":"string","description":"The unique identifier for the code. For example `BOBTESTERSON`."},"dateCreated":{"type":"integer","format":"int64","description":"Unix timestamp (milliseconds) when the code was created."},"programId":{"type":"string","nullable":true,"description":"The ID of the program that the code belongs to. Null if not associated with a specific program."},"referrerName":{"type":"string","description":"The display name of the owner of this code. For example `Bob Testerson`."},"reward":{"$ref":"#/components/schemas/ClassicRewardTemplate"}}},"ClassicRewardTemplate":{"description":"Classic Only Details of the reward that could be earned, but is not yet earned.","allOf":[{"$ref":"#/components/schemas/RewardTemplate"}]},"RewardTemplate":{"description":"Details of the reward that could be earned, but is not yet earned.","type":"object","properties":{"type":{"type":"string","description":"The type of reward.","enum":["PCT_DISCOUNT","FUELTANK","CREDIT","INTEGRATION"]},"unit":{"type":"string","description":"An identifier for the unit of the reward. For example `CENTS`, `freemb`, `freemonth`. Only present for `CREDIT` rewards."},"credit":{"type":"integer","description":"The amount of credit this referral code is valid for. For example, for $20 this would be `credit=2000`, `unit=\"CENTS\"`. Only works with `CREDIT`."},"discountPercent":{"type":"integer","description":"The percent discount the referral code is valid for. For example, `10` for `10%`. Only works with `PCT_DISCOUNT`."},"monthsDiscountIsValid":{"type":"integer","description":"The number of months the discount is valid for. Only works with `PCT_DISCOUNT`."},"valueInCents":{"type":"integer","description":"The value of the reward in cents. Works with `INTEGRATION`."},"rewardDetails":{"type":"string","description":"JSON object containing details about the reward. Works with `INTEGRATION`."}}},"Error":{"properties":{"statusCode":{"description":"The HTTP status code of the error.","type":"integer","format":"int32"},"message":{"description":"The human-readable description of what went wrong. Use this to help you debug.","type":"string"},"apiErrorCode":{"description":"A machine-readable error code.","type":"string"},"rsCode":{"description":"A secondary machine-readable error code.","type":"string"}}}}},"paths":{"/{tenant_alias}/open/code/{referral_code}":{"get":{"summary":"Lookup a referral code (Open Endpoint)","description":"Returns a referral code along with the referrer's name and the reward the code unlocks. Use this from client-side contexts such as the Mobile and Web SDKs.\n\nThis is an [Open Endpoint](https://integrations.impact.com/impact-brand/reference/api-open-endpoints) and is disabled by default. Contact support to enable open endpoints.\n","operationId":"openValidateCode","tags":["Referral Code","Open Endpoint"],"parameters":[{"$ref":"#/components/parameters/TenantAlias"},{"name":"referral_code","in":"path","description":"The code to be validated, for example `BOBTESTERSON`. Can be a user's primary or non-primary referral code.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Referral code found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CodeClassicReward"}}}},"403":{"description":"Endpoint disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Apply a referral code
> Applies a referral code to the specified account and user, marking them as referred by the code's owner.\
> \
> Requires a \[write token]\() or an API key. This is an \[Open Endpoint]\() and is disabled by default. Contact support to enable open endpoints.
```json
{"openapi":"3.1.0","info":{"title":"impact.com API - Referral Code","version":"1.0.0"},"tags":[{"name":"Referral Code","description":"Endpoints for working with referral codes: look up a code and its associated reward, or apply a code to a referred account. For background on what referral codes are, see the Referral Code Overview.\n"}],"servers":[{"url":"https://app.referralsaasquatch.com/api/v1"}],"security":[{"APIKey":[]},{"UserJWT":[]}],"components":{"securitySchemes":{"APIKey":{"type":"http","scheme":"basic","description":"Authorize your requests using a tenant's API Key. Use this method only in server-to-server interactions."},"UserJWT":{"type":"apiKey","in":"header","name":"X-SaaSquatch-User-Token","description":"A JWT for a given user. Used by the Mobile and Web SDKs and other client-side contexts via Open Endpoints."}},"parameters":{"TenantAlias":{"name":"tenant_alias","in":"path","description":"Tenant being referenced. E.g. `\"aboih12h16t\"` or `\"test_abo912126tastastt\"`","required":true,"schema":{"type":"string"}}},"schemas":{"Code":{"description":"A referral code, the referrer it belongs to, and details of the reward it unlocks.","type":"object","properties":{"code":{"type":"string","description":"The unique identifier for the code. For example `BOBTESTERSON`."},"dateCreated":{"type":"integer","format":"int64","description":"Unix timestamp (milliseconds) when the code was created."},"programId":{"type":"string","nullable":true,"description":"The ID of the program that the code belongs to. Null if not associated with a specific program."},"referrerName":{"type":"string","description":"The display name of the owner of this code. For example `Bob Testerson`."},"reward":{"$ref":"#/components/schemas/RewardTemplate"}}},"RewardTemplate":{"description":"Details of the reward that could be earned, but is not yet earned.","type":"object","properties":{"type":{"type":"string","description":"The type of reward.","enum":["PCT_DISCOUNT","FUELTANK","CREDIT","INTEGRATION"]},"unit":{"type":"string","description":"An identifier for the unit of the reward. For example `CENTS`, `freemb`, `freemonth`. Only present for `CREDIT` rewards."},"credit":{"type":"integer","description":"The amount of credit this referral code is valid for. For example, for $20 this would be `credit=2000`, `unit=\"CENTS\"`. Only works with `CREDIT`."},"discountPercent":{"type":"integer","description":"The percent discount the referral code is valid for. For example, `10` for `10%`. Only works with `PCT_DISCOUNT`."},"monthsDiscountIsValid":{"type":"integer","description":"The number of months the discount is valid for. Only works with `PCT_DISCOUNT`."},"valueInCents":{"type":"integer","description":"The value of the reward in cents. Works with `INTEGRATION`."},"rewardDetails":{"type":"string","description":"JSON object containing details about the reward. Works with `INTEGRATION`."}}},"Error":{"properties":{"statusCode":{"description":"The HTTP status code of the error.","type":"integer","format":"int32"},"message":{"description":"The human-readable description of what went wrong. Use this to help you debug.","type":"string"},"apiErrorCode":{"description":"A machine-readable error code.","type":"string"},"rsCode":{"description":"A secondary machine-readable error code.","type":"string"}}}}},"paths":{"/{tenant_alias}/open/code/{code}/account/{accountId}/user/{userId}":{"post":{"summary":"Apply a referral code","description":"Applies a referral code to the specified account and user, marking them as referred by the code's owner.\n\nRequires a [write token](https://integrations.impact.com/impact-brand/reference/api-open-endpoints) or an API key. This is an [Open Endpoint](https://integrations.impact.com/impact-brand/reference/api-open-endpoints) and is disabled by default. Contact support to enable open endpoints.\n","operationId":"openApplyCode","tags":["Referral Code","Open Endpoint"],"parameters":[{"$ref":"#/components/parameters/TenantAlias"},{"name":"code","in":"path","description":"The referral code to apply to the user's account.","required":true,"schema":{"type":"string"}},{"name":"accountId","in":"path","description":"The account to apply the referral code to. This account will be marked as referred by the owner of the code.","required":true,"schema":{"type":"string"}},{"name":"userId","in":"path","description":"The user to apply the referral code to. This user will be marked as referred by the owner of the code.","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"Referral code applied","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Code"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"Endpoint disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
---
# Agent Instructions: Querying This Documentation
If you need additional information that is not directly available in this page, you can query the documentation dynamically by asking a question.
Perform an HTTP GET request on the current page URL with the `ask` query parameter:
```
GET https://integrations.impact.com/brand-api-reference/advocate-api-reference-v1/reference/referral-code-overview/referral-code.md?ask=
```
The question should be specific, self-contained, and written in natural language.
The response will contain a direct answer to the question and relevant excerpts and sources from the documentation.
Use this mechanism when the answer is not explicitly present in the current page, you need clarification or additional context, or you want to retrieve related documentation sections.