{ "openapi": "3.1.0", "info": { "title": "COR Resource Allocation API", "description": "The Resource Allocation API is a dedicated service for managing the capacity of users on the COR platform. This API uses the same authentication as the main COR API.", "version": "1.0.0" }, "servers": [ { "url": "https://planner.svc.v2.projectcor.com", "description": "Resource Allocation Service" } ], "security": [ { "bearerAuth": [] } ], "paths": { "/allocation/saveAllocation": { "post": { "tags": ["Resource Allocation"], "summary": "Save Allocation", "description": "Creates a new resource allocation for a user on a project.\n\n**Request Body Requirements:**\nAll values in the object are required.\n\n**Known Errors:**\n- `InvalidAllocationError` — The allocation is invalid:\n - Empty `allocatedHours` field\n - The `from` date is greater than or equal to the `to` date\n - The date range exceeds 12 months\n- `AllocationAlreadyExistInDatesRangeError` — An allocation already exists within the specified date range\n- `UserNotFoundError` — The specified user cannot be found\n- `UserNotHaveWorkDaysError` — The user does not have any work days configured\n- `ProjectNotFoundError` — The specified project cannot be found", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllocationInput" }, "example": { "userId": 1111, "companyId": 1111, "email": "email@email.com", "resource": { "typeId": "Project", "entityId": 1111 }, "from": "2024-06-01", "to": "2024-10-31", "assignedByUserId": 11111, "allocatedHours": 20 } } } }, "responses": { "200": { "description": "Allocation saved successfully" }, "400": { "description": "Invalid allocation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllocationError" }, "examples": { "invalid_allocation": { "summary": "Invalid allocation data", "value": { "error": "InvalidAllocationError", "message": "Empty allocated hours field" } }, "user_not_found": { "summary": "User not found", "value": { "error": "UserNotFoundError", "message": "The specified user cannot be found" } }, "allocation_exists": { "summary": "Allocation already exists", "value": { "error": "AllocationAlreadyExistInDatesRangeError", "message": "An allocation already exists within the specified date range" } } } } } } } } }, "/allocation/updateAllocation": { "put": { "tags": ["Resource Allocation"], "summary": "Update Allocation", "description": "Updates an existing resource allocation. Requires both the old allocation data and the new allocation data.\n\n**Known Errors:**\n- `InvalidAllocationError` — The new allocation is invalid:\n - Empty `allocatedHours` field\n - The `from` date is greater than or equal to the `to` date\n - The date range exceeds 12 months\n- `AllocationNotFoundError` — The specified old allocation cannot be found\n- `AllocationAlreadyExistInDatesRangeError` — The new allocation already exists within the specified date range\n- `UserNotFoundError` — The specified user in new allocation cannot be found\n- `UserNotHaveWorkDaysError` — The user does not have any work days in the new allocation dates range\n- `ProjectNotFoundError` — The specified project in new allocation cannot be found\n\n**Note:** You can use this endpoint to change a project allocation, as long as there isn't an existing allocation for the same user in the target project for any date within the range of the new allocation.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllocationUpdateInput" }, "example": { "oldAllocation": { "userId": 1111, "companyId": 11, "resource": { "entityId": 11111, "typeId": "Project" }, "from": "2024-01-01", "to": "2024-03-31", "assignedByUserId": 1111, "allocatedHours": 0 }, "newAllocation": { "userId": 1111, "companyId": 11, "resource": { "entityId": 11111, "typeId": "Project" }, "from": "2024-01-01", "to": "2024-03-31", "assignedByUserId": 1111, "allocatedHours": 10 } } } } }, "responses": { "200": { "description": "Allocation updated successfully" }, "400": { "description": "Invalid allocation error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllocationError" }, "examples": { "allocation_not_found": { "summary": "Old allocation not found", "value": { "error": "AllocationNotFoundError", "message": "The specified allocation cannot be found" } } } } } } } } }, "/allocation/removeAllocation": { "delete": { "tags": ["Resource Allocation"], "summary": "Delete Allocation", "description": "Removes an existing resource allocation.\n\n**Request Body Requirements:**\nAll values in the object are required.\n\n**Known Errors:**\n- `AllocationNotFoundError` — The specified allocation cannot be found\n- `ProjectNotFoundError` — The specified project cannot be found\n\nPlease ensure that your request is valid and all specified resources exist to avoid these errors.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllocationInput" }, "example": { "userId": 1111, "companyId": 111, "resource": { "typeId": "Project", "entityId": 1111 }, "from": "2024-01-01", "to": "2024-03-31", "assignedByUserId": 11111, "allocatedHours": 20 } } } }, "responses": { "200": { "description": "Allocation deleted successfully" }, "400": { "description": "Allocation not found error", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/AllocationError" }, "example": { "error": "AllocationNotFoundError", "message": "The specified allocation cannot be found" } } } } } } }, "/allocation/getAllocations/{projectId}": { "get": { "tags": ["Resource Allocation"], "summary": "Get Allocations By Project", "description": "Gets information about user allocations for a given project. Returns all users allocated to the project along with their allocation details and allocations in other projects.", "parameters": [ { "name": "projectId", "in": "path", "required": true, "schema": { "type": "integer" }, "description": "Project ID to get allocations for", "example": 12345 } ], "responses": { "200": { "description": "List of user allocations for the project", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/ProjectAllocationsResponse" }, "example": { "users": [ { "userId": 1234, "firstName": "John", "lastName": "Doe", "positionName": "Developer", "categoryName": "Engineering", "categoryId": "10", "picture": "", "userPositionId": "5", "companyId": 41195, "hidden": false, "isDeleted": false, "labelsByCategory": [], "createdAt": "2024-01-15T10:00:00", "allocations": [ { "primaryKey": "00000001", "from": "2024-06-01T00:00:00", "to": "2024-08-31T00:00:00", "allocatedHours": 20, "capacity": 160, "availabilityLeft": 140, "createdAt": "2024-05-20T14:30:00", "allocationUserAnotherProjects": [ { "projectId": 5678, "projectName": "Project Alpha", "clientName": "Client ABC", "allocatedHours": 15 }, { "projectId": 5679, "projectName": "Project Beta", "clientName": "Client XYZ", "allocatedHours": 5 } ] } ], "totalAllocatedHours": 20 } ] } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "JWT", "description": "Uses the same authentication as the main COR API. Obtain a token from https://api.projectcor.com/v1/oauth/token" } }, "schemas": { "AllocationResource": { "type": "object", "required": ["typeId", "entityId"], "properties": { "typeId": { "type": "string", "enum": ["Project"], "description": "Type of resource (currently only Project is supported)" }, "entityId": { "type": "integer", "description": "Project ID" } } }, "AllocationInput": { "type": "object", "required": ["userId", "companyId", "resource", "from", "to", "assignedByUserId", "allocatedHours"], "properties": { "userId": { "type": "integer", "description": "ID of the user being allocated" }, "companyId": { "type": "integer", "description": "Company ID" }, "email": { "type": "string", "format": "email", "description": "User email (optional)" }, "resource": { "$ref": "#/components/schemas/AllocationResource" }, "from": { "type": "string", "format": "date", "description": "Start date (YYYY-MM-DD)" }, "to": { "type": "string", "format": "date", "description": "End date (YYYY-MM-DD). Must be after 'from' date and within 12 months." }, "assignedByUserId": { "type": "integer", "description": "ID of the user who assigned the allocation" }, "allocatedHours": { "type": "number", "description": "Number of hours allocated" } } }, "AllocationUpdateInput": { "type": "object", "required": ["oldAllocation", "newAllocation"], "properties": { "oldAllocation": { "$ref": "#/components/schemas/AllocationInput", "description": "The existing allocation to be updated" }, "newAllocation": { "$ref": "#/components/schemas/AllocationInput", "description": "The new allocation data" } } }, "AllocationError": { "type": "object", "properties": { "error": { "type": "string", "description": "Error type", "enum": [ "InvalidAllocationError", "AllocationAlreadyExistInDatesRangeError", "UserNotFoundError", "UserNotHaveWorkDaysError", "ProjectNotFoundError", "AllocationNotFoundError" ] }, "message": { "type": "string", "description": "Error description" } } }, "UserAllocation": { "type": "object", "properties": { "primaryKey": { "type": "string", "description": "Unique identifier for the allocation" }, "from": { "type": "string", "format": "date-time", "description": "Start date of the allocation" }, "to": { "type": "string", "format": "date-time", "description": "End date of the allocation" }, "allocatedHours": { "type": "number", "description": "Number of hours allocated" }, "capacity": { "type": "number", "description": "Total capacity in hours" }, "availabilityLeft": { "type": "number", "description": "Remaining availability (can be negative if overallocated)" }, "createdAt": { "type": "string", "format": "date-time", "description": "When the allocation was created" }, "allocationUserAnotherProjects": { "type": "array", "description": "Other project allocations for this user in the same period", "items": { "type": "object", "properties": { "projectId": { "type": "integer", "description": "Project ID" }, "projectName": { "type": "string", "description": "Name of the project" }, "clientName": { "type": "string", "description": "Name of the client" }, "allocatedHours": { "type": "number", "description": "Hours allocated to this project" } } } } } }, "AllocatedUser": { "type": "object", "properties": { "userId": { "type": "integer", "description": "User ID" }, "firstName": { "type": "string", "description": "User's first name" }, "lastName": { "type": "string", "description": "User's last name" }, "positionName": { "type": "string", "description": "User's position name" }, "categoryName": { "type": "string", "description": "User's category name" }, "categoryId": { "type": "string", "description": "User's category ID" }, "picture": { "type": "string", "description": "URL to user's profile picture" }, "userPositionId": { "type": "string", "description": "User's position ID" }, "companyId": { "type": "integer", "description": "Company ID" }, "hidden": { "type": "boolean", "description": "Whether the user is hidden" }, "isDeleted": { "type": "boolean", "description": "Whether the user is deleted" }, "labelsByCategory": { "type": "array", "description": "Labels assigned to the user grouped by category", "items": { "type": "object" } }, "createdAt": { "type": "string", "format": "date-time", "description": "When the user was created" }, "allocations": { "type": "array", "description": "User's allocations for this project", "items": { "$ref": "#/components/schemas/UserAllocation" } }, "totalAllocatedHours": { "type": "number", "description": "Total hours allocated to this user for the project" } } }, "ProjectAllocationsResponse": { "type": "object", "properties": { "users": { "type": "array", "description": "List of users allocated to the project", "items": { "$ref": "#/components/schemas/AllocatedUser" } } } } } } }