# List document metadata. Lists the metadata of Documents belonging to the provided owner ID. # OpenAPI definition ```json { "openapi": "3.0.0", "info": { "title": "Document Management", "version": "2.0.0", "description": "Collection of endpoints to manage Documents." }, "servers": [ { "url": "https://api.personio.de" } ], "security": [ { "BearerAuth": [] } ], "paths": { "/v2/document-management/documents": { "get": { "summary": "List document metadata.", "description": "Lists the metadata of Documents belonging to the provided owner ID.", "tags": [ "Document Management" ], "x-path-examples": { "List the Document metadata": { "value": "owner_id=123" }, "List a limited amount of Document metadata": { "value": "owner_id=123&limit=1" }, "List the Document metadata with a cursor": { "value": "cursor=15sdwf2eIvLilN2dKFh211Js" }, "List the Document metadata for Documents in a specific category": { "value": "owner_id=123&category_id=7" }, "List the Document metadata for Documents created since a specific date": { "value": "owner_id=123&created_at.gte=2024-02-15" }, "List the Document metadata for Documents created before a specific date": { "value": "owner_id=123&created_at.lt=2024-02-15" }, "List the Document metadata for Documents created on a specific date": { "value": "owner_id=123&created_at.gte=2024-02-15&created_at.lt=2024-02-16" }, "No metatadata found for owner": { "value": "owner_id=99999" }, "No metatadata found for category": { "value": "owner_id=123&category_id=99999" }, "Invalid limit": { "value": "owner_id=123&limit=300" }, "Invalid created_at.gte": { "value": "owner_id=123&created_at.gte=string" }, "Invalid created_at.lt": { "value": "owner_id=123&created_at.lt=string" }, "No Owner ID": { "value": "/v2/document-management/documents" } }, "parameters": [ { "name": "owner_id", "in": "query", "description": "The ID of the owner of the Documents whose metadata is to be returned.", "example": 123, "schema": { "type": "string" }, "required": true }, { "name": "category_id", "in": "query", "description": "The ID of the category in which the Documents whose metadata is to be returned belong.", "example": 123, "schema": { "type": "string" } }, { "name": "created_at.gte", "in": "query", "description": "This is a date filter to return documents with a 'created_at' date greater than or equal to the provided date (in YYYY-MM-DD format). Documents created on this date will be included in the response.", "example": "2024-03-25", "schema": { "type": "string", "format": "date" } }, { "name": "created_at.lt", "in": "query", "description": "This is a date filter to return documents with a 'created_at' date less than the provided date (in YYYY-MM-DD format). Documents created on this date will not be included in the response.", "example": "2024-03-26", "schema": { "type": "string", "format": "date" } }, { "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." } ], "responses": { "200": { "$ref": "#/components/responses/GetDocumentMetadataResponse" }, "400": { "$ref": "#/components/responses/BadRequestError" }, "422": { "$ref": "#/components/responses/InvalidRequestError" } } } } }, "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer" } }, "responses": { "GetDocumentMetadataResponse": { "description": "Successful response.", "content": { "application/json": { "schema": { "type": "object", "properties": { "_data": { "type": "array", "items": { "$ref": "#/components/schemas/Document" } }, "_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=" } } } } } } } }, "examples": { "List the Document metadata": { "$ref": "#/components/examples/ListTheDocumentMetadata" }, "List a limited amount of Document metadata": { "$ref": "#/components/examples/ListTheDocumentMetadataWithLimit" }, "List the Document metadata with a cursor": { "$ref": "#/components/examples/ListDocumentMetadataWithCursor" }, "List the Document metadata for Documents in a specific category": { "$ref": "#/components/examples/ListTheDocumentMetadataForCategory" }, "List the Document metadata for Documents created since a specific date": { "$ref": "#/components/examples/ListTheDocumentMetadataSinceDate" }, "List the Document metadata for Documents created before a specific date": { "$ref": "#/components/examples/ListTheDocumentMetadataBeforeDate" }, "List the Document metadata for Documents created on a specific date": { "$ref": "#/components/examples/ListTheDocumentMetadataOnDate" }, "No metatadata found for owner": { "$ref": "#/components/examples/NoMetadataForOwnerIdResponse" }, "No metatadata found for category": { "$ref": "#/components/examples/NoMetadataForCategoryIdResponse" } } } } }, "BadRequestError": { "description": "Bad request sent by client.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/responses/NotFoundError/content/application~1problem%2Bjson/schema" }, "examples": { "No Owner ID": { "$ref": "#/components/examples/NoOwnerIdResponse" } } } } }, "NotFoundError": { "description": "Requested resource not found.", "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": { "Category Not Found": { "$ref": "#/components/examples/CategoryNotFoundResponse" }, "Document not found": { "$ref": "#/components/examples/DocumentNotFoundResponse" } } } } }, "InvalidRequestError": { "description": "Invalid request.", "content": { "application/problem+json": { "schema": { "$ref": "#/components/responses/NotFoundError/content/application~1problem%2Bjson/schema" }, "examples": { "Invalid Date Format": { "$ref": "#/components/examples/InvalidDocumentDateFormatResponse" }, "Invalid Date Null Value": { "$ref": "#/components/examples/InvalidDocumentDateNullEmptyValueResponse" }, "Invalid Date Empty String Value": { "$ref": "#/components/examples/InvalidDocumentDateNullEmptyValueResponse" }, "Invalid Name Length": { "$ref": "#/components/examples/InvalidDocumentNameLengthResponse" }, "Invalid Name Null Value": { "$ref": "#/components/examples/InvalidDocumentNameNullEmptyValueResponse" }, "Invalid Name Empty String Value": { "$ref": "#/components/examples/InvalidDocumentNameNullEmptyValueResponse" }, "Invalid Comment Null Value": { "$ref": "#/components/examples/InvalidDocumentCommentNullValueResponse" }, "Invalid Category ID Null Value": { "$ref": "#/components/examples/InvalidCategoryIdNullEmptyValueResponse" }, "Invalid Category ID Empty String Value": { "$ref": "#/components/examples/InvalidCategoryIdNullEmptyValueResponse" }, "Invalid limit": { "$ref": "#/components/examples/InvalidLimitResponse" }, "Invalid created_at.gte": { "$ref": "#/components/examples/InvalidCreatedAtGteResponse" }, "Invalid created_at.lt": { "$ref": "#/components/examples/InvalidCreatedAtLtResponse" } } } } } }, "schemas": { "Document": { "description": "Document schema", "type": "object", "properties": { "id": { "type": "string", "description": "The identifier for the Document.", "readOnly": true }, "name": { "type": "string", "description": "The name of the Document." }, "date": { "type": "string", "format": "date", "description": "A customisable date field for the Document. Documents will be ordered in Personio according to this date." }, "comment": { "type": "string", "description": "The comment associated with the Document." }, "category": { "type": "object", "description": "The category that the Document belongs to.", "properties": { "id": { "type": "string", "description": "ID of the category." } } }, "owner": { "type": "object", "description": "The owner of the document.", "properties": { "id": { "type": "string", "description": "The ID of the owner." } } }, "document_type": { "type": "string", "description": "The MIME type of the Document.", "readOnly": true }, "size": { "type": "integer", "description": "The size of the Document in bytes.", "readOnly": true }, "created_at": { "type": "string", "description": "The date/time the Document was created at.", "readOnly": true }, "virus_scan": { "type": "object", "description": "Information related to the virus scanning of the Document.", "readOnly": true, "properties": { "status": { "type": "string", "description": "The virus scan status of the Document. If no viruses have been detected, the status will be 'safe'. If a virus has been detected, the status will be 'unsafe'. If the virus scan has not yet completed, the status will be 'unknown'.", "enum": [ "unknown", "safe", "unsafe" ], "readOnly": true } } }, "esignature": { "type": "object", "description": "Information related to e-signature requests for the Document.", "readOnly": true, "properties": { "status": { "type": "string", "enum": [ "status_unspecified", "pending", "signed", "declined", "canceled", "expired", "failed", "email_bounced" ], "description": "The status of e-signature requests associated with the Document.", "readOnly": true } } } } } }, "examples": { "ListTheDocumentMetadata": { "value": { "_data": [ { "id": 10003, "name": "Fourth Document", "date": "2024-02-16", "comment": "This is the fourth document.", "category": { "id": 1 }, "owner": { "id": 123 }, "document_type": "text/plain", "size": 47360, "created_at": "2024-02-16 16:54:18", "virus_scan": { "status": "safe" }, "esignature": { "status": "status_unspecified" } }, { "id": 10002, "name": "Third Document", "date": "2024-03-18", "comment": "", "category": { "id": 2 }, "owner": { "id": 123 }, "document_type": "application/pdf", "size": 3028, "created_at": "2024-02-15 09:12:36", "virus_scan": { "status": "safe" }, "esignature": { "status": "pending" } } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/document-management/documents?cursor=35yM9aE27fsB4Joth7iDGgyk" }, "next": { "href": "https://api.personio.de/v2/document-management/documents?cursor=15sdwf2eIvLilN2dKFh211Js" } } } } }, "ListTheDocumentMetadataWithLimit": { "value": { "_data": [ { "id": 10003, "name": "Fourth Document", "date": "2024-02-16", "comment": "This is the fourth document.", "category": { "id": 1 }, "owner": { "id": 123 }, "document_type": "text/plain", "size": 47360, "created_at": "2024-02-16 16:54:18", "virus_scan": { "status": "safe" }, "esignature": { "status": "status_unspecified" } } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/document-management/documents?cursor=35yM9aE27fsB4Joth7iDGgyk" }, "next": { "href": "https://api.personio.de/v2/document-management/documents?cursor=15sdwf2eIvLilN2dKFh211Js" } } } } }, "ListDocumentMetadataWithCursor": { "value": { "_data": [ { "id": 10001, "name": "Second Document", "date": "2024-02-14", "comment": "This is the second document.", "category": { "id": 5 }, "owner": { "id": 123 }, "document_type": "application/pdf", "size": 6038, "created_at": "2024-02-14 10:30:28", "virus_scan": { "status": "safe" }, "esignature": { "status": "status_unspecified" } }, { "id": 10000, "name": "First Document", "date": "2024-02-20", "comment": "", "category": { "id": 7 }, "owner": { "id": 123 }, "document_type": "application/pdf", "size": 5974, "created_at": "2024-02-12 17:01:20", "virus_scan": { "status": "safe" }, "esignature": { "status": "pending" } } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/document-management/documents?cursor=15sdwf2eIvLilN2dKFh211Js" }, "next": { "href": "https://api.personio.de/v2/document-management/documents?cursor=LIviNw2fN2f2eNh31eNh12eI" } } } } }, "ListTheDocumentMetadataForCategory": { "value": { "_data": [ { "id": 10000, "name": "First Document", "date": "2024-02-20", "comment": "", "category": { "id": 7 }, "owner": { "id": 123 }, "document_type": "application/pdf", "size": 5974, "created_at": "2024-02-12 17:01:20", "virus_scan": { "status": "safe" }, "esignature": { "status": "pending" } } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/document-management/documents?cursor=15sdwf2eIvLilN2dKFh211Js" }, "next": { "href": "https://api.personio.de/v2/document-management/documents?cursor=LIviNw2fN2f2eNh31eNh12eI" } } } } }, "ListTheDocumentMetadataSinceDate": { "value": { "_data": [ { "id": 10003, "name": "Fourth Document", "date": "2024-02-16", "comment": "This is the fourth document.", "category": { "id": 1 }, "owner": { "id": 123 }, "document_type": "text/plain", "size": 47360, "created_at": "2024-02-16 16:54:18", "virus_scan": { "status": "safe" }, "esignature": { "status": "status_unspecified" } }, { "id": 10002, "name": "Third Document", "date": "2024-03-18", "comment": "", "category": { "id": 2 }, "owner": { "id": 123 }, "document_type": "application/pdf", "size": 3028, "created_at": "2024-02-15 09:12:36", "virus_scan": { "status": "safe" }, "esignature": { "status": "pending" } } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/document-management/documents?cursor=35yM9aE27fsB4Joth7iDGgyk" }, "next": { "href": "https://api.personio.de/v2/document-management/documents?cursor=15sdwf2eIvLilN2dKFh211Js" } } } } }, "ListTheDocumentMetadataBeforeDate": { "value": { "_data": [ { "id": 10001, "name": "Second Document", "date": "2024-02-14", "comment": "This is the second document.", "category": { "id": 5 }, "owner": { "id": 123 }, "document_type": "application/pdf", "size": 6038, "created_at": "2024-02-14 10:30:28", "virus_scan": { "status": "safe" }, "esignature": { "status": "status_unspecified" } }, { "id": 10000, "name": "First Document", "date": "2024-02-20", "comment": "", "category": { "id": 7 }, "owner": { "id": 123 }, "document_type": "application/pdf", "size": 5974, "created_at": "2024-02-12 17:01:20", "virus_scan": { "status": "safe" }, "esignature": { "status": "pending" } } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/document-management/documents?cursor=35yM9aE27fsB4Joth7iDGgyk" }, "next": { "href": "https://api.personio.de/v2/document-management/documents?cursor=15sdwf2eIvLilN2dKFh211Js" } } } } }, "ListTheDocumentMetadataOnDate": { "value": { "_data": [ { "id": 10002, "name": "Third Document", "date": "2024-03-18", "comment": "", "category": { "id": 2 }, "owner": { "id": 123 }, "document_type": "application/pdf", "size": 3028, "created_at": "2024-02-15 09:12:36", "virus_scan": { "status": "safe" }, "esignature": { "status": "pending" } } ], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/document-management/documents?cursor=35yM9aE27fsB4Joth7iDGgyk" }, "next": { "href": "https://api.personio.de/v2/document-management/documents?cursor=15sdwf2eIvLilN2dKFh211Js" } } } } }, "NoMetadataForOwnerIdResponse": { "value": { "_data": [], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/document-management/documents?cursor=15sdwf2eIvLilN2dKFh211Js" } } } } }, "NoMetadataForCategoryIdResponse": { "value": { "_data": [], "_meta": { "links": { "self": { "href": "https://api.personio.de/v2/document-management/documents?cursor=15sdwf2eIvLilN2dKFh211Js" } } } } }, "InvalidDocumentDateFormatResponse": { "value": { "timestamp": "2022-06-17T14:07:17Z", "personio_trace_id": "aswo3f-a202lfso-312123sld-1230dd1", "errors": [ { "title": "Invalid date format.", "detail": "The provided date for field 'date' is invalid. Please ensure that the date follows the format YYYY-MM-DD.", "type": "https://developer.personio.de/reference/errors#documents.invalid_request.date_format" } ] } }, "InvalidDocumentDateNullEmptyValueResponse": { "value": { "timestamp": "2022-06-17T14:07:17Z", "personio_trace_id": "aswo3f-a202lfso-312123sld-1230dd1", "errors": [ { "title": "Missing value for document date.", "detail": "If the 'date' field is included, a value must be provided. Please ensure that the value follows the format YYYY-MM-DD.", "type": "https://developer.personio.de/reference/errors#documents.invalid_request.date_format" } ] } }, "InvalidDocumentNameLengthResponse": { "value": { "timestamp": "2022-06-17T14:07:17Z", "personio_trace_id": "aswo3f-a202lfso-312123sld-1230dd1", "errors": [ { "title": "Invalid document name length.", "detail": "The provided value for field 'name' is invalid. The name must be less than 256 characters.", "type": "https://developer.personio.de/reference/errors#documents.invalid_request.name_length" } ] } }, "InvalidDocumentNameNullEmptyValueResponse": { "value": { "timestamp": "2022-06-17T14:07:17Z", "personio_trace_id": "aswo3f-a202lfso-312123sld-1230dd1", "errors": [ { "title": "Missing value for document name.", "detail": "If the 'name' field is included, a value must be provided.", "type": "https://developer.personio.de/reference/errors#documents.invalid_request.name_empty" } ] } }, "InvalidDocumentCommentNullValueResponse": { "value": { "timestamp": "2022-06-17T14:07:17Z", "personio_trace_id": "aswo3f-a202lfso-312123sld-1230dd1", "errors": [ { "title": "Null value for document comment.", "detail": "If the 'comment' field is included, the value must not be null.", "type": "https://developer.personio.de/reference/errors#documents.invalid_request.comment_null" } ] } }, "InvalidCategoryIdNullEmptyValueResponse": { "value": { "timestamp": "2022-06-17T14:07:17Z", "personio_trace_id": "aswo3f-a202lfso-312123sld-1230dd1", "errors": [ { "title": "Missing value for document category.id.", "detail": "If the 'category.id' field is included, a value must be provided.", "type": "https://developer.personio.de/reference/errors#documents.invalid_request.category_id_empty" } ] } }, "NoOwnerIdResponse": { "value": { "timestamp": "2022-06-17T14:07:17Z", "personio_trace_id": "aswo3f-a202lfso-312123sld-1230dd1", "errors": [ { "title": "Missing value for owner_id query parameter.", "detail": "The owner_id query parameter is required.", "type": "https://developer.personio.de/reference/errors#documents.bad_request.owner_id_absent" } ] } }, "InvalidLimitResponse": { "value": { "timestamp": "2022-06-17T14:07:17Z", "personio_trace_id": "aswo3f-a202lfso-312123sld-1230dd1", "errors": [ { "title": "Invalid limit parameter.", "detail": "The provided value for the 'limit' parameter is invalid. Please ensure that the value is an integer within the range 1-200.", "type": "https://developer.personio.de/reference/errors#documents.invalid_request.limit" } ] } }, "InvalidCreatedAtGteResponse": { "value": { "timestamp": "2022-06-17T14:07:17Z", "personio_trace_id": "aswo3f-a202lfso-312123sld-1230dd1", "errors": [ { "title": "Invalid created_at.gte parameter.", "detail": "The provided date for the 'created_at.gte' parameter is invalid. Please ensure that the date follows the format YYYY-MM-DD.", "type": "https://developer.personio.de/reference/errors#documents.invalid_request.created_at.gte" } ] } }, "InvalidCreatedAtLtResponse": { "value": { "timestamp": "2022-06-17T14:07:17Z", "personio_trace_id": "aswo3f-a202lfso-312123sld-1230dd1", "errors": [ { "title": "Invalid created_at.lt parameter.", "detail": "The provided date for the 'created_at.lt' parameter is invalid. Please ensure that the date follows the format YYYY-MM-DD.", "type": "https://developer.personio.de/reference/errors#documents.invalid_request.created_at.lt" } ] } } } } } ```