Positions

Create a position

POST

/positions

Creates a position with its interview questions. status defaults to open, so you can invite candidates right away.

companyId (and teamId, if sent) must belong to your organization; otherwise the API returns 400.

Request body PositionInputrequired

namestringrequiredmin length 2max length 100
companyIdstringrequiredpattern ^[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[]requiredmin 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

201

The position was created.

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": "66f3a1c2e4b0a1d2c3e4f540",
    "name": "Data Engineer",
    "status": "open",
    "companyId": "66f3a1c2e4b0a1d2c3e4f510",
    "teamId": "66f3a1c2e4b0a1d2c3e4f520",
    "interviewCondition": "Please record in a quiet room.",
    "questions": [
      {
        "id": "66f3a1c2e4b0a1d2c3e4f541",
        "text": "Describe a data pipeline you built.",
        "timeLimit": 3,
        "order": 1
      },
      {
        "id": "66f3a1c2e4b0a1d2c3e4f542",
        "text": "How do you test data quality?",
        "timeLimit": 2,
        "order": 2
      }
    ],
    "createdAt": "2026-09-25T10:00: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
}

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
}