List orders

List orders

curl --request GET \
  --url https://api.jobhandy.io/v1/orders \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

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

using RestSharp;


var options = new RestClientOptions("https://api.jobhandy.io/v1/orders");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("X-API-Key", "<api-key>");
var response = await client.GetAsync(request);

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

{
  "page": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalElements": 1,
  "items": [
    {
      "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
      }
    }
  ]
}

GET

https://api.jobhandy.io/v1

orders

List orders

curl --request GET \
  --url https://api.jobhandy.io/v1/orders \
  --header 'X-API-Key: <api-key>'

const options = {method: 'GET', headers: {'X-API-Key': '<api-key>'}};

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

using RestSharp;


var options = new RestClientOptions("https://api.jobhandy.io/v1/orders");
var client = new RestClient(options);
var request = new RestRequest("");
request.AddHeader("X-API-Key", "<api-key>");
var response = await client.GetAsync(request);

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

{
  "page": 1,
  "pageSize": 100,
  "totalPages": 1,
  "totalElements": 1,
  "items": [
    {
      "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; omit to query all authorized tenants
Dry run	Not supported
Request body	None
Response	JSON
Primary success	`200`
Side effects	None beyond reading or downloading the authorized resource
Retry guidance	Transient read failures are generally safe to retry with bounded backoff

Operational behavior

Lists orders in the API key’s scope. Filter and sort fields: id, status, employee, orderNumber, createdAt, updatedAt, contractDurationInMonths, contractStartDate, contractEndDate.

Use status=under_review to retrieve work that is eligible for the public HR decision flow.

Common errors

Error code	Meaning
`VALIDATION_ERROR`	Schema or business validation failed
`INVALID_REQUEST_ID`	X-Request-ID is not UUID v4 or v7
`UNKNOWN_QUERY_PARAMETER`	Query parameter is not supported
`INVALID_FILTER_SYNTAX`	Filter expression cannot be parsed
`UNSUPPORTED_FILTER_FIELD`	Filter field is not supported
`UNSUPPORTED_FILTER_OPERATOR`	Operator is not supported for the field
`UNSUPPORTED_SORT_FIELD`	Sort field is not supported
`INVALID_API_KEY`	Missing, invalid, deleted, or inactive API key
`TENANT_NOT_IN_SCOPE`	Selected tenant is outside API-key scope
`NOT_ACCEPTABLE`	Requested response media type is unavailable
`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

Restricts results to one tenant in the API key's scope. Omit the header to query all tenants in scope. 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}$

Query Parameters

page

integer

inactive

optional

server default: 1

not sent by default

One-based page number. When omitted, the server uses 1.

Required range: x >= 1Must be a multiple of 1

Example:

1

pageSize

integer

inactive

optional

server default: 100

not sent by default

Number of resources per page. When omitted, the server uses 100.

Required range: 1 <= x <= 1000Must be a multiple of 1

Example:

100

sort

string

inactive

optional

not sent by default

One endpoint-supported public scalar field. Prefix with - for descending order. Multiple fields and whitespace are rejected. Null values sort first in ascending order and last in descending order.

filter

string

inactive

optional

not sent by default

Expression over endpoint-supported public scalar fields. Operators: =, !=, >, >=, <, <=, IN (...), CONTAINS, STARTS_WITH, ENDS_WITH, IS NULL, IS NOT NULL. AND binds before OR; parentheses override precedence. Whitespace outside quoted values is ignored. String comparisons are case-insensitive. String values may be unquoted, single-quoted, or double-quoted. Values containing whitespace must be enclosed in single or double quotes. An apostrophe may be escaped as ' in either quote style; the escape backslash is not part of the matched value. Nested, object, and array fields are rejected. Examples show decoded filter expressions; URL-encode the query parameter value when constructing a raw URL.

createdAtFrom

string<date-time>

inactive

optional

not sent by default

Inclusive lower bound for createdAt. Must be an ISO-8601 UTC timestamp ending in Z.

Pattern: Z$

Example:

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

createdAtTo

string<date-time>

inactive

optional

not sent by default

Inclusive upper bound for createdAt. Must be an ISO-8601 UTC timestamp ending in Z.

Pattern: Z$

Example:

"2026-12-31T23:59:59.999Z"

Response

A page of orders.

One page of orders.

page

integer

required

Current one-based page number.

Must be a multiple of 1

Example:

1

pageSize

integer

required

Maximum number of resources returned per page.

Must be a multiple of 1

Example:

100

totalPages

integer

required

Number of available pages.

Must be a multiple of 1

Example:

1

totalElements

integer

required

Number of resources matching the request.

Must be a multiple of 1

Example:

2

items

object[]

required

Orders on the current page.

Show child attributes

Last modified on August 28, 2026

Overview

Data Models

Specification

At a glance

Operational behavior

Common errors

Before implementation

Related integration guidance

Authorizations

Headers

Query Parameters

Response

​At a glance

​Operational behavior

​Common errors

​Before implementation

Related integration guidance

Authorizations

Headers

Query Parameters

Response

At a glance

Operational behavior

Common errors

Before implementation