{
  "openapi": "3.1.0",
  "info": {
    "title": "Careers Orbit management API",
    "version": "1",
    "summary": "Read and change jobs, applications and candidates from your own scripts and systems.",
    "description": "The management API is for your own scripts and other systems, such as an HR system that picks up new hires. It needs a management token (careers_mt_) and acts as the person who created it, with their current role and permissions. A read-only token gets 403 on every change. It is in the Growth and Enterprise plans.\n\nApplications and candidates come 50 at a time, or limit up to 100; when there are more, meta.next holds a cursor to send back as cursor. The job list comes in one answer. Answers are never cached. There is no endpoint to erase candidates or send emails.\n\nEach network may make 120 requests a minute with one token. Going over answers 429 rate_limited; no rate-limit headers are sent, so wait a minute and try again. Errors are { error: { code, message } }, with issues on 422.",
    "contact": {
      "name": "Bifröst Orbit",
      "url": "https://docs.bifrostorbit.com/",
      "email": "hello@bifrostorbit.com"
    },
    "termsOfService": "https://bifrostorbit.com/legal/terms/"
  },
  "servers": [
    {
      "url": "https://app.bifrostorbit.com/careers/api/v1",
      "description": "Production"
    },
    {
      "url": "https://stage.bifrostorbit.com/careers/api/v1",
      "description": "Staging"
    }
  ],
  "tags": [
    {
      "name": "Token",
      "description": "Who the token acts as."
    },
    {
      "name": "Jobs",
      "description": "Every job, and publishing or closing one."
    },
    {
      "name": "Pipelines",
      "description": "Stages and rejection reasons."
    },
    {
      "name": "Applications",
      "description": "Applications, moving and rejecting."
    },
    {
      "name": "Candidates",
      "description": "Candidates, tags and notes."
    }
  ],
  "externalDocs": {
    "url": "https://docs.bifrostorbit.com/careers/developers/management-api/",
    "description": "The management API guide"
  },
  "paths": {
    "/me": {
      "get": {
        "operationId": "me",
        "tags": [
          "Token"
        ],
        "summary": "Who the token is",
        "description": "The organisation, the person the token acts as, their role and their permissions.",
        "responses": {
          "200": {
            "description": "The token's person.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "object",
                      "properties": {
                        "organisation": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "name": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "id",
                            "name"
                          ]
                        },
                        "person": {
                          "type": "object",
                          "properties": {
                            "id": {
                              "type": "string"
                            },
                            "name": {
                              "type": "string"
                            },
                            "email": {
                              "type": "string"
                            }
                          },
                          "required": [
                            "id",
                            "name",
                            "email"
                          ]
                        },
                        "role": {
                          "type": "string"
                        },
                        "permissions": {
                          "type": "array",
                          "items": {
                            "type": "string"
                          }
                        }
                      },
                      "required": [
                        "organisation",
                        "person",
                        "role",
                        "permissions"
                      ]
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "organisation": {
                      "id": "6651a0c2b9e4c1d2e3f40a01",
                      "name": "Northwilds"
                    },
                    "person": {
                      "id": "6651a0c2b9e4c1d2e3f40f01",
                      "name": "Ingrid Berg",
                      "email": "ingrid.berg@northwilds.com"
                    },
                    "role": "recruiter",
                    "permissions": [
                      "jobs:write",
                      "jobs:publish",
                      "candidates:read",
                      "applications:move",
                      "applications:reject",
                      "messages:send",
                      "notes:write"
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "A missing, wrong, revoked or expired token, or a person who no longer has Careers Orbit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unauthorized",
                    "message": "This management token isn't valid. Create one under API keys in Careers Orbit."
                  }
                }
              }
            }
          },
          "403": {
            "description": "The token's person may not do this, the token is read-only, or the plan doesn't include the management API.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "You don't have permission to do that"
                  }
                }
              }
            }
          },
          "429": {
            "description": "More than 120 requests a minute from one network with one token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many tries. Wait a minute and try again."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Something failed on our side. Try again in a moment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "server_error",
                    "message": "Something went wrong on our side. Try again in a moment."
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "x-try-it": {
          "run": false,
          "reason": "Management tokens are secret; use them from a server or the API playground in Careers Orbit."
        }
      }
    },
    "/jobs": {
      "get": {
        "operationId": "listJobs",
        "tags": [
          "Jobs"
        ],
        "summary": "List jobs",
        "description": "Every job, drafts and closed ones too, most recently changed first, in one answer of up to 500 jobs. Not paged.",
        "parameters": [
          {
            "name": "status",
            "in": "query",
            "description": "open, or one of draft, inReview, published, internal, closed, archived.",
            "schema": {
              "type": "string"
            },
            "example": "published"
          }
        ],
        "responses": {
          "200": {
            "description": "The jobs.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Job"
                      }
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": [
                    {
                      "id": "6651a0c2b9e4c1d2e3f40b01",
                      "slug": "trip-guide-lofoten",
                      "status": "published",
                      "title": "Trip guide, Lofoten",
                      "employmentType": "temporary",
                      "remote": "onsite",
                      "departmentId": "6651a0c2b9e4c1d2e3f40a11",
                      "locationIds": [
                        "6651a0c2b9e4c1d2e3f40a21"
                      ],
                      "salary": {
                        "min": 42000,
                        "max": 48000,
                        "currency": "NOK",
                        "period": "month",
                        "shown": true
                      },
                      "ownerId": "6651a0c2b9e4c1d2e3f40f01",
                      "hiringTeam": [
                        "6651a0c2b9e4c1d2e3f40f01"
                      ],
                      "pipelineId": "6651a0c2b9e4c1d2e3f40a31",
                      "publishAt": null,
                      "closeAt": "2027-01-31T23:00:00.000Z",
                      "publishedAt": "2026-10-20T08:00:00.000Z",
                      "closedAt": null,
                      "createdAt": "2026-10-14T10:05:00.000Z",
                      "updatedAt": "2026-10-20T08:00:00.000Z"
                    }
                  ]
                }
              }
            }
          },
          "400": {
            "description": "An unknown status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid",
                    "message": "status must be open or one of draft, inReview, published, internal, closed, archived"
                  }
                }
              }
            }
          },
          "401": {
            "description": "A missing, wrong, revoked or expired token, or a person who no longer has Careers Orbit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unauthorized",
                    "message": "This management token isn't valid. Create one under API keys in Careers Orbit."
                  }
                }
              }
            }
          },
          "403": {
            "description": "The token's person may not do this, the token is read-only, or the plan doesn't include the management API.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "You don't have permission to do that"
                  }
                }
              }
            }
          },
          "429": {
            "description": "More than 120 requests a minute from one network with one token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many tries. Wait a minute and try again."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Something failed on our side. Try again in a moment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "server_error",
                    "message": "Something went wrong on our side. Try again in a moment."
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "x-try-it": {
          "run": false,
          "reason": "Management tokens are secret."
        }
      }
    },
    "/jobs/{jobId}": {
      "get": {
        "operationId": "getJob",
        "tags": [
          "Jobs"
        ],
        "summary": "Get a job",
        "description": "With its text in the main language, and translations holding only what differs in each other language.",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "description": "The job's id.",
            "schema": {
              "type": "string"
            },
            "example": "6651a0c2b9e4c1d2e3f40b01"
          }
        ],
        "responses": {
          "200": {
            "description": "The job.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Job"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "6651a0c2b9e4c1d2e3f40b01",
                    "slug": "trip-guide-lofoten",
                    "status": "published",
                    "title": "Trip guide, Lofoten",
                    "employmentType": "temporary",
                    "remote": "onsite",
                    "departmentId": "6651a0c2b9e4c1d2e3f40a11",
                    "locationIds": [
                      "6651a0c2b9e4c1d2e3f40a21"
                    ],
                    "salary": {
                      "min": 42000,
                      "max": 48000,
                      "currency": "NOK",
                      "period": "month",
                      "shown": true
                    },
                    "ownerId": "6651a0c2b9e4c1d2e3f40f01",
                    "hiringTeam": [
                      "6651a0c2b9e4c1d2e3f40f01"
                    ],
                    "pipelineId": "6651a0c2b9e4c1d2e3f40a31",
                    "publishAt": null,
                    "closeAt": "2027-01-31T23:00:00.000Z",
                    "publishedAt": "2026-10-20T08:00:00.000Z",
                    "closedAt": null,
                    "createdAt": "2026-10-14T10:05:00.000Z",
                    "updatedAt": "2026-10-20T08:00:00.000Z",
                    "summary": "Lead small groups on sea kayaking and ridge walks in Lofoten, from May to September.",
                    "description": "<p>You will guide groups of up to eight on our Lofoten sea kayaking and ridge walk trips.</p><ul><li>Kayak guide or mountain leader certificate</li><li>First aid at work</li></ul>",
                    "seoTitle": null,
                    "seoDescription": null,
                    "translations": {
                      "nb": {
                        "title": "Turleder, Lofoten"
                      }
                    }
                  }
                }
              }
            }
          },
          "401": {
            "description": "A missing, wrong, revoked or expired token, or a person who no longer has Careers Orbit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unauthorized",
                    "message": "This management token isn't valid. Create one under API keys in Careers Orbit."
                  }
                }
              }
            }
          },
          "403": {
            "description": "The token's person may not do this, the token is read-only, or the plan doesn't include the management API.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "You don't have permission to do that"
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such job.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Job was not found"
                  }
                }
              }
            }
          },
          "429": {
            "description": "More than 120 requests a minute from one network with one token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many tries. Wait a minute and try again."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Something failed on our side. Try again in a moment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "server_error",
                    "message": "Something went wrong on our side. Try again in a moment."
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "x-try-it": {
          "run": false,
          "reason": "Management tokens are secret."
        }
      }
    },
    "/jobs/{jobId}/status": {
      "post": {
        "operationId": "setJobStatus",
        "tags": [
          "Jobs"
        ],
        "summary": "Publish or close a job",
        "description": "Checks reviews, the job's required details and your plan's limit on live jobs, as Careers Orbit does.",
        "parameters": [
          {
            "name": "jobId",
            "in": "path",
            "required": true,
            "description": "The job's id.",
            "schema": {
              "type": "string"
            },
            "example": "6651a0c2b9e4c1d2e3f40b01"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "status": {
                    "type": "string",
                    "enum": [
                      "published",
                      "internal",
                      "closed",
                      "archived",
                      "draft"
                    ]
                  }
                },
                "required": [
                  "status"
                ]
              },
              "example": {
                "status": "closed"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The job.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Job"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "6651a0c2b9e4c1d2e3f40b01",
                    "slug": "trip-guide-lofoten",
                    "status": "closed",
                    "title": "Trip guide, Lofoten",
                    "employmentType": "temporary",
                    "remote": "onsite",
                    "departmentId": "6651a0c2b9e4c1d2e3f40a11",
                    "locationIds": [
                      "6651a0c2b9e4c1d2e3f40a21"
                    ],
                    "salary": {
                      "min": 42000,
                      "max": 48000,
                      "currency": "NOK",
                      "period": "month",
                      "shown": true
                    },
                    "ownerId": "6651a0c2b9e4c1d2e3f40f01",
                    "hiringTeam": [
                      "6651a0c2b9e4c1d2e3f40f01"
                    ],
                    "pipelineId": "6651a0c2b9e4c1d2e3f40a31",
                    "publishAt": null,
                    "closeAt": "2027-01-31T23:00:00.000Z",
                    "publishedAt": "2026-10-20T08:00:00.000Z",
                    "closedAt": "2026-11-02T09:30:00.000Z",
                    "createdAt": "2026-10-14T10:05:00.000Z",
                    "updatedAt": "2026-11-02T09:30:00.000Z",
                    "summary": "Lead small groups on sea kayaking and ridge walks in Lofoten, from May to September.",
                    "description": "<p>You will guide groups of up to eight on our Lofoten sea kayaking and ridge walk trips.</p><ul><li>Kayak guide or mountain leader certificate</li><li>First aid at work</li></ul>",
                    "seoTitle": null,
                    "seoDescription": null,
                    "translations": {
                      "nb": {
                        "title": "Turleder, Lofoten"
                      }
                    }
                  }
                }
              }
            }
          },
          "400": {
            "description": "The job is missing something it needs to go live.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid",
                    "message": "Choose at least one location, or make the job remote"
                  }
                }
              }
            }
          },
          "401": {
            "description": "A missing, wrong, revoked or expired token, or a person who no longer has Careers Orbit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unauthorized",
                    "message": "This management token isn't valid. Create one under API keys in Careers Orbit."
                  }
                }
              }
            }
          },
          "403": {
            "description": "The token's person may not publish, the job needs a review first, the plan's limit on live jobs is reached, or the token is read-only.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Job ads are reviewed before they go live here. Send it for review."
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such job.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Job was not found"
                  }
                }
              }
            }
          },
          "409": {
            "description": "The job is in the bin.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "conflict",
                    "message": "Restore the job from the bin first"
                  }
                }
              }
            }
          },
          "422": {
            "description": "An unknown status.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid",
                    "message": "Invalid option: expected one of \"published\"|\"internal\"|\"closed\"|\"archived\"|\"draft\""
                  },
                  "issues": [
                    {
                      "code": "invalid_value",
                      "path": [
                        "status"
                      ],
                      "message": "Invalid option: expected one of \"published\"|\"internal\"|\"closed\"|\"archived\"|\"draft\""
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "description": "More than 120 requests a minute from one network with one token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many tries. Wait a minute and try again."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Something failed on our side. Try again in a moment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "server_error",
                    "message": "Something went wrong on our side. Try again in a moment."
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "x-try-it": {
          "run": false,
          "reason": "It changes real jobs or candidates and can start automations that email them."
        }
      }
    },
    "/stages": {
      "get": {
        "operationId": "listStages",
        "tags": [
          "Pipelines"
        ],
        "summary": "List pipelines and stages",
        "description": "Pipelines with their stages and stage types, and the rejection reasons.",
        "responses": {
          "200": {
            "description": "The pipelines.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "id": {
                            "type": "string"
                          },
                          "name": {
                            "type": "string"
                          },
                          "isDefault": {
                            "type": "boolean"
                          },
                          "stages": {
                            "type": "array",
                            "items": {
                              "type": "object",
                              "properties": {
                                "id": {
                                  "type": "string"
                                },
                                "name": {
                                  "type": "string"
                                },
                                "type": {
                                  "type": "string"
                                },
                                "publicName": {
                                  "type": [
                                    "string",
                                    "null"
                                  ]
                                }
                              },
                              "required": [
                                "id",
                                "name",
                                "type",
                                "publicName"
                              ]
                            }
                          }
                        },
                        "required": [
                          "id",
                          "name",
                          "isDefault",
                          "stages"
                        ]
                      }
                    },
                    "rejectionReasons": {
                      "type": "array",
                      "items": {}
                    }
                  },
                  "required": [
                    "data",
                    "rejectionReasons"
                  ]
                },
                "example": {
                  "data": [
                    {
                      "id": "6651a0c2b9e4c1d2e3f40a31",
                      "name": "Guides",
                      "isDefault": true,
                      "stages": [
                        {
                          "id": "new",
                          "name": "New",
                          "type": "new",
                          "publicName": "Received"
                        },
                        {
                          "id": "screening",
                          "name": "Screening",
                          "type": "screening",
                          "publicName": "Being reviewed"
                        },
                        {
                          "id": "interview",
                          "name": "Interview",
                          "type": "interview",
                          "publicName": "Interviews"
                        },
                        {
                          "id": "offer",
                          "name": "Offer",
                          "type": "offer",
                          "publicName": "Offer"
                        },
                        {
                          "id": "hired",
                          "name": "Hired",
                          "type": "hired",
                          "publicName": "Hired"
                        },
                        {
                          "id": "rejected",
                          "name": "Not taken forward",
                          "type": "rejected",
                          "publicName": "Closed"
                        }
                      ]
                    }
                  ],
                  "rejectionReasons": [
                    {
                      "id": "experience",
                      "label": "Not enough relevant experience"
                    },
                    {
                      "id": "location",
                      "label": "Can't work where the job is"
                    },
                    {
                      "id": "other-candidate",
                      "label": "We chose another candidate"
                    }
                  ]
                }
              }
            }
          },
          "401": {
            "description": "A missing, wrong, revoked or expired token, or a person who no longer has Careers Orbit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unauthorized",
                    "message": "This management token isn't valid. Create one under API keys in Careers Orbit."
                  }
                }
              }
            }
          },
          "403": {
            "description": "The token's person may not do this, the token is read-only, or the plan doesn't include the management API.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "You don't have permission to do that"
                  }
                }
              }
            }
          },
          "429": {
            "description": "More than 120 requests a minute from one network with one token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many tries. Wait a minute and try again."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Something failed on our side. Try again in a moment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "server_error",
                    "message": "Something went wrong on our side. Try again in a moment."
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "x-try-it": {
          "run": false,
          "reason": "Management tokens are secret."
        }
      }
    },
    "/applications": {
      "get": {
        "operationId": "listApplications",
        "tags": [
          "Applications"
        ],
        "summary": "List applications",
        "description": "Newest first, without answers, 50 at a time: when meta.next isn't null, send it back as cursor for the next page.",
        "parameters": [
          {
            "name": "jobId",
            "in": "query",
            "description": "Only this job.",
            "schema": {
              "type": "string"
            },
            "example": "6651a0c2b9e4c1d2e3f40b01"
          },
          {
            "name": "status",
            "in": "query",
            "description": "active, rejected, withdrawn or hired.",
            "schema": {
              "type": "string",
              "enum": [
                "active",
                "rejected",
                "withdrawn",
                "hired"
              ]
            }
          },
          {
            "name": "stageId",
            "in": "query",
            "description": "Only this stage.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "updatedSince",
            "in": "query",
            "description": "Such as 2026-10-01T00:00:00Z.",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "50 unless you say, up to 100. Larger values are capped at 100.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "meta.next from the page before. Leave it out for the first page.",
            "schema": {
              "type": "string"
            },
            "example": "6651a0c2b9e4c1d2e3f40c01"
          }
        ],
        "responses": {
          "200": {
            "description": "A page.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Application"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "description": "Items a page."
                        },
                        "next": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Send as cursor for the next page. null on the last page."
                        }
                      },
                      "required": [
                        "limit",
                        "next"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                },
                "example": {
                  "data": [
                    {
                      "id": "6651a0c2b9e4c1d2e3f40c01",
                      "jobId": "6651a0c2b9e4c1d2e3f40b01",
                      "candidateId": "6651a0c2b9e4c1d2e3f40e01",
                      "stageId": "interview",
                      "stageType": "interview",
                      "status": "active",
                      "source": "website",
                      "sourceDetail": {
                        "utmSource": "newsletter",
                        "utmMedium": "email",
                        "utmCampaign": "summer-guides",
                        "referrer": "https://northwilds.com/"
                      },
                      "knockedOut": false,
                      "appliedAt": "2026-10-24T18:12:00.000Z",
                      "updatedAt": "2026-11-02T09:30:00.000Z"
                    }
                  ],
                  "meta": {
                    "limit": 50,
                    "next": null
                  }
                }
              }
            }
          },
          "400": {
            "description": "A cursor that isn't one, or updatedSince that isn't a date.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid",
                    "message": "The cursor isn't valid. Use meta.next from the page before."
                  }
                }
              }
            }
          },
          "401": {
            "description": "A missing, wrong, revoked or expired token, or a person who no longer has Careers Orbit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unauthorized",
                    "message": "This management token isn't valid. Create one under API keys in Careers Orbit."
                  }
                }
              }
            }
          },
          "403": {
            "description": "The token's person may not do this, the token is read-only, or the plan doesn't include the management API.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "You don't have permission to do that"
                  }
                }
              }
            }
          },
          "429": {
            "description": "More than 120 requests a minute from one network with one token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many tries. Wait a minute and try again."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Something failed on our side. Try again in a moment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "server_error",
                    "message": "Something went wrong on our side. Try again in a moment."
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "x-try-it": {
          "run": false,
          "reason": "Management tokens are secret."
        }
      }
    },
    "/applications/{applicationId}": {
      "get": {
        "operationId": "getApplication",
        "tags": [
          "Applications"
        ],
        "summary": "Get an application",
        "description": "With the candidate's answers and file ids. Recorded in the audit trail.",
        "parameters": [
          {
            "name": "applicationId",
            "in": "path",
            "required": true,
            "description": "The application's id.",
            "schema": {
              "type": "string"
            },
            "example": "6651a0c2b9e4c1d2e3f40c01"
          }
        ],
        "responses": {
          "200": {
            "description": "The application.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Application"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "6651a0c2b9e4c1d2e3f40c01",
                    "jobId": "6651a0c2b9e4c1d2e3f40b01",
                    "candidateId": "6651a0c2b9e4c1d2e3f40e01",
                    "stageId": "interview",
                    "stageType": "interview",
                    "status": "active",
                    "source": "website",
                    "sourceDetail": {
                      "utmSource": "newsletter",
                      "utmMedium": "email",
                      "utmCampaign": "summer-guides",
                      "referrer": "https://northwilds.com/"
                    },
                    "knockedOut": false,
                    "appliedAt": "2026-10-24T18:12:00.000Z",
                    "updatedAt": "2026-11-02T09:30:00.000Z",
                    "fields": {
                      "phone": "+47 912 34 567",
                      "coverLetter": "I have guided sea kayak trips around Lofoten for three summers.",
                      "linkedin": null,
                      "location": "Bodø",
                      "salaryExpectation": null,
                      "startDate": "2027-05-01"
                    },
                    "answers": [
                      {
                        "questionId": "certificate",
                        "kind": "choice",
                        "label": "Which guiding certificate do you hold?",
                        "value": "kayak"
                      },
                      {
                        "questionId": "season",
                        "kind": "yesNo",
                        "label": "Can you work the whole season, May to September?",
                        "value": true
                      }
                    ],
                    "rejection": null,
                    "withdrawal": null,
                    "cvFileId": "6651a0c2b9e4c1d2e3f40d01",
                    "fileIds": [
                      "6651a0c2b9e4c1d2e3f40d01"
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "A missing, wrong, revoked or expired token, or a person who no longer has Careers Orbit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unauthorized",
                    "message": "This management token isn't valid. Create one under API keys in Careers Orbit."
                  }
                }
              }
            }
          },
          "403": {
            "description": "The token's person may not do this, the token is read-only, or the plan doesn't include the management API.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "You don't have permission to do that"
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such application, or not one the token's person may read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Application was not found"
                  }
                }
              }
            }
          },
          "429": {
            "description": "More than 120 requests a minute from one network with one token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many tries. Wait a minute and try again."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Something failed on our side. Try again in a moment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "server_error",
                    "message": "Something went wrong on our side. Try again in a moment."
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "x-try-it": {
          "run": false,
          "reason": "Management tokens are secret."
        }
      }
    },
    "/applications/{applicationId}/move": {
      "post": {
        "operationId": "moveApplication",
        "tags": [
          "Applications"
        ],
        "summary": "Move to a stage",
        "description": "Runs the stage's automations, which may email the candidate. Moving to the rejected stage is refused: use reject.",
        "parameters": [
          {
            "name": "applicationId",
            "in": "path",
            "required": true,
            "description": "The application's id.",
            "schema": {
              "type": "string"
            },
            "example": "6651a0c2b9e4c1d2e3f40c01"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "stageId": {
                    "type": "string"
                  }
                },
                "required": [
                  "stageId"
                ]
              },
              "example": {
                "stageId": "interview"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The application.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Application"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "6651a0c2b9e4c1d2e3f40c01",
                    "jobId": "6651a0c2b9e4c1d2e3f40b01",
                    "candidateId": "6651a0c2b9e4c1d2e3f40e01",
                    "stageId": "interview",
                    "stageType": "interview",
                    "status": "active",
                    "source": "website",
                    "sourceDetail": {
                      "utmSource": "newsletter",
                      "utmMedium": "email",
                      "utmCampaign": "summer-guides",
                      "referrer": "https://northwilds.com/"
                    },
                    "knockedOut": false,
                    "appliedAt": "2026-10-24T18:12:00.000Z",
                    "updatedAt": "2026-11-02T09:30:00.000Z",
                    "fields": {
                      "phone": "+47 912 34 567",
                      "coverLetter": "I have guided sea kayak trips around Lofoten for three summers.",
                      "linkedin": null,
                      "location": "Bodø",
                      "salaryExpectation": null,
                      "startDate": "2027-05-01"
                    },
                    "answers": [
                      {
                        "questionId": "certificate",
                        "kind": "choice",
                        "label": "Which guiding certificate do you hold?",
                        "value": "kayak"
                      },
                      {
                        "questionId": "season",
                        "kind": "yesNo",
                        "label": "Can you work the whole season, May to September?",
                        "value": true
                      }
                    ],
                    "rejection": null,
                    "withdrawal": null,
                    "cvFileId": "6651a0c2b9e4c1d2e3f40d01",
                    "fileIds": [
                      "6651a0c2b9e4c1d2e3f40d01"
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "The stage isn't in the job's pipeline, or it is the rejected stage.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid",
                    "message": "That stage isn't in this job's pipeline. GET /stages lists them."
                  }
                }
              }
            }
          },
          "401": {
            "description": "A missing, wrong, revoked or expired token, or a person who no longer has Careers Orbit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unauthorized",
                    "message": "This management token isn't valid. Create one under API keys in Careers Orbit."
                  }
                }
              }
            }
          },
          "403": {
            "description": "The token's person may not do this, the token is read-only, or the plan doesn't include the management API.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "You don't have permission to do that"
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such application, or not one the token's person may read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Application was not found"
                  }
                }
              }
            }
          },
          "422": {
            "description": "No stageId.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid",
                    "message": "Send the stageId to move to"
                  },
                  "issues": [
                    {
                      "code": "invalid_type",
                      "path": [
                        "stageId"
                      ],
                      "message": "Send the stageId to move to"
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "description": "More than 120 requests a minute from one network with one token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many tries. Wait a minute and try again."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Something failed on our side. Try again in a moment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "server_error",
                    "message": "Something went wrong on our side. Try again in a moment."
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "x-try-it": {
          "run": false,
          "reason": "It changes real jobs or candidates and can start automations that email them."
        }
      }
    },
    "/applications/{applicationId}/reject": {
      "post": {
        "operationId": "rejectApplication",
        "tags": [
          "Applications"
        ],
        "summary": "Reject",
        "description": "With a reason from the stages endpoint, and an optional note for the team, up to 500 characters.",
        "parameters": [
          {
            "name": "applicationId",
            "in": "path",
            "required": true,
            "description": "The application's id.",
            "schema": {
              "type": "string"
            },
            "example": "6651a0c2b9e4c1d2e3f40c01"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "reasonId": {
                    "type": "string"
                  },
                  "note": {
                    "type": [
                      "string",
                      "null"
                    ],
                    "maxLength": 500
                  }
                },
                "required": [
                  "reasonId"
                ]
              },
              "example": {
                "reasonId": "other-candidate",
                "note": "Strong candidate; ask again next season."
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The application.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Application"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "6651a0c2b9e4c1d2e3f40c01",
                    "jobId": "6651a0c2b9e4c1d2e3f40b01",
                    "candidateId": "6651a0c2b9e4c1d2e3f40e01",
                    "stageId": "rejected",
                    "stageType": "rejected",
                    "status": "rejected",
                    "source": "website",
                    "sourceDetail": {
                      "utmSource": "newsletter",
                      "utmMedium": "email",
                      "utmCampaign": "summer-guides",
                      "referrer": "https://northwilds.com/"
                    },
                    "knockedOut": false,
                    "appliedAt": "2026-10-24T18:12:00.000Z",
                    "updatedAt": "2026-11-02T09:30:00.000Z",
                    "fields": {
                      "phone": "+47 912 34 567",
                      "coverLetter": "I have guided sea kayak trips around Lofoten for three summers.",
                      "linkedin": null,
                      "location": "Bodø",
                      "salaryExpectation": null,
                      "startDate": "2027-05-01"
                    },
                    "answers": [
                      {
                        "questionId": "certificate",
                        "kind": "choice",
                        "label": "Which guiding certificate do you hold?",
                        "value": "kayak"
                      },
                      {
                        "questionId": "season",
                        "kind": "yesNo",
                        "label": "Can you work the whole season, May to September?",
                        "value": true
                      }
                    ],
                    "rejection": {
                      "reasonId": "other-candidate",
                      "reason": "We chose another candidate",
                      "by": "6651a0c2b9e4c1d2e3f40f01",
                      "at": "2026-11-02T09:30:00.000Z"
                    },
                    "withdrawal": null,
                    "cvFileId": "6651a0c2b9e4c1d2e3f40d01",
                    "fileIds": [
                      "6651a0c2b9e4c1d2e3f40d01"
                    ]
                  }
                }
              }
            }
          },
          "400": {
            "description": "An unknown reason.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid",
                    "message": "Choose a reason"
                  }
                }
              }
            }
          },
          "401": {
            "description": "A missing, wrong, revoked or expired token, or a person who no longer has Careers Orbit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unauthorized",
                    "message": "This management token isn't valid. Create one under API keys in Careers Orbit."
                  }
                }
              }
            }
          },
          "403": {
            "description": "The token's person may not do this, the token is read-only, or the plan doesn't include the management API.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "You don't have permission to do that"
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such application, or not one the token's person may read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Application was not found"
                  }
                }
              }
            }
          },
          "422": {
            "description": "No reasonId, or a note that is too long.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid",
                    "message": "Send a reasonId from GET /stages"
                  },
                  "issues": [
                    {
                      "code": "invalid_type",
                      "path": [
                        "reasonId"
                      ],
                      "message": "Send a reasonId from GET /stages"
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "description": "More than 120 requests a minute from one network with one token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many tries. Wait a minute and try again."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Something failed on our side. Try again in a moment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "server_error",
                    "message": "Something went wrong on our side. Try again in a moment."
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "x-try-it": {
          "run": false,
          "reason": "It changes real jobs or candidates and can start automations that email them."
        }
      }
    },
    "/candidates": {
      "get": {
        "operationId": "listCandidates",
        "tags": [
          "Candidates"
        ],
        "summary": "List candidates",
        "description": "Newest first, 50 at a time: when meta.next isn't null, send it back as cursor for the next page. Recorded in the audit trail.",
        "parameters": [
          {
            "name": "q",
            "in": "query",
            "description": "Words in the name or email.",
            "schema": {
              "type": "string"
            },
            "example": "Nordmann"
          },
          {
            "name": "email",
            "in": "query",
            "description": "One exact address.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "tag",
            "in": "query",
            "description": "Only candidates with this tag.",
            "schema": {
              "type": "string"
            }
          },
          {
            "name": "limit",
            "in": "query",
            "description": "50 unless you say, up to 100. Larger values are capped at 100.",
            "schema": {
              "type": "integer",
              "minimum": 1,
              "maximum": 100,
              "default": 50
            }
          },
          {
            "name": "cursor",
            "in": "query",
            "description": "meta.next from the page before. Leave it out for the first page.",
            "schema": {
              "type": "string"
            },
            "example": "6651a0c2b9e4c1d2e3f40c01"
          }
        ],
        "responses": {
          "200": {
            "description": "A page.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Candidate"
                      }
                    },
                    "meta": {
                      "type": "object",
                      "properties": {
                        "limit": {
                          "type": "integer",
                          "description": "Items a page."
                        },
                        "next": {
                          "type": [
                            "string",
                            "null"
                          ],
                          "description": "Send as cursor for the next page. null on the last page."
                        }
                      },
                      "required": [
                        "limit",
                        "next"
                      ]
                    }
                  },
                  "required": [
                    "data",
                    "meta"
                  ]
                },
                "example": {
                  "data": [
                    {
                      "id": "6651a0c2b9e4c1d2e3f40e01",
                      "firstName": "Kari",
                      "lastName": "Nordmann",
                      "email": "kari.nordmann@northwilds.com",
                      "phone": "+47 912 34 567",
                      "location": "Bodø",
                      "links": [],
                      "tags": [
                        "Glacier certified"
                      ],
                      "talentPool": true,
                      "locale": "en",
                      "createdAt": "2026-10-24T18:12:00.000Z",
                      "lastActivityAt": "2026-11-02T09:30:00.000Z"
                    }
                  ],
                  "meta": {
                    "limit": 50,
                    "next": null
                  }
                }
              }
            }
          },
          "400": {
            "description": "A cursor that isn't one.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid",
                    "message": "The cursor isn't valid. Use meta.next from the page before."
                  }
                }
              }
            }
          },
          "401": {
            "description": "A missing, wrong, revoked or expired token, or a person who no longer has Careers Orbit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unauthorized",
                    "message": "This management token isn't valid. Create one under API keys in Careers Orbit."
                  }
                }
              }
            }
          },
          "403": {
            "description": "The token's person may not do this, the token is read-only, or the plan doesn't include the management API.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "You don't have permission to do that"
                  }
                }
              }
            }
          },
          "429": {
            "description": "More than 120 requests a minute from one network with one token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many tries. Wait a minute and try again."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Something failed on our side. Try again in a moment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "server_error",
                    "message": "Something went wrong on our side. Try again in a moment."
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "x-try-it": {
          "run": false,
          "reason": "Management tokens are secret."
        }
      }
    },
    "/candidates/{candidateId}": {
      "get": {
        "operationId": "getCandidate",
        "tags": [
          "Candidates"
        ],
        "summary": "Get a candidate",
        "description": "With the applications you may read. Recorded in the audit trail.",
        "parameters": [
          {
            "name": "candidateId",
            "in": "path",
            "required": true,
            "description": "The candidate's id.",
            "schema": {
              "type": "string"
            },
            "example": "6651a0c2b9e4c1d2e3f40e01"
          }
        ],
        "responses": {
          "200": {
            "description": "The candidate.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Candidate"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "6651a0c2b9e4c1d2e3f40e01",
                    "firstName": "Kari",
                    "lastName": "Nordmann",
                    "email": "kari.nordmann@northwilds.com",
                    "phone": "+47 912 34 567",
                    "location": "Bodø",
                    "links": [],
                    "tags": [
                      "Glacier certified"
                    ],
                    "talentPool": true,
                    "locale": "en",
                    "createdAt": "2026-10-24T18:12:00.000Z",
                    "lastActivityAt": "2026-11-02T09:30:00.000Z",
                    "applications": [
                      {
                        "id": "6651a0c2b9e4c1d2e3f40c01",
                        "jobId": "6651a0c2b9e4c1d2e3f40b01",
                        "stageId": "interview",
                        "status": "active",
                        "appliedAt": "2026-10-24T18:12:00.000Z"
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "A missing, wrong, revoked or expired token, or a person who no longer has Careers Orbit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unauthorized",
                    "message": "This management token isn't valid. Create one under API keys in Careers Orbit."
                  }
                }
              }
            }
          },
          "403": {
            "description": "The token's person may not do this, the token is read-only, or the plan doesn't include the management API.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "You don't have permission to do that"
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such candidate, or not one the token's person may read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Candidate was not found"
                  }
                }
              }
            }
          },
          "429": {
            "description": "More than 120 requests a minute from one network with one token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many tries. Wait a minute and try again."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Something failed on our side. Try again in a moment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "server_error",
                    "message": "Something went wrong on our side. Try again in a moment."
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "x-try-it": {
          "run": false,
          "reason": "Management tokens are secret."
        }
      }
    },
    "/candidates/{candidateId}/tags": {
      "post": {
        "operationId": "tagCandidate",
        "tags": [
          "Candidates"
        ],
        "summary": "Tag a candidate",
        "description": "A tag of up to 40 characters. remove: true takes the tag off.",
        "parameters": [
          {
            "name": "candidateId",
            "in": "path",
            "required": true,
            "description": "The candidate's id.",
            "schema": {
              "type": "string"
            },
            "example": "6651a0c2b9e4c1d2e3f40e01"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "tag": {
                    "type": "string",
                    "maxLength": 40
                  },
                  "remove": {
                    "type": "boolean"
                  }
                },
                "required": [
                  "tag"
                ]
              },
              "example": {
                "tag": "Glacier certified"
              }
            }
          }
        },
        "responses": {
          "200": {
            "description": "The candidate.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {
                      "$ref": "#/components/schemas/Candidate"
                    }
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "id": "6651a0c2b9e4c1d2e3f40e01",
                    "firstName": "Kari",
                    "lastName": "Nordmann",
                    "email": "kari.nordmann@northwilds.com",
                    "phone": "+47 912 34 567",
                    "location": "Bodø",
                    "links": [],
                    "tags": [
                      "Glacier certified"
                    ],
                    "talentPool": true,
                    "locale": "en",
                    "createdAt": "2026-10-24T18:12:00.000Z",
                    "lastActivityAt": "2026-11-02T09:30:00.000Z",
                    "applications": [
                      {
                        "id": "6651a0c2b9e4c1d2e3f40c01",
                        "jobId": "6651a0c2b9e4c1d2e3f40b01",
                        "stageId": "interview",
                        "status": "active",
                        "appliedAt": "2026-10-24T18:12:00.000Z"
                      }
                    ]
                  }
                }
              }
            }
          },
          "401": {
            "description": "A missing, wrong, revoked or expired token, or a person who no longer has Careers Orbit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unauthorized",
                    "message": "This management token isn't valid. Create one under API keys in Careers Orbit."
                  }
                }
              }
            }
          },
          "403": {
            "description": "The token's person may not do this, the token is read-only, or the plan doesn't include the management API.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "You don't have permission to do that"
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such candidate, or not one the token's person may read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Candidate was not found"
                  }
                }
              }
            }
          },
          "422": {
            "description": "No tag, or one that is too long.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid",
                    "message": "Send a tag"
                  },
                  "issues": [
                    {
                      "code": "invalid_type",
                      "path": [
                        "tag"
                      ],
                      "message": "Send a tag"
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "description": "More than 120 requests a minute from one network with one token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many tries. Wait a minute and try again."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Something failed on our side. Try again in a moment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "server_error",
                    "message": "Something went wrong on our side. Try again in a moment."
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "x-try-it": {
          "run": false,
          "reason": "It changes real jobs or candidates and can start automations that email them."
        }
      }
    },
    "/candidates/{candidateId}/notes": {
      "post": {
        "operationId": "addNote",
        "tags": [
          "Candidates"
        ],
        "summary": "Add a note",
        "description": "Mentions notify colleagues. With applicationId, the note belongs to that application.",
        "parameters": [
          {
            "name": "candidateId",
            "in": "path",
            "required": true,
            "description": "The candidate's id.",
            "schema": {
              "type": "string"
            },
            "example": "6651a0c2b9e4c1d2e3f40e01"
          }
        ],
        "requestBody": {
          "required": true,
          "content": {
            "application/json": {
              "schema": {
                "type": "object",
                "properties": {
                  "body": {
                    "type": "string",
                    "maxLength": 5000
                  },
                  "applicationId": {
                    "type": [
                      "string",
                      "null"
                    ]
                  }
                },
                "required": [
                  "body"
                ]
              },
              "example": {
                "body": "Strong on glacier safety. Ask about the Svartisen course in the interview.",
                "applicationId": "6651a0c2b9e4c1d2e3f40c01"
              }
            }
          }
        },
        "responses": {
          "201": {
            "description": "The note.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "data": {}
                  },
                  "required": [
                    "data"
                  ]
                },
                "example": {
                  "data": {
                    "type": "note",
                    "id": "6651a0c2b9e4c1d2e3f40e11",
                    "at": "2026-11-02T09:30:00.000Z",
                    "who": "Ingrid Berg",
                    "whoId": "6651a0c2b9e4c1d2e3f40f01",
                    "body": "Strong on glacier safety. Ask about the Svartisen course in the interview.",
                    "jobId": "6651a0c2b9e4c1d2e3f40b01",
                    "applicationId": "6651a0c2b9e4c1d2e3f40c01",
                    "drafted": null
                  }
                }
              }
            }
          },
          "401": {
            "description": "A missing, wrong, revoked or expired token, or a person who no longer has Careers Orbit.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "unauthorized",
                    "message": "This management token isn't valid. Create one under API keys in Careers Orbit."
                  }
                }
              }
            }
          },
          "403": {
            "description": "The token's person may not leave notes on this candidate, or the token is read-only.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "forbidden",
                    "message": "Your role doesn't let you leave notes on this candidate"
                  }
                }
              }
            }
          },
          "404": {
            "description": "No such candidate, or not one the token's person may read.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "not_found",
                    "message": "Candidate was not found"
                  }
                }
              }
            }
          },
          "422": {
            "description": "No body, or one over 5,000 characters.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "invalid",
                    "message": "Write the note in body"
                  },
                  "issues": [
                    {
                      "code": "invalid_type",
                      "path": [
                        "body"
                      ],
                      "message": "Write the note in body"
                    }
                  ]
                }
              }
            }
          },
          "429": {
            "description": "More than 120 requests a minute from one network with one token.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "rate_limited",
                    "message": "Too many tries. Wait a minute and try again."
                  }
                }
              }
            }
          },
          "500": {
            "description": "Something failed on our side. Try again in a moment.",
            "content": {
              "application/json": {
                "schema": {
                  "$ref": "#/components/schemas/Error"
                },
                "example": {
                  "error": {
                    "code": "server_error",
                    "message": "Something went wrong on our side. Try again in a moment."
                  }
                }
              }
            }
          }
        },
        "security": [
          {
            "bearer": []
          }
        ],
        "x-try-it": {
          "run": false,
          "reason": "It changes real jobs or candidates and can start automations that email them."
        }
      }
    }
  },
  "components": {
    "schemas": {
      "Error": {
        "type": "object",
        "description": "Every error has this shape. Write code against the status and code, never the message.",
        "properties": {
          "error": {
            "type": "object",
            "properties": {
              "code": {
                "type": "string",
                "description": "unauthorized, forbidden, not_found, subscription_inactive, invalid, conflict, rate_limited or server_error."
              },
              "message": {
                "type": "string",
                "description": "A message people can read. Messages meant for candidates follow their language where Careers Orbit has it; the rest are in English."
              }
            },
            "required": [
              "code",
              "message"
            ]
          },
          "issues": {
            "type": "array",
            "items": {},
            "description": "On 422: the fields that failed."
          }
        },
        "required": [
          "error"
        ]
      },
      "Job": {
        "type": "object",
        "description": "A job. The text fields only on one job.",
        "properties": {
          "id": {
            "type": "string"
          },
          "slug": {
            "type": "string"
          },
          "status": {
            "type": "string",
            "enum": [
              "draft",
              "inReview",
              "published",
              "internal",
              "closed",
              "archived"
            ]
          },
          "title": {
            "type": "string"
          },
          "summary": {
            "type": "string"
          },
          "description": {
            "type": "string"
          },
          "seoTitle": {
            "type": [
              "string",
              "null"
            ]
          },
          "seoDescription": {
            "type": [
              "string",
              "null"
            ]
          },
          "translations": {
            "type": "object",
            "additionalProperties": {},
            "description": "Only what differs, by language."
          },
          "employmentType": {
            "type": "string",
            "enum": [
              "fullTime",
              "partTime",
              "contract",
              "temporary",
              "internship",
              "apprenticeship",
              "workingStudent"
            ]
          },
          "remote": {
            "type": "string",
            "enum": [
              "onsite",
              "hybrid",
              "remote"
            ]
          },
          "departmentId": {
            "type": [
              "string",
              "null"
            ]
          },
          "locationIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "salary": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ]
          },
          "ownerId": {
            "type": [
              "string",
              "null"
            ]
          },
          "hiringTeam": {
            "type": "array",
            "items": {}
          },
          "pipelineId": {
            "type": [
              "string",
              "null"
            ]
          },
          "publishAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "closeAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "publishedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "closedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "createdAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "slug",
          "status",
          "title",
          "employmentType",
          "remote",
          "departmentId",
          "locationIds",
          "salary",
          "ownerId",
          "hiringTeam",
          "pipelineId",
          "publishAt",
          "closeAt",
          "publishedAt",
          "closedAt",
          "createdAt",
          "updatedAt"
        ]
      },
      "Application": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "jobId": {
            "type": "string"
          },
          "candidateId": {
            "type": "string"
          },
          "stageId": {
            "type": "string"
          },
          "stageType": {
            "type": [
              "string",
              "null"
            ]
          },
          "status": {
            "type": "string",
            "enum": [
              "active",
              "rejected",
              "withdrawn",
              "hired"
            ]
          },
          "source": {
            "type": "string"
          },
          "sourceDetail": {
            "type": [
              "object",
              "null"
            ],
            "description": "Where the candidate came from, when known.",
            "properties": {
              "utmSource": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "utmMedium": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "utmCampaign": {
                "type": [
                  "string",
                  "null"
                ]
              },
              "referrer": {
                "type": [
                  "string",
                  "null"
                ]
              }
            },
            "required": [
              "utmSource",
              "utmMedium",
              "utmCampaign",
              "referrer"
            ]
          },
          "knockedOut": {
            "type": "boolean",
            "description": "Failed a screening rule."
          },
          "fields": {
            "type": "object",
            "additionalProperties": {},
            "description": "On one application: the standard fields."
          },
          "answers": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "questionId": {
                  "type": "string"
                },
                "kind": {
                  "type": "string",
                  "enum": [
                    "text",
                    "longText",
                    "choice",
                    "multiChoice",
                    "yesNo",
                    "file",
                    "date",
                    "number"
                  ]
                },
                "label": {
                  "type": "string",
                  "description": "The question as it was asked."
                },
                "value": {
                  "description": "Text, a list of option ids, a number, yes or no as a boolean, or null."
                }
              },
              "required": [
                "questionId",
                "kind",
                "label",
                "value"
              ]
            },
            "description": "On one application: the answers, in the form's order."
          },
          "rejection": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ]
          },
          "withdrawal": {
            "anyOf": [
              {},
              {
                "type": "null"
              }
            ]
          },
          "cvFileId": {
            "type": [
              "string",
              "null"
            ]
          },
          "fileIds": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "appliedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "updatedAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "jobId",
          "candidateId",
          "stageId",
          "stageType",
          "status",
          "source",
          "sourceDetail",
          "knockedOut",
          "appliedAt",
          "updatedAt"
        ]
      },
      "Candidate": {
        "type": "object",
        "properties": {
          "id": {
            "type": "string"
          },
          "firstName": {
            "type": "string"
          },
          "lastName": {
            "type": "string"
          },
          "email": {
            "type": "string"
          },
          "phone": {
            "type": [
              "string",
              "null"
            ]
          },
          "location": {
            "type": [
              "string",
              "null"
            ]
          },
          "links": {},
          "tags": {
            "type": "array",
            "items": {
              "type": "string"
            }
          },
          "talentPool": {},
          "locale": {
            "type": [
              "string",
              "null"
            ]
          },
          "applications": {
            "type": "array",
            "items": {
              "type": "object",
              "properties": {
                "id": {
                  "type": "string"
                },
                "jobId": {
                  "type": "string"
                },
                "stageId": {
                  "type": "string"
                },
                "status": {
                  "type": "string"
                },
                "appliedAt": {
                  "type": [
                    "string",
                    "null"
                  ],
                  "format": "date-time"
                }
              },
              "required": [
                "id",
                "jobId",
                "stageId",
                "status",
                "appliedAt"
              ]
            },
            "description": "On one candidate."
          },
          "createdAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          },
          "lastActivityAt": {
            "type": [
              "string",
              "null"
            ],
            "format": "date-time"
          }
        },
        "required": [
          "id",
          "firstName",
          "lastName",
          "email",
          "phone",
          "location",
          "links",
          "tags",
          "talentPool",
          "locale",
          "createdAt",
          "lastActivityAt"
        ]
      }
    },
    "securitySchemes": {
      "bearer": {
        "type": "http",
        "scheme": "bearer",
        "description": "A management token, careers_mt_…. Keep it on a server."
      }
    }
  }
}
