Cora PPM API — Overview and Getting Started

Related Pages: [link Swagger reference, API admin config guide]

Purpose and Scope

Use this page if you are connecting an external tool to Cora PPM, including implementation consultants, developers, or administrators setting up an integration.

What the API Is

The Cora PPM API is a RESTful HTTP API. It lets external systems read and write almost every domain in Cora PPM, including projects, tasks, users, financials, forecasting, timesheets, registers, organisations, and custom fields.

It exists so Cora PPM can act as an open platform, not just a browser-based app. Instead of manual data entry or exports, you can automate the flow of data in and out of Cora.

Response and URL Basics

• All responses come back in JSON.

• Resources are named in plural form.

• You can drill down by ID to reach nested resources.

This nesting can go several levels deep, for example /projects/{id}/projectRegister/{registerId}/records/{recordId}/approvals.

Enabling API Access

1. Navigate to Administration → System → My Installation → Features.

2. Enable the API feature by checking the API box. If it is greyed out, you will need to subscribe to the Cora Integration Platform through your sales team.

3. Access API settings under Administration → System → API, where you configure authentication and manage access tokens.

Authentication

Every request must be authenticated. There are two main mechanisms, plus optional external identity provider support.

Personal Access Tokens (PATs)

• Set up: Administration → System → API → Personal Access Token. Give it a descriptive name and an expiry date, up to a year out, then save.

• The token stays valid until you manually regenerate it or it expires.

• Admins create these tokens for automated services that do not have a human user logging in.

• Some endpoints require the [UseClaimsWithPersonalAccessToken] attribute to be usable via PAT. Check the endpoint's Swagger entry.

API Clients (OAuth 2 / IdentityServer)

• Each API client has a Client ID and Client Secret.

• Tokens are typically valid for 24 hours and refresh automatically.

• The token carries the user's identity claims, including admin status, which the API uses to check permissions on every call.

External IDP

If your organisation uses its own Identity Provider, the system can delegate authentication to it instead of the built-in IdentityServer.

Discovering Endpoints: Swagger

Swagger is the interactive API documentation hub. It is accessible by appending _API/swagger to your Cora site URL, or via the Cora PPM API admin page at Admin/Config_API.aspx.

• A full catalogue of every endpoint, organised by data type, with parameters and response formats.

• Live testing for endpoints such as GET Projects.

• Request URL generation so you can copy calls into Power BI, Excel, or Postman.

Key Endpoints You'll Use Most

Pagination and Filtering

All list endpoints paginate. Every response includes four headers:

• Default and maximum page size is 500 records, unless the ExceedApiDefaultLimit feature toggle is on.

• To go beyond the first page, use offset and limit.

• Sort results with a sort parameter. Prefix a field with - for descending.

• Shape fields with the fields parameter to return only the fields you need.

• Most resources also support endpoint-specific filters such as date ranges and status IDs.

Power Query and custom scripts can automate the offset and limit loop so you do not have to do it by hand.

Finding System IDs for Filters

Many endpoints filter by numeric ID, not by the name you see in the UI. Run these lookup endpoints once to build a reference table, then reuse the IDs confidently.

JSON, in Brief

JSON, or JavaScript Object Notation, is the data format the API returns.

• Key-value pairs: "projectID": 123 pairs a field name with its value.

• Data types: strings, numbers, booleans, or null.

• Nested structures: objects can contain other objects or arrays, such as a project with a nested array of team members.

Tools like Power Query and Excel parse JSON into familiar tables automatically, so you rarely need to handle it manually.

Connecting External Tools

Power BI / Excel (Power Query)

1. Get Data → Web → Advanced.

2. Add headers: accept: application/json and authorization: private-token [your_token].

3. Paste the request URL copied from a successful Swagger test.

4. Load and transform so Power Query converts the JSON into a table automatically.

Power Query treats each JSON object as a row and each key as a column. Nested objects appear as expandable columns. For datasets bigger than the pagination limit, M code can loop through multiple calls and concatenate the results.

Postman

Postman is built for sustained API work, including persistent collections, environment variables, and batch operations.

• Persistent collections organise calls by site or function.

• Environment variables store base URLs, tokens, and project IDs.

• Batch operations run whole collections in sequence, for example to bulk import users or update records via the Collection Runner.

Setting Up a Request

1. New → Request: name it clearly and add it to a collection.

2. Configure method and URL: choose GET, POST, or PUT, then add the endpoint path.

3. Add the Authorization header: key Authorization, value private-token [your_token].

4. Send and review: check the response body, status code, and timing. Save successful requests for reuse.

For POST or PUT, add a JSON body in the Body tab. Postman validates syntax and flags errors before sending.

Understanding Call Types

Practical Use Cases

• Bulk data imports — create hundreds of users, projects, or skills at once via Postman or scripts.

• ERP integration — sync actuals from your accounting system into Cora automatically.

• Workflow automation — trigger Cora actions from external events or push Cora updates to Slack, Teams, or email via iPaaS tools.

• Advanced reporting — pull project and financial data into Power BI for visualisations beyond Cora's native reports.

• Historical data archiving — extract scheduled snapshots into a SQL database for a long-term audit trail.

• Data quality audits — export projects or users, run validation scripts, then PUT corrections back automatically.

Security and Hardening

• HTTPS is enforced on all requests.

• CORS validation allows only explicitly allowed origins to make cross-origin browser requests.

• Content Security Policy headers are applied.

• Rate limiting is supported.

• Configurable input sanitisation is available: None, All, or default script-tag scrubbing.

• All write operations on protected endpoints require administrator-level claims.

• A /ping endpoint is available for unauthenticated health checks.

Auditing and Data Persistence

Best Practices

• Secure your tokens. Never share PATs publicly or hardcode them in version-controlled scripts. Use environment variables or a secure vault, and rotate tokens regularly.

• Document your integrations. Keep a record of which endpoints you use, what filters you apply, and where the data flows.

• Test before production. Validate calls in a sandbox or demo site first, using realistic data.

• Optimise for performance. Filter to only the fields you need and schedule bulk operations during off-peak hours.

Getting Started: a Suggested Path

1. Start small by running simple GET requests in Swagger.

2. Build gradually by moving to Power BI or Excel once you understand endpoint structure.

3. Scale strategically by moving production integrations to API clients with OAuth and partnering with IT on reliable workflows.

Admin Reference

Admins manage the API from Cora PPM's Admin section, under Cora PPM API at Admin/Config_API.aspx. Tabs include API Keys, Documentation, API Clients, Personal Access Tokens, Configuration, Bulk Data Logs, Cora Hub Staging Configuration, and live endpoint Statistics.

The modern API also has a full Swagger/OpenAPI UI at the root URL of the API service.