Skip to main content

Kontakto Business Data Service (2.0.1)

Download OpenAPI specification:Download

Kontakto API Support: [email protected] Terms of Service

The Kontakto Business Data Service is a high-performance, low-latency API for accessing Finnish business data from multiple sources.

Engineered with exceptional speed in mind, Kontakto is an ideal solution for powering real-time, user-facing applications where performance is critical.

Example Use Cases:

  • Instant Autocomplete: Type-ahead search boxes that feel instantaneous to the user.
  • Real-time Data Enrichment: Enrich user profiles or company records on the fly without adding user-perceptible delay.
  • Dynamic Form Validation: Validate business information (like company names or VAT numbers) as users type.

Rate limits

Each API key may send up to 10 requests per second, with bursts of up to 60 requests. There is no daily or monthly quota. A request over the limit gets HTTP 429 Too Many Requests with a Retry-After header (seconds); retry after that. Every response carries RateLimit-Limit, RateLimit-Remaining and RateLimit-Reset headers. Exceeding the limit never incurs a charge.

Register for an API key

Create an account at Kontakto.fi and get your API key.

Companies

Company search (typeahead)

Search companies by name, business ID, VAT ID, domain or phone number, with compact results for typeahead functionality. Every word of the query must occur; a query with no match is retried allowing for typos. Hides black-rated companies and companies who have requested to be hidden from Kontakto platform. Use the advanced search to filter the results yourself.

Use Cases: Perfect for autocomplete dropdowns, company selection forms, and quick company lookups. Returns essential company information including business ID, name, auxiliary names, and Kontakto rating.

Authorizations:
apiKeyAuth
query Parameters
q
string
Example: q=Kontakto

Search query

limit
string
Example: limit=10

Maximum number of results (1-50, default 10)

Responses

Response samples

Content type
application/json
{
  • "hits": [
    ],
  • "estimatedTotalHits": 0,
  • "processingTimeMs": 0
}

Advanced company search

Company search with filters and field projection. The query matches names, business ID, VAT ID, domains and phone numbers; every word must occur. Without a query, the filters alone select the companies, in name order. Companies who have requested to be hidden are never returned; black-rated companies are, unless filters.ratingColor leaves them out.

Filtering: filters is an object; every key given narrows the result. Code lists match any of the given values.

Field Projection: Use the fields parameter to specify which fields to include in the response. You can use any fields specified in the company schema, including nested fields with dot notation (e.g., kontaktoRating.color). If omitted, returns complete company data.

Authorizations:
apiKeyAuth
Request Body schema: application/json
q
string

Search query (optional when filters are given)

object
fields
string

Comma-separated list of fields to include in the response. Use dot notation for nested fields (e.g., 'kontaktoRating.color'). If omitted, returns complete company data. Examples: 'businessId,businessName' for minimal data, 'businessId,businessName,kontaktoRating.color,address.city' for specific fields.

limit
number
Default: 10

Maximum number of results: up to 10, or up to your plan's limit (at most 1000) on a bigger plan

offset
number
Default: 0

Number of results to skip, for paging (on a plan with more than 10 results per search). A search with filters and no query pages through every match in name order.

Responses

Request samples

Content type
application/json
{
  • "q": "Kontakto",
  • "filters": {
    },
  • "fields": "businessId,businessName,kontaktoRating.color,address.city,website",
  • "limit": 10,
  • "offset": 0
}

Response samples

Content type
application/json
{
  • "hits": [
    ],
  • "query": "string",
  • "processingTimeMs": 0,
  • "limit": 0,
  • "offset": 0,
  • "estimatedTotalHits": 0
}

Get company by business ID

Returns company details based on the business ID

Authorizations:
apiKeyAuth
path Parameters
businessId
required
string
Example: 1234567-8

Business ID of the company

Responses

Response samples

Content type
application/json
{
  • "kontaktoId": "string",
  • "businessId": "string",
  • "vatId": "string",
  • "businessName": "string",
  • "auxiliaryNames": [
    ],
  • "parallelNames": [
    ],
  • "operationalStatus": true,
  • "operationalStatusAsOf": "string",
  • "operationalStatusDescription": "string",
  • "countryCode": "string",
  • "languageCode": "string",
  • "domicileCity": "string",
  • "domicileCode": "string",
  • "industryDescription": "string",
  • "industryAsOf": "string",
  • "industryTol2008Code": "string",
  • "industryTol2025Code": "string",
  • "legalForm": "string",
  • "legalFormCode": "string",
  • "legalFormAsOf": "string",
  • "sector": "associations_and_foundations",
  • "establishmentDate": "string",
  • "otherAddress": [
    ],
  • "postalAddress": {
    },
  • "visitingAddress": {
    },
  • "website": [
    ],
  • "domain": [
    ],
  • "phoneNumber": [
    ],
  • "email": [
    ],
  • "websites": [
    ],
  • "socialLinks": [
    ],
  • "register": [
    ],
  • "eInvoiceAddress": [
    ],
  • "kontaktoRating": {
    },
  • "businessIdHistory": [
    ]
}

Get tax debt status for company

Returns tax debt and filing negligence status. Uses cached data when appropriate, fetches fresh data during update periods. Use refresh=true to force fresh data fetch.

Authorizations:
apiKeyAuth
path Parameters
businessId
required
string
Example: 1234567-8

Business ID of the company

query Parameters
refresh
string
Example: refresh=true

Force fresh data fetch from Tax Administration API (ignores cache)

Responses

Response samples

Content type
application/json
{
  • "businessId": "string",
  • "businessName": "string",
  • "lastUpdate": "string",
  • "hasTaxDebt": true,
  • "hasFilingNegligence": true,
  • "queriedAt": "string",
  • "source": "string"
}

Postal Codes

Search postal codes

Search Finnish postal codes with comprehensive location information. The query matches the start of the postal code or a word in the postal code, municipality or administrative area names (Finnish or Swedish). Returns postal code details including municipality names in Finnish and Swedish, administrative areas, and geographic codes. Ideal for address validation and location-based applications.

Authorizations:
apiKeyAuth
query Parameters
q
string
Example: q=Helsinki

Search query

limit
string
Example: limit=10

Maximum number of results (1-100, default 10)

Responses

Response samples

Content type
application/json
{
  • "hits": [
    ],
  • "estimatedTotalHits": 0,
  • "processingTimeMs": 0
}

Addresses

Address search (typeahead)

Fast address suggestions for checkout forms, registration workflows, and autocomplete functionality. The query is read as a street name (a prefix of the Finnish or Swedish name), then a number with an optional letter, then a postal code or locality: Mannerheimintie 15, Kampinkuja2, Eeronkatu 7, 40720 Jyväskylä. Returns essential address information optimized for user interface components including unique address identifiers for form handling.

Authorizations:
apiKeyAuth
query Parameters
q
required
string >= 2 characters
Example: q=Mannerheimintie

Search query (minimum 2 characters)

limit
string
Example: limit=10

Maximum number of results

deduplicate
string
Example: deduplicate=true

Deduplicate results by address name, postal code, and address number. Useful for typeahead where multiple entries for the same physical address are not needed.

hasBuilding
string
Example: hasBuilding=true

Only return addresses that have associated building data.

Responses

Response samples

Content type
application/json
{
  • "hits": [
    ],
  • "estimatedTotalHits": 0,
  • "processingTimeMs": 0,
  • "source": "Suomen ympäristökeskuksen (Syke)"
}

Advanced address search

Advanced address search with filters and field projection. The query is read like the typeahead's (street name, number and letter, postal code or locality); without a query the filters alone select the addresses, in street name order.

Filtering: filters is an object; every key given narrows the result: postalCode and municipalityNumber (lists, any of the values), hasBuilding (boolean).

Field Projection: Use the fields parameter to specify which fields to include in the response. You can use any fields specified in the address schema, including nested fields with dot notation (e.g., coordinates.longitude). If omitted, returns complete address data.

Pagination: Use limit and offset parameters for result pagination. The hasMore field indicates if additional results are available.

Authorizations:
apiKeyAuth
Request Body schema: application/json
query
string

Search query (optional when filters are given)

limit
number

Maximum number of results

offset
number

Number of results to skip

object
fields
string

Comma-separated list of fields to include in the response. Use dot notation for nested fields (e.g., 'coordinates.longitude'). If omitted, returns complete address data. Examples: 'id,addressFin,postalCode' for minimal data, 'id,addressFin,postalCode,coordinates' for specific fields.

Responses

Request samples

Content type
application/json
{
  • "query": "Mannerheimintie 15, Helsinki",
  • "limit": 20,
  • "offset": 0,
  • "filters": {
    },
  • "fields": "id,addressFin,postalCode,coordinates"
}

Response samples

Content type
application/json
{
  • "hits": [
    ],
  • "estimatedTotalHits": 0,
  • "processingTimeMs": 0,
  • "query": "string",
  • "limit": 0,
  • "offset": 0,
  • "hasMore": true,
  • "source": "Suomen ympäristökeskuksen (Syke)"
}

Get single address by ID

Fetch complete address information by unique address identifier. Returns detailed address data including building information, coordinates, and all available fields.

Authorizations:
apiKeyAuth
path Parameters
id
required
string
Example: b75f82f3-4075-461a-b033-aa35724a3155

Unique address identifier

Responses

Response samples

Content type
application/json
{
  • "id": "b75f82f3-4075-461a-b033-aa35724a3155",
  • "addressFin": "Mannerheimintie 1",
  • "addressSwe": "Mannerheimvägen 1",
  • "addressNameFin": "Mannerheimintie",
  • "addressNameSwe": "Mannerheimvägen",
  • "numberPartOfAddressNumber": 71,
  • "postalCode": "00100",
  • "postalOfficeFin": "Helsinki",
  • "postalOfficeSwe": "Helsingfors",
  • "municipalityNumber": "091",
  • "domicileCode": "091",
  • "coordinates": {
    },
  • "country": "FI",
  • "building": {
    }
}

Target groups

Attributes for criteria

The attributes criteria can use, with their kinds, operators and values.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "attributes": [
    ]
}

Count matching companies

How many companies the criteria match, and whether a list can be made of them.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
object

A filter tree: a condition { "field": <attribute>, <operator>: <value> } or a group { "all": [...] }, { "any": [...] }, { "not": {...} }. The attributes and their operators are listed by GET /target-groups/attributes. A condition never matches a company whose value is unknown.

property name*
additional property
any or null

Responses

Request samples

Content type
application/json
{
  • "criteria": {
    }
}

Response samples

Content type
application/json
{
  • "count": 0,
  • "maxCompanies": 0,
  • "canCreateList": true,
  • "dataAsOf": "string"
}

Sample matching companies

Up to 5 random companies that match the criteria, to check they are the right ones.

Authorizations:
apiKeyAuth
Request Body schema: application/json
required
object

A filter tree: a condition { "field": <attribute>, <operator>: <value> } or a group { "all": [...] }, { "any": [...] }, { "not": {...} }. The attributes and their operators are listed by GET /target-groups/attributes. A condition never matches a company whose value is unknown.

fields
string

Comma-separated fields to include, as in the advanced search; all when omitted

Responses

Request samples

Content type
application/json
{
  • "criteria": {
    },
  • "fields": "businessId,businessName,domicileCity,industryDescription,websites"
}

Response samples

Content type
application/json
{
  • "companies": [
    ]
}

Make a list

Save the companies that match the criteria as a list. Its first members are its baseline; from then on the list follows the criteria as the company data changes (once a day), and GET /target-groups/{id}/events tells who entered and left. The criteria of a list never change: to change them, make a new list with replacesId. Refused when the criteria match more companies than your organization's limit (see POST /target-groups/count).

Authorizations:
apiKeyAuth
Request Body schema: application/json
name
required
string [ 1 .. 200 ] characters
required
object

A filter tree: a condition { "field": <attribute>, <operator>: <value> } or a group { "all": [...] }, { "any": [...] }, { "not": {...} }. The attributes and their operators are listed by GET /target-groups/attributes. A condition never matches a company whose value is unknown.

replacesId
string <uuid>

A list of yours this one replaces (a new version, or a deleted list made again)

Responses

Request samples

Content type
application/json
{
  • "name": "string",
  • "criteria": {
    },
  • "replacesId": "60f42e29-ba32-4077-b7d5-608555a5fb6c"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "criteria": {
    },
  • "replacesId": "string",
  • "createdAt": "string",
  • "deletedAt": "string",
  • "memberCount": 0,
  • "enteredCount": 0,
  • "leftCount": 0,
  • "dataAsOf": "string"
}

Your lists

Your organization's lists, newest first, deleted ones included.

Authorizations:
apiKeyAuth

Responses

Response samples

Content type
application/json
{
  • "lists": [
    ]
}

A list

Authorizations:
apiKeyAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "criteria": {
    },
  • "replacesId": "string",
  • "createdAt": "string",
  • "deletedAt": "string",
  • "memberCount": 0,
  • "enteredCount": 0,
  • "leftCount": 0,
  • "dataAsOf": "string"
}

Delete a list

Deletes the list's members and events for good. The list itself stays, marked deleted, with its name, criteria and counts, so it can be made again (POST /target-groups/{id}/recreate) with a new baseline.

Authorizations:
apiKeyAuth
path Parameters
id
required
string <uuid>

Responses

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "criteria": {
    },
  • "replacesId": "string",
  • "createdAt": "string",
  • "deletedAt": "string",
  • "memberCount": 0,
  • "enteredCount": 0,
  • "leftCount": 0,
  • "dataAsOf": "string"
}

Make a list again

A new list with the criteria of this one (deleted or not) and a new baseline; it names this one in replacesId.

Authorizations:
apiKeyAuth
path Parameters
id
required
string <uuid>
Request Body schema: application/json
name
string [ 1 .. 200 ] characters

Responses

Request samples

Content type
application/json
{
  • "name": "string"
}

Response samples

Content type
application/json
{
  • "id": "string",
  • "name": "string",
  • "criteria": {
    },
  • "replacesId": "string",
  • "createdAt": "string",
  • "deletedAt": "string",
  • "memberCount": 0,
  • "enteredCount": 0,
  • "leftCount": 0,
  • "dataAsOf": "string"
}

Companies in a list

The companies in the list now, with their current data, a page at a time.

Authorizations:
apiKeyAuth
path Parameters
id
required
string <uuid>
query Parameters
limit
integer [ 1 .. 1000 ]

1-1000, default 100

cursor
string <uuid>

The next value of the previous page

fields
string

Comma-separated fields to include, as in the advanced search

Responses

Response samples

Content type
application/json
{
  • "companies": [
    ],
  • "next": "string"
}

Who entered and left a list

The list's events in order: ENTER or LEAVE, with the reason (baseline, company_new, company_changed, company_removed) and, for a company that left but is still in the data, the parts of the criteria it no longer meets (details.failed). Keep the last id you have and ask for the events after it.

Authorizations:
apiKeyAuth
path Parameters
id
required
string <uuid>
query Parameters
after
integer or null >= 0

Events after this event id (the last id you have); from the start when omitted

limit
integer [ 1 .. 1000 ]

1-1000, default 100

Responses

Response samples

Content type
application/json
{
  • "events": [
    ]
}

Legacy

Get company by business ID (legacy format) Deprecated

Returns company details in the response format of the previous Kontakto API. For customers migrating from it; new integrations should use /companies/{businessId}.

Authorizations:
apiKeyAuth
path Parameters
businessId
required
string
Example: 2831767-5

Business ID of the company

Responses

Response samples

Content type
application/json
{
  • "businessId": "2831767-5",
  • "businessName": "Kontakto Oy",
  • "vatNumber": "FI28317675",
  • "domicile": {
    },
  • "auxiliaryNames": [
    ],
  • "parallelNames": [
    ],
  • "mailAddress": {
    },
  • "visitingAddress": {
    },
  • "deliveryAddress": {
    },
  • "officialLanguage": "fi",
  • "languages": [
    ],
  • "register": {
    },
  • "industry": {
    },
  • "website": "http://kontakto.fi",
  • "url": {},
  • "phoneNumber": {
    },
  • "email": "string",
  • "legalForm": {
    },
  • "businessStatus": {
    },
  • "kontaktoRating": {
    },
  • "eInvoice": {
    }
}