Validot API Documentation

Integrate our company verification service into your application with our user-friendly API.

API Overview

The Validot API provides programmatic access to our company verification and data platform. With our API, you can:

Request and manage company verifications
Access verified company profiles and information
Monitor verification status and updates

Coming Soon

Our API is currently private beta and available by invitation only. Please contact us if you'd like to be notified when it becomes generally available or to discuss your integration needs.

Base URL & Authentication

BASE URL: https://api.validot.com/v1

All API requests require authentication via API keys. API keys will be available from your Validot dashboard.

Authorization: Bearer YOUR_API_KEY

Rate Limiting

The API is rate limited to ensure fair usage. Rate limits vary by subscription tier.

Plan	Rate Limit
Basic	100 requests/minute
Professional	500 requests/minute
Enterprise	2000 requests/minute

Response Format

All API responses are returned in JSON format and include standardized HTTP status codes.

// Success Response
{
  "data": {
    // Resource data here
  },
  "meta": {
    // Pagination, version info, etc.
  }
}

// Error Response
{
  "error": {
    "code": "error_code",
    "message": "Human-readable error message",
    "details": [
      // Additional error details when available
    ]
  }
}

Verification Endpoints

The verification endpoints allow you to request, monitor, and manage company verifications through our platform.

GET /verifications

List Verifications

Retrieve a paginated list of verification requests associated with your organization.

Query Parameters:

Name	Type	Description
page	integer	Page number (default: 1)
per_page	integer	Results per page (default: 20, max: 100)
status	string	Filter by status (pending, in_progress, completed, canceled, more_info)
country	string	Filter by country code (e.g., TR, MY, ID)
type	string	Filter by verification type (basic, premium)

Example Response:

{
  "data": [
    {
      "id": "VER-349671",
      "company_name": "New Textile Company",
      "company_country": {
        "code": "ID",
        "name": "Indonesia"
      },
      "verification_type": "basic",
      "status": "in_progress",
      "created_at": "2023-10-15T08:12:33Z",
      "updated_at": "2023-10-16T14:23:10Z"
    },
    {
      "id": "VER-567234",
      "company_name": "Global Manufacturing Ltd",
      "company_country": {
        "code": "MY",
        "name": "Malaysia"
      },
      "verification_type": "premium",
      "status": "completed",
      "created_at": "2023-09-22T11:45:17Z",
      "updated_at": "2023-10-01T09:32:08Z"
    }
  ],
  "meta": {
    "current_page": 1,
    "total_pages": 3,
    "total_count": 45,
    "per_page": 20
  }
}

GET /verifications/{verification_id}

Get Verification Details

Retrieve detailed information about a specific verification request.

Path Parameters:

Name	Type	Description
verification_id	string	The unique identifier of the verification

Example Response:

{
  "data": {
    "id": "VER-349671",
    "company_name": "New Textile Company",
    "company_website": "https://newtextile.com",
    "company_city": "Jakarta",
    "company_country": {
      "code": "ID",
      "name": "Indonesia"
    },
    "company_email": "contact@newtextile.com",
    "status": "in_progress",
    "verification_type": "basic",
    "feedback": "We are currently verifying the company registration documents.",
    "current_stage": "documentation_review",
    "completion_percentage": 45,
    "estimated_completion_date": "2023-10-25T00:00:00Z",
    "created_at": "2023-10-15T08:12:33Z",
    "updated_at": "2023-10-16T14:23:10Z",
    "results": {
      "legal_name_verified": true,
      "address_verified": "pending",
      "registration_verified": "pending",
      "management_verified": "pending",
      "tax_verified": "pending"
    },
    "template": {
      "id": "TPL-001",
      "name": "Standard Indonesia Verification",
      "country": "ID"
    }
  }
}

POST /verifications

Create Verification

Request a new company verification.

Request Body:

{
  "company_name": "New Textile Company",
  "company_website": "https://newtextile.com",
  "company_city": "Jakarta",
  "company_country_code": "ID", 
  "company_email": "contact@newtextile.com",
  "verification_type": "basic",
  "template_id": "TPL-001",
  "request_details": "We are looking to partner with this company and need to verify their business.",
  "priority": "standard",
  "contact_person": {
    "name": "John Smith",
    "email": "john@yourcompany.com",
    "phone": "+1234567890"
  }
}

Example Response:

{
  "data": {
    "id": "VER-349671",
    "company_name": "New Textile Company",
    "company_country": {
      "code": "ID",
      "name": "Indonesia"
    },
    "verification_type": "basic",
    "status": "pending",
    "template": {
      "id": "TPL-001",
      "name": "Standard Indonesia Verification"
    },
    "estimated_completion_date": "2023-10-30T00:00:00Z",
    "created_at": "2023-10-15T08:12:33Z",
    "updated_at": "2023-10-15T08:12:33Z"
  }
}

PATCH /verifications/{verification_id}

Update Verification

Update details of an existing verification or provide additional information requested.

Path Parameters:

Name	Type	Description
verification_id	string	The unique identifier of the verification

Request Body:

{
  "additional_information": "Here is the business registration document that was requested.",
  "documents": [
    {
      "type": "business_registration",
      "file": "base64_encoded_file_data",
      "filename": "registration_cert.pdf",
      "description": "Business registration certificate from Ministry of Trade"
    }
  ],
  "contact_person": {
    "name": "Sarah Johnson",
    "email": "sarah@yourcompany.com",
    "phone": "+1987654321"
  }
}

Example Response:

{
  "data": {
    "id": "VER-349671",
    "status": "in_progress",
    "updated_at": "2023-10-17T10:22:43Z",
    "message": "Additional information received and being processed."
  }
}

POST /verifications/{verification_id}/cancel

Cancel Verification

Cancel an ongoing verification request.

Path Parameters:

Name	Type	Description
verification_id	string	The unique identifier of the verification

Request Body:

{
  "reason": "No longer needed",
  "comments": "We've decided to pursue a different partnership."
}

Example Response:

{
  "data": {
    "id": "VER-349671",
    "status": "canceled",
    "canceled_at": "2023-10-18T15:30:22Z",
    "message": "Verification successfully canceled."
  }
}

Want API Access?

Our API is currently invite-only. Contact our team to discuss your integration needs and get early access to the Validot API.