Workist Invoices API

openapi: 3.0.3
info:
  title: Workist Integrations & Developer Delivery Notes Invoices API
  version: v1
  description: With this API you can access different resources of the Workist platform (e.g. processed documents, masterdata imports)
  termsOfService: https://www.workist.com/terms-of-use
  contact:
    email: info@workist.com
servers:
- url: /v1/
- url: /api/v1/
tags:
- name: Invoices
paths:
  /invoices:
    get:
      operationId: invoices_list
      description: 'To extract data from a file a `Processing Record` is created. Each `Processing Record` is part of a `Channel`. A `Channel` defines which fields should be extracted, confidence thresholds and more. '
      summary: Get all processing records for this document type
      parameters:
      - in: query
        name: channel
        schema:
          type: string
        description: Id of a processing channel
      - in: query
        name: assistance_needed
        schema:
          type: boolean
        description: Filter by assistance needed records
      - in: query
        name: finished
        schema:
          type: boolean
        description: Filter by finished records
      - in: query
        name: imported
        schema:
          type: boolean
        description: Filter records marked as [SUCCEEDED]
      - in: query
        name: import_failed
        schema:
          type: boolean
        description: Filter records marked as [FAILED]
      - in: query
        name: created_by
        schema:
          type: string
        description: Email address or id of a user.
      - in: query
        name: assisted_by
        schema:
          type: string
        description: Email address or id of a user.
      - in: query
        name: date_from
        schema:
          type: string
          format: date-time
        description: 'Beginning of a date range (based on created_at) in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`'
      - in: query
        name: date_to
        schema:
          type: string
          format: date-time
        description: 'End of a date range (based on created_at) in ISO 8601 format: `YYYY-MM-DDTHH:MM:SSZ`'
      - name: page
        required: false
        in: query
        description: A page number within the paginated result set.
        schema:
          type: integer
      - name: page_size
        required: false
        in: query
        description: Number of results to return per page.
        schema:
          type: integer
      - in: query
        name: show_unfinished_data
        schema:
          type: boolean
        description: 'By default, only completed data is displayed to avoid inaccuracies. However, you can use this parameter to access data still under processing.


          Default: `False`'
      tags:
      - Invoices
      security:
      - BearerAuthentication: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedInvoiceProcessingRecordList'
          description: ''
        '400':
          description: The request was unacceptable, often due to missing a required parameter or an invalid value.
        '401':
          description: Unauthorized, no valid token provided.
        '404':
          description: The requested resource doesn't exist.
        '500':
          description: Something went wrong on Workist's end.
    post:
      operationId: invoices_create
      description: 'To extract data from a file a `Processing Record` is created. Each `Processing Record` is part of a `Channel`. A `Channel` defines which fields should be extracted, confidence thresholds and more. '
      summary: Add a new processing record for this document type
      parameters:
      - in: query
        name: show_unfinished_data
        schema:
          type: boolean
        description: 'By default, only completed data is displayed to avoid inaccuracies. However, you can use this parameter to access data still under processing.


          Default: `False`'
      tags:
      - Invoices
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/CreateDocumentRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/CreateDocumentRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/CreateDocumentRequest'
        required: true
      security:
      - BearerAuthentication: []
      responses:
        '201':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceProcessingRecord'
          description: ''
        '400':
          description: The request was unacceptable, often due to missing a required parameter or an invalid value.
        '401':
          description: Unauthorized, no valid token provided.
        '404':
          description: The requested resource doesn't exist.
        '500':
          description: Something went wrong on Workist's end.
  /invoices/{id}:
    get:
      operationId: invoices_retrieve
      description: 'To extract data from a file a `Processing Record` is created. Each `Processing Record` is part of a `Channel`. A `Channel` defines which fields should be extracted, confidence thresholds and more. '
      summary: Get a specific processing record for this document type
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this invoice processing record.
        required: true
      - in: query
        name: show_unfinished_data
        schema:
          type: boolean
        description: 'By default, only completed data is displayed to avoid inaccuracies. However, you can use this parameter to access data still under processing.


          Default: `False`'
      tags:
      - Invoices
      security:
      - BearerAuthentication: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceProcessingRecord'
          description: ''
        '400':
          description: The request was unacceptable, often due to missing a required parameter or an invalid value.
        '401':
          description: Unauthorized, no valid token provided.
        '404':
          description: The requested resource doesn't exist.
        '500':
          description: Something went wrong on Workist's end.
    delete:
      operationId: invoices_destroy
      description: 'To extract data from a file a `Processing Record` is created. Each `Processing Record` is part of a `Channel`. A `Channel` defines which fields should be extracted, confidence thresholds and more. '
      summary: Delete a processing record of this document type
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this invoice processing record.
        required: true
      tags:
      - Invoices
      security:
      - BearerAuthentication: []
      responses:
        '204':
          description: No response body
        '400':
          description: The request was unacceptable, often due to missing a required parameter or an invalid value.
        '401':
          description: Unauthorized, no valid token provided.
        '404':
          description: The requested resource doesn't exist.
        '500':
          description: Something went wrong on Workist's end.
  /invoices/{id}/assign_user:
    put:
      operationId: invoices_assign_user_update
      description: The user will be stored in the field `assigned_to`.
      summary: Assign a user to a specific processing record of this document type
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this invoice processing record.
        required: true
      - in: query
        name: show_unfinished_data
        schema:
          type: boolean
        description: 'By default, only completed data is displayed to avoid inaccuracies. However, you can use this parameter to access data still under processing.


          Default: `False`'
      tags:
      - Invoices
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AssignUserRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AssignUserRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AssignUserRequest'
        required: true
      security:
      - BearerAuthentication: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceProcessingRecord'
          description: ''
        '400':
          description: The request was unacceptable, often due to missing a required parameter or an invalid value.
        '401':
          description: Unauthorized, no valid token provided.
        '404':
          description: The requested resource doesn't exist.
        '500':
          description: Something went wrong on Workist's end.
  /invoices/{id}/mark_imported:
    put:
      operationId: invoices_mark_imported_update
      description: The external data will be stored in the fields `external_reference`, `external_status` and `external_message`.
      summary: Mark a processing record of this document type as imported
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this invoice processing record.
        required: true
      - in: query
        name: show_unfinished_data
        schema:
          type: boolean
        description: 'By default, only completed data is displayed to avoid inaccuracies. However, you can use this parameter to access data still under processing.


          Default: `False`'
      tags:
      - Invoices
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MarkImportedRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/MarkImportedRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/MarkImportedRequest'
      security:
      - BearerAuthentication: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceProcessingRecord'
          description: ''
        '400':
          description: The request was unacceptable, often due to missing a required parameter or an invalid value.
        '401':
          description: Unauthorized, no valid token provided.
        '404':
          description: The requested resource doesn't exist.
        '500':
          description: Something went wrong on Workist's end.
  /invoices/{id}/meta:
    patch:
      operationId: invoices_meta_partial_update
      summary: Update the meta information of a processing record of this document type
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this invoice processing record.
        required: true
      - in: query
        name: show_unfinished_data
        schema:
          type: boolean
        description: 'By default, only completed data is displayed to avoid inaccuracies. However, you can use this parameter to access data still under processing.


          Default: `False`'
      tags:
      - Invoices
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PatchedMetaRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/PatchedMetaRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/PatchedMetaRequest'
      security:
      - BearerAuthentication: []
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/InvoiceProcessingRecord'
          description: ''
        '400':
          description: The request was unacceptable, often due to missing a required parameter or an invalid value.
        '401':
          description: Unauthorized, no valid token provided.
        '404':
          description: The requested resource doesn't exist.
        '500':
          description: Something went wrong on Workist's end.
components:
  schemas:
    MarkImportedRequest:
      type: object
      properties:
        status:
          enum:
          - PENDING
          - SUCCEEDED
          - FAILED
          type: string
          default: SUCCEEDED
          description: 'Default is `SUCCEEDED`. If once marked as `SUCCEEDED` it cannot be changed anymore. If marked as `FAILED` the record will be displayed in the `open` tab and a user needs to take action again (either reopen for assistance to resolve the issue or deleting/discarding the record).


            * `PENDING` - Pending

            * `SUCCEEDED` - Succeeded

            * `FAILED` - Failed'
        external_reference:
          type: string
          minLength: 1
          default: ''
          description: Id that represents this record in the target system
        external_status:
          type: string
          minLength: 1
          default: ''
          description: Status of the record in the target system
        external_message:
          type: string
          minLength: 1
          default: ''
          description: E.g. error message
    PatchedMetaRequest:
      type: object
      properties:
        sender:
          type: string
          minLength: 1
          default: ''
          description: Sender of the document (e.g. sender of the original email)
        subject:
          type: string
          minLength: 1
          default: ''
          description: Subject of the document (e.g. subject of the original email)
    InvoiceProcessingRecord:
      type: object
      properties:
        id:
          type: string
          format: uuid
          readOnly: true
        channel:
          type: string
          nullable: true
          readOnly: true
        status:
          type: string
        sender:
          type: string
          nullable: true
        subject:
          type: string
          nullable: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        created_by:
          allOf:
          - $ref: '#/components/schemas/User'
          readOnly: true
        assigned_to:
          allOf:
          - $ref: '#/components/schemas/User'
          readOnly: true
        assisted_by:
          allOf:
          - $ref: '#/components/schemas/User'
          readOnly: true
        assisted_at:
          type: string
          format: date-time
          nullable: true
        delivered_at:
          type: string
          format: date-time
          readOnly: true
        finished_at:
          type: string
          format: date-time
          nullable: true
        imported_at:
          type: string
          format: date-time
          readOnly: true
        email_file_url:
          type: string
          nullable: true
          readOnly: true
        input_file_url:
          type: string
          nullable: true
          readOnly: true
        classified_files:
          type: array
          items:
            type: object
            additionalProperties:
              type: string
          readOnly: true
        additional_file_urls:
          type: array
          items:
            type: string
          nullable: true
          description: Rarely used in customisations
          readOnly: true
        workbench_url:
          type: string
          format: uri
          readOnly: true
        external_reference:
          type: string
          nullable: true
          readOnly: true
        external_status:
          type: string
          nullable: true
          readOnly: true
        external_message:
          type: string
          nullable: true
          readOnly: true
        data:
          allOf:
          - $ref: '#/components/schemas/Invoice'
          readOnly: true
      required:
      - additional_file_urls
      - assigned_to
      - assisted_by
      - channel
      - classified_files
      - created_at
      - created_by
      - data
      - delivered_at
      - email_file_url
      - external_message
      - external_reference
      - external_status
      - id
      - imported_at
      - input_file_url
      - status
      - updated_at
      - workbench_url
    PaginatedInvoiceProcessingRecordList:
      type: object
      required:
      - count
      - results
      properties:
        next:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=4
        previous:
          type: string
          nullable: true
          format: uri
          example: http://api.example.org/accounts/?page=2
        items:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceProcessingRecord'
        total_count:
          type: integer
          example: 123
    CreateDocumentRequest:
      type: object
      properties:
        channel:
          type: string
          format: uuid
          description: Id of a processing channel
        file:
          type: string
          format: binary
          description: File to be processed
        user:
          type: string
          minLength: 1
          description: Email address or id of a user.
      required:
      - channel
      - file
    ContactPerson:
      type: object
      properties:
        number:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
    AssignUserRequest:
      type: object
      properties:
        user:
          type: string
          minLength: 1
          description: Email address or id of a user.
      required:
      - user
    Address:
      type: object
      properties:
        number:
          type: string
          nullable: true
        number2:
          type: string
          nullable: true
        number3:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        misc:
          type: string
          nullable: true
        company_name:
          type: string
          nullable: true
        company_name2:
          type: string
          nullable: true
        company_name3:
          type: string
          nullable: true
        company_name4:
          type: string
          nullable: true
        street_and_nr:
          type: string
          nullable: true
        street_name:
          type: string
          nullable: true
        street_number:
          type: string
          nullable: true
        postal_code:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        country_subdivision:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        phone:
          type: string
          nullable: true
        email:
          type: string
          nullable: true
    InvoiceLineItem:
      type: object
      properties:
        pos:
          type: string
          nullable: true
        article_number:
          type: string
          nullable: true
        article_number_2:
          type: string
          nullable: true
        article_number_3:
          type: string
          nullable: true
        external_article_number:
          type: string
          nullable: true
        external_reference:
          type: string
          nullable: true
        article_description:
          type: string
          nullable: true
        unit:
          type: string
          nullable: true
        quantity:
          type: string
          nullable: true
        unit_price:
          type: string
          nullable: true
        price_unit:
          type: string
          nullable: true
        total_price:
          type: string
          nullable: true
        order_number:
          type: string
          nullable: true
        tax_rate:
          type: string
          nullable: true
        tax_amount:
          type: string
          nullable: true
        fulfillment_date:
          type: string
          nullable: true
    User:
      type: object
      properties:
        first_name:
          type: string
          maxLength: 150
        last_name:
          type: string
          maxLength: 150
        email:
          type: string
          format: email
          title: Email address
          maxLength: 254
      required:
      - email
    Invoice:
      type: object
      properties:
        invoice_number:
          type: string
          nullable: true
        order_number:
          type: string
          nullable: true
        contract_number:
          type: string
          nullable: true
        delivery_note_number:
          type: string
          nullable: true
        invoice_date:
          type: string
          nullable: true
        invoice_due_date:
          type: string
          nullable: true
        delivery_date:
          type: string
          nullable: true
        recipient_customer_number:
          type: string
          nullable: true
        recipient_address:
          allOf:
          - $ref: '#/components/schemas/Address'
          nullable: true
        recipient_contact:
          allOf:
          - $ref: '#/components/schemas/ContactPerson'
          nullable: true
        sender_supplier:
          allOf:
          - $ref: '#/components/schemas/Customer'
          nullable: true
        sender_vat_id:
          type: string
          nullable: true
        sender_tax_number:
          type: string
          nullable: true
        sender_address:
          allOf:
          - $ref: '#/components/schemas/Address'
          nullable: true
        sender_contact:
          allOf:
          - $ref: '#/components/schemas/ContactPerson'
          nullable: true
        payment_bank:
          type: string
          nullable: true
        payment_bic:
          type: string
          nullable: true
        payment_iban:
          type: string
          nullable: true
        payment_method:
          type: string
          nullable: true
        payment_reference:
          type: string
          nullable: true
        payment_swift:
          type: string
          nullable: true
        payment_terms_discount:
          type: string
          nullable: true
        payment_terms_due_days:
          type: string
          nullable: true
        payment_terms_type:
          type: string
          nullable: true
        payment_terms:
          type: string
          nullable: true
        document_type:
          type: string
          nullable: true
        currency:
          type: string
          nullable: true
        net_amount:
          type: string
          nullable: true
        tax_rate:
          type: string
          nullable: true
        tax_amount:
          type: string
          nullable: true
        total_amount:
          type: string
          nullable: true
        total_due:
          type: string
          nullable: true
        line_items:
          type: array
          items:
            $ref: '#/components/schemas/InvoiceLineItem'
          nullable: true
    Customer:
      type: object
      properties:
        number:
          type: string
          nullable: true
        number2:
          type: string
          nullable: true
        name:
          type: string
          nullable: true
        street_and_nr:
          type: string
          nullable: true
        postal_code:
          type: string
          nullable: true
        city:
          type: string
          nullable: true
        country:
          type: string
          nullable: true
        customer_type:
          type: string
          nullable: true
        iln:
          type: string
          nullable: true
        contact_person:
          type: string
          nullable: true
  securitySchemes:
    BearerAuthentication:
      type: http
      scheme: bearer
externalDocs:
  url: https://workist.notion.site/How-to-Use-the-Master-Data-API-4fb9f1279ae8421088495e20b846b179
  description: Master data implementation guide (includes code examples)