Skip to main content

Integration Guide

Overview​

This guide provides practical guidance and best practices for integrating the Kontakto API into your applications.

info

We're working on official Typescript SDKs for popular programming languages to make integration even easier.

Company Search Integration​

The /search endpoint is optimized for typeahead functionality, providing fast, relevant results as users type. This endpoint returns compact company information including business ID, name, auxiliary names, and Kontakto rating.

Key Features​

  • Fast Response: Optimized for real-time search with sub-100ms response times
  • Smart Ranking: Results are ranked by relevance and company status
  • Rating Information: Includes Kontakto rating (green/yellow/red) for risk assessment
  • Multiple Names: Returns business names, auxiliary names, and parallel names

Postal Code Search Integration​

The /postalcodes endpoint provides fast search for Finnish postal codes and municipalities. This is useful for address forms.

Available Information​

  • Postal Codes: Complete Finnish postal code database
  • Area Names: Both Finnish and Swedish language support

Best Practices​

Performance Optimization​

  1. Debounce Search Inputs: Use 300-500ms debouncing to avoid excessive API calls
  2. Minimum Query Length: Start searching after 2-3 characters
  3. Result Limits: Use appropriate limits (default is 10)
  4. Caching: Cache frequently searched results when appropriate

User Experience​

  1. Loading States: Show clear loading indicators during searches
  2. Error Handling: Gracefully handle API errors and network issues
  3. Empty States: Provide helpful messages when no results are found
  4. Accessibility: Ensure keyboard navigation and screen reader support

Security​

  1. API Key Storage: Store API keys securely (environment variables, secure storage)
  2. Rate Limiting: Respect API rate limits and implement client-side throttling if needed
  3. Input Validation: Sanitize user inputs before sending to the API

Error Handling​

Common Error Scenarios​

  • 401 Unauthorized: Invalid or expired API key
  • 403 Forbidden: Insufficient permissions or rate limit exceeded
  • 404 Not Found: Requested resource doesn't exist
  • 500 Internal Error: Server-side issues (rare)

Best Practices​

  • Implement exponential backoff for retries
  • Log errors for debugging and monitoring
  • Provide user-friendly error messages
  • Handle network timeouts gracefully

Upcoming SDK​

The JavaScript SDK will provide:

  • Server-Side Only: Designed for Node.js and secure server environments
  • Type-Safe Interfaces: Full TypeScript support with comprehensive type definitions
  • Built-in Security: Validation to prevent client-side usage
  • Authentication Handling: Secure token management and renewal
  • Rate Limiting: Automatic rate limit handling and backoff strategies
  • Error Handling: Comprehensive error handling with detailed error messages
  • Development Tools: Debugging and logging capabilities
  • Integration Examples: Server-side implementation templates

Support and Resources​

  • API Documentation: Complete endpoint reference in the OpenAPI specification
  • Support: Contact [email protected] for technical assistance