--- agentTools: projectIndex: https://scandoc.readme.io/llms.txt --- # /extraction/ This endpoint is the backbone of our image data extraction process. Extraction endpoint is used in extracting data from document images. Images are prefferably first validated using /validation endpoint, but this endpoint can be used independently of validation endpoint. Supported REST method is /extraction/ POST method that submits the document images through JSON body alongside settings that the service should take into account when extracting the data. ## Request format Request contains keys as described by the form on this page. The request is split into 3 important section 1. Accepting terms and conditions - which have to be accepted to successfully perform any extraction 2. DataFields - that contain image data 3. Settings that contain multiple settings that can be used to tailor a response specifically to your desires ### Important notes regarding the request AcceptTermsAndConditions must be set to true, or the request won't be accepted. DataFields' Front and Back image keys do not have to actually contain front and back sides respectivelly, but they can be switched, this is due to backwards compatibility, the only restriction is if the document submitted contains only front side (most of European drivers licenses and all passports) IgnoreBackImage setting must be set to true. ### Settings structure Settings contains useful settings that tailor responses to your needs each used setting is as follows: 1. ShouldReturnDocumentImage - indicates if the cropped image of the document should be returned (we reccommend that this image is displayed to the user so the user can verify that the image was properly cropped) 2. ShouldReturnFaceIfDetected - indicates if the service should return face image from the document 3. ShouldReturnSignatureIfDetected - indicates if the service should return signature image from the document 4. **SkipDocumentsSizeCheck** - if set to true, any problems tied to input image size (document too far away from the camera or similar) will be added to warnings list and will not raise a BAD REQUEST 400 response 5. **SkipImageSizeCheck** - if set to true, any problems tied to low image resolution will be added to warnings list and will not raise a BAD REQUEST 400 response 6. **CanStoreImages** - allows the service to store the images that could be used for any troubleshooting or service improvements if set to true 7. **EnforceDocsSameCountryTypeSeries** - if set to true, raises a BAD REQUEST 400 error if the front side of the document doesn't correspond to the back side of the document - this might cause some service missfunctioning since some documents have very similar versions which could lead to BAD REQUEST 400 being thrown unnecessarily, we reccommend for this flag to be set to false 8. CaseSensitiveOutput - if set to true output will correspond to the input text symbols on the document, else all letters will be returned as capitalized 9. FaceImageResize - isn't a flag, but a field that takes the following format: XxY (ex. 300x400) which indicates the resize dimensions for the returned face image 10. SignatureImageResize - isn't a flag, but a field that takes the following format: XxY (ex. 300x400) which indicates the resize dimensions for the returned signature image 11. SegmentedImageResize - isn't a flag, but a field that takes the following format: XxY (ex. 300x400) which indicates the resize dimensions for the returned document cropped images 12. StoreFaceImage - if set to true, and if ShouldReturnFaceIfDetected is set to true, face image will be stored in AWS S3 container defined in the service environment 13. **DontUseValidation** - if set to true, the service runs one validation call prior to extraction and terminates the transaction if the image is inadequate, currently this option is true by default and extraction **does not** perform one additional validation call **Bolded settings** are important and could cause your requests to fail so be mindful of them, other settings are used more for specifically tailoring response format. ## Response The service responds with JSON body containing extraction results as given below: ```Text JSON { "TransactionID": "e8edb095-5640-4250-b59a-463df488db87", "UploadedAt": "2023-06-13T08:44:31.398563", "ProductName": "Scan App v8.2.2", "Errors": [], "Warnings": [], "Status": 200, "Method": "Extraction", "InfoCode": "1000", "Data": { "Name": { "Read": false, "Validated": false, "RecommendedValue": null, "MRZ": { "Read": false, "Value": null, "Validated": false }, "OCR": { "Read": false, "Value": null, "Validated": false } }, "BirthDate": { "Read": true, "Validated": true, "RecommendedValue": "25.11.1979", "OCR": { "Read": true, "Validated": true, "Value": "25.11.1979" }, "MRZ": { "Read": false, "Value": null, "Validated": false } }, { ... } }, "Metadata": [ { "Country": "HRV", "DocumentSide": "FRONT", "DocumentType": "ID", "DocumentSeries": "HRV-BO-04001" } ], "ImageData": { "Documents": [ "...", "..." ], "FaceImage": "...", "Signature": "..." }, "AnalysisTime": "1493.297 ms" } ``` Response contains fields similar to the /validation endpoint with a couple of differences. The /extraction endpoint doesn't contain info field - errors and warnings should be used instead. You can check info codes and their meaning [here](https://scandoc.readme.io/reference/extraction-info-codes) ### Response data The most important response fields are * Data * ImageData * Metadata *Data* field is a key-value dictionary where the keys are document fields (ex. name, surname, ...) and values are dictionaries with the following key-value structure: ```Text JSON "FieldKey": { "Read": true, "Validated": true, "RecommendedValue": "", "OCR": { "Read": true, "Validated": true, "Value": "" }, "MRZ": { "Read": false, "Value": "", "Validated": false } } ``` When unpacking *Data* key results, we reccomend you check each *Read* key and take the *ReccommendedValue* as the reading. You can check the what's next section if you want a detailed list of all available fields. *ImageData* contains images that were modified by the Settings input. *ImageData* is comprised of Documents, Signature, FaceImage. Documents contains one or two segmented images (depending on the amount of images submitted through a request) in the front/back order. Signature key holds a signature image and FaceImage key contains the face image. All image data is base64 encoded. *Metadata* contains metadata about each submitted image in the order of submittion (front/back): * Document country * Document type * Document series * Document side # OpenAPI definition ```json { "openapi": "3.1.0", "info": { "title": "ScanApp API", "version": "1.0" }, "servers": [ { "url": "https://api.scandoc.ai/ss/" } ], "security": [ {} ], "paths": { "/extraction/": { "post": { "summary": "/extraction/", "description": "This endpoint is the backbone of our image data extraction process.", "operationId": "extraction-1", "parameters": [ { "name": "Authorization", "in": "header", "description": "Authorization key provided by key-service", "required": true, "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "required": [ "DataFields", "AcceptTermsAndConditions" ], "properties": { "DataFields": { "type": "object", "description": "Object containing images submitted for extraction", "properties": { "FrontImageType": { "type": "string", "description": "Front image encoding declaration", "default": "base64" }, "FrontImageCropped": { "type": "boolean", "description": "Indicator defining if the front image is cropped", "default": false }, "BackImageType": { "type": "string", "description": "Back image encoding declaration", "default": "base64" }, "BackImageCropped": { "type": "boolean", "description": "Indicator defining if the back image is cropped", "default": false }, "FrontImage": { "type": "string", "description": "Base64 encoded front image" }, "BackImage": { "type": "string", "description": "Base64 encoded back image" } } }, "Settings": { "type": "object", "description": "Extraction settings so you can tailor requests to your own preference", "properties": { "ShouldReturnDocumentImage": { "type": "boolean", "description": "Indicator specifying if the segmented document image should be returned", "default": false }, "ShouldReturnFaceIfDetected": { "type": "boolean", "description": "Indicator if the service should return face image (if detected on the document)", "default": false }, "SkipReturnSignatureIfDetected": { "type": "boolean", "description": "Indicator if returning the signature should be skipped", "default": false }, "SkipDocumentSizeCheck": { "type": "boolean", "description": "Indicator if the document size (relative to the submitted image) check should be skipped - the service might reject images where the documents are too small since that might cause poor extraction", "default": false }, "SkipImageSizeCheck": { "type": "boolean", "description": "Indicator if image size check should be skipped - the service might reject images where the image resolution is too small since that might cause poor extraction", "default": false }, "CanStoreImages": { "type": "boolean", "description": "Indicator if the service is allowed to store images", "default": false }, "EnforceDocsSameCountryTypeSeries": { "type": "boolean", "description": "Indicator if the service should enforce that both sides of the documents match by series - some documents can be quite similar between series, we reccommend this to remain false", "default": false }, "CaseSensitiveOutput": { "type": "boolean", "description": "Indicator if the output should be case sensitive", "default": false }, "FaceImageResize": { "type": "string", "description": "Face image return value size - ex: \"200x200\" would result the returning face image be resized to 200x200" }, "SignatureImageResize": { "type": "string", "description": "Signature image return value size - ex: \"200x200\" would result the returning signature image be resized to 200x200" }, "SegmentedImageResize": { "type": "string", "description": "Segmented document image return value size - ex: \"200x200\" would result the returning segmented document image be resized to 200x200" }, "StoreFaceImage": { "type": "boolean", "description": "Indicator if the face images should be stored to the service specified location", "default": false }, "DontUseValidation": { "type": "boolean", "description": "Indicator if the service should not run an additional validation call prior to extraction", "default": true } } }, "AcceptTermsAndConditions": { "type": "boolean", "description": "Terms and conditions must be accepted in order to use this service", "default": true } } } } } }, "responses": { "200": { "description": "200", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"TransactionID\": \"e8edb095-5640-4250-b59a-463df488db87\",\n \"UploadedAt\": \"2023-06-13T08:44:31.398563\",\n \"ProductName\": \"Scan App v8.2.2\",\n \"Errors\": [],\n \"Warnings\": [],\n \"Status\": 200,\n \"Method\": \"Extraction\",\n \"InfoCode\": \"1000\",\n \"Data\": {\n \"Name\": {\n \"Read\": false,\n \"Validated\": false,\n \"RecommendedValue\": null,\n \"MRZ\": {\n \"Read\": false,\n \"Value\": null,\n \"Validated\": false\n },\n \"OCR\": {\n \"Read\": false,\n \"Value\": null,\n \"Validated\": false\n }\n },\n \"BirthDate\": {\n \"Read\": true,\n \"Validated\": true,\n \"RecommendedValue\": \"25.11.1979\",\n \"OCR\": {\n \"Read\": true,\n \"Validated\": true,\n \"Value\": \"25.11.1979\"\n },\n \"MRZ\": {\n \"Read\": false,\n \"Value\": null,\n \"Validated\": false\n }\n },\n {\n ...\n }\n },\n \"Metadata\": [\n {\n \"Country\": \"HRV\",\n \"DocumentSide\": \"FRONT\",\n \"DocumentType\": \"ID\",\n \"DocumentSeries\": \"HRV-BO-04001\"\n }\n ],\n \"ImageData\": {\n \"Documents\": [\n \"...\", \"...\"\n ],\n \"FaceImage\": \"...\",\n \"Signature\": \"...\"\n },\n \"AnalysisTime\": \"1493.297 ms\"\n}" } } } } }, "400": { "description": "400", "content": { "application/json": { "examples": { "Result": { "value": "{\n \"TransactionID\": \"e8edb095-5640-4250-b59a-463df488db87\",\n \"UploadedAt\": \"2023-06-13T08:44:31.398563\",\n \"ProductName\": \"Scan App v8.2.2\",\n \"Errors\": [\"Error1\", ...],\n \"Warnings\": [\"Warning1\", ...],\n \"Status\": 400,\n \"Method\": \"Extraction\",\n \"InfoCode\": \"1000\",\n \"AnalysisTime\": \"1493.297 ms\"\n}" } } } } } }, "deprecated": false, "security": [] } } }, "x-readme": { "headers": [], "explorer-enabled": true, "proxy-enabled": true }, "x-readme-fauxas": true, "_id": "651199055344160047ffb101:651199bf38be0500673b4638" } ```