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": "joe@example.com",
    "accountId": "joe@example.com",
    "firstName": "Joe",
    "lastName": "Testerson",
    "email": "joe@example.com",
    "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": "joe@example.com",
  "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"
  ]
}