Timix.AI — Workato Custom Connector

The official Workato custom connector for Timix.AI — time tracking & billing for services businesses. It talks to the public Timix Integration API (https://api.timix.ai/api/integration/v1) and lets Workato recipes:

• Trigger when new records appear in Timix (customers, projects, time entries, invoices).
• Create records in Timix (customers, projects, tasks, subtasks, time entries).

Timix.AI's hierarchy is Customer → Project → Task → SubTask → Time Entry, and all time is logged at the SubTask level.

---

What it does

Connection

• API-key auth. You provide a Timix Integration API key; the connector sends it as Authorization: Bearer <key>.
• Base URL. https://api.timix.ai/api/integration/v1.
• Connection test & label. On connect, the connector calls GET /me. The organization name becomes the connection label. If the organization's plan does not include API access, the connector shows a clear message that Professional+ is required.

Triggers (polling)

All triggers are poll-based and deduplicated by record id. Timix list endpoints return results newest-created first; the connector stores a createdAfter cursor in the trigger closure so each poll only fetches records created since the last one. Each trigger also offers an optional Created after input to control the starting point on the first poll.

Trigger	Endpoint	Notes
New customer	GET /customers	id, name, country, currency, contactEmail, timestamps
New project	GET /projects	id, name, parentId/customerId, status, allowedBillingTypes, timestamps
New time entry	GET /time-reports	id, subTaskId, reporterId, start, end, duration, hours, date, billingType, status, text; optional Work date from/to filter
New invoice	GET /invoices	id, number, status, totalAmount, currency, customerId; optional Date from/to filter. Uses the CRUDResponse { data: [...] } envelope and pageNumber paging (not { items } / page).

Actions (create)

The organization is bound to the API key server-side, so no org id is ever sent.

Action	Endpoint	Required inputs	Optional inputs
Create customer	POST /customers	name	description, country, currency, contactEmail
Create project	POST /projects	name, parentId (customer id)	description, billingType (TM / Fix / OVH) — sent to the API as the allowedBillingTypes string array
Create task	POST /tasks	name, parentId (project id)	description
Create subtask	POST /subtasks	name, parentId (task id)	description
Log time	POST /time-reports	subTaskId, start, end	text

---

Getting an API key

1. In the Timix.AI web app, go to Settings → API Keys.
2. Create / copy a key — new keys start with tmx_ (older bbl_ keys still work).
   • API access requires a Professional+ plan. On a lower plan, GET /me returns hasApiAccess: false and the connection test surfaces an upgrade message.
3. In Workato, add a Timix connection and paste your key.
4. Click Connect. On success the connection is labeled with your organization name.

Keep API keys secret — treat them like passwords. Rotate them in Settings → API Keys if exposed.

---

Installing the connector

This is a standalone Workato SDK connector (connector.rb). Import it into your own Workato account with either the UI or the SDK CLI.

Option A — Workato UI (quickest)

1. Sign in to Workato → Tools → Connector SDK → Create connector (or Community connectors → Build a connector).
2. Choose to start from code, then paste the contents of connector.rb into the editor.
3. Save, then use the Test tab to add a connection (Timix API key) and run the actions/triggers.
4. When ready, Release a version and (optionally) submit it for the Workato community/marketplace.

Option B — Workato SDK CLI (recommended for version control)

# 1. Install the gem (Ruby 2.7+).
gem install workato-connector-sdk

# 2. From this repo, set your Workato API token.
export WORKATO_API_TOKEN=...           # from Workato → Account → API tokens

# 3. Validate locally.
workato exec test --connector connector.rb        # runs the `test:` lambda

# 4. Push to your Workato workspace.
workato push --connector connector.rb --title "Timix"

• Use a settings.yaml (git-ignored) to hold your API key for local workato exec runs.
• See the Workato SDK CLI docs for workato push, workato exec, and RSpec testing.

---

Rate limits & error handling (built in)

• Rate limit. Timix enforces a per-key fixed 60-second window (120/min Free–Starter, 300/min Professional, 1000/min Business). On limit it returns HTTP 429 with a Retry-After header (seconds). The connector's global after_error_response hook surfaces a clear "rate limit exceeded — retry after N seconds" message. To auto-retry, enable request-level retry on the recipe step, or add a small delay/retry in the recipe.
• Entitlement. Unentitled calls return HTTP 403 with error.code = "entitlement_required"; the connector surfaces "API access requires a Professional+ plan."
• Errors. Non-2xx responses come back as { error: { code, message, details? } } with real HTTP status codes (422 validation, 401, 403, 404, 409, 429, 500). The connector surfaces the real error.message (and code) instead of a generic failure, so users see the actual reason.

---

Known limitation — polling only (no instant triggers yet)

This connector uses polling triggers only. There are no real-time / instant (webhook) triggers in this version yet — real-time triggers are a planned enhancement. Practical implications:

• New-record triggers fire on Workato's poll interval (e.g. every few minutes), not instantly.
• Triggers dedupe by record id, so a record is only delivered once even across overlapping polls.

---

API reference (summary)

• Base URL: https://api.timix.ai/api/integration/v1.
• Auth: Authorization: Bearer <key> (also accepts X-Api-Key).
• Test / label: GET /me → { organizationId, organizationName, userId, apiKeyId, plan, hasApiAccess }.
• Pagination: ?page=<1-based>&pageSize=<n ≤200, default 50> → { items, totalCount, page, pageSize, hasMore } (also X-Total-Count header). Stable-sorted newest-first.
• Polling filter: ?createdAfter=<ISO-8601 UTC> (newest-created first). Also ?updatedAfter=<ISO> for new-or-updated, and ?from=&to= on /time-reports (work date) and /invoices.

---

Learn more at timix.ai · Integrations · hello@timix.ai