AFaffinda
Documents

Upload a document for parsing

Changed on

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} endpoint to check processing status and retrieve results.<br/>

post/v3/documents

Request

Query parameters

snake_caseboolean

Whether to return the response in snake_case instead of camelCase. Default is false.

Request body multipart/form-data

filestring binary

File as binary data blob. Supported formats: PDF, DOC, DOCX, TXT, RTF, HTML, PNG, JPG, TIFF, ODT, XLS, XLSX

urlstring nullable

URL to download the document.

collectionstring

Uniquely identify a collection.

documentTypestring nullable

The document type's identifier. Provide if you already know the document type.

workspacestring

Uniquely identify a workspace.

waitboolean

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.

identifierstring

Deprecated in favor of customIdentifier.

customIdentifierstring

Specify a custom identifier for the document if you need one, not required to be unique.

fileNamestring nullable

Optional filename of the file

expiryTimestring date-time nullable

The date/time in ISO-8601 format when the document will be automatically deleted. Defaults to no expiry.

languagestring nullable

Language code in ISO 639-1 format. Must specify zh-cn or zh-tw for Chinese.

rejectDuplicatesboolean nullable

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.

regionBiasstring

A JSON representation of the RegionBias object.

lowPriorityboolean

Explicitly mark this document as low priority.

compactboolean

If true, the returned parse result (assuming wait is also true) will be a compact version of the full result.

deleteAfterParseboolean

If true, no data will be stored after parsing. Only compatible with requests where wait: True.

enableValidationToolboolean

If true, the document will be viewable in the Affinda Validation Tool. Set to False to optimize parsing speed.

useOcrboolean nullable

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.

llmHintstring nullable

Optional hint inserted into the LLM prompt when processing this document.

limitToExamplesstring[] nullable

Restrict LLM example selection to the specified document identifiers.

Example request

{
  "url": "https://api.affinda.com/static/sample_resumes/example.docx",
  "collection": "mEFayXdO",
  "workspace": "mEFayXdO",
  "wait": true,
  "fileName": "Document.pdf",
  "language": "en",
  "rejectDuplicates": true,
  "regionBias": "{\"country\": \"vn\"}",
  "lowPriority": true,
  "compact": true,
  "deleteAfterParse": true,
  "enableValidationTool": true,
  "warningMessages": [
    {
      "warningCode": "too_many_pages",
      "warningDetail": "File exceeds maximum number of pages allowed, parsing the first 10 pages only."
    }
  ]
}

Response

Only returned when wait=True, will return the created document

dataobject
extractorstring required

Example response

{
  "meta": {
    "customIdentifier": "46ab8b02-0e5b-420c-877c-8b678d46a834",
    "fileName": "Document.pdf",
    "ready": true,
    "readyDt": "2020-12-10T01:43:32.276724Z",
    "language": "en",
    "pdf": "https://affinda-api.s3.amazonaws.com/media/documents/Document.pdf?AWSAccessKeyId=KEY&Signature=SIG&Expires=1663302062",
    "parentDocument": {
      "customIdentifier": "46ab8b02-0e5b-420c-877c-8b678d46a834"
    },
    "childDocuments": [
      {
        "customIdentifier": "46ab8b02-0e5b-420c-877c-8b678d46a834"
      }
    ],
    "pages": [
      {
        "image": "https://affinda-api.s3.amazonaws.com/media/pages/Page.png?AWSAccessKeyId=KEY&Signature=SIG&Expires=1663302062",
        "imageTranslated": "https://affinda-api.s3.amazonaws.com/media/pages/PageTranslated.png?AWSAccessKeyId=KEY&Signature=SIG&Expires=1663302062",
        "height": 700,
        "width": 500,
        "rotation": 90
      }
    ],
    "collection": {
      "identifier": "mEFayXdO",
      "extractor": {
        "identifier": "resume"
      },
      "validationRules": [
        {
          "slug": "supplier_name_is_alphanumeric"
        }
      ]
    },
    "workspace": {
      "identifier": "mEFayXdO"
    },
    "confirmedBy": {
      "id": 1,
      "name": "Carl Johnson",
      "username": "carljohnson",
      "email": "carljohnson@grove.street",
      "avatar": "https://affinda-api.s3.amazonaws.com/media/user-avatar.png?AWSAccessKeyId=KEY&Signature=SIG"
    },
    "rejectedBy": {
      "id": 1,
      "name": "Carl Johnson",
      "username": "carljohnson",
      "email": "carljohnson@grove.street",
      "avatar": "https://affinda-api.s3.amazonaws.com/media/user-avatar.png?AWSAccessKeyId=KEY&Signature=SIG"
    },
    "archivedBy": {
      "id": 1,
      "name": "Carl Johnson",
      "username": "carljohnson",
      "email": "carljohnson@grove.street",
      "avatar": "https://affinda-api.s3.amazonaws.com/media/user-avatar.png?AWSAccessKeyId=KEY&Signature=SIG"
    },
    "errorCode": "document_conversion_failed",
    "errorDetail": "Unable to convert word document",
    "tags": [
      {
        "id": 1,
        "workspace": "mEFayXdO"
      }
    ],
    "createdBy": {
      "id": 1,
      "name": "Carl Johnson",
      "username": "carljohnson",
      "email": "carljohnson@grove.street",
      "avatar": "https://affinda-api.s3.amazonaws.com/media/user-avatar.png?AWSAccessKeyId=KEY&Signature=SIG"
    },
    "regionBias": {
      "strict": true
    }
  },
  "error": {
    "errorCode": "document_conversion_failed",
    "errorDetail": "Unable to convert word document"
  },
  "warnings": [
    {
      "warningCode": "too_many_pages",
      "warningDetail": "File exceeds maximum number of pages allowed, parsing the first 10 pages only."
    }
  ]
}

Changes

  • 86b6b449b1f3Revision changes
    • info

      added the new optional request property

  • 978cf99a2ac0Revision changes
    • breaking

      the response property // became nullable for the status

    • breaking

      the response property // became nullable for the status

    • warning

      removed the request property

    • info

      api tag Documents added

    • info

      api tag Document API - Document removed

    • info

      added the new optional request property

    • info

      added the optional property / to the response with the status

    • info

      added the optional property / to the response with the status