Scoro

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:

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

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

Standard Prompts

Users can trigger these capabilities with natural language:

Task Management

Hours & Time Entries

Team & Manager Reports

Utilization Reporting

Billable Corrections

Environment Variables

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)

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)

$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}

| Endpoint | Purpose | |----------|---------| | tasks/list | Fetch tasks with filters | | tasks/view/ID | View single task details | | timeEntries/list | Fetch time entries (with date, user, billable filters) | | timeEntries/modify/ID | Update a time entry (e.g. fix billable status) | | users/list | Fetch all users (includes reporting manager info) | | projects/list | Fetch projects | | contacts/list | Fetch contacts |

Filtering

Tasks

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

Time Entries

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

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

Users

No specific filter needed. Returns all active users.

Response Fields

Task Fields

Time Entry Fields

User Fields

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:

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:

   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
   

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

Correction

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

Always confirm with the user before modifying entries.

Rate Limits

Response Format

{
  "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

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:

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

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