> ## 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/deprecated-end-points/create-a-collection", "feedback": "Description of the issue" } ``` Only submit feedback when you have something specific and actionable to report. # Create a collection > Create a collection ## OpenAPI ````yaml https://api.affinda.com/static/v3/api_spec.yaml post /v3/collections 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/collections: post: tags: - Deprecated End Points summary: Create a collection description: Create a collection operationId: createCollection requestBody: required: true content: application/json: schema: $ref: '#/components/schemas/CollectionCreate' responses: '201': description: Successfully created a collection. content: application/json: schema: $ref: '#/components/schemas/Collection' '400': $ref: '#/components/responses/400Error' '401': $ref: '#/components/responses/401Error' default: $ref: '#/components/responses/DefaultError' deprecated: true components: schemas: CollectionCreate: type: object required: - name - workspace properties: name: $ref: '#/components/schemas/name' workspace: $ref: '#/components/schemas/identifier' extractor: type: string description: >- Uniquely identify an extractor. Required if you are not a super user. example: resume baseExtractor: type: string description: >- Not applicable, please leave empty. This feature is reserved for super user. autoValidationThreshold: $ref: '#/components/schemas/autoValidationThreshold' enableAutoValidationThreshold: $ref: '#/components/schemas/enableAutoValidationThreshold' fields: $ref: '#/components/schemas/fields' fieldsLayout: $ref: '#/components/schemas/FieldsLayout' dateFormatPreference: $ref: '#/components/schemas/dateFormatPreference' dateFormatFromDocument: $ref: '#/components/schemas/dateFormatFromDocument' extractorConfig: $ref: '#/components/schemas/ExtractorConfig' allowOpenai: $ref: '#/components/schemas/allowOpenai' trainsExtractor: $ref: '#/components/schemas/trainsExtractor' disableConfirmationIfValidationRulesFail: $ref: '#/components/schemas/disableConfirmationIfValidationRulesFail' Collection: type: object required: - identifier properties: identifier: type: string description: Uniquely identify a collection. example: mEFayXdO name: type: string workspace: type: object properties: identifier: $ref: '#/components/schemas/identifier' organization: $ref: '#/components/schemas/Organization' name: $ref: '#/components/schemas/name' extractor: $ref: '#/components/schemas/Extractor' nullable: true autoValidationThreshold: type: number enableAutoValidationThreshold: type: boolean default: false autoValidateIfValidationRulesPass: type: boolean default: false fields: type: array nullable: true items: $ref: '#/components/schemas/FieldGroup' deprecated: true fieldsLayout: $ref: '#/components/schemas/FieldsLayout' fieldsConfigured: type: boolean dateFormatPreference: type: string enum: - DMY - MDY - YMD nullable: true dateFormatFromDocument: type: boolean nullable: true description: >- Predict the date format from any dates in the document that is not ambiguous. extractorConfig: $ref: '#/components/schemas/ExtractorConfig' unvalidatedDocsCount: type: integer nullable: true minimum: 0 description: Number of unvalidated documents in the collection. confirmedDocsCount: type: integer nullable: true minimum: 0 description: Number of validated documents in the collection. ingestEmail: type: string description: >- When you send email to this address, any document attached in the body will be uploaded to this collection. tailoredExtractorRequested: type: boolean description: Whether a tailored extractor has been requested for this collection. allowOpenai: type: boolean default: false description: >- Whether to allow OpenAI API to be used to assist in creating a model for this collection. trainsExtractor: type: boolean description: >- Whether this collection feeds documents into the extractor's training queue. This setting can only be toggled for custom extractors. disableConfirmationIfValidationRulesFail: type: boolean default: false description: >- If True, users cannot validate documents with missing mandatory fields, or failing validation rules. autoRefreshValidationResults: type: boolean default: true description: >- If True, validation results are refreshed whenever annotations are changed. name: type: string identifier: type: string description: Uniquely identify a workspace. example: mEFayXdO autoValidationThreshold: type: number enableAutoValidationThreshold: type: boolean default: false fields: type: array nullable: true items: $ref: '#/components/schemas/FieldGroup' deprecated: true FieldsLayout: type: object properties: defaultCategory: $ref: '#/components/schemas/FieldCategory' categories: type: array items: $ref: '#/components/schemas/FieldCategory' required: - defaultCategory - categories additionalProperties: false dateFormatPreference: type: string enum: - DMY - MDY - YMD nullable: true dateFormatFromDocument: type: boolean nullable: true description: >- Predict the date format from any dates in the document that is not ambiguous. ExtractorConfig: type: object nullable: true description: Extra configurations specific to an extractor. properties: resumeRedact: $ref: '#/components/schemas/RedactConfig' allowOpenai: type: boolean default: false description: >- Whether to allow OpenAI API to be used to assist in creating a model for this collection. trainsExtractor: type: boolean description: >- Whether this collection feeds documents into the extractor's training queue. This setting can only be toggled for custom extractors. disableConfirmationIfValidationRulesFail: type: boolean default: false description: >- If True, users cannot validate documents with missing mandatory fields, or failing validation rules. 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. Extractor: type: object required: - identifier - name - namePlural - validatable properties: identifier: type: string description: Uniquely identify an extractor. example: resume name: type: string namePlural: type: string baseExtractor: type: object nullable: true required: - identifier - name - namePlural - validatable properties: identifier: $ref: '#/components/schemas/Extractor_properties-identifier' name: $ref: '#/components/schemas/name' namePlural: $ref: '#/components/schemas/namePlural' validatable: $ref: '#/components/schemas/validatable' isCustom: $ref: '#/components/schemas/isCustom' createdDt: $ref: '#/components/schemas/createdDt' organization: $ref: '#/components/schemas/Organization' nullable: true category: type: string nullable: true example: Recruitment validatable: type: boolean isCustom: type: boolean fieldGroups: type: array nullable: true items: $ref: '#/components/schemas/FieldGroup' createdDt: type: string format: date-time lastTrainedDt: type: string format: date-time nullable: true FieldGroup: type: object properties: label: type: string fields: type: array items: $ref: '#/components/schemas/FieldDeprecated' required: - label - fields additionalProperties: false 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 FieldCategory: type: object properties: label: type: string enabledFields: type: array items: $ref: '#/components/schemas/Field' disabledFields: type: array items: $ref: '#/components/schemas/Field' required: - label - enabledFields - disabledFields additionalProperties: false RedactConfig: type: object properties: redactHeadshot: type: boolean example: true redactPersonalDetails: type: boolean example: true redactWorkDetails: type: boolean example: true redactReferees: type: boolean example: true redactEducationDetails: type: boolean example: true redactLocations: type: boolean example: true redactDates: type: boolean example: true redactGender: type: boolean example: true OrganizationRole: type: string enum: - admin - member example: admin 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 Extractor_properties-identifier: type: string description: Uniquely identify an extractor. example: resume namePlural: type: string validatable: type: boolean isCustom: type: boolean createdDt: type: string format: date-time FieldDeprecated: type: object properties: label: type: string slug: type: string nullable: true deprecated: true fieldType: $ref: '#/components/schemas/AnnotationContentType' dataSource: type: string description: Data source mapping identifier nullable: true mapping: type: string description: Defines how the data point is mapped to the data source nullable: true dataPoint: type: string mandatory: type: boolean disabled: type: boolean autoValidationThreshold: type: number nullable: true showDropdown: type: boolean displayRawText: type: boolean dropNull: type: boolean description: >- If True, any dropdown annotations that fail to parse to a value will be discarded displayEnumValue: type: boolean fields: type: array items: $ref: '#/components/schemas/FieldDeprecated' required: - label - dataPoint - fieldType additionalProperties: true Field: type: object properties: label: type: string dataPoint: type: string description: Data point identifier fieldType: $ref: '#/components/schemas/AnnotationContentType' dataSource: type: string description: Data source mapping identifier nullable: true mapping: type: string description: Defines how the data point is mapped to the data source nullable: true mandatory: type: boolean autoValidationThreshold: type: number nullable: true minimum: 0 maximum: 1 description: >- Threshold for auto validation. If null, uses the collection's autoValidationThreshold. enableAutoValidationThreshold: type: boolean nullable: true description: >- If true, the autoValidationThreshold enable auto validation from the threshold from this field if specified, else from the collection showDropdown: type: boolean deprecated: true displayEnumValue: type: boolean description: >- If true, both the value and the label for the enums will appear in the dropdown in the validation tool. hideEnumDetail: type: boolean description: If true, the hoverable enum value detail icon will be hidden. dropNull: type: boolean description: >- If True, any dropdown annotations that fail to parse to a value will be discarded enabledChildFields: type: array items: $ref: '#/components/schemas/Field' disabledChildFields: type: array items: $ref: '#/components/schemas/Field' slug: type: string nullable: true deprecated: true displayRawText: type: boolean description: >- If true, then the validation tool will show the user the raw text found on the page, not the value that has been parsed to a specific type. fields: type: array items: type: object nullable: true deprecated: true required: - label - dataPoint - fieldType additionalProperties: true PaletteColorOptions: type: object required: - main properties: main: type: string light: type: string dark: type: string contrastText: type: string AnnotationContentType: type: string description: The different data types of annotations enum: - text - integer - float - decimal - date - datetime - daterange - boolean - enum - location - phonenumber - json - table - expectedremuneration - jobtitle - language - skill - yearsexperience - group - table_deprecated - url - image - docclf 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 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). ````