Positions

List positions

GET

/positions

Positions in your organization, newest first.

Query parameters

pageintegermin 1
Page number, starting at 1.

Default: 1
limitintegermin 1max 100
Items per page.

Default: 20
statusstring
Only return positions with this status.

Values: "open", "closed", "draft"

Responses

200

A page of positions.

Body object

dataPosition[]required
- idstringrequiredpattern ^[0-9a-fA-F]{24}$
  A 24-character hex ID.
- namestringrequired
- statusstringrequired
  Only open positions accept new invites.
  
  Values: "open", "closed", "draft"
- companyIdstringrequiredpattern ^[0-9a-fA-F]{24}$
  A 24-character hex ID.
- teamIdstring | nullrequired
- interviewConditionstring | nullrequired
  Instructions shown to the candidate before the interview.
- questionsQuestion[]required
  Sorted by order.
- createdAtstring (date-time) | nullrequired
- updatedAtstring (date-time) | nullrequired
metaPaginationMetarequired
- totalintegerrequired
  Total number of matching items.
- pageintegerrequiredmin 1
- limitintegerrequiredmin 1max 100
- totalPagesintegerrequired
  ceil(total / limit). It is 0 when there are no results.
timestampinteger (int64)required
Server time in milliseconds since the Unix epoch.

Example

{
  "data": [
    {
      "id": "66f3a1c2e4b0a1d2c3e4f530",
      "name": "Warehouse Supervisor",
      "status": "open",
      "companyId": "66f3a1c2e4b0a1d2c3e4f510",
      "teamId": "66f3a1c2e4b0a1d2c3e4f521",
      "interviewCondition": "Answer in English or Thai.",
      "questions": [
        {
          "id": "66f3a1c2e4b0a1d2c3e4f531",
          "text": "Tell us about a time you led a team through a busy period.",
          "timeLimit": 3,
          "order": 1
        },
        {
          "id": "66f3a1c2e4b0a1d2c3e4f532",
          "text": "How do you keep a warehouse safe?",
          "timeLimit": 2,
          "order": 2
        }
      ],
      "createdAt": "2026-09-20T08:15:00.000Z",
      "updatedAt": "2026-09-22T03:40:12.000Z"
    }
  ],
  "meta": {
    "total": 1,
    "page": 1,
    "limit": 20,
    "totalPages": 1
  },
  "timestamp": 1790330400000
}

400

The request is invalid. message is the first validation error.

Body Error

successbooleanrequired
Values: false
messagestringrequired
A human-readable error message.
timestampinteger (int64)required
Server time in milliseconds since the Unix epoch.

Example

{
  "success": false,
  "message": "limit must be between 1 and 100",
  "timestamp": 1790330400000
}

401

The API key is missing, malformed, invalid or revoked.

Body Error

successbooleanrequired
Values: false
messagestringrequired
A human-readable error message.
timestampinteger (int64)required
Server time in milliseconds since the Unix epoch.

{
  "success": false,
  "message": "API key is required. Send it as 'Authorization: Bearer <key>'",
  "timestamp": 1790330400000
}

403

API access is disabled for your organization (any endpoint), or, when creating an invite, your organization has no active subscription or no interview credits left.

Body Error

successbooleanrequired
Values: false
messagestringrequired
A human-readable error message.
timestampinteger (int64)required
Server time in milliseconds since the Unix epoch.

{
  "success": false,
  "message": "API access is not enabled for this organization",
  "timestamp": 1790330400000
}

429

Too many requests. Wait for Retry-After seconds (or the reset value in RateLimit), then retry.

Headers

RateLimitstring
Draft-7 rate limit state, e.g. limit=120, remaining=0, reset=42 (reset is in seconds).
RateLimit-Policystring
Draft-7 rate limit policy: the limit and the window in seconds.
Retry-Afterinteger
Seconds to wait before retrying.

Body Error

successbooleanrequired
Values: false
messagestringrequired
A human-readable error message.
timestampinteger (int64)required
Server time in milliseconds since the Unix epoch.

Example

{
  "success": false,
  "message": "Too many requests. Retry after the number of seconds in the RateLimit header.",
  "timestamp": 1790330400000
}