Vista™ Database
    v6.10.5

    VistaConnect API Documentation — Match, Enrich & Access UK B2B Data

    The UK's most comprehensive B2B database. Match company names to verified records, enrich with 50+ data points, and access 6.8M+ professional contacts including 2.5M senior decision makers.

    4.8M+ SitesUK business locations
    6.8M+ ContactsProfessional contacts
    2M SDMsSenior decision makers
    ~40msAverage response time

    Production URL

    https://vistaapi.datahq.co.uk
    HTTPS only
    JSON responses
    REST API

    Authentication

    All requests require an API key in the header:

    X-API-Key: your-api-key-here

    Example cURL Request

    curl -X POST "https://vistaapi.datahq.co.uk/api/v1/match" \
  -H "X-API-Key: your-api-key-here" \
  -H "Content-Type: application/json" \
  -d '{"company_name": "Data HQ Ltd"}'

    Authentication Errors

    401
    Missing or invalid API key
    403
    API key is inactive or disabled

    Your API key is available on your dashboard. Contact helpdesk@datahq.co.uk if you need assistance.

    Rate Limits & Quotas

    EndpointLimitWindow
    /api/v1/search
    60 requests
    		Per minute
    /api/v1/match
    120 requests
    		Per minute
    /api/v1/match/bulk
    30 requests
    		Per minute
    /api/v1/match/export
    120 requests
    		Per minute
    /api/v1/enrich/{site_urn}
    120 requests
    		Per minute
    /api/v1/enrich/{site_urn}/contacts
    120 requests
    		Per minute
    /api/v1/screen
    120 requests
    		Per minute
    /api/v1/screen/bulk
    30 requests
    		Per minute

    Rate Limit Headers

    Returned in every response:

    X-RateLimit-Limit: 120
X-RateLimit-Remaining: 118
X-RateLimit-Reset: 1702291200

    429 Response Example

    {
  "detail": "Rate limit exceeded. Please retry after 60 seconds."
}

    Credit Usage: /search is free./match costs 1 credit per successful match (free if no match found)./enrich costs 4 credits./contacts costs 5-10 credits per contact. All endpoints are rate limited.

    API Endpoints

    Seven endpoints for searching, matching, bulk processing, exporting, enrichment, contacts, and company screening

    GET
    /api/v1/search
    Free
    v6.2.1

    Simple fuzzy company name search. Returns similarity-ranked results with Site_URN for enrichment lookup.

    Query Parameters

    ParameterTypeRequiredDescription
    q
    string
    Yes
    		Company name to search for (min 2 characters)
    limit
    integer
    No
    		Maximum results to return (1-50, default: 10)

    Example Request

    GET /api/v1/search?q=Microsoft&limit=5

    Response Schema

    interface SearchResponse {
  query: string;           // Original search query
  total_results: number;   // Number of results returned
  results: SearchResult[];
}

interface SearchResult {
  site_urn: string;        // Unique ID for enrichment
  company_name: string;    // Official registered name
  town: string | null;     // Town/city location
  postcode: string | null; // Postal code
  similarity: number;      // Name similarity score (0-1)
}

    Example Response

    {
  "query": "Microsoft",
  "total_results": 5,
  "results": [
    {
      "site_urn": "123456",
      "company_name": "Microsoft Limited",
      "town": "READING",
      "postcode": "RG1 1WG",
      "similarity": 0.923
    },
    {
      "site_urn": "789012",
      "company_name": "Microsoft Research Ltd",
      "town": "CAMBRIDGE",
      "postcode": "CB1 2FB",
      "similarity": 0.756
    }
  ]
}

    When to use Search vs Match:

    • Search: Simple name lookup when you only have a company name
    • Match: Higher confidence matching with address verification

    Error Responses

    Standard HTTP error codes returned by the API

    CodeError TypeDescriptionResolution
    400
    		Bad RequestInvalid request format or validation errorCheck request schema and field constraints
    401
    		UnauthorisedMissing or invalid authenticationVerify API key format and validity
    403
    		ForbiddenInactive API keyContact support to activate account
    404
    		Not FoundCompany not found with provided Site URNVerify Site URN from match endpoint
    422
    		Unprocessable EntityValidation error (e.g., invalid weights)Review error details in response body
    429
    		Too Many RequestsRate limit or quota exceededWait for rate limit reset or purchase credits
    503
    		Service UnavailableDatabase connection unavailableRetry after a few seconds; contact support if persistent
    504
    		Gateway TimeoutMatch query took too long to executeSimplify query or retry; complex name patterns may timeout

    Validation Error Response (422)

    {
  "detail": [
    {
      "type": "value_error",
      "loc": ["body"],
      "msg": "If custom weights are provided, all four weights must be specified",
      "input": {...}
    }
  ]
}

    Support

    Technical Support

    helpdesk@datahq.co.uk

    Account Queries

    accounts@datahq.co.uk

    Response Times

    • Critical issues: 2 hours
    • Standard queries: 24 hours
    • Feature requests: 5 business days