# List all jobs.

Returns a list of jobs for an authorized company, sorted by last updated date, newest first.
The endpoint supports pagination.
The endpoint requires the `personio:recruiting:read` scope.

> 🚧 Warning
>
> This endpoint is in beta, and may be subject to change.
> Please report any bugs to [Help & Feedback](https://support.personio.de/hc/en-us/articles/5659436229277-Help-Feedback) section.

# OpenAPI definition

```json
{
  "openapi": "3.0.3",
  "info": {
    "title": "Recruiting (Beta)",
    "description": "Collection of endpoints to manage recruiting applications.",
    "version": "2.0.0"
  },
  "servers": [
    {
      "url": "https://api.personio.de"
    }
  ],
  "security": [
    {
      "BearerAuth": []
    }
  ],
  "paths": {
    "/v2/recruiting/jobs": {
      "get": {
        "summary": "List all jobs.",
        "description": "Returns a list of jobs for an authorized company, sorted by last updated date, newest first.\nThe endpoint supports pagination.\nThe endpoint requires the `personio:recruiting:read` scope.\n\n> 🚧 Warning\n>\n> This endpoint is in beta, and may be subject to change.\n> Please report any bugs to [Help & Feedback](https://support.personio.de/hc/en-us/articles/5659436229277-Help-Feedback) section.",
        "tags": [
          "Jobs"
        ],
        "parameters": [
          {
            "in": "query",
            "name": "limit",
            "required": false,
            "schema": {
              "example": 100,
              "type": "integer",
              "minimum": 1,
              "maximum": 200,
              "default": 100
            },
            "description": "The amount of resources to be returned per one request. It can range between 1 and 200,  and the default is 100."
          },
          {
            "in": "query",
            "name": "cursor",
            "example": "cur_82sQwR2eZvKilo2duNh219Kw",
            "required": false,
            "schema": {
              "type": "string"
            },
            "description": "The pagination cursor to navigate over to the next list of resources. If you pass a specific limit to your  request, or you rely on the default value of the number of resources to be returned, then your subsequent call has to include the cursor in order to retrieve the next list of resources. If cursor is missing,  the first page is returned."
          },
          {
            "description": "Return jobs updated before given time.\nMutually exclusive with `updated_at.gt`.",
            "name": "updated_at.lt",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "description": "Return jobs updated after given time.\nMutually exclusive with `updated_at.lt`.",
            "name": "updated_at.gt",
            "required": false,
            "in": "query",
            "schema": {
              "type": "string",
              "format": "date-time"
            }
          },
          {
            "description": "As this is a Beta endpoint, the Beta header must be provided with the value `true`.",
            "name": "Beta",
            "in": "header",
            "schema": {
              "type": "string",
              "example": "true"
            }
          }
        ],
        "x-path-examples": {
          "200 List all jobs": {
            "value": "/v2/recruiting/jobs"
          },
          "200 List all jobs with non-default limit": {
            "value": "/v2/recruiting/jobs",
            "query": "limit=150"
          },
          "200 List all jobs after given date": {
            "value": "/v2/recruiting/jobs",
            "query": "updated_at.gt=2025-02-20T13:19:40"
          },
          "200 List all jobs before given date": {
            "value": "/v2/recruiting/jobs",
            "query": "updated_at.lt=2025-02-20T13:19:40"
          },
          "200 List jobs by cursor": {
            "value": "/v2/recruiting/jobs",
            "query": "cursor=cur_15sdwf2eIvLilN2dKFh211Js"
          },
          "400 List jobs using wrong pagination value": {
            "value": "/v2/recruiting/jobs",
            "query": "limit=400"
          }
        },
        "responses": {
          "200": {
            "description": "Successful response.",
            "content": {
              "application/json": {
                "schema": {
                  "type": "object",
                  "properties": {
                    "_data": {
                      "type": "array",
                      "items": {
                        "$ref": "#/components/schemas/Job"
                      }
                    },
                    "_meta": {
                      "$ref": "#/components/schemas/Job/properties/_meta"
                    }
                  }
                },
                "examples": {
                  "200 List all jobs": {
                    "$ref": "#/components/examples/JobListResponse"
                  },
                  "200 List all jobs with non-default limit": {
                    "$ref": "#/components/examples/JobListResponse"
                  },
                  "200 List all jobs after given date": {
                    "$ref": "#/components/examples/JobListResponse"
                  },
                  "200 List all jobs before given date": {
                    "$ref": "#/components/examples/JobListResponse"
                  },
                  "200 List jobs by cursor": {
                    "$ref": "#/components/examples/JobListByCursorResponse"
                  }
                }
              }
            }
          },
          "400": {
            "description": "Bad request.",
            "content": {
              "application/problem+json": {
                "schema": {
                  "type": "object",
                  "description": "This object represents an error response.",
                  "properties": {
                    "personio_trace_id": {
                      "type": "string",
                      "example": "aswo3f-a202lfso-312123sld-1230ddd",
                      "description": "A unique ID that was created for this error."
                    },
                    "timestamp": {
                      "type": "string",
                      "format": "date-time",
                      "example": "2021-05-28T11:17:30.000Z",
                      "description": "The timestamp of when the error occurred."
                    },
                    "errors": {
                      "type": "array",
                      "items": {
                        "type": "object",
                        "properties": {
                          "title": {
                            "type": "string",
                            "example": "Not found",
                            "description": "The title of the error."
                          },
                          "detail": {
                            "type": "string",
                            "example": "The requested resource was not found.",
                            "description": "A short description about the error."
                          },
                          "type": {
                            "type": "string",
                            "format": "uri",
                            "example": "https://developer.personio.de/reference/errors#common.requested_resource_not_found",
                            "description": "A link to the developer hub where more information can be found for the encountered error."
                          },
                          "_meta": {
                            "type": "object",
                            "additionalProperties": {
                              "type": "string"
                            }
                          }
                        }
                      }
                    }
                  }
                },
                "examples": {
                  "400 List jobs using wrong pagination value": {
                    "$ref": "#/components/examples/InvalidFilterValue"
                  }
                }
              }
            }
          }
        }
      }
    }
  },
  "components": {
    "securitySchemes": {
      "BearerAuth": {
        "type": "http",
        "scheme": "bearer",
        "bearerFormat": "JWT"
      }
    },
    "schemas": {
      "CategoryRef": {
        "description": "The job category minimalized object.",
        "type": "object",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "description": "The unique identifier of a job category.",
            "readOnly": true,
            "type": "string",
            "example": "324"
          },
          "name": {
            "description": "The name of a job category.",
            "readOnly": true,
            "type": "string",
            "example": "Technology Position"
          },
          "_meta": {
            "$ref": "#/components/schemas/Job/properties/_meta"
          }
        }
      },
      "CompanyRef": {
        "description": "The company object.",
        "type": "object",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "description": "The unique identifier of a company.",
            "readOnly": true,
            "type": "string",
            "example": "324"
          },
          "_meta": {
            "$ref": "#/components/schemas/Job/properties/_meta"
          }
        }
      },
      "DepartmentRef": {
        "description": "The company department object.",
        "type": "object",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "description": "The unique identifier of a department.",
            "readOnly": true,
            "type": "string",
            "example": "324"
          },
          "name": {
            "description": "The name of a department.",
            "readOnly": true,
            "type": "string",
            "example": "HR"
          },
          "_meta": {
            "$ref": "#/components/schemas/Job/properties/_meta"
          }
        }
      },
      "Job": {
        "description": "Recruiting job object.",
        "type": "object",
        "required": [
          "id",
          "name",
          "company"
        ],
        "properties": {
          "id": {
            "description": "The unique identifier of a Job.",
            "type": "string",
            "readOnly": true,
            "example": "9823749"
          },
          "department": {
            "$ref": "#/components/schemas/DepartmentRef"
          },
          "company": {
            "$ref": "#/components/schemas/CompanyRef"
          },
          "name": {
            "description": "Job title.",
            "readOnly": true,
            "type": "string",
            "example": "Software Developer"
          },
          "category": {
            "$ref": "#/components/schemas/CategoryRef"
          },
          "hiring_team": {
            "description": "List of hiring team members assigned to the job.",
            "type": "array",
            "items": {
              "$ref": "#/components/schemas/HiringTeamMember"
            }
          },
          "created_at": {
            "description": "Creation date of a job.",
            "readOnly": true,
            "type": "object",
            "required": [
              "date-time",
              "timezone"
            ],
            "properties": {
              "date-time": {
                "type": "string",
                "description": "Timestamp with UTC offset.",
                "format": "date-time"
              },
              "timezone": {
                "type": "string",
                "description": "Provide a time zone ID that conforms to the [Time Zone Database](https://www.iana.org/time-zones).",
                "example": "Europe/Berlin"
              }
            }
          },
          "updated_at": {
            "description": "Last modification date of a job.",
            "readOnly": true,
            "type": "object",
            "required": [
              "date-time",
              "timezone"
            ],
            "properties": {
              "date-time": {
                "type": "string",
                "description": "Timestamp with UTC offset.",
                "format": "date-time"
              },
              "timezone": {
                "type": "string",
                "description": "Provide a time zone ID that conforms to the [Time Zone Database](https://www.iana.org/time-zones).",
                "example": "Europe/Berlin"
              }
            }
          },
          "_meta": {
            "description": "This object represents the metadata information for an object. It's a set of arbitrary key/value attributes such as `links`.",
            "type": "object",
            "readOnly": true,
            "properties": {
              "links": {
                "type": "object",
                "additionalProperties": {
                  "description": "This objects represents a hyperlink.",
                  "type": "object",
                  "readOnly": true,
                  "properties": {
                    "href": {
                      "type": "string",
                      "format": "uri"
                    }
                  },
                  "additionalProperties": true
                },
                "example": {
                  "links": {
                    "self": {
                      "href": "https://api.personio.de/v2/person?cursor=<current-cursor>"
                    }
                  }
                }
              }
            }
          }
        }
      },
      "HiringTeamMember": {
        "description": "Hiring team member object.",
        "type": "object",
        "required": [
          "person",
          "role"
        ],
        "properties": {
          "person": {
            "$ref": "#/components/schemas/PersonRef"
          },
          "role": {
            "$ref": "#/components/schemas/RecruitingRoleRef"
          }
        }
      },
      "PersonRef": {
        "description": "The person object.",
        "type": "object",
        "required": [
          "id"
        ],
        "properties": {
          "id": {
            "description": "The unique identifier of a person.",
            "readOnly": true,
            "type": "string",
            "example": "324"
          },
          "_meta": {
            "$ref": "#/components/schemas/Job/properties/_meta"
          }
        }
      },
      "RecruitingRoleRef": {
        "description": "The recruiting role object.",
        "type": "object",
        "required": [
          "name"
        ],
        "properties": {
          "name": {
            "description": "The name of a role.",
            "readOnly": true,
            "type": "string",
            "example": "HR manager"
          }
        }
      }
    },
    "examples": {
      "InvalidFilterValue": {
        "value": {
          "personio_trace_id": "aswo3f-a202lfso-312123sld-1230ddd",
          "timestamp": "2021-05-28T11:17:30+00:00",
          "errors": [
            {
              "title": "Bad request",
              "detail": "Provided request parameters are invalid.",
              "type": "https://developer.personio.de/v2.0/page/public-api-error-codes#common.bad_request"
            }
          ]
        }
      },
      "JobListResponse": {
        "value": {
          "_data": [
            {
              "id": "209321",
              "name": "Software Developer",
              "category": {
                "id": "13415",
                "name": "Technology"
              },
              "company": {
                "id": "10567"
              },
              "department": {
                "id": "321",
                "name": "IT"
              },
              "hiring_team": [
                {
                  "person": {
                    "id": "98765",
                    "_meta": {
                      "links": {
                        "self": {
                          "href": "https://api.personio.de/v2/persons/98765"
                        }
                      }
                    }
                  },
                  "role": {
                    "name": "HR manager"
                  }
                }
              ],
              "created_at": {
                "date-time": "2023-12-11T14:50:17Z",
                "timezone": "UTC"
              },
              "updated_at": {
                "date-time": "2023-12-11T14:50:17Z",
                "timezone": "UTC"
              },
              "_meta": {
                "links": {
                  "self": {
                    "href": "https://api.personio.de/v2/recruiting/jobs/495039"
                  }
                }
              }
            },
            {
              "id": "209321",
              "name": "Software Developer",
              "category": {
                "id": "13415",
                "name": "Technology"
              },
              "company": {
                "id": "10567"
              },
              "department": {
                "id": "321",
                "name": "IT"
              },
              "created_at": {
                "date-time": "2023-12-11T14:50:17Z",
                "timezone": "UTC"
              },
              "updated_at": {
                "date-time": "2023-12-11T14:50:17Z",
                "timezone": "UTC"
              },
              "_meta": {
                "links": {
                  "self": {
                    "href": "https://api.personio.de/v2/recruiting/jobs/3459829"
                  }
                }
              }
            }
          ],
          "_meta": {
            "links": {
              "self": {
                "href": "https://api.personio.de/v2/recruiting/jobs"
              },
              "next": {
                "href": "https://api.personio.de/v2/recruiting/jobs?cursor=cur_234ls0f02lalfdd"
              }
            }
          }
        }
      },
      "JobListByCursorResponse": {
        "value": {
          "_data": [
            {
              "id": "209321",
              "company": {
                "id": "10567"
              },
              "name": "Software Developer",
              "category": {
                "id": "13415",
                "name": "Technology"
              },
              "department": {
                "id": "321",
                "name": "IT"
              },
              "created_at": {
                "date-time": "2023-12-11T14:50:17Z",
                "timezone": "UTC"
              },
              "updated_at": {
                "date-time": "2023-12-11T14:50:17Z",
                "timezone": "UTC"
              },
              "_meta": {
                "links": {
                  "self": {
                    "href": "https://api.personio.de/v2/recruiting/jobs/495039"
                  }
                }
              }
            },
            {
              "id": "2309850",
              "company": {
                "id": "10567"
              },
              "name": "Software Developer",
              "category": {
                "id": "13415",
                "name": "Technology"
              },
              "department": {
                "id": "321",
                "name": "IT"
              },
              "created_at": {
                "date-time": "2023-12-11T14:50:17Z",
                "timezone": "UTC"
              },
              "updated_at": {
                "date-time": "2023-12-11T14:50:17Z",
                "timezone": "UTC"
              },
              "_meta": {
                "links": {
                  "self": {
                    "href": "https://api.personio.de/v2/recruiting/jobs/3459829"
                  }
                }
              }
            }
          ],
          "_meta": {
            "links": {
              "self": {
                "href": "https://api.personio.de/v2/recruiting/jobs?cursor=cur_15sdwf2eIvLilN2dKFh211Js"
              },
              "next": {
                "href": "https://api.personio.de/v2/recruiting/jobs?cursor=cur_234ls0f02lalfddQrefvA2fe"
              }
            }
          }
        }
      }
    }
  }
}
```