Scoro Integration

Full Scoro API v2 integration for OpenClaw. Provides task management, time tracking, hours calculation, utilization reports, team dashboards, and billable status corrections.

Setup

1. 1. Get your Scoro API key from Settings → External connections → API in your Scoro account.
2. Set your company URL (e.g. https://yourcompany.scoro.com/api/v2).
3. Add both to your OpenClaw config:

CODEBLOCK0

1. 4. Add "scoro" to your agent's skills list in openclaw.json.

Standard Prompts

Users can trigger these capabilities with natural language:

Task Management

• - fetch my scoro tasks / INLINECODE4
• INLINECODE5
• INLINECODE6

Hours & Time Entries

• - show my hours this week / INLINECODE8
• INLINECODE9 / INLINECODE10
• INLINECODE11
• INLINECODE12

Team & Manager Reports

• - show team status / INLINECODE14
• INLINECODE15

Utilization Reporting

• - INLINECODE16
• INLINECODE17

Billable Corrections

• - INLINECODE18
• INLINECODE19
• INLINECODE20

Environment Variables

• - SCORO_COMPANY_URL — full base URL (e.g. https://yourcompany.scoro.com/api/v2)
• INLINECODE23 — company API key (starts with ScoroAPI_)

Both must be set in openclaw.json under env.vars. They are available as shell environment variables. Do NOT use .env files.

API Basics

All Scoro API v2 requests are POST. Every request body must include apiKey and company_account_id.

The company_account_id is the subdomain from your Scoro URL. For https://yourcompany.scoro.com, it is yourcompany.

Example Request (curl)

CODEBLOCK1

Example Request (PowerShell / Windows)

CODEBLOCK2

Key Endpoints

All endpoints: POST $SCORO_COMPANY_URL/{module}/{action}

Filtering

Tasks

CODEBLOCK3

• - responsible_person_ids — array of assigned user IDs
• INLINECODE42 — INLINECODE43
• INLINECODE44 — INLINECODE45

Time Entries

CRITICAL: The date filter field is time_entry_date with from/to keys. NOT start_date/end_date.

CODEBLOCK4

• - user_ids — array of user IDs (not a single value)

Users

No specific filter needed. Returns all active users.

Response Fields

Task Fields

• - event_id — unique task ID
• INLINECODE53 — task name/title
• INLINECODE54 — deadline (ISO datetime)
• INLINECODE55 — 0 or 1
• INLINECODE56 — project/category name
• INLINECODE57 — assigned user ID
• INLINECODE58 — task description

Time Entry Fields

• - time_entry_id — unique ID
• INLINECODE60 — the user who logged it
• INLINECODE61 — format "HH:MM:SS" (e.g. "01:30:00" = 1.5h)
• INLINECODE62 — task/event name
• INLINECODE63 — "billable", "non_billable", or "custom"
• INLINECODE64 — "YYYY-MM-DD"
• INLINECODE65 — the task/event this entry is for
• INLINECODE66 — 0 or 1

User Fields

• - id — unique user ID
• INLINECODE68 — display name
• INLINECODE69 — email address
• INLINECODE70 — job title

Duration Parsing

Pagination — CRITICAL

Scoro caps page size at 25 items regardless of per_page setting.

You MUST paginate through ALL pages for any list operation:

CODEBLOCK5

Important: Do NOT use data.length < per_page as a stop condition — the API returns a max of 25 items per page even if you request 100. Stop when a page returns 0 results.

Calculating Hours

1. 1. Determine date range (default: this week Monday to today)
2. Fetch all time entries for the date range and user(s), paginating all pages
3. Calculate:

   total_hours = sum(duration)
   billable_hours = sum(duration where billable_time_type == "billable")
   non_billable_hours = sum(duration where billable_time_type == "non_billable")
   billable_ratio = (billable_hours / total_hours) * 100
   

1. 4. Present with 2 decimal places

Team Reports

Teams are organized by direct manager (reporting lines).

Workflow for Team Status

1. 1. Resolve user IDs for all team members (by email, from users/list, all pages)
2. Fetch today's time entries for all team members at once
3. Per member: total hours, billable split, latest task name
4. Calculate team totals and billable ratio

Billable Status Correction

Detection

1. 1. Retrieve time entries for the period
2. Retrieve task billing type for each task
3. Flag mismatches: task is billable but time entry is non_billable

Correction

Always confirm with the user before modifying entries.

Rate Limits

• - 2-second rate limit window
• Add 1-second delay between paginated API calls
• On 429 errors, wait and retry

Response Format

CODEBLOCK8

All Available Modules

INLINECODE75, timeEntries, users, projects, contacts, invoices, quotes, orders, bills, expenses, products, calendarEvents, bookings, purchaseOrders, tags, customModules, vatCodes, INLINECODE92

Each module supports: list, view, modify, delete.

Use modify and delete only with explicit user permission.

Notes

• - All requests are POST (even "list" and "view")
• Always include apiKey and company_account_id in the JSON body
• Use detailed_response: true for full field data in list requests
• Duration format: "HH:MM:SS" → convert to decimal hours for reporting
• The lang parameter is optional (defaults to site language)
• On Windows, prefer PowerShell Invoke-RestMethod over curl