Skip to main content
Verify corporate documents such as certificates of incorporation or shareholder certificates. The API extracts company information and validates shareholder details against user-provided data.

​
Supported document types

Document typeDescription
KybCertificateOfIncorporationCertificate of incorporation, articles of association, or similar formation documents
KybOwnershipDocumentShareholder certificate, ownership registry extract, or similar documents listing beneficial owners

​
Step 1: Create an applicant

Create an applicant to associate the verification with. 
export API_KEY=<YOUR_API_KEY>

curl -H "ds-api-token: $API_KEY" \
  -H "Content-Type: application/json" \
  -X POST "https://api.dataspike.io/api/v3/applicants" \
  --data '{"external_id": "company-123"}'
Response:
{
  "id": "01827ed4-c928-7a3c-9a30-7ab7cc169d11"
}

​
Step 2: Upload a document

Upload the corporate document using the file upload endpoint. Note the returned document_id — you will pass it to the verification request. 
APPLICANT_ID="01827ed4-c928-7a3c-9a30-7ab7cc169d11"

curl -H "ds-api-token: $API_KEY" \
  -X POST "https://api.dataspike.io/api/v3/upload/$APPLICANT_ID" \
  -F "file=@certificate_of_incorporation.pdf" \
  -F "document_type=kyb_certificate_of_incorporation"
Response:
{
  "document_id": "019c9c39-0b8a-7aa4-a5c0-abc123def456"
}

​
Step 3: Submit verification request

Submit the document for KYB verification. Optionally provide shareholder data to validate against extracted information from the document. 
curl -H "ds-api-token: $API_KEY" \
  -H "Content-Type: application/json" \
  -X POST "https://api.dataspike.io/api/v4/kyb/$APPLICANT_ID/verify-document" \
  --data '{
    "documents": [
      {
        "doc_path": "019c9c39-0b8a-7aa4-a5c0-abc123def456",
        "document_type": "KybCertificateOfIncorporation"
      }
    ],
    "user_provided_data": {
      "shareholders": [
        {
          "name": "John Doe",
          "first_name": "John",
          "last_name": "Doe",
          "nationality": "US"
        }
      ]
    }
  }'
Response (HTTP 202):
{
  "request_id": "019c9e79-8f48-73e1-86e3-317a95f43178",
  "status": "initial"
}

​
Request body

FieldTypeRequiredDescription
documentsarrayYesList of documents to verify
documents[].doc_pathstringYesDocument ID returned from the upload endpoint
documents[].document_typestringYesOne of KybCertificateOfIncorporation, KybOwnershipDocument
user_provided_dataobjectNoShareholder data to validate against the document
user_provided_data.shareholdersarrayNoList of shareholders to verify
user_provided_data.shareholders[].namestringNoFull name
user_provided_data.shareholders[].first_namestringNoFirst name
user_provided_data.shareholders[].last_namestringNoLast name
user_provided_data.shareholders[].nationalitystringNoCountry code (e.g. US)

​
Step 4: Poll for the result

The verification takes approximately 15-30 seconds. Poll the result endpoint until the status changes from initial. 
REQUEST_ID="019c9e79-8f48-73e1-86e3-317a95f43178"

curl -H "ds-api-token: $API_KEY" \
  "https://api.dataspike.io/api/v4/kyb/result/$REQUEST_ID"
Example response (verified):
{
  "request_id": "019c9e79-8f48-73e1-86e3-317a95f43178",
  "status": "verified",
  "verification_type": "document_verification",
  "response_data": {
    "result": {
      "status": "VERIFIED",
      "document_results": [
        {
          "status": "VERIFIED",
          "document": {
            "document_type": "KybCertificateOfIncorporation"
          },
          "extracted_shareholders": [
            {
              "name": "John Doe",
              "first_name": "John",
              "last_name": "Doe",
              "country": "US"
            }
          ]
        }
      ],
      "extracted_company_info": {
        "company_name": "Acme Corp.",
        "jurisdiction": "US",
        "address": "123 Main St, Dover, DE 19901"
      }
    }
  },
  "created_at": "2026-02-27T09:41:32.629118Z",
  "completed_at": "2026-02-27T09:42:02.004789Z"
}

​
Verification errors

When a document verification returns not_verified, the response_data.result.document_results[].errors array contains one or more of the following error codes:
Error codeDescription
SHAREHOLDER_NAME_NOT_FOUNDA provided shareholder name was not found in the document
SHAREHOLDER_NAME_MISMATCHA shareholder name was found but does not match the provided data
SHAREHOLDER_NATIONALITY_MISMATCHShareholder nationality does not match
DOCUMENT_UNREADABLEThe document could not be parsed or read
DOCUMENT_TYPE_NOT_SUPPORTEDThe document type is not supported
DOCUMENTS_FROM_DIFFERENT_ENTITIESMultiple documents appear to belong to different companies
IRRELEVANT_DOCUMENT_PROVIDEDThe provided document is not relevant for KYB verification