VistaConnect API documentation

How to match, enrich and search UK B2B data with the VistaConnect API.

Vista™ Database

v7.57.0

VistaConnect API: match, enrich and access UK B2B data

Match company names to our records, enrich with up to 22 company fields, and access6.9 million professional contacts including 1.8 million senior decision makers.

4.0 million companiesUK companies

6.9 million contactsProfessional contacts

1.8 million SDMsSenior decision makers

6-39msTypical server response

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 support@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

Every rate-limited response carries your position in the current one-minute window, counted per API key and per endpoint:

X-RateLimit-Limit: 120
X-RateLimit-Remaining: 87
X-RateLimit-Reset: 23

X-RateLimit-Reset is the number of seconds until the window resets. A 429 for the rate limit also carries Retry-After: wait that many seconds, then retry. A 429 for an exhausted credit balance has no Retry-After, because waiting will not help; the detail message says which it is.

429 Response Example

{
  "detail": "Rate limit exceeded"
}

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, so 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. These are per-call costs: /enrich and /contacts both take the site_urn that /match returns, so a record you have not matched before costs the match too: 5 credits all-in for a company profile, 6 for a contact, 11 with an email. Re-using a stored site_urn costs only the per-call price. 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

support@datahq.co.uk

Account Queries

accounts@datahq.co.uk

Response Times

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