Get Started

Before running a validation checklist, create a case and share data by uploading one or more documents and / or by creating one or more open banking connections.

Create a Case

Create a case using the create case endpoint. A case can optionally contain people. You can share data and run a Validation Checklist at the case or person or document level.

Upload Documents

Upload documents using the upload document endpoint. Ensure the entity_id and entity_type are specified in the request.

Payslips

Payslips must meet the following criteria:

Documents must be unaltered and unencrypted.
Documents should have a good resolution. If they are scanned or are an image then the image should not be blurry and all text must be clear.

When a payslip has been uploaded and we have attempted to extract the data from it we will try to send a PayslipProcessing.Completed webhook if one has been configured in our API. For full details, please see the Payslip Processing Completed Webhook section.

Bank Statements

Bank statements must meet the following criteria:

Statements must be from a supported UK bank. You can find a list of supported banks here.
Statements must be in PDF format, base64 encoded.
Statements must be downloaded directly from the official bank website or mobile application. Photos or scanned copies are not supported.
Statements must be unaltered and unencrypted.
Statements must be for a joint or individual bank account or credit card. Mortgage statements and loan statements are not supported.

⚠️
Safari, Firefox and Edge browsers may alter the documents if viewed in the browser and then saved, either directly or via a “print to pdf” function.

When a bank statement has been uploaded and we have attempted to extract the data from it we will try to send a BankStatementProcessing.Completed webhook if one has been configured in our API. For full details, please see the Bank Statement Processing Completed Webhook section.

Create an Open Banking Connection

As an alternative to uploading bank statements, connect a bank account for a UK bank using open banking by utilising the relevant open banking connection endpoint.

You can find more information on the types of connected accounts that can be used to generate an affordability insights here.

When an open banking connection has been completed we will try to send a OpenBankingProcessing.Completed webhook if one has been configured in our API. For full details, please see the Open Banking Processing Completed Webhook section.

Review Data Sources

If you're not using webhooks or if you want to view all the data sources which have been provided for a given entity, you can also verify the processing status for all documents and open banking connections using our data sources endpoint.

Learn more about data sources here.

Data Sources with a Provided Failed, or Pending statuses cannot be used to run validation checklists.

Run Validation Checklist

Once you've created a case and successfully uploaded the relevant documents or created the relevant open banking connections, you can run a Validation Checklist using the POST Validation Check endpoint.

{
  "validation_type_id": "a072e37a-dee1-4a4e-b098-168a6a1f4603",
  "validation_check_version": 1,
  "entity_id": "3f615611-3dc3-418b-bed5-a53c4390c97c",
  "entity_type": "Case",
  "checklist_params": [
    {
      "source_id": "5c8a9d27-fa27-4e15-aefd-9b5a5e32f4c1",
      "source_category_type": "document"
    }
  ]
}

When making the request, the following input parameters are required:

validation_type_id: This is the unique ID for the validation checklist that you want to run. you can retrieve a list of all available validation checklists via the list all validation checklists endpoint.
entity_type: This indicates if the entity you want to run the checklist on is a case, a company, or a person.
entity_id: This is the unique case_id, person_id, or company_id for the entity you want to run the checklist on.

To run the checklist against a specific data source associated with an entity (e.g. a single document):

Use the check_params filter and provide the the following information of the data source you want to run the checklist against
- source_category_type: This can be either Document or OpenBankingConnection.
- source_id: This is the document ID for files like payslips or a bank connection ID for successful open banking connections and processed bank statements. You can find a list of all bank connection IDs under an entity by using this endpoint here.

{
  "validation_instance_id": "2ef5079a-b3de-44a5-b4ff-c534259e752c",
  "validation_type_id": "a072e37a-dee1-4a4e-b098-168a6a1f4603",
  "status": "Pending",
  "entity_id": "b3f6ed8f-bc57-4a23-801e-e744aecb7b03",
  "entity_type": "case",
  "checklist_params": [
    {
      "source_id": "5c8a9d27-fa27-4e15-aefd-9b5a5e32f4c1",
      "source_category_type": "document"
    }
  ],
  "datetime_requested": "2024-01-01T12:38:45.711Z",
  "datetime_completed": null,
  "message": "Validation Check request pending"
}

Record the validation_instance_id from the response as it will be required to retrieve the results

Retrieve Validation Checklist Results

Once you've run a Validation Checklist verification and the status of your request is complete, you can retrieve the results.

The results include an overview the overall status or result of the checklist along with a result of each of the individual rules within the checklist.

Use the GET Validation Checklist endpoint and ensure the relevant validation_instance_id is specified in the URL.

{
  "validation_instance_id": "2ef5079a-b3de-44a5-b4ff-c534259e752c",
  "validation_type_id": "a072e37a-dee1-4a4e-b098-168a6a1f4603",
  "validation_check_name": "Last 3 months of payslips",
  "validation_check_version": "1",
  "status": "Complete",
  "entity_id": "b3f6ed8f-bc57-4a23-801e-e744aecb7b03",
  "entity_type": "case",
  "checklist_params": [
    {
      "source_id": "5c8a9d27-fa27-4e15-aefd-9b5a5e32f4c1",
      "source_id_type": "document"
    }
  ],
  "datetime_requested": "2024-01-01T12:38:45.711Z",
  "datetime_completed": "2024-01-02T12:22:07.747Z",
  "message": "Validation Check request pending",
  "rules": [
    {
      "rule_name": "If the last 3 months of payslips have been provided",
      "decision": "Pass",
      "message": "Validation Check Passed",
      "sources": [
        {
          "source_id": "6f6b61c2-fe31-42be-b46c-20a0b9685aaf",
          "source_type": "Document",
          "source_uri": "https://api.sikoia.com/v2/documents/6f6b61c2-fe31-42be-b46c-20a0b9685aaf"
        }
      ]
    }
  ]
}