Positions

Get a position

GET

/positions/{id}

Path parameters

idstringrequiredpattern ^[0-9a-fA-F]{24}$
A 24-character hex ID.

Example: "66f3a1c2e4b0a1d2c3e4f530"

Responses

200

The position, with its questions sorted by order.

Body PositionResponse

dataPositionrequired
- 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
timestampinteger (int64)required
Server time in milliseconds since the Unix epoch.

Example

{
  "data": {
    "id": "66f3a1c2e4b0a1d2c3e4f530",
    "name": "Warehouse Supervisor",
    "status": "open",
    "companyId": "66f3a1c2e4b0a1d2c3e4f510",
    "teamId": null,
    "interviewCondition": null,
    "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"
  },
  "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
}

404

The resource doesn't exist, was cancelled, or belongs to another organization. The API never returns 403 for another organization's IDs.

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": "Interview not found",
  "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
}