Truework subpackage_orders API

openapi: 3.1.0
info:
  title: Truework Qualifications & Tenant Properties API (Beta) subpackage_orders API
  description: 'Public beta surfaces of the Truework API covering Qualification Checks (lightweight income/employment knockout decisions against a borrower''s verified employment data) and Tenant Properties (provider-defined verification configuration knobs). These endpoints are in public beta and the schema may evolve.

    '
  version: 2023-10-30-beta
  contact:
    name: Truework Implementations
    email: implementations@truework.com
    url: https://www.truework.com/docs
  license:
    name: Truework Terms of Service
    url: https://www.truework.com/legal/terms
servers:
- url: https://api.truework-sandbox.com
- url: https://api.truework.com
tags:
- name: subpackage_orders
paths:
  /orders/target-employer:
    post:
      operationId: create-new-target-employer-verification
      summary: Create a target employer order
      description: 'Creates a new order and verification. Returns a JSON object representing the newly created order and verification.


        A target employer verification is distinct in that it _requires_ a target employer in the request body for processing.


        ## Verification processing


        Target employer verifications are processed _asynchronously_: they will be created and returned in the response body without any [reports](api.yaml/paths/~1verification-requests~1{verification_id}~1report/get). Truework will then send a webhook when the request has finished processing, and the reports can be retrieved.


        This creates a verification request with the following attributes:


        - Target employer required

        - Is processed asynchronously

        - Can be any client-defined combination of Instant, Credentials, and Smart Outreach verification methods

        - Returns the verification on a new order object


        ### Controlling Processing with request config


        The request config object allows you to configure how you use Truework by selecting only the verification methods and features you need.

        '
      tags:
      - subpackage_orders
      parameters:
      - name: Authorization
        in: header
        description: 'Bearer tokens conform to the [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1) spec.



          Production API keys (secret keys) are prefixed with `tw_sk_` and sandbox keys are prefixed with `tw_sk_test_`. If your secret key is published, you should rotate your API keys.


          Truework.JS publishable keys are prefixed with `tw_pk_` and `tw_pk_test` respectively.



          **Examples**

          - For Authorization Headers: `Authorization: Bearer tw_sk_test_e508eb797edb95ade85284bcb54dd49ed45db1be`

          - For the "try it now" `token` field, input only the token itself, omitting `Bearer `.'
        required: true
        schema:
          type: string
      - name: Accept
        in: header
        description: Specify the content type and version that the API should use. It's recommended to include this to avoid breaking changes.
        required: false
        schema:
          $ref: '#/components/schemas/OrdersTargetEmployerPostParametersAccept'
          default: application/json
      responses:
        '201':
          description: Order Request Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponseResourceV20231030'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: The request's authorization is missing, invalid, or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '406':
          description: An invalid API version was requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error406'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429'
        '451':
          description: Frozen SSN
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error451'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error501'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderTargetEmployerVerificationRequestV20231030'
  /orders/employer-search:
    post:
      operationId: create-new-order-employer-search-verification
      summary: Create an employer search order
      description: 'POST requests create both an order and a verification. Returns a JSON object representing the newly created order and verification.


        ## Verification processing


        Employer search verifications are processed _synchronously_: Truework will attempt to process the verification during the initial POST request. If successful, the `201` response will include a `reports` key, which will contain the requested data.


        It is recommended to set a timeout on synchronous requests, to account for potential latency when calling our

        partners. Synchronous requests generally take only a few seconds to complete, but in rare cases they may take longer.


        This creates a verification request with the following attributes:


        - No target company

        - Is processed synchronously

        - Is Instant verification method only

        - Filter employers by one of the following: any-employers, current-employers, previous-employers

        - Returns the verification on a new order object

        '
      tags:
      - subpackage_orders
      parameters:
      - name: fields
        in: query
        description: Comma-separated names of fields to include in the response. Separate multiple fields with commas, and denote subfields with parentheses. Multiple subfields from the same type can be listed within parentheses. In case of a list, subfields apply to each individual object. If omitted, all fields are included.
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: include_income_analytics
        in: query
        description: Whether to calculate income analytics for the nested reports in each verification.
        required: false
        schema:
          type: boolean
          default: false
      - name: include_report_annotations
        in: query
        description: Include potentially unverified data in the response, including report annotations and unparsed documents.
        required: false
        schema:
          type: boolean
          default: false
      - name: Authorization
        in: header
        description: 'Bearer tokens conform to the [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1) spec.



          Production API keys (secret keys) are prefixed with `tw_sk_` and sandbox keys are prefixed with `tw_sk_test_`. If your secret key is published, you should rotate your API keys.


          Truework.JS publishable keys are prefixed with `tw_pk_` and `tw_pk_test` respectively.



          **Examples**

          - For Authorization Headers: `Authorization: Bearer tw_sk_test_e508eb797edb95ade85284bcb54dd49ed45db1be`

          - For the "try it now" `token` field, input only the token itself, omitting `Bearer `.'
        required: true
        schema:
          type: string
      - name: Accept
        in: header
        description: Specify the content type and version that the API should use. It's recommended to include this to avoid breaking changes.
        required: false
        schema:
          $ref: '#/components/schemas/OrdersEmployerSearchPostParametersAccept'
          default: application/json
      responses:
        '201':
          description: Order and Verification Request Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponseResourceV20231030'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: The request's authorization is missing, invalid, or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '406':
          description: An invalid API version was requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error406'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429'
        '451':
          description: Frozen SSN
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error451'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error501'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderEmployerSearchVerificationRequestV20231030'
  /orders/truework-direct:
    post:
      operationId: create-new-truework-direct-order
      summary: Create a Truework Direct order
      description: POST requests create an order with a Truework Direct session token, used for instantiating the Truework.js widget.
      tags:
      - subpackage_orders
      parameters:
      - name: Authorization
        in: header
        description: 'Bearer tokens conform to the [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1) spec.



          Production API keys (secret keys) are prefixed with `tw_sk_` and sandbox keys are prefixed with `tw_sk_test_`. If your secret key is published, you should rotate your API keys.


          Truework.JS publishable keys are prefixed with `tw_pk_` and `tw_pk_test` respectively.



          **Examples**

          - For Authorization Headers: `Authorization: Bearer tw_sk_test_e508eb797edb95ade85284bcb54dd49ed45db1be`

          - For the "try it now" `token` field, input only the token itself, omitting `Bearer `.'
        required: true
        schema:
          type: string
      - name: Accept
        in: header
        description: Specify the content type and version that the API should use. It's recommended to include this to avoid breaking changes.
        required: false
        schema:
          $ref: '#/components/schemas/OrdersTrueworkDirectPostParametersAccept'
          default: application/json
      responses:
        '201':
          description: Order Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponseResourceV20231030'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: The request's authorization is missing, invalid, or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '406':
          description: An invalid API version was requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error406'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429'
        '451':
          description: Frozen SSN
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error451'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error501'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderTrueworkDirectPostRequestV20231030'
  /orders/{order_id}:
    get:
      operationId: get-one-order
      summary: Get one order
      description: 'Retrieves an order by id.

        '
      tags:
      - subpackage_orders
      parameters:
      - name: order_id
        in: path
        description: Order ID
        required: true
        schema:
          type: string
      - name: include_report_annotations
        in: query
        description: Include potentially unverified data in the response, including report annotations and unparsed documents.
        required: false
        schema:
          type: boolean
          default: false
      - name: Authorization
        in: header
        description: 'Bearer tokens conform to the [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1) spec.



          Production API keys (secret keys) are prefixed with `tw_sk_` and sandbox keys are prefixed with `tw_sk_test_`. If your secret key is published, you should rotate your API keys.


          Truework.JS publishable keys are prefixed with `tw_pk_` and `tw_pk_test` respectively.



          **Examples**

          - For Authorization Headers: `Authorization: Bearer tw_sk_test_e508eb797edb95ade85284bcb54dd49ed45db1be`

          - For the "try it now" `token` field, input only the token itself, omitting `Bearer `.'
        required: true
        schema:
          type: string
      - name: Accept
        in: header
        description: Specify the content type and version that the API should use. It's recommended to include this to avoid breaking changes.
        required: false
        schema:
          $ref: '#/components/schemas/OrdersOrderIdGetParametersAccept'
          default: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponseResourceV20231030'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: The request's authorization is missing, invalid, or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '406':
          description: An invalid API version was requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error406'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429'
        '451':
          description: Frozen SSN
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error451'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error501'
  /orders:
    get:
      operationId: get-all-orders
      summary: Get all orders
      description: An order is a consolidation of multiple verifications.
      tags:
      - subpackage_orders
      parameters:
      - name: limit
        in: query
        description: Limit the number of results returned
        required: false
        schema:
          type: integer
          default: 25
      - name: offset
        in: query
        description: Offset the results by page
        required: false
        schema:
          type: integer
          default: 0
      - name: search_key
        in: query
        description: Filter by search_key value passed in on Order creation
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: include_report_annotations
        in: query
        description: Opt-in to including annotations on reports
        required: false
        schema:
          type: boolean
          default: false
      - name: verification_id
        in: query
        description: Filter by associated verification_id
        required: false
        schema:
          type:
          - string
          - 'null'
      - name: Authorization
        in: header
        description: 'Bearer tokens conform to the [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1) spec.



          Production API keys (secret keys) are prefixed with `tw_sk_` and sandbox keys are prefixed with `tw_sk_test_`. If your secret key is published, you should rotate your API keys.


          Truework.JS publishable keys are prefixed with `tw_pk_` and `tw_pk_test` respectively.



          **Examples**

          - For Authorization Headers: `Authorization: Bearer tw_sk_test_e508eb797edb95ade85284bcb54dd49ed45db1be`

          - For the "try it now" `token` field, input only the token itself, omitting `Bearer `.'
        required: true
        schema:
          type: string
      - name: Accept
        in: header
        description: Specify the content type and version that the API should use. It's recommended to include this to avoid breaking changes.
        required: false
        schema:
          $ref: '#/components/schemas/OrdersGetParametersAccept'
          default: application/json
      responses:
        '200':
          description: A list of Orders was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderListResponseResourceV20231030'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: The request's authorization is missing, invalid, or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '406':
          description: An invalid API version was requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error406'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429'
        '451':
          description: Frozen SSN
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error451'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error501'
  /orders/{order_id}/cancel:
    put:
      operationId: cancel-an-order
      summary: Cancel an order
      description: 'Cancels all verification requests on an order, provided each request is not already in a terminal state.

        '
      tags:
      - subpackage_orders
      parameters:
      - name: order_id
        in: path
        description: Order ID
        required: true
        schema:
          type: string
      - name: Authorization
        in: header
        description: 'Bearer tokens conform to the [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1) spec.



          Production API keys (secret keys) are prefixed with `tw_sk_` and sandbox keys are prefixed with `tw_sk_test_`. If your secret key is published, you should rotate your API keys.


          Truework.JS publishable keys are prefixed with `tw_pk_` and `tw_pk_test` respectively.



          **Examples**

          - For Authorization Headers: `Authorization: Bearer tw_sk_test_e508eb797edb95ade85284bcb54dd49ed45db1be`

          - For the "try it now" `token` field, input only the token itself, omitting `Bearer `.'
        required: true
        schema:
          type: string
      - name: Accept
        in: header
        description: Specify the content type and version that the API should use. It's recommended to include this to avoid breaking changes.
        required: false
        schema:
          $ref: '#/components/schemas/OrdersOrderIdCancelPutParametersAccept'
          default: application/json
      responses:
        '200':
          description: OK
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderCancelResponseResourceV20231030'
        '400':
          description: Bad Request or Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: The request's authorization is missing, invalid, or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '406':
          description: An invalid API version was requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error406'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429'
        '451':
          description: Frozen SSN
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error451'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error501'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderCancelPutRequestV20231030'
  /orders/{order_id}/events:
    get:
      operationId: get-order-events
      summary: Get order events
      description: Returns all events associated with an order.
      tags:
      - subpackage_orders
      parameters:
      - name: order_id
        in: path
        description: Order ID
        required: true
        schema:
          type: string
      - name: limit
        in: query
        description: Limit the number of results returned
        required: false
        schema:
          type: integer
          default: 25
      - name: offset
        in: query
        description: Offset the results by page
        required: false
        schema:
          type: integer
          default: 0
      - name: Authorization
        in: header
        description: 'Bearer tokens conform to the [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1) spec.



          Production API keys (secret keys) are prefixed with `tw_sk_` and sandbox keys are prefixed with `tw_sk_test_`. If your secret key is published, you should rotate your API keys.


          Truework.JS publishable keys are prefixed with `tw_pk_` and `tw_pk_test` respectively.



          **Examples**

          - For Authorization Headers: `Authorization: Bearer tw_sk_test_e508eb797edb95ade85284bcb54dd49ed45db1be`

          - For the "try it now" `token` field, input only the token itself, omitting `Bearer `.'
        required: true
        schema:
          type: string
      - name: Accept
        in: header
        description: Specify the content type and version that the API should use. It's recommended to include this to avoid breaking changes.
        required: false
        schema:
          $ref: '#/components/schemas/OrdersOrderIdEventsGetParametersAccept'
          default: application/json
      responses:
        '200':
          description: A list of Events was successfully retrieved.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/EventListResource'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: The request's authorization is missing, invalid, or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Order not found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '406':
          description: An invalid API version was requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error406'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429'
        '451':
          description: Frozen SSN
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error451'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error501'
  /orders/reverification:
    post:
      operationId: reverify-a-verification
      summary: Reverify a report
      description: Reverifies a report, provided no more than 90 days have passed since completion of the verification.
      tags:
      - subpackage_orders
      parameters:
      - name: Authorization
        in: header
        description: 'Bearer tokens conform to the [RFC6750](https://datatracker.ietf.org/doc/html/rfc6750#section-2.1) spec.



          Production API keys (secret keys) are prefixed with `tw_sk_` and sandbox keys are prefixed with `tw_sk_test_`. If your secret key is published, you should rotate your API keys.


          Truework.JS publishable keys are prefixed with `tw_pk_` and `tw_pk_test` respectively.



          **Examples**

          - For Authorization Headers: `Authorization: Bearer tw_sk_test_e508eb797edb95ade85284bcb54dd49ed45db1be`

          - For the "try it now" `token` field, input only the token itself, omitting `Bearer `.'
        required: true
        schema:
          type: string
      - name: Accept
        in: header
        description: Specify the content type and version that the API should use. It's recommended to include this to avoid breaking changes.
        required: false
        schema:
          $ref: '#/components/schemas/OrdersReverificationPostParametersAccept'
          default: application/json
      - name: Request-Sync
        in: header
        description: A header that defines if a request should be executed synchronously. Only Verifications that were initially executed synchronously may be reverified synchronously. `sync` can only return completed or canceled verification responses, not pending. `async` will return only pending.
        required: false
        schema:
          $ref: '#/components/schemas/OrdersReverificationPostParametersRequestSync'
          default: async
      responses:
        '201':
          description: Reverification Request Created.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/OrderResponseResourceV20231030'
        '400':
          description: Bad Request
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error400'
        '401':
          description: The request's authorization is missing, invalid, or expired
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error401'
        '403':
          description: Forbidden
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error403'
        '404':
          description: Not Found
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error404'
        '406':
          description: An invalid API version was requested
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error406'
        '429':
          description: Too Many Requests
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error429'
        '451':
          description: Frozen SSN
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error451'
        '500':
          description: Internal Server Error
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error500'
        '501':
          description: Not Implemented
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/Error501'
      requestBody:
        description: ''
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderReverificationRequestV20231030'
components:
  schemas:
    CompanyInputV20231030:
      type: object
 

# --- truncated at 32 KB (156 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/truework/refs/heads/main/openapi/truework-subpackage-orders-api-openapi.yml