Trimble Crews API

openapi: 3.2.0
info:
  title: Vista Payroll v2 Direct Crews 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: Crews
paths:
  /direct/subscribers/{subscriber_code}/vista/pr/2/data/crews/cache:
    get:
      tags:
      - Crews
      summary: Gets all Crews objects from the cache
      description: 'Represents data found in Vista™ PR Crews program.


        Vista views PRCR, PRCW'
      operationId: GET/direct/subscribers/{subscriber_code}/vista/pr/2/data/crews/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_crews_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/pr/2/data/crews/cache
  /direct/subscribers/{subscriber_code}/vista/pr/2/data/crews/cache/search:
    post:
      tags:
      - Crews
      summary: Search through Crews objects in the data cache
      description: 'Represents data found in Vista™ PR Crews program.


        Vista views PRCR, PRCW'
      operationId: POST/direct/subscribers/{subscriber_code}/vista/pr/2/data/crews/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_crews_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/pr/2/data/crews/cache/search/search
  /direct/subscribers/{subscriber_code}/vista/pr/2/data/crews/cache/{ryvitId_value}:
    get:
      tags:
      - Crews
      summary: Gets one Crews object from the cache
      description: 'Represents data found in Vista™ PR Crews program.


        Vista views PRCR, PRCW'
      operationId: GET/direct/subscribers/{subscriber_code}/vista/pr/2/data/crews/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_crews_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/pr/2/data/crews/cache/{ryvitId_value}
  /direct/subscribers/{subscriber_code}/vista/pr/2/data/crews/cache/__ryvitId/{ryvitId_value}:
    get:
      tags:
      - Crews
      summary: Gets one Crews object from the cache
      description: 'Represents data found in Vista™ PR Crews program.


        Vista views PRCR, PRCW'
      operationId: GET/direct/subscribers/{subscriber_code}/vista/pr/2/data/crews/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_crews_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/pr/2/data/crews/cache/__ryvitId/{ryvitId_value}
  /direct/subscribers/{subscriber_code}/vista/pr/2/data/crews/cache/natural/{PRCo}/{Crew}:
    get:
      tags:
      - Crews
      summary: Gets one Crews object from the cache
      description: 'Represents data found in Vista™ PR Crews program.


        Vista views PRCR, PRCW'
      operationId: GET/direct/subscribers/{subscriber_code}/vista/pr/2/data/crews/cache/natural/{PRCo,Crew}
      parameters:
      - $ref: '#/components/parameters/subscriber_code'
      - $ref: '#/components/parameters/X-Application-Key'
      - name: PRCo
        in: path
        description: The PRCo portion of the key used to identify the object.
        required: true
        schema:
          type: string
      - name: Crew
        in: path
        description: The Crew 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_crews_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/pr/2/data/crews/cache/natural/{PRCo,Crew}
  /direct/subscribers/{subscriber_code}/vista/pr/2/data/crews/cache/keyid/{KeyID}:
    get:
      tags:
      - Crews
      summary: Gets one Crews object from the cache
      description: 'Represents data found in Vista™ PR Crews program.


        Vista views PRCR, PRCW'
      operationId: GET/direct/subscribers/{subscriber_code}/vista/pr/2/data/crews/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_crews_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/pr/2/data/crews/cache/keyid/{KeyID}
  /direct/subscribers/{subscriber_code}/vista/pr/2/data/crews/actions/add:
    post:
      tags:
      - Crews
      summary: Executes the Add action for the Crews data object
      description: Add
      operationId: POST/direct/subscribers/{subscriber_code}/vista/pr/2/data/crews/actions/add
      parameters:
      - $ref: '#/components/parameters/subscriber_code'
      - $ref: '#/components/parameters/X-Application-Key'
      requestBody:
        content:
          application/json:
            schema:
              title: Add Crew
              required:
              - PRCo
              - Crew
              - PRGroup
              - ApprovalReq
              type: object
              properties:
                PRCo:
                  type: integer
                  description: Payroll Company
                Crew:
                  maxLength: 10
                  type: string
                  description: Crew Identifier
                Description:
                  maxLength: 30
                  type:
                  - string
                  - 'null'
                Notes:
                  type:
                  - string
                  - 'null'
                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'
                JCCo:
                  type:
                  - integer
                  - 'null'
                Job:
                  maxLength: 10
                  type:
                  - string
                  - 'null'
                PhaseGroup:
                  type:
                  - integer
                  - 'null'
                Phase1:
                  maxLength: 20
                  type:
                  - string
                  - 'null'
                Phase2:
                  maxLength: 20
                  type:
                  - string
                  - 'null'
                Phase3:
                  maxLength: 20
                  type:
                  - string
                  - 'null'
                Phase4:
                  maxLength: 20
                  type:
                  - string
                  - 'null'
                Phase5:
                  maxLength: 20
                  type:
                  - string
                  - 'null'
                Phase6:
                  maxLength: 20
                  type:
                  - string
                  - 'null'
                Phase7:
                  maxLength: 20
                  type:
                  - string
                  - 'null'
                Phase8:
                  maxLength: 20
                  type:
                  - string
                  - 'null'
                RegECOvride:
                  type:
                  - integer
                  - 'null'
                OTECOvride:
                  type:
                  - integer
                  - 'null'
                DblECOvride:
                  type:
                  - integer
                  - 'null'
                PRGroup:
                  type: integer
                Shift:
                  type:
                  - integer
                  - 'null'
                ApprovalReq:
                  enum:
                  - Y
                  - N
                  type: string
                __custom_fields:
                  type: object
                Members:
                  type: array
                  items:
                    required:
                    - Seq
                    - UseStdHrs
                    type: object
                    properties:
                      Seq:
                        type: integer
                      Employee:
                        type:
                        - integer
                        - 'null'
                      UseStdHrs:
                        enum:
                        - Y
                        - N
                        type: string
                      AddOnHrs:
                        pattern: ^[-+]?[0-9]{1,8}(?:.[0-9]{0,2})?$
                        type:
                        - string
                        - 'null'
                      EMCo:
                        type:
                        - integer
                        - 'null'
                      Equipment:
                        maxLength: 10
                        type:
                        - string
                        - 'null'
                      EMGroup:
                        type:
                        - integer
                        - 'null'
                      RevCode:
                        maxLength: 10
                        type:
                        - string
                        - 'null'
                      UsagePct:
                        pattern: ^[-+]?[0-9]{1,2}(?:.[0-9]{0,4})?$
                        type:
                        - string
                        - 'null'
                      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'
              additionalProperties: false
      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:
                - PRCo
                - Crew
                - KeyID
                type: object
                properties:
                  PRCo:
                    type: integer
                    description: ''
                  Crew:
                    maxLength: 10
                    type: string
                    description: ''
                  KeyID:
                    type: integer
        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/pr/2/data/crews/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:
    data_crews:
      required:
      - PRCo
      - Crew
      - PRGroup
      - ApprovalReq
      - KeyID
      type: object
      properties:
        PRCo:
          type: integer
          description: ''
        Crew:
          maxLength: 10
          type: string
          description: ''
        Description:
          maxLength: 30
          type:
          - string
          - 'null'
          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: ''
        JCCo:
          type:
          - integer
          - 'null'
          description: ''
        Job:
          maxLength: 10
          type:
          - string
          - 'null'
          description: ''
        PhaseGroup:
          type:
          - integer
          - 'null'
          description: ''
        Phase1:
          maxLength: 20
          type:
          - string
          - 'null'
          description: ''
        Phase2:
          maxLength: 20
          type:
          - string
          - 'null'
          description: ''
        Phase3:
          maxLength: 20
          type:
          - string
          - 'null'
          description: ''
        Phase4:
          maxLength: 20
          type:
          - string
          - 'null'
          description: ''
        Phase5:
          maxLength: 20
          type:
          - string
          - 'null'
          description: ''
        Phase6:
          maxLength: 20
          type:
          - string
          - 'null'
          description: ''
        Phase7:
          maxLength: 20
          type:
          - string
          - 'null'
          description: ''
        Phase8:
          maxLength: 20
          type:
          - string
          - 'null'
          description: ''
        RegECOvride:
          type:
          - integer
          - 'null'
          description: ''
        OTECOvride:
          type:
          - integer
          - 'null'
          description: ''
        DblECOvride:
          type:
          - integer
          - 'null'
          description: ''
        PRGroup:
          type: integer
          description: ''
        Shift:
          type:
          - integer
          - 'null'
          description: ''
        ApprovalReq:
          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.
        Members:
          type: array
          items:
            required:
            - Seq
            - UseStdHrs
            - KeyID
            type: object
            properties:
              Seq:
                type: integer
                description: ''
              Employee:
                type:
                - integer
                - 'null'
                description: ''
              UseStdHrs:
                enum:
                - Y
                - N
                type: string
                description: ''
              AddOnHrs:
                pattern: ^[-+]?[0-9]{1,8}(?:.[0-9]{0,2})?$
                type:
                - string
                - 'null'
                description: ''
              EMCo:
                type:
                - integer
                - 'null'
                description: ''
              Equipment:
                maxLength: 10
                type:
                - string
                - 'null'
                description: ''
              EMGroup:
                type:
                - integer
                - 'null'
                description: ''
              RevCode:
                maxLength: 10
                type:
                - string
                - 'null'
                description: ''
              UsagePct:
                pattern: ^[-+]?[0-9]{1,2}(?:.[0-9]{0,4})?$
                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: ''
    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_crews_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:
            - natural/{PRCo}/{Crew}
          __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_crews'