Documentation Index
Fetch the complete documentation index at: https://docs.dataspike.io/llms.txt
Use this file to discover all available pages before exploring further.
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 type | Description |
|---|
KybCertificateOfIncorporation | Certificate of incorporation, articles of association, or similar formation documents |
KybOwnershipDocument | Shareholder 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"}'
{
"id": "01827ed4-c928-7a3c-9a30-7ab7cc169d11"
}
import requests
API_KEY = "<YOUR_API_KEY>"
BASE = "https://api.dataspike.io"
HEADERS = {"ds-api-token": API_KEY, "Content-Type": "application/json"}
resp = requests.post(f"{BASE}/api/v3/applicants", headers=HEADERS, json={"external_id": "company-123"})
applicant_id = resp.json()["id"]
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"
{
"document_id": "019c9c39-0b8a-7aa4-a5c0-abc123def456"
}
with open("certificate_of_incorporation.pdf", "rb") as f:
resp = requests.post(
f"{BASE}/api/v3/upload/{applicant_id}",
headers={"ds-api-token": API_KEY},
files={"file": f},
data={"document_type": "kyb_certificate_of_incorporation"},
)
document_id = resp.json()["document_id"]
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"
}
]
}
}'
{
"request_id": "019c9e79-8f48-73e1-86e3-317a95f43178",
"status": "initial"
}
resp = requests.post(
f"{BASE}/api/v4/kyb/{applicant_id}/verify-document",
headers=HEADERS,
json={
"documents": [
{"doc_path": document_id, "document_type": "KybCertificateOfIncorporation"}
],
"user_provided_data": {
"shareholders": [
{"name": "John Doe", "first_name": "John", "last_name": "Doe", "nationality": "US"}
]
},
},
)
request_id = resp.json()["request_id"]
Request body
| Field | Type | Required | Description |
|---|
documents | array | Yes | List of documents to verify |
documents[].doc_path | string | Yes | Document ID returned from the upload endpoint |
documents[].document_type | string | Yes | One of KybCertificateOfIncorporation, KybOwnershipDocument |
user_provided_data | object | No | Shareholder data to validate against the document |
user_provided_data.shareholders | array | No | List of shareholders to verify |
user_provided_data.shareholders[].name | string | No | Full name |
user_provided_data.shareholders[].first_name | string | No | First name |
user_provided_data.shareholders[].last_name | string | No | Last name |
user_provided_data.shareholders[].nationality | string | No | Country 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"
{
"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"
}
import time
while True:
resp = requests.get(f"{BASE}/api/v4/kyb/result/{request_id}", headers=HEADERS)
result = resp.json()
if result["status"] != "initial":
break
time.sleep(5)
print(result)
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 code | Description |
|---|
SHAREHOLDER_NAME_NOT_FOUND | A provided shareholder name was not found in the document |
SHAREHOLDER_NAME_MISMATCH | A shareholder name was found but does not match the provided data |
SHAREHOLDER_NATIONALITY_MISMATCH | Shareholder nationality does not match |
DOCUMENT_UNREADABLE | The document could not be parsed or read |
DOCUMENT_TYPE_NOT_SUPPORTED | The document type is not supported |
DOCUMENTS_FROM_DIFFERENT_ENTITIES | Multiple documents appear to belong to different companies |
IRRELEVANT_DOCUMENT_PROVIDED | The provided document is not relevant for KYB verification |
