Trimble Roles API

openapi: 3.2.0
info:
  title: Vista Headquarters v2 Direct Roles API
  description: For assistance, please visit our Customer Support page.
  contact:
    name: Customer Support
  version: '2'
  x-logo:
    url: https://cdn.brandfolder.io/IH4HLZST/at/pwwq8z7wf64v8jxbtrgnpwqr/TrimbleR-Horiz-RGB-Blue.png
    altText: Trimble logo
servers:
- url: https://{apiHost}/connect/v1/
  description: App Xchange API (choose region)
  variables:
    apiHost:
      default: api.xchange.trimble.com
      description: Regional API hostname. Application keys and subscriber codes are environment-specific.
      enum:
      - api.xchange.trimble.com
      - api-ap-au.xchange.trimble.com
security:
- {}
tags:
- name: Roles
paths:
  /direct/subscribers/{subscriber_code}/vista/hq/2/data/roles/cache:
    get:
      tags:
      - Roles
      summary: Gets all Roles objects from the cache
      description: 'Represents data found in Vista™ HQ Roles program.


        Vista views: HQRoles, HQRoleLimit, HQRoleMember'
      operationId: GET/direct/subscribers/{subscriber_code}/vista/hq/2/data/roles/cache
      parameters:
      - $ref: '#/components/parameters/subscriber_code'
      - $ref: '#/components/parameters/X-Application-Key'
      - $ref: '#/components/parameters/limit_continuation'
      - $ref: '#/components/parameters/modifiedUTCSince'
      - $ref: '#/components/parameters/continuationToken'
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                required:
                - limit
                - data
                - next
                - continuationToken
                type: object
                properties:
                  limit:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/data_roles_withKeys'
                  next:
                    type: string
                  continuationToken:
                    type: string
        '400':
          $ref: '#/components/responses/errorResponse'
        '401':
          $ref: '#/components/responses/unauth'
        '403':
          $ref: '#/components/responses/forbidden'
      x-operation-id-source: normalized
      x-operation-id-original: GET /direct/subscribers/{subscriber_code}/vista/hq/2/data/roles/cache
  /direct/subscribers/{subscriber_code}/vista/hq/2/data/roles/cache/search:
    post:
      tags:
      - Roles
      summary: Search through Roles objects in the data cache
      description: 'Represents data found in Vista™ HQ Roles program.


        Vista views: HQRoles, HQRoleLimit, HQRoleMember'
      operationId: POST/direct/subscribers/{subscriber_code}/vista/hq/2/data/roles/cache/search/search
      parameters:
      - $ref: '#/components/parameters/subscriber_code'
      - $ref: '#/components/parameters/X-Application-Key'
      requestBody:
        content:
          application/json:
            schema:
              type: object
              properties:
                modifiedUtcAfter:
                  maxLength: 28
                  minLength: 28
                  type: string
                  description: 'Returns objects that were modified after the specified date (ISO 8601 format).  Format: yyyy-MM-ddThh:mm:ss.fffffffZ.  Example ''2019-12-11T20:16:58.3419275Z''.  If provided on the first call, the same value must be provided on all subsequent calls as you use the continuation token for the next result set.'
                  format: date-time
                modifiedUtcBefore:
                  maxLength: 28
                  minLength: 28
                  type: string
                  description: 'Returns objects that were modified before the specified date (ISO 8601 format).  Format: yyyy-MM-ddThh:mm:ss.fffffffZ.  Example ''2019-12-11T20:16:58.3419275Z''.  If provided on the first call, the same value must be provided on all subsequent calls as you use the continuation token for the next result set.'
                  format: date-time
                continuationToken:
                  type: string
                  description: Supplying this token will result in retrieving the next chunk of data if the first request contained more than 100 (up to) records or greater than 1 megabyte in size.  On your first call, you must omit or provide an empty string.  On subsequent calls, provide the continuationToken from the previous result.
                filters:
                  type: array
                  items:
                    oneOf:
                    - required:
                      - propertyName
                      - value
                      - operator
                      type: object
                      properties:
                        propertyName:
                          type: string
                          description: Name of the property to apply the filter on. Nested properties are supported with a dot (.) delimiter.  E.g. 'PONumber' or 'Sender.LastName'.
                        value:
                          type: integer
                          description: You must match the JSON type value to the propertyName JSON type.  There is no type coercion.
                        operator:
                          enum:
                          - Equal
                          - GreaterThan
                          - GreaterThanOrEqual
                          - LessThan
                          - LessThanOrEqual
                          - NotEqual
                          type: string
                      additionalProperties: false
                      description: ''
                    - required:
                      - propertyName
                      - value
                      - operator
                      type: object
                      properties:
                        propertyName:
                          type: string
                          description: Name of the property to apply the filter on. Nested properties are supported with a dot (.) delimiter.  E.g. 'PONumber' or 'Sender.LastName'.
                        value:
                          type: string
                          description: You must match the JSON type value to the propertyName JSON type.  There is no type coercion.
                        operator:
                          enum:
                          - Equal
                          - GreaterThan
                          - GreaterThanOrEqual
                          - LessThan
                          - LessThanOrEqual
                          - NotEqual
                          - Like
                          - EndsWith
                          - StartsWith
                          - Contains
                          type: string
                      additionalProperties: false
                      description: ''
                    - required:
                      - propertyName
                      - value
                      - operator
                      type: object
                      properties:
                        propertyName:
                          type: string
                          description: Name of the property to apply the filter on. Nested properties are supported with a dot (.) delimiter.  E.g. 'PONumber' or 'Sender.LastName'.
                        value:
                          type: boolean
                          description: You must match the JSON type value to the propertyName JSON type.  There is no type coercion.
                        operator:
                          enum:
                          - Equal
                          - NotEqual
                          type: string
                      additionalProperties: false
                      description: ''
                    - required:
                      - propertyName
                      - value
                      - operator
                      type: object
                      properties:
                        propertyName:
                          type: string
                          description: Name of the property to apply the filter on. Nested properties are supported with a dot (.) delimiter.  E.g. 'PONumber' or 'Sender.LastName'.
                        value:
                          type: array
                          items:
                            oneOf:
                            - type: string
                            - type: number
                          description: ' This oneOf option is to be used for null values for all data types.  You must match the JSON type value to the propertyName JSON type.  There is no type coercion.'
                        operator:
                          enum:
                          - In
                          type: string
                      additionalProperties: false
                      description: ''
                  description: All provided filters are combined with AND conditions. E.g. filter1 AND filter2 AND filter3.  Not providing a filter will result in an unfiltered result.  Filtering can be performed on nested object properties but can not be performed on array item properties.  If provided on the first call, the same value must be provided on all subsequent calls as you use the continuation token for the next result set.
              additionalProperties: false
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                required:
                - count
                - data
                type: object
                properties:
                  count:
                    type: integer
                  data:
                    type: array
                    items:
                      $ref: '#/components/schemas/data_roles_withKeys'
                  continuationToken:
                    type: string
                    description: Supply this token on the next request to get the next chunk of data. This will have a value if the result set contains more than 100 records or the set is greater than 1 megabyte.
        '400':
          $ref: '#/components/responses/errorResponse'
        '401':
          $ref: '#/components/responses/unauth'
        '403':
          $ref: '#/components/responses/forbidden'
      x-operation-id-source: normalized
      x-operation-id-original: POST /direct/subscribers/{subscriber_code}/vista/hq/2/data/roles/cache/search/search
  /direct/subscribers/{subscriber_code}/vista/hq/2/data/roles/cache/{ryvitId_value}:
    get:
      tags:
      - Roles
      summary: Gets one Roles object from the cache
      description: 'Represents data found in Vista™ HQ Roles program.


        Vista views: HQRoles, HQRoleLimit, HQRoleMember'
      operationId: GET/direct/subscribers/{subscriber_code}/vista/hq/2/data/roles/cache/{ryvitId_value}
      parameters:
      - $ref: '#/components/parameters/subscriber_code'
      - $ref: '#/components/parameters/X-Application-Key'
      - name: ryvitId_value
        in: path
        description: The code of the data object you want to get.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/data_roles_withKeys'
        '401':
          $ref: '#/components/responses/unauth'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
      x-operation-id-source: normalized
      x-operation-id-original: GET /direct/subscribers/{subscriber_code}/vista/hq/2/data/roles/cache/{ryvitId_value}
  /direct/subscribers/{subscriber_code}/vista/hq/2/data/roles/cache/__ryvitId/{ryvitId_value}:
    get:
      tags:
      - Roles
      summary: Gets one Roles object from the cache
      description: 'Represents data found in Vista™ HQ Roles program.


        Vista views: HQRoles, HQRoleLimit, HQRoleMember'
      operationId: GET/direct/subscribers/{subscriber_code}/vista/hq/2/data/roles/cache/__ryvitId/{ryvitId_value}
      parameters:
      - $ref: '#/components/parameters/subscriber_code'
      - $ref: '#/components/parameters/X-Application-Key'
      - name: ryvitId_value
        in: path
        description: The code of the data object you want to get.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/data_roles_withKeys'
        '401':
          $ref: '#/components/responses/unauth'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
      x-operation-id-source: normalized
      x-operation-id-original: GET /direct/subscribers/{subscriber_code}/vista/hq/2/data/roles/cache/__ryvitId/{ryvitId_value}
  /direct/subscribers/{subscriber_code}/vista/hq/2/data/roles/cache/keyid/{KeyID}:
    get:
      tags:
      - Roles
      summary: Gets one Roles object from the cache
      description: 'Represents data found in Vista™ HQ Roles program.


        Vista views: HQRoles, HQRoleLimit, HQRoleMember'
      operationId: GET/direct/subscribers/{subscriber_code}/vista/hq/2/data/roles/cache/keyid/{KeyID}
      parameters:
      - $ref: '#/components/parameters/subscriber_code'
      - $ref: '#/components/parameters/X-Application-Key'
      - name: KeyID
        in: path
        description: The KeyID portion of the key used to identify the object.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/data_roles_withKeys'
        '401':
          $ref: '#/components/responses/unauth'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
      x-operation-id-source: normalized
      x-operation-id-original: GET /direct/subscribers/{subscriber_code}/vista/hq/2/data/roles/cache/keyid/{KeyID}
  /direct/subscribers/{subscriber_code}/vista/hq/2/data/roles/cache/natural/{Role}:
    get:
      tags:
      - Roles
      summary: Gets one Roles object from the cache
      description: 'Represents data found in Vista™ HQ Roles program.


        Vista views: HQRoles, HQRoleLimit, HQRoleMember'
      operationId: GET/direct/subscribers/{subscriber_code}/vista/hq/2/data/roles/cache/natural/{Role}
      parameters:
      - $ref: '#/components/parameters/subscriber_code'
      - $ref: '#/components/parameters/X-Application-Key'
      - name: Role
        in: path
        description: The Role portion of the key used to identify the object.
        required: true
        schema:
          type: string
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/data_roles_withKeys'
        '401':
          $ref: '#/components/responses/unauth'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
      x-operation-id-source: normalized
      x-operation-id-original: GET /direct/subscribers/{subscriber_code}/vista/hq/2/data/roles/cache/natural/{Role}
components:
  parameters:
    X-Application-Key:
      name: X-Application-Key
      in: header
      description: Used to authorize access to the Direct API.
      required: true
      schema:
        type: string
    continuationToken:
      name: continuationToken
      in: query
      description: A URL Encoded continuationToken value from a previous GET response.  When provided, the next set of results for the original GET will be returned.
      schema:
        type: string
    subscriber_code:
      name: subscriber_code
      in: path
      description: The code of the subscriber that you are making this request for.
      required: true
      schema:
        type: string
    modifiedUTCSince:
      name: modifiedUTCSince
      in: query
      description: A string specifies a datetime against which to filter the results. When specified the result will be ordered oldest __modifiedUTC to newest.  Example 2019-12-11T20:16:58.3419275Z. Optional. If unspecified, all cached objects will be returned.
      schema:
        type: string
    limit_continuation:
      name: limit
      in: query
      description: Limits the number of records returned by the API, up to a maximum of 1,000.  The API may return less than the limit even when more records exist.  Always examine the 'next' and 'continuationToken' properties to determine if more records are available.
      schema:
        type: integer
  responses:
    errorResponse:
      description: Describes issues with the request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/errorSchema'
    unauth:
      description: You have not provided a proper X-Application-Key in the header of this request.
    notFound:
      description: The object with the given ID was not found OR a subscriber with the given URL was not found.
    forbidden:
      description: The X-Application-Key provided is valid but the key does not have access to this resource.
  schemas:
    errorSchema:
      type: object
      properties:
        error:
          type: object
          properties:
            message:
              type: string
            details:
              type: array
              items:
                type: object
                properties:
                  target:
                    title: Describes which field in the request has an issue.
                    type: string
                  message:
                    title: The error message describing the issue.
                    type: string
    data_roles:
      required:
      - KeyID
      - Role
      - Active
      - UsableInPC
      - UsableInPM
      - UsableInSM
      type: object
      properties:
        KeyID:
          type: integer
          description: ''
        Role:
          maxLength: 20
          type: string
          description: ''
        Description:
          maxLength: 60
          type:
          - string
          - 'null'
          description: ''
        Active:
          maxLength: 1
          type: string
          description: ''
        Notes:
          type:
          - string
          - 'null'
          description: ''
        UniqueAttchID:
          maxLength: 36
          minLength: 36
          pattern: '[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}'
          type:
          - string
          - 'null'
          description: ''
        UsableInPC:
          enum:
          - Y
          - N
          type: string
          description: ''
        UsableInPM:
          enum:
          - Y
          - N
          type: string
          description: ''
        UsableInSM:
          enum:
          - Y
          - N
          type: string
          description: ''
        __custom_fields:
          type: object
          description: This property will be added if there are any custom fields defined for this object in Vista.  Each custom field will be a property of this object.
        SpendingLimits:
          type: array
          items:
            required:
            - Type
            - SubType
            - Limit
            - Threshold
            - Active
            - KeyID
            type: object
            properties:
              Type:
                maxLength: 10
                type: string
                description: ''
              SubType:
                maxLength: 10
                type: string
                description: ''
              Limit:
                pattern: ^[-+]?[0-9]{1,10}(?:.[0-9]{1,2})?$
                type: string
                description: ''
              Threshold:
                pattern: ^[-+]?[0-9]{1,2}(?:.[0-9]{1,4})?$
                type: string
                description: ''
              Active:
                enum:
                - Y
                - N
                type: string
                description: ''
              Notes:
                type:
                - string
                - 'null'
                description: ''
              UniqueAttchID:
                maxLength: 36
                minLength: 36
                pattern: '[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}'
                type:
                - string
                - 'null'
                description: ''
              KeyID:
                type: integer
                description: ''
              __custom_fields:
                type: object
                description: This property will be added if there are any custom fields defined for this object in Vista.  Each custom field will be a property of this object.
          description: ''
        Users:
          type: array
          items:
            required:
            - UserName
            - Active
            - KeyID
            type: object
            properties:
              UserName:
                maxLength: 128
                type: string
                description: ''
              Active:
                enum:
                - Y
                - N
                type: string
                description: ''
              Notes:
                type:
                - string
                - 'null'
                description: ''
              UniqueAttchID:
                maxLength: 36
                minLength: 36
                pattern: '[0-9a-fA-F]{8}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{4}\-[0-9a-fA-F]{12}'
                type:
                - string
                - 'null'
                description: ''
              KeyID:
                type: integer
                description: ''
              __custom_fields:
                type: object
                description: This property will be added if there are any custom fields defined for this object in Vista.  Each custom field will be a property of this object.
          description: ''
    data_roles_withKeys:
      allOf:
      - type: object
        properties:
          __ryvitKeys:
            type: array
            items:
              type: string
            description: Array of key paths that can be used to retrieve this object.
            example:
            - keyid/{KeyID}
          __modifiedUTC:
            type: string
            description: UTC timestamp of when this object was last modified in the cache.
            example: '2020-01-01T13:01:01.1234567Z'
      - $ref: '#/components/schemas/data_roles'