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. 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:

json

{
  "env": {
    "vars": {
      "SCORO_API_KEY": "ScoroAPI_your_key_here",
      "SCORO_COMPANY_URL": "https://yourcompany.scoro.com/api/v2"
    }
  }
}

1. 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 / show my tasks for this week
• fetch tasks for <user email or name>
• show overdue tasks

Hours & Time Entries#

• show my hours this week / how many hours have I logged?
• calculate my billable hours / show billable vs non-billable hours
• send me a report of my billable and non-billable hours
• show time entries for <user> from <date> to <date>

Team & Manager Reports#

• show team status / team pulse
• generate team hours report

Utilization Reporting#

• generate weekly utilization report
• show billable ratio for <user>

Billable Corrections#

• find incorrect billable entries
• fix billable status for entries <IDs>
• adjust all logs on task X to be billable

Environment Variables#

• SCORO_COMPANY_URL — full base URL (e.g. https://yourcompany.scoro.com/api/v2)
• SCORO_API_KEY — 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)#

bash

curl -X POST "$SCORO_COMPANY_URL/timeEntries/list" \
  -H "Content-Type: application/json" \
  -d '{
    "apiKey": "'"$SCORO_API_KEY"'",
    "company_account_id": "yourcompany",
    "filter": {
      "time_entry_date": {
        "from": "2026-03-10",
        "to": "2026-03-16"
      },
      "user_ids": [123]
    },
    "per_page": 100,
    "page": 1,
    "detailed_response": true
  }'

Example Request (PowerShell / Windows)#

powershell

$body = @{
    apiKey = $env:SCORO_API_KEY
    company_account_id = 'yourcompany'
    filter = @{
        time_entry_date = @{ from = '2026-03-10'; to = '2026-03-16' }
        user_ids = @(123)
    }
    per_page = 100
    page = 1
    detailed_response = $true
} | ConvertTo-Json -Depth 10

$response = Invoke-RestMethod -Method Post `
    -Uri "$env:SCORO_COMPANY_URL/timeEntries/list" `
    -ContentType 'application/json' -Body $body

Key Endpoints#

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

EndpointPurposetasks/listFetch tasks with filterstasks/view/IDView single task detailstimeEntries/listFetch time entries (with date, user, billable filters)timeEntries/modify/IDUpdate a time entry (e.g. fix billable status)users/listFetch all users (includes reporting manager info)projects/listFetch projectscontacts/listFetch contacts

Filtering#

Tasks#

json

{
  "filter": {
    "responsible_person_ids": [123],
    "deadline": { "from": "2026-03-16", "to": "2026-03-22" },
    "status": "in_progress"
  }
}

• responsible_person_ids — array of assigned user IDs
• deadline — {"from": "YYYY-MM-DD", "to": "YYYY-MM-DD"}
• modified_date — {"from": "YYYY-MM-DD", "to": "YYYY-MM-DD"}

Time Entries#

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

json

{
  "filter": {
    "time_entry_date": { "from": "2026-03-10", "to": "2026-03-16" },
    "user_ids": [123]
  }
}

• 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
• event_name — task name/title
• datetime_due — deadline (ISO datetime)
• is_completed — 0 or 1
• activity_type — project/category name
• responsible_person_id — assigned user ID
• description — task description

Time Entry Fields#

• time_entry_id — unique ID
• user_id — the user who logged it
• duration — format "HH:MM:SS" (e.g. "01:30:00" = 1.5h)
• title — task/event name
• billable_time_type — "billable", "non_billable", or "custom"
• time_entry_date — "YYYY-MM-DD"
• event_id — the task/event this entry is for
• is_billable — 0 or 1

User Fields#

• id — unique user ID
• full_name — display name
• email — email address
• position — job title

Duration Parsing#

Format is "HH:MM:SS". Convert to decimal hours: hours + minutes/60 + seconds/3600.

Pagination — CRITICAL#

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

You MUST paginate through ALL pages for any list operation:

text

page = 1
all_results = []
loop:
  response = POST .../endpoint { per_page: 100, page: page }
  if length(response.data) == 0: break
  all_results += response.data
  page += 1
  sleep 1 second (rate limit)

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. 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: text

   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
   
   

4. Present with 2 decimal places

Team Reports#

Teams are organized by direct manager (reporting lines).

Workflow for Team Status#

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. 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#

json

POST /timeEntries/modify/<ENTRY_ID>
{
  "apiKey": "...",
  "company_account_id": "yourcompany",
  "request": {
    "billable_time_type": "billable"
  }
}

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#

json

{
  "status": "OK",
  "statusCode": 200,
  "messages": null,
  "data": []
}

All Available Modules#

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

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