Introduction

Welcome to the Tohama Integration API — the partner-facing API for integrating your system with the Tohama platform.

What you can do

Capability	Endpoints
Jobs	Create a job · List your jobs
Internships	Create an internship · List your internships
Seminars	Create a seminar · List your seminars
Master data	List job categories · List locations · List related universities

Master-data endpoints give you the ids you need to build create payloads: categoryId and locationId come from List Job Categories / List Locations, and the university ids for university-targeted publishing come from List Related Universities.

Base URLs

Endpoints are served through the Azure API Gateway, with one base per service. This documentation is built per environment — the base URL below reflects the environment you are reading:

Gateway base for this environment: https://ke-tohama-api-gateway.azure-api.net

Service	Base URL	Endpoints
Jobs	https://ke-tohama-api-gateway.azure-api.net/jobs/v1/external	Jobs, Internships, Job Categories
Seminars	https://ke-tohama-api-gateway.azure-api.net/seminars/v1/external	Seminars
Universities	https://ke-tohama-api-gateway.azure-api.net/universities/v1/external	University Relationship
Commons	https://ke-tohama-api-gateway.azure-api.net/commons/v1/external	Locations

Each endpoint in the API Reference also documents the service it belongs to.

:::note Environments The gateway host differs per region — for example https://ke-tohama-api-gateway.azure-api.net (Kenya) and https://jp-tohama-api-gateway.azure-api.net (Japan). Always use the base shown above for the environment you were onboarded to. :::

Authentication

Every request is authenticated with HMAC-SHA256 request signing (there are no bearer tokens). You will be issued an API Key and a Secret Key; each request carries three headers:

X-Api-Key: <your-api-key>
X-Timestamp: <current-unix-time-in-milliseconds>
X-Signature: <hmac-sha256-signature>

See Request Signature for the exact, step-by-step algorithm with a fully worked example and copy-paste code.

Conventions

• Request/response bodies are JSON — always send Content-Type: application/json.
• Dates are ISO 8601 (2026-04-01); times are 24-hour HH:mm.
• Money/count fields are plain numbers (500000), not formatted strings.
• Unknown fields are rejected with VALIDATION_ERROR.
• Company scope is always derived from your API key — you never send a company id, and you only see/create resources for your own company.
• Set the optional X-Service-Lang header (e.g. en, ja) to localize names in responses.
• Every response includes a requestId (also returned in the X-Request-Id header) — quote it when contacting support.

Quick start

1. Get your API Key and Secret Key from the My Resource admin web (Settings → API Key). The Secret Key is shown once — store it securely.
2. Sign every request as described in Request Signature.
3. Fetch master data (categories, locations, related universities) to build your payloads.
4. Create jobs, internships or seminars, and list them back.

Explore the full reference under API Reference.