Data Models

Reference documentation for all API resource data models.

Verification

A verification represents a single identity verification request.

json

{
  "id": "ver_xxxxx",
  "url": "https://{workspace}.colleckt.io/spa/v3/.../process",
  "qr_code": "https://{workspace}.colleckt.io/qr/...",
  "vendor_reference": "REF-001",
  "vendor_state": "TN",
  "expected_data": { ... },
  "status_label": "Approved",
  "submitted_at": "2026-06-11T07:36:11.000000Z",
  "created_at": "2026-06-11T07:04:50.000000Z",
  "updated_at": "2026-06-11T07:36:42.000000Z",
  "flow": "USPS 1583",
  "documents": [ ... ],
  "comments": [ ... ],
  "history": [ ... ]
}

Fields:

Field	Type	Description
`id`	string	Unique verification ID, prefixed with `ver_`
`url`	string	URL to the end-user verification widget
`qr_code`	string	QR code image URL for mobile access
`vendor_reference`	string (nullable)	Internal reference for tracking
`vendor_state`	string (nullable)	Vendor state information
`expected_data`	object	Expected person, address, and document details
`status_label`	string	Human-readable status (e.g. Started, Submitted, Approved, etc.)
`submitted_at`	string (nullable)	ISO 8601 timestamp of submission
`created_at`	string	ISO 8601 timestamp of creation
`updated_at`	string	ISO 8601 timestamp of last update
`flow`	string	Display name of the verification flow (e.g. "USPS 1583")
`documents`	array	Verification documents (only present on detail view)
`comments`	array	Non-private comments (sorted newest first)
`history`	array	Status change history (only present on detail view)

Expected Data

json

{
  "person": {
    "first_name": "Homer",
    "last_name": "Simpson",
    "date_of_birth": "1988-05-06"
  },
  "address": {
    "street": "742 Evergreen Terrace",
    "city": "Springfield",
    "state": "Tennessee",
    "postal_code": "92026",
    "country": "USA"
  },
  "documents": {
    "photo_id": {
      "type": "Passport",
      "number": "AB123456",
      "country": "USA"
    },
    "proof_of_address": {
      "type": "Driver License",
      "number": "DL789012",
      "country": "USA"
    }
  }
}

Fields:

Field	Type	Description
`person.first_name`	string	Expected first name
`person.last_name`	string	Expected last name
`person.date_of_birth`	string	Expected date of birth (YYYY-MM-DD)
`address.street`	string	Expected street address
`address.city`	string	Expected city
`address.state`	string	Expected state/province
`address.postal_code`	string	Expected postal/ZIP code
`address.country`	string	Expected country (ISO3 code)
`documents.photo_id.type`	string	Expected photo ID document type name
`documents.photo_id.number`	string	Expected photo ID document number
`documents.photo_id.country`	string	Expected photo ID issuing country (ISO3)
`documents.proof_of_address.type`	string	Expected proof of address document type name
`documents.proof_of_address.number`	string	Expected proof of address document number
`documents.proof_of_address.country`	string	Expected proof of address issuing country (ISO3)

Verification Document

A document uploaded as part of a verification.

json

{
  "id": "doc_xxxxx",
  "url_front": "https://...",
  "url_back": "https://...",
  "status_label": "Approved",
  "verification_id": "ver_xxxxx",
  "document_type": {
    "id": 5,
    "name": "Uniformed Service ID",
    "type_label": "Photo ID"
  },
  "country": {
    "name": "United States of America",
    "iso2": "US",
    "iso3": "USA"
  },
  "created_at": "2026-06-11T02:42:50.000000Z",
  "updated_at": "2026-06-11T02:42:50.000000Z",
  "extracted_data": { ... },
  "decisions": [ ... ],
  "rules": { ... }
}

Fields:

Field	Type	Description
`id`	string	Unique document ID, prefixed with `doc_`
`url_front`	string	Temporary signed S3 URL for the front side image (30-min expiry)
`url_back`	string (nullable)	Temporary signed S3 URL for the back side image (30-min expiry)
`status_label`	string	Human-readable status (e.g. Uploaded, Extracted, Approved, etc.)
`verification_id`	string	ID of the parent verification
`document_type`	object (nullable)	Document type information
`country`	object (nullable)	Country information
`created_at`	string	ISO 8601 upload timestamp
`updated_at`	string	ISO 8601 last update timestamp
`extracted_data`	object (nullable)	extracted data
`decisions`	array	List of decisions
`rules`	object (nullable)	Validation rule results

Extracted Data

json

{
  "person": {
    "surname": "Simpson",
    "full_name": "Simpson Homer",
    "given_names": "Homer",
    "date_of_birth": "1988-07-23"
  },
  "address": {
    "zip": "92026",
    "city": "Springfield",
    "full": "742 Evergreen Terrace, Springfield, Tennessee 92026",
    "state": "Tennessee",
    "street": "742 Evergreen Terrace",
    "country": "USA"
  },
  "document": {
    "type": "Driver License",
    "number": "",
    "has_selfie": "1",
    "identified": "United States of America - Driver License",
    "country_code": "USA",
    "country_name": "United States of America",
    "issuing_entity": "Government",
    "expiration_date": "2028-07-23",
    "selfie_comparison": "99"
  }
}

Person Fields:

Field	Type	Description
`surname`	string	Extracted surname
`full_name`	string	Extracted full name
`given_names`	string	Extracted given names
`date_of_birth`	string	Extracted date of birth

Address Fields:

Field	Type	Description
`zip`	string	Extracted postal/ZIP code
`city`	string	Extracted city
`full`	string	Extracted full address string
`state`	string	Extracted state/province
`street`	string	Extracted street address
`country`	string	Extracted country name

Document Fields:

Field	Type	Description
`type`	string	Extracted document type name
`number`	string	Extracted document number
`has_selfie`	string	Whether a selfie was provided ("1" or "0")
`identified`	string	Identified document description
`country_code`	string	Extracted ISO3 country code
`country_name`	string	Extracted country name
`issuing_entity`	string	Document issuing authority
`expiration_date`	string	Document expiration date
`selfie_comparison`	string	Selfie match percentage (e.g., "99")

Validation Rules

json

{
  "id": "rule_xxxxx",
  "approved_rules": {
    "RulePH001": { "expected": "Homer Simpson", "extracted": "Homer Simpson" },
    "RulePH002": { "expected": "USA", "extracted": "USA" },
    "RulePH003": { "expected": "ID Card", "extracted": "ID Card" },
    "RulePH004": { "expected": "SIMPSON HOMER", "extracted": "Simpson Homer" },
    "RulePH005": { "expected": "AB123456", "extracted": "AB123456" },
    "RulePH006": { "expected": "1988-07-23", "extracted": "1988-07-23" },
    "RulePH007": { "expected": "Same document sides", "extracted": "Same document sides" }
  },
  "failed_rules": {},
  "suggestions": ["The document you uploaded is correct."]
}

Fields:

Field	Type	Description
`id`	string	Unique rule ID, prefixed with `rule_`
`approved_rules`	object	Rules that passed validation, with expected vs extracted values
`failed_rules`	object	Rules that failed validation, with expected vs extracted values
`suggestions`	array	Human-readable suggestions for fixing issues

Document Decision

A decision made on a verification document.

json

{
  "id": "dec_xxxxx",
  "status_label": "Approved",
  "validation_workflow": "Automatic",
  "created_at": "2026-06-11T07:36:42.000000Z",
  "updated_at": "2026-06-11T07:36:42.000000Z"
}

Fields:

Field	Type	Description
`id`	string	Unique decision ID, prefixed with `dec_`
`status_label`	string	Human-readable decision status (e.g. Approved, Rejected, etc.)
`validation_workflow`	string (nullable)	How the decision was made (e.g. "Automatic", "Manual by some@email.com")
`created_at`	string	ISO 8601 decision timestamp
`updated_at`	string	ISO 8601 last update timestamp

Comment

A comment attached to a verification.

json

{
  "content": "Document appears valid after manual review.",
  "status": "Double Check",
  "created_at": "2026-06-11T08:00:00.000000Z"
}

Fields:

Field	Type	Description
`content`	string	Comment text
`status`	string	Verification status label at the time of the comment
`created_at`	string	ISO 8601 comment timestamp

Verification History

A record of a verification status change.

json

{
  "id": "hist_xxxxx",
  "from_status": "Submitted",
  "to_status": "Approved",
  "user": "system",
  "comment": null,
  "created_at": "2026-06-11T07:36:42.000000Z"
}

Fields:

Field	Type	Description
`id`	string	Unique history entry ID, prefixed with `hist_`
`from_status`	string (nullable)	Previous status label (null for initial creation)
`to_status`	string	New status label
`user`	string (nullable)	Who triggered the change (email or "system")
`comment`	string (nullable)	Associated comment
`created_at`	string	ISO 8601 timestamp

Document Type

A type of document that can be uploaded for verification.

json

{
  "id": 5,
  "name": "Uniformed Service ID",
  "type_label": "Photo ID"
}

Fields:

Field	Type	Description
`id`	integer	Document type ID
`name`	string	Document type name
`type_label`	string	Category label

Country

A country reference.

json

{
  "name": "United States of America",
  "iso2": "US",
  "iso3": "USA"
}

Fields:

Field	Type	Description
`name`	string	Full country name
`iso2`	string	ISO 3166-1 alpha-2 code
`iso3`	string	ISO 3166-1 alpha-3 code

Statuses & Enums

Verification Status

Value	Label
1	Started
2	Submitted
3	Approved
4	Rejected
5	Double Check
6	Expired
7	Canceled
8	Hold

Transition lifecycle:

text

Started → Submitted → Approved
                  ↘ Rejected
                  ↘ Double Check ─→ Approved / Rejected
Started ──────────────────────────→ Canceled

Document Status

Value	Label
1	Uploaded
2	In progress
3	Approved
4	Rejected
5	Double check
6	Canceled
7	Extracted

Document Decision Status

Value	Label
0	Pending
1	Approved
2	Rejected
3	Double check
4	Canceled

Document Type Category

Value	Label
1	Photo ID
2	Proof of Address
3	Selfie

Flow Type

Pretty Path	Label
usps1583	USPS 1583
identity	Identity Verification

Webhook Event Codes

Value	Code	Description
1	verification.started	A verification has been started
2	verification.submitted	A verification has been submitted by the end user
3	verification.finished	A verification has been resolved (approved/rejected/expired)
4	verification.canceled	A verification has been canceled
5	document.uploaded	A document has been uploaded
6	document.canceled	A document has been canceled
7	decision.made	A decision has been made on a document
8	decision.canceled	A decision has been canceled

Pagination Meta

json

{
  "current_page": 1,
  "from": 1,
  "last_page": 5,
  "path": "https://{workspace}.colleckt.io/api/v1/usps1583/verifications",
  "per_page": 15,
  "to": 15,
  "total": 72
}

Fields:

Field	Type	Description
`current_page`	integer	Current page number
`from`	integer	Index of the first item on this page
`last_page`	integer	Total number of pages
`path`	string	Base URL for pagination
`per_page`	integer	Items per page
`to`	integer	Index of the last item on this page
`total`	integer	Total number of items

Pagination Links

json

{
  "first": "https://{workspace}.colleckt.io/api/v1/usps1583/verifications?page=1",
  "last": "https://{workspace}.colleckt.io/api/v1/usps1583/verifications?page=5",
  "prev": null,
  "next": "https://{workspace}.colleckt.io/api/v1/usps1583/verifications?page=2"
}

Fields:

Field	Type	Description
`first`	string	URL to the first page
`last`	string	URL to the last page
`prev`	string (nullable)	URL to the previous page
`next`	string (nullable)	URL to the next page

Data Models ​

Verification ​

Expected Data ​

Verification Document ​

Extracted Data ​

Validation Rules ​

Document Decision ​

Comment ​

Verification History ​

Document Type ​

Country ​

Statuses & Enums ​

Verification Status ​

Document Status ​

Document Decision Status ​

Document Type Category ​

Flow Type ​

Webhook Event Codes ​

Pagination Meta ​

Pagination Links ​

Data Models

Verification

Expected Data

Verification Document

Extracted Data

Validation Rules

Document Decision

Comment

Verification History

Document Type

Country

Statuses & Enums

Verification Status

Document Status

Document Decision Status

Document Type Category

Flow Type

Webhook Event Codes

Pagination Meta

Pagination Links