Timesheet

POST/v1/timesheet

Generate timesheet invoice PDFs for hourly billing. Track tasks, dates, and hours worked with auto-calculated totals.

Auto-Calculated Fields

The following values are computed automatically — do not send them in the request:

Amount per entry = entry hours × hourly_rate
Total hours = sum of all entry hours
Subtotal = total hours × hourly_rate
Tax amount = subtotal × tax.rate / 100
Total = subtotal + tax amount

Headers

Header	Value	Required
`Authorization`	Bearer YOUR_API_KEY	Yes
`Content-Type`	application/json	Yes

Request Body

json

{
  "timesheet_number": "TS-001",
  "date": "2026-03-17",
  "due_date": "2026-04-17",
  "currency": "USD",
  "period": "March 1–15, 2026",
  "hourly_rate": 150,
  "from": {
    "name": "Jane Smith",
    "email": "jane@freelancer.com",
    "address": "456 Oak Ave\nPortland, OR 97201"
  },
  "to": {
    "name": "TechCorp Inc.",
    "email": "accounts@techcorp.com",
    "address": "789 Corporate Blvd\nSan Francisco, CA 94102"
  },
  "entries": [
    {
      "date": "2026-03-01",
      "description": "Frontend development — dashboard UI",
      "hours": 8
    },
    {
      "date": "2026-03-02",
      "description": "API integration and testing",
      "hours": 6.5
    },
    {
      "date": "2026-03-03",
      "description": "Bug fixes and code review",
      "hours": 4
    },
    {
      "date": "2026-03-05",
      "description": "Design review meeting + revisions",
      "hours": 3
    },
    {
      "date": "2026-03-06",
      "description": "Authentication flow implementation",
      "hours": 7.5
    }
  ],
  "tax": {
    "rate": 0
  },
  "notes": "Payment due within 30 days. Thank you for your business."
}

Fields

Field	Type	Required	Description
`timesheet_number`	string	Yes	Unique identifier (e.g. "TS-001")
`date`	string	Yes	Issue date (YYYY-MM-DD)
`currency`	string	Yes	3-letter currency code (e.g. USD, EUR)
`hourly_rate`	number	Yes	Rate per hour
`from`	object	Yes	Your details (freelancer/agency)
`from.name`	string	Yes	Your name or company name
`from.email`	string	No	Your email
`from.address`	string	No	Your address
`to`	object	Yes	Client details
`to.name`	string	Yes	Client name
`to.email`	string	No	Client email
`to.address`	string	No	Client address
`entries`	array	Yes	Time entries (at least 1)
`entries[].date`	string	Yes	Date of work (YYYY-MM-DD)
`entries[].description`	string	Yes	What was done
`entries[].hours`	number	Yes	Hours worked (supports decimals like 6.5)
`due_date`	string	No	Payment due date (YYYY-MM-DD)
`period`	string	No	Billing period (e.g. "March 1–15, 2026")
`tax`	object	No	Tax settings
`tax.rate`	number	No	Tax percentage (default: 0)
`direction`	string	No	"ltr" (default) or "rtl" for Arabic/Hebrew
`language`	string	No	Language hint: "ar", "he", "fa", etc.
`notes`	string	No	Additional notes shown at bottom
`branding`	object	No	Branding overrides
`branding.accent_color`	string	No	Hex color override (e.g. #22c55e)

Full Example

bash

curl -X POST https://api.kagyz.com/v1/timesheet \
  -H "Authorization: Bearer YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "timesheet_number": "TS-001",
    "date": "2026-03-17",
    "currency": "USD",
    "hourly_rate": 150,
    "period": "March 1–15, 2026",
    "from": { "name": "Jane Smith" },
    "to": { "name": "TechCorp Inc." },
    "entries": [
      { "date": "2026-03-01", "description": "Frontend development", "hours": 8 },
      { "date": "2026-03-02", "description": "API integration", "hours": 6.5 },
      { "date": "2026-03-03", "description": "Code review", "hours": 4 }
    ]
  }' \
  --output timesheet.pdf

javascript

const response = await fetch('https://api.kagyz.com/v1/timesheet', {
  method: 'POST',
  headers: {
    'Authorization': 'Bearer YOUR_API_KEY',
    'Content-Type': 'application/json'
  },
  body: JSON.stringify({
    timesheet_number: 'TS-001',
    date: '2026-03-17',
    currency: 'USD',
    hourly_rate: 150,
    period: 'March 1–15, 2026',
    from: { name: 'Jane Smith', email: 'jane@freelancer.com' },
    to: { name: 'TechCorp Inc.', email: 'accounts@techcorp.com' },
    entries: [
      { date: '2026-03-01', description: 'Frontend development', hours: 8 },
      { date: '2026-03-02', description: 'API integration', hours: 6.5 },
      { date: '2026-03-03', description: 'Code review', hours: 4 }
    ],
    notes: 'Payment due within 30 days.'
  })
});

const blob = await response.blob();
// Save or send the PDF

RTL / Arabic Example

Add direction: "rtl" to generate an Arabic timesheet with right-to-left layout:

json

{
  "timesheet_number": "TS-001",
  "date": "2026-03-17",
  "currency": "SAR",
  "hourly_rate": 500,
  "direction": "rtl",
  "from": { "name": "أحمد محمد" },
  "to": { "name": "شركة التقنية المتقدمة" },
  "entries": [
    { "date": "2026-03-01", "description": "تطوير الواجهة الأمامية", "hours": 8 },
    { "date": "2026-03-02", "description": "اختبار واجهة البرمجة", "hours": 6.5 }
  ]
}

Response

Success (200)

Content-Type: application/pdf
Body: PDF binary data

Errors

Status	Body
`400`	`{ "error": "timesheet_number is required" }`
`401`	`{ "error": "Invalid API key" }`
`429`	`{ "error": "Monthly limit reached. Please upgrade." }`

Try our free Timesheet Generator — no API key needed →

Need a standard invoice? See the Invoice API →

Send this document via email → See Email Delivery

Supports Arabic & RTL → See docs

Every generated PDF is automatically stored and gets a shareable URL. Check the X-Kagyz-Document-URL response header. Learn more →