---
updatedAt: 2025-12-16T09:38:48.000Z
---
Fetch the complete documentation index at: https://apidocs.hibob.com/llms.txt. Use this file to discover all available pages before exploring further.
# Search Projects
This endpoint allows you to retrieve project data based on specified filters. Please note that this endpoint requires body parameters, which is why it utilizes a POST request for a read operation. Before using this endpoint:
- Explore the Attendance API for more details on usage, rate limits, permissions, and more.
- Only project fields mentioned in the `fields` parameter are returned. Use project metadata endpoint to get the field IDs.
- Pagination note: Pagination parameters are currently accepted but not enforced. The response includes all matching results regardless of the `limit` or `cursor` values. Pagination will be implemented in a future version to limit results per page. To learn more, see Pagination in Bob’s API.
Testing notes:
- Use the testing widget's Try It! option to test this endpoint.
- Use the Examples > Request Example option to see how to initiate body parameters.
# OpenAPI definition
```json
{
"openapi": "3.1.1",
"info": {
"title": "Attendance API",
"contact": {
"name": "Hi Bob, Inc."
},
"description": "Public API for importing attendance entries and managing attendance projects, tasks, and clients. Supports detailed field metadata and flexible filtering.",
"license": {
"name": "Proprietary",
"url": "https://apidocs.hibob.com/docs/api-terms-of-use"
},
"version": "1.0.0"
},
"servers": [
{
"url": "https://api.hibob.com/v1",
"description": "Production"
},
{
"url": "https://api.sandbox.hibob.com/v1",
"description": "Sandbox"
}
],
"x-readme": {
"metrics-enabled": false
},
"tags": [
{
"name": "Projects",
"description": "Operations for managing attendance projects, tasks and clients"
}
],
"paths": {
"/attendance/projects/search": {
"post": {
"operationId": "post_attendance-projects-search",
"tags": [
"Projects"
],
"summary": "Search Projects",
"description": "This endpoint allows you to retrieve project data based on specified filters. Please note that this endpoint requires body parameters, which is why it utilizes a POST request for a read operation. Before using this endpoint:
- Explore the Attendance API for more details on usage, rate limits, permissions, and more.
- Only project fields mentioned in the `fields` parameter are returned. Use project metadata endpoint to get the field IDs.
- Pagination note: Pagination parameters are currently accepted but not enforced. The response includes all matching results regardless of the `limit` or `cursor` values. Pagination will be implemented in a future version to limit results per page. To learn more, see Pagination in Bob’s API.
Testing notes:
\n \n - Use the testing widget's Try It! option to test this endpoint.
\n - Use the Examples > Request Example option to see how to initiate body parameters.
\n
\n",
"requestBody": {
"required": true,
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectSearchRequest"
},
"examples": {
"projectBasicSearch": {
"summary": "Active projects",
"description": "Search for id and name of active projects",
"value": {
"fields": [
"/project/id",
"/project/name"
],
"filters": [
{
"fieldId": "/project/status",
"operator": "equals",
"values": [
"active"
]
}
],
"includeHumanReadable": true
}
},
"projectTrackingSearch": {
"summary": "Project tracking search with billable field",
"description": "Search for billable projects with core fields",
"value": {
"fields": [
"/project/id",
"/project/name",
"/project/description",
"/project/billable",
"/project/status",
"/project/clientReference"
],
"filters": [
{
"fieldId": "/project/billable",
"operator": "equals",
"values": [
"true"
]
}
],
"includeHumanReadable": true
}
},
"archivedProjects": {
"summary": "Search archived projects",
"description": "Search for archived projects only",
"value": {
"fields": [
"/project/id",
"/project/name",
"/project/status",
"/project/description"
],
"filters": [
{
"fieldId": "/project/status",
"operator": "equals",
"values": [
"archived"
]
}
],
"includeHumanReadable": true
}
}
}
}
}
},
"responses": {
"200": {
"description": "A list of Projects matching the search criteria",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ProjectSearchResponse"
},
"examples": {
"projectTrackingResponse": {
"summary": "Project tracking response",
"description": "Response showing billable projects with human-readable values",
"value": {
"items": [
{
"objectType": "project",
"fields": {
"/project/id": {
"value": 123456789,
"humanReadable": "123456789"
},
"/project/name": {
"value": "Mobile App Redesign",
"humanReadable": "Mobile App Redesign"
},
"/project/description": {
"value": "Complete redesign of mobile application",
"humanReadable": "Complete redesign of mobile application"
},
"/project/billable": {
"value": true,
"humanReadable": "Yes"
},
"/project/status": {
"value": "active",
"humanReadable": "active"
},
"/project/clientReference": {
"value": 42,
"humanReadable": "Acme Corporation"
}
}
}
],
"response_metadata": {
"next_cursor": null
}
}
},
"customFieldsResponse": {
"summary": "Custom fields response",
"description": "Response including custom fields with various data types",
"value": {
"items": [
{
"objectType": "project",
"fields": {
"/project/id": {
"value": 555666777,
"humanReadable": "555666777"
},
"/project/name": {
"value": "Enterprise Integration",
"humanReadable": "Enterprise Integration"
},
"/project/description": {
"value": "Integration with enterprise systems",
"humanReadable": "Integration with enterprise systems"
},
"/project/billable": {
"value": true,
"humanReadable": "Yes"
},
"/project/status": {
"value": "active",
"humanReadable": "active"
},
"/project/clientReference": {
"value": 45,
"humanReadable": "Tech Solutions Inc"
},
"/project/audienceSelector": {
"value": {
"mode": "all"
},
"humanReadable": "all"
},
"/project/field_591": {
"value": 75000,
"humanReadable": "$75,000"
},
"/project/field_203": {
"value": "high",
"humanReadable": "High Priority"
}
}
}
],
"response_metadata": {
"next_cursor": null
}
}
}
}
}
}
},
"400": {
"description": "The request is malformed or includes invalid parameters",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"401": {
"description": "Authentication failed. Check your service user credentials",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"403": {
"description": "The service user or token is missing the required permissions to access the requested data",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"429": {
"description": "Rate limit exceeded - see Rate limits",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
},
"500": {
"description": "An unexpected error occurred. Try again or contact support if the issue persists.",
"content": {
"application/json": {
"schema": {
"$ref": "#/components/schemas/ApiErrorResponse"
}
}
}
}
},
"security": [
{
"basic": []
},
{
"Bearer": []
}
]
}
}
},
"components": {
"securitySchemes": {
"basic": {
"type": "http",
"scheme": "basic",
"description": "Basic HTTP authentication using service user credentials"
},
"Bearer": {
"type": "http",
"scheme": "bearer",
"bearerFormat": "OAuth 2.0",
"description": "OAuth 2.0 authentication using an Access Token is available for registered partners only. Try It! does not support the full HiBob OAuth flow. You can follow these steps to complete the OAuth 2.0 flow in Postman and then paste the token here."
}
},
"schemas": {
"ApiErrorResponse": {
"type": "object",
"properties": {
"key": {
"type": "string",
"description": "Error key identifier"
},
"error": {
"type": "string",
"description": "Human-readable error message"
},
"args": {
"type": "array",
"description": "Optional error arguments providing additional context",
"items": {
"type": "string"
}
}
}
},
"ProjectSearchResponseObject": {
"type": "object",
"properties": {
"objectType": {
"type": "string",
"enum": [
"project"
],
"description": "Type of the object"
},
"fields": {
"type": "object",
"properties": {
"/project/id": {
"type": "object",
"properties": {
"value": {
"type": "integer",
"format": "int64"
},
"humanReadable": {
"type": "string"
}
}
},
"/project/name": {
"type": "object",
"description": "The unique project name",
"properties": {
"value": {
"type": "string"
},
"humanReadable": {
"type": "string"
}
}
},
"/project/description": {
"type": "object",
"properties": {
"value": {
"type": "string"
},
"humanReadable": {
"type": "string"
}
}
},
"/project/billable": {
"type": "object",
"description": "Relevant only when tracking by project. Determines whether the attendance entry is billable or not.",
"properties": {
"value": {
"type": "boolean"
},
"humanReadable": {
"type": "string"
}
}
},
"/project/status": {
"type": "object",
"properties": {
"value": {
"type": "string",
"enum": [
"active",
"archived"
]
},
"humanReadable": {
"type": "string"
}
}
},
"/project/clientReference": {
"type": "object",
"description": "This is a reference to a `projectClient` object. Use the project client search endpoint to get the client details and filter by the ID from `referenceId`.",
"properties": {
"value": {
"type": "integer",
"format": "int64"
},
"humanReadable": {
"type": "string"
}
}
},
"/project/audienceSelector": {
"type": "object",
"description": "Employees assigned to this project. Only assigned employees can log attendance entries for the project. When `mode=all` this means all employees are linked to this project, and `mode=explicit` specifies employees in `employeeIds`. See Search for employees to get the employee details by ID.",
"properties": {
"value": {
"type": "object",
"properties": {
"mode": {
"type": "string",
"enum": [
"all",
"explicit"
]
},
"employeeIds": {
"type": "array",
"items": {
"type": "string"
}
}
}
},
"humanReadable": {
"type": "string"
}
}
},
"/project/taskIds": {
"type": "object",
"description": "Relevant only when tracking billing by task. The attendance entries are tracked at the task level, and the billable flag of the task determines whether the attendance entry is billable or not. Employees assigned to the project must select a task when logging attendance entries. Use the project task search endpoint to get the task details.",
"properties": {
"value": {
"type": "array",
"items": {
"type": "integer",
"format": "int64"
}
},
"humanReadable": {
"type": "string"
}
}
}
},
"description": "Project fields returned in search response"
}
}
},
"ProjectSearchResponse": {
"type": "object",
"properties": {
"items": {
"type": "array",
"items": {
"$ref": "#/components/schemas/ProjectSearchResponseObject"
},
"description": "Array of project objects matching the search criteria"
},
"response_metadata": {
"type": "object",
"properties": {
"next_cursor": {
"type": [
"string",
"null"
],
"description": "A marker representing the first item on the next page to read. Do not provide it in the first call. Currently ignored for this endpoint. To learn more, see Pagination in Bob's API. "
}
}
}
}
},
"ProjectSearchRequest": {
"type": "object",
"description": "Request schema for searching projects.\n",
"properties": {
"fields": {
"type": "array",
"items": {
"type": "string",
"enum": [
"/project/id",
"/project/name",
"/project/description",
"/project/billable",
"/project/status",
"/project/clientReference",
"/project/audienceSelector",
"/project/taskIds"
],
"description": "Field ID. ootb fields are listed above. Custom fields following the pattern `/project/field_` (e.g., `/project/field_591`) are also supported - use the metadata endpoint to get the field IDs, and Postman to test the endpoint with custom fields if needed."
},
"description": "List of field paths to include in the response. Standard fields are listed above. Custom fields following the pattern `/project/field_` are also supported.",
"example": [
"/project/id",
"/project/name",
"/project/status"
],
"default": [
"/project/id",
"/project/name",
"/project/status"
]
},
"filters": {
"type": "array",
"items": {
"type": "object",
"properties": {
"fieldId": {
"type": "string",
"enum": [
"/project/billable",
"/project/clientReference",
"/project/id",
"/project/name",
"/project/status"
],
"description": "Field ID to filter by. Only the following out-of-the-box fields can be used for filtering: `/project/billable`, `/project/clientReference`, `/project/id`, `/project/name`, `/project/status` "
},
"operator": {
"type": "string",
"description": "The operator can be `equals` or `notEqual` (for boolean you can only use `equals`)",
"enum": [
"equals",
"notEqual"
]
},
"values": {
"type": "array",
"items": {
"type": "string"
},
"description": "One or more values to filter by, provided as strings. For boolean fields,\nuse `true` or `false`.\n"
}
},
"required": [
"fieldId",
"operator",
"values"
]
},
"description": "List of filters to apply",
"example": [
{
"fieldId": "/project/status",
"operator": "equals",
"values": [
"active"
]
}
],
"default": [
{
"fieldId": "/project/status",
"operator": "equals",
"values": [
"active"
]
}
]
},
"limit": {
"type": "integer",
"minimum": 0,
"maximum": 1000,
"default": 50,
"description": "Specifies the number of entries to include on each page of the results. Defaults to 50 if not supplied. Currently ignored for this endpoint."
},
"cursor": {
"type": "string",
"description": "A marker representing the first item on the next page to read. Do not provide it in the first call. Currently ignored for this endpoint. To learn more, see Pagination in Bob's API. "
},
"includeHumanReadable": {
"type": "boolean",
"default": true,
"description": "Whether to include human-readable values in the response"
}
}
}
}
}
}
```