Trimble Attachments API

openapi: 3.2.0
info:
  title: Vista Document Management v2 Direct Attachments 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: Attachments
paths:
  /direct/subscribers/{subscriber_code}/vista/dm/2/data/attachments/cache:
    get:
      tags:
      - Attachments
      summary: Gets all Attachments objects from the cache
      description: 'Attachment metadata synced from Vista DM (HQAT). Does not include file bytes or download URLs. To retrieve file content, call attachment_files/cache_file with UniqueAttchID, AttachmentID, or KeyID from this object.


        Vista view: HQAT'
      operationId: GET/direct/subscribers/{subscriber_code}/vista/dm/2/data/attachments/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_attachments_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/dm/2/data/attachments/cache
  /direct/subscribers/{subscriber_code}/vista/dm/2/data/attachments/cache/search:
    post:
      tags:
      - Attachments
      summary: Search through Attachments objects in the data cache
      description: 'Attachment metadata synced from Vista DM (HQAT). Does not include file bytes or download URLs. To retrieve file content, call attachment_files/cache_file with UniqueAttchID, AttachmentID, or KeyID from this object.


        Vista view: HQAT'
      operationId: POST/direct/subscribers/{subscriber_code}/vista/dm/2/data/attachments/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_attachments_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/dm/2/data/attachments/cache/search/search
  /direct/subscribers/{subscriber_code}/vista/dm/2/data/attachments/cache/{ryvitId_value}:
    get:
      tags:
      - Attachments
      summary: Gets one Attachments object from the cache
      description: 'Attachment metadata synced from Vista DM (HQAT). Does not include file bytes or download URLs. To retrieve file content, call attachment_files/cache_file with UniqueAttchID, AttachmentID, or KeyID from this object.


        Vista view: HQAT'
      operationId: GET/direct/subscribers/{subscriber_code}/vista/dm/2/data/attachments/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_attachments_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/dm/2/data/attachments/cache/{ryvitId_value}
  /direct/subscribers/{subscriber_code}/vista/dm/2/data/attachments/cache/__ryvitId/{ryvitId_value}:
    get:
      tags:
      - Attachments
      summary: Gets one Attachments object from the cache
      description: 'Attachment metadata synced from Vista DM (HQAT). Does not include file bytes or download URLs. To retrieve file content, call attachment_files/cache_file with UniqueAttchID, AttachmentID, or KeyID from this object.


        Vista view: HQAT'
      operationId: GET/direct/subscribers/{subscriber_code}/vista/dm/2/data/attachments/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_attachments_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/dm/2/data/attachments/cache/__ryvitId/{ryvitId_value}
  /direct/subscribers/{subscriber_code}/vista/dm/2/data/attachments/cache/keyid/{KeyID}:
    get:
      tags:
      - Attachments
      summary: Gets one Attachments object from the cache
      description: 'Attachment metadata synced from Vista DM (HQAT). Does not include file bytes or download URLs. To retrieve file content, call attachment_files/cache_file with UniqueAttchID, AttachmentID, or KeyID from this object.


        Vista view: HQAT'
      operationId: GET/direct/subscribers/{subscriber_code}/vista/dm/2/data/attachments/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_attachments_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/dm/2/data/attachments/cache/keyid/{KeyID}
  /direct/subscribers/{subscriber_code}/vista/dm/2/data/attachments/cache/natural/{AttachmentID}:
    get:
      tags:
      - Attachments
      summary: Gets one Attachments object from the cache
      description: 'Attachment metadata synced from Vista DM (HQAT). Does not include file bytes or download URLs. To retrieve file content, call attachment_files/cache_file with UniqueAttchID, AttachmentID, or KeyID from this object.


        Vista view: HQAT'
      operationId: GET/direct/subscribers/{subscriber_code}/vista/dm/2/data/attachments/cache/natural/{AttachmentID}
      parameters:
      - $ref: '#/components/parameters/subscriber_code'
      - $ref: '#/components/parameters/X-Application-Key'
      - name: AttachmentID
        in: path
        description: The AttachmentID 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_attachments_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/dm/2/data/attachments/cache/natural/{AttachmentID}
  /direct/subscribers/{subscriber_code}/vista/dm/2/data/attachments/actions/add:
    post:
      tags:
      - Attachments
      summary: Executes the Add action for the Attachments data object
      description: 'Adds a new attachment to a Vista record. Provide URLToFileBytes pointing to the file to upload (public HTTP URL or an App Xchange/AppNetwork file URL). The connector downloads the bytes and writes them to Vista per DM attachment options (HQAO): HQAF database storage or filesystem path.'
      operationId: POST/direct/subscribers/{subscriber_code}/vista/dm/2/data/attachments/actions/add
      parameters:
      - $ref: '#/components/parameters/subscriber_code'
      - $ref: '#/components/parameters/X-Application-Key'
      requestBody:
        content:
          application/json:
            schema:
              required:
              - HQCo
              - FormName
              - KeyField
              - DocAttchYN
              - IsEmail
              - URLToFileBytes
              - TableName
              - OrigFileName
              type: object
              properties:
                HQCo:
                  type: integer
                  description: HQ Company
                FormName:
                  maxLength: 30
                  type: string
                  description: Name of the form this file will be attached to.
                KeyField:
                  maxLength: 500
                  type: string
                  description: Formatted string representing the where clause of the parent form (ie. KeyID = 123
                Description:
                  maxLength: 255
                  type:
                  - string
                  - 'null'
                  description: Description of the file.
                TableName:
                  maxLength: 128
                  type:
                  - string
                  - 'null'
                  description: Table name/View name for the record that this file is being attached to.
                OrigFileName:
                  maxLength: 512
                  type:
                  - string
                  - 'null'
                  description: Original file name and dot extension.  No path information.
                DocAttchYN:
                  enum:
                  - Y
                  - N
                  type: string
                  description: Y - Document Type attachment. N - non document type attachment.  PM module looks at this value.  Generally speaking Y should be provided.
                IsEmail:
                  enum:
                  - Y
                  - N
                  type: string
                  description: ''
                AttachmentTypeID:
                  type:
                  - integer
                  - 'null'
                  description: ''
                URLToFileBytes:
                  type: string
                  description: URL to download the file bytes to upload into Vista. Supports public HTTP(S) URLs and App Xchange/AppNetwork file URLs.
      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:
                - AttachmentID
                - KeyID
                type: object
                properties:
                  AttachmentID:
                    type: integer
                    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: ''
        x-$.result for Failed:
          description: Object returned at $.result from GET /direct/actions/{action_key_value} when $.status = "Failed"
          content:
            application/json:
              schema:
                required:
                - errors
                type: object
                properties:
                  errors:
                    minItems: 1
                    type: array
                    items:
                      required:
                      - text
                      type: object
                      properties:
                        code:
                          type: integer
                        text:
                          type: string
      x-operation-id-source: normalized
      x-operation-id-original: POST /direct/subscribers/{subscriber_code}/vista/dm/2/data/attachments/actions/add
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_attachments:
      required:
      - HQCo
      - FormName
      - KeyField
      - AttachmentID
      - DocAttchYN
      - CurrentState
      - IsEmail
      - KeyID
      type: object
      properties:
        HQCo:
          type: integer
          description: ''
        FormName:
          maxLength: 30
          type: string
          description: ''
        KeyField:
          maxLength: 500
          type: string
          description: ''
        Description:
          maxLength: 255
          type:
          - string
          - 'null'
          description: ''
        AddedBy:
          maxLength: 128
          type:
          - string
          - 'null'
          description: ''
        AddDate:
          type:
          - string
          - 'null'
          description: ''
        DocName:
          maxLength: 512
          type:
          - string
          - 'null'
          description: Filesystem path to attachment bytes when HQAO SaveToDatabase=N. cache_file reads this path when staging files out of Vista.
        AttachmentID:
          type: integer
          description: ''
        TableName:
          maxLength: 128
          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: Vista DM attachment GUID (HQAT.UniqueAttchID). Pass to attachment_files/cache_file to download file bytes.
        OrigFileName:
          maxLength: 512
          type:
          - string
          - 'null'
          description: ''
        DocAttchYN:
          enum:
          - Y
          - N
          type: string
          description: ''
        CurrentState:
          maxLength: 1
          type: string
          description: (A)ttached, (S)tandalone, (D)eleted
        AttachmentTypeID:
          type:
          - integer
          - 'null'
          description: ''
        IsEmail:
          enum:
          - Y
          - N
          type: string
          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.
    data_attachments_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_attachments'