TachoSync API

TachoSync provides a REST API that enables external systems to integrate with the TachoSync platform and interact with data programmatically. This allows customers, service providers, and partners to automate workflows and connect TachoSync with other systems.

API access is secured using API keys, which define what company data the integration is allowed to access.

For detailed endpoint documentation, request parameters, responses, and examples, see the TachoSync API Documentation Portal.

Prerequisites and important notes

Before using the API, the following conditions must be met:

• You must have a TachoSync user account.
• Your user must belong to a company in the TachoSync system.
• You must have the Company Administrator role to create and manage API keys.

NOTE! If you are a new customer and do not yet have a company or user account, contact Sales or Support to get access.

How API key works

Each API key is scoped to one specific company in the company hierarchy. The key grants access to:

• Selected company
• All child companies below it

NOTE! The key cannot access parent companies or sibling companies.

Why this matters

This model allows safe separation of data:

• Service providers can create one API key per customer.
• Each key only exposes the data that customer is entitled to see.
• There is no risk of cross-customer data access.

Examples

• A root-level Company Administrator can create a key that accesses all companies in the hierarchy
• A sub-company administrator can only create keys for their own company and its children

How to create an API key

Only Company Administrators can create API keys. Creation Step-by-step  :

1. Log in to the TachoSync portal:
2. Navigate to Integrations → API
3. Click Add Integration
4. Select API as the integration type
5. Fill in the fields:
   1. Key name - A descriptive name for the key (required, max 50 characters)
   2. Company - Select the company the key will be scoped to(only companies within your hierarchy are available)
   3. Expiry date (optional) - The date after which the key will automatically expire
6. Click Generate.
7. Copy the API key value
   1. The key is shown only once
   2. It cannot be retrieved later
8. Tick “I have saved the API key” and close the dialog

Important: Store the key securely. If it is lost, it must be deleted and regenerated.

API authentication

All API requests must include the API key in the request header:

X-API-KEY: your_api_key_here

Important: If the key is missing, invalid, expired, disabled, or deleted, the request is rejected immediately.

Company context and companyId

Each API key automatically applies a company context to all API requests.

• By default, requests operate on the company the key is scoped to
• The key also authorizes access to child companies within that scope

Using companyId Some API endpoints support an optional companyId parameter. You should include companyId when: • You want to access or modify data for a specific child company If companyId is: • Provided → the request applies to that company (if it is within scope) • Omitted → the API uses the company the key is scoped to The API will reject requests that attempt to access companies outside the key’s scope.

API key list

The API key list shows all keys available to your company. Down below TachoSync columns explained

• Name

Friendly name of the API key

• Company

The company the key is scoped to (defines access scope)

• Status
  • Active – key is valid and requests are accepted
  • Disabled – key is manually suspended; requests are rejected
  • Expired – expiry date has passed; requests are rejected
• Last event

Most recent API activity using this key

• Expiry date

Date when the key expires (if set)

• Created at

Date and time when the key was created

Managing existing API keys

The API key list shows all keys available to your company.

• Editing
  • Only the key name can be changed
  • Company scope and expiry date cannot be edited after creation
• Enabling and disabling
  • Disabled keys reject all API requests immediately
  • Re enabling restores access using the same key value

This is useful for Temporary suspension/Incident response/Pausing integrations without reconfiguration

• Expiry behavior
  • Keys with an expiry date automatically move to Expired status
  • Expired keys cannot be re activated
  • To continue access, a new key must be created
• Deletion
  • Deletion is permanent and immediate
  • Any request using a deleted key is rejected instantly

Important notes

• Expiry dates cannot be changed after creation
  

This is intentional. If a key must remain active longer, create a new one.

• API keys belong to the company, not the user
  

If the user who created a key leaves the organisation, the key: remains valid/can be managed by other Company Administrators

• API key values are shown only once
  

There is no recovery mechanism. If a key is lost or exposed, delete it and generate a new one.