Workist Master Data API

openapi: 3.0.3
info:
  title: Workist Integrations & Developer Delivery Notes Master Data 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: Master Data
paths:
  /master-data/addresses/imports:
    post:
      operationId: addresses_imports_create
      description: "Create a new import for the given `lookup_definition_id`. To see the schema that the data should conform to, please refer to the import endpoint parameters for each type of master data. \n\nNote: by default, the given data will be imported immediately. If your data volume exceeds the limits for a single request (see `file`, `file_url` and `data` parameters below), you can create a batched import instead (by setting `batched: true`). Batched imports are created in pending status and will accept additional batches of data, which are appended to the import. After all batches of data have been transferred, batched imports need to be started explicitly. "
      summary: Create a new master data import
      tags:
      - Master Data
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/AddressMasterDataImportRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/AddressMasterDataImportRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/AddressMasterDataImportRequest'
        required: true
      responses:
        '202':
          headers:
            Location:
              schema:
                type: string
              description: URL to get the import status
              required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
          description: The import run was created successfully. The status of the import can be checked by calling the import details endpoint with the returned import id.
        '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.
      security:
      - BearerAuthentication: []
  /master-data/articles/imports:
    post:
      operationId: articles_imports_create
      description: "Create a new import for the given `lookup_definition_id`. To see the schema that the data should conform to, please refer to the import endpoint parameters for each type of master data. \n\nNote: by default, the given data will be imported immediately. If your data volume exceeds the limits for a single request (see `file`, `file_url` and `data` parameters below), you can create a batched import instead (by setting `batched: true`). Batched imports are created in pending status and will accept additional batches of data, which are appended to the import. After all batches of data have been transferred, batched imports need to be started explicitly. "
      summary: Create a new master data import
      tags:
      - Master Data
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ArticleMasterDataImportRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ArticleMasterDataImportRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ArticleMasterDataImportRequest'
        required: true
      responses:
        '202':
          headers:
            Location:
              schema:
                type: string
              description: URL to get the import status
              required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
          description: The import run was created successfully. The status of the import can be checked by calling the import details endpoint with the returned import id.
        '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.
      security:
      - BearerAuthentication: []
  /master-data/clients/imports:
    post:
      operationId: clients_imports_create
      description: "Create a new import for the given `lookup_definition_id`. To see the schema that the data should conform to, please refer to the import endpoint parameters for each type of master data. \n\nNote: by default, the given data will be imported immediately. If your data volume exceeds the limits for a single request (see `file`, `file_url` and `data` parameters below), you can create a batched import instead (by setting `batched: true`). Batched imports are created in pending status and will accept additional batches of data, which are appended to the import. After all batches of data have been transferred, batched imports need to be started explicitly. "
      summary: Create a new master data import
      tags:
      - Master Data
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ClientMasterDataImportRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ClientMasterDataImportRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ClientMasterDataImportRequest'
        required: true
      responses:
        '202':
          headers:
            Location:
              schema:
                type: string
              description: URL to get the import status
              required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
          description: The import run was created successfully. The status of the import can be checked by calling the import details endpoint with the returned import id.
        '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.
      security:
      - BearerAuthentication: []
  /master-data/contacts/imports:
    post:
      operationId: contacts_imports_create
      description: "Create a new import for the given `lookup_definition_id`. To see the schema that the data should conform to, please refer to the import endpoint parameters for each type of master data. \n\nNote: by default, the given data will be imported immediately. If your data volume exceeds the limits for a single request (see `file`, `file_url` and `data` parameters below), you can create a batched import instead (by setting `batched: true`). Batched imports are created in pending status and will accept additional batches of data, which are appended to the import. After all batches of data have been transferred, batched imports need to be started explicitly. "
      summary: Create a new master data import
      tags:
      - Master Data
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ContactMasterDataImportRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ContactMasterDataImportRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ContactMasterDataImportRequest'
        required: true
      responses:
        '202':
          headers:
            Location:
              schema:
                type: string
              description: URL to get the import status
              required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
          description: The import run was created successfully. The status of the import can be checked by calling the import details endpoint with the returned import id.
        '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.
      security:
      - BearerAuthentication: []
  /master-data/conversion-factors/imports:
    post:
      operationId: conversion_factors_imports_create
      description: "Create a new import for the given `lookup_definition_id`. To see the schema that the data should conform to, please refer to the import endpoint parameters for each type of master data. \n\nNote: by default, the given data will be imported immediately. If your data volume exceeds the limits for a single request (see `file`, `file_url` and `data` parameters below), you can create a batched import instead (by setting `batched: true`). Batched imports are created in pending status and will accept additional batches of data, which are appended to the import. After all batches of data have been transferred, batched imports need to be started explicitly. "
      summary: Create a new master data import
      tags:
      - Master Data
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ConversionFactorMasterDataImportRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ConversionFactorMasterDataImportRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ConversionFactorMasterDataImportRequest'
        required: true
      responses:
        '202':
          headers:
            Location:
              schema:
                type: string
              description: URL to get the import status
              required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
          description: The import run was created successfully. The status of the import can be checked by calling the import details endpoint with the returned import id.
        '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.
      security:
      - BearerAuthentication: []
  /master-data/framework-contracts/imports:
    post:
      operationId: framework_contracts_imports_create
      description: "Create a new import for the given `lookup_definition_id`. To see the schema that the data should conform to, please refer to the import endpoint parameters for each type of master data. \n\nNote: by default, the given data will be imported immediately. If your data volume exceeds the limits for a single request (see `file`, `file_url` and `data` parameters below), you can create a batched import instead (by setting `batched: true`). Batched imports are created in pending status and will accept additional batches of data, which are appended to the import. After all batches of data have been transferred, batched imports need to be started explicitly. "
      summary: Create a new master data import
      tags:
      - Master Data
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/FrameworkContractMasterDataImportRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/FrameworkContractMasterDataImportRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/FrameworkContractMasterDataImportRequest'
        required: true
      responses:
        '202':
          headers:
            Location:
              schema:
                type: string
              description: URL to get the import status
              required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
          description: The import run was created successfully. The status of the import can be checked by calling the import details endpoint with the returned import id.
        '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.
      security:
      - BearerAuthentication: []
  /master-data/imports:
    get:
      operationId: imports_list
      description: Returns all your master data import runs.
      summary: Get all master data import runs
      parameters:
      - 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
      tags:
      - Master Data
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PaginatedDataImportRunList'
          description: Success
        '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.
      security:
      - BearerAuthentication: []
    post:
      operationId: imports_create
      description: "Create a new import for the given `lookup_definition_id`. To see the schema that the data should conform to, please refer to the import endpoint parameters for each type of master data. \n\nNote: by default, the given data will be imported immediately. If your data volume exceeds the limits for a single request (see `file`, `file_url` and `data` parameters below), you can create a batched import instead (by setting `batched: true`). Batched imports are created in pending status and will accept additional batches of data, which are appended to the import. After all batches of data have been transferred, batched imports need to be started explicitly. "
      summary: Create a new master data import
      tags:
      - Master Data
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/ImportRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/ImportRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/ImportRequest'
        required: true
      responses:
        '202':
          headers:
            Location:
              schema:
                type: string
              description: URL to get the import status
              required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
          description: The import run was created successfully. The status of the import can be checked by calling the import details endpoint with the returned import id.
        '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.
      security:
      - BearerAuthentication: []
  /master-data/imports/{id}:
    get:
      operationId: imports_retrieve
      description: Returns the details of a specific master data import run.
      summary: Get a specific master data import run
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this data import run.
        required: true
      tags:
      - Master Data
      responses:
        '200':
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/DataImportRun'
          description: Success
        '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.
      security:
      - BearerAuthentication: []
  /master-data/imports/{id}/data:
    post:
      operationId: imports_data_create
      description: Only for batched imports. Associates a batch of data (given as a `file`, `file_url` or JSON `data`) with the import. In case you are using the `file` or `file_url` parameters, each batch file needs to provide a similar header row containing the column names. To see the schema that the data should conform to, please refer to the import endpoint parameters for each type of master data. You can call this endpoint as often as needed to transfer all your data in batches, each batch will be appended to the import. When all data has been transferred, you need to start the import explicitly. Once the import has started processing, all data will be made available for download as a single CSV file (`input_file_url` and `input_file_num_rows` of the returned `DataImportRun`) - regardless of the format it was originally provided in. For a pretty overview of all imports and their status, you can check the master data imports in the Workbench (channel settings).
      summary: Append a batch of data to a batched import
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this data import run.
        required: true
      tags:
      - Master Data
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/DataRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/DataRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/DataRequest'
      responses:
        '202':
          headers:
            Location:
              schema:
                type: string
              description: URL to get the import status
              required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
          description: The data was successfully appended to the import. The status of the import can be checked by calling the import details endpoint with the returned import id.
        '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.
      security:
      - BearerAuthentication: []
  /master-data/imports/{id}/start:
    post:
      operationId: imports_start_create
      description: Only for batched imports. Starts the import and ingest all associated data. Note that you cannot POST any more batches of data to an import run once it has been started. If you have a single `file`, `file_url` or a small amount  of `data` that can be imported in a single request, prefer using a non-batched import instead.
      summary: Start the batched import & ingest all associated data
      parameters:
      - in: path
        name: id
        schema:
          type: string
          format: uuid
        description: A UUID string identifying this data import run.
        required: true
      tags:
      - Master Data
      responses:
        '202':
          headers:
            Location:
              schema:
                type: string
              description: URL to get the import status
              required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
          description: The import was started successfully
        '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.
      security:
      - BearerAuthentication: []
  /master-data/offer-matching/imports:
    post:
      operationId: offer_matching_imports_create
      description: "Create a new import for the given `lookup_definition_id`. To see the schema that the data should conform to, please refer to the import endpoint parameters for each type of master data. \n\nNote: by default, the given data will be imported immediately. If your data volume exceeds the limits for a single request (see `file`, `file_url` and `data` parameters below), you can create a batched import instead (by setting `batched: true`). Batched imports are created in pending status and will accept additional batches of data, which are appended to the import. After all batches of data have been transferred, batched imports need to be started explicitly. "
      summary: Create a new master data import
      tags:
      - Master Data
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OfferMatchingMasterDataImportRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/OfferMatchingMasterDataImportRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/OfferMatchingMasterDataImportRequest'
        required: true
      responses:
        '202':
          headers:
            Location:
              schema:
                type: string
              description: URL to get the import status
              required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
          description: The import run was created successfully. The status of the import can be checked by calling the import details endpoint with the returned import id.
        '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.
      security:
      - BearerAuthentication: []
  /master-data/order-matching/imports:
    post:
      operationId: order_matching_imports_create
      description: "Create a new import for the given `lookup_definition_id`. To see the schema that the data should conform to, please refer to the import endpoint parameters for each type of master data. \n\nNote: by default, the given data will be imported immediately. If your data volume exceeds the limits for a single request (see `file`, `file_url` and `data` parameters below), you can create a batched import instead (by setting `batched: true`). Batched imports are created in pending status and will accept additional batches of data, which are appended to the import. After all batches of data have been transferred, batched imports need to be started explicitly. "
      summary: Create a new master data import
      tags:
      - Master Data
      requestBody:
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/OrderMatchingMasterDataImportRequest'
          application/x-www-form-urlencoded:
            schema:
              $ref: '#/components/schemas/OrderMatchingMasterDataImportRequest'
          multipart/form-data:
            schema:
              $ref: '#/components/schemas/OrderMatchingMasterDataImportRequest'
        required: true
      responses:
        '202':
          headers:
            Location:
              schema:
                type: string
              description: URL to get the import status
              required: true
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/AcceptedResponse'
          description: The import run was created successfully. The status of the import can be checked by calling the import details endpoint with the returned import id.
        '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.
      security:
      - BearerAuthentication: []
components:
  schemas:
    AcceptedResponse:
      type: object
      properties:
        import_id:
          type: string
          format: uuid
          description: Id of a master data import run
      required:
      - import_id
    PaginatedDataImportRunList:
      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/DataImportRun'
        total_count:
          type: integer
          example: 123
    DataImportRun:
      type: object
      properties:
        import_id:
          type: string
          format: uuid
        customer_id:
          type: string
          format: uuid
        lookup_type:
          enum:
          - ARTICLE_LOOKUP
          - CLIENT_LOOKUP
          - CONTACT_LOOKUP
          - ADDRESS_LOOKUP
          - CONVERSION_FACTOR_LOOKUP
          - FRAMEWORK_CONTRACT_LOOKUP
          - ORDER_MATCHING_LOOKUP
          - OFFER_MATCHING_LOOKUP
          - CLIENT_MAPPING_LOOKUP
          - CONTACT_MAPPING_LOOKUP
          - ARTICLE_MAPPING_LOOKUP
          - VAT_ID_CHECK_MAPPING_LOOKUP
          - ADDRESS_MAPPING_LOOKUP
          - null
          type: string
          description: '* `ARTICLE_LOOKUP` - ARTICLE_LOOKUP

            * `CLIENT_LOOKUP` - CLIENT_LOOKUP

            * `CONTACT_LOOKUP` - CONTACT_LOOKUP

            * `ADDRESS_LOOKUP` - ADDRESS_LOOKUP

            * `CONVERSION_FACTOR_LOOKUP` - CONVERSION_FACTOR_LOOKUP

            * `FRAMEWORK_CONTRACT_LOOKUP` - FRAMEWORK_CONTRACT_LOOKUP

            * `ORDER_MATCHING_LOOKUP` - ORDER_MATCHING_LOOKUP

            * `OFFER_MATCHING_LOOKUP` - OFFER_MATCHING_LOOKUP

            * `CLIENT_MAPPING_LOOKUP` - CLIENT_MAPPING_LOOKUP

            * `CONTACT_MAPPING_LOOKUP` - CONTACT_MAPPING_LOOKUP

            * `ARTICLE_MAPPING_LOOKUP` - ARTICLE_MAPPING_LOOKUP

            * `VAT_ID_CHECK_MAPPING_LOOKUP` - VAT_ID_CHECK_MAPPING_LOOKUP

            * `ADDRESS_MAPPING_LOOKUP` - ADDRESS_MAPPING_LOOKUP'
          nullable: true
        lookup_definition:
          type: string
          format: uuid
          nullable: true
        ingestion_file_url:
          type: string
          nullable: true
        ingestion_file_num_rows:
          type: integer
          maximum: 2147483647
          minimum: -2147483648
          nullable: true
        error_type:
          type: string
          nullable: true
        error_message:
          type: string
          nullable: true
        trigger:
          type: string
          readOnly: true
          nullable: true
        created_at:
          type: string
          format: date-time
          readOnly: true
        updated_at:
          type: string
          format: date-time
          readOnly: true
        started_at:
          type: string
          format: date-time
          nullable: true
          title: Import started at
        finished_at:
          type: string
          format: date-time
          nullable: true
          title: Import finished at
        status:
          type: string
          readOnly: true
      required:
      - created_at
      - customer_id
      - import_id
      - status
      - trigger
      - updated_at
    ContactMasterDataImportRequest:
      type: object
      properties:
        lookup_definition_id:
          type: string
          format: uuid
          description: ID of a lookup definition (obtainable via Workbench)
        batched:
          type: boolean
          default: false
          description: If `true`, the import will be created in a pending status so that additional batches of data can be appended to the import. If `false` (default), the import will be started immediately.
        file_url:
          type: string
          format: uri
          minLength: 1
          description: If given, the file at the target URL will be downloaded, stored temporarily and imported when the import run is started. Make sure the `file_url` is publicly accessible. The maximum allowed download file size is 300.0 MB.
        file:
          type: string
          format: binary
          description: If given, the file will be temporarily stored and imported when the import run is started. The maximum allowed file size for a single request is 10.0 MB.
        data:
          type: array
          items:
            $ref: '#/components/schemas/ContactMasterData'
      required:
      - lookup_definition_id
    DataRequest:
      type: object
      properties:
        file_url:
          type: string
          format: uri
          minLength: 1
          description: If given, the file at the target URL will be downloaded, stored temporarily and imported when the import run is started. Make sure the `file_url` is publicly accessible. The maximum allowed download file size is 300.0 MB.
        file:
          type: string
          format: binary
          description: If given, the file will be temporarily stored and imported when the import run is started. The maximum allowed file size for a single request is 10.0 MB.
        data:
          type: array
          items:
            type: object
            additionalProperties: {}
            description: List of `Master Data` entities of the lookup's type (see `Schemas` for details)
          description: If given, the data will be converted into a CSV file, temporarily stored and imported when the import run is started. The maximum allowed number of rows for a single request is 10000.
    ConversionFactorMasterDataImportRequest:
      type: object
      properties:
        lookup_definition_id:
          type: string
          form

# --- truncated at 32 KB (52 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/workist/refs/heads/main/openapi/workist-master-data-api-openapi.yml