Resource Allocation - COR API Documentation

The Resource Allocation API is a dedicated service for managing the capacity of users on the COR platform. This service allows you to allocate users to projects, track their availability, and manage workload distribution.

Overview

COR’s Resource Allocation service provides endpoints to:

Save allocations — Assign users to projects with specific hour allocations
Update allocations — Modify existing allocations
Remove allocations — Delete allocations when no longer needed
Get allocations — Retrieve allocation data for a specific project

Base URL

The Resource Allocation API uses a different base URL than the main COR API:

https://planner.svc.v2.projectcor.com

Authentication

The Resource Allocation API uses the same authentication as the main COR API. You can use the same Bearer token obtained from the main authentication endpoints.

To authenticate requests, include your access token in the Authorization header:

Authorization: Bearer YOUR_ACCESS_TOKEN

Obtain your access token using one of the authentication methods from the main API:

Quick Start

Creating an Allocation

To allocate a user to a project, send a POST request with the allocation details:

curl --location 'https://planner.svc.v2.projectcor.com/allocation/saveAllocation' \
--header 'Content-Type: application/json' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN' \
--data '{
  "userId": 1111,
  "companyId": 1111,
  "email": "user@example.com",
  "resource": {
    "typeId": "Project",
    "entityId": 1111
  },
  "from": "2024-06-01",
  "to": "2024-10-31",
  "assignedByUserId": 11111,
  "allocatedHours": 20
}'

const response = await fetch('https://planner.svc.v2.projectcor.com/allocation/saveAllocation', {
  method: 'POST',
  headers: {
    'Content-Type': 'application/json',
    'Authorization': `Bearer ${accessToken}`
  },
  body: JSON.stringify({
    userId: 1111,
    companyId: 1111,
    email: 'user@example.com',
    resource: {
      typeId: 'Project',
      entityId: 1111
    },
    from: '2024-06-01',
    to: '2024-10-31',
    assignedByUserId: 11111,
    allocatedHours: 20
  })
});

import requests

response = requests.post(
    'https://planner.svc.v2.projectcor.com/allocation/saveAllocation',
    headers={
        'Content-Type': 'application/json',
        'Authorization': f'Bearer {access_token}'
    },
    json={
        'userId': 1111,
        'companyId': 1111,
        'email': 'user@example.com',
        'resource': {
            'typeId': 'Project',
            'entityId': 1111
        },
        'from': '2024-06-01',
        'to': '2024-10-31',
        'assignedByUserId': 11111,
        'allocatedHours': 20
    }
)

Getting Project Allocations

To retrieve all allocations for a project:

curl --location 'https://planner.svc.v2.projectcor.com/allocation/getAllocations/12345' \
--header 'Authorization: Bearer YOUR_ACCESS_TOKEN'

{
  "users": [
    {
      "userId": 1234,
      "firstName": "John",
      "lastName": "Doe",
      "positionName": "Developer",
      "categoryName": "Engineering",
      "companyId": 41195,
      "hidden": false,
      "isDeleted": false,
      "allocations": [
        {
          "primaryKey": "00000001",
          "from": "2024-06-01T00:00:00",
          "to": "2024-08-31T00:00:00",
          "allocatedHours": 20,
          "capacity": 160,
          "availabilityLeft": 140,
          "allocationUserAnotherProjects": [
            {
              "projectId": 5678,
              "projectName": "Project Alpha",
              "clientName": "Client ABC",
              "allocatedHours": 15
            }
          ]
        }
      ],
      "totalAllocatedHours": 20
    }
  ]
}

Known Errors

The API may return the following error types:

Error	Description
`InvalidAllocationError`	The allocation data is invalid (empty hours, invalid date range, or dates span more than 12 months)
`AllocationAlreadyExistInDatesRangeError`	An allocation already exists within the specified date range
`UserNotFoundError`	The specified user cannot be found
`UserNotHaveWorkDaysError`	The user does not have any work days configured
`ProjectNotFoundError`	The specified project cannot be found
`AllocationNotFoundError`	The allocation to update or delete cannot be found

Validation Rules

When creating or updating allocations, ensure that:

The allocatedHours field is not empty
The from date is before the to date
The date range does not exceed 12 months
No existing allocation overlaps with the new date range for the same user and project

Batch Migration

If you have a large amount of allocation data to migrate, you can use a script to batch process the data.

Migration Script Example

const fs = require('fs');
const allocations = require('./allocations-data.json');

async function migrateAllocations() {
  const token = 'YOUR_ACCESS_TOKEN';
  const url = 'https://planner.svc.v2.projectcor.com/allocation/saveAllocation';

  for (const allocation of allocations) {
    try {
      const response = await fetch(url, {
        method: 'POST',
        headers: {
          'Content-Type': 'application/json',
          'Authorization': `Bearer ${token}`
        },
        body: JSON.stringify(allocation),
      });

      if (response.ok) {
        console.log('Allocation saved:', allocation);
        fs.appendFileSync('success.log', 
          `${new Date().toISOString()} - Saved: ${JSON.stringify(allocation)}\n`
        );
      } else {
        console.error('Failed to save allocation:', allocation);
        fs.appendFileSync('error.log', 
          `${new Date().toISOString()} - Failed: ${JSON.stringify(allocation)}\n`
        );
      }
    } catch (error) {
      console.error('Error:', error);
      fs.appendFileSync('error.log', 
        `${new Date().toISOString()} - Error: ${error}\n`
      );
    }
  }
  
  console.log('Migration completed');
}

migrateAllocations();

Data File Format

The allocations data file should follow this format:

[
  {
    "userId": 11111,
    "companyId": 11111,
    "email": "user@example.com",
    "resource": {
      "typeId": "Project",
      "entityId": 11111
    },
    "from": "2024-01-01",
    "to": "2024-03-31",
    "assignedByUserId": 11111,
    "allocatedHours": 20
  },
  {
    "userId": 22222,
    "companyId": 11111,
    "email": "another@example.com",
    "resource": {
      "typeId": "Project",
      "entityId": 11111
    },
    "from": "2024-02-01",
    "to": "2024-04-30",
    "assignedByUserId": 11111,
    "allocatedHours": 40
  }
]

The same script structure can be used for updating allocations by changing the endpoint to /allocation/updateAllocation and adjusting the data format to include both oldAllocation and newAllocation objects.

​Overview

​Base URL

​Authentication

​Quick Start

​Creating an Allocation

​Getting Project Allocations

​Known Errors

​Validation Rules

​Batch Migration

​Migration Script Example

​Data File Format

Overview

Base URL

Authentication

Quick Start

Creating an Allocation

Getting Project Allocations

Known Errors

Validation Rules

Batch Migration

Migration Script Example

Data File Format