Approve or reject an order

cURL

curl --request POST \
  --url 'https://api.jobhandy.io/v1/orders/ORDER_ID/decision?dryRun=true' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data '{"decision":"approved"}'

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({decision: 'approved'})
};

fetch('https://api.jobhandy.io/v1/orders/{id}/decision', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.jobhandy.io/v1/orders/{id}/decision"

payload = { "decision": "approved" }
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

using RestSharp;


var options = new RestClientOptions("https://api.jobhandy.io/v1/orders/{id}/decision");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("X-API-Key", "<api-key>");
request.AddJsonBody("{\n  \"decision\": \"approved\"\n}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

$headers=@{}
$headers.Add("X-API-Key", "<api-key>")
$headers.Add("Content-Type", "application/json")
$response = Invoke-WebRequest -Uri 'https://api.jobhandy.io/v1/orders/{id}/decision' -Method POST -Headers $headers -ContentType 'application/json' -Body '{
  "decision": "approved"
}'

{
  "id": "69eb125feddfff1d13676751",
  "status": "approved",
  "employee": "68a000000000000000000001",
  "orderNumber": 10495,
  "createdAt": "2026-07-01T10:00:00.000Z",
  "updatedAt": "2026-07-02T12:15:00.000Z",
  "products": [
    {
      "id": "69eb125feddfff1d13676761",
      "label": "Example Smartphone, 256 GB, Black, New",
      "model": "Example Smartphone",
      "vatRate": "19.00",
      "manufacturerName": "Example Manufacturer",
      "articleGroupName": "smartphones",
      "grossAmount": "34.99",
      "netAmount": "29.4034",
      "service": false,
      "grossService": null,
      "netService": null,
      "isAccessory": false
    },
    {
      "id": "69eb125feddfff1d13676762",
      "label": "Example Protective Case",
      "model": "Example Protective Case",
      "vatRate": "19.00",
      "manufacturerName": "Example Manufacturer",
      "articleGroupName": "accessories",
      "grossAmount": "3.99",
      "netAmount": "3.3529",
      "service": null,
      "grossService": null,
      "netService": null,
      "isAccessory": true
    }
  ],
  "deliveryAddress": {
    "firstName": "Alex",
    "lastName": "Morgan",
    "street": "Example Street 12",
    "postalCode": "50667",
    "city": "Cologne",
    "countryCode": "DE"
  },
  "contractDurationInMonths": 24,
  "contractStartDate": "2026-08-01T00:00:00.000Z",
  "contractEndDate": "2028-07-31T23:59:59.999Z",
  "attachments": [
    {
      "id": "contract.10495.1",
      "type": "nuev"
    },
    {
      "id": "contract.10495.2",
      "type": "emv"
    }
  ],
  "hrHistory": {
    "approvedBy": null,
    "approvedAt": "2026-07-02T12:15:00.000Z",
    "rejectedBy": null,
    "rejectedAt": null,
    "requestedAt": "2026-07-01T10:00:00.000Z",
    "decisionBy": null
  }
}

POST

https://api.jobhandy.io/v1

orders

{id}

decision

cURL

curl --request POST \
  --url 'https://api.jobhandy.io/v1/orders/ORDER_ID/decision?dryRun=true' \
  --header 'Content-Type: application/json' \
  --header 'X-API-Key: YOUR_API_KEY' \
  --data '{"decision":"approved"}'

const options = {
  method: 'POST',
  headers: {'X-API-Key': '<api-key>', 'Content-Type': 'application/json'},
  body: JSON.stringify({decision: 'approved'})
};

fetch('https://api.jobhandy.io/v1/orders/{id}/decision', options)
  .then(res => res.json())
  .then(res => console.log(res))
  .catch(err => console.error(err));

import requests

url = "https://api.jobhandy.io/v1/orders/{id}/decision"

payload = { "decision": "approved" }
headers = {
    "X-API-Key": "<api-key>",
    "Content-Type": "application/json"
}

response = requests.post(url, json=payload, headers=headers)

print(response.text)

using RestSharp;


var options = new RestClientOptions("https://api.jobhandy.io/v1/orders/{id}/decision");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("X-API-Key", "<api-key>");
request.AddJsonBody("{\n  \"decision\": \"approved\"\n}", false);
var response = await client.PostAsync(request);

Console.WriteLine("{0}", response.Content);

$headers=@{}
$headers.Add("X-API-Key", "<api-key>")
$headers.Add("Content-Type", "application/json")
$response = Invoke-WebRequest -Uri 'https://api.jobhandy.io/v1/orders/{id}/decision' -Method POST -Headers $headers -ContentType 'application/json' -Body '{
  "decision": "approved"
}'

{
  "id": "69eb125feddfff1d13676751",
  "status": "approved",
  "employee": "68a000000000000000000001",
  "orderNumber": 10495,
  "createdAt": "2026-07-01T10:00:00.000Z",
  "updatedAt": "2026-07-02T12:15:00.000Z",
  "products": [
    {
      "id": "69eb125feddfff1d13676761",
      "label": "Example Smartphone, 256 GB, Black, New",
      "model": "Example Smartphone",
      "vatRate": "19.00",
      "manufacturerName": "Example Manufacturer",
      "articleGroupName": "smartphones",
      "grossAmount": "34.99",
      "netAmount": "29.4034",
      "service": false,
      "grossService": null,
      "netService": null,
      "isAccessory": false
    },
    {
      "id": "69eb125feddfff1d13676762",
      "label": "Example Protective Case",
      "model": "Example Protective Case",
      "vatRate": "19.00",
      "manufacturerName": "Example Manufacturer",
      "articleGroupName": "accessories",
      "grossAmount": "3.99",
      "netAmount": "3.3529",
      "service": null,
      "grossService": null,
      "netService": null,
      "isAccessory": true
    }
  ],
  "deliveryAddress": {
    "firstName": "Alex",
    "lastName": "Morgan",
    "street": "Example Street 12",
    "postalCode": "50667",
    "city": "Cologne",
    "countryCode": "DE"
  },
  "contractDurationInMonths": 24,
  "contractStartDate": "2026-08-01T00:00:00.000Z",
  "contractEndDate": "2028-07-31T23:59:59.999Z",
  "attachments": [
    {
      "id": "contract.10495.1",
      "type": "nuev"
    },
    {
      "id": "contract.10495.2",
      "type": "emv"
    }
  ],
  "hrHistory": {
    "approvedBy": null,
    "approvedAt": "2026-07-02T12:15:00.000Z",
    "rejectedBy": null,
    "rejectedAt": null,
    "requestedAt": "2026-07-01T10:00:00.000Z",
    "decisionBy": null
  }
}

At a glance

Property	Behavior
Authentication	Required in X-API-Key
Tenant context	Optional narrowing; resource and references must remain in scope
Dry run	Supported with dryRun=true
Request body	application/json; closed schema; maximum documented body 5 MiB
Response	JSON
Primary success	`200`
Side effects	Applies the HR decision and corresponding notifications; dry run suppresses both
Retry guidance	Re-read the order; a final decision may already have been applied

Operational behavior

Approves or rejects an order that is under HR review. Approval applies the documented contract date defaults and sends the corresponding notifications. With dryRun=true, the API returns the projected order without applying the decision or sending notifications.

Only an order in under_review is eligible for this public decision operation.
A final decision cannot be overwritten through this endpoint.
After timeout, re-read the order before any retry.

Common errors

Error code	Meaning
`VALIDATION_ERROR`	Schema or business validation failed
`INVALID_REQUEST_ID`	X-Request-ID is not UUID v4 or v7
`INVALID_API_KEY`	Missing, invalid, deleted, or inactive API key
`TENANT_NOT_IN_SCOPE`	Selected tenant is outside API-key scope
`NOT_FOUND`	Resource is absent or not accessible in scope
`NOT_ACCEPTABLE`	Requested response media type is unavailable
`ORDER_ALREADY_DECIDED`	Order already has a final HR decision
`INVALID_STATE_TRANSITION`	Current lifecycle state does not permit the request
`PAYLOAD_TOO_LARGE`	Complete request exceeds the documented limit
`UNSUPPORTED_MEDIA_TYPE`	Request media type is not accepted
`RATE_LIMIT_EXCEEDED`	API-key rate limit was exceeded
`INTERNAL_SERVER_ERROR`	Unexpected server failure

The operation response list and Error handling page are authoritative for complete handling.

Before implementation

Generate and log a new X-Request-ID for the attempt.
Handle every documented response status.
Do not log X-API-Key or unnecessary personal data.
Reconcile current resource state before replaying an ambiguous write.

Related integration guidance

Review the complete process, state, retry, and operational pattern for this operation.

Authorizations

X-API-Key

string

header

required

JobHandy integration API key. Send the credential in the X-API-Key header. Treat the key as a secret and use it only from trusted server-side environments.

Headers

X-Tenant-ID

string

inactive

optional

not sent by default

Narrows the operation to one tenant in the API key's scope. Any referenced or target resource must be accessible through that tenant. In interactive clients, use the {{tenantId}} variable when a tenant must be selected. Keep the header disabled when tenant selection is not required.

Pattern: ^[0-9a-fA-F]{24}$

X-Request-ID

string<uuid>

inactive

optional

not sent by default

Optional request identifier. If supplied, it must be a UUID v4 or v7 and is returned unchanged in every response. If omitted, the API generates one. Invalid values return 400 INVALID_REQUEST_ID. If your client uses a {{requestId}} variable, refresh it with a new UUID version 4 or 7 for every HTTP request attempt. Keep the header disabled to let the API generate the request identifier.

Pattern: ^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[47][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$

Path Parameters

string

required

Order ID.

Pattern: ^[0-9a-fA-F]{24}$

Example:

"69eb125feddfff1d13676751"

Query Parameters

dryRun

boolean

inactive

optional

server default: false

not sent by default

When true, the API validates the request without applying the change. The operation's responses specify the returned representation. When omitted, the server uses false.

Example:

true

Body

application/json

The JSON request body must not exceed 5,242,880 bytes.

Approval or rejection to record for an order under HR review.

decision

enum<string>

required

Target decision. Values are case-sensitive.

Available options:

approved,

rejected

Minimum string length: 1

Response

Returns the decided order, or the projected order when dryRun=true.

Order details.

string

required

read-only

Unique order identifier.

Pattern: ^[0-9a-fA-F]{24}$

Example:

"69eb125feddfff1d13676751"

status

enum<string>

required

read-only

Current order lifecycle status. Values are case-sensitive.

Available options:

under_review,

rejected,

approved,

active,

archived,

withdrawn

Minimum string length: 1

Example:

"approved"

employee

string

required

Identifier of the employee who placed or owns the order.

Pattern: ^[0-9a-fA-F]{24}$

Example:

"68a000000000000000000001"

orderNumber

integer

required

read-only

Human-readable numeric order number.

Must be a multiple of 1

Example:

10495

createdAt

string<date-time>

required

read-only

UTC timestamp at which the order was created.

Minimum string length: 1

Pattern: Z$

Example:

"2026-07-01T10:00:00.000Z"

updatedAt

string<date-time>

required

read-only

UTC timestamp of the latest order update.

Minimum string length: 1

Pattern: Z$

Example:

"2026-07-02T12:15:00.000Z"

products

object[]

required

Products and accessories included in the order.

Show child attributes

deliveryAddress

object | null

required

nullable

Delivery address for the order, or null when no delivery address is available.

Show child attributes

Example:

{
  "firstName": "Alex",
  "lastName": "Morgan",
  "street": "Example Street 12",
  "postalCode": "50667",
  "city": "Cologne",
  "countryCode": "DE"
}

hrHistory

object

required

HR review request and decision history.

Show child attributes

Example:

{
  "approvedBy": null,
  "approvedAt": "2026-07-02T12:15:00.000Z",
  "rejectedBy": null,
  "rejectedAt": null,
  "requestedAt": "2026-07-01T10:05:00.000Z",
  "decisionBy": null
}

contractDurationInMonths

number | null

required

nullable

Contract duration in whole months, or null when not determined.

Must be a multiple of 1

Example:

24

contractStartDate

string<date-time> | null

required

nullable

UTC contract start date, or null when not determined.

Minimum string length: 1

Pattern: Z$

Example:

"2026-08-01T00:00:00.000Z"

contractEndDate

string<date-time> | null

required

nullable

UTC contract end date, or null when not determined.

Minimum string length: 1

Pattern: Z$

Example:

"2028-07-31T23:59:59.999Z"

attachments

object[]

required

Order contract documents available through the order attachment download endpoint.

Show child attributes

Last modified on August 27, 2026

Overview

Data Models

Specification

At a glance

Operational behavior

Common errors

Before implementation

Related integration guidance

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response

​At a glance

​Operational behavior

​Common errors

​Before implementation

Related integration guidance

Authorizations

Headers

Path Parameters

Query Parameters

Body

Response

At a glance

Operational behavior

Common errors

Before implementation