Skip to main content
Submission characteristics are optional metadata that you can attach to a submission to provide additional context about the document, the submitting user, and the submission environment. They help to:
  • better understand the data and its origin (e.g., source channels, customer segments)
  • add behavioural, device, and identity context that can improve serial fraud detection recall
  • reduce false-positive clustering across multiple submissions from the same user (when a stable user_id is provided)

​
Important behavior

Submission characteristics are attached using: PUT /v2/submission/{submission_id}/characteristics Calling this endpoint is only allowed if enable_submission_characteristics is set to true when creating the submission. When submission characteristics are enabled for a submission, submitting them becomes required — the document will not be analyzed without them.

​
How to enable submission characteristics

When creating a submission, set:
  • enable_submission_characteristics: true
The create-submission response provides a submission_characteristics_upload_url you can use to attach characteristics.

​
What data can be provided

The request body supports the following top-level groups (all are optional):
  • document_characteristics
  • device_characteristics
  • identity_characteristics
  • transaction_characteristics
  • email_characteristics
  • claims_characteristics
  • submission_time
  • customer_tenant_id
  • customer_case_id

​
Highlights (what’s most useful in practice)

​
Document origin & context

Use document_characteristics to provide non-sensitive context such as:
  • document type and custom document type labels
  • source channel (e.g., API vs web vs mobile)

​
Device and behavioural context

Use device_characteristics to supply information that can help detect unusual submission patterns (e.g., high-volume or suspicious device behaviours).

​
Identity and user-level grouping

Use identity_characteristics.user_id to reduce false positives caused by clustering multiple submissions from the same user under different contexts.
Good rule: user_id should be stable, non-PII, and consistent across your systems (e.g., internal account ID, not an email/phone).

​
Segmentation fields

  • customer_tenant_id: customer-assigned identifier used to separate data by customer tenants for monitoring/configuration (shouldn’t contain PII).
  • customer_case_id: customer-assigned case identifier used to correlate resubmissions (shouldn’t contain PII).

​
Schema extensibility

All submission characteristics fields are optional (unless you enable them for the submission, in which case some submitting characteristics is required to proceed). If you need additional fields for your workflow, contact Resistant AI to discuss extending the schema.