Getting started with Scoro API

Scoro API lets you connect Scoro with other software. You can use it to build your own integrations, sync Scoro data with other systems, or load Scoro data into reports and BI tools.

Scoro offers two versions of the API: API v4 (in beta) and API v2. This article will walk you through everything you need to know about the Scoro API, which API version to use, and how to get started.

1. Scoro API versions

An application programming interface, or API for short, specifies how software components should interact with each other through defined rules. For example, if Software 1 requests data from Software 2, then Software 2 provides only the allowed data.

Scoro offers two versions of the API: API v4 (available in beta) and API v2. Both API versions let you connect Scoro with other software. They differ in how you log in and how you send requests.

API v4 (beta) is the current version and the one we recommend for new integrations.

• It is a standard REST API: you read with GET, create with POST, update with PATCH, and delete with DELETE, and responses are plain JSON.
• Integrations log in with OAuth 2.0. Each integration is an app you register in the Developer Portal, and the app's scopes determine what it can access.
• With API v4, every call runs as one Scoro user: the user who logged in to the app. Records the integration creates or changes show this user as the author, and a call can do only what that user's Scoro permissions and the app's scopes allow. You can use an existing user account for the integration’s purposes, but we recommend creating a dedicated user account for the API integration user instead of a personal login. This way, the records don't depend on one person, and there are no issues when that person leaves your team.

API v2 is the earlier version of the Scoro API.

• Every request is sent as a POST request, and you authenticate with an API key or a user token in the request body.
• You set it up in your site's Scoro API settings under Settings > Site settings > Integrations > Scoro API.
• Even with Scoro API v4 available in beta, API v2 remains available and supported, and existing API v2 integrations will keep working without changes. 

1.1. Plan availability and call limits

1.2. Which Scoro API version should you use?

Use the Scoro API v4 (beta) for creating new integrations. Existing integrations built on Scoro API v2 keep working.

To check which version an integration uses, look at the request URL: v2 URLs contain /api/v2/ and v4 URLs contain /api/v4/.

Here’s a quick comparison of both Scoro API versions so you know the main differences:

1.3. Why use Scoro API v4?

Scoro API v4 (beta) brings countless benefits:

• Secure, standard authentication. Scoro API v4 uses OAuth 2.0 with access scopes, so API keys and user tokens no longer go in request bodies. Each integration is its own app in the Developer Portal: you sign up yourself, get credentials straight away, and can rotate the client secret with a grace period. Scopes such as tasks:r, tasks:rw , tasks:rwd let an integration ask only for the access it needs. The people who connect the app see exactly what it can access.
• A real REST API that works with standard tools. GET reads, POST creates, PATCH updates, and DELETE deletes. Errors come back as standard HTTP status codes (400, 401, 403, 404, 429), and responses are plain JSON. A full OpenAPI 3.1 specification lets you generate client code and test against it.
• Simple connections to BI tools. Every read is a plain GET URL with filters in the query string, and it returns a flat JSON array. Tools such as Power BI, Tableau, Looker Studio, and Excel Power Query can load Scoro data with far less custom code. With the modifiedDateTime filter, a report can refresh only the records that changed.
• Built for AI and agents. The scoro-api skill gives AI coding assistants the endpoint reference, the data model, guides for each area, and a step-by-step v2 to v4 porting guide. See more on AI skills.
• Field names that people and AI read the same way. Names say what the field holds, for example,  dueDateTime, durationPlanned, isDone, and projectIds. Many linked records come with their name next to the ID, for example, companyId and companyName on projects, so one call returns a readable result. Booleans are true or false, durations are in seconds, and dates use ISO 8601 with a timezone offset.
• Resources and actions that are easy to understand. Everything that belongs to a record lives under that record. For example, POST /invoices/{invoiceId}/payments records a payment on an invoice. Business actions are explicit endpoints, such as /invoices/{id}/mark-paid, /tasks/{id}/set-done, and /time-trackers/{id}/pause, and Scoro applies its own business rules for you.
• Querying that matches how people ask questions. Typed filters for each endpoint cover date ranges, ID lists, and custom fields. Each resource has a search endpoint that turns a name into an ID. You can sort by up to 3 fields in either direction.

1.4. What are the plans for Scoro API v2?

API v2 remains available and supported, and your existing integrations keep working without any changes. In the future, additional fees may apply to API v2, but we'll share more information in a timely manner when the details are confirmed.

We encourage you to create new integrations on Scoro API v4 and plan a move to API v4 for the existing integrations when it suits you. Learn more about the migration in the Migrating from API v2 to API v4 section.

2. Setting up and using Scoro API

3. Migrating from Scoro API v2 to API v4

Even with Scoro API v4 available in beta, your Scoro API v2 integrations continue working, and API v2 remains available and supported. We encourage you to move your apps to API v4 when it suits you. Moving early also gives you time to plan, because additional fees may apply to API v2 in the future.

What changes in your calls: see the example of the task calls in both Scoro API versions:

You also change how you authenticate (OAuth access token instead of an API key or user token), use camelCase field names such as projectId, and read list responses as a plain array instead of a response wrapped in status and data. The company account is now an optional header instead of a field in the request body.

To move an integration from Scoro API v2 to API v4:

1. Create a new app in the Developer Portal and generate your OAuth credentials. See this section for more guidance.

2. Decide which Scoro user your integration will act as. Every API v4 call runs as the user who logs in to the app, and the app can do only what that user's permissions and the app's scopes allow. You can use an existing user, but we recommend creating a dedicated API integration user instead of using a personal login, so records created by the integration don't depend on one person. Then give the app only the scopes it needs under Manage access in the Developer Portal.

3. Update your requests to the v4 endpoints, methods, and field names. Check the API v4 reference for the endpoints you use. Let an AI assistant do most of the work: the scoro-api skill includes a step-by-step v2 to v4 porting guide. Get the skill on the AI skills page.

4. Frequently asked questions (FAQ)