Resistant AI Submission API
The Submission API from Resistant AI — 10 operation(s) for submission.
The Submission API from Resistant AI — 10 operation(s) for submission.
openapi: 3.0.1
info:
title: Resistant Documents Submission API
version: 2.0.0b
description: '
Resistant Documents provides this API to programmatically interact with its document analysis engine.
Interaction with the API can be divided into three phases:
1. Creating document submission
2. Uploading a file for for analysis to an address returned from step 1.
3. Fetching analysis results
In the first step, the submission is created by posting to the `/v2/submission` endpoint. The response contains a `submission_id` uniquely identifying the document to be analyzed throughout the entire interaction, and is used to fetch analysis results later.
Submission response also returns `upload_url` containing a pre-signed URL. This URL should be used to upload the actual document to be analyzed in the second step. Please note the document has to be uploaded using HTTP `PUT` method with `Content-Type` HTTP header set to `application/octet-stream`.
In the last step, client should repeatedly poll using the `/v2/submission/{submission_id}/fraud` endpoint for analysis results. The best practice is to use polling with an [exponential back-off](https://en.wikipedia.org/wiki/Exponential_backoff) to reduce load on the API.
# Authentication
<SecurityDefinitions />'
servers:
- url: https://{environment}.resistant.ai
variables:
environment:
default: api.documents
enum:
- api.documents
- api.us-1.documents
- api.ca-1.documents
- api.ap-2.documents
- api.ap-3.documents
- api.documents.testing
tags:
- name: Submission
paths:
/v2/submission:
post:
summary: Create a submission
description: Create a new submission for a document to be analyzed
operationId: createSubmission
security:
- OAuth2:
- submissions.write
responses:
'200':
description: Submission created successfully
content:
application/json:
schema:
$ref: '#/components/schemas/SubmissionResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
'429':
$ref: '#/components/responses/TooManyRequests'
requestBody:
required: false
content:
application/json:
schema:
$ref: '#/components/schemas/SubmissionRequest'
tags:
- Submission
/v2/submission/{submission_id}/characteristics:
put:
summary: Add submission characteristics
operationId: putSubmissionCharacteristics
description: 'Attach submission characteristics to the submission. Submission characteristics are properties associated with the <i>original</i> submission of the document (i.e., from the end user).
In descriptions of the properties, "user" refers to the person who initially submitted the document, "customer" refers to a customer of Resistant.ai using this API.
Calling this endpoint is only allowed if `enable_submission_characteristics` is set to `true` when creating the submission. When submission characteristics are enabled for the submission, submitting then is <b>required</b> (the document will not be analyzed without them).'
security:
- OAuth2:
- submissions.write
parameters:
- in: path
name: submission_id
required: true
schema:
type: string
responses:
'204':
description: Submission characteristics were submitted successfully
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
'429':
$ref: '#/components/responses/TooManyRequests'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/SubmissionCharacteristicsRequest'
tags:
- Submission
/v2/submission/{submission_id}/fraud:
get:
summary: Fetch fraud result
operationId: getFraud
description: Fetch fraud analysis result
security:
- OAuth2:
- submissions.read
parameters:
- in: query
name: with_metadata
description: Enables indicator medatadata in the response object
required: false
schema:
type: boolean
default: false
- in: path
name: submission_id
required: true
schema:
type: string
responses:
'200':
description: Asynchronous processing finished (either with a success or an error). Result of the processing is described by the specific response object.
content:
application/json:
schema:
$ref: '#/components/schemas/AnalysisResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
'429':
$ref: '#/components/responses/TooManyRequests'
tags:
- Submission
/v2/submission/{submission_id}/content:
get:
summary: Fetch content result [limited]
description: Fetch content extraction result
operationId: getContent
security:
- OAuth2:
- submissions.read
parameters:
- in: path
name: submission_id
required: true
schema:
type: string
responses:
'200':
description: Asynchronous processing finished (either with a success or an error). Result of the processing is described by specific response object.
content:
application/json:
schema:
$ref: '#/components/schemas/ContentResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
'429':
$ref: '#/components/responses/TooManyRequests'
tags:
- Submission
/v2/submission/{submission_id}/quality:
get:
summary: Fetch quality result
operationId: getQuality
security:
- OAuth2:
- submissions.read
parameters:
- in: path
name: submission_id
required: true
schema:
type: string
responses:
'200':
description: Asynchronous processing finished (either with a success or an error). Result of the processing is described by specific response object.
content:
application/json:
schema:
$ref: '#/components/schemas/QualityResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
'429':
$ref: '#/components/responses/TooManyRequests'
tags:
- Submission
/v2/submission/{submission_id}/decision:
get:
summary: Fetch Adaptive Decision result
description: Fetch Adaptive Decision result
operationId: getDecision
security:
- OAuth2:
- submissions.read
parameters:
- in: path
name: submission_id
required: true
schema:
type: string
- in: query
name: embed
description: Comma-separated list of `decision_inputs` that should include the full data in its `data` attribute, e.g. `?embed=fraud`.
example: fraud
required: false
schema:
type: string
responses:
'200':
description: Results of Adaptive Decision if Adaptive Decision was enabled for the submission.
content:
application/json:
schema:
$ref: '#/components/schemas/AdaptiveDecisionResponse'
'400':
description: Bad request. Submission must be created with `enable_decision` flag set to `true`.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: Not found. Submission doesn't exist or verdict is not ready yet.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
'429':
$ref: '#/components/responses/TooManyRequests'
tags:
- Submission
/v2/submission/{submission_id}/classification:
get:
summary: Fetch document classification
operationId: getClassification
description: Fetch classification of the type of the submitted document
security:
- OAuth2:
- submissions.read
parameters:
- in: path
name: submission_id
required: true
schema:
type: string
responses:
'200':
description: Results of document type classification if classification analysis was enabled for the submission.
content:
application/json:
schema:
$ref: '#/components/schemas/ClassificationResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'429':
$ref: '#/components/responses/TooManyRequests'
tags:
- Submission
/v2/submission/{submission_id}/report:
get:
summary: Fetch report [preview]
operationId: getReport
description: Fetch fraud analysis report of the submitted document
security:
- OAuth2:
- submissions.read
parameters:
- in: path
name: submission_id
required: true
schema:
type: string
- in: query
name: include_decision
description: Include Adaptive Decision result in report
schema:
type: boolean
responses:
'200':
description: Download URL to get the fraud analysis report.
content:
application/json:
schema:
$ref: '#/components/schemas/ReportResponse'
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
$ref: '#/components/responses/NotFound'
'409':
description: The report cannot be downloaded because the fraud analysis or adaptive decision was not completed successfully or was skipped.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'429':
$ref: '#/components/responses/TooManyRequests'
tags:
- Submission
/v2/submission/{submission_id}:
delete:
summary: Delete submission
description: Permanently deletes the submission. Can be used, e.g., to remove a document before the configured retention period.
operationId: deleteSubmission
security:
- OAuth2:
- submissions.write
parameters:
- in: path
name: submission_id
required: true
schema:
type: string
responses:
'204':
description: Submission deleted.
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: Submission doesn't exist.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'409':
description: Submission cannot be deleted while it is being processed. Retry the request later.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
'429':
$ref: '#/components/responses/TooManyRequests'
tags:
- Submission
/v2/submission/{submission_id}/feedback:
put:
summary: Add analysis feedback
description: "Add custom feedback for the document analysis result. \n\nAll custom feedback provided for a document must be reviewed by the customer before submission to ensure it does not contain any Personally Identifiable Information (PII). Submitted feedback will be securely stored indefinitely to support ongoing product improvements."
operationId: putFeedback
security:
- OAuth2:
- submissions.write
parameters:
- in: path
name: submission_id
required: true
schema:
type: string
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/FeedbackRequest'
responses:
'200':
description: Custom feedback for fraud analysis.
content:
application/json:
schema:
$ref: '#/components/schemas/FeedbackResponse'
'400':
description: Bad request. Feedback must be sent with all required properties.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: Not found. Submission doesn't exist.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
'429':
$ref: '#/components/responses/TooManyRequests'
tags:
- Submission
get:
summary: Get analysis feedback
description: Get custom feedback for the document analysis result previously stored with a PUT request to this endpoint.
operationId: getFeedback
security:
- OAuth2:
- submissions.read
parameters:
- in: path
name: submission_id
required: true
schema:
type: string
responses:
'200':
description: Custom feedback for fraud analysis.
content:
application/json:
schema:
$ref: '#/components/schemas/FeedbackResponse'
'401':
$ref: '#/components/responses/Unauthorized'
'403':
$ref: '#/components/responses/Forbidden'
'404':
description: Not found. Submission or feedback doesn't exist.
content:
application/json:
schema:
$ref: '#/components/schemas/Error'
'415':
$ref: '#/components/responses/UnsupportedMediaType'
'429':
$ref: '#/components/responses/TooManyRequests'
tags:
- Submission
components:
schemas:
PipelineInvalidInputResponse:
title: Unprocessable input entity
type: object
properties:
status:
title: Status
enum:
- INVALID_INPUT
type: string
message:
title: Error message
minLength: 0
maxLength: 256
type: string
deployment_version:
title: Deployment version
description: Version of analysis engine used for analysis
minLength: 0
maxLength: 256
type: string
analysis_time:
title: Analysis time
description: Timestamp of analysis
type: string
file_type:
description: General type of the input file
title: File Type
$ref: '#/components/schemas/FileType'
mime_type:
title: Mime type
description: Mime type of the input file, e.g. `application/pdf`, `image/jpeg`, etc.
minLength: 0
maxLength: 256
type: string
nullable: true
query_id:
title: Query ID
description: Customer's own submission ID. This field may contain customer's own internal ID of analyzed file (e.g. ID in database).
minLength: 0
maxLength: 256
type: string
nullable: true
required:
- status
- message
- deployment_version
- analysis_time
BillingMonth:
title: BillingMonth
type: object
properties:
month:
title: Billing month
type: integer
year:
title: Billing year
type: integer
required:
- month
- year
SubmissionResponse:
title: SubmissionResponse
type: object
properties:
upload_url:
title: Presigned URL
description: "Presigned URL to AWS S3 service where the actual file will\nbe uploaded using the PUT method. Note that the content type in the PUT request\nhas to be set to `application/octet-stream`.\n\nExample file upload request using `curl`:\n```\ncurl --request PUT \\\n --url $UPLOAD_URL \\\n --header 'content-type: application/octet-stream' \\\n --data @path_to_file\n```\n"
type: string
format: uri
submission_id:
title: Submission ID
description: Unique submission ID generated by Documents service that uniquely identifies the submitted file.
minLength: 24
maxLength: 36
type: string
submission_characteristics_upload_url:
title: Submission characteristics upload URL
description: URL where submission characteristics can be attached to this submission - see the `/v2/submission/{submission_id}/characteristics` endpoint. Note that this URL is not pre-signed and requires access token in headers. The URL may be relative.
type: string
format: uri
required:
- upload_url
- submission_id
DocumentClass:
title: DocumentClass
type: object
properties:
id:
title: Document class
description: Document class that describes type of file submitted for analysis, e.g. invoice, account statement, payslip, etc.
minLength: 0
maxLength: 256
type: string
type:
title: Document class identifier
description: A unique identifier for the document class, e.g. `invoice_bouygues_fra`, `receipt_github`, `payslip_sdworx`, etc.
$ref: '#/components/schemas/DocumentType'
document_class_type:
title: Object discriminator
description: This field can be used to discriminate the actual type of the serialized object, for more details see http://spec.openapis.org/oas/v3.1.0#composition-and-inheritance-polymorphism. Note that the list is not fixed and additional types may be added without further notice.
enum:
- DocumentClass
type: string
required:
- id
- type
- document_class_type
ClassificationResponse:
title: Document type classification response
discriminator:
propertyName: status
mapping:
SUCCESS: '#/components/schemas/ClassificationSuccessResponse'
FAILED: '#/components/schemas/PipelineFailedResponse'
INVALID_INPUT: '#/components/schemas/PipelineInvalidInputResponse'
SKIPPED: '#/components/schemas/PipelineSkippedResponse'
anyOf:
- $ref: '#/components/schemas/ClassificationSuccessResponse'
- $ref: '#/components/schemas/PipelineFailedResponse'
- $ref: '#/components/schemas/PipelineInvalidInputResponse'
- $ref: '#/components/schemas/PipelineSkippedResponse'
SupportedCountry:
title: SupportedCountry
description: An enumeration.
enum:
- CZ
type: string
DocumentClassificationScore:
title: Document type
description: Toplevel score for classification
type: string
nullable: true
enum:
- CLASSIFIED
- DOCUMENT_MISSING
- NOT_CLASSIFIED
SampleMetadata:
title: SampleMetadata
description: Metadata of an analyzed file.
type: object
properties:
producer:
title: Document producer
minLength: 0
maxLength: 256
type: string
nullable: true
creator:
title: Document creator
minLength: 0
maxLength: 256
type: string
nullable: true
creation_date:
title: Creation date
type: string
nullable: true
mod_date:
title: Modification date
type: string
nullable: true
author:
title: Document author
minLength: 0
maxLength: 256
type: string
nullable: true
title:
title: Document title
minLength: 0
maxLength: 256
type: string
nullable: true
keywords:
title: Keywords
minLength: 0
maxLength: 256
type: string
nullable: true
subject:
title: Subject
minLength: 0
maxLength: 256
type: string
nullable: true
CardBackZaf:
title: ZAF IdCard Back
type: object
properties:
card_generation:
title: Card generation
$ref: '#/components/schemas/CardGeneration'
issuing_country:
title: Issuing country
description: Country that issued this ID card, e.g. USA, DEU, FRA, CZE, SVK, etc. The country code is encoded with ISO-31661 alpha-3 code, see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements.
minLength: 3
maxLength: 3
type: string
id_card_type:
title: Id Card Type
enum:
- ZafBack
type: string
content_type:
title: Content Type
enum:
- IdCard
type: string
card_no_str:
title: Card No Str
type: string
nullable: true
barcode_str:
title: Barcode Str
type: string
nullable: true
required:
- card_generation
- issuing_country
- id_card_type
- content_type
UtilityBillDocumentClass:
title: UtilityBillDocumentClass
type: object
properties:
id:
title: Document class
description: Document class that describes type of file submitted for analysis, e.g. invoice, account statement, payslip, etc.
minLength: 0
maxLength: 256
type: string
type:
title: Document class identifier
description: A unique identifier for the document class, e.g. `invoice_bouygues_fra`, `receipt_github`, `payslip_sdworx`, etc.
$ref: '#/components/schemas/DocumentType'
document_class_type:
title: Document Class Type
enum:
- UtilityBillDocumentClass
type: string
detailed_type:
title: Utility bill type
description: Type of the utility bill. Note that the list is not fixed and additional types may be added without further notice.
$ref: '#/components/schemas/UtilityBillType'
required:
- id
- type
- document_class_type
- detailed_type
CardFrontCze2012:
title: CZE IdCard Front
type: object
properties:
card_generation:
title: Card generation
$ref: '#/components/schemas/CardGeneration'
issuing_country:
title: Issuing country
description: Country that issued this ID card, e.g. USA, DEU, FRA, CZE, SVK, etc. The country code is encoded with ISO-31661 alpha-3 code, see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements.
minLength: 3
maxLength: 3
type: string
id_card_type:
title: Id Card Type
enum:
- CzeFront2012
type: string
content_type:
title: Content Type
enum:
- IdCard
type: string
first_name:
title: First Name
type: string
nullable: true
last_name:
title: Last Name
type: string
nullable: true
card_no:
title: Card No
type: integer
nullable: true
date_of_birth_str:
title: Date Of Birth Str
type: string
nullable: true
date_of_expiry_str:
title: Date Of Expiry Str
type: string
nullable: true
nationality:
title: Nationality
type: string
nullable: true
date_of_issue_str:
title: Date Of Issue Str
type: string
nullable: true
place_of_birth:
title: Place Of Birth
type: string
nullable: true
sex:
$ref: '#/components/schemas/Sex'
nullable: true
required:
- card_generation
- issuing_country
- id_card_type
- content_type
IndicatorMetadataElement:
title: IndicatorMetadataElement
discriminator:
propertyName: type
mapping:
BBoxOnly: '#/components/schemas/BBoxOnlyMetadataElement'
BBoxGroups: '#/components/schemas/BBoxGroupsMetadataElement'
BBoxWithOldAndNewText: '#/components/schemas/NewAndOldTextMetadataElement'
BBoxWithText: '#/components/schemas/TextMetadataElement'
BBoxIncrementalUpdate: '#/components/schemas/IncrementalUpdateIndicatorMetadataElement'
anyOf:
- $ref: '#/components/schemas/BBoxOnlyMetadataElement'
- $ref: '#/components/schemas/BBoxGroupsMetadataElement'
- $ref: '#/components/schemas/NewAndOldTextMetadataElement'
- $ref: '#/components/schemas/TextMetadataElement'
- $ref: '#/components/schemas/IncrementalUpdateIndicatorMetadataElement'
QualityResponse:
title: Quality engine response
discriminator:
propertyName: status
mapping:
SUCCESS: '#/components/schemas/QualitySuccessResponse'
FAILED: '#/components/schemas/PipelineFailedResponse'
INVALID_INPUT: '#/components/schemas/PipelineInvalidInputResponse'
SKIPPED: '#/components/schemas/PipelineSkippedResponse'
anyOf:
- $ref: '#/components/schemas/QualitySuccessResponse'
- $ref: '#/components/schemas/PipelineFailedResponse'
- $ref: '#/components/schemas/PipelineInvalidInputResponse'
- $ref: '#/components/schemas/PipelineSkippedResponse'
CardBackCze2012:
title: CZE IdCard Back
type: object
properties:
card_generation:
title: Card generation
$ref: '#/components/schemas/CardGeneration'
issuing_country:
title: Issuing country
description: Country that issued this ID card, e.g. USA, DEU, FRA, CZE, SVK, etc. The country code is encoded with ISO-31661 alpha-3 code, see https://en.wikipedia.org/wiki/ISO_3166-1_alpha-3#Officially_assigned_code_elements.
minLength: 3
maxLength: 3
type: string
id_card_type:
title: Id Card Type
enum:
- CzeBack2012
type: string
content_type:
title: Content Type
enum:
- IdCard
type: string
personal_no:
title: Personal No
type: string
nullable: true
machine_readable_summary:
$ref: '#/components/schemas/MachineReadableSummary'
barcode_str:
title: Barcode Str
type: string
nullable: true
permanent_stay:
title: Permanent Stay
type: string
nullable: true
academic_degree:
title: Academic Degree
type: string
nullable: true
issued_by:
title: Issued By
type: string
nullable: true
marital_status:
$ref: '#/components/schemas/MaritalStatus'
nullable: true
required:
- card_generation
- issuing_country
- id_card_type
- content_type
- machine_readable_summary
ElementsCollectionIndicatorMetadata:
title: ElementsCollectionIndicatorMetadata
type: object
properties:
type:
title: Type
enum:
- ElementsCollection
type: string
data:
title: Metadata elements
description: Metadata elements that represents individual detections, e.g. modified characters, area with flash reflection, etc.
type: array
items:
$ref: '#/components/schemas/IndicatorMetadataElement'
columns_definition:
title: Columns definition
description: Definition of columns in data table.
type: array
items:
$ref: '#/components/schemas/ColumnDefinition'
required:
- type
AdaptiveDecisionSuccessResponse:
title: Adaptive Decision success response
type: object
properties:
status:
title: Status
description: '`SUCCESS` status indicates the Adaptive Decision result is available'
type: string
enum:
- SUCCESS
decision:
title: Decision
type: string
description: 'Value range of this field is determined by tenant configuration, however default values are enum: `APPROVED`, `DECLINED`, `MANUAL_REVIEW`'
decision_inputs:
title: Decision inputs
description: Inputs the decision is based on
type: object
properties:
fraud:
title: Fraud analysis result
description: Link to fraud analysis result. Full `data` is only included if requested with the `embed` query string parameter
type: object
properties:
url:
title: Fraud analysis result URL
description: URL where full fraud analysis can be retrieved
example: /v2/submission/submission123/fraud
type: string
format: uri
data:
$ref: '#/components/schemas/AnalysisResponse'
required:
- url
adaptive_decision_version:
title: Version of Adaptive Decision configuration
type: string
reason:
title: Customer-specific explanation of the decision
type: object
properties:
sub_reason:
type: object
properties:
value:
title: Reason identifier
description: Machine-readable identifier of the reason
type: string
maxLength: 1024
label:
title: Reason description
description: Human-readable description of the reason
type: string
maxLength: 1024
nullable: true
required:
- status
- decision
- decision_inputs
- adaptive_decision_version
CardGener
# --- truncated at 32 KB (105 KB total) ---
# Full source: https://raw.githubusercontent.com/api-evangelist/resistant-ai/refs/heads/main/openapi/resistant-ai-submission-api-openapi.yml