Skip to main content
API docs by Redocly

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.

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

offset
number
Default: 0

Number of results to skip

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": [
    ],
  • "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": {
    }
}

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": {
    }
}