Trimble Inquiries API

openapi: 3.2.0
info:
  title: Vista Viewpoint Administration v2 Direct Inquiries 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: Inquiries
paths:
  /direct/subscribers/{subscriber_code}/vista/va/2/data/inquiries/cache:
    get:
      tags:
      - Inquiries
      summary: Gets all Inquiries objects from the cache
      description: 'Represents data found in Trimble Vista™ VA Inquiries program.


        Vista views: VPGridQueries, and VPGridQueryParameters'
      operationId: GET/direct/subscribers/{subscriber_code}/vista/va/2/data/inquiries/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_inquiries_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/va/2/data/inquiries/cache
  /direct/subscribers/{subscriber_code}/vista/va/2/data/inquiries/cache/search:
    post:
      tags:
      - Inquiries
      summary: Search through Inquiries objects in the data cache
      description: 'Represents data found in Trimble Vista™ VA Inquiries program.


        Vista views: VPGridQueries, and VPGridQueryParameters'
      operationId: POST/direct/subscribers/{subscriber_code}/vista/va/2/data/inquiries/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_inquiries_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/va/2/data/inquiries/cache/search/search
  /direct/subscribers/{subscriber_code}/vista/va/2/data/inquiries/cache/{ryvitId_value}:
    get:
      tags:
      - Inquiries
      summary: Gets one Inquiries object from the cache
      description: 'Represents data found in Trimble Vista™ VA Inquiries program.


        Vista views: VPGridQueries, and VPGridQueryParameters'
      operationId: GET/direct/subscribers/{subscriber_code}/vista/va/2/data/inquiries/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_inquiries_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/va/2/data/inquiries/cache/{ryvitId_value}
  /direct/subscribers/{subscriber_code}/vista/va/2/data/inquiries/cache/__ryvitId/{ryvitId_value}:
    get:
      tags:
      - Inquiries
      summary: Gets one Inquiries object from the cache
      description: 'Represents data found in Trimble Vista™ VA Inquiries program.


        Vista views: VPGridQueries, and VPGridQueryParameters'
      operationId: GET/direct/subscribers/{subscriber_code}/vista/va/2/data/inquiries/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_inquiries_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/va/2/data/inquiries/cache/__ryvitId/{ryvitId_value}
  /direct/subscribers/{subscriber_code}/vista/va/2/data/inquiries/cache/keyid/{KeyID}:
    get:
      tags:
      - Inquiries
      summary: Gets one Inquiries object from the cache
      description: 'Represents data found in Trimble Vista™ VA Inquiries program.


        Vista views: VPGridQueries, and VPGridQueryParameters'
      operationId: GET/direct/subscribers/{subscriber_code}/vista/va/2/data/inquiries/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_inquiries_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/va/2/data/inquiries/cache/keyid/{KeyID}
  /direct/subscribers/{subscriber_code}/vista/va/2/data/inquiries/cache/natural/{QueryName}:
    get:
      tags:
      - Inquiries
      summary: Gets one Inquiries object from the cache
      description: 'Represents data found in Trimble Vista™ VA Inquiries program.


        Vista views: VPGridQueries, and VPGridQueryParameters'
      operationId: GET/direct/subscribers/{subscriber_code}/vista/va/2/data/inquiries/cache/natural/{QueryName}
      parameters:
      - $ref: '#/components/parameters/subscriber_code'
      - $ref: '#/components/parameters/X-Application-Key'
      - name: QueryName
        in: path
        description: The QueryName 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_inquiries_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/va/2/data/inquiries/cache/natural/{QueryName}
  /direct/subscribers/{subscriber_code}/vista/va/2/data/inquiries/actions/run_inquiry:
    post:
      tags:
      - Inquiries
      summary: Executes the Run Inquiry action for the Inquiries data object
      description: Runs the selected VA Inquiry.
      operationId: POST/direct/subscribers/{subscriber_code}/vista/va/2/data/inquiries/actions/run_inquiry
      parameters:
      - $ref: '#/components/parameters/subscriber_code'
      - $ref: '#/components/parameters/X-Application-Key'
      requestBody:
        content:
          application/json:
            schema:
              required:
              - __inquiry_keyID
              - __filter
              type: object
              properties:
                __inquiry_keyID:
                  type: integer
                  description: The KeyID (Internal Primary Key) of the specific VA Inquiry record to be executed.
                __filter:
                  type: object
                  description: An object containing key-value pairs that correspond to the parameters defined on the VA Inquiry in Vista. The property name must match the Inquiry Parameter name exactly.
              description: Schema for initiating an Inquiry Run. The results will be stored in the inquiry_data object.
      responses:
        '200':
          description: Success
          content:
            application/json:
              schema:
                properties:
                  id:
                    type: string
                  operation:
                    type: string
                  status:
                    type: string
        '400':
          $ref: '#/components/responses/errorResponse'
        '401':
          $ref: '#/components/responses/unauth'
        '403':
          $ref: '#/components/responses/forbidden'
        '404':
          $ref: '#/components/responses/notFound'
        x-$.result for Successful:
          description: Object returned at $.result from GET /direct/actions/{action_key_value} when $.status = "Successful"
          content:
            application/json:
              schema:
                required:
                - __inquiry_run_key
                - status
                type: object
                properties:
                  __inquiry_run_key:
                    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
                    description: The unique key (GUID/UUID) generated for this specific Inquiry Run. This key is used to fetch the resulting data from the inquiry_data cache and manage the inquiry run.
                  status:
                    enum:
                    - Success
                    type: string
                    description: A status message confirming that the inquiry run has been successfully initiated.
                description: Successful output schema for the run_inquiry action.
        x-$.result for Failed:
          description: Object returned at $.result from GET /direct/actions/{action_key_value} when $.status = "Failed"
          content:
            application/json:
              schema:
                required:
                - code
                - errors
                type: object
                properties:
                  code:
                    type: string
                    description: Well known codes listed in the examples properties.  You must not fail to accept the error response if other codes are found as codes will be added over time.
                  user_defined_code:
                    type:
                    - string
                    - 'null'
                    description: When Code is User Defined, then this value provides details specific to this api.
                  errors:
                    minItems: 1
                    type: array
                    items:
                      required:
                      - text
                      type: object
                      properties:
                        text:
                          type: string
                        source:
                          type: array
                          items:
                            type: string
                          description: Array of a json path strings to the property(s) related to this error.  (eg. $.Taxes.Amount)
                        details:
                          type: object
                          description: Properties will be added to this object to provide details specific to the error.
      x-operation-id-source: normalized
      x-operation-id-original: POST /direct/subscribers/{subscriber_code}/vista/va/2/data/inquiries/actions/run_inquiry
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:
    data_inquiries:
      required:
      - QueryName
      - Query
      - IsStandard
      - KeyID
      - QueryType
      - IsAssignableInWorkCenter
      - IsPublished
      type: object
      properties:
        QueryName:
          maxLength: 50
          type: string
          description: The unique, internal name of the inquiry query (Primary Key Component).
        QueryTitle:
          maxLength: 255
          type:
          - string
          - 'null'
          description: A user-friendly title for the inquiry.
        QueryDescription:
          maxLength: 512
          type:
          - string
          - 'null'
          description: A detailed description of the inquiry's purpose.
        Query:
          type: string
          description: The SQL query definition itself (may be large).
        Notes:
          type:
          - string
          - 'null'
          description: Any additional notes regarding the query.
        IsStandard:
          maxLength: 1
          enum:
          - Y
          - N
          type: string
          description: Indicates if the query is a standard, system-provided definition ('Y' or 'N').
        KeyID:
          type: integer
          description: The unique internal record identifier (Internal Primary Key).
        QueryType:
          type: integer
          description: The numeric type code of the query (e.g., Grid, Report).
        IsAssignableInWorkCenter:
          maxLength: 1
          enum:
          - Y
          - N
          type: string
          description: Indicates if the inquiry can be assigned within a WorkCenter ('Y' or 'N').
        ChangeNotes:
          type:
          - string
          - 'null'
          description: Notes detailing changes made to the query.
        IsPublished:
          maxLength: 1
          enum:
          - Y
          - N
          type: string
          description: Indicates if the query is published and available for use ('Y' or 'N').
        ApiExecutions:
          type:
          - integer
          - 'null'
          description: Count of times the inquiry has been executed via API.
        LastApiExecution:
          type:
          - string
          - 'null'
          description: Timestamp of the last time the inquiry was executed via API.
          format: date-time
        FormName:
          maxLength: 128
          type:
          - string
          - 'null'
          description: The name of the form associated with the query, if applicable.
        Parameters:
          type: array
          items:
            required:
            - ParameterName
            - IsVisible
            - IsStandard
            - KeyID
            type: object
            properties:
              ParameterName:
                maxLength: 50
                type: string
                description: The unique name of the parameter (Primary Key Component).
              DataType:
                maxLength: 30
                type:
                - string
                - 'null'
                description: The SQL data type of the parameter (e.g., varchar, int, datetime).
              Value:
                maxLength: 50
                type:
                - string
                - 'null'
                description: A default value or example value for the parameter.
              IsVisible:
                maxLength: 1
                enum:
                - Y
                - N
                type: string
                description: Indicates if the parameter is visible in the UI ('Y' or 'N').
              Description:
                maxLength: 255
                type:
                - string
                - 'null'
                description: A user-friendly description of the parameter.
              DefaultType:
                type:
                - integer
                - 'null'
                description: The numeric code defining how the default value is determined.
              IsStandard:
                maxLength: 1
                enum:
                - Y
                - N
                type: string
                description: Indicates if the parameter is a standard, system-provided definition ('Y' or 'N').
              InputType:
                type:
                - integer
                - 'null'
                description: The numeric code defining the input control type (e.g., text box, lookup).
              InputLength:
                type:
                - integer
                - 'null'
                description: The maximum input length for the parameter value.
              Prec:
                type:
                - integer
                - 'null'
                description: Precision for numeric data types.
              KeyID:
                type: integer
                description: The unique internal record identifier for the parameter.
              Lookup:
                maxLength: 30
                type:
                - string
                - 'null'
                description: The name of the lookup query or table used to populate the parameter values.
              Comparison:
                maxLength: 10
                type:
                - string
                - 'null'
                description: The default comparison operator (e.g., EQ, LT, GT).
              Operator:
                maxLength: 10
                type:
                - string
                - 'null'
                description: The logical operator used to combine multiple parameters (e.g., AND, OR).
              Seq:
                type:
                - integer
                - 'null'
                description: The sequence or order in which the parameter appears.
              ColumnName:
                maxLength: 50
                type:
                - string
                - 'null'
                description: The database column name associated with the parameter.
              DefaultOrder:
                type:
                - integer
                - 'null'
                description: The default sort order for the parameter.
            description: A parameter associated with the VPGridQuery.
          description: A collection of parameters required or used by this inquiry.
      description: Schema for caching Inquiry Definitions (originally VPGridQueries), including their associated parameters.
    data_inquiries_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_inquiries'
    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