docufykit.comVerify. Extract. Deliver.
Sign inQuickstart

POST /v1/verifications starts the customer workflow. It creates a verification job in awaiting_upload and returns the direct upload target for the document bytes.

Endpoint

POST https://api.docufykit.com/v1/verifications

Example request

curl -X POST "https://api.docufykit.com/v1/verifications" \
  -H "X-API-Key: <your-api-key>" \
  -H "Idempotency-Key: 4dd2b36b-8f7c-4f8a-8fb5-1f2d27c3c0f1" \
  -H "Content-Type: application/json" \
  -d '{
    "document_type": "YOK_STUDENT",
    "process_type": "async",
    "external_reference_id": "student-12345",
    "original_filename": "belge.pdf",
    "file_size_bytes": 160585,
    "metadata": {
      "customer_user_id": "usr_12345"
    }
  }'

Important request fields

  • document_type: optional today, but recommended when you know the expected schema.
  • process_type: sync or async. The current quickstart defaults to sync when omitted.
  • external_reference_id: your own reconciliation id.
  • original_filename: traceability only.
  • file_size_bytes: declared upload size. The later upload-complete step checks the stored object against this value.
  • metadata: free-form JSON echoed back in results and webhooks.

Example response shape

First-time creation returns 201 Created. If the same app retries with the same Idempotency-Key, the API can return the existing job as 200 OK instead of creating a duplicate.

{
  "verification_id": "ver_123",
  "document_type": "YOK_STUDENT",
  "status": "awaiting_upload",
  "reason_code": "awaiting_upload",
  "process_type": "async",
  "external_reference_id": "student-12345",
  "original_filename": "belge.pdf",
  "file_size_bytes": 160585,
  "message": "upload URL created; upload the file and confirm completion to start processing",
  "upload": {
    "method": "PUT",
    "url": "https://storage.example.com/...",
    "expires_at": "2026-03-07T12:34:56Z"
  }
}

What create does and does not do

At create time the platform:

  • validates the JSON request
  • stores the verification job
  • assigns awaiting_upload plus reason_code=awaiting_upload
  • returns a signed upload target

At create time the platform does not yet:

  • inspect the uploaded bytes
  • know the real content type
  • return a terminal decision
  • produce structured_data

Next pages