> ## Documentation Index
> Fetch the complete documentation index at: https://developers.resistant.ai/llms.txt
> Use this file to discover all available pages before exploring further.

# Add submission characteristics [ap-2]

> Attach submission characteristics to the submission. Submission characteristics are properties associated with the original document submission by the end user.

In property descriptions, "user" refers to the person who submitted the document, and "customer" refers to the organization using the Documents API.

This endpoint can only be called if enable_submission_characteristics was set to true when creating the submission. When enabled, submitting characteristics is required before analysis begins.



## OpenAPI

````yaml /spec-ap-2.json put /v2/submission/{submission_id}/characteristics
openapi: 3.0.1
info:
  title: Resistant Documents 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://api.ap-2.documents.resistant.ai
security: []
paths:
  /v2/submission/{submission_id}/characteristics:
    put:
      summary: Add submission characteristics [ap-2]
      description: >-
        Attach submission characteristics to the submission. Submission
        characteristics are properties associated with the original document
        submission by the end user.


        In property descriptions, "user" refers to the person who submitted the
        document, and "customer" refers to the organization using the Documents
        API.


        This endpoint can only be called if enable_submission_characteristics
        was set to true when creating the submission. When enabled, submitting
        characteristics is required before analysis begins.
      operationId: putSubmissionCharacteristics
      parameters:
        - in: path
          name: submission_id
          required: true
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/SubmissionCharacteristicsRequest'
      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'
      security:
        - OAuth2:
            - submissions.write
components:
  schemas:
    SubmissionCharacteristicsRequest:
      title: SubmissionCharacteristicsRequest
      description: >-
        Properties associated with the original document submission by the end
        user.
      type: object
      properties:
        document_characteristics:
          title: Document characteristics
          description: Properties associated with the analyzed document.
          type: object
          nullable: true
          properties:
            document_type:
              title: Document type
              description: >-
                Type of the document, such as ID card, passport, or account
                statement.
              type: string
              enum:
                - unknown
                - id_card
                - drivers_license
                - birth_certificate
                - health_insurance_card
                - id_certificate
                - passport
                - residence_permit
                - account_confirmation
                - account_statement
                - bank_details
                - delivery_note
                - company_detail
                - earnings_confirmation
                - employer_identification_number
                - fees_statement
                - government_registry_confirmation
                - incorporation_certificate
                - insurance_claim
                - insurance_documentation
                - invoice
                - order
                - order_confirmation
                - payment
                - payment_confirmation
                - payslip
                - proof_of_address
                - receipt
                - registration_certificate
                - rental_agreement
                - report
                - residence_certificate
                - tax_form
                - tax_information
                - ticket
                - tracking_note
                - transaction_detail
                - transaction_history
                - transport_order
                - utility_bill
                - vehicle_appraisal
                - vehicle_registration_certificate
              maxLength: 1024
              nullable: true
            document_type_string:
              title: Custom document type
              description: >-
                Customer-specific document type name if not mapped to standard
                document_type values.
              type: string
              maxLength: 1024
              nullable: true
            issuing_country_code:
              $ref: '#/components/schemas/CountryCode'
            document_id:
              title: Document ID
              description: Customer-assigned document identifier, such as a scan reference.
              type: string
              maxLength: 1024
              nullable: true
            document_filename:
              title: Document filename
              type: string
              maxLength: 1024
              nullable: true
            document_score:
              title: Document score
              description: >-
                Internal document score or classification computed by the
                customer.
              type: string
              maxLength: 1024
              nullable: true
            status:
              title: Document status
              description: >-
                Document submission status computed by the customer, such as
                accepted, rejected, or pending verification.
              type: string
              maxLength: 1024
              nullable: true
            document_position_on_image:
              title: Document position on image
              description: Position of a document (e.g., ID card) on the submitted image
              type: object
              nullable: true
              properties:
                corner_1:
                  title: First corner (e.g., top-left) of the document
                  description: >-
                    Coordinates of a first corner of the document on the
                    submitted image.
                  type: object
                  properties:
                    x:
                      $ref: '#/components/schemas/XCoordinate'
                    'y':
                      $ref: '#/components/schemas/YCoordinate'
                  required:
                    - x
                    - 'y'
                corner_2:
                  title: Second corner (e.g., top-right) of the document
                  description: >-
                    Coordinates of a second corner of the document on the
                    submitted image.
                  type: object
                  properties:
                    x:
                      $ref: '#/components/schemas/XCoordinate'
                    'y':
                      $ref: '#/components/schemas/YCoordinate'
                  required:
                    - x
                    - 'y'
                corner_3:
                  title: Third corner (e.g., bottom-right) of the document
                  description: >-
                    Coordinates of a third corner of the document on the
                    submitted image.
                  type: object
                  properties:
                    x:
                      $ref: '#/components/schemas/XCoordinate'
                    'y':
                      $ref: '#/components/schemas/YCoordinate'
                  required:
                    - x
                    - 'y'
                corner_4:
                  title: Fourth corner (e.g., bottom-left) of the document
                  description: >-
                    Coordinates of a fourth corner of the document on the
                    submitted image.
                  type: object
                  properties:
                    x:
                      $ref: '#/components/schemas/XCoordinate'
                    'y':
                      $ref: '#/components/schemas/YCoordinate'
                  required:
                    - x
                    - 'y'
              required:
                - corner_1
                - corner_2
                - corner_3
                - corner_4
            source_channel:
              title: Source channel
              description: >-
                Channel through which the document was submitted, such as API,
                web, or mobile.
              type: string
              enum:
                - api
                - web
                - mobile
              nullable: true
              maxLength: 1024
            document_side:
              title: Document side
              description: Side of the document, e.g. front or back side of an ID card.
              type: string
              enum:
                - front
                - back
              nullable: true
              maxLength: 1024
        device_characteristics:
          title: Device characteristics
          description: Properties associated with the device used to submit the document.
          type: object
          nullable: true
          properties:
            device_ip_address:
              title: Device IP address
              description: Public IP address of the end user's device.
              type: string
              maxLength: 39
              nullable: true
            server_ip_address:
              title: IP address of the server where the document was submitted
              type: string
              maxLength: 39
              nullable: true
            country_code:
              title: Country code
              description: >-
                ISO 3166-1 alpha-3 code of the country from which the document
                was submitted.
              type: string
              maxLength: 1024
              nullable: true
              example: GBR
            country_name:
              title: Country name
              description: Name of the country from where the document was submitted.
              type: string
              maxLength: 1024
              nullable: true
            city:
              title: City
              description: City from which the document was submitted.
              type: string
              maxLength: 1024
              nullable: true
            postal_code:
              title: Postal code
              description: >-
                Postal code of the location from which the document was
                submitted.
              type: string
              maxLength: 1024
              nullable: true
            gcs_latitude:
              title: Latitude
              description: >-
                Latitude of the location from which the document was submitted,
                in decimal degrees (e.g., 38.775546 or 32.30642° N).
              type: string
              maxLength: 1024
              nullable: true
              example: '38.77554692'
            gcs_longitude:
              title: Longitude
              description: >-
                Longitude of the location from which the document was submitted,
                in decimal degrees (e.g., -75.1396939 or 75.1396939° E).
              type: string
              maxLength: 1024
              nullable: true
              example: '-75.1396939'
            isp:
              title: Internet service provider
              description: Name of the ISP of the connection used to submit the document.
              type: string
              maxLength: 1024
              nullable: true
            referer:
              title: Browser referer
              description: HTTP referer URL related to the submission.
              type: string
              maxLength: 1024
              nullable: true
            user_agent:
              title: User agent of the browser used to submit the document
              type: string
              maxLength: 1024
              nullable: true
              example: >-
                Mozilla/5.0 (Android 4.4; Mobile; rv:41.0) Gecko/41.0
                Firefox/41.0
            browser_description:
              title: Browser
              description: Browser name, such as Chrome or Safari.
              type: string
              maxLength: 1024
              nullable: true
            device_platform:
              title: Device platform
              description: Operating system or platform, such as Windows 10 or Android.
              type: string
              maxLength: 1024
              nullable: true
            device_language:
              title: Device language
              description: >-
                Device language in [ISO
                639-1](https://en.wikipedia.org/wiki/List_of_ISO_639-1_codes)
                format
              type: string
              maxLength: 1024
              nullable: true
              example: en
            screen_height:
              title: Screen height in pixels
              type: integer
              nullable: true
            screen_width:
              title: Screen width in pixels
              type: integer
              nullable: true
            device_fingerprint:
              title: Device fingerprint
              description: >-
                Customer-assigned unique device identifier, such as a
                fingerprint hash. Should be consistent across submissions from
                the same device.
              type: string
              maxLength: 1024
              nullable: true
        identity_characteristics:
          title: User identity characteristics
          description: Properties identifying the user who submitted the document.
          type: object
          nullable: true
          properties:
            first_name:
              title: First name
              type: string
              maxLength: 1024
              nullable: true
            last_name:
              title: Last name
              type: string
              maxLength: 1024
              nullable: true
            email:
              title: Email address
              type: string
              maxLength: 1024
              nullable: true
            user_id:
              title: User ID
              description: >-
                Customer-assigned identifier for the user or account holder who
                submitted the document.
              type: string
              maxLength: 1024
              nullable: true
            user_group_id:
              title: User group ID
              description: >-
                Customer-assigned identifier for grouping multiple users acting
                as a single entity.
              type: string
              maxLength: 1024
              nullable: true
            phone_number:
              title: Phone number
              type: string
              maxLength: 1024
              nullable: true
            date_of_birth:
              title: Date of birth
              description: Date of birth in YYYY-MM-DD (ISO 8601) format.
              type: string
              maxLength: 10
              nullable: true
              example: '2020-01-30'
        transaction_characteristics:
          title: Characteristics related to a transaction with the user
          description: >-
            Properties of a transaction between the user and customer, e.g.,
            load or purchase.
          type: object
          nullable: true
          properties:
            amount_usd:
              title: Amount converted to USD
              type: number
              nullable: true
              example: 120.5
            maturity_days:
              title: Number of days until maturity
              description: Number of days until maturity (e.g., for a loan)
              type: integer
              nullable: true
              example: 60
        email_characteristics:
          title: Characteristics related to an email interaction with the user
          description: >-
            Properties of an email interaction between the user and customer,
            e.g. email or subject hashes.
          type: object
          nullable: true
          properties:
            originator_address_hashes:
              title: >-
                SHA256 hashes of the email addresses of the originators (both
                the 'Sender' and 'From' fields).
              type: array
              items:
                type: string
                maxLength: 64
              nullable: true
              example:
                - >-
                  2cf24dba5fb0a30e26e83b2ac5b9e29e1b161e5c1fa7425e73043362938b9824
            originator_domain_hashes:
              title: >-
                SHA256 hashes of the email domains of the originators (both the
                'Sender' and 'From' fields).
              type: array
              items:
                type: string
                maxLength: 64
              nullable: true
              example:
                - >-
                  486ea46224d1bb4fb680f34f7c9ad96a8f24ec88be73ea8e5a6c65260e9cb8a7
            subject_hash:
              title: SHA256 hash of the email subject.
              type: string
              maxLength: 64
              nullable: true
              example: bbcfcbdecdfec348f558015cc36d01ab27081c2cef9dad3e44d9277b46de2f72
            number_of_recipients:
              title: Number of email recipients
              type: integer
              minimum: 0
              nullable: true
            recipient_hashes:
              title: Hashes of email recipients
              type: array
              items:
                type: string
                maxLength: 64
              nullable: true
              example:
                - >-
                  486ea46224d1bb4fb680f34f7c9ad96a8f24ec88be73ea8e5a6c65260e9cb8a7
            body_embedding:
              title: Embedding of email body
              type: string
              maxLength: 1024
              nullable: true
            subject_embedding:
              title: Embedding of email subject
              type: string
              maxLength: 1024
              nullable: true
        claims_characteristics:
          title: Insurance claims characteristics
          description: Properties of an insurance claim.
          type: object
          nullable: true
          properties:
            claim_number:
              title: Claim number
              type: string
              maxLength: 1024
              nullable: true
            policy_number:
              title: Policy number
              type: string
              maxLength: 1024
              nullable: true
            insurance_type:
              title: Insurance type
              type: string
              maxLength: 1024
              nullable: true
            incident_date:
              title: Incident date in YYYY-MM-DD (ISO-8601) format
              type: string
              maxLength: 10
              nullable: true
              example: '2020-01-30'
            reported_date:
              title: Reported date in YYYY-MM-DD (ISO-8601) format
              type: string
              maxLength: 10
              nullable: true
              example: '2020-01-30'
            incident_description:
              title: Incident description
              type: string
              maxLength: 1024
              nullable: true
            incident_location:
              title: Incident location
              type: string
              maxLength: 1024
              nullable: true
            claim_value:
              title: Claim value
              type: number
              nullable: true
              example: 1729.2
        submission_time:
          title: Document submission time
          description: Time of document submission by the end user
          type: string
          nullable: true
        customer_tenant_id:
          title: Customer tenant ID
          description: >-
            Customer-assigned identifier for a tenant or merchant. Must not
            contain PII. Used to separate data by tenant for monitoring and
            configuration.
          type: string
          maxLength: 1024
          nullable: true
        customer_case_id:
          title: Customer case ID
          description: >-
            Customer-assigned case identifier. Must not contain PII. Used to
            track document resubmissions.
          type: string
          maxLength: 1024
          nullable: true
    CountryCode:
      title: Country code
      description: ISO 3166-1 alpha-3 country code or UNKNOWN
      type: string
      maxLength: 1024
      nullable: true
    XCoordinate:
      title: X (horizontal) coordinate
      description: >-
        X (horizontal) coordinate in pixels. The axis starts (x=0) at the
        top-left corner of the image.
      type: integer
    YCoordinate:
      title: Y (vertical) coordinate
      description: >-
        Y (vertical) coordinate in pixels. The axis starts (y=0) at the top-left
        corner of the image.
      type: integer
    Error:
      title: Error
      type: object
      properties:
        message:
          title: Error message
          description: Detailed error message
          minLength: 0
          maxLength: 512
          type: string
      required:
        - message
  responses:
    BadRequest:
      description: Bad request.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Unauthorized:
      description: Missing valid authentication credentials.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    Forbidden:
      description: Access to the requested resource is forbidden.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    NotFound:
      description: The requested resource was not found.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    UnsupportedMediaType:
      description: Unsupported media type.
      content:
        application/json:
          schema:
            $ref: '#/components/schemas/Error'
    TooManyRequests:
      description: Request quota was exceeded
  securitySchemes:
    OAuth2:
      type: oauth2
      flows:
        clientCredentials:
          tokenUrl: https://eu.id.resistant.ai/oauth2/aus827qzu1l953dI4417/v1/token
          scopes:
            submissions.read: Read analysis results for a submission
            submissions.write: Create a new submission

````