Skip to main content

Users

Status: Proposed

A “user” is a person or bot that could potentially interact with the platform. If they have not been granted access to any features they will not be able to do anything after logging in.

A person who is the customer of multiple businesses may have multiple separate user records within the platform so it is important to always include an organization filter when searching by email or name.

To learn more and view sample requests visit the user management guide

typestring

Possible values: [users]

Default value: users
idstring

The id will be assigned by the server and must be included on all update requests. Values sent during creation will be ignored. It is globally unique across all platform instances and will not change.

You may use the special id me to operate on the current user if you have the scope openid.

Example: U-3ca38c57-7677-45d4-81e8-cd29eab91d63
attributes objectnullable
displayNamestring

The user’s name formatted for display. This will always have a value.

Example: Bill Smith
givenNamestring

Given name(s) or first name(s) of the End-User. Note that in some cultures, people can have multiple given names; all can be present, with the names being separated by space characters.

Possible values: <= 50 characters

Example: William
familyNamestring

Surname(s) or last name(s) of the End-User. Note that in some cultures, people can have multiple family names or no family name; all can be present, with the names being separated by space characters.

Possible values: <= 50 characters

Example: Smith
greetingNamestring

The name to use at the opening of messages addressed to the user. Note that in some cultures this is an alternate spelling or shortened form of the first name. Defaults to givenName.

Possible values: <= 50 characters

Example: Billy
emailemail

The primary email address for the user. This is required when creating a user.

Possible values: >= 5 characters

Example: bill@example.com
emailVerifiedboolean

True if the End-User's e-mail address has been verified; otherwise false. When true affirmative steps to ensure that this e-mail address was controlled by the End-User at the time the verification was performed.

Default value: false
emailSetboolean

Indicates there is an email address available that can have messages sent to it using the notifications system.

languageLocaleCodestring

The local language that content should be displayed to this user in.

Note: We currently have a limited set of allowed languages but expect to support many more in the future. When the requested language is not supported US English will be used.

It should be a single BCP47/RFC5646 language tag. This is an ISO 639-1 Alpha-2 language code in lowercase and an ISO 3166-1 Alpha-2 country code in uppercase, separated by a dash.

Examples:

  • en-US English (US)
  • fr-FR French (France)
  • cs-Cz Czech (Czech Republic)
  • de-DE German (Germany)
  • nl-BE Dutch (Belgium)

Possible values: Value must match regular expression ^[a-z]{2}-[A-Z]{2}$

Example: en-US
phoneNumbersSetboolean
phoneNumbers object[]

A list of phone numbers for the user.

Note: Do not send a phone number object or type if the user does not have a phone number.

  • Array [
    • numberstringrequired

    The standard phone numbers for the location. Formatting characters may be included.

    Extensions

    It is recommended that extensions are included at the end of the number after an appropriate separator: Pause: , Wait: ; Default: ext.

    You may test the parsibility of a number using https://phonenumbers.temba.io/

    All partial phone numbers are assumed to be in the same country as this user's address.

    Example: +1-306-555-1234 ext. 56
    typeCodestringrequired

    A classification of what the number should be used for.

    The mobile number should be preferred when sending SMS messages to the user however they may also be sent to work or home numbers.

    Possible values: [mobile, work, home, fax, pager]

  • ]
    • address object

    The primary address where this user can be reached.

    line1string

    The primary information. Typically a street address.

    Example: 109 8th Street E.
    line2string

    An additional line of information to add after the street address.

    Example: Suite 23
    streetAddressstringdeprecated

    Deprecated - This field has been renamed line1

    Example: 109 8th Street E.
    additionalAddressstringdeprecated

    Deprecated - This field has been renamed line2. An additional line of information to add after the street address.

    Example: Suite 23
    citystring

    The city, town or locality component of an address.

    Example: Saskatoon
    postalCodestring

    The zip code or postal code component of an address.

    Example: S7M 1R3
    regionCodestring

    The code for the top level subdivision within the country (state/province). For more info see the Addresses guide

    Examples: CA-SK, US-FL, AG-08, AU-NSW

    Possible values: >= 4 characters and <= 6 characters, Value must match regular expression ^[A-Z]{2}-[\w]{1,3}$

    Example: CA-SK
    countryCodestring

    The two letter country code. For more info see the Addresses guide

    Examples: CA, US, AU

    Possible values: >= 2 characters and <= 2 characters, Value must match regular expression ^[A-Z]{2}$

    Example: CA
    profileImageuri

    A photo that can be used to represent this user. If the user does not have a custom image set a default image will be returned.

    Example: https://storage.googleapis.com/wordpress-www-vendasta/vw-wordpress/Brendan-King-1.jpg
    timeZonestring

    The User's time zone in the IANA time zone database format.

    Example: America/Los_Angeles

    Example: America/Regina
    createdAtdate-time

    The time at which the user was initially created in the platform.

    updatedAtdate-time

    The time at which the user’s profile was last updated. Note: Changes to permissions will not affect this field.

    relationships object
    partner object

    A link to the organization that provides the platform to this user.

    data objectrequired
    typestringrequired

    Possible values: [partners]

    Default value: partners
    idstringrequired
    Example: ABC
    businessLocations object

    The business locations that this user is a member of.

    When a new location is added to a user they will be granted the default business user permissions.

    Fine grained permissions currently must be managed in Partner Center's UI. We are gathering interest to determine how it should work by API so please send us your use cases.

    data object[]
  • Array [
    • typestringrequired

    Possible values: [businessLocations]

    Default value: businessLocations
    Example: businessLocations
    idstringrequired

    The ID of a previously created business location record.

    Example: AG-1234567
  • ]
    • platformAccess object

    Proposed The platform access functionality is still at a proposed status. Not all options are currently available.

    Use this field to grant access to platform level features to your employees and contractors.

    data object[]
  • Array [
    • typestringrequired
    Default value: appFeatures
    Example: appFeatures
    idstringrequired

    The platform access functionality is still at a proposed status. Not all options are currently available.

    Possible values: [pc:access, pc:canCustomizeWhitelabel, pc:canAccessBilling, pc:canManageSales, pc:canManageAccounts, pc:canManageTasks, pc:canAccessBrands, pc:canAccessMarketing, pc:canAccessDashboard, pc:canAccessOrders, pc:canManageAdmins, pc:canAccessMarketplace, pc:canEnableApps, pc:canAccessCompanyProfile, pc:canAccessAutomations, ssc:access, ssc:manage, tm:access, tm:manage]

  • ]
    • Users
    {
      "type": "users",
      "id": "U-3ca38c57-7677-45d4-81e8-cd29eab91d63",
      "attributes": {
        "displayName": "Bill Smith",
        "givenName": "William",
        "familyName": "Smith",
        "greetingName": "Billy",
        "email": "bill@example.com",
        "emailVerified": false,
        "emailSet": true,
        "languageLocaleCode": "en-US",
        "phoneNumbersSet": true,
        "phoneNumbers": [
          {
            "number": "+1-306-555-1234 ext. 56",
            "typeCode": "mobile"
          }
        ],
        "address": {
          "line1": "109 8th Street E.",
          "line2": "Suite 23",
          "city": "Saskatoon",
          "postalCode": "S7M 1R3",
          "regionCode": "CA-SK",
          "countryCode": "CA"
        },
        "profileImage": "https://storage.googleapis.com/wordpress-www-vendasta/vw-wordpress/Brendan-King-1.jpg",
        "timeZone": "America/Regina",
        "createdAt": "2024-07-29T15:51:28.071Z",
        "updatedAt": "2024-07-29T15:51:28.071Z"
      },
      "relationships": {
        "partner": {
          "data": {
            "type": "partners",
            "id": "ABC"
          }
        },
        "businessLocations": {
          "data": [
            {
              "type": "businessLocations",
              "id": "AG-1234567"
            }
          ]
        },
        "platformAccess": {
          "data": [
            {
              "type": "appFeatures",
              "id": "pc:access"
            }
          ]
        }
      }
    }