Vendasta Users API

openapi: 3.2.0
info:
  title: Platform REST Users API
  version: Evergreen
servers:
- url: https://prod.apigateway.co/platform
  description: Production
- description: Demo
  url: https://demo.apigateway.co/platform
- description: Local
  url: '{local}/platform'
- url: http://localhost:11001/platform
  description: Localhost
tags:
- name: Users
paths:
  /users:
    post:
      summary: Create User
      operationId: post-users
      responses:
        '201':
          description: Created
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/users'
                  links:
                    type: object
                    properties:
                      self:
                        type: string
                        format: uri
                        description: The address of the newly created user
          headers:
            Location:
              schema:
                type: string
                format: uri
              description: The address of the newly created user
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/users'
            examples:
              Example 1:
                value:
                  data:
                    type: users
                    attributes:
                      givenName: William
                      familyName: Smith
                      greetingName: Billy
                      email: bill@example.com
                      languageLocaleCode: en-US
                      phoneNumbersSet: true
                      phoneNumbers:
                      - number: +1-306-555-1234 ext. 56
                        typeCode: mobile
                      address:
                        line1: 109 8th Street E.
                        line2: Suite 23
                        streetAddress: 109 8th Street E.
                        additionalAddress: Suite 23
                        city: Saskatoon
                        postalCode: S7M 1R3
                        regionCode: CA-SK
                        countryCode: CA
                      timeZone: America/Regina
                    relationships:
                      partner:
                        data:
                          type: partners
                          id: ABC
                      businessLocations:
                        data:
                        - type: businessLocations
                          id: AG-1234567
                      platformAccess:
                        data:
                        - type: appFeatures
                          id: pc:access
      x-lifecycle:
        status: trustedTester
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`


        Used to record basic data for a new location.


        The following members must be populated during creation:

        - `relationships.partner.data.id`

        - `attributes.email`'
      parameters:
      - schema:
          type: string
          example: Bearer <Access Token>
          pattern: ^Bearer\s\S+
        in: header
        name: Authorization
        description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
        required: true
      - schema:
          type: string
          default: application/vnd.api+json
          enum:
          - application/vnd.api+json
        in: header
        name: Content-Type
        required: true
        description: Indicates the format of the request body being sent. In most cases you will want `application/vnd.api+json`
      security:
      - OAuth2Demo:
        - user.admin
      - OAuth2Prod:
        - user.admin
      tags:
      - Users
    options:
      operationId: options-users
      summary: List valid HTTP verbs for /users
      description: 'Used solely for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) the OPTIONS request returns the list of possible HTTP methods and other headers that browsers use to protect user''s security. You should not call this operation directly. '
      responses:
        '204':
          description: No Content
      tags:
      - Users
    get:
      summary: List Users
      operationId: get-users
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/users'
                  links:
                    type: object
                    properties:
                      self:
                        type: string
                        format: uri
                      first:
                        type: string
                        description: Provides a link back to the first page of results
                        format: uri
                      next:
                        type: string
                        description: The URI at which the next batch of users can be gotten from
                        format: uri
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`


        Produces a list of users'
      parameters:
      - schema:
          type: string
        in: header
        name: Authorization
        description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
        required: true
      - schema:
          type: string
        in: query
        name: filter[partner.id]
        description: Return users for the specified partner. Required except when filtering by id.
      - schema:
          type: string
        in: query
        description: The cursor stores all your filters and current location in the list to allow paging over the results in smaller batches. The value will be provided in the response links. [Pagination Docs](https://developers.vendasta.com/platform/ZG9jOjEwMTkzMDg0-overview#paging).
        name: page[cursor]
      - schema:
          type: integer
          minimum: 1
          maximum: 100
          default: 10
        in: query
        description: The maximum number of users you would like returned in a single batch. Use the links.next member in the response to get the remainder. [Pagination Docs](https://developers.vendasta.com/platform/ZG9jOjEwMTkzMDg0-overview#paging).
        name: page[limit]
      - schema:
          type: array
          example:
          - U-12342,U-5345
          items:
            type: string
        in: query
        name: filter[id]
        description: A comma separated list of user ids to fetch in a batch
      - schema:
          type: string
        in: query
        name: filter[searchTerm]
        description: A string containing a partial name or email address. The results order is not affected by the quality of this match.
      - schema:
          type: string
        in: query
        name: filter[email]
        description: A string containing a complete email that must be an exact match.
      - schema:
          type: array
          items:
            type: string
            enum:
            - business
            - partner
            - bot
        in: query
        name: filter[category]
        description: 'Filter the users based on the broad category that they fall into. In some rare cases users may be part of multiple categories. '
      security:
      - OAuth2Demo:
        - user.admin
        - user.list
      - OAuth2Prod:
        - user.admin
        - user.list
      tags:
      - Users
      x-lifecycle:
        status: trustedTester
  /users/{id}:
    parameters:
    - schema:
        type: string
      name: id
      in: path
      required: true
    get:
      summary: Get User
      tags:
      - Users
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/users'
                  links:
                    type: object
                    properties:
                      self:
                        type: string
      operationId: get-users-id
      x-lifecycle:
        status: trustedTester
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`


        Returns information about a single user. The fields you are able to use will be affected by the combination of scopes that you were granted access to.'
      parameters:
      - schema:
          type: string
          example: Bearer <Access Token>
          pattern: ^Bearer\s\S+
        in: header
        name: Authorization
        description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
        required: true
      security:
      - OAuth2Demo:
        - user.admin
        - user.profile:read
        - user.contact:read
        - user.permission:read
        - user.permission
        - self.user.admin
        - self.user.contact:read
        - openid
        - profile
        - email
        - phone
        - address
      - OAuth2Prod:
        - user.admin
        - user.profile:read
        - user.contact:read
        - user.permission:read
        - user.permission
        - self.user.admin
        - self.user.contact:read
        - openid
        - profile
        - email
        - phone
        - address
    options:
      operationId: options-users-id
      summary: List valid HTTP verbs for /users/{id}
      description: 'Used solely for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) the OPTIONS request returns the list of possible HTTP methods and other headers that browsers use to protect user''s security. You should not call this operation directly. '
      responses:
        '204':
          description: No Content
      tags:
      - Users
    patch:
      summary: Update User
      operationId: patch-users-id
      tags:
      - Users
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Proposed`


        Update the existing user.

        Only the root ID and type fields are required. All others are optional and will keep their original value if omitted.'
      x-lifecycle:
        status: proposed
      parameters:
      - schema:
          type: string
          example: Bearer <Access Token>
          pattern: ^Bearer\s\S+
        in: header
        name: Authorization
        description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
        required: true
      - schema:
          type: string
          default: application/vnd.api+json
          enum:
          - application/vnd.api+json
        in: header
        name: Content-Type
        required: true
        description: Indicates the format of the request body being sent. In most cases you will want `application/vnd.api+json`
      security:
      - OAuth2Demo:
        - user.admin
      - OAuth2Prod:
        - user.admin
      responses:
        '200':
          description: Ok
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/users'
                  links:
                    type: object
                    properties:
                      self:
                        type: string
                        format: uri
                        description: The address of the updated user
          headers: {}
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  $ref: '#/components/schemas/users'
            examples:
              Example 1:
                value:
                  data:
                    type: users
                    id: U-3ca38c57-7677-45d4-81e8-cd29eab91d63
                    attributes:
                      givenName: William
                      familyName: Smith
                      greetingName: Billy
                      email: bill@example.com
                      languageLocaleCode: en-US
                      phoneNumbersSet: true
                      phoneNumbers:
                      - number: +1-306-555-1234 ext. 56
                        typeCode: mobile
                      address:
                        line1: 109 8th Street E.
                        line2: Suite 23
                        streetAddress: 109 8th Street E.
                        additionalAddress: Suite 23
                        city: Saskatoon
                        postalCode: S7M 1R3
                        regionCode: CA-SK
                        countryCode: CA
                      timeZone: America/Regina
                    relationships:
                      partner:
                        data:
                          type: partners
                          id: ABC
                      businessLocations:
                        data:
                        - type: businessLocations
                          id: AG-1234567
                      platformAccess:
                        data:
                        - type: appFeatures
                          id: pc:access
    delete:
      summary: Delete User
      operationId: delete-users-id
      responses:
        '204':
          description: No Content
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`


        Deleting a user will remove personal data from it and prevent the ID from being used again in the future.'
      security:
      - OAuth2Demo:
        - user.admin
      - OAuth2Prod:
        - user.admin
      tags:
      - Users
      parameters:
      - schema:
          type: string
        in: header
        name: Authorization
        description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
        required: true
      x-lifecycle:
        status: trustedTester
  /users/{id}/relationships/businessLocations:
    parameters:
    - schema:
        type: string
      name: id
      in: path
      required: true
    options:
      operationId: options-users-id-relationships-businessLocations
      summary: List valid HTTP verbs for /users/{id}/relationships/businessLocations
      description: 'Used solely for [CORS](https://developer.mozilla.org/en-US/docs/Web/HTTP/CORS) the OPTIONS request returns the list of possible HTTP methods and other headers that browsers use to protect user''s security. You should not call this operation directly. '
      responses:
        '204':
          description: No Content
      tags:
      - Users
    post:
      summary: Associate user with location
      operationId: post-users-id-relationships-businessLocations
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: array
                  description: A list of business locations to be added
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        example: AG-1234567
                        description: The ID of a business location to grant access to
                      type:
                        type: string
                        description: This should always be `businessLocations`
                        default: businessLocations
                        example: businessLocations
                    required:
                    - id
                    - type
              required:
              - data
      responses:
        '201':
          description: Created
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/users'
                  links:
                    type: object
                    properties:
                      self:
                        type: string
      x-lifecycle:
        status: trustedTester
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`


        Users can be granted access to business location(s) using the POST operation. After the operation completes, the user will have access to all their previous business locations plus any new locations in the POST request. If the user already has access to one or more of the specified locations they will be silently ignored.'
      parameters:
      - schema:
          type: string
          example: Bearer <Access Token>
          pattern: ^Bearer\s\S+
        in: header
        name: Authorization
        description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
        required: true
      - schema:
          type: string
          default: application/vnd.api+json
          enum:
          - application/vnd.api+json
        in: header
        name: Content-Type
        required: true
        description: Indicates the format of the request body being sent. In most cases you will want `application/vnd.api+json`
      security:
      - OAuth2Demo:
        - user.admin
      - OAuth2Prod:
        - user.admin
      tags:
      - Users
    get:
      summary: Get user locations
      operationId: get-users-id-relationships-businessLocations
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/users'
                  links:
                    type: object
                    properties:
                      self:
                        type: string
      x-lifecycle:
        status: trustedTester
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`


        Retrieves the business locations to which the User is associated.'
      parameters:
      - schema:
          type: string
          example: Bearer <Access Token>
          pattern: ^Bearer\s\S+
        in: header
        name: Authorization
        description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
        required: true
      security:
      - OAuth2Demo:
        - user.admin
      - OAuth2Prod:
        - user.admin
      tags:
      - Users
    patch:
      summary: Replace user location access
      operationId: patch-users-id-relationships-businessLocations
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: array
                  description: A list of business locations to be updated
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        example: AG-1234567
                        description: The ID of a business location to grant access to
                      type:
                        type: string
                        description: This should always be `businessLocations`
                        default: businessLocations
                        example: businessLocations
                    required:
                    - id
                    - type
              required:
              - data
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/users'
                  links:
                    type: object
                    properties:
                      self:
                        type: string
      x-lifecycle:
        status: trustedTester
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`


        Users can be granted access to business location(s) or removed from access to business location(s) using the PATCH operation. After the operation completes, the user will have access only to those business locations specified in the request body (if any).'
      parameters:
      - schema:
          type: string
          example: Bearer <Access Token>
          pattern: ^Bearer\s\S+
        in: header
        name: Authorization
        description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
        required: true
      - schema:
          type: string
          default: application/vnd.api+json
          enum:
          - application/vnd.api+json
        in: header
        name: Content-Type
        required: true
        description: Indicates the format of the request body being sent. In most cases you will want `application/vnd.api+json`
      security:
      - OAuth2Demo:
        - user.admin
      - OAuth2Prod:
        - user.admin
      tags:
      - Users
    delete:
      summary: Dissociate user from location
      operationId: delete-users-id-relationships-businessLocations
      requestBody:
        content:
          application/vnd.api+json:
            schema:
              type: object
              properties:
                data:
                  type: array
                  description: A list of business locations to be removed
                  items:
                    type: object
                    properties:
                      id:
                        type: string
                        example: AG-1234567
                        description: The ID of a business location to remove access
                      type:
                        type: string
                        description: This should always be `businessLocations`
                        default: businessLocations
                        example: businessLocations
                    required:
                    - id
                    - type
              required:
              - data
      responses:
        '204':
          description: No Content
      x-lifecycle:
        status: trustedTester
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`


        Access to business locations can be removed from a user with the DELETE operation. If the user does not already have access to one or more of the specified locations, they will be silently ignored.'
      parameters:
      - schema:
          type: string
          example: Bearer <Access Token>
          pattern: ^Bearer\s\S+
        in: header
        name: Authorization
        description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
        required: true
      - schema:
          type: string
          default: application/vnd.api+json
          enum:
          - application/vnd.api+json
        in: header
        name: Content-Type
        required: true
        description: Indicates the format of the request body being sent. In most cases you will want `application/vnd.api+json`
      security:
      - OAuth2Demo:
        - user.admin
      - OAuth2Prod:
        - user.admin
      tags:
      - Users
  /users/{id}/customFields:
    parameters:
    - schema:
        type: string
      name: id
      in: path
      required: true
    get:
      summary: Get Custom Fields
      responses:
        '200':
          description: OK
          content:
            application/vnd.api+json:
              schema:
                type: object
                properties:
                  data:
                    $ref: '#/components/schemas/userCustomFields'
                  links:
                    type: object
                    properties:
                      self:
                        type: string
                        format: uri
              examples:
                Return Example:
                  value:
                    data:
                      id: U-12345678-abcd-1234-abcd-123456789ab1
                      type: userCustomFields
                      attributes:
                        partnerFields:
                        - fieldId: FieldID-123448ca-abc0-abc5-abc2-abc640bf4b99
                          integerValue: 1000
                          title: Title of 123448ca field
                          description: Description for 123448ca field
                          fieldType: integer
                        - fieldId: FieldID-987448ca-abc0-abc5-abc2-abc640bf4b99
                          dateValue: A good date value
                          title: Title of 987448ca field
                          description: Description for 987448ca field
                          fieldType: date
                        - fieldId: FieldID-abc448ca-abc0-abc5-abc2-abc640bf4b99
                          stringValue: A good string value
                          title: Title of abc448ca field
                          description: Description for abc448ca field
                          fieldType: string
      operationId: get-userCustomFields-by-userid
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`


        This endpoint acts like a alias to [Get User Custom Fields by ID endpoint](b3A6MzczMDUyMjU-get-custom-fields-by-id). It returns custom fields for a user.'
      security:
      - OAuth2Demo:
        - user.admin
      - OAuth2Prod:
        - user.admin
      x-lifecycle:
        status: trustedTester
      tags:
      - Users
      parameters:
      - schema:
          type: string
          example: Bearer <Access Token>
          pattern: ^Bearer\s\S+
        in: header
        name: Authorization
        description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
        required: true
  /users/{id}/actions/sendWelcomeEmail:
    parameters:
    - schema:
        type: string
      name: id
      in: path
      required: true
    get:
      summary: Send Welcome Email
      operationId: get-sendWelcomeEmail-by-userid
      description: '[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Trusted Tester`


        An email will be sent to the already created user whose user id is passed in the request.'
      security:
      - OAuth2Demo:
        - user.admin
      - OAuth2Prod:
        - user.admin
      x-lifecycle:
        status: trustedTester
      tags:
      - Users
      parameters:
      - schema:
          type: string
          example: Bearer <Access Token>
          pattern: ^Bearer\s\S+
        in: header
        name: Authorization
        description: A Bearer access token to identify the user the app is acting on behalf of. See the Authorization guide for details.
        required: true
      responses:
        '202':
          description: Accepted
components:
  schemas:
    users:
      title: Users
      type: object
      x-lifecycle:
        status: proposed
      description: "[Status](https://developers.vendasta.com/platform/ZG9jOjEwMTU2NTYy-versioning): `Proposed`\n\t\nA “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.\n\nA 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. \n\nTo learn more and view sample requests visit the [user management guide](../../../../../docs/Guides/Users.md)"
      x-tags:
      - Users
      properties:
        type:
          type: string
          default: users
          enum:
          - users
        id:
          type: string
          description: '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:
          type:
          - object
          - 'null'
          properties:
            displayName:
              type: string
              example: Bill Smith
              description: The user’s name formatted for display. This will always have a value.
              readOnly: true
            givenName:
              type: string
              description: 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.
              minLength: 0
              maxLength: 50
              example: William
            familyName:
              type: string
              description: 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.
              minLength: 0
              maxLength: 50
              example: Smith
            greetingName:
              type: string
              description: 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.
              minLength: 0
              maxLength: 50
              example: Billy
            email:
              type: string
              format: email
              example: bill@example.com
              minLength: 5
              description: 'The primary email address for the user.

                This is required when creating a user.'
            emailVerified:
              type: boolean
              default: false
              description: '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. '
              readOnly: true
            emailSet:
              type: boolean
              description: Indicates there is an email address available that can have messages sent to it using the notifications system.
              readOnly: true
            languageLocaleCode:
              type: string
              pattern: ^[a-z]{2}(-[A-Z]{2})?$
              example: en-US
              description: '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](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes) language code in lowercase and an [ISO 3166-1 Alpha-2](https://en.wikipedia.org/wiki/List_of_ISO_3166_country_codes) 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)

                - `it` Italian'
            phoneNumbersSet:
              type: boolean
            phoneNumbe

# --- truncated at 32 KB (54 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/vendasta/refs/heads/main/openapi/vendasta-users-api-openapi.yml