Overview

Document verification performed via the API includes the following steps:

1. Create case (and conversation).
2. Process one or more documents:
   1. Run document verification.
   2. Submit comments on the issues found (will be present in the report).
3. Mark conversation as finished - this will generate a report.
4. Download report (and, if needed, documents).
5. If needed, create follow-up conversation and repeat from step 2.

Authentication

All API calls described in this guide use HTTP Basic Authentication, so all requests shall include an Authorization header with appropriate service credentials.

Integration Scheme

1. Create Case and Conversation

Onboarding of each new client is tracked within an entity called "case".

Each case contains one or more "conversations". Each conversation is the process where we collect some information about the client (e.g. validate a set of documents) and generate a report in the end. There may be more than one conversation within the case - for example, if a manager decides that additional information about the client shall be requested and/or checked after the initial phase was fully completed.

To start the onboarding flow, you shall create the case and the conversation and keep their IDs for future reference.

Send POST api/v1/cases with:

• application/json payload specifying:
  • onboarding case kind
  • company data (name, reg number, etc.)
  • documents_verification module

Example payload:

{
  "communication_id": "...",
  "case": {
    "case_kind": "onboarding",
    "company_country_code": "NL",
    "company_full_name": "...",
    "company_reg_number": "...",
    "user_full_name": "...",
    "company_industry_classification": [
      {
        "classification": "UKSIC2007", 
        "code": "30990"
      }
    ],
    "modules": [
      {"module": "documents_verification"}
    ]
  },
  "invitation_email_recipients": [
    "[email protected]"
  ],
  "case_manager": {
    "name": "Alice Smith",
    "email": "[email protected]"
  }
}

The result will contain IDs of the case and the conversation:

{
  "result": "case_created",
  "case_id": "...",
  "conversation_id": "..."  
}

See https://docs.intrepidfox.tech/reference/create_case_api_v1_cases_post

2. Run Document Verification

The document verification includes the following steps:

1. Upload document file and save returned document ID.
2. Run verification task for the uploaded document.
3. Wait until verification result is ready (poll the endpoint).

2.1. Upload Document

Send POST /api/v1/conversations/{conversation_id}/documents with:

• conversation_id parameter - obtained when creating case/conversation
• multipart/form-data payload with:
• file part with the document file

The result will contain ID of the uploaded document:

{
  "document_id": "..."
}

See https://docs.intrepidfox.tech/reference/upload_document_api_v1_conversations__conversation_id__documents_post

2.2. Run Verification

Send POST /api/v1/conversations/{conversation_id}/verifications with:

• conversation_id parameter - obtained when creating case/conversation
• application/json payload specifying:
  • document_id - ID of the uploaded document
  • details of the verification task

Example payload:

{
  "document_id": "...",
  "verification_task": {
    "document_type": "certificate_of_incorporation",
    "company_full_name": "..."
  }
}

The result will contain ID of the started verification task:

{
  "verification_id": "..."
}

See https://docs.intrepidfox.tech/reference/run_verification_api_v1_conversations__conversation_id__verifications_post

2.3. Get Verification Result

Run GET /api/v1/conversations/{conversation_id}/verifications/{verification_id} with:

• conversation_id parameter - obtained when creating case/conversation
• verification_id parameter - ID of the verification task

The result will contain information about the status of the task and the task result (when completed).

{
  "status": "not_ready"
}

You shall poll this endpoint until you get ready status. Response will contain document check results:

{
  "status": "ready",
  "result": {
    "check_results": [
      {
        "issue_id": "...",
        "severity": "warning",
        "text": "The name of the company in the document (...) does not match ..."
      }
    ]
  }
}

See https://docs.intrepidfox.tech/reference/get_verification_results_api_v1_conversations__conversation_id__verifications__verification_id__get

3. Submit Comments

Send POST /api/v1/conversations/{conversation_id}/comments with:

• conversation_id parameter - obtained when creating case/conversation
• application/json payload with comments on one or more issues (referenced by IDs)

Example payload:

[
  {
    "issue_id": "...",
    "comment_text": "this is the parent company name"
  },
  {
    "issue_id": "...",
    "comment_text": "we will upload new documents ASAP"
  }
]

See https://docs.intrepidfox.tech/reference/comment_on_issue_api_v1_conversations__conversation_id__comments_post

4. Finish Conversation

Send POST /api/v1/conversations/{conversation_id}/status with:

• conversation_id parameter - obtained when creating case/conversation
• application/json payload with string "completed" (the only allowed transition at the moment)

See https://docs.intrepidfox.tech/reference/update_conversation_status_api_v1_conversations__conversation_id__status_post

5. Access Report

After the conversation is finished, we prepare conversation results (including the report). To access these results, run GET /api/v1/conversations/{conversation_id}/result passing conversation_id of the finished conversation.

In some cases the report generation may take some time and until the report is ready, the following will be returned:

{
  "status": "not_ready"
}

When the report is ready, the following will be returned:

{
  "status": "ready",
  "result": {
    "web_report_link": "...",
    "client_documents": [
      {
        "document_id": "...",
        "document_type": "...",
        "document_name": "...",
        "rejected": false,
        "file_name": "Invoice_Supplier.pdf",
        "download_link": "..."
      },
      ...
    ]
  }
}

See https://docs.intrepidfox.tech/reference/get_conversation_result_api_v1_conversations__conversation_id__result_get