> ## Documentation Index
> Fetch the complete documentation index at: https://docs.affinda.com/llms.txt
> Use this file to discover all available pages before exploring further.
## Submitting Feedback
If you encounter incorrect, outdated, or confusing documentation on this page, submit feedback:
POST https://docs.affinda.com/feedback
```json
{
"path": "/api-reference/documents/upload-a-document-for-parsing",
"feedback": "Description of the issue"
}
```
Only submit feedback when you have something specific and actionable to report.
# Upload a document for parsing
>
Uploads a document for parsing via file upload or URL.
When successful, returns an `identifier` in the response for subsequent use with the [/documents/{identifier}](#get-/v3/documents/-identifier-) endpoint to check processing status and retrieve results.
## OpenAPI
````yaml https://api.affinda.com/static/v3/api_spec.yaml post /v3/documents
openapi: 3.0.3
info:
description: >-
# Introduction
Affinda uses the latest advancements in AI technology to rapidly process
documents with better-than-human accuracy.
This guide covers how to:
* Extract structured data from a range of document types
* Integrate our solutions into your platform
* Manage users
*Note: This API spec is for v3 of the API, the deprecated v2 documentation
[can be found here](https://api.affinda.com/docs/v2)*
> **Important: Use the correct API URL for your region.** Affinda is hosted
across multiple instances. Make sure you are sending requests to the correct
URL for your account:
> | Instance | API Base URL |
> |----------|-------------|
> | **AUS / Global** | `https://api.affinda.com` |
> | **US** | `https://api.us1.affinda.com` |
> | **EU** | `https://api.eu1.affinda.com` |
>
> You can determine your instance from the URL you use to access the Affinda
web app (e.g. `app.us1.affinda.com` means you are on the US instance). When
using the "Try it" feature, select the matching region from the server
dropdown.
# Getting Started
* Obtain an API key by [signing up for a
free-trial](https://app.affinda.com/auth/register)
* (Recommended) Download and install one of our client libraries: *
[Python](https://github.com/affinda/affinda-python) : `pip install affinda`
* [Javascript](https://github.com/affinda/affinda-typescript) : `npm install
@affinda/affinda` * [.NET](https://github.com/affinda/affinda-dotnet):
`dotnet add package Affinda.API` *
[Java](https://github.com/affinda/affinda-java) - [maven
repository](https://mvnrepository.com/artifact/com.affinda.api/affinda-api-client)
* Without a client library, API requests via HTTP according to the API spec
in this documentation
version: v3
title: Affinda API
contact:
email: contact@affinda.com
license:
name: MIT
url: https://raw.githubusercontent.com/affinda/affinda-api-spec/master/LICENSE
x-logo:
url: https://api.affinda.com/static/documentation/affinda_logo.png
backgroundColor: '#FFFFFF'
altText: Affinda logo
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: Documents
description: >
Operations to upload documents for parsing.
A document can be uploaded using `file` or `url`, one of these parameters
must be provided.
A document can be uploaded to a `workspace` or a `collection`, one of
these parameters must also be provided.
When uploaded to a workspace, the document's specific type will be
predicted and auto classified into one of the collections before being
parsed.
When uploaded to a collection, the document will be parsed using that
collection's extractor.
- name: Organizations
description: |
Operations to manage organizations and organization memberships.
Organizations are the top-level entity for managing users and workspaces.
- name: Workspaces
description: |
Operations to manage workspaces.
Workspaces group together related collections of documents.
- name: Document Types
description: >
Operations to manage document types.
Document types represent specific categories of documents with common
extraction patterns, such as invoices or resumes.
- name: Data Sources
description: >
Operations to manage custom mapping data sources. These are used to map
from raw data extracted by
Affinda AI models onto your own data model.
- name: Validation Results
description: >
Operations to manage validation results.
Validation results track the status and outcomes of document validation
processes.
- name: Usage
description: >
Operations to retrieve credits consumption.
Returns daily credits usage for an organization, optionally narrowed to a
single
workspace or document type.
- name: Tags
description: >
Operations to manage tags.
Tags can be arbitrarily attached to documents to help organize and manage
them.
- name: Annotations
description: >
Operations to manually create, update, delete annotations.
Together with the data point endpoints, these helps to annotate your
documents with arbitrary data,
or to edit annotations that were created by the Affinda parser.
- name: Webhooks
description: >
Manage webhook integrations with your apps.
Affinda have implemented webhooks to allow the data extracted by Affinda
to be 'pushed' to you when an event occurs
(e.g. document parsed or document validated), instead of you having to
constantly poll our API to 'pull' the data to your system.
- name: Search & Match
description: >
Operations to search through an index of documents and manage indexes via
the Affinda Resume Parser API or a client library.
Resumes and job descriptions must be explicitly added to an index, which
then makes them searchable.
- name: Deprecated End Points
description: >
Deprecated endpoints that are maintained for backward compatibility.
These endpoints include Data Point, Collection, and Users functionality
that has been superseded by newer APIs.
- name: Add x-hidden to endpoints
description: >
Hidden endpoints not intended for public use.
These endpoints include Splitting, Extractor, Organization, and Workspace
Memberships & Usage functionality.
paths:
/v3/documents:
post:
tags:
- Documents
summary: Upload a document for parsing
description: >-
Uploads a document for parsing via file upload or URL.
When successful, returns an `identifier` in the response for subsequent
use with the [/documents/{identifier}](#get-/v3/documents/-identifier-)
endpoint to check processing status and retrieve results.
operationId: createDocument
parameters:
- in: query
name: snake_case
required: false
description: >-
Whether to return the response in snake_case instead of camelCase.
Default is false.
schema:
type: boolean
requestBody:
description: Document to upload, either via file upload or URL to a file
required: true
content:
multipart/form-data:
schema:
$ref: '#/components/schemas/DocumentCreate'
responses:
'200':
description: Only returned when wait=True, will return the created document
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
'201':
description: >-
Only returned when wait=False, will return document uploaded and
identifier created
x-summary: >-
Document uploaded and created, use document.meta.identifier to poll
for processing status
content:
application/json:
schema:
$ref: '#/components/schemas/Document'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
'403':
$ref: '#/components/responses/403Error'
default:
$ref: '#/components/responses/DefaultError'
components:
schemas:
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
description: Deprecated in favor of `customIdentifier`.
deprecated: true
customIdentifier:
type: string
description: >-
Specify a custom identifier for the document if you need one, not
required to be unique.
fileName:
$ref: '#/components/schemas/FileName'
expiryTime:
$ref: '#/components/schemas/ExpiryTime'
language:
$ref: '#/components/schemas/Language'
rejectDuplicates:
$ref: '#/components/schemas/RejectDuplicatesMaybeString'
regionBias:
type: string
description: A JSON representation of the RegionBias object.
example: '{"country": "vn"}'
lowPriority:
type: boolean
description: Explicitly mark this document as low priority.
example: true
compact:
type: boolean
description: >-
If true, the returned parse result (assuming `wait` is also true)
will be a compact version of the full result.
example: true
deleteAfterParse:
type: boolean
description: >-
If true, no data will be stored after parsing. Only compatible with
requests where wait: True.
example: true
enableValidationTool:
type: boolean
description: >-
If true, the document will be viewable in the Affinda Validation
Tool. Set to False to optimize parsing speed.
example: true
useOcr:
type: boolean
nullable: true
description: >-
If true, the document will be treated like an image, and the text
will be extracted using OCR. If false, the document will be treated
like a PDF, and the text will be extracted using the parser. If not
set, we will determine whether to use OCR based on whether words are
found in the document.
llmHint:
type: string
nullable: true
description: >-
Optional hint inserted into the LLM prompt when processing this
document.
limitToExamples:
type: array
nullable: true
description: >-
Restrict LLM example selection to the specified document
identifiers.
items:
type: string
warningMessages:
type: array
items:
$ref: '#/components/schemas/DocumentWarning'
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
properties-identifier:
type: string
description: Uniquely identify a collection.
example: mEFayXdO
identifier:
type: string
description: Uniquely identify a workspace.
example: mEFayXdO
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
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.
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
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.
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
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
DocumentMeta_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
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
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
Identifier:
type: string
description: A random string that uniquely identify the resource.
responses:
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
401Error:
description: Authorisation error
content:
application/json:
schema:
$ref: '#/components/schemas/RequestError'
x-ms-error-response: true
403Error:
description: Forbidden 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
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).
````