Positions

Update a position

PATCH

/positions/{id}

Send only the fields you want to change.

teamId: null removes the team.
Sending questions replaces the whole list. To keep an existing question (and any image uploaded for it in the dashboard), include its id. Questions without an id are created as new.
analyzePrompt updates the instructions for AI analysis. It is never returned.

Path parameters

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

Example: "66f3a1c2e4b0a1d2c3e4f530"

Request body PositionInputrequired

namestringmin length 2max length 100
companyIdstringpattern ^[0-9a-fA-F]{24}$
Must be a company in your organization.
teamIdstring | nullpattern ^[0-9a-fA-F]{24}$
Must be a team in your organization. null means no team (on PATCH, it removes the team).
statusstring
Defaults to open on create.

Values: "open", "closed", "draft"
interviewConditionstringmax length 500
Instructions shown to the candidate before the interview.
questionsQuestionInput[]min items 1max items 15
On PATCH, this replaces the whole list. Include id to keep an existing question.
analyzePromptstringmax length 10000
Extra instructions for the AI analysis of this position's interviews. Write-only; it is never returned.

Responses

200

The updated position.

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": "Senior Warehouse Supervisor",
    "status": "closed",
    "companyId": "66f3a1c2e4b0a1d2c3e4f510",
    "teamId": null,
    "interviewCondition": "Answer in English or Thai.",
    "questions": [
      {
        "id": "66f3a1c2e4b0a1d2c3e4f531",
        "text": "Tell us about a time you led a team through a busy period (peak season).",
        "timeLimit": 4,
        "order": 1
      },
      {
        "id": "66f3a1c2e4b0a1d2c3e4f535",
        "text": "How would you onboard three new staff in one week?",
        "timeLimit": 2,
        "order": 2
      }
    ],
    "createdAt": "2026-09-20T08:15:00.000Z",
    "updatedAt": "2026-09-25T10:00:00.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
}