openapi: 3.0.3
info:
title: Affinda Organizations API
version: 3.0.0
description: "Affinda Organizations 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/organizations:
get:
tags:
- Organizations
summary: Get list of all organizations
operationId: getAllOrganizations
description: Returns all the organizations
responses:
'200':
description: All organizations you created or joined.
content:
application/json:
schema:
type: array
items:
$ref: '#/components/schemas/Organization'
'400':
$ref: '#/components/responses/400Error'
'401':
$ref: '#/components/responses/401Error'
default:
$ref: '#/components/responses/DefaultError'
/v3/organizations/{identifier}:
get:
tags:
- Organizations
summary: Get detail of an organization
operationId: getOrganization
description: Get detail of an organization.
parameters:
- in: path
required: true
name: identifier
description: Organization identifier.
schema:
$ref: '#/components/schemas/Organization_properties-identifier'
responses:
'200':
description: Successfully retrieved organization.
content:
application/json:
schema:
$ref: '#/components/schemas/Organization'
'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: [email protected]
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: [email protected]
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
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'
DocumentFormat:
type: string
enum:
- json
- xml
- hr-xml
isConfirmed:
type: boolean
isRejected:
type: boolean
isArchived:
type: boolean
skipParse:
type: boolean
DocumentUpdate:
type: object
properties:
collection:
$ref: '#/components/schemas/properties-identifier'
workspace:
$ref: '#/components/schemas/identifier'
documentType:
type: string
description: The document type's identifier. Provide if you already know the document type.
nullable: true
fileName:
$ref: '#/components/schemas/FileName'
expiryTime:
$ref: '#/components/schemas/ExpiryTime'
isConfirmed:
$ref: '#/components/schemas/isConfirmed'
isRejected:
$ref: '#/components/schemas/isRejected'
isArchived:
$ref: '#/components/schemas/isArchived'
skipParse:
$ref: '#/components/schemas/skipParse'
language:
$ref: '#/components/schemas/Language'
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.
llmHint:
type: string
nullable: true
description: Optional hint inserted into the LLM prompt when processing this document.
warningMessages:
type: array
items:
$ref: '#/components/schemas/DocumentWarning'
Organization_properties-identifier:
type: string
description: Uniquely identify an organization.
example: mEFayXdO
OrganizationRole:
type: string
enum:
- admin
- member
example: admin
PaletteColorOptions:
type: object
required:
- main
properties:
main:
type: string
light:
type: string
dark:
type: string
contrastText:
type: string
ThemeConfig:
type: object
properties:
palette:
type: object
properties:
mode:
type: string
enum:
- light
- dark
background:
oneOf:
- type: string
- type: object
properties:
default:
type: string
paper:
type: string
text:
type: object
properties:
primary:
type: string
secondary:
type: string
disabled:
type: string
divider:
type: string
primary:
$ref: '#/components/schemas/PaletteColorOptions'
secondary:
$ref: '#/components/schemas/PaletteColorOptions'
success:
$ref: '#/components/schemas/PaletteColorOptions'
annotation:
$ref: '#/components/schemas/PaletteColorOptions'
error:
$ref: '#/components/schemas/PaletteColorOptions'
info:
$ref: '#/components/schemas/PaletteColorOptions'
warning:
$ref: '#/components/schemas/PaletteColorOptions'
typography:
type: object
properties:
fontFamily:
type: string
fontSize:
oneOf:
- type: string
- type: number
fontWeightRegular:
type: string
fontWeightMedium:
type: string
fontWeightBold:
type: string
borderRadius:
type: number
fontUrl:
type: string
Organization:
type: object
properties:
identifier:
type: string
description: Uniquely identify an organization.
example: mEFayXdO
name:
type: string
example: Grove Street King
userRole:
type: string
allOf:
- $ref: '#/components/schemas/OrganizationRole'
nullable: true
description: The role of the logged in user within the organization.
avatar:
type: string
nullable: true
description: URL of the organization's avatar.
example: https://affinda-api.s3.amazonaws.com/media/org-avatar.png?AWSAccessKeyId=KEY&Signature=SIG
resthookSignatureKey:
type: string
nullable: true
description: Used to sign webhook payloads so you can verify their integrity.
example: 465c6598bd34c0558f0ce256c43209d49fa85b0ff3e4c18b24e408b7563143ad
isTrial:
type: boolean
validationToolConfig:
type: object
nullable: true
description: Configuration of the embeddable validation tool.
properties:
theme:
$ref: '#/components/schemas/ThemeConfig'
hideActions:
type: boolean
description: Hide the confirm document button and other actions.
hideCollection:
type: boolean
description: Hide the collection selector.
hideEditPages:
type: boolean
description: Hide the edit pages button.
hideExport:
type: boolean
description: Hide the export menu.
hideFilename:
type: boolean
description: Hide the filename input.
hideShowRawValues:
type: boolean
description: Hide the toggle for showing raw annotation values.
hideReject:
type: boolean
description: Hide the reject document button.
hideReparse:
type: boolean
description: Hide the reparse button.
hideRunOcr:
type: boolean
description: Hide the run OCR button.
hideTags:
type: boolean
description: Hide the tags editor.
hideWarnings:
type: boolean
description: Hide the warnings panel.
restrictDocumentSplitting:
type: boolean
description: Disable the page editor after a document has been split once.
disableCurrencyFormatting:
type: boolean
description: Disable currency formatting of decimals values.
disableEditDocumentMetadata:
type: boolean
description: Disable editing document metadata. Makes the collection selector, filename input and tags editor
read only.
disableManualAnnotationEditing:
type: boolean
description: Disable manual editing of annotation values via the validation popover.
hideDocumentStatus:
type: boolean
description: Hide the document status indicator in the toolbar.
showCustomFieldCreation:
type: boolean
description: Whether to show the custom field creation in the UI.
WorkspaceVisibility:
type: string
enum:
- organization
- private
description: Visibility "organization" means everyone in the organization can access the workspace. Visi
# --- truncated at 32 KB (203 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/affinda/refs/heads/main/openapi/affinda-organizations-api-openapi.yml