Colleckt

Appearance

Verifications API ​

Overview ​

The Verifications API manages identity verification workflows. A verification represents a single identity-check session that collects, extracts, and validates document data against expected values.

The API supports the full lifecycle: create a verification with expected data, upload documents, submit for processing, review results, and take manual action (approve, reject, cancel, resubmit).

Try it live

Create and manage verifications in the Playground → — add your API token to get started.

Status Lifecycle ​

StatusAPI ValueLabelDescription
Started1StartedVerification created, awaiting document upload
Submitted2SubmittedDocuments uploaded, pipeline processing
Approved3ApprovedAll validations passed
Rejected4RejectedValidation failed
Double Check5Double CheckNeeds manual review
Expired6ExpiredVerification timed out
Canceled7CanceledVerification canceled
Hold8HoldVerification paused

The typical flow: Started → Submitted → Approved / Rejected / Double Check.

List Verifications ​

GET /api/v1/{flow}/verifications

Description ​

Retrieve a paginated list of verifications for a flow. Pass an empty string or omit flow to include all flows.

Path Parameters ​

ParameterTypeDescription
flowstringThe flow path name (e.g. usps1583).

Query Parameters ​

ParameterTypeDescription
pageintegerPage number for pagination (default: 1)

Example Request ​

http
GET /api/v1/usps1583/verifications?page=1
Authorization: Bearer {token}
Accept: application/json

Example Response ​

json
{
  "data": [
    {
      "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": {
        "person": {
          "first_name": "Homer",
          "last_name": "Simpson",
          "date_of_birth": ""
        },
        "address": {
          "street": "742 Evergreen Terrace",
          "city": "Springfield",
          "state": "Tennessee",
          "postal_code": "92026",
          "country": "USA"
        },
        "documents": {
          "photo_id": {
            "type": "ID Card",
            "number": "AB123456",
            "country": "USA"
          },
          "proof_of_address": {
            "type": "Driver License",
            "number": "",
            "country": "USA"
          }
        }
      },
      "status_label": "Submitted",
      "submitted_at": "2026-06-11T07:36:11.000000Z",
      "created_at": "2026-06-11T07:04:50.000000Z",
      "updated_at": "2026-06-11T07:36:11.000000Z",
      "flow": "USPS 1583",
      "comments": []
    }
  ],
  "links": {
    "first": "https://{workspace}.colleckt.io/api/v1/usps1583/verifications?page=1",
    "last": "https://{workspace}.colleckt.io/api/v1/usps1583/verifications?page=1",
    "prev": null,
    "next": null
  },
  "meta": {
    "current_page": 1,
    "from": 1,
    "last_page": 1,
    "path": "https://{workspace}.colleckt.io/api/v1/usps1583/verifications",
    "per_page": 15,
    "to": 1,
    "total": 1
  }
}

Possible Errors ​

StatusMeaning
401Missing or invalid authentication
404Flow not found

Create Verification ​

POST /api/v1/{flow}/verifications

Description ​

Start a new verification process. Provide expected person details, address, and document information. The response includes a url (redirect the end-user here) and qr_code (for mobile access) to the verification widget.

Path Parameters ​

ParameterTypeDescription
flowstringThe flow path name (e.g. usps1583)

Request Body ​

ParameterTypeRequiredDescription
vendor_referencestringNoInternal reference for this verification
vendor_statestringNoVendor state information
personobjectConditionalRequired if the flow supports photo ID documents
person.first_namestringConditionalRequired when person is present
person.last_namestringConditionalRequired when person is present
person.date_of_birthstringNoDate of birth in YYYY-MM-DD format
addressobjectConditionalRequired if the flow supports proof of address documents
address.streetstringConditionalRequired when address is present
address.citystringConditionalRequired when address is present
address.statestringConditionalRequired when address.country is USA
address.postal_codestringConditionalRequired when address is present
address.countrystringConditionalRequired when address is present. ISO3 country code (uppercased)
documentsobjectNoDocument expectations
documents.photo_idobjectConditionalRequired if the flow supports photo ID documents
documents.photo_id.typestringConditionalMust be a valid photo ID document type for this flow. Must not be forbidden for the selected country. Must differ from documents.proof_of_address.type
documents.photo_id.numberstringConditionalRequired when documents.photo_id is present
documents.photo_id.countrystringConditionalRequired when documents.photo_id is present. ISO3 code. Must be a valid country for this flow
documents.proof_of_addressobjectConditionalRequired if the flow supports proof of address documents
documents.proof_of_address.typestringConditionalMust be a valid proof of address document type for this flow. Must not be forbidden for the selected country. Must differ from documents.photo_id.type
documents.proof_of_address.numberstringNoDocument number
documents.proof_of_address.countrystringConditionalRequired when documents.proof_of_address is present. ISO3 code. Must be a valid country for this flow

Example Request ​

http
POST /api/v1/usps1583/verifications
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

{
  "vendor_reference": "REF-001",
  "vendor_state": "TN",
  "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"
    }
  }
}

Response (201 Created) ​

json
{
  "data": {
    "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": {
      "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"
        }
      }
    },
    "status_label": "Started",
    "submitted_at": null,
    "created_at": "2026-06-10T20:50:15.000000Z",
    "updated_at": "2026-06-10T20:50:15.000000Z",
    "flow": "USPS 1583",
    "comments": []
  }
}

Possible Errors ​

StatusMeaning
401Missing or invalid authentication
404Flow not found
422Validation error — see response body for details

Business Rules ​

  • The verification is created in Started status
  • Country codes are uppercased automatically (e.g. usa → USA)
  • person and documents.photo_id are required when the flow supports photo ID
  • address and documents.proof_of_address are required when the flow supports proof of address
  • Document types must be valid for the flow, not forbidden for the selected country, and must differ between photo ID and proof of address

Get Verification ​

GET /api/v1/{flow}/verifications/{verification}

Description ​

Retrieve a single verification with all associated data including documents (with temporary signed URLs), extraction results, validation rule evaluations, decisions, non-private comments, and status history.

Path Parameters ​

ParameterTypeDescription
flowstringThe flow path name
verificationstringThe verification ID (e.g. ver_xxxxx)

Example Request ​

http
GET /api/v1/usps1583/verifications/ver_xxxxx
Authorization: Bearer {token}
Accept: application/json

Example Response ​

json
{
  "data": {
    "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": {
      "person": {
        "first_name": "Homer",
        "last_name": "Simpson",
        "date_of_birth": ""
      },
      "address": {
        "street": "742 Evergreen Terrace",
        "city": "Springfield",
        "state": "Tennessee",
        "postal_code": "92026",
        "country": "USA"
      },
      "documents": {
        "photo_id": {
          "type": "ID Card",
          "number": "AB123456",
          "country": "USA"
        },
        "proof_of_address": {
          "type": "Driver License",
          "number": "",
          "country": "USA"
        }
      }
    },
    "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": [
      {
        "id": "doc_xxxxx",
        "url_front": "https://...",
        "url_back": "https://...",
        "status_label": "Approved",
        "verification_id": "ver_xxxxx",
        "document_type": {
          "id": 2,
          "name": "Driver License",
          "type_label": "Proof of Address"
        },
        "country": {
          "name": "United States of America",
          "iso2": "US",
          "iso3": "USA"
        },
        "created_at": "2026-06-11T07:05:01.000000Z",
        "updated_at": "2026-06-11T07:36:42.000000Z",
        "extracted_data": { },
        "decisions": [],
        "rules": null
      }
    ],
    "comments": [],
    "history": [
      {
        "id": "hist_xxxxx",
        "from_status": "Submitted",
        "to_status": "Approved",
        "user": "system",
        "comment": null,
        "created_at": "2026-06-11T07:36:42.000000Z"
      },
      {
        "id": "hist_xxxxx",
        "from_status": "Started",
        "to_status": "Submitted",
        "user": "some@email.com",
        "comment": null,
        "created_at": "2026-06-11T07:36:11.000000Z"
      },
      {
        "id": "hist_xxxxx",
        "from_status": null,
        "to_status": "Started",
        "user": "some@email.com",
        "comment": null,
        "created_at": "2026-06-11T07:04:50.000000Z"
      }
    ]
  }
}

Possible Errors ​

StatusMeaning
400Verification does not belong to the specified flow
401Missing or invalid authentication
404Verification not found

Business Rules ​

  • The verification must belong to the specified flow
  • Document image URLs are temporary signed URLs (30-minute expiry)
  • Document images are not embedded — use url_front and url_back to access images
  • Extracted data, decisions, and rules are only available after processing
  • The expected_data field reflects the initial expected values (not extracted results)

Update Verification ​

PATCH /api/v1/{flow}/verifications/{verification}

Description ​

Update an existing verification's expected data. All fields are optional — only provided fields are merged into existing data. Omitted fields retain their current values.

You can also change the verification's status by providing status, comment, and email. When changing status to DOUBLE_CHECK (5), the validation pipeline is re-triggered.

Path Parameters ​

ParameterTypeDescription
flowstringThe flow path name
verificationstringThe verification ID

Request Body ​

ParameterTypeRequiredDescription
vendor_referencestringNoInternal reference
vendor_statestringNoVendor state information
statusintegerNoNew verification status (1–8). See Status Lifecycle
commentstringConditionalRequired when status is provided
emailstringConditionalRequired when status is provided. Must be valid email
personobjectNoPartial person fields — only provided keys are updated
person.first_namestringNo
person.last_namestringNo
person.date_of_birthstringNo
addressobjectNoPartial address fields
address.streetstringNo
address.citystringNo
address.statestringConditionalRequired when address.country is USA
address.postal_codestringNo
address.countrystringNoISO3 code
documentsobjectNoDocument configuration
documents.photo_idobjectNoPhoto ID document expectations
documents.photo_id.typestringNoMust be valid for this flow, not forbidden, and differ from proof_of_address.type
documents.photo_id.numberstringConditionalRequired when documents.photo_id.type is present
documents.photo_id.countrystringConditionalRequired when documents.photo_id.type is present. ISO3 code
documents.proof_of_addressobjectNoProof of address document expectations
documents.proof_of_address.typestringNoMust be valid for this flow, not forbidden, and differ from photo_id.type
documents.proof_of_address.numberstringNo
documents.proof_of_address.countrystringConditionalRequired when documents.proof_of_address.type is present. ISO3 code

Example Request ​

http
PATCH /api/v1/usps1583/verifications/ver_xxxxx
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

{
  "vendor_reference": "REF-002",
  "person": {
    "first_name": "Homer J.",
    "last_name": "Simpson",
    "date_of_birth": "1988-05-06"
  }
}

Example Response ​

json
{
  "data": {
    "id": "ver_xxxxx",
    "url": "https://{workspace}.colleckt.io/spa/v3/.../process",
    "qr_code": "https://{workspace}.colleckt.io/qr/...",
    "vendor_reference": "REF-002",
    "vendor_state": "TN",
    "expected_data": {
      "person": {
        "first_name": "Homer J.",
        "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": "ID Card",
          "number": "AB123456",
          "country": "USA"
        },
        "proof_of_address": {
          "type": "Driver License",
          "number": "",
          "country": "USA"
        }
      }
    },
    "status_label": "Started",
    "submitted_at": null,
    "created_at": "2026-06-10T20:50:15.000000Z",
    "updated_at": "2026-06-11T02:02:40.000000Z",
    "flow": "USPS 1583",
    "comments": []
  }
}

Possible Errors ​

StatusMeaning
400Verification does not belong to specified flow or is canceled
401Missing or invalid authentication
404Verification not found
422Validation error

Business Rules ​

  • Only provided fields are updated — missing fields retain their previous values
  • Country codes are uppercased automatically
  • The verification must not be canceled
  • When status is set to DOUBLE_CHECK, the validation pipeline is re-triggered for all uploaded documents

Delete Verification ​

DELETE /api/v1/{flow}/verifications/{verification}

Description ​

Permanently delete a verification and its associated documents.

Path Parameters ​

ParameterTypeDescription
flowstringThe flow path name
verificationstringThe verification ID

Example Request ​

http
DELETE /api/v1/usps1583/verifications/ver_xxxxx
Authorization: Bearer {token}
Accept: application/json

Response (204 No Content) ​

No response body.

Possible Errors ​

StatusMeaning
400Verification does not belong to the specified flow
401Missing or invalid authentication
404Verification not found

Business Rules ​

  • Verifications can be deleted in any status
  • Consider canceling instead of deleting if you need to preserve the record

Submit Verification ​

PUT /api/v1/{flow}/verifications/{verification}/submit

Description ​

Submit a verification for processing. Transitions the verification from Started to Submitted and triggers document extraction and validation.

Path Parameters ​

ParameterTypeDescription
flowstringThe flow path name
verificationstringThe verification ID

Example Request ​

http
PUT /api/v1/usps1583/verifications/ver_xxxxx/submit
Authorization: Bearer {token}
Accept: application/json

Example Response ​

json
{
  "data": {
    "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": {
      "person": {
        "first_name": "Homer",
        "last_name": "Simpson",
        "date_of_birth": ""
      },
      "address": {
        "street": "742 Evergreen Terrace",
        "city": "Springfield",
        "state": "Tennessee",
        "postal_code": "92026",
        "country": "USA"
      },
      "documents": {
        "photo_id": {
          "type": "ID Card",
          "number": "AB123456",
          "country": "USA"
        },
        "proof_of_address": {
          "type": "Driver License",
          "number": "",
          "country": "USA"
        }
      }
    },
    "status_label": "Submitted",
    "submitted_at": "2026-06-11T07:36:11.000000Z",
    "created_at": "2026-06-11T07:04:50.000000Z",
    "updated_at": "2026-06-11T07:36:11.000000Z",
    "flow": "USPS 1583",
    "comments": []
  }
}

Possible Errors ​

StatusMeaning
400Verification does not belong to the specified flow
400Verification is not in Started status
400Not all required documents have been uploaded
401Missing or invalid authentication
404Verification not found

Business Rules ​

  • All required documents must be uploaded before submission
  • Once submitted, documents cannot be modified or replaced (use resubmit)
  • Status changes from Started to Submitted
  • Submission triggers the automated extraction and validation pipeline

Resubmit Verification ​

PUT /api/v1/{flow}/verifications/{verification}/resubmit

Description ​

Resubmit a verification for reprocessing. Resets all document statuses to Uploaded, clears prior extracted data and validation rules, and re-triggers the full pipeline.

Path Parameters ​

ParameterTypeDescription
flowstringThe flow path name
verificationstringThe verification ID

Request Body ​

ParameterTypeRequiredDescription
commentstringYesReason for resubmission
emailstringYesEmail of the user performing the action

Example Request ​

http
PUT /api/v1/usps1583/verifications/ver_xxxxx/resubmit
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

{
  "comment": "Re-uploaded documents with better quality.",
  "email": "some@email.com"
}

Example Response ​

json
{
  "data": {
    "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": {
      "person": {
        "first_name": "Homer",
        "last_name": "Simpson",
        "date_of_birth": ""
      },
      "address": {
        "street": "742 Evergreen Terrace",
        "city": "Springfield",
        "state": "Tennessee",
        "postal_code": "92026",
        "country": "USA"
      },
      "documents": {
        "photo_id": {
          "type": "ID Card",
          "number": "AB123456",
          "country": "USA"
        },
        "proof_of_address": {
          "type": "Driver License",
          "number": "",
          "country": "USA"
        }
      }
    },
    "status_label": "Submitted",
    "submitted_at": "2026-06-11T08:00:00.000000Z",
    "created_at": "2026-06-11T07:04:50.000000Z",
    "updated_at": "2026-06-11T08:00:00.000000Z",
    "flow": "USPS 1583",
    "comments": []
  }
}

Possible Errors ​

StatusMeaning
400Verification does not belong to the specified flow
400The verification is canceled
400Not all required documents have been uploaded
401Missing or invalid authentication
404Verification not found
422Validation error (missing comment or email)

Business Rules ​

  • The verification must not be canceled
  • All required documents must be uploaded before resubmission
  • Document statuses are reset to Uploaded, clearing prior extraction and rules
  • Pipeline is re-triggered after resubmission

Approve Verification ​

PUT /api/v1/{flow}/verifications/{verification}/approve

Description ​

Manually approve a verification. Transitions to Approved, marks all documents as Approved, and triggers webhooks.

Path Parameters ​

ParameterTypeDescription
flowstringThe flow path name
verificationstringThe verification ID

Request Body ​

ParameterTypeRequiredDescription
commentstringYesReason for approval
emailstringYesEmail of the approving user

Example Request ​

http
PUT /api/v1/usps1583/verifications/ver_xxxxx/approve
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

{
  "comment": "ID documents match the provided information.",
  "email": "some@email.com"
}

Example Response ​

json
{
  "data": {
    "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",
    "status_label": "Approved",
    "flow": "USPS 1583",
    "documents": [],
    "comments": [
      {
        "content": "ID documents match the provided information.",
        "status": "Approved",
        "created_at": "2026-06-11T07:36:42.000000Z"
      }
    ]
  }
}

Possible Errors ​

StatusMeaning
400Verification does not belong to the specified flow
400The verification is canceled
400The verification is already approved
401Missing or invalid authentication
404Verification not found
422Validation error (missing comment or email)

Business Rules ​

  • The verification must not be canceled or already approved
  • Sets the verification status to Approved
  • Marks all documents as Approved with a manual decision
  • Triggers the VerificationFinished event and associated webhooks

Reject Verification ​

PUT /api/v1/{flow}/verifications/{verification}/reject

Description ​

Manually reject a verification. Transitions to Rejected, marks all documents as Rejected, and triggers webhooks.

Path Parameters ​

ParameterTypeDescription
flowstringThe flow path name
verificationstringThe verification ID

Request Body ​

ParameterTypeRequiredDescription
commentstringYesReason for rejection
emailstringYesEmail of the rejecting user

Example Request ​

http
PUT /api/v1/usps1583/verifications/ver_xxxxx/reject
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

{
  "comment": "ID does not match the provided information.",
  "email": "some@email.com"
}

Example Response ​

json
{
  "data": {
    "id": "ver_xxxxx",
    "status_label": "Rejected",
    "flow": "USPS 1583",
    "comments": [
      {
        "content": "ID does not match the provided information.",
        "status": "Rejected",
        "created_at": "2026-06-11T07:36:42.000000Z"
      }
    ]
  }
}

Possible Errors ​

StatusMeaning
400Verification does not belong to the specified flow
400The verification is canceled
400The verification is already rejected
401Missing or invalid authentication
404Verification not found
422Validation error (missing comment or email)

Business Rules ​

  • The verification must not be canceled or already rejected
  • Sets the verification status to Rejected
  • Marks all documents as Rejected with a manual decision
  • Triggers the VerificationFinished event and associated webhooks

Cancel Verification ​

PUT /api/v1/{flow}/verifications/{verification}/cancel

Description ​

Cancel a verification. Transitions to Canceled, marks all documents as Canceled, and triggers webhooks. Canceled verifications cannot be processed further.

Path Parameters ​

ParameterTypeDescription
flowstringThe flow path name
verificationstringThe verification ID

Request Body ​

ParameterTypeRequiredDescription
commentstringYesReason for cancellation
emailstringYesEmail of the canceling user

Example Request ​

http
PUT /api/v1/usps1583/verifications/ver_xxxxx/cancel
Authorization: Bearer {token}
Content-Type: application/json
Accept: application/json

{
  "comment": "Canceling verification due to duplicate entry.",
  "email": "some@email.com"
}

Example Response ​

json
{
  "data": {
    "id": "ver_xxxxx",
    "status_label": "Canceled",
    "flow": "USPS 1583",
    "comments": [
      {
        "content": "Canceling verification due to duplicate entry.",
        "status": "Canceled",
        "created_at": "2026-06-11T17:16:06.000000Z"
      }
    ]
  }
}

Possible Errors ​

StatusMeaning
400Verification does not belong to the specified flow
400The verification is already canceled
401Missing or invalid authentication
404Verification not found
422Validation error (missing comment or email)

Business Rules ​

  • Sets the verification status to Canceled
  • Marks all documents as Canceled
  • Triggers the VerificationCanceled event and associated webhooks
  • Canceled verifications cannot be resumed, resubmitted, or processed further

Business Rules Summary ​

  • Document types must be valid for the flow, not forbidden for the selected country, and must differ between photo ID and proof of address
  • Country codes are ISO3 format
  • The verification status lifecycle is: Started → Submitted → processing → Approved / Rejected / Double Check
  • Canceled verifications cannot be modified, submitted, resubmitted, approved, or rejected
  • Document images are accessed via temporary signed URLs (30-minute expiry)
  • All action endpoints (approve, reject, cancel, resubmit) require both comment and email for audit trail
  • Updating status via PATCH triggers additional behavior (e.g., re-running validation for DOUBLE_CHECK)

Notes ​

  • Soft deletes are used for verifications — records are not immediately removed from storage
  • For document upload, use the dedicated Documents API endpoints

Built for virtual address providers requiring USPS 1583 compliance.

Copyright © 2023 - 2026 Colleckt. All rights reserved.