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 (CSV from /match/export)

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

403

Missing API key (Not authenticated)

403

Invalid, inactive or disabled API key

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

Rate Limits & Quotas

Endpoint	Limit	Window
/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

Credit Headers

Returned on calls that consume credits, so you can track spend without a second request:

X-Credits-Consumed: 1
X-Credits-Remaining: 48210

Rate-limit headers are not currently returned; a 429 response indicates either the rate limit or an exhausted credit balance — the detail message distinguishes them.

429 Response Example

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

Two things worth knowing before you budget. A bulk request is all or nothing: if your balance will not cover every company that matched, the request is refused with 429, nothing is charged and no results are returned — you never receive a partial batch you have paid for. And a returned result is not proof of a charge: very weak candidates are still returned so you can see them, but they are free. Treat the X-Credits-Consumed header as the authority on what a call cost, not the number of rows you got back.

Credit Usage: /search is free./match costs 1 credit per request that returns a match — one credit however many candidates come back, and nothing at all if none do./match/bulk costs 1 credit per input company that matches, so a 100-company batch where 60 match costs 60./match/export is charged like /match./enrich costs 4 credits./contacts costs 5 credits per contact, or 10 with an email address./screen costs 4 credits per suppression hit only. All endpoints are rate limited.

API Endpoints

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

Parameter	Type	Required	Description
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,
  // two of the five shown
  "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

Code	Error Type	Description	Resolution
400	Bad Request	Invalid request format or validation error	Check request schema and field constraints
403	Forbidden	Missing, invalid or inactive API key	Verify the key is correct and the account is active
404	Not Found	Company not found with provided Site URN	Verify Site URN from match endpoint
422	Unprocessable Entity	Validation error — invalid weights, or more than 100 companies in a bulk request	Review the error details in the response body
429	Too Many Requests	Rate limit exceeded, or insufficient credits — check the detail field. On /match/bulk an unaffordable batch is refused whole: nothing is charged and no results are returned	Wait for the limit to reset, or top up credits and retry
503	Service Unavailable	Database connection unavailable	Retry after a few seconds; contact support if persistent
504	Gateway Timeout	Match query took too long to execute	Simplify 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