Quickstart

This quickstart verifies the complete integration path without requiring a persistent write.

Prerequisites

Access to JobHandy Administration
Portal permission IT, HR, or Company-Admin to create a key
A dedicated API key with the required company and division scope
A server-side runtime that can store secrets securely

Create an API key first

Create and securely store a scoped credential before running the protected examples.

1. Check public availability

curl --request GET \
  --url 'https://api.jobhandy.io/v1/health'

A successful response proves that the public API endpoint is reachable. It does not validate your API key, tenant scope, or access to protected resources.

2. Generate a request ID

Use a new UUID v4 or v7 for each logical attempt. The API echoes a supplied ID or generates one when omitted.

X-Request-ID: {{requestId}}

X-Request-ID is for correlation only. It is not an idempotency key.

3. List employees

curl --request GET \
  --url 'https://api.jobhandy.io/v1/employees?page=1&pageSize=10' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Request-ID: {{requestId}}'

const requestId = crypto.randomUUID();
const response = await fetch(
  'https://api.jobhandy.io/v1/employees?page=1&pageSize=10',
  {
    headers: {
      'X-API-Key': process.env.JOBHANDY_API_KEY,
      'X-Request-ID': requestId,
    },
  },
);
const payload = await response.json();
console.log(response.status, response.headers.get('x-request-id'), payload);

import os
import uuid
import requests

request_id = str(uuid.uuid4())
response = requests.get(
    'https://api.jobhandy.io/v1/employees',
    params={'page': 1, 'pageSize': 10},
    headers={
        'X-API-Key': os.environ['JOBHANDY_API_KEY'],
        'X-Request-ID': request_id,
    },
    timeout=30,
)
print(response.status_code, response.headers.get('X-Request-ID'))
response.raise_for_status()
print(response.json())

$requestId = [guid]::NewGuid().ToString()
$headers = @{
    'X-API-Key'    = $env:JOBHANDY_API_KEY
    'X-Request-ID' = $requestId
}
Invoke-RestMethod `
    -Method Get `
    -Uri 'https://api.jobhandy.io/v1/employees?page=1&pageSize=10' `
    -Headers $headers

4. Narrow to one tenant when required

If the key covers multiple companies, add the tenant ID returned by JobHandy resources or supplied during integration onboarding:

X-Tenant-ID: {{tenantId}}

Omit the header when you intentionally need a collection across all tenants in scope. See Tenant scope.

5. Test filter quoting

curl --get 'https://api.jobhandy.io/v1/employees' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data-urlencode 'filter=lastName="van Example"'

The raw filter expression is URL-encoded by the HTTP client. Values containing whitespace must be quoted.

6. Validate a write without persistence

Use a supported write operation with dryRun=true. The example below validates an employee update but does not save it:

curl --request PATCH \
  --url 'https://api.jobhandy.io/v1/employees/EMPLOYEE_ID?dryRun=true' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --header 'X-Request-ID: {{requestId}}' \
  --data '{"phoneNumber":"+49 221 1234567"}'

A successful dry run returns the projected employee. It does not reserve state; the real write can still fail if the resource changes between validation and persistence.

7. Recognize an error response

{
  "error": {
    "code": "TENANT_NOT_IN_SCOPE",
    "message": "The selected tenant is not available to this API key.",
    "requestId": "{{requestId}}"
  }
}

Use error.code for program logic, error.message for diagnostics, and error.requestId for logs and support.

Success criteria

You have completed the quickstart when all of the following are true:

GET /health returns successfully
a protected request authenticates with your API key
tenant selection behaves as expected for the key scope
the response includes or echoes X-Request-ID
a quoted filter returns a valid collection response
a supported dry run returns a projection without changing data
your logs contain no API key or unnecessary personal data

Prepare for production

Complete the security, retry, reconciliation, monitoring, and operational controls before enabling a schedule.

Get Started

Architecture & Concepts

Integration Guides

Operations

Prerequisites

Create an API key first

1. Check public availability

2. Generate a request ID

3. List employees

4. Narrow to one tenant when required

5. Test filter quoting

6. Validate a write without persistence

7. Recognize an error response

Success criteria

Prepare for production

​Prerequisites

Create an API key first

​1. Check public availability

​2. Generate a request ID

​3. List employees

​4. Narrow to one tenant when required

​5. Test filter quoting

​6. Validate a write without persistence

​7. Recognize an error response

​Success criteria

Prepare for production

Prerequisites

1. Check public availability

2. Generate a request ID

3. List employees

4. Narrow to one tenant when required

5. Test filter quoting

6. Validate a write without persistence

7. Recognize an error response

Success criteria