--- updatedAt: 2026-05-14T14:32:15.000Z agentTools: projectIndex: https://docs.oysterhr.com/v0.1/llms.txt --- # Retrieve all engagements Returns a list of engagements # OpenAPI definition ```json { "openapi": "3.0.1", "info": { "title": "Endpoints", "version": "v0.1" }, "components": { "securitySchemes": { "bearer_auth": { "type": "http", "scheme": "bearer" } }, "schemas": { "address": { "type": "object", "properties": { "addressId": { "type": "string" }, "addressLine1": { "type": "string", "nullable": true }, "addressLine2": { "type": "string", "nullable": true }, "city": { "type": "string", "nullable": true }, "region": { "type": "string", "nullable": true }, "countryCode": { "type": "string", "nullable": true }, "postalCode": { "type": "string", "nullable": true } }, "required": [ "addressId", "addressLine1", "postalCode" ] }, "amount": { "type": "object", "properties": { "decimal": { "type": "string", "pattern": "^\\d+([.]\\d+)?$" }, "currencyCode": { "type": "string", "minLength": 3, "maxLength": 3 } }, "required": [ "decimal", "currencyCode" ] }, "phoneNumber": { "type": "object", "properties": { "countryCode": { "type": "string", "nullable": true }, "number": { "type": "string" } }, "required": [ "number" ] }, "engagement": { "type": "object", "properties": { "engagementId": { "type": "string" }, "modifiedAt": { "type": "string", "format": "date-time" }, "startDate": { "type": "string", "format": "date" }, "engagementType": { "enum": [ "EMPLOYMENT", "CONTRACT" ] }, "state": { "type": "string" }, "role": { "type": "string" }, "countryCode": { "type": "string" }, "personalDetails": { "type": "object", "properties": { "name": { "type": "string", "nullable": true }, "addresses": { "type": "object", "properties": { "livingAddress": { "type": "object", "nullable": true, "$ref": "#/components/schemas/address" }, "mailingAddress": { "type": "object", "nullable": true, "$ref": "#/components/schemas/address" } } }, "citizenships": { "type": "array", "items": { "type": "string", "nullable": true } }, "dateOfBirth": { "type": "string", "nullable": true }, "phoneNumbers": { "type": "object", "properties": { "default": { "type": "object", "nullable": true, "$ref": "#/components/schemas/phoneNumber" }, "emergency": { "type": "object", "nullable": true, "$ref": "#/components/schemas/phoneNumber" } } } }, "required": [ "name", "addresses" ] }, "employment": { "type": "object", "properties": { "id": { "type": "string" }, "employmentId": { "type": "string" }, "name": { "type": "string", "nullable": true }, "fullLegalName": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "workEmail": { "type": "string", "nullable": true }, "employmentType": { "type": "string", "enum": [ "FULL-TIME", "PART-TIME" ], "nullable": true }, "type": { "type": "string", "enum": [ "FULL-TIME", "PART-TIME" ], "nullable": true }, "salarySubunit": { "type": "integer", "nullable": true }, "salaryCurrencyCode": { "type": "string", "minLength": 3, "maxLength": 3, "nullable": true }, "salary": { "$ref": "#/components/schemas/amount" }, "lastDayOn": { "type": "string", "format": "date", "nullable": true }, "payrollTeamMember": { "type": "boolean" } }, "required": [ "id", "employmentId", "name", "fullLegalName", "email", "workEmail", "employmentType", "type", "lastDayOn", "salarySubunit", "salaryCurrencyCode", "salary", "payrollTeamMember" ], "nullable": true }, "contract": { "type": "object", "properties": { "id": { "type": "string", "nullable": true }, "contractId": { "type": "string", "nullable": true }, "name": { "type": "string", "nullable": true }, "email": { "type": "string", "nullable": true }, "workEmail": { "type": "string", "nullable": true }, "billingType": { "type": "string", "enum": [ "FIXED", "PAY_AS_YOU_GO", "MILESTONE" ], "nullable": true }, "taxIdNumber": { "type": "string", "nullable": true } }, "required": [ "id", "contractId", "name", "email", "workEmail", "billingType", "taxIdNumber" ], "nullable": true }, "benefitEnrollments": { "type": "array", "items": { "type": "object", "properties": { "benefitEnrollmentId": { "type": "string" }, "plan": { "type": "object", "properties": { "provider": { "type": "string" }, "descriptiveName": { "type": "string" } } }, "name": { "type": "string" }, "state": { "type": "string" } } } }, "terminations": { "type": "array", "items": { "type": "object", "properties": { "state": { "type": "string" }, "proposedDate": { "type": "string", "format": "date" } } } }, "department": { "type": "object", "nullable": true, "properties": { "departmentId": { "type": "string" }, "name": { "type": "string" }, "description": { "type": "string" } } } }, "required": [ "engagementId", "engagementType", "personalDetails", "startDate", "countryCode", "role" ] }, "engagements": { "type": "array", "items": { "$ref": "#/components/schemas/engagement" } }, "meta": { "type": "object", "properties": { "items": { "type": "integer" }, "count": { "type": "integer" }, "page": { "type": "integer" }, "pages": { "type": "integer" }, "firstUrl": { "type": "string" }, "lastUrl": { "type": "string" }, "pageUrl": { "type": "string" }, "nextUrl": { "type": "string" }, "prevUrl": { "type": "string" }, "deprecation": { "type": "object", "properties": { "at": { "type": "string" }, "sunset": { "type": "string" }, "link": { "type": "object", "properties": { "rel": { "type": "string" }, "url": { "type": "string" } } } } } }, "required": [ "items", "count", "page", "pages", "firstUrl", "lastUrl", "pageUrl", "nextUrl", "prevUrl" ] } } }, "paths": { "/v0.1/engagements": { "get": { "summary": "Retrieve all engagements", "tags": [ "Engagements" ], "description": "Returns a list of engagements", "security": [ { "bearer_auth": [ "read" ] } ], "parameters": [ { "name": "per_page", "in": "query", "required": false, "schema": { "type": "integer" } }, { "name": "page", "in": "query", "required": false, "schema": { "type": "integer" } } ], "responses": { "200": { "description": "Successful", "content": { "application/json": { "examples": { "No engagements": { "value": { "data": [], "meta": { "items": 100, "count": 0, "page": 1, "pages": 1, "firstUrl": "/v0.1/engagements?perPage=100&page=1", "lastUrl": "/v0.1/engagements?perPage=100&page=1", "pageUrl": "/v0.1/engagements?perPage=100&page=1", "nextUrl": "/v0.1/engagements?perPage=100&page=", "prevUrl": "/v0.1/engagements?perPage=100&page=" } } }, "Successful": { "value": { "data": [ { "id": "Ga3b36b4", "engagementId": "Ga3b36b4", "modifiedAt": "2022-10-15T12:34:56Z", "startDate": "2022-10-15", "type": "CONTRACT", "engagementType": "CONTRACT", "state": "IN_PROGRESS", "role": "Corporate Hospitality Manager Consultant", "countryCode": "GB", "personalDetails": { "name": "The Hon. Bobbie Haag", "addresses": { "livingAddress": null, "mailingAddress": null } }, "livingAddress": null, "mailingAddress": null, "employment": null, "contract": { "id": "Bc7afde1", "contractId": "Bc7afde1", "name": "Danny Keebler", "email": "soila_rosenbaum@prosacco.example", "workEmail": null, "billingType": "FIXED", "taxIdNumber": null }, "benefitEnrollments": [], "terminations": [], "department": null, "usefulInfo": null }, { "id": "E420a9d8", "engagementId": "E420a9d8", "modifiedAt": "2022-10-15T12:34:56Z", "startDate": "2022-10-15", "type": "CONTRACT", "engagementType": "CONTRACT", "state": "IN_PROGRESS", "role": "Senior Sales Representative Consultant", "countryCode": "GB", "personalDetails": { "name": "Shaina Pollich", "addresses": { "livingAddress": null, "mailingAddress": null } }, "livingAddress": null, "mailingAddress": null, "employment": null, "contract": { "id": "A116a07d", "contractId": "A116a07d", "name": "Joel Murazik", "email": "krishna@bahringer.test", "workEmail": null, "billingType": "FIXED", "taxIdNumber": null }, "benefitEnrollments": [], "terminations": [], "department": null, "usefulInfo": null }, { "id": "C6c9d557", "engagementId": "C6c9d557", "modifiedAt": "2022-10-15T12:34:56Z", "startDate": "2022-10-15", "type": "EMPLOYMENT", "engagementType": "EMPLOYMENT", "state": "DRAFT", "role": "Senior Retail Orchestrator Consultant", "countryCode": "GB", "personalDetails": { "name": null, "addresses": { "livingAddress": null, "mailingAddress": null } }, "livingAddress": null, "mailingAddress": null, "employment": { "id": "C6c9d557", "employmentId": "C6c9d557", "name": "Candida Stamm", "fullLegalName": "Candida Stamm", "email": "zachariah_mohr@thompson.example", "workEmail": null, "type": null, "employmentType": null, "lastDayOn": null, "salarySubunit": 12034500, "salaryCurrencyCode": "EUR", "salary": { "decimal": "120345.00", "currencyCode": "EUR" }, "payrollTeamMember": false }, "contract": null, "benefitEnrollments": [], "terminations": [], "department": null, "usefulInfo": null }, { "id": "B0b779a8", "engagementId": "B0b779a8", "modifiedAt": "2022-10-15T12:34:56Z", "startDate": "2022-10-15", "type": "EMPLOYMENT", "engagementType": "EMPLOYMENT", "state": "DRAFT", "role": "Administration Strategist Consultant", "countryCode": "GB", "personalDetails": { "name": null, "addresses": { "livingAddress": null, "mailingAddress": null } }, "livingAddress": null, "mailingAddress": null, "employment": { "id": "B0b779a8", "employmentId": "B0b779a8", "name": "Shirlee Cremin", "fullLegalName": "Shirlee Cremin", "email": "keila.dibbert@sipes.test", "workEmail": null, "type": null, "employmentType": null, "lastDayOn": null, "salarySubunit": 12034500, "salaryCurrencyCode": "EUR", "salary": { "decimal": "120345.00", "currencyCode": "EUR" }, "payrollTeamMember": false }, "contract": null, "benefitEnrollments": [], "terminations": [], "department": null, "usefulInfo": null }, { "id": "A5540727", "engagementId": "A5540727", "modifiedAt": "2022-10-15T12:34:56Z", "startDate": "2022-10-15", "type": "EMPLOYMENT", "engagementType": "EMPLOYMENT", "state": "DRAFT", "role": "Design Technician Consultant", "countryCode": "GB", "personalDetails": { "name": null, "addresses": { "livingAddress": null, "mailingAddress": null } }, "livingAddress": null, "mailingAddress": null, "employment": { "id": "A5540727", "employmentId": "A5540727", "name": "Mafalda Fahey", "fullLegalName": "Mafalda Fahey", "email": "michael.roberts@hintz.example", "workEmail": null, "type": null, "employmentType": null, "lastDayOn": null, "salarySubunit": 12034500, "salaryCurrencyCode": "EUR", "salary": { "decimal": "120345.00", "currencyCode": "EUR" }, "payrollTeamMember": false }, "contract": null, "benefitEnrollments": [], "terminations": [], "department": null, "usefulInfo": null } ], "meta": { "items": 100, "count": 5, "page": 1, "pages": 1, "firstUrl": "/v0.1/engagements?perPage=100&page=1", "lastUrl": "/v0.1/engagements?perPage=100&page=1", "pageUrl": "/v0.1/engagements?perPage=100&page=1", "nextUrl": "/v0.1/engagements?perPage=100&page=", "prevUrl": "/v0.1/engagements?perPage=100&page=" } } } }, "schema": { "type": "object", "properties": { "data": { "$ref": "#/components/schemas/engagements" }, "meta": { "$ref": "#/components/schemas/meta" } }, "required": [ "data", "meta" ] } } } } } } } }, "servers": [ { "url": "https://api.oysterhr.com", "description": "Production server" }, { "url": "https://api-sandbox.oysterhr.com", "description": "Sandbox server" } ] } ```