HomeGuidesAPI ReferenceAPI Changelog
Log In
API Reference

User Upsert

This method updates/creates a user and an account and returns the user object representing that newly created user/account.

You can provide vanity referral codes and sharelinks in a user upsert. New sharelinks and referral codes will be set as primary for the upserted user. If a referral code is passed without an associated sharelink for that program, then one will be generated and vice versa for sharelinks. For more information, visit Assign Vanity Share Links or Referral Codes.

Because this call creates a user, it requires either a write token or an API key.

Path Parameters

accountId string required

The account to upsert.

userId string required

The user to upsert.

tenant_alias string required

Tenant being referenced. E.g., "aboih12h16t" or "Barb Dwyer"

Query Parameters

fields string

The fields to be included in the response. Cannot coexist with extraFields. E.g., "firstName,lastName,dateBlocked". Defaults to null.

extraFields string

Specifies additional fields to include in the response, beyond the default fields. To include only default fields, use the fields parameter instead. This option cannot be used together with fields, e.g., "firstName, lastName, dateBlocked". Defaults to null.

Body Parameters

id string required

The unique identifier provided for this user. Use the user's email as their Id.

accountId string required

The unique identifier of the account. Value must match id. Use the user's email as their account Id.

firstName string

The user's first name.

lastName string

The user's last name.

email string

The email address provided for the user. Advocate uses this to notify someone when they have a successful referral.

referable boolean

Flag used by Advocate to determine whether a user is able to be referred.

referralCodes object

The primary custom referral codes for different programs.

View child attributes

programId string

The Id of the program.

code string

The referral code used for sharing by this user.

locale string

The user's locale, used for Internationalization. The locale must be of the format language_COUNTRY where the language code must be lowercase and the country code must be uppercase. The separator must be an underscore.

countryCode string

The user's ISO 3166-1 Alpha-2 country code. For example, "CA" for Canada and "ES" for Spain.

referredByCodes array of strings

An array of referral codes used to refer this account.

cookies string

The Base64URL encoded attribution cookie values. When decoded, the schema will resemble the following:

{"app.referralsaasquatch.com": {"tenantAlias_CODE": {"codes": {"program1": "CODE1"},"codesExp": {"CODE1": 1234567}}}}

segments array of strings

A list of operations for adding and removing a user from segments.

Details about the supported operators and operations for adding and removing users from a segment can be found in our User Segmentation.

shareLinks object

The primary custom shareLinks for different programs. If a given program does not have a referral code, one will be generated.

View child attributes

programId string

The Id of the program.

sharelink string

The custom link used for sharing by this user.

customFields object

An object containing the custom fields for this user.

Learn more about the available custom field functionality in our Custom Fields article.

Responses

Refer to this guide for Error Responses.

Example request

curl 'https://app.referralsaasquatch.com/api/v1/{tenant_alias}/open/account/{accountId}/user/{userId}?fields=&extraFields=' \
  -X PUT \
  -u :API_KEY \
  -H 'Content-Type: application/json' \
  -d '{
    "id": "[email protected]",
    "accountId": "[email protected]",
    "firstName": "Joe",
    "lastName": "Testerson",
    "email": "[email protected]",
    "referable": true,
    "referralCodes": {
      "12345": "JOETESTERSON",
      "22345": "JOE123"
    },
    "locale": "en_US",
    "countryCode": "US",
    "dateUsTaxFormSubmitted": 1619647338270,
    "referredByCodes": [
      "JONDOE1234",
      "JOHNDOE"
    ],
    "cookies": "eyJhcHAucmVmZXJyYWxzYWFzcXVhdGNoLmNvbSI6eyJ0ZW5hbnRBbGlhc19DT0RFIjp7ImNvZGVzIjp7InByb2dyYW0xIjoiQ09ERTEifSwiY29kZXNFeHAiOnsiQ09ERTEiOjEyMzQ1Njd9fX19",
    "segments": [
      "segment1",
      "segment2"
    ],
    "shareLinks": {
      "12345": "http://example.com/free"
    },
    "customFields": {
      "lastPurchaseDate": 1512152525513,
      "plan": "Pro+",
      "phone": 19055551234
    }
  }'

Example response

{
  "id": "5d266be33d08baefc3d29c608d8ce6327874a12ab5b345d54fa1ae1822ddfdbd",
  "accountId": "5d266be33d08baefc3d29c608d8ce6327874a12ab5b345d54fa1ae1822ddfdbd",
  "firstName": "Joe",
  "lastName": "Testerson",
  "referralCodes": {
    "33255": "JOETESTERSON",
    "34681": "JOE123"
  },
  "imageUrl": "",
  "email": "[email protected]",
  "cookieId": null,
  "locale": "en_US",
  "countryCode": "US",
  "referable": true,
  "firstSeenIP": null,
  "lastSeenIP": null,
  "dateCreated": 1749503206814,
  "programShareLinks": {
    "33255": {
      "cleanShareLink": "https://ssqt.co/mzEwu2Z",
      "UNKNOWN": {
        "DIRECT": "https://ssqt.co/mvEwu2Z"
      },
      "EMAIL": {
        "DIRECT": "https://ssqt.co/mPEwu2Z"
      },
      "MOBILE": {
        "DIRECT": "https://ssqt.co/meEwu2Z"
      }
    }
  },
  "customFields": {
    "lastPurchaseDate": 1512152525513,
    "phone": 19055551234,
    "plan": "Pro+"
  },
  "segments": [
    "segment1",
    "segment2"
  ],
  "referredByCodes": [
    "JONDOE1234",
    "JOHNDOE"
  ]
}