> For the complete documentation index, see [llms.txt](https://integrations.impact.com/llms.txt). Markdown versions of documentation pages are available by appending `.md` to page URLs; this page is available as [Markdown](https://integrations.impact.com/brand-api-reference/advocate-api-reference-v1/reference/user-overview/user.md).
# User
API for managing users, including creation, lookup, and blocking.
## Lookup a user by Referral Code
> Looks up a user based upon their \`referralCode\` and returns their personal information.\
> This method is useful for retrieving the user when only the Referral Code is available.
```json
{"openapi":"3.1.0","info":{"title":"impact.com API - User","version":"2.0.0"},"tags":[{"name":"User","description":"API for managing users, including creation, lookup, and blocking."}],"servers":[{"url":"https://app.referralsaasquatch.com/api/v1","description":"Production Server"}],"security":[{"APIKey":[]}],"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."}},"parameters":{"tenant_alias":{"name":"tenant_alias","in":"path","description":"Tenant being referenced. E.g. `\"aboih12h16t\"`","required":true,"schema":{"type":"string"}}},"schemas":{"User":{"description":"A user in the impact.com referral program.","type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the user."},"accountId":{"type":"string","description":"The unique identifier of the account the user belongs to."},"firstName":{"type":"string","description":"The user's first name."},"lastName":{"type":"string","description":"The user's last name."},"lastInitial":{"type":"string","description":"The first initial of the user's last name."},"email":{"type":"string","format":"email","description":"The user's email address."},"emailHash":{"type":"string","description":"An MD5 hash of the user's email address."},"imageUrl":{"type":"string","description":"URL of the user's profile image. Empty string if not set."},"referralCode":{"type":"string","description":"The user's primary referral code."},"cookieId":{"type":"string","nullable":true,"description":"The cookie ID associated with this user."},"paymentProviderId":{"type":"string","nullable":true,"description":"The ID of the user in the payment provider system."},"locale":{"type":"string","nullable":true,"description":"The user's locale (e.g. `en_US`)."},"countryCode":{"type":"string","nullable":true,"description":"The user's ISO 3166-1 Alpha-2 country code (e.g. `US`)."},"referralSource":{"type":"string","nullable":true,"description":"The source of the user's referral."},"firstSeenIP":{"type":"string","nullable":true,"description":"The IP address the user was first seen from."},"lastSeenIP":{"type":"string","nullable":true,"description":"The IP address the user was last seen from."},"dateCreated":{"type":"integer","format":"int64","description":"Unix timestamp (milliseconds) when the user was created."},"dateBlocked":{"type":"integer","format":"int64","nullable":true,"description":"Unix timestamp (milliseconds) when the user was blocked. Null if not blocked."},"shareLinks":{"$ref":"#/components/schemas/Sharelink"}}},"Sharelink":{"description":"Legacy flat-format share links for a user, organised by share medium and engagement medium.","type":"object","properties":{"shareLink":{"type":"string","format":"uri","description":"The user's primary share link."},"facebookShareLink":{"type":"string","format":"uri","description":"The share link for Facebook."},"twitterShareLink":{"type":"string","format":"uri","description":"The share link for Twitter."},"emailShareLink":{"type":"string","format":"uri","description":"The share link for Email."},"linkedinShareLink":{"type":"string","format":"uri","description":"The share link for LinkedIn."},"mobileShareLink":{"type":"string","format":"uri","description":"The share link for mobile devices."},"mobileFacebookShareLink":{"type":"string","format":"uri","description":"The share link for Facebook on mobile."},"mobileTwitterShareLink":{"type":"string","format":"uri","description":"The share link for Twitter on mobile."},"mobileEmailShareLink":{"type":"string","format":"uri","description":"The share link for Email on mobile."},"EMBED":{"$ref":"#/components/schemas/SharelinkEngagementMedium"},"POPUP":{"$ref":"#/components/schemas/SharelinkEngagementMedium"},"HOSTED":{"$ref":"#/components/schemas/SharelinkEngagementMedium"},"MOBILE":{"$ref":"#/components/schemas/SharelinkEngagementMedium"},"EMAIL":{"$ref":"#/components/schemas/SharelinkEngagementMedium"}}},"SharelinkEngagementMedium":{"description":"Share links for a single engagement medium in the legacy flat format.","type":"object","properties":{"shareLink":{"type":"string","format":"uri","description":"The primary share link for this engagement medium."},"facebookShareLink":{"type":"string","format":"uri","description":"The Facebook share link for this engagement medium."},"twitterShareLink":{"type":"string","format":"uri","description":"The Twitter share link for this engagement medium."},"emailShareLink":{"type":"string","format":"uri","description":"The Email share link for this engagement medium."},"linkedinShareLink":{"type":"string","format":"uri","description":"The LinkedIn share link for this engagement medium."}}},"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}/user":{"get":{"summary":"Lookup a user by Referral Code","operationId":"findUserByReferralCode","tags":["User"],"description":"Looks up a user based upon their `referralCode` and returns their personal information.\nThis method is useful for retrieving the user when only the Referral Code is available.\n","parameters":[{"$ref":"#/components/parameters/tenant_alias"},{"name":"referralCode","in":"query","required":true,"schema":{"type":"string"},"description":"The `referralCode` of the user you want to retrieve."}],"responses":{"200":{"description":"User found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"404":{"description":"User NOT found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Create or Update a User
> This method creates or updates a User object by performing an atomic upsert operation.\
> This method will not create or update the Account linked by \`accountId\`.
```json
{"openapi":"3.1.0","info":{"title":"impact.com API - User","version":"2.0.0"},"tags":[{"name":"User","description":"API for managing users, including creation, lookup, and blocking."}],"servers":[{"url":"https://app.referralsaasquatch.com/api/v1","description":"Production Server"}],"security":[{"APIKey":[]}],"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."}},"parameters":{"tenant_alias":{"name":"tenant_alias","in":"path","description":"Tenant being referenced. E.g. `\"aboih12h16t\"`","required":true,"schema":{"type":"string"}}},"schemas":{"UserStub":{"description":"Request body for creating or updating a user.","required":["id","accountId"],"properties":{"id":{"type":"string","description":"The unique identifier for the user."},"accountId":{"type":"string","description":"The unique identifier of the account the user belongs to."},"firstName":{"type":"string","description":"The user's first name."},"lastName":{"type":"string","description":"The user's last name."},"email":{"type":"string","format":"email","description":"The user's email address."},"locale":{"type":"string","description":"The user's locale (e.g. `en_US`)."},"countryCode":{"type":"string","description":"The user's ISO 3166-1 Alpha-2 country code (e.g. `US`)."},"referralCode":{"type":"string","description":"A custom referral code to assign to the user."},"customFields":{"type":"object","additionalProperties":true,"description":"Custom fields for this user."}}},"User":{"description":"A user in the impact.com referral program.","type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the user."},"accountId":{"type":"string","description":"The unique identifier of the account the user belongs to."},"firstName":{"type":"string","description":"The user's first name."},"lastName":{"type":"string","description":"The user's last name."},"lastInitial":{"type":"string","description":"The first initial of the user's last name."},"email":{"type":"string","format":"email","description":"The user's email address."},"emailHash":{"type":"string","description":"An MD5 hash of the user's email address."},"imageUrl":{"type":"string","description":"URL of the user's profile image. Empty string if not set."},"referralCode":{"type":"string","description":"The user's primary referral code."},"cookieId":{"type":"string","nullable":true,"description":"The cookie ID associated with this user."},"paymentProviderId":{"type":"string","nullable":true,"description":"The ID of the user in the payment provider system."},"locale":{"type":"string","nullable":true,"description":"The user's locale (e.g. `en_US`)."},"countryCode":{"type":"string","nullable":true,"description":"The user's ISO 3166-1 Alpha-2 country code (e.g. `US`)."},"referralSource":{"type":"string","nullable":true,"description":"The source of the user's referral."},"firstSeenIP":{"type":"string","nullable":true,"description":"The IP address the user was first seen from."},"lastSeenIP":{"type":"string","nullable":true,"description":"The IP address the user was last seen from."},"dateCreated":{"type":"integer","format":"int64","description":"Unix timestamp (milliseconds) when the user was created."},"dateBlocked":{"type":"integer","format":"int64","nullable":true,"description":"Unix timestamp (milliseconds) when the user was blocked. Null if not blocked."},"shareLinks":{"$ref":"#/components/schemas/Sharelink"}}},"Sharelink":{"description":"Legacy flat-format share links for a user, organised by share medium and engagement medium.","type":"object","properties":{"shareLink":{"type":"string","format":"uri","description":"The user's primary share link."},"facebookShareLink":{"type":"string","format":"uri","description":"The share link for Facebook."},"twitterShareLink":{"type":"string","format":"uri","description":"The share link for Twitter."},"emailShareLink":{"type":"string","format":"uri","description":"The share link for Email."},"linkedinShareLink":{"type":"string","format":"uri","description":"The share link for LinkedIn."},"mobileShareLink":{"type":"string","format":"uri","description":"The share link for mobile devices."},"mobileFacebookShareLink":{"type":"string","format":"uri","description":"The share link for Facebook on mobile."},"mobileTwitterShareLink":{"type":"string","format":"uri","description":"The share link for Twitter on mobile."},"mobileEmailShareLink":{"type":"string","format":"uri","description":"The share link for Email on mobile."},"EMBED":{"$ref":"#/components/schemas/SharelinkEngagementMedium"},"POPUP":{"$ref":"#/components/schemas/SharelinkEngagementMedium"},"HOSTED":{"$ref":"#/components/schemas/SharelinkEngagementMedium"},"MOBILE":{"$ref":"#/components/schemas/SharelinkEngagementMedium"},"EMAIL":{"$ref":"#/components/schemas/SharelinkEngagementMedium"}}},"SharelinkEngagementMedium":{"description":"Share links for a single engagement medium in the legacy flat format.","type":"object","properties":{"shareLink":{"type":"string","format":"uri","description":"The primary share link for this engagement medium."},"facebookShareLink":{"type":"string","format":"uri","description":"The Facebook share link for this engagement medium."},"twitterShareLink":{"type":"string","format":"uri","description":"The Twitter share link for this engagement medium."},"emailShareLink":{"type":"string","format":"uri","description":"The Email share link for this engagement medium."},"linkedinShareLink":{"type":"string","format":"uri","description":"The LinkedIn share link for this engagement medium."}}}}},"paths":{"/{tenant_alias}/user":{"post":{"summary":"Create or Update a User","operationId":"createUser","tags":["User"],"description":"This method creates or updates a User object by performing an atomic upsert operation.\nThis method will not create or update the Account linked by `accountId`.\n","parameters":[{"$ref":"#/components/parameters/tenant_alias"}],"requestBody":{"description":"Details of the User to be created or updated","required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserStub"}}}},"responses":{"200":{"description":"User Created or Updated","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}}}}}}}
```
## Lookup a user
> Looks up a user based upon their \`id\` and returns their personal information.\
> This method just returns the details of the user in question, and not all associated properties like Rewards, Balances, or Referrals.
```json
{"openapi":"3.1.0","info":{"title":"impact.com API - User","version":"2.0.0"},"tags":[{"name":"User","description":"API for managing users, including creation, lookup, and blocking."}],"servers":[{"url":"https://app.referralsaasquatch.com/api/v1","description":"Production Server"}],"security":[{"APIKey":[]}],"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."}},"parameters":{"tenant_alias":{"name":"tenant_alias","in":"path","description":"Tenant being referenced. E.g. `\"aboih12h16t\"`","required":true,"schema":{"type":"string"}},"accountId":{"name":"accountId","in":"path","description":"The ID of the account.","required":true,"schema":{"type":"string"}},"userId":{"name":"userId","in":"path","description":"The ID of the user.","required":true,"schema":{"type":"string"}}},"schemas":{"User":{"description":"A user in the impact.com referral program.","type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the user."},"accountId":{"type":"string","description":"The unique identifier of the account the user belongs to."},"firstName":{"type":"string","description":"The user's first name."},"lastName":{"type":"string","description":"The user's last name."},"lastInitial":{"type":"string","description":"The first initial of the user's last name."},"email":{"type":"string","format":"email","description":"The user's email address."},"emailHash":{"type":"string","description":"An MD5 hash of the user's email address."},"imageUrl":{"type":"string","description":"URL of the user's profile image. Empty string if not set."},"referralCode":{"type":"string","description":"The user's primary referral code."},"cookieId":{"type":"string","nullable":true,"description":"The cookie ID associated with this user."},"paymentProviderId":{"type":"string","nullable":true,"description":"The ID of the user in the payment provider system."},"locale":{"type":"string","nullable":true,"description":"The user's locale (e.g. `en_US`)."},"countryCode":{"type":"string","nullable":true,"description":"The user's ISO 3166-1 Alpha-2 country code (e.g. `US`)."},"referralSource":{"type":"string","nullable":true,"description":"The source of the user's referral."},"firstSeenIP":{"type":"string","nullable":true,"description":"The IP address the user was first seen from."},"lastSeenIP":{"type":"string","nullable":true,"description":"The IP address the user was last seen from."},"dateCreated":{"type":"integer","format":"int64","description":"Unix timestamp (milliseconds) when the user was created."},"dateBlocked":{"type":"integer","format":"int64","nullable":true,"description":"Unix timestamp (milliseconds) when the user was blocked. Null if not blocked."},"shareLinks":{"$ref":"#/components/schemas/Sharelink"}}},"Sharelink":{"description":"Legacy flat-format share links for a user, organised by share medium and engagement medium.","type":"object","properties":{"shareLink":{"type":"string","format":"uri","description":"The user's primary share link."},"facebookShareLink":{"type":"string","format":"uri","description":"The share link for Facebook."},"twitterShareLink":{"type":"string","format":"uri","description":"The share link for Twitter."},"emailShareLink":{"type":"string","format":"uri","description":"The share link for Email."},"linkedinShareLink":{"type":"string","format":"uri","description":"The share link for LinkedIn."},"mobileShareLink":{"type":"string","format":"uri","description":"The share link for mobile devices."},"mobileFacebookShareLink":{"type":"string","format":"uri","description":"The share link for Facebook on mobile."},"mobileTwitterShareLink":{"type":"string","format":"uri","description":"The share link for Twitter on mobile."},"mobileEmailShareLink":{"type":"string","format":"uri","description":"The share link for Email on mobile."},"EMBED":{"$ref":"#/components/schemas/SharelinkEngagementMedium"},"POPUP":{"$ref":"#/components/schemas/SharelinkEngagementMedium"},"HOSTED":{"$ref":"#/components/schemas/SharelinkEngagementMedium"},"MOBILE":{"$ref":"#/components/schemas/SharelinkEngagementMedium"},"EMAIL":{"$ref":"#/components/schemas/SharelinkEngagementMedium"}}},"SharelinkEngagementMedium":{"description":"Share links for a single engagement medium in the legacy flat format.","type":"object","properties":{"shareLink":{"type":"string","format":"uri","description":"The primary share link for this engagement medium."},"facebookShareLink":{"type":"string","format":"uri","description":"The Facebook share link for this engagement medium."},"twitterShareLink":{"type":"string","format":"uri","description":"The Twitter share link for this engagement medium."},"emailShareLink":{"type":"string","format":"uri","description":"The Email share link for this engagement medium."},"linkedinShareLink":{"type":"string","format":"uri","description":"The LinkedIn share link for this engagement medium."}}},"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}/account/{accountId}/user/{userId}":{"get":{"summary":"Lookup a user","operationId":"getUser","tags":["User"],"description":"Looks up a user based upon their `id` and returns their personal information.\nThis method just returns the details of the user in question, and not all associated properties like Rewards, Balances, or Referrals.\n","parameters":[{"$ref":"#/components/parameters/tenant_alias"},{"$ref":"#/components/parameters/accountId"},{"$ref":"#/components/parameters/userId"}],"responses":{"200":{"description":"User found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/User"}}}},"404":{"description":"User NOT found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Lookup a user PII
> Returns details of the personally identifiable information stored in the impact.com system for a specific user.\
> \> 🚧 \*\*Warning!\*\* This method should only be used in connection with data protection and privacy compliance.
```json
{"openapi":"3.1.0","info":{"title":"impact.com API - User","version":"2.0.0"},"tags":[{"name":"User","description":"API for managing users, including creation, lookup, and blocking."}],"servers":[{"url":"https://app.referralsaasquatch.com/api/v1","description":"Production Server"}],"security":[{"APIKey":[]}],"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."}},"parameters":{"tenant_alias":{"name":"tenant_alias","in":"path","description":"Tenant being referenced. E.g. `\"aboih12h16t\"`","required":true,"schema":{"type":"string"}},"accountId":{"name":"accountId","in":"path","description":"The ID of the account.","required":true,"schema":{"type":"string"}},"userId":{"name":"userId","in":"path","description":"The ID of the user.","required":true,"schema":{"type":"string"}}},"schemas":{"UserPII":{"description":"Full personally identifiable information for a user, including rewards, referrals, and share links. Only use in connection with data protection and privacy compliance.","type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the user."},"accountId":{"type":"string","description":"The unique identifier of the account the user belongs to."},"firstName":{"type":"string","description":"The user's first name."},"lastName":{"type":"string","description":"The user's last name."},"lastInitial":{"type":"string","description":"The first initial of the user's last name."},"email":{"type":"string","format":"email","description":"The user's email address."},"emailHash":{"type":"string","description":"An MD5 hash of the user's email address."},"imageUrl":{"type":"string","description":"URL of the user's profile image."},"cookieId":{"type":"string","nullable":true,"description":"The cookie ID associated with this user."},"paymentProviderId":{"type":"string","nullable":true,"description":"The ID of the user in the payment provider system."},"locale":{"type":"string","nullable":true,"description":"The user's locale (e.g. `en_US`)."},"countryCode":{"type":"string","nullable":true,"description":"The user's ISO 3166-1 Alpha-2 country code (e.g. `US`)."},"referable":{"type":"boolean","description":"Whether this user can be referred by another user."},"referralSource":{"type":"string","nullable":true,"description":"The source of the user's referral."},"referralCodes":{"type":"object","additionalProperties":{"type":"string"},"description":"A map of program IDs to the user's referral code for that program."},"firstSeenIP":{"type":"string","nullable":true,"description":"The IP address the user was first seen from."},"lastSeenIP":{"type":"string","nullable":true,"description":"The IP address the user was last seen from."},"firstSeenIPLocation":{"type":"string","nullable":true,"description":"The geographic location derived from `firstSeenIP`."},"lastSeenIPLocation":{"type":"string","nullable":true,"description":"The geographic location derived from `lastSeenIP`."},"firstSeenUserAgent":{"type":"string","nullable":true,"description":"The browser user agent string from the user's first session."},"lastSeenUserAgent":{"type":"string","nullable":true,"description":"The browser user agent string from the user's most recent session."},"dateCreated":{"type":"integer","format":"int64","description":"Unix timestamp (milliseconds) when the user was created."},"customFields":{"type":"object","additionalProperties":true,"description":"Custom fields for this user."},"programShareLinks":{"$ref":"#/components/schemas/ProgramShareLink"},"referredByCodes":{"type":"array","items":{"type":"string"},"description":"Referral codes used to refer this user."},"referredByReferrals":{"type":"array","description":"Referral records where this user was the referred party.","items":{"type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the referral."},"moderationStatus":{"type":"string","description":"The moderation status of the referral."},"dateReferralStarted":{"type":"integer","format":"int64","description":"Unix timestamp (milliseconds) when the referral started."},"dateReferralPaid":{"type":"integer","format":"int64","nullable":true,"description":"Unix timestamp (milliseconds) when the referral was paid."},"dateReferralEnded":{"type":"integer","format":"int64","nullable":true,"description":"Unix timestamp (milliseconds) when the referral ended."},"dateModerated":{"type":"integer","format":"int64","nullable":true,"description":"Unix timestamp (milliseconds) when the referral was moderated."},"referredModerationStatus":{"type":"string","description":"The moderation status of the referred user."},"referrerModerationStatus":{"type":"string","description":"The moderation status of the referrer."},"programId":{"type":"string","nullable":true,"description":"The program ID associated with this referral."},"referredReward":{"type":"object","nullable":true,"description":"The reward earned by the referred user."},"referrerReward":{"type":"object","nullable":true,"description":"The reward earned by the referrer."},"publicMeta":{"type":"object","nullable":true,"description":"Public metadata associated with the referral."},"privateMeta":{"type":"object","nullable":true,"description":"Private metadata associated with the referral."},"fraudSignals":{"type":"object","nullable":true,"description":"Fraud signals detected for this referral."}}}},"rewards":{"type":"object","description":"A paginated list of rewards earned by this user.","properties":{"totalCount":{"type":"integer","description":"Total number of rewards."},"data":{"type":"array","items":{"type":"object"}}}},"rewardBalances":{"type":"array","description":"Aggregated reward balance summaries for this user.","items":{"type":"object","properties":{"type":{"type":"string","description":"The reward type."},"unit":{"type":"string","description":"The unit of the reward."},"count":{"type":"integer","description":"Number of rewards of this type."},"totalAssignedCredit":{"type":"integer","description":"Total credit assigned."},"totalRedeemedCredit":{"type":"integer","description":"Total credit redeemed."},"totalPendingCredit":{"type":"integer","description":"Total credit pending."},"totalExpiredCredit":{"type":"integer","description":"Total credit expired."},"totalCancelledCredit":{"type":"integer","description":"Total credit cancelled."},"prettyAssignedCredit":{"type":"string","description":"Human-readable total assigned credit."},"prettyRedeemedCredit":{"type":"string","description":"Human-readable total redeemed credit."},"prettyPendingCredit":{"type":"string","description":"Human-readable total pending credit."},"value":{"type":"integer","description":"The available (unredeemed) credit balance."},"prettyValue":{"type":"string","description":"Human-readable available balance."}}}},"referrals":{"type":"object","description":"A paginated list of referrals made by this user.","properties":{"totalCount":{"type":"integer","description":"Total number of referrals."},"data":{"type":"array","items":{"type":"object"}}}},"segments":{"type":"array","items":{"type":"string"},"description":"The segments this user belongs to."}}},"ProgramShareLink":{"description":"A map of program IDs to share link sets for that program.","type":"object","additionalProperties":{"type":"object","properties":{"cleanShareLink":{"type":"string","format":"uri","description":"The clean (unencoded) primary share link for this program."},"UNKNOWN":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"EMAIL":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"MOBILE":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"EMBED":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"POPUP":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"HOSTED":{"type":"object","additionalProperties":{"type":"string","format":"uri"}}}}},"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}/account/{accountId}/user/{userId}/pii":{"get":{"summary":"Lookup a user PII","operationId":"getUserPII","tags":["User"],"description":"Returns details of the personally identifiable information stored in the impact.com system for a specific user.\n> 🚧 **Warning!** This method should only be used in connection with data protection and privacy compliance.\n","parameters":[{"$ref":"#/components/parameters/tenant_alias"},{"$ref":"#/components/parameters/accountId"},{"$ref":"#/components/parameters/userId"}],"responses":{"200":{"description":"User found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserPII"}}}},"404":{"description":"User NOT found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Block user
> Block a user from making successful referrals based upon their user and account \`id\`.
```json
{"openapi":"3.1.0","info":{"title":"impact.com API - User","version":"2.0.0"},"tags":[{"name":"User","description":"API for managing users, including creation, lookup, and blocking."}],"servers":[{"url":"https://app.referralsaasquatch.com/api/v1","description":"Production Server"}],"security":[{"APIKey":[]}],"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."}},"parameters":{"tenant_alias":{"name":"tenant_alias","in":"path","description":"Tenant being referenced. E.g. `\"aboih12h16t\"`","required":true,"schema":{"type":"string"}},"accountId":{"name":"accountId","in":"path","description":"The ID of the account.","required":true,"schema":{"type":"string"}},"userId":{"name":"userId","in":"path","description":"The ID of the user.","required":true,"schema":{"type":"string"}}},"schemas":{"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}/account/{accountId}/user/{userId}/block":{"post":{"summary":"Block user","operationId":"blockUser","tags":["User"],"description":"Block a user from making successful referrals based upon their user and account `id`.","parameters":[{"$ref":"#/components/parameters/tenant_alias"},{"$ref":"#/components/parameters/accountId"},{"$ref":"#/components/parameters/userId"}],"responses":{"200":{"description":"User blocked successfully","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"User account NOT found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## Unblock user
> Unblock a user based upon their user and account \`id\`.
```json
{"openapi":"3.1.0","info":{"title":"impact.com API - User","version":"2.0.0"},"tags":[{"name":"User","description":"API for managing users, including creation, lookup, and blocking."}],"servers":[{"url":"https://app.referralsaasquatch.com/api/v1","description":"Production Server"}],"security":[{"APIKey":[]}],"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."}},"parameters":{"tenant_alias":{"name":"tenant_alias","in":"path","description":"Tenant being referenced. E.g. `\"aboih12h16t\"`","required":true,"schema":{"type":"string"}},"accountId":{"name":"accountId","in":"path","description":"The ID of the account.","required":true,"schema":{"type":"string"}},"userId":{"name":"userId","in":"path","description":"The ID of the user.","required":true,"schema":{"type":"string"}}},"schemas":{"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}/account/{accountId}/user/{userId}/unblock":{"post":{"summary":"Unblock user","operationId":"unblockUser","tags":["User"],"description":"Unblock a user based upon their user and account `id`.","parameters":[{"$ref":"#/components/parameters/tenant_alias"},{"$ref":"#/components/parameters/accountId"},{"$ref":"#/components/parameters/userId"}],"responses":{"200":{"description":"User unblocked successfully","content":{"application/json":{"schema":{"type":"object"}}}},"404":{"description":"User account NOT found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}}}
```
## List users
> List all of the users in your Advocate referral programs.\
> This method supports pagination and search queries.
```json
{"openapi":"3.1.0","info":{"title":"impact.com API - User","version":"2.0.0"},"tags":[{"name":"User","description":"API for managing users, including creation, lookup, and blocking."}],"servers":[{"url":"https://app.referralsaasquatch.com/api/v1","description":"Production Server"}],"security":[{"APIKey":[]}],"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."}},"parameters":{"tenant_alias":{"name":"tenant_alias","in":"path","description":"Tenant being referenced. E.g. `\"aboih12h16t\"`","required":true,"schema":{"type":"string"}},"query":{"name":"query","in":"query","description":"A search query that can be used to filter users by email, name or ID.","schema":{"type":"string"}},"limit":{"name":"limit","in":"query","description":"A limit on the number of results returned.","schema":{"type":"integer","default":10}},"offset":{"name":"offset","in":"query","description":"When included, offsets the first result returned in the list.","schema":{"type":"integer","default":0}}},"schemas":{"UserList":{"type":"object","properties":{"count":{"type":"integer"},"totalCount":{"type":"integer"},"users":{"type":"array","items":{"$ref":"#/components/schemas/User"}}}},"User":{"description":"A user in the impact.com referral program.","type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the user."},"accountId":{"type":"string","description":"The unique identifier of the account the user belongs to."},"firstName":{"type":"string","description":"The user's first name."},"lastName":{"type":"string","description":"The user's last name."},"lastInitial":{"type":"string","description":"The first initial of the user's last name."},"email":{"type":"string","format":"email","description":"The user's email address."},"emailHash":{"type":"string","description":"An MD5 hash of the user's email address."},"imageUrl":{"type":"string","description":"URL of the user's profile image. Empty string if not set."},"referralCode":{"type":"string","description":"The user's primary referral code."},"cookieId":{"type":"string","nullable":true,"description":"The cookie ID associated with this user."},"paymentProviderId":{"type":"string","nullable":true,"description":"The ID of the user in the payment provider system."},"locale":{"type":"string","nullable":true,"description":"The user's locale (e.g. `en_US`)."},"countryCode":{"type":"string","nullable":true,"description":"The user's ISO 3166-1 Alpha-2 country code (e.g. `US`)."},"referralSource":{"type":"string","nullable":true,"description":"The source of the user's referral."},"firstSeenIP":{"type":"string","nullable":true,"description":"The IP address the user was first seen from."},"lastSeenIP":{"type":"string","nullable":true,"description":"The IP address the user was last seen from."},"dateCreated":{"type":"integer","format":"int64","description":"Unix timestamp (milliseconds) when the user was created."},"dateBlocked":{"type":"integer","format":"int64","nullable":true,"description":"Unix timestamp (milliseconds) when the user was blocked. Null if not blocked."},"shareLinks":{"$ref":"#/components/schemas/Sharelink"}}},"Sharelink":{"description":"Legacy flat-format share links for a user, organised by share medium and engagement medium.","type":"object","properties":{"shareLink":{"type":"string","format":"uri","description":"The user's primary share link."},"facebookShareLink":{"type":"string","format":"uri","description":"The share link for Facebook."},"twitterShareLink":{"type":"string","format":"uri","description":"The share link for Twitter."},"emailShareLink":{"type":"string","format":"uri","description":"The share link for Email."},"linkedinShareLink":{"type":"string","format":"uri","description":"The share link for LinkedIn."},"mobileShareLink":{"type":"string","format":"uri","description":"The share link for mobile devices."},"mobileFacebookShareLink":{"type":"string","format":"uri","description":"The share link for Facebook on mobile."},"mobileTwitterShareLink":{"type":"string","format":"uri","description":"The share link for Twitter on mobile."},"mobileEmailShareLink":{"type":"string","format":"uri","description":"The share link for Email on mobile."},"EMBED":{"$ref":"#/components/schemas/SharelinkEngagementMedium"},"POPUP":{"$ref":"#/components/schemas/SharelinkEngagementMedium"},"HOSTED":{"$ref":"#/components/schemas/SharelinkEngagementMedium"},"MOBILE":{"$ref":"#/components/schemas/SharelinkEngagementMedium"},"EMAIL":{"$ref":"#/components/schemas/SharelinkEngagementMedium"}}},"SharelinkEngagementMedium":{"description":"Share links for a single engagement medium in the legacy flat format.","type":"object","properties":{"shareLink":{"type":"string","format":"uri","description":"The primary share link for this engagement medium."},"facebookShareLink":{"type":"string","format":"uri","description":"The Facebook share link for this engagement medium."},"twitterShareLink":{"type":"string","format":"uri","description":"The Twitter share link for this engagement medium."},"emailShareLink":{"type":"string","format":"uri","description":"The Email share link for this engagement medium."},"linkedinShareLink":{"type":"string","format":"uri","description":"The LinkedIn share link for this engagement medium."}}}}},"paths":{"/{tenant_alias}/users":{"get":{"summary":"List users","operationId":"listUsers","tags":["User"],"description":"List all of the users in your Advocate referral programs.\nThis method supports pagination and search queries.\n","parameters":[{"$ref":"#/components/parameters/tenant_alias"},{"$ref":"#/components/parameters/query"},{"$ref":"#/components/parameters/limit"},{"$ref":"#/components/parameters/offset"}],"responses":{"200":{"description":"Users found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserList"}}}}}}}}}
```
## Lookup a user (Open Endpoint)
> This method looks up a user based on their \`id\` and returns their personal information including sharelinks. This endpoint requires authentication via a write token or API credentials.
```json
{"openapi":"3.1.0","info":{"title":"impact.com API - User","version":"2.0.0"},"tags":[{"name":"User","description":"API for managing users, including creation, lookup, and blocking."},{"name":"Open Endpoint","description":"Special methods designed for Client-facing applications like the Mobile and Javascript SDKs."}],"servers":[{"url":"https://app.referralsaasquatch.com/api/v1","description":"Production Server"}],"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":{"tenant_alias":{"name":"tenant_alias","in":"path","description":"Tenant being referenced. E.g. `\"aboih12h16t\"`","required":true,"schema":{"type":"string"}},"accountId":{"name":"accountId","in":"path","description":"The ID of the account.","required":true,"schema":{"type":"string"}},"userId":{"name":"userId","in":"path","description":"The ID of the user.","required":true,"schema":{"type":"string"}},"fields":{"name":"fields","in":"query","schema":{"type":"string"},"description":"The fields to be included in the response. Cannot coexist with `extraFields`.","style":"form","explode":false},"extraFields":{"name":"extraFields","in":"query","schema":{"type":"string"},"description":"The fields to be included in the response in addition to all the default fields. Cannot coexist with `fields`.","style":"form","explode":false}},"schemas":{"OpenUser":{"description":"A user object returned by open endpoints. Includes program share links and custom fields.","type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the user."},"accountId":{"type":"string","description":"The unique identifier of the account the user belongs to."},"firstName":{"type":"string","description":"The user's first name."},"lastName":{"type":"string","description":"The user's last name."},"email":{"type":"string","format":"email","description":"The user's email address."},"imageUrl":{"type":"string","description":"URL of the user's profile image."},"cookieId":{"type":"string","nullable":true,"description":"The cookie ID associated with this user."},"locale":{"type":"string","nullable":true,"description":"The user's locale (e.g. `en_US`)."},"countryCode":{"type":"string","nullable":true,"description":"The user's ISO 3166-1 Alpha-2 country code (e.g. `US`)."},"referable":{"type":"boolean","description":"Whether this user can be referred by another user."},"firstSeenIP":{"type":"string","nullable":true,"description":"The IP address the user was first seen from."},"lastSeenIP":{"type":"string","nullable":true,"description":"The IP address the user was last seen from."},"dateCreated":{"type":"integer","format":"int64","description":"Unix timestamp (milliseconds) when the user was created."},"referralCodes":{"type":"object","additionalProperties":{"type":"string"},"description":"A map of program IDs to the user's referral code for that program."},"programShareLinks":{"$ref":"#/components/schemas/ProgramShareLink"},"customFields":{"type":"object","additionalProperties":true,"description":"Custom fields for this user."},"segments":{"type":"array","items":{"type":"string"},"description":"The segments this user belongs to."},"referredByCodes":{"type":"array","items":{"type":"string"},"description":"Referral codes used to refer this user."}}},"ProgramShareLink":{"description":"A map of program IDs to share link sets for that program.","type":"object","additionalProperties":{"type":"object","properties":{"cleanShareLink":{"type":"string","format":"uri","description":"The clean (unencoded) primary share link for this program."},"UNKNOWN":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"EMAIL":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"MOBILE":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"EMBED":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"POPUP":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"HOSTED":{"type":"object","additionalProperties":{"type":"string","format":"uri"}}}}},"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":{"UnauthorizedError":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"ForbiddenError":{"description":"Forbidden/Endpoint Disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFoundError":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/{tenant_alias}/open/account/{accountId}/user/{userId}":{"get":{"summary":"Lookup a user (Open Endpoint)","operationId":"openGetUser","tags":["User","Open Endpoint"],"description":"This method looks up a user based on their `id` and returns their personal information including sharelinks. This endpoint requires authentication via a write token or API credentials.\n","parameters":[{"$ref":"#/components/parameters/tenant_alias"},{"$ref":"#/components/parameters/accountId"},{"$ref":"#/components/parameters/userId"},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/extraFields"}],"responses":{"200":{"description":"User found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenUser"}}}},"401":{"$ref":"#/components/responses/UnauthorizedError"},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"}}}}}}
```
## Create a user and account (Open Endpoint)
> This method creates a user and an account and returns the user object representing that newly created user/account.\
> Because this call creates a user, it requires either a write token or an API key.
```json
{"openapi":"3.1.0","info":{"title":"impact.com API - User","version":"2.0.0"},"tags":[{"name":"User","description":"API for managing users, including creation, lookup, and blocking."},{"name":"Open Endpoint","description":"Special methods designed for Client-facing applications like the Mobile and Javascript SDKs."}],"servers":[{"url":"https://app.referralsaasquatch.com/api/v1","description":"Production Server"}],"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":{"tenant_alias":{"name":"tenant_alias","in":"path","description":"Tenant being referenced. E.g. `\"aboih12h16t\"`","required":true,"schema":{"type":"string"}},"accountId":{"name":"accountId","in":"path","description":"The ID of the account.","required":true,"schema":{"type":"string"}},"userId":{"name":"userId","in":"path","description":"The ID of the user.","required":true,"schema":{"type":"string"}},"fields":{"name":"fields","in":"query","schema":{"type":"string"},"description":"The fields to be included in the response. Cannot coexist with `extraFields`.","style":"form","explode":false},"extraFields":{"name":"extraFields","in":"query","schema":{"type":"string"},"description":"The fields to be included in the response in addition to all the default fields. Cannot coexist with `fields`.","style":"form","explode":false}},"schemas":{"OpenUserUpsert":{"title":"A Open User object for Upsert/Create","description":"An object describing an individual user submitted to an open endpoint when you want to create or update a user.","required":["id","accountId"],"properties":{"id":{"type":"string","description":"The unique identifier provided for this user. Use the user's email as their user Id."},"accountId":{"type":"string","description":"The unique identifier of the account. Value must match `id`. Use the user's email as their account Id."},"firstName":{"type":"string","description":"The user's first name."},"lastName":{"type":"string","description":"The user's last name."},"email":{"type":"string","format":"email","description":"The email address provided for the user."},"referable":{"type":"boolean","description":"Flag to determine whether a user is able to be referred."},"referralCodes":{"type":"object","additionalProperties":{"type":"string"},"description":"The primary custom referral codes for different programs, mapping `programId` to `code`."},"locale":{"type":"string","description":"The user's locale, used for Internationalization (e.g., `en_US`)."},"countryCode":{"type":"string","description":"The user's ISO 3166-1 Alpha-2 country code (e.g., `US`)."},"dateUsTaxFormSubmitted":{"type":"integer","format":"int64","description":"The timestamp of when a user's W-9 tax form was submitted."},"referredByCodes":{"type":"array","items":{"type":"string"},"description":"An array of referral codes used to refer this account."},"cookies":{"type":"string","description":"The Base64URL encoded attribution cookie values."},"segments":{"type":"array","items":{"type":"string"},"description":"A list of operations for adding and removing a user from segments (e.g., `[\"segment1\", \"~segment2\"]`)."},"shareLinks":{"type":"object","additionalProperties":{"type":"string"},"description":"The primary custom shareLinks for different programs, mapping `programId` to `sharelink`."},"customFields":{"type":"object","additionalProperties":true,"description":"An object containing the custom fields for this user."}}},"OpenUser":{"description":"A user object returned by open endpoints. Includes program share links and custom fields.","type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the user."},"accountId":{"type":"string","description":"The unique identifier of the account the user belongs to."},"firstName":{"type":"string","description":"The user's first name."},"lastName":{"type":"string","description":"The user's last name."},"email":{"type":"string","format":"email","description":"The user's email address."},"imageUrl":{"type":"string","description":"URL of the user's profile image."},"cookieId":{"type":"string","nullable":true,"description":"The cookie ID associated with this user."},"locale":{"type":"string","nullable":true,"description":"The user's locale (e.g. `en_US`)."},"countryCode":{"type":"string","nullable":true,"description":"The user's ISO 3166-1 Alpha-2 country code (e.g. `US`)."},"referable":{"type":"boolean","description":"Whether this user can be referred by another user."},"firstSeenIP":{"type":"string","nullable":true,"description":"The IP address the user was first seen from."},"lastSeenIP":{"type":"string","nullable":true,"description":"The IP address the user was last seen from."},"dateCreated":{"type":"integer","format":"int64","description":"Unix timestamp (milliseconds) when the user was created."},"referralCodes":{"type":"object","additionalProperties":{"type":"string"},"description":"A map of program IDs to the user's referral code for that program."},"programShareLinks":{"$ref":"#/components/schemas/ProgramShareLink"},"customFields":{"type":"object","additionalProperties":true,"description":"Custom fields for this user."},"segments":{"type":"array","items":{"type":"string"},"description":"The segments this user belongs to."},"referredByCodes":{"type":"array","items":{"type":"string"},"description":"Referral codes used to refer this user."}}},"ProgramShareLink":{"description":"A map of program IDs to share link sets for that program.","type":"object","additionalProperties":{"type":"object","properties":{"cleanShareLink":{"type":"string","format":"uri","description":"The clean (unencoded) primary share link for this program."},"UNKNOWN":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"EMAIL":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"MOBILE":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"EMBED":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"POPUP":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"HOSTED":{"type":"object","additionalProperties":{"type":"string","format":"uri"}}}}},"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":{"ForbiddenError":{"description":"Forbidden/Endpoint Disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/{tenant_alias}/open/account/{accountId}/user/{userId}":{"post":{"summary":"Create a user and account (Open Endpoint)","operationId":"openCreateUser","tags":["User","Open Endpoint"],"description":"This method creates a user and an account and returns the user object representing that newly created user/account.\nBecause this call creates a user, it requires either a write token or an API key.\n","parameters":[{"$ref":"#/components/parameters/tenant_alias"},{"$ref":"#/components/parameters/accountId"},{"$ref":"#/components/parameters/userId"},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/extraFields"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenUserUpsert"}}}},"responses":{"201":{"description":"Information about the newly created user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenUser"}}}},"403":{"$ref":"#/components/responses/ForbiddenError"}}}}}}
```
## User Upsert (Open Endpoint)
> This method updates/creates a user and an account and returns the user object representing that newly created user/account.\
> Because this call creates a user, it requires either a write token or an API key.
```json
{"openapi":"3.1.0","info":{"title":"impact.com API - User","version":"2.0.0"},"tags":[{"name":"User","description":"API for managing users, including creation, lookup, and blocking."},{"name":"Open Endpoint","description":"Special methods designed for Client-facing applications like the Mobile and Javascript SDKs."}],"servers":[{"url":"https://app.referralsaasquatch.com/api/v1","description":"Production Server"}],"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":{"tenant_alias":{"name":"tenant_alias","in":"path","description":"Tenant being referenced. E.g. `\"aboih12h16t\"`","required":true,"schema":{"type":"string"}},"accountId":{"name":"accountId","in":"path","description":"The ID of the account.","required":true,"schema":{"type":"string"}},"userId":{"name":"userId","in":"path","description":"The ID of the user.","required":true,"schema":{"type":"string"}},"fields":{"name":"fields","in":"query","schema":{"type":"string"},"description":"The fields to be included in the response. Cannot coexist with `extraFields`.","style":"form","explode":false},"extraFields":{"name":"extraFields","in":"query","schema":{"type":"string"},"description":"The fields to be included in the response in addition to all the default fields. Cannot coexist with `fields`.","style":"form","explode":false}},"schemas":{"OpenUserUpsert":{"title":"A Open User object for Upsert/Create","description":"An object describing an individual user submitted to an open endpoint when you want to create or update a user.","required":["id","accountId"],"properties":{"id":{"type":"string","description":"The unique identifier provided for this user. Use the user's email as their user Id."},"accountId":{"type":"string","description":"The unique identifier of the account. Value must match `id`. Use the user's email as their account Id."},"firstName":{"type":"string","description":"The user's first name."},"lastName":{"type":"string","description":"The user's last name."},"email":{"type":"string","format":"email","description":"The email address provided for the user."},"referable":{"type":"boolean","description":"Flag to determine whether a user is able to be referred."},"referralCodes":{"type":"object","additionalProperties":{"type":"string"},"description":"The primary custom referral codes for different programs, mapping `programId` to `code`."},"locale":{"type":"string","description":"The user's locale, used for Internationalization (e.g., `en_US`)."},"countryCode":{"type":"string","description":"The user's ISO 3166-1 Alpha-2 country code (e.g., `US`)."},"dateUsTaxFormSubmitted":{"type":"integer","format":"int64","description":"The timestamp of when a user's W-9 tax form was submitted."},"referredByCodes":{"type":"array","items":{"type":"string"},"description":"An array of referral codes used to refer this account."},"cookies":{"type":"string","description":"The Base64URL encoded attribution cookie values."},"segments":{"type":"array","items":{"type":"string"},"description":"A list of operations for adding and removing a user from segments (e.g., `[\"segment1\", \"~segment2\"]`)."},"shareLinks":{"type":"object","additionalProperties":{"type":"string"},"description":"The primary custom shareLinks for different programs, mapping `programId` to `sharelink`."},"customFields":{"type":"object","additionalProperties":true,"description":"An object containing the custom fields for this user."}}},"OpenUser":{"description":"A user object returned by open endpoints. Includes program share links and custom fields.","type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the user."},"accountId":{"type":"string","description":"The unique identifier of the account the user belongs to."},"firstName":{"type":"string","description":"The user's first name."},"lastName":{"type":"string","description":"The user's last name."},"email":{"type":"string","format":"email","description":"The user's email address."},"imageUrl":{"type":"string","description":"URL of the user's profile image."},"cookieId":{"type":"string","nullable":true,"description":"The cookie ID associated with this user."},"locale":{"type":"string","nullable":true,"description":"The user's locale (e.g. `en_US`)."},"countryCode":{"type":"string","nullable":true,"description":"The user's ISO 3166-1 Alpha-2 country code (e.g. `US`)."},"referable":{"type":"boolean","description":"Whether this user can be referred by another user."},"firstSeenIP":{"type":"string","nullable":true,"description":"The IP address the user was first seen from."},"lastSeenIP":{"type":"string","nullable":true,"description":"The IP address the user was last seen from."},"dateCreated":{"type":"integer","format":"int64","description":"Unix timestamp (milliseconds) when the user was created."},"referralCodes":{"type":"object","additionalProperties":{"type":"string"},"description":"A map of program IDs to the user's referral code for that program."},"programShareLinks":{"$ref":"#/components/schemas/ProgramShareLink"},"customFields":{"type":"object","additionalProperties":true,"description":"Custom fields for this user."},"segments":{"type":"array","items":{"type":"string"},"description":"The segments this user belongs to."},"referredByCodes":{"type":"array","items":{"type":"string"},"description":"Referral codes used to refer this user."}}},"ProgramShareLink":{"description":"A map of program IDs to share link sets for that program.","type":"object","additionalProperties":{"type":"object","properties":{"cleanShareLink":{"type":"string","format":"uri","description":"The clean (unencoded) primary share link for this program."},"UNKNOWN":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"EMAIL":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"MOBILE":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"EMBED":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"POPUP":{"type":"object","additionalProperties":{"type":"string","format":"uri"}},"HOSTED":{"type":"object","additionalProperties":{"type":"string","format":"uri"}}}}},"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":{"ForbiddenError":{"description":"Forbidden/Endpoint Disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}},"paths":{"/{tenant_alias}/open/account/{accountId}/user/{userId}":{"put":{"summary":"User Upsert (Open Endpoint)","operationId":"openUserUpsert","tags":["User","Open Endpoint"],"description":"This method updates/creates a user and an account and returns the user object representing that newly created user/account.\nBecause this call creates a user, it requires either a write token or an API key.\n","parameters":[{"$ref":"#/components/parameters/tenant_alias"},{"$ref":"#/components/parameters/accountId"},{"$ref":"#/components/parameters/userId"},{"$ref":"#/components/parameters/fields"},{"$ref":"#/components/parameters/extraFields"}],"requestBody":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenUserUpsert"}}}},"responses":{"200":{"description":"Information about the upserted user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OpenUser"}}}},"403":{"$ref":"#/components/responses/ForbiddenError"}}}}}}
```
## Delete a user (Open Endpoint)
> Delete a user in your impact.com project. By default this endpoint only deletes a User on an Account (and not the Account itself).
```json
{"openapi":"3.1.0","info":{"title":"impact.com API - User","version":"2.0.0"},"tags":[{"name":"User","description":"API for managing users, including creation, lookup, and blocking."},{"name":"Open Endpoint","description":"Special methods designed for Client-facing applications like the Mobile and Javascript SDKs."}],"servers":[{"url":"https://app.referralsaasquatch.com/api/v1","description":"Production Server"}],"security":[{"APIKey":[]}],"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."}},"parameters":{"tenant_alias":{"name":"tenant_alias","in":"path","description":"Tenant being referenced. E.g. `\"aboih12h16t\"`","required":true,"schema":{"type":"string"}},"accountId":{"name":"accountId","in":"path","description":"The ID of the account.","required":true,"schema":{"type":"string"}},"userId":{"name":"userId","in":"path","description":"The ID of the user.","required":true,"schema":{"type":"string"}}},"responses":{"NotFoundError":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"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/account/{accountId}/user/{userId}":{"delete":{"summary":"Delete a user (Open Endpoint)","operationId":"openDeleteUser","tags":["User","Open Endpoint"],"description":"Delete a user in your impact.com project. By default this endpoint only deletes a User on an Account (and not the Account itself).\n","parameters":[{"$ref":"#/components/parameters/tenant_alias"},{"$ref":"#/components/parameters/accountId"},{"$ref":"#/components/parameters/userId"},{"name":"doNotTrack","in":"query","description":"Do not track this user (this user cannot be re-registered on the same account).","schema":{"type":"boolean"}},{"name":"preserveEmptyAccount","in":"query","description":"Do not delete accounts when all the users in the account are deleted.","schema":{"type":"boolean"}}],"responses":{"204":{"description":"User successfully deleted"},"404":{"$ref":"#/components/responses/NotFoundError"}}}}}}
```
## Get a user by a referral code (Open Endpoint)
> Looks up a user based upon their \`ReferralCode\` and returns their personal information. This is an \[Open Endpoint]\() and disabled by default.
```json
{"openapi":"3.1.0","info":{"title":"impact.com API - User","version":"2.0.0"},"tags":[{"name":"User","description":"API for managing users, including creation, lookup, and blocking."},{"name":"Open Endpoint","description":"Special methods designed for Client-facing applications like the Mobile and Javascript SDKs."}],"servers":[{"url":"https://app.referralsaasquatch.com/api/v1","description":"Production Server"}],"security":[],"paths":{"/{tenant_alias}/open/user":{"get":{"summary":"Get a user by a referral code (Open Endpoint)","operationId":"openGetUserByCode","tags":["User","Open Endpoint"],"description":"Looks up a user based upon their `ReferralCode` and returns their personal information. This is an [Open Endpoint](https://integrations.impact.com/impact-brand/reference/api-open-endpoints) and disabled by default.\n","parameters":[{"$ref":"#/components/parameters/tenant_alias"},{"name":"referralCode","in":"query","required":true,"schema":{"type":"string"},"description":"The code with which to lookup the user."}],"responses":{"200":{"description":"Found user","content":{"application/json":{"schema":{"$ref":"#/components/schemas/UserByCode"}}}},"403":{"$ref":"#/components/responses/ForbiddenError"},"404":{"$ref":"#/components/responses/NotFoundError"}}}}},"components":{"parameters":{"tenant_alias":{"name":"tenant_alias","in":"path","description":"Tenant being referenced. E.g. `\"aboih12h16t\"`","required":true,"schema":{"type":"string"}}},"schemas":{"UserByCode":{"description":"Minimal user information returned when looking up a user by referral code from the open endpoint.","type":"object","properties":{"id":{"type":"string","description":"The unique identifier for the user."},"accountId":{"type":"string","description":"The unique identifier of the account the user belongs to."},"firstName":{"type":"string","description":"The user's first name."},"lastInitial":{"type":"string","description":"The first initial of the user's last name."},"referralCode":{"type":"string","description":"The user's primary referral code."},"imageUrl":{"type":"string","description":"URL of the user's profile image."}}},"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":{"ForbiddenError":{"description":"Forbidden/Endpoint Disabled","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"NotFoundError":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}
```
---
# Agent Instructions
This documentation is published with GitBook. GitBook is the documentation platform designed so that both humans and AI agents can read, navigate, and reason over technical content effectively. Learn more at gitbook.com.
## 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/user-overview/user.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.