API docs by Redocly

ScaleUnit API (1.0.0)

Download OpenAPI specification:

Roman Meusch: r.meusch@scaleunit.de

This document describes the authenticated portal API and the public webhook that power the JobBoard frontend. Every operation is scoped to exactly one of: a tenant, an organization, or the calling user. Provide the OAuth2 bearer token together with the required scope-selection header (X-Tenant-ID or X-Organization-ID); user-scoped operations need the token alone. Authenticated endpoints return 401 when the bearer token (or session cookie) is missing or invalid; operations with parseable inputs return 400 on malformed ids or bodies; any operation may return 500 on internal errors.

Jobs

Job postings

List job postings, newest first. Plain `GET /` returns the full

list as a bare array (the pre-pagination behavior, kept for existing clients); specifying offset or count opts into pagination and returns the JobPage envelope with total.

Authorizations:
(OAUTHTENANT) (MACHINETENANT)
query Parameters
offset
integer [ 0 .. 4294967295 ]

Offset into the newest-first job list. Specifying offset or count opts into pagination. Defaults to 0.

count
integer [ 0 .. 4294967295 ]

Maximum number of jobs to return. Specifying offset or count opts into pagination. Defaults to 50 when paginating.

object (JobFilter)

Optional filter selectors in serde_qs deep-object form. Filtering works with and without pagination.

Responses

Response samples

Content type
Example
[ ]

Create job posting

Authorizations:
(OAUTHTENANT) (MACHINETENANT)
Request Body schema:
required
ai_context_info
string
ai_instructions
string
archive_at
integer <int64>

Unix timestamp (ms). 0 when unset; explicit null is rejected.

auto_invite
required
boolean
benefits
required
Array of strings
category_id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

CvRequest (string) or null

Whether the chatbot asks for a CV. unspecified inherits the workspace's default_cv_request, then the organization's, then optional. Option so a partial PUT leaves the stored value untouched; GET always returns it.

description
required
string
export_alternative_id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

export_emails
required
Array of strings
export_template
required
string (ExportTemplate)
Enum: "default" "softGarden"
boolean or null
import_reference
string
invite_link
required
string
JobLanguage (string) or null

Language of the job's candidate-facing content; unspecified falls back to the tenant's default_job_language (then German). Option so a write without the field leaves the stored value untouched; GET always returns it.

link
string
location_ids
required
Array of strings <int64> (Id) [ items <int64 > ]
name
required
string
notify_contacts
required
boolean
primary_contact_person_id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

required_questions
required
Array of strings
requirements
required
Array of strings
SalaryQuestion (string) or null

How the interviewer asks this job's candidates for their salary expectation. Absent or null on create takes the organization's default_salary_question (then single); on PUT it leaves the stored value untouched. GET always returns it.

SalaryHandling (string) or null

What the interviewer does with the salary expectation: asks and checks it against salary_range, asks and only notes it, or does not raise it. Absent or null on create takes the organization's default_salary_handling (then ask_and_check); on PUT it leaves the stored value untouched. GET always returns it.

SalaryRange (object) or null

The pay band the tenant budgets for this job. Internal — never shown to candidates; the interviewer only compares against it. null when unset.

secondary_contact_person_id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

starting_date
integer <int64>

Unix timestamp (ms). 0 when unset; explicit null is rejected.

status
required
string (JobStatus)
Enum: "draft" "published" "paused" "archived" "deleted"
tasks
required
Array of strings
timemodel
required
string (WorkingTimeModel)
Enum: "unspecified" "fullTime" "partTime" "miniJob" "fullOrPartTime"
string or null

Read-only: the job's stable WhatsApp short link (302-redirects to wa.me with the prefilled application message, built at scan time). null when the tenant has no WhatsApp channel; values supplied on write are silently discarded.

workmodel
required
string (EmploymentRelationship)
Enum: "unspecified" "permanent" "temporary" "internship" "training" "workingStudent" "studientAssistent" "practiceIntegratedStudent" "freelance"

Type of employment offered. studientAssistent is misspelled but preserved for backwards compatibility with existing clients.

Responses

Request samples

Content type
{
  • "ai_context_info": "string",
  • "ai_instructions": "string",
  • "archive_at": 0,
  • "auto_invite": true,
  • "benefits": [
    ],
  • "category_id": "string",
  • "cv_request": "unspecified",
  • "description": "string",
  • "export_alternative_id": "string",
  • "export_emails": [
    ],
  • "export_template": "default",
  • "homeoffice": true,
  • "import_reference": "string",
  • "invite_link": "string",
  • "language": "unspecified",
  • "link": "string",
  • "location_ids": [
    ],
  • "name": "string",
  • "notify_contacts": true,
  • "primary_contact_person_id": "string",
  • "required_questions": [
    ],
  • "requirements": [
    ],
  • "salary_question": "single",
  • "salary_handling": "ask_and_check",
  • "salary_range": {
    },
  • "secondary_contact_person_id": "string",
  • "starting_date": 0,
  • "status": "draft",
  • "tasks": [
    ],
  • "timemodel": "unspecified",
  • "whatsapp_link": "string",
  • "workmodel": "unspecified"
}

Response samples

Content type
{
  • "id": "string"
}

Update job posting

Authorizations:
(OAUTHTENANT) (MACHINETENANT)
path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

Request Body schema:
required
ai_context_info
string
ai_instructions
string
archive_at
integer <int64>

Unix timestamp (ms). 0 when unset; explicit null is rejected.

auto_invite
required
boolean
benefits
required
Array of strings
category_id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

CvRequest (string) or null

Whether the chatbot asks for a CV. unspecified inherits the workspace's default_cv_request, then the organization's, then optional. Option so a partial PUT leaves the stored value untouched; GET always returns it.

description
required
string
export_alternative_id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

export_emails
required
Array of strings
export_template
required
string (ExportTemplate)
Enum: "default" "softGarden"
boolean or null
import_reference
string
invite_link
required
string
JobLanguage (string) or null

Language of the job's candidate-facing content; unspecified falls back to the tenant's default_job_language (then German). Option so a write without the field leaves the stored value untouched; GET always returns it.

link
string
location_ids
required
Array of strings <int64> (Id) [ items <int64 > ]
name
required
string
notify_contacts
required
boolean
primary_contact_person_id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

required_questions
required
Array of strings
requirements
required
Array of strings
SalaryQuestion (string) or null

How the interviewer asks this job's candidates for their salary expectation. Absent or null on create takes the organization's default_salary_question (then single); on PUT it leaves the stored value untouched. GET always returns it.

SalaryHandling (string) or null

What the interviewer does with the salary expectation: asks and checks it against salary_range, asks and only notes it, or does not raise it. Absent or null on create takes the organization's default_salary_handling (then ask_and_check); on PUT it leaves the stored value untouched. GET always returns it.

SalaryRange (object) or null

The pay band the tenant budgets for this job. Internal — never shown to candidates; the interviewer only compares against it. null when unset.

secondary_contact_person_id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

starting_date
integer <int64>

Unix timestamp (ms). 0 when unset; explicit null is rejected.

status
required
string (JobStatus)
Enum: "draft" "published" "paused" "archived" "deleted"
tasks
required
Array of strings
timemodel
required
string (WorkingTimeModel)
Enum: "unspecified" "fullTime" "partTime" "miniJob" "fullOrPartTime"
string or null

Read-only: the job's stable WhatsApp short link (302-redirects to wa.me with the prefilled application message, built at scan time). null when the tenant has no WhatsApp channel; values supplied on write are silently discarded.

workmodel
required
string (EmploymentRelationship)
Enum: "unspecified" "permanent" "temporary" "internship" "training" "workingStudent" "studientAssistent" "practiceIntegratedStudent" "freelance"

Type of employment offered. studientAssistent is misspelled but preserved for backwards compatibility with existing clients.

Responses

Request samples

Content type
{
  • "ai_context_info": "string",
  • "ai_instructions": "string",
  • "archive_at": 0,
  • "auto_invite": true,
  • "benefits": [
    ],
  • "category_id": "string",
  • "cv_request": "unspecified",
  • "description": "string",
  • "export_alternative_id": "string",
  • "export_emails": [
    ],
  • "export_template": "default",
  • "homeoffice": true,
  • "import_reference": "string",
  • "invite_link": "string",
  • "language": "unspecified",
  • "link": "string",
  • "location_ids": [
    ],
  • "name": "string",
  • "notify_contacts": true,
  • "primary_contact_person_id": "string",
  • "required_questions": [
    ],
  • "requirements": [
    ],
  • "salary_question": "single",
  • "salary_handling": "ask_and_check",
  • "salary_range": {
    },
  • "secondary_contact_person_id": "string",
  • "starting_date": 0,
  • "status": "draft",
  • "tasks": [
    ],
  • "timemodel": "unspecified",
  • "whatsapp_link": "string",
  • "workmodel": "unspecified"
}

Delete job posting

Authorizations:
(OAUTHTENANT) (MACHINETENANT)
path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

Responses

Download the job's WhatsApp QR code as a print-ready PNG. The QR

encodes the job's stable short link (whatsapp_link on the job), so printed codes survive message-wording changes. 404 when the job is not in this workspace or the tenant has no WhatsApp channel.

Authorizations:
(OAUTHTENANT) (MACHINETENANT)
path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

header Parameters
If-None-Match
string

Revalidation: a previously returned ETag; on a match the response is 304 Not Modified.

Responses

Download the job's WhatsApp QR code as a freely scalable SVG.

Same content and 404 conditions as the PNG variant.

Authorizations:
(OAUTHTENANT) (MACHINETENANT)
path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

header Parameters
If-None-Match
string

Revalidation: a previously returned ETag; on a match the response is 304 Not Modified.

Responses

OrganizationSettings

Customer organization settings

Get organization settings

Authorizations:
(OAUTHORG)
header Parameters
Accept-Language
string
Enum: "de" "en"

Response language; one of de, en. Absent or unsupported values fall back to de.

Responses

Response samples

Content type
{
  • "ai_context_info": "string",
  • "ai_instructions": "string",
  • "default_cv_request": "unspecified",
  • "default_imprint_url": "string",
  • "default_privacy_policy_url": "string",
  • "default_required_questions": [
    ],
  • "default_salary_question": "single",
  • "default_salary_handling": "ask_and_check",
  • "default_terms_of_service_url": "string",
  • "groups": [
    ],
  • "name": "string",
  • "tags": [
    ]
}

Update organization settings

Authorizations:
(OAUTHORG)
Request Body schema:
required
string or null

Organization-level settings. Option so a partial PUT leaves them untouched.

Two kinds live here, and they behave differently. ai_context_info, ai_instructions, default_required_questions and default_cv_request are read live on every chat and therefore apply immediately to every existing workspace and job. The default_*_url fields are copied once when a workspace is created and later edits never reach existing workspaces.

string or null
CvRequest (string) or null
string or null
string or null
Array of strings or null
SalaryQuestion (string) or null

The salary_question a new job of this organization starts with when it does not set its own; single until changed. Copied at job creation — later edits do not reach existing jobs.

SalaryHandling (string) or null

The salary_handling a new job of this organization starts with when it does not set its own; ask_and_check until changed. Copied at job creation — later edits do not reach existing jobs.

string or null
(Array of ApplicationGroupSet (ApplicationGroup (object) or null)) or null
name
required
string
(Array of ApplicationTagSet (ApplicationTag (object) or null)) or null

Responses

Request samples

Content type
{
  • "ai_context_info": "string",
  • "ai_instructions": "string",
  • "default_cv_request": "unspecified",
  • "default_imprint_url": "string",
  • "default_privacy_policy_url": "string",
  • "default_required_questions": [
    ],
  • "default_salary_question": "single",
  • "default_salary_handling": "ask_and_check",
  • "default_terms_of_service_url": "string",
  • "groups": [
    ],
  • "name": "string",
  • "tags": [
    ]
}

Download the organization default workspace title image

Authorizations:
(OAUTHORG)
header Parameters
If-None-Match
string

Revalidation: a previously returned ETag; on a match the response is 304 Not Modified.

Responses

Upload the organization default workspace title image

Authorizations:
(OAUTHORG)
Request Body schema: */*
required

File upload; the filename is sent in the Content-Disposition header.

string <binary>

Responses

Clear the organization default workspace title image

Authorizations:
(OAUTHORG)

Responses

CompanyBranding

Tenant / company branding

Get company branding and settings

Authorizations:
(OAUTHTENANT)
header Parameters
Accept-Language
string
Enum: "de" "en"

Response language; one of de, en. Absent or unsupported values fall back to de.

Responses

Response samples

Content type
{
  • "about_us_text": "string",
  • "about_us_title": "string",
  • "ai_context_info": "string",
  • "ai_instructions": "string",
  • "color_1": "string",
  • "color_2": "string",
  • "default_cv_request": "unspecified",
  • "default_job_language": "unspecified",
  • "groups": [
    ],
  • "imprint_link": "string",
  • "mail_language": "de",
  • "name": "string",
  • "privacy_policy_link": "string",
  • "retention_days": 0,
  • "social_facebook": "string",
  • "social_instagram": "string",
  • "social_linkedin": "string",
  • "social_x": "string",
  • "social_xing": "string",
  • "social_youtube": "string",
  • "summary_language": "de",
  • "tags": [
    ],
  • "terms_of_service_link": "string",
  • "thank_you_page_link": "string",
  • "whatsapp_link": "string"
}

Update company branding and settings

Authorizations:
(OAUTHTENANT)
Request Body schema:
required
about_us_text
required
string
about_us_title
required
string
ai_context_info
string
ai_instructions
string
color_1
required
string^#[0-9a-f]{6}([0-9a-f]{2})?$

Primary color.

color_2
required
string^#[0-9a-f]{6}([0-9a-f]{2})?$

Secondary color.

CvRequest (string) or null

Whether the chatbot asks for a CV on jobs of this workspace whose own cv_request is unspecified. unspecified here inherits the organization's value, then optional. Option so a partial PUT leaves the stored value untouched; GET always returns it.

JobLanguage (string) or null

Default language for jobs whose own language is unspecified. unspecified = no tenant default; candidate-facing surfaces then keep their German fallback. Option so a partial PUT leaves the stored value untouched; GET always returns it.

(Array of ApplicationGroupSet (ApplicationGroup (object) or null)) or null
imprint_link
required
string
MailLanguage (string) or null

Language of the platform's internal notification and account mails to the tenant's contacts. German for tenants that never set it. Option so a partial PUT leaves the stored value untouched; GET always returns it.

name
required
string
privacy_policy_link
required
string
integer or null

Application-data retention in whole days: applications are irreversibly deleted once older than this (counted from process completion). 0 disables retention (never delete). Option so a partial PUT leaves the stored value untouched; GET always returns the effective value.

social_facebook
required
string
social_instagram
required
string
social_linkedin
required
string
social_x
required
string
social_xing
required
string
social_youtube
required
string
SummaryLanguage (string) or null

Language of the AI-generated qualification summary. German for tenants that never set it. Option so a partial PUT leaves the stored value untouched; GET always returns it.

(Array of ApplicationTagSet (ApplicationTag (object) or null)) or null
terms_of_service_link
string
thank_you_page_link
string

Read-only: synthesised from the tenant slug on read (never null); values supplied on write are silently discarded.

string or null

Read-only: the tenant's stable WhatsApp short link for the general (job-independent) application entry (302-redirects to wa.me with the prefilled message, built at scan time). null when the tenant has no WhatsApp channel; values supplied on write are silently discarded.

Responses

Request samples

Content type
{
  • "about_us_text": "string",
  • "about_us_title": "string",
  • "ai_context_info": "string",
  • "ai_instructions": "string",
  • "color_1": "string",
  • "color_2": "string",
  • "default_cv_request": "unspecified",
  • "default_job_language": "unspecified",
  • "groups": [
    ],
  • "imprint_link": "string",
  • "mail_language": "de",
  • "name": "string",
  • "privacy_policy_link": "string",
  • "retention_days": 0,
  • "social_facebook": "string",
  • "social_instagram": "string",
  • "social_linkedin": "string",
  • "social_x": "string",
  • "social_xing": "string",
  • "social_youtube": "string",
  • "summary_language": "de",
  • "tags": [
    ],
  • "terms_of_service_link": "string",
  • "thank_you_page_link": "string",
  • "whatsapp_link": "string"
}

Download the company about-us image

Authorizations:
(OAUTHTENANT)
header Parameters
If-None-Match
string

Revalidation: a previously returned ETag; on a match the response is 304 Not Modified.

Responses

Set company about-us image (any format; the server sniffs the type)

Authorizations:
(OAUTHTENANT)
Request Body schema: */*
required

File upload; the filename is sent in the Content-Disposition header.

string <binary>

Responses

Clear the company about-us image

Authorizations:
(OAUTHTENANT)

Responses

Download the tenant's WhatsApp QR code (general application entry,

not job-specific) as a print-ready PNG. The QR encodes the tenant's stable short link (whatsapp_link on the company), so printed codes survive message-wording changes. 404 when the tenant has no WhatsApp channel.

Authorizations:
(OAUTHTENANT)
header Parameters
If-None-Match
string

Revalidation: a previously returned ETag; on a match the response is 304 Not Modified.

Responses

Download the tenant's WhatsApp QR code as a freely scalable SVG.

Same content and 404 conditions as the PNG variant.

Authorizations:
(OAUTHTENANT)
header Parameters
If-None-Match
string

Revalidation: a previously returned ETag; on a match the response is 304 Not Modified.

Responses

Categories

Job categories

List job categories

Authorizations:
(OAUTHTENANT) (MACHINETENANT)

Responses

Response samples

Content type
[
  • {
    }
]

Create job category

Authorizations:
(OAUTHTENANT) (MACHINETENANT)
Request Body schema:
required
name
required
string

Responses

Request samples

Content type
{
  • "name": "string"
}

Response samples

Content type
{
  • "id": "string"
}

Update job category

Authorizations:
(OAUTHTENANT) (MACHINETENANT)
path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

Request Body schema:
required
name
required
string

Responses

Request samples

Content type
{
  • "name": "string"
}

Delete job category

Authorizations:
(OAUTHTENANT) (MACHINETENANT)
path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

Responses

Locations

Job locations

List job locations

Authorizations:
(OAUTHTENANT) (MACHINETENANT)

Responses

Response samples

Content type
[
  • {
    }
]

Create job location

Authorizations:
(OAUTHTENANT) (MACHINETENANT)
Request Body schema:
required
name
required
string

The label the tenant sees. For an imported location this is the ATS's own name where it has one, else the compact address line "street, zip city"; the next import overwrites it.

Address (object) or null

The location's address. null when all four parts are empty. Absent or null on create/update leaves the stored address untouched; an Address with four empty strings clears it. A changed address clears the coordinates and re-geocodes, exactly like a rename.

Responses

Request samples

Content type
{
  • "name": "string",
  • "address": {
    }
}

Response samples

Content type
{
  • "id": "string"
}

Update job location

Authorizations:
(OAUTHTENANT) (MACHINETENANT)
path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

Request Body schema:
required
name
required
string

The label the tenant sees. For an imported location this is the ATS's own name where it has one, else the compact address line "street, zip city"; the next import overwrites it.

Address (object) or null

The location's address. null when all four parts are empty. Absent or null on create/update leaves the stored address untouched; an Address with four empty strings clears it. A changed address clears the coordinates and re-geocodes, exactly like a rename.

Responses

Request samples

Content type
{
  • "name": "string",
  • "address": {
    }
}

Delete job location

Authorizations:
(OAUTHTENANT) (MACHINETENANT)
path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

Responses

Contacts

Contacts and their portal access

List contacts

Authorizations:
(OAUTHTENANT)

Responses

Response samples

Content type
[
  • {
    }
]

Create contact. Access state is read-only here and silently ignored —

mutate it via PATCH /api/v1/users.

Authorizations:
(OAUTHTENANT)
Request Body schema:
required
email
required
string <email>

Email address. Input is trimmed; the domain is lowercased and IDN labels are punycoded. Empty string is the empty value.

link
required
string
name
required
string
phone
required
string <= 30 characters ^[0-9+()/ -]*$

Phone number. Input is lenient: unknown characters are dropped; the canonical form keeps digits and +-()/ .

position
required
string

Responses

Request samples

Content type
{
  • "email": "user@example.com",
  • "link": "string",
  • "name": "string",
  • "phone": "string",
  • "position": "string"
}

Response samples

Content type
{
  • "id": "string"
}

Update contact. Access state is read-only here and silently ignored.

Authorizations:
(OAUTHTENANT)
path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

Request Body schema:
required
email
required
string <email>

Email address. Input is trimmed; the domain is lowercased and IDN labels are punycoded. Empty string is the empty value.

link
required
string
name
required
string
phone
required
string <= 30 characters ^[0-9+()/ -]*$

Phone number. Input is lenient: unknown characters are dropped; the canonical form keeps digits and +-()/ .

position
required
string

Responses

Request samples

Content type
{
  • "email": "user@example.com",
  • "link": "string",
  • "name": "string",
  • "phone": "string",
  • "position": "string"
}

Delete contact

Authorizations:
(OAUTHTENANT)
path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

Responses

Invite contact as portal user

Authorizations:
(OAUTHTENANT)
path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

Responses

Download the contact picture

Authorizations:
(OAUTHTENANT)
path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

header Parameters
If-None-Match
string

Revalidation: a previously returned ETag; on a match the response is 304 Not Modified.

Responses

Set contact picture (any format; the server sniffs the type)

Authorizations:
(OAUTHTENANT)
path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

Request Body schema: */*
required

File upload; the filename is sent in the Content-Disposition header.

string <binary>

Responses

Clear the contact picture

Authorizations:
(OAUTHTENANT)
path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

Responses

Send password recovery to contact

Authorizations:
(OAUTHTENANT)
path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

Responses

Applications

Applicants and their lifecycle

List applications

Authorizations:
(OAUTHTENANT) (MACHINETENANT)
query Parameters
offset
integer [ 0 .. 4294967295 ]

Offset into the result list. Defaults to 0.

count
integer [ 0 .. 4294967295 ]

Maximum number of items to return. Defaults to 20.

object (ApplicationFilter)

Optional filter selectors in serde_qs deep-object form.

Responses

Response samples

Content type
{
  • "items": [
    ],
  • "offset": 0,
  • "total": 0
}

Create application. `Origin`/`Referer` (Referer preferred) populate the

stored application's origin URL.

Authorizations:
(OAUTHTENANT) (MACHINETENANT)
header Parameters
Origin
string
Referer
string
Request Body schema:
required
email
required
string <email>

Email address. Input is trimmed; the domain is lowercased and IDN labels are punycoded. Empty string is the empty value.

job_id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

location
required
string
name
required
string
phone
required
string <= 30 characters ^[0-9+()/ -]*$

Phone number. Input is lenient: unknown characters are dropped; the canonical form keeps digits and +-()/ .

Responses

Request samples

Content type
{
  • "email": "user@example.com",
  • "job_id": "string",
  • "location": "string",
  • "name": "string",
  • "phone": "string"
}

Response samples

Content type
{
  • "id": "string"
}

Get application

Authorizations:
(OAUTHTENANT) (MACHINETENANT)
path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

header Parameters
Accept-Language
string
Enum: "de" "en"

Response language; one of de, en. Absent or unsupported values fall back to de.

Responses

Response samples

Content type
{
  • "comment_count": 0,
  • "contact": "string",
  • "cv_present": true,
  • "date": "string",
  • "expected_salary": {
    },
  • "fitness": 1,
  • "group": 0,
  • "headhunting": true,
  • "job": "string",
  • "location": "string",
  • "name": "string",
  • "origin": {
    },
  • "qualified": true,
  • "rating": 1,
  • "status": "queued",
  • "tags": 0,
  • "phone": "string",
  • "attachments": [
    ],
  • "chat": [
    ],
  • "comments": [
    ],
  • "disability": "string",
  • "email": "string",
  • "events": [
    ],
  • "gender": "string",
  • "qualification": {
    },
  • "title": "string"
}

Apply action to application

Authorizations:
(OAUTHTENANT) (MACHINETENANT)
path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

Request Body schema:
required
One of
action
required
any
Value: "invite"
link
string

Responses

Request samples

Content type
{
  • "action": "updateJob",
  • "job": "string"
}

Delete application

Authorizations:
(OAUTHTENANT) (MACHINETENANT)
path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

Responses

Upload application attachment

Authorizations:
(OAUTHTENANT) (MACHINETENANT)
path Parameters
application_id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

filename
required
string
Request Body schema: */*
required
string <binary>

Responses

Download the application summary PDF.

Authorizations:
(OAUTHTENANT) (MACHINETENANT)
path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

Responses

Attachments

Attachment downloads

Download attachment. The transform header selects audio transcoding

(wav:pcm, webm:opus, mp4:aac) for audio/opus attachments.

Authorizations:
(OAUTHTENANT) (MACHINETENANT)
path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

header Parameters
X-JobBoard-FileTransform
string
If-None-Match
string

Revalidation: a previously returned ETag; on a match the response is 304 Not Modified.

Responses

Headhunting

Headhunting applications

Create headhunting application

Authorizations:
(OAUTHTENANT)
Request Body schema:
required
email
required
string <email>

Email address. Input is trimmed; the domain is lowercased and IDN labels are punycoded. Empty string is the empty value.

job_id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

location
required
string
name
required
string
phone
required
string <= 30 characters ^[0-9+()/ -]*$

Phone number. Input is lenient: unknown characters are dropped; the canonical form keeps digits and +-()/ .

Responses

Request samples

Content type
{
  • "email": "user@example.com",
  • "job_id": "string",
  • "location": "string",
  • "name": "string",
  • "phone": "string"
}

Response samples

Content type
{
  • "direct_entry_key": "string",
  • "id": "string"
}

Upload headhunting transcript (UTF-8 text)

Authorizations:
(OAUTHTENANT)
path Parameters
application_id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

Request Body schema: text/plain
required
string

Responses

Upload headhunting parsed CV

Authorizations:
(OAUTHTENANT)
path Parameters
application_id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

Request Body schema: */*
required
string <binary>

Responses

Embed

Embed widget configuration (authenticated)

Get embed widget configuration

Authorizations:
(OAUTHTENANT)

Responses

Response samples

Content type
{
  • "color": "string",
  • "cta": "string",
  • "fgcolor": "string",
  • "icon": "default",
  • "icon_id": "string",
  • "image": "string",
  • "language": "de",
  • "mode": "form",
  • "position": "bottom-left",
  • "round": 0.1,
  • "ai_context_info": "string",
  • "ai_instructions": "string"
}

Update embed widget configuration

Authorizations:
(OAUTHTENANT)
Request Body schema:
required
color
required
string^#[0-9a-f]{6}([0-9a-f]{2})?$

CSS color. Input accepts hex, rgb()/rgba(), hsl()/hsla(), and named colors; canonical form is lowercase hex with alpha only when not opaque.

cta
required
string <= 99 characters

Call-to-action label; at most 99 UTF-8 bytes.

fgcolor
required
string^#[0-9a-f]{6}([0-9a-f]{2})?$

CSS color. Input accepts hex, rgb()/rgba(), hsl()/hsla(), and named colors; canonical form is lowercase hex with alpha only when not opaque.

icon
required
string (EmbedIcon)
Enum: "default" "whatsapp" "custom"
icon_id
string <int64> (Id)

File id of the custom trigger-button icon ("0" when unset, never null). Read-only on PUT /api/v1/embed — mutate via PUT /api/v1/embed/icon.

image
string <int64> (Id)

File id of the about-us / hero image ("0" when unset, never null). Read-only on PUT /api/v1/embed — mutate via PUT /api/v1/embed/image.

language
required
string (EmbedLanguage)
Enum: "de" "en"
mode
required
string (EmbedMode)
Enum: "form" "whatsapp"
position
required
string (EmbedPosition)
Enum: "bottom-left" "bottom-right"
round
required
number <float>
ai_context_info
string
ai_instructions
string

Responses

Request samples

Content type
{
  • "color": "string",
  • "cta": "string",
  • "fgcolor": "string",
  • "icon": "default",
  • "icon_id": "string",
  • "image": "string",
  • "language": "de",
  • "mode": "form",
  • "position": "bottom-left",
  • "round": 0.1,
  • "ai_context_info": "string",
  • "ai_instructions": "string"
}

Download the embed widget icon

Authorizations:
(OAUTHTENANT)
header Parameters
If-None-Match
string

Revalidation: a previously returned ETag; on a match the response is 304 Not Modified.

Responses

Set embed widget icon (must be an SVG)

Authorizations:
(OAUTHTENANT)
Request Body schema: */*
required

File upload; the filename is sent in the Content-Disposition header.

string <binary>

Responses

Clear the embed widget icon

Authorizations:
(OAUTHTENANT)

Responses

Download the embed widget about-us image

Authorizations:
(OAUTHTENANT)
header Parameters
If-None-Match
string

Revalidation: a previously returned ETag; on a match the response is 304 Not Modified.

Responses

Set embed widget image (any format; the server sniffs the type)

Authorizations:
(OAUTHTENANT)
Request Body schema: */*
required

File upload; the filename is sent in the Content-Disposition header.

string <binary>

Responses

Clear the embed widget about-us image

Authorizations:
(OAUTHTENANT)

Responses

Users

Portal user access management

List portal users

Authorizations:
(OAUTHORG)

Responses

Response samples

Content type
[
  • {
    }
]

Update user access

Authorizations:
(OAUTHORG)
Request Body schema:
required
One of
user_id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

access
required
any
Value: "organization"

Responses

Request samples

Content type
{
  • "user_id": "string",
  • "access": "tenants",
  • "tenants": [
    ]
}

MachineKeys

Machine keys of the organization: the credentials unattended clients mint machine tokens from. Reachable with an OAuth token only, never with a machine token, so a key can neither issue nor revoke another.

Issue a machine key. The response carries the secret exactly once.

Authorizations:
(OAUTHORG)
Request Body schema:
required
One of
name
required
string

Shown in the key list and in the application event feed, so name it after the integration rather than the person.

level
required
string (MachineKeyLevel)
Enum: "read" "write"

What a machine key may do. A read key reaches every read operation of the interfaces that accept machine tokens and is refused on every mutation; a write key may additionally do what a full-write portal user may do. Neither is ever a superadmin.

string or null

End of validity. Absent means the key is valid until revoked.

integer or null

Multiplies the default per-key rate-limit buckets. Absent = defaults.

grant
required
any
Value: "organization"

Responses

Request samples

Content type
{
  • "name": "string",
  • "level": "read",
  • "expires_at": "string",
  • "rate_limit_factor": 0,
  • "grant": "tenants",
  • "tenants": [
    ]
}

Response samples

Content type
{
  • "key": {
    },
  • "secret": "string"
}

The organization's keys, without secrets, revoked ones included.

Authorizations:
(OAUTHORG)

Responses

Response samples

Content type
[
  • {
    }
]

Revoke a key. The row stays for audit; tokens already minted stop

verifying within the token validity cap.

Authorizations:
(OAUTHORG)
path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

Responses

Workspaces

Tenant administration

Create workspace

Authorizations:
(OAUTHORG)
Request Body schema:
required
name
required
string

Responses

Request samples

Content type
{
  • "name": "string"
}

Response samples

Content type
{
  • "id": "string"
}

Rename workspace

Authorizations:
(OAUTHTENANT)
Request Body schema:
required
name
required
string

Responses

Request samples

Content type
{
  • "name": "string"
}

Delete workspace

Authorizations:
(OAUTHTENANT)

Responses

Account

Identity and password change

Change password

Authorizations:
OAUTH
Request Body schema:
required
new_password
required
string
old_password
required
string

Responses

Request samples

Content type
{
  • "new_password": "string",
  • "old_password": "string"
}

Get current user identity and access

Authorizations:
OAUTH
query Parameters
thin
boolean

When set, omit logo data URIs and return a minimal payload

Responses

Response samples

Content type
{
  • "claims": {
    },
  • "organizations": [],
  • "tenants": []
}

WebChat

Web-chat widget configuration for the current tenant: appearance/behavior, allowed embed domains, and the logo + bot-avatar images.

Get the web-chat widget configuration.

Authorizations:
(OAUTHTENANT)

Responses

Response samples

Content type
{
  • "tenant_article": "string",
  • "title": "string",
  • "subtitle": "string",
  • "chatbot_display_name": "string",
  • "frame_color": "string",
  • "bot_color": "string",
  • "user_color": "string",
  • "text_color": "string",
  • "bot_avatar_bg_color": "string",
  • "show_academic_title": true,
  • "show_disability_question": true,
  • "show_scaleunit_footer": true,
  • "font_css_url": "string",
  • "font_family": "string",
  • "title_font_family": "string"
}

Update the web-chat widget configuration (the logo/avatar keep their

current images — set those via the image endpoints).

Authorizations:
(OAUTHTENANT)
Request Body schema:
required
tenant_article
required
string
title
required
string
subtitle
required
string
chatbot_display_name
required
string
frame_color
required
string^#[0-9a-f]{6}([0-9a-f]{2})?$

CSS color. Input accepts hex, rgb()/rgba(), hsl()/hsla(), and named colors; canonical form is lowercase hex with alpha only when not opaque.

bot_color
required
string^#[0-9a-f]{6}([0-9a-f]{2})?$

CSS color. Input accepts hex, rgb()/rgba(), hsl()/hsla(), and named colors; canonical form is lowercase hex with alpha only when not opaque.

user_color
required
string^#[0-9a-f]{6}([0-9a-f]{2})?$

CSS color. Input accepts hex, rgb()/rgba(), hsl()/hsla(), and named colors; canonical form is lowercase hex with alpha only when not opaque.

text_color
required
string^#[0-9a-f]{6}([0-9a-f]{2})?$

CSS color. Input accepts hex, rgb()/rgba(), hsl()/hsla(), and named colors; canonical form is lowercase hex with alpha only when not opaque.

string or null
show_academic_title
required
boolean
show_disability_question
required
boolean
show_scaleunit_footer
required
boolean
font_css_url
required
string
font_family
required
string
title_font_family
required
string

Responses

Request samples

Content type
{
  • "tenant_article": "string",
  • "title": "string",
  • "subtitle": "string",
  • "chatbot_display_name": "string",
  • "frame_color": "string",
  • "bot_color": "string",
  • "user_color": "string",
  • "text_color": "string",
  • "bot_avatar_bg_color": "string",
  • "show_academic_title": true,
  • "show_disability_question": true,
  • "show_scaleunit_footer": true,
  • "font_css_url": "string",
  • "font_family": "string",
  • "title_font_family": "string"
}

Get the domains allowed to embed the widget.

Authorizations:
(OAUTHTENANT)

Responses

Response samples

Content type
{
  • "domains": [
    ]
}

Set the domains allowed to embed the widget.

Authorizations:
(OAUTHTENANT)
Request Body schema:
required
domains
required
Array of strings

Responses

Request samples

Content type
{
  • "domains": [
    ]
}

Download the web-chat bot avatar.

Authorizations:
(OAUTHTENANT)
header Parameters
If-None-Match
string

Revalidation: a previously returned ETag; on a match the response is 304 Not Modified.

Responses

Set the web-chat bot avatar (any format; the server sniffs the type).

Authorizations:
(OAUTHTENANT)
Request Body schema: */*
required

File upload; the filename is sent in the Content-Disposition header.

string <binary>

Responses

Clear the web-chat bot avatar.

Authorizations:
(OAUTHTENANT)

Responses

Places

Google Places autocomplete proxy — for location fields. User-scoped (any authenticated caller); the Google API key stays server-side.

Autocomplete place suggestions for a free-text `input` (German locale).

Authorizations:
OAUTH
query Parameters
input
string

Responses

Response samples

Content type
[
  • {
    }
]

PublicEmbed

Public embed widget endpoints

Get public embed widget configuration

path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

Responses

Response samples

Content type
{
  • "color": "string",
  • "cta": "string",
  • "fgcolor": "string",
  • "icon": "string",
  • "imprint": "string",
  • "inbox": "string",
  • "job": "string",
  • "language": "de",
  • "mode": "form",
  • "name": "string",
  • "position": "bottom-left",
  • "privacy": "string",
  • "qrcode": "string",
  • "round": 0.1,
  • "walink": "string"
}

Get public embed about-us image

path Parameters
id
required
string <int64> (Id)

64-bit identifier serialized as a decimal string.

query Parameters
dpr
number <float>

Device pixel ratio (e.g. 2.0 for retina)

header Parameters
If-None-Match
string

Revalidation: a previously returned ETag; on a match the response is 304 Not Modified.

Responses

PasswordReset

Public password-reset flow: request the email, complete via the emailed link.

Request password reset email

Request Body schema:
required
email
required
string <email>

Email address. Input is trimmed; the domain is lowercased and IDN labels are punycoded. Empty string is the empty value.

Responses

Request samples

Content type
{
  • "email": "user@example.com"
}

Complete password reset: the new password is sent by email and the

browser is redirected to the fixed target (https://scaleunit.app). An unparseable token surfaces as 404, never 400.

path Parameters
uuid
required
string

Responses