API Reference

We’ve designed Kota Embedded around payroll, employer of record and HR platforms with specific use-cases available to different platforms so you don’t have to worry about compliance and can focus on offering a great customer experience.

Scoping out an integration?

Check out our documentation to plan your integration.

Base URL

https://api.kota.io

The Kota API uses API keys to authenticate requests.

Test mode secret keys have the prefix pk_test_ and live mode secret keys have the prefix pk_live_.

Your API keys carry many privileges, so be sure to keep them secure! Do not share your secret API keys in publicly accessible areas such as GitHub, client-side code, and so forth.

Authentication to the API is performed via Bearer Auth. Provide your API key as the bearer token value in the Authorization header. Use -H "Authorization: Bearer YOUR_API_SECRET_KEY" in your request.

All API requests must be made over HTTPS. Calls made over plain HTTP will fail. API requests without authentication will also fail.

API keys are tied to an individual platform and are restricted to that platform’s type, such as employer_of_record and payroll_provider. Some endpoints are restricted to specific types and they are clearly noted in this API reference.

Kota uses conventional HTTP response codes to indicate the success or failure of an API request.

In general:

• Codes in the 2xx range indicate success.
• Codes in the 4xx range indicate an error that failed given the information provided (e.g., a required parameter was omitted). You should not retry the same request, except for the 429 status code.
• Codes in the 5xx range indicate an error with Kota’s servers (these are rare). You can retry the same request.

Learn more about specific errors here.

The Error object

In the event of an error, Kota will return an error object conform to the Problem Details for HTTP APIs specification. The error object has at the following properties. Additional properties may be included for specific errors, see the detailed error documentation.

The API supports idempotency for safely retrying requests without accidentally performing the same operation twice. When creating or updating an object, use an idempotency key. Then, if a connection error occurs, you can safely repeat the request without risk of creating a second object or performing the update twice.

To perform an idempotent request, provide an additional header to the request: "Idempotency-Key: YOUR_IDEMPOTENT_KEY"

The idempotency key is a unique identifier that Kota’s servers use to recognize subsequent retries of the same request. How you create unique keys is up to you, but we suggest using V4 UUIDs, or another random string with at least 30 characters of entropy to avoid collisions.

Idempotency keys are linked with your authentication token and are up to 200 characters long with an expiration of 1 hour.

The idempotency layer compares incoming parameters to those of the original request. If the parameters match we’ll return exactly the same response as before without re-executing the request. If they do not match it will return a 409 Conflict error to prevent accidental misuse.

We save results only after the execution of an endpoint completes successfully. If incoming parameters fail validation, or the request conflicts with another request that’s executing concurrently we will discard the data of the subsequent request. You can retry these requests.

All POST requests accept idempotency keys. Don’t send idempotency keys in GET, PUT and DELETE requests because it has no effect. These requests are idempotent by definition.