Advert Import API v4

This document describes the v4 API for publishing job adverts on individual job boards (target systems) for a vacancy that already exists in Teamio. The API exposes three operations:

• Order — publish a new advert (or a new add-on such as highlighting) for a vacancy on a given target system.
• Resume — resume a previously paused advert on a target system.
• Withdraw — withdraw an active advert from a target system.

The vacancy itself must first be created via the Vacancy Import API v4. The Advert Import API then orders publication for that vacancy on one or more target systems.

Base URL

https://integrations-api.teamio.com

Endpoints

Production (requires production credentials):

Test (requires test credentials):

Important: Production and test endpoints use separate credentials. The access token obtained from production credentials works only with production endpoints, and the token from test credentials works only with test endpoints. Both sets of credentials are available in Teamio integration settings  (login required).

Rate Limiting: Production endpoints enforce a rate limit of 10 requests per minute per company for each operation path (order, resume, and withdraw are limited separately). Test endpoints allow up to 50 requests per minute per company for each operation path. Requests exceeding the limit are rejected with HTTP 429.

Target Systems

The targetSystem field identifies the job board on which the advert is published.

Each target system supports a different set of provisions (see Provisions per Target System below). The selected target system must match the type of the underlying vacancy — for example, TW_CZ may only be used for temporary-work vacancies.

Provisions

A provision is the type of service to publish on the advert. The most common is ADVERT (the basic advert listing). Add-on provisions (highlighting, company introduction, logo, etc.) may be ordered together with the basic ADVERT, or separately later for an already published advert.

Provisions per Target System

Only the combinations listed below are accepted. Sending an unsupported combination results in HTTP 400 (Provision X is not supported for target system Y).

Ordering Add-ons Later

When you later add new add-on provisions to an advert that already has a published ADVERT presentation, send only the new provisions in orderItems. Do not repeat ADVERT — re-sending it on the same target system will return Bad request response.

Authentication

All requests require a JWT Bearer token obtained from the auth endpoint.

Obtaining a Token

Endpoint: POST /api/v1/auth/token

Note: Both production and test credentials are available in your Teamio integration settings  (login required). The password shown there is already Base64-encoded — copy and use it directly. Use production credentials to call production endpoints and test credentials to call test endpoints.

curl --location 'https://integrations-api.teamio.com/api/v1/auth/token' \
--header 'Content-Type: application/json' \
--data '{
    "username": "<from Teamio integration settings>",
    "password": "<from Teamio integration settings>"
}'

Response:

{
    "accessToken": "eyJhbGciOiJSUzI1NiIsInR5cCI6IkpXVCJ9...",
    "expiresAt": "2026-03-19T15:30:00.000Z",
    "tokenType": "Bearer"
}

Cache the token and reuse it until expiresAt. Do not request a new token for each API call.

Authentication Flow

Common Request Headers

For all advert endpoints:

• Authorization: Bearer <accessToken>
• Content-Type: application/json

The company identity is derived from the JWT token — there is no companyId field in the request body. The vacancy referenced by vacancyId must belong to the company derived from the token; otherwise HTTP 400 is returned with Advert for vacancy {id} does not belong to company {companyId}.

Order Advert

Endpoint: POST /api/import/v4/adverts/order (test: POST /api/import/test/v4/adverts/order)

Orders an advert (and/or add-ons) for an existing vacancy on a specified target system. If no advert exists yet for the (vacancy, target system) pair, one is created. If an advert already exists, the new provisions are added to it.

Fields marked with * are required.

Request Examples

Minimal — Required Fields Only

Order a basic advert presentation on Jobs.cz:

curl --location 'https://integrations-api.teamio.com/api/import/v4/adverts/order' \
--header 'Authorization: Bearer <accessToken>' \
--header 'Content-Type: application/json' \
--data '{
    "vacancyId": 2003358593,
    "targetSystem": "JOBS_CZ",
    "orderItems": [
        { "provision": "ADVERT" }
    ]
}'

Typical — Basic Advert with Highlighting

Order a basic advert presentation together with a highlighting add-on:

curl --location 'https://integrations-api.teamio.com/api/import/v4/adverts/order' \
--header 'Authorization: Bearer <accessToken>' \
--header 'Content-Type: application/json' \
--data '{
    "vacancyId": 2003358593,
    "targetSystem": "JOBS_CZ",
    "orderItems": [
        { "provision": "ADVERT" },
        { "provision": "HIGHLIGHTING" }
    ]
}'

Maximum — All Add-ons for JOBS_CZ

Order all provisions supported on Jobs.cz at once:

curl --location 'https://integrations-api.teamio.com/api/import/v4/adverts/order' \
--header 'Authorization: Bearer <accessToken>' \
--header 'Content-Type: application/json' \
--data '{
    "vacancyId": 2003358593,
    "targetSystem": "JOBS_CZ",
    "orderItems": [
        { "provision": "ADVERT" },
        { "provision": "HIGHLIGHTING" },
        { "provision": "INTRODUCTION" },
        { "provision": "LOGO_DETAIL" },
        { "provision": "PROGADMEDIA" }
    ]
}'

Adding an Add-on to an Existing Advert

When the basic ADVERT is already published, order only the new add-on:

curl --location 'https://integrations-api.teamio.com/api/import/v4/adverts/order' \
--header 'Authorization: Bearer <accessToken>' \
--header 'Content-Type: application/json' \
--data '{
    "vacancyId": 2003358593,
    "targetSystem": "PRACE_CZ",
    "orderItems": [
        { "provision": "HIGHLIGHTING" }
    ]
}'

Temporary Work Advert

Temporary-work vacancies (created with jobTypeIds = [201300004]) are published on the TW_CZ target system, which supports only the ADVERT provision:

curl --location 'https://integrations-api.teamio.com/api/import/v4/adverts/order' \
--header 'Authorization: Bearer <accessToken>' \
--header 'Content-Type: application/json' \
--data '{
    "vacancyId": 2003358600,
    "targetSystem": "TW_CZ",
    "orderItems": [
        { "provision": "ADVERT" }
    ]
}'

Response

HTTP Status: 200 OK on success. Error responses use HTTP 400/401/404/429 with RFC 7807 Problem Details  bodies — see Error Responses.

Example — Success Response (Production)

{
    "status": "OK",
    "vacancyId": 2003358593,
    "url": "https://www.jobs.cz/rpd/2003358593/",
    "orderItems": [
        {
            "provision": "ADVERT",
            "from": "2026-05-21",
            "to": "2026-06-20"
        },
        {
            "provision": "HIGHLIGHTING",
            "from": "2026-05-21",
            "to": "2026-05-24"
        }
    ],
    "processedAt": "2026-05-21T10:15:30.123Z"
}

Example — Test Response

The test endpoint validates the request without publishing the advert. The response echoes vacancyId, returns an empty orderItems array, and url is omitted.

{
    "status": "OK",
    "vacancyId": 2003358593,
    "orderItems": [],
    "processedAt": "2026-05-21T10:15:30.123Z"
}

Resume Advert

Endpoint: PUT /api/import/v4/adverts/resume (test: PUT /api/import/test/v4/adverts/resume)

Resumes a previously paused (e.g. manually withdrawn) advert on a target system. The advert must already exist for the (vacancy, target system) pair and must be a charged by resumable credit subscription.

Request Schema

Request Example

curl --location --request PUT \
'https://integrations-api.teamio.com/api/import/v4/adverts/resume' \
--header 'Authorization: Bearer <accessToken>' \
--header 'Content-Type: application/json' \
--data '{
    "vacancyId": 2003358593,
    "targetSystem": "JOBS_CZ"
}'

Response

HTTP Status: 200 OK on success. The response body example:

{
    "status": "OK",
    "vacancyId": 2003358593,
    "processedAt": "2026-06-03T10:51:04.699466763Z"
}

Both the production and the test endpoint return 200 OK — the test endpoint performs the same validation (auth, subscription, target system, advert existence and ownership) but does not actually resume the advert.

Withdraw Advert

Endpoint: PUT /api/import/v4/adverts/withdraw (test: PUT /api/import/test/v4/adverts/withdraw)

Withdraws an active advert from a target system. The advert must already exist for the (vacancy, target system) pair and must be in a state that allows withdrawal.

Request Schema

Request Example

curl --location --request PUT \
'https://integrations-api.teamio.com/api/import/v4/adverts/withdraw' \
--header 'Authorization: Bearer <accessToken>' \
--header 'Content-Type: application/json' \
--data '{
    "vacancyId": 2003358593,
    "targetSystem": "JOBS_CZ"
}'

Response

HTTP Status: 200 OK on success. The response body example:

{
    "status": "OK",
    "vacancyId": 2003358593,
    "processedAt": "2026-06-03T10:51:04.699466763Z"
}

Both the production and the test endpoint return 200 OK — the test endpoint validates the request without changing the advert state.

Error Responses

When an advert endpoint returns a non-success HTTP status, the response body follows the RFC 7807 Problem Details  format.

HTTP 400 — Bad Request

Returned for validation errors, unknown values, business-rule violations, and inactive subscription.

No active import service

{
    "title": "Bad Request",
    "status": 400,
    "detail": "Validation error occurred. Please check the error messages for details and correct the request accordingly.",
    "instance": "/api/import/v4/adverts/order",
    "messages": [
        {
          "type": "ERROR",
          "message": "Company does not have active import service."
        }
    ],
    "processedAt": "2026-05-26T11:31:21.014118734Z"
}

Invalid targetSystem

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation error occurred. Please check the error messages for details and correct the request accordingly.",
  "instance": "/api/import/v4/adverts/order",
  "messages": [
    {
      "type": "ERROR",
      "message": "Target system NO_SUCH_TARGET_SYSTEM is not allowed"
    }
  ],
  "processedAt": "2026-05-26T11:31:21.014118734Z"
}

Invalid provision

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation error occurred. Please check the error messages for details and correct the request accordingly.",
  "instance": "/api/import/v4/adverts/order",
  "messages": [
    {
      "type": "ERROR",
      "message": "Provision NO_SUCH_PROVISION is not allowed"
    }
  ],
  "processedAt": "2026-05-26T11:31:21.014118734Z"
}

Provision not supported for the chosen target system

For example, LOGO_DETAIL on ATMOSKOP_CZ:

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Validation error occurred. Please check the error messages for details and correct the request accordingly.",
  "instance": "/api/import/v4/adverts/order",
  "messages": [
    {
      "type": "ERROR",
      "message": "Provision LOGO_DETAIL is not supported for target system ATMOSKOP_CZ"
    }
  ],
  "processedAt": "2026-05-26T11:31:21.014118734Z"
}

Advert belongs to a different company

Returned when the vacancy referenced by vacancyId (and the advert ordered against it) does not belong to the company derived from the JWT token:

{
    "title": "Bad Request",
    "status": 400,
    "detail": "Validation error occurred. Please check the error messages for details and correct the request accordingly.",
    "instance": "/api/import/v4/adverts/order",
    "messages": [
        {
          "type": "ERROR",
          "message": "Vacancy 1234456 does not belong to company 001"
        }
    ],
    "processedAt": "2026-05-26T11:31:21.014118734Z"
}

Malformed JSON body

Returned when the request body cannot be parsed as JSON (e.g. truncated payload, wrong content type, syntax error).

{
  "title": "Bad Request",
  "status": 400,
  "detail": "Failed to read request",
  "instance": "/api/import/v4/adverts/order"
}

HTTP 401 — Unauthorized

Returned by the authentication layer when the Bearer token is missing, malformed, or expired. The response body may also include an upstream message such as:

Note: Both 401 (no/invalid Bearer token) and 400 with the “Authentication context is not valid” message indicate an authentication problem. Obtain a fresh token via POST /api/v1/auth/token.

HTTP 403 — Forbidden

Returned by Spring Security when the token is valid but does not carry the Cognito group required for the endpoint (GROUP_LIVE_VACANCY_IMPORT_API_WRITE for production endpoints, GROUP_SANDBOX_VACANCY_IMPORT_API_WRITE for test endpoints). No body is guaranteed.

HTTP 404 — Not Found

Vacancy not found

Returned when the vacancy referenced by vacancyId does not exist:

{
    "title": "Not Found",
    "status": 404,
    "detail": "Validation error occurred. Please check the error messages for details and correct the request accordingly.",
    "instance": "/api/import/v4/adverts/order",
    "messages": [
        {
          "type": "ERROR",
          "message": "Vacancy 1234 not found"
        }
    ],
    "processedAt": "2026-05-26T11:31:21.014118734Z"
}

Advert not found (resume and withdraw)

Returned when no advert exists for the given (vacancyId, targetSystem) pair:

{
    "title": "Not Found",
    "status": 404,
    "detail": "Validation error occurred. Please check the error messages for details and correct the request accordingly.",
    "instance": "/api/import/v4/adverts/resume",
    "messages": [
        {
          "type": "ERROR",
          "message": "Advert not found for vacancy 456 and target system PRACE_CZ"
        }
    ],
    "processedAt": "2026-05-26T11:31:21.014118734Z"
}

HTTP 429 — Too Many Requests

Returned when the per-company rate limit is exceeded (10 req/min for production endpoints, 50 req/min for test endpoints — applied per operation path). The rate-limit name in the message identifies which path was hit: advertOrder, advertResume, advertWithdraw on production and advertTestOrder, advertTestResume, advertTestWithdraw on test.

{
    "title": "Too Many Requests",
    "status": 429,
    "detail": "You have sent too many requests. Please try again later.",
    "instance": "/api/import/v4/adverts/order",
    "messages": [
        {
          "type": "ERROR",
          "message": "Rate limit exceeded for companyId=12345, rateLimitName=advertOrder. Allowed: 10 requests per minute."
        }
    ]
}

Counters are bucketed per one-minute wall-clock window — wait until the current minute resets before retrying. Consider adding retry logic with a back-off to handle this gracefully.

Common Validation Error Messages

Testing

Use the test endpoints to validate your payload before calling production. Test endpoints perform the same authentication, subscription, target-system, provision-compatibility, and ownership checks as production — but do not publish, resume, or withdraw any real adverts.

# Validate an order request
curl --location 'https://integrations-api.teamio.com/api/import/test/v4/adverts/order' \
--header 'Authorization: Bearer <accessToken>' \
--header 'Content-Type: application/json' \
--data '{
    "vacancyId": 2003358593,
    "targetSystem": "JOBS_CZ",
    "orderItems": [
        { "provision": "ADVERT" }
    ]
}'

On success the test order endpoint returns the same response shape as production but with an empty orderItems array and no url. The test resume and withdraw endpoints return 200 OK on success, identical to production.

Best Practices

1. Test before production — validate the request against the test endpoint first; production calls publish real adverts and consume credit.
2. Cache auth tokens — reuse tokens until expiresAt to avoid unnecessary auth calls. The same token works across all advert operations.
3. Order add-ons separately — when adding a new add-on to an already published advert, send only the new provision; do not re-send ADVERT on the same target system.
4. Respect the support matrix — verify the (targetSystem, provision) combination before sending; an unsupported combination is rejected as 400.
5. Handle 429 with back-off — implement retry logic that respects the per-minute rate limit (10 req/min production, 50 req/min test, per endpoint).
6. Use credentials as-is — the password in Teamio integration settings is already Base64-encoded; copy and use it directly.
7. Keep credentials secure — never log or commit credentials or tokens to version control.