Affinda Data Sources API

openapi: 3.0.3
info:
  title: Affinda Data Sources API
  version: 3.0.0
  description: "Affinda Data Sources API \u2014 subset of the Affinda v3 Document Processing API."
servers:
- url: https://{region}.affinda.com
  description: 'Select the correct server for your instance: api (AUS/Global), api.us1 (US), or api.eu1 (EU).'
  variables:
    region:
      default: api
      description: The instance region. Use 'api' for AUS/Global, 'api.us1' for US, or 'api.eu1' for EU. You can find your
        region in the Affinda web app URL.
      enum:
      - api
      - api.eu1
      - api.us1
      x-ms-parameter-location: client
security:
- ApiKeyAuth: []
paths:
  /v3/mapping_data_sources:
    post:
      tags:
      - Data Sources
      summary: Create a data source
      operationId: createMappingDataSource
      description: Create a custom mapping data source.
      responses:
        '201':
          description: Successfully created a mapping data source.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MappingDataSource'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/MappingDataSourceCreate'
    get:
      tags:
      - Data Sources
      summary: List data sources
      operationId: listMappingDataSources
      parameters:
      - $ref: '#/components/parameters/offsetParam'
      - $ref: '#/components/parameters/limitParam'
      - in: query
        name: name
        required: false
        schema:
          $ref: '#/components/schemas/properties-name'
        description: Filter by name.
      - in: query
        name: organization
        required: false
        schema:
          $ref: '#/components/schemas/Organization_properties-identifier'
        description: Filter by organization.
      - in: query
        name: workspace
        required: false
        schema:
          $ref: '#/components/schemas/identifier'
        description: Filter by workspace.
      - in: query
        name: identifier
        required: false
        schema:
          $ref: '#/components/schemas/MappingDataSource_properties-identifier'
        description: Filter by identifier.
      description: Returns the list of all custom mapping data sources.
      responses:
        '200':
          description: Will return matching data sources
          x-summary: Will return matching data sources
          content:
            application/json:
              schema:
                type: object
                required:
                - results
                - count
                allOf:
                - $ref: '#/components/schemas/PaginatedResponse'
                - type: object
                  properties:
                    results:
                      type: array
                      items:
                        $ref: '#/components/schemas/MappingDataSource'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
  /v3/mapping_data_sources/{identifier}:
    get:
      tags:
      - Data Sources
      summary: Get specific data source
      operationId: getMappingDataSource
      description: Return a specific mapping data source.
      parameters:
      - in: path
        required: true
        name: identifier
        description: Data source's identifier
        schema:
          $ref: '#/components/schemas/MappingDataSource_properties-identifier'
      responses:
        '200':
          description: Successfully retrieved mapping data source value.
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/MappingDataSource'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
    delete:
      tags:
      - Data Sources
      summary: Delete specific data source
      operationId: deleteMappingDataSource
      description: Delete the specified mapping data source from the database.
      parameters:
      - in: path
        required: true
        name: identifier
        description: Data source's identifier
        schema:
          $ref: '#/components/schemas/MappingDataSource_properties-identifier'
      responses:
        '204':
          $ref: '#/components/responses/204NoContent'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
  /v3/mapping_data_sources/{identifier}/values:
    get:
      tags:
      - Data Sources
      summary: List values for a data source
      operationId: listMappingDataSourceValues
      description: Returns the list of all values in a mapping data source
      parameters:
      - $ref: '#/components/parameters/limitParam'
      - $ref: '#/components/parameters/offsetParam'
      - in: query
        name: search
        required: false
        schema:
          type: string
          example: Supplier XYZ
        description: Search for specific values
      - in: query
        name: annotation
        required: false
        schema:
          type: integer
          example: 124
        description: Filter based on annotation ID
      - in: query
        name: document
        required: false
        schema:
          type: string
          example: stXkrhIY
        description: Identifier of the document to apply filter lookups on if available
      - in: path
        required: true
        name: identifier
        description: Data source's identifier
        schema:
          $ref: '#/components/schemas/MappingDataSource_properties-identifier'
      responses:
        '200':
          description: Will return matching data source values
          x-summary: Will return matching data source values
          content:
            application/json:
              schema:
                type: object
                required:
                - results
                - count
                allOf:
                - $ref: '#/components/schemas/PaginatedResponse'
                - type: object
                  properties:
                    results:
                      type: array
                      items:
                        type: object
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
    put:
      tags:
      - Data Sources
      summary: Replace values for a data source
      operationId: replaceMappingDataSourceValues
      description: 'Replaces the list of all values in a mapping data source

        Note: For large data sources (e.g. > 1000 values), it can take a few minutes after the request completes for the new
        values to be searchable.'
      parameters:
      - in: path
        required: true
        name: identifier
        description: Data source's identifier
        schema:
          $ref: '#/components/schemas/MappingDataSource_properties-identifier'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: array
              items:
                type: object
      responses:
        '201':
          description: Will return matching data source values
          content:
            application/json:
              schema:
                type: array
                items:
                  type: object
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
    post:
      tags:
      - Data Sources
      summary: Add value for a data source
      operationId: addMappingDataSourceValue
      description: Adds a value to a mapping data source
      parameters:
      - in: path
        required: true
        name: identifier
        description: Data source's identifier
        schema:
          $ref: '#/components/schemas/MappingDataSource_properties-identifier'
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '201':
          description: Will return the created mapping data source value
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
  /v3/mapping_data_sources/{identifier}/values/{value}:
    get:
      tags:
      - Data Sources
      summary: Get specific data source value
      operationId: getMappingDataSourceValue
      description: Return a specific mapping dta source value.
      parameters:
      - in: path
        required: true
        name: identifier
        description: Data source's identifier
        schema:
          $ref: '#/components/schemas/MappingDataSource_properties-identifier'
      - in: path
        required: true
        name: value
        description: Data Source Value's value
        schema:
          type: string
      responses:
        '200':
          description: Successfully retrieved mapping data source value.
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
    put:
      tags:
      - Data Sources
      summary: Update specific data source value
      operationId: updateMappingDataSourceValue
      description: Update the specified mapping data source value.
      parameters:
      - in: path
        required: true
        name: identifier
        description: Data source's identifier
        schema:
          $ref: '#/components/schemas/MappingDataSource_properties-identifier'
      - in: path
        required: true
        name: value
        description: Data Source's value
        schema:
          type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              type: object
      responses:
        '200':
          description: Successfully updated mapping data source value.
          content:
            application/json:
              schema:
                type: object
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
    delete:
      tags:
      - Data Sources
      summary: Delete specific data source value
      operationId: deleteMappingDataSourceValue
      description: Delete the specified mapping data source value from the database.
      parameters:
      - in: path
        required: true
        name: identifier
        description: Data source's identifier
        schema:
          $ref: '#/components/schemas/MappingDataSource_properties-identifier'
      - in: path
        required: true
        name: value
        description: Data Source Value's value
        schema:
          type: string
      responses:
        '204':
          $ref: '#/components/responses/204NoContent'
        '400':
          $ref: '#/components/responses/400Error'
        '401':
          $ref: '#/components/responses/401Error'
        default:
          $ref: '#/components/responses/DefaultError'
components:
  securitySchemes:
    ApiKeyAuth:
      type: http
      scheme: bearer
      description: 'Basic authentication using an API key, e.g. `{Authorization: Bearer aff_0bb4fbdf97b7e4111ff6c0015471094155f91}`.

        You can find your API key within the Settings page of the [Affinda web app](https://app.affinda.com/). You can obtain
        an API key by [signing up for a free trial](https://app.affinda.com/auth/register).'
  schemas:
    Resume:
      allOf:
      - $ref: '#/components/schemas/Document'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/ResumeData'
      x-ms-discriminator-value: resume
    Invoice:
      allOf:
      - $ref: '#/components/schemas/Document'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/InvoiceData'
      x-ms-discriminator-value: invoice
    JobDescription:
      allOf:
      - $ref: '#/components/schemas/Document'
      - type: object
        properties:
          data:
            $ref: '#/components/schemas/JobDescriptionData'
      x-ms-discriminator-value: job-description
    ResumeRedact:
      allOf:
      - $ref: '#/components/schemas/Document'
      - type: object
        properties:
          data:
            type: object
            properties:
              redactedPdf:
                type: string
                description: URL to download the redacted resume.
      x-ms-discriminator-value: resume-redact
    DateRangeAnnotation:
      type: object
      nullable: true
      allOf:
      - $ref: '#/components/schemas/Annotation'
      - type: object
        properties:
          parsed:
            type: object
            properties:
              start:
                $ref: '#/components/schemas/DateRangeValue'
              end:
                $ref: '#/components/schemas/DateRangeValue'
    PhoneNumberAnnotation:
      type: object
      nullable: true
      allOf:
      - $ref: '#/components/schemas/Annotation'
      - type: object
        properties:
          parsed:
            type: object
            properties:
              rawText:
                type: string
                nullable: false
                example: '+61412632636'
                deprecated: true
              formattedNumber:
                type: string
                nullable: true
                example: +61 412 632 636
              countryCode:
                type: string
                nullable: true
                example: AU
              internationalCountryCode:
                type: integer
                nullable: true
                example: 61
                minimum: 1
              nationalNumber:
                type: string
                nullable: true
                example: 0412 632 636
    UrlAnnotation:
      type: object
      nullable: true
      allOf:
      - $ref: '#/components/schemas/Annotation'
      - type: object
        properties:
          parsed:
            type: object
            properties:
              url:
                type: string
                nullable: true
                example: https://2nb9s.com/hello/world?foo=bar#baz
              domain:
                type: string
                nullable: true
                example: 2nb9s.com
    identifier:
      type: string
      description: Uniquely identify a workspace.
      example: mEFayXdO
    properties-identifier:
      type: string
      description: Uniquely identify a collection.
      example: mEFayXdO
    DocumentState:
      type: string
      enum:
      - uploaded
      - review
      - validated
      - archived
      - rejected
    id:
      type: integer
      description: Uniquely identify a tag.
      example: 1
      minimum: 1
    DateRange:
      type: string
      enum:
      - today
      - yesterday
      - week
      - month
      - year
    DocumentMeta_properties-identifier:
      type: string
      description: Unique identifier for the document
    RequestError:
      type: object
      additionalProperties: false
      required:
      - type
      - errors
      properties:
        type:
          type: string
          example: validation_error
        errors:
          type: array
          items:
            type: object
            required:
            - attr
            - code
            - detail
            properties:
              attr:
                type: string
                nullable: true
                example: non_field_errors
              code:
                type: string
                example: unique
              detail:
                type: string
                example: This index name has already been used
    PaginatedResponse:
      type: object
      required:
      - count
      properties:
        count:
          type: integer
          example: 10
          description: Number of items in results.
          minimum: 0
        next:
          type: string
          nullable: true
          description: URL to request next page of results.
        previous:
          type: string
          nullable: true
          description: URL to request previous page of results.
    FileName:
      type: string
      nullable: true
      description: Optional filename of the file
      example: Document.pdf
    ExpiryTime:
      type: string
      nullable: true
      format: date-time
      description: The date/time in ISO-8601 format when the document will be automatically deleted.  Defaults to no expiry.
    customIdentifier:
      type: string
      nullable: true
      description: Optional identifier for the document that you can set to track the document in the Affinda system.  Is
        not required to be unique.
      example: 46ab8b02-0e5b-420c-877c-8b678d46a834
    PageMeta:
      type: object
      required:
      - id
      - pageIndex
      - image
      - width
      - height
      - rotation
      properties:
        id:
          type: integer
          minimum: 1
        pageIndex:
          type: integer
          example: 0
          minimum: 0
          description: Page number within the document, starts from 0.
        image:
          type: string
          nullable: true
          example: https://affinda-api.s3.amazonaws.com/media/pages/Page.png?AWSAccessKeyId=KEY&Signature=SIG&Expires=1663302062
          description: The URL to the image of the page.
        imageTranslated:
          type: string
          nullable: true
          example: https://affinda-api.s3.amazonaws.com/media/pages/PageTranslated.png?AWSAccessKeyId=KEY&Signature=SIG&Expires=1663302062
          description: The URL to the translated image of the page.
        height:
          type: number
          example: 700
          description: Height of the page's image in px.
        width:
          type: number
          example: 500
          description: Width of the page's image in px.
        rotation:
          type: integer
          example: 90
          minimum: -360
          maximum: 360
          description: The degree of rotation applied to the page. Greater than 0 indicates clockwise rotation. Less than
            0 indicates counter-clockwise rotation.
    name:
      type: string
    Extractor_properties-identifier:
      type: string
      description: Uniquely identify an extractor.
      example: resume
    validatable:
      type: boolean
    Identifier:
      type: string
      description: A random string that uniquely identify the resource.
    ValidationRule:
      type: object
      additionalProperties: false
      nullable: false
      description: A validation rule for a collection
      required:
      - slug
      - dataPoints
      properties:
        slug:
          type: string
          description: The slug of the validation rule, in lowercase snake_case
          pattern: ^[a-z0-9_]+$
          example: supplier_name_is_alphanumeric
        dataPoints:
          type: array
          description: The data point identifier that this validation rule applies to, can be an empty list if the rule doens't
            use any data points as sources
          items:
            $ref: '#/components/schemas/Identifier'
    UserNullable:
      type: object
      nullable: true
      properties:
        id:
          type: integer
          description: Uniquely identify a user.
          example: 1
          minimum: 1
        name:
          type: string
          example: Carl Johnson
        username:
          type: string
          example: carljohnson
        email:
          type: string
          example: carljohnson@grove.street
        avatar:
          type: string
          nullable: true
          description: URL of the user's avatar.
          example: https://affinda-api.s3.amazonaws.com/media/user-avatar.png?AWSAccessKeyId=KEY&Signature=SIG
    errorCode:
      type: string
      nullable: true
      example: document_conversion_failed
    errorDetail:
      type: string
      nullable: true
      example: Unable to convert word document
    Tag:
      type: object
      required:
      - id
      - name
      - workspace
      - documentCount
      properties:
        id:
          type: integer
          description: Uniquely identify a tag.
          example: 1
          minimum: 1
        name:
          type: string
        workspace:
          $ref: '#/components/schemas/identifier'
        documentCount:
          type: integer
          minimum: 0
          description: Number of documents tagged with this.
    User:
      type: object
      properties:
        id:
          type: integer
          description: Uniquely identify a user.
          example: 1
          minimum: 1
        name:
          type: string
          example: Carl Johnson
        username:
          type: string
          example: carljohnson
        email:
          type: string
          example: carljohnson@grove.street
        avatar:
          type: string
          nullable: true
          description: URL of the user's avatar.
          example: https://affinda-api.s3.amazonaws.com/media/user-avatar.png?AWSAccessKeyId=KEY&Signature=SIG
    RegionBias:
      type: object
      nullable: true
      properties:
        country:
          type: string
          nullable: true
          description: A single alpha-2 country code (e.g. AU) used by google geocoding service
        countries:
          type: array
          items:
            type: string
          nullable: true
          description: A list of alpha-2 country codes used by Pelias
        squareCoordinates:
          type: array
          items:
            type: number
          nullable: true
          description: A list of coordinates used by Pelias in the shape of [min_lon, min_lat, max_lon, max_lat]
        strict:
          type: boolean
          description: 'If true, the location must be within the region, as opposed to prefering locations within the region.

            Default to false.

            '
          example: true
    DocumentMeta:
      type: object
      required:
      - identifier
      - pages
      - workspace
      properties:
        identifier:
          type: string
          description: Unique identifier for the document
        customIdentifier:
          type: string
          nullable: true
          description: Optional identifier for the document that you can set to track the document in the Affinda system.  Is
            not required to be unique.
          example: 46ab8b02-0e5b-420c-877c-8b678d46a834
        fileName:
          $ref: '#/components/schemas/FileName'
        ready:
          type: boolean
          nullable: false
          example: true
          description: If true, the document has finished processing. Particularly useful if an endpoint request specified
            wait=False, when polling use this variable to determine when to stop polling
        readyDt:
          type: string
          format: date-time
          example: '2020-12-10T01:43:32.276724Z'
          nullable: true
          description: The datetime when the document was ready
        failed:
          type: boolean
          nullable: false
          example: false
          description: If true, some exception was raised during processing. Check the 'error' field of the main return object.
        expiryTime:
          $ref: '#/components/schemas/ExpiryTime'
        language:
          type: string
          nullable: true
          example: en
          description: The document's language.
        pdf:
          type: string
          nullable: true
          example: https://affinda-api.s3.amazonaws.com/media/documents/Document.pdf?AWSAccessKeyId=KEY&Signature=SIG&Expires=1663302062
          description: The URL to the document's pdf (if the uploaded document is not already pdf, it's converted to pdf as
            part of the parsing process).
        parentDocument:
          type: object
          nullable: true
          description: If this document is part of a splitted document, this attribute points to the original document that
            this document is splitted from.
          properties:
            identifier:
              $ref: '#/components/schemas/DocumentMeta_properties-identifier'
            customIdentifier:
              $ref: '#/components/schemas/customIdentifier'
        childDocuments:
          type: array
          description: If this document has been splitted into a number of child documents, this attribute points to those
            child documents.
          items:
            type: object
            properties:
              identifier:
                $ref: '#/components/schemas/DocumentMeta_properties-identifier'
              customIdentifier:
                $ref: '#/components/schemas/customIdentifier'
        pages:
          type: array
          items:
            $ref: '#/components/schemas/PageMeta'
          description: The document's pages.
        isOcrd:
          type: boolean
        ocrConfidence:
          type: number
          nullable: true
        reviewUrl:
          type: string
          nullable: true
        documentType:
          type: string
          description: The document type's identifier.  Provide if you already know the document type.
          nullable: true
        collection:
          type: object
          nullable: true
          required:
          - identifier
          properties:
            identifier:
              $ref: '#/components/schemas/properties-identifier'
            name:
              $ref: '#/components/schemas/name'
            extractor:
              type: object
              nullable: true
              properties:
                identifier:
                  $ref: '#/components/schemas/Extractor_properties-identifier'
                name:
                  $ref: '#/components/schemas/name'
                baseExtractor:
                  type: string
                  description: Base extractor's identifier.
                  nullable: true
                validatable:
                  $ref: '#/components/schemas/validatable'
            validationRules:
              type: array
              items:
                $ref: '#/components/schemas/ValidationRule'
            autoRefreshValidationResults:
              type: boolean
              description: If True, validation results are refreshed whenever annotations are changed.
        workspace:
          type: object
          required:
          - identifier
          properties:
            identifier:
              $ref: '#/components/schemas/identifier'
            name:
              $ref: '#/components/schemas/name'
        archivedDt:
          type: string
          format: date-time
          nullable: true
        isArchived:
          type: boolean
        skipParse:
          type: boolean
        confirmedDt:
          type: string
          format: date-time
          nullable: true
        confirmedBy:
          $ref: '#/components/schemas/UserNullable'
        isConfirmed:
          type: boolean
        rejectedDt:
          type: string
          format: date-time
          nullable: true
        rejectedBy:
          $ref: '#/components/schemas/UserNullable'
        archivedBy:
          $ref: '#/components/schemas/UserNullable'
        isRejected:
          type: boolean
        createdDt:
          type: string
          format: date-time
        errorCode:
          $ref: '#/components/schemas/errorCode'
        errorDetail:
          $ref: '#/components/schemas/errorDetail'
        file:
          type: string
          nullable: true
          description: URL to view the file.
        html:
          type: string
          nullable: true
          description: URL to view the file converted to HTML.
        llmHint:
          type: string
          nullable: true
          description: Optional hint inserted into the LLM prompt when processing this document.
        tags:
          type: array
          items:
            $ref: '#/components/schemas/Tag'
        createdBy:
          $ref: '#/components/schemas/User'
        sourceEmail:
          type: string
          nullable: true
          description: If the document is created via email ingestion, this field stores the email file's URL.
        sourceEmailAddress:
          type: string
          nullable: true
          description: If the document is created via email ingestion, this field stores the email's From address.
        regionBias:
          $ref: '#/components/schemas/RegionBias'
    DocumentError:
      type: object
      additionalProperties: false
      properties:
        errorCode:
          type: string
          nullable: true
          example: document_conversion_failed
        errorDetail:
          type: string
          nullable: true
          example: Unable to convert word document
    DocumentWarning:
      type: object
      additionalProperties: false
      properties:
        warningCode:
          type: string
          nullable: true
          example: too_many_pages
        warningDetail:
          type: string
          nullable: true
          example: File exceeds maximum number of pages allowed, parsing the first 10 pages only.
    Document:
      type: object
      required:
      - meta
      - extractor
      properties:
        data:
          type: object
        extractor:
          type: string
        meta:
          $ref: '#/components/schemas/DocumentMeta'
        error:
          $ref: '#/components/schemas/DocumentError'
        warnings:
          type: array
          items:
            $ref: '#/components/schemas/DocumentWarning'
      discriminator:
        propertyName: extractor
      x-csharp-usage: input,output
    File:
      type: string
      format: binary
      description: 'File as binary data blob. Supported formats: PDF, DOC, DOCX, TXT, RTF, HTML, PNG, JPG, TIFF, ODT, XLS,
        XLSX'
    Wait:
      type: boolean
      description: If "true" (default), will return a response only after processing has completed. If "false", will return
        an empty data object which can be polled at the GET endpoint until processing is complete.
      example: true
      default: true
      nullable: false
    Language:
      type: string
      nullable: true
      description: Language code in ISO 639-1 format. Must specify zh-cn or zh-tw for Chinese.
      example: en
    RejectDuplicatesMaybeString:
      type: boolean
      description: If "true", parsing will fail when the uploaded document is duplicate of an existing document, no credits
        will be consumed. If "false", will parse the document normally whether its a duplicate or not. If not provided, will
        fallback to the workspace settings.
      example: true
      nullable: true
    DocumentCreate:
      type: object
      properties:
        file:
          $ref: '#/components/schemas/File'
        url:
          type: string
          nullable: true
          description: URL to download the document.
          example: https://api.affinda.com/static/sample_resumes/example.docx
        collection:
          $ref: '#/components/schemas/properties-identifier'
        documentType:
          type: string
          description: The document type's identifier.  Provide if you already know the document type.
          nullable: true
        workspace:
          $ref: '#/components/schemas/identifier'
        wait:
          $ref: '#/components/schemas/Wait'
        identifier:
          type: string
          descrip

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