Manage custom mapping data sources — master-data lists used to match raw extracted values (vendor names, SKUs, categories) to known canonical entities. Upload values via the API and reference the data source from a document type field to enable automatic data matching during parsing.
openapi: 3.0.3
info:
title: Affinda Annotations Add x-hidden to endpoints Data Sources API
version: 3.0.0
description: Affinda Annotations API — 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: []
tags:
- name: Data Sources
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:
parameters:
limitParam:
in: query
name: limit
required: false
schema:
type: integer
minimum: 1
maximum: 100
example: 20
description: The numbers of results to return.
x-ms-parameter-location: method
offsetParam:
in: query
name: offset
required: false
schema:
type: integer
minimum: 0
example: 0
description: The number of documents to skip before starting to collect the result set.
x-ms-parameter-location: method
schemas:
MappingDataSourceCreate:
type: object
description: A mapping data source is used to map from raw data found by our AI models to records in your database.
required:
- identifier
properties:
name:
type: string
example: My supplier list
nullable: true
organization:
type: string
example: mewlkWEKL
description: The organization that this mapping data source belongs to.
nullable: true
workspace:
type: string
example: mewlkWEKL
description: The workspace that this mapping data source belongs to.
nullable: true
keyProperty:
type: string
example: value
description: Attribute in the schema which uniquely identifiers the value
displayProperty:
type: string
example: label
description: Attribute in the schema which is used to display the value
values:
type: array
writeOnly: true
items:
type: object
schema:
type: object
description: The schema of the mapping data source.
example:
type: object
$schema: http://json-schema.org/draft-07/schema#
required:
- label
properties:
label:
type: string
description:
type: string
Organization_properties-identifier:
type: string
description: Uniquely identify an organization.
example: mEFayXdO
MappingDataSource_properties-identifier:
type: string
description: Uniquely identify a mapping data source.
example: mEFayXdO
readOnly: true
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.
MappingDataSource:
type: object
description: A mapping data source is used to map from raw data found by our AI models to records in your database.
required:
- identifier
- organization
- workspace
- keyProperty
- displayProperty
properties:
identifier:
type: string
description: Uniquely identify a mapping data source.
example: mEFayXdO
readOnly: true
name:
type: string
example: My supplier list
nullable: true
keyProperty:
type: string
example: value
description: Attribute in the schema which uniquely identifiers the value
displayProperty:
type: string
example: value
description: Attribute in the schema which is used to display the value
organization:
type: string
example: mewlkWEKL
description: The organization that this mapping data source belongs to.
nullable: true
workspace:
type: string
example: mewlkWEKL
description: The workspace that this mapping data source belongs to.
nullable: true
schema:
type: object
description: The schema of the mapping data source.
example:
type: object
$schema: http://json-schema.org/draft-07/schema#
required:
- label
properties:
label:
type: string
description:
type: string
properties-name:
type: string
example: My supplier list
nullable: true
identifier:
type: string
description: Uniquely identify a workspace.
example: mEFayXdO
responses:
401Error:
description: Authorisation error
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
x-ms-error-response: true
DefaultError:
description: UnexpectedError
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
x-ms-error-response: true
400Error:
description: Bad request. If it is a validation error will contain a list of each invalid field
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
x-ms-error-response: true
204NoContent:
description: Delete successful, no content returned
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).'