{ "openapi": "3.0.1", "info": { "title": "Wagepoint Public API", "description": "Public REST API for partners and integrations to access Wagepoint Company, Person, Pay Group, and Time data.", "version": "v1" }, "servers": [ { "url": "/api" } ], "paths": { "/v1/companies/{company_id}/time-entries": { "post": { "tags": [ "Time Entries" ], "operationId": "CreateTimeEntries", "parameters": [ { "name": "company_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "Idempotency-Key", "in": "header", "description": "Optional idempotency key to prevent duplicate writes. Must be unique per request.", "schema": { "type": "string" } } ], "requestBody": { "description": "Time entries to create (1-100)", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/create_time_entries_request" } } }, "required": true }, "responses": { "201": { "description": "Created time entries", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_items_response_time_entry_response" } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem_details" } } } }, "401": { "description": "Missing or invalid token" } }, "security": [ { "bearerAuth": [ ] } ] }, "get": { "tags": [ "Time Entries" ], "operationId": "ListTimeEntries", "parameters": [ { "name": "company_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "from_date", "in": "query", "description": "Start of the date window (ISO YYYY-MM-DD, inclusive).", "required": true, "schema": { "type": "string" } }, { "name": "to_date", "in": "query", "description": "End of the date window (ISO YYYY-MM-DD, inclusive). Must be on or after from_date.", "required": true, "schema": { "type": "string" } }, { "name": "person_id", "in": "query", "description": "Repeated person id filter, e.g. ?person_id=1&person_id=2.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } }, { "name": "status", "in": "query", "description": "Repeated status filter (snake_case, e.g. approved).", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "string" } } } ], "responses": { "200": { "description": "Time entries in the date window", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_items_response_time_entry_response" } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem_details" } } } }, "422": { "description": "A value could not be converted to the expected type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem_details" } } } }, "401": { "description": "Missing or invalid token" } }, "security": [ { "bearerAuth": [ ] } ] }, "patch": { "tags": [ "Time Entries" ], "operationId": "UpdateTimeEntries", "parameters": [ { "name": "company_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update_time_entries_request" } } }, "required": true }, "responses": { "200": { "description": "Payload of UpdateTimeEntriesResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update_time_entries_response" } } } } }, "security": [ { "bearerAuth": [ ] } ] } }, "/v1/companies/{company_id}/time-entries/status": { "patch": { "tags": [ "Time Entries" ], "operationId": "UpdateTimeEntryStatus", "parameters": [ { "name": "company_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "Idempotency-Key", "in": "header", "schema": { "type": "string" } } ], "requestBody": { "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update_time_entry_status_request" } } }, "required": true }, "responses": { "200": { "description": "Payload of UpdateTimeEntryStatusResponse", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/update_time_entry_status_response" } } } } }, "security": [ { "bearerAuth": [ ] } ] } }, "/v1/companies/{company_id}/persons": { "get": { "tags": [ "Persons" ], "operationId": "ListPersons", "parameters": [ { "name": "company_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } }, { "name": "page_size", "in": "query", "description": "Page size, 1..100. Defaults to 100. Free per request; it should remain constant across a page sequence because ordering is unstable and a sequence is not a consistent snapshot.", "schema": { "type": "integer", "format": "int32" } }, { "name": "after", "in": "query", "description": "Opaque, forward-only pagination cursor. Do not decode or construct it; resend it verbatim. A page sequence is not a consistent snapshot; changing page_size mid-sequence can skip or duplicate persons.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of persons", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paged_response_person_response" } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem_details" } } } }, "422": { "description": "A value could not be converted to the expected type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem_details" } } } }, "403": { "description": "Forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem_details" } } } }, "500": { "description": "Internal error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem_details" } } } }, "502": { "description": "Upstream bad response or contract violation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem_details" } } } }, "503": { "description": "Upstream unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem_details" } } } }, "504": { "description": "Upstream timeout", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem_details" } } } }, "401": { "description": "Missing or invalid token" } }, "security": [ { "bearerAuth": [ ] } ] } }, "/v1/companies/{company_id}/pay-groups": { "get": { "tags": [ "Pay Groups" ], "operationId": "ListPayGroups", "parameters": [ { "name": "company_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "Active pay groups for the company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/list_items_response_pay_group_response" } } } }, "400": { "description": "validation_error, upstream_bad_request, idempotency_not_supported", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem_details" } } } }, "401": { "description": "unauthorized", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem_details" } } } }, "403": { "description": "forbidden", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem_details" } } } }, "422": { "description": "invalid_type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem_details" } } } }, "500": { "description": "internal_error", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem_details" } } } }, "502": { "description": "upstream_bad_response, upstream_contract_violation", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem_details" } } } }, "503": { "description": "upstream_unavailable", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem_details" } } } }, "504": { "description": "upstream_timeout", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem_details" } } } } }, "security": [ { "bearerAuth": [ ] } ] } }, "/mcp/client-metadata.json": { "get": { "tags": [ "MCP" ], "operationId": "GetMcpClientMetadata", "responses": { "200": { "description": "CIMD document for the Wagepoint MCP STDIO bundle", "content": { "application/json": { "schema": { "type": "object" } } } }, "404": { "description": "CIMD client URL is not configured" } } } }, "/v1/companies/{company_id}": { "get": { "tags": [ "Companies" ], "operationId": "GetCompany", "parameters": [ { "name": "company_id", "in": "path", "required": true, "schema": { "type": "integer", "format": "int32" } } ], "responses": { "200": { "description": "The requested company", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/company_response" } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem_details" } } } }, "404": { "description": "Company not found", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem_details" } } } }, "401": { "description": "Missing or invalid token" } }, "security": [ { "bearerAuth": [ ] } ] } }, "/v1/companies": { "get": { "tags": [ "Companies" ], "operationId": "ListCompanies", "parameters": [ { "name": "page_size", "in": "query", "description": "Page size, 1..100. Defaults to 100. On a follow-up request it must match the cursor.", "schema": { "type": "integer", "format": "int32" } }, { "name": "name", "in": "query", "description": "Case-insensitive name prefix filter.", "schema": { "type": "string" } }, { "name": "status", "in": "query", "description": "Filter by a single company status value (snake_case, e.g. active).", "schema": { "type": "string" } }, { "name": "id", "in": "query", "description": "Repeated company id filter, e.g. ?id=1&id=2.", "style": "form", "explode": false, "schema": { "type": "array", "items": { "type": "integer", "format": "int32" } } }, { "name": "after", "in": "query", "description": "Opaque, forward-only pagination cursor. Do not decode or construct it; resend it verbatim.", "schema": { "type": "string" } } ], "responses": { "200": { "description": "A page of companies", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/paged_response_company_list_item_response" } } } }, "400": { "description": "Invalid request", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem_details" } } } }, "422": { "description": "A value could not be converted to the expected type", "content": { "application/problem+json": { "schema": { "$ref": "#/components/schemas/problem_details" } } } }, "401": { "description": "Missing or invalid token" } }, "security": [ { "bearerAuth": [ ] } ] } }, "/health": { "get": { "tags": [ "Health" ], "operationId": "Health", "responses": { "503": { "description": "Service is unhealthy", "content": { "application/json": { "schema": { "type": "object" } } } }, "200": { "description": "Service is healthy" } } } }, "/alive": { "get": { "tags": [ "Health" ], "operationId": "Alive", "responses": { "200": { "description": "Service is alive" } } } } }, "components": { "schemas": { "address_response": { "type": "object", "properties": { "line1": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" } } }, "company_list_item_response": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "dba": { "type": "string" }, "company_code": { "type": "string" }, "status": { "enum": [ "not_defined", "waiting_data", "pending_verification", "active", "inactive", "close_initiated", "close_pending", "closed", "expired", "banned" ], "type": "string", "default": "not_defined" } } }, "company_response": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "dba": { "type": "string" }, "company_code": { "type": "string" }, "status": { "enum": [ "not_defined", "waiting_data", "pending_verification", "active", "inactive", "close_initiated", "close_pending", "closed", "expired", "banned" ], "type": "string", "default": "not_defined" }, "phone_number": { "type": "string" }, "primary_address": { "$ref": "#/components/schemas/address_response" }, "locations": { "type": "array", "items": { "$ref": "#/components/schemas/location_response" } }, "created_at": { "type": "string", "format": "date-time" } } }, "create_time_entries_request": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/create_time_entry_request" } } } }, "create_time_entry_request": { "type": "object", "properties": { "person_id": { "type": "integer", "format": "int32" }, "work_date": { "type": "string", "format": "date" }, "hours": { "type": "number", "format": "double" }, "notes": { "type": "string" } } }, "list_items_response_pay_group_response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/pay_group_response" } } } }, "list_items_response_time_entry_response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/time_entry_response" } } } }, "location_response": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "location_type": { "enum": [ "not_defined", "not_specified", "headquarters" ], "type": "string", "default": "not_defined" }, "is_primary": { "type": "boolean" }, "address": { "$ref": "#/components/schemas/address_response" } } }, "page_info": { "type": "object", "properties": { "after": { "type": "string" }, "page_size": { "type": "integer", "format": "int32" }, "has_more": { "type": "boolean" } } }, "paged_response_company_list_item_response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/company_list_item_response" } }, "page_info": { "$ref": "#/components/schemas/page_info" } } }, "paged_response_person_response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/person_response" } }, "page_info": { "$ref": "#/components/schemas/page_info" } } }, "pay_group_response": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "name": { "type": "string" }, "is_auto_run": { "type": "boolean" } } }, "person_address_response": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "line1": { "type": "string" }, "line2": { "type": "string" }, "city": { "type": "string" }, "state": { "type": "string" }, "postal_code": { "type": "string" }, "country": { "type": "string" } } }, "person_response": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "company_id": { "type": "integer", "format": "int32" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "email": { "type": "string" }, "person_type": { "enum": [ "not_defined", "employee", "contractor", "other" ], "type": "string", "default": "not_defined" }, "status": { "enum": [ "not_defined", "not_specified", "active", "terminated", "on_leave", "terminated_pending", "on_leave_pending", "disabled", "pending", "incomplete_profile", "deleted" ], "type": "string", "default": "not_defined", "nullable": true }, "hire_date": { "type": "string", "format": "date", "nullable": true }, "address": { "$ref": "#/components/schemas/person_address_response" } } }, "problem_details": { "type": "object", "properties": { "type": { "type": "string" }, "title": { "type": "string" }, "status": { "type": "integer", "format": "int32", "nullable": true }, "detail": { "type": "string" }, "instance": { "type": "string" }, "extensions": { "type": "object", "additionalProperties": { "type": "object" } } } }, "time_entry_response": { "type": "object", "properties": { "id": { "type": "integer", "format": "int32" }, "person_id": { "type": "integer", "format": "int32" }, "work_date": { "type": "string", "format": "date" }, "hours": { "type": "number", "format": "double" }, "notes": { "type": "string" }, "status": { "enum": [ "pending", "edited", "approved", "paid", "rejected" ], "type": "string", "default": "pending" } } }, "update_time_entries_request": { "type": "object", "properties": { "entries": { "type": "array", "items": { "$ref": "#/components/schemas/update_time_entry_request" } } } }, "update_time_entries_response": { "type": "object", "properties": { "items": { "type": "array", "items": { "$ref": "#/components/schemas/time_entry_response" } } } }, "update_time_entry_request": { "type": "object", "properties": { "time_entry_id": { "type": "integer", "format": "int32" }, "hours": { "type": "number", "format": "double", "nullable": true }, "notes": { "type": "string" } } }, "update_time_entry_status_request": { "type": "object", "properties": { "time_entry_ids": { "type": "array", "items": { "type": "integer", "format": "int32" } }, "action": { "enum": [ "approve", "unapprove", "reject" ], "type": "string", "default": "approve", "nullable": true }, "notes": { "type": "string" } } }, "update_time_entry_status_response": { "type": "object", "properties": { "time_entry_ids": { "type": "array", "items": { "type": "integer", "format": "int32" } }, "status": { "enum": [ "pending", "edited", "approved", "paid", "rejected" ], "type": "string", "default": "pending" } } } }, "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT" } } } }