itmatch.dev

Employee API

Integrate your CRM or HR system with itmatch.dev. Create and update employees, skills, languages, and documents using a company API token.

Register company Log in to create API key

Getting started

  1. Register your company and complete verification.
  2. Enable the Employees module in company settings.
  3. As company admin, open Company → API tokens and create a key.
  4. Copy the secret immediately (shown once).
  5. Call the API with Authorization: Bearer <secret>.

Base URL

http://itmatch.dev/api/v1/

external_id (required)

Every employee created via API must include external_id — your CRM primary key. It must be unique within your company. Use GET /employees/by-external-id/{external_id}/ to fetch records.

Reference data (read-only)

Load catalogs before creating employees. One-shot bootstrap or individual lists:

  • GET /api/v1/reference/employees/
  • GET /api/v1/managers/
  • GET /api/v1/locations/
  • GET /api/v1/skills/
  • GET /api/v1/languages/
  • GET /api/v1/countries/
Employee field Source
manager_idGET /managers/ → id
current_locationGET /locations/ → id
timezonereference/employees → timezones[].value
education_level, status, …choices.*.value
skills[].nameGET /skills/ (must exist)
languages[].proficiencychoices.language_proficiency
documents[].document_typechoices.document_type

Example: create employee

curl -X POST "http://itmatch.dev/api/v1/employees/" \
  -H "Authorization: Bearer yst_live_YOUR_SECRET" \
  -H "Content-Type: application/json" \
  -d '{
    "external_id": "crm-employee-42",
    "first_name": "Jane",
    "last_name": "Doe",
    "position": "Backend Developer",
    "status": "draft",
    "education_level": "bachelor",
    "manager_id": 12,
    "current_location": "1",
    "timezone": "Europe/Warsaw",
    "skills": [{"name": "Python", "level": "advanced"}],
    "languages": [{"name": "English", "proficiency": "fluent"}],
    "documents": [{"document_type": "passport", "country": "Poland"}]
  }'

Endpoints

  • GET /api/v1/employees/
  • POST /api/v1/employees/
  • GET /api/v1/employees/{id}/
  • PATCH /api/v1/employees/{id}/
  • DELETE /api/v1/employees/{id}/
  • GET /api/v1/employees/by-external-id/{external_id}/

List filters: status, external_id, updated_since, search.

Activation rules

Setting status to active requires location, available availability, experience, work format, and rate — same rules as the web UI.

Provenance

Responses include created_via and last_updated_via (manual or api) so you can see how a profile was last changed in itmatch.dev.

OpenAPI reference

Download OpenAPI schema · Swagger UI