{
  "aid": "timelyapp.com:main-V1",
  "name": "Timely API Docs",
  "type": "Index",
  "description": "The Timely API allows you to integrate time tracking into your applications and workflows. Use it to sync projects, log time entries, export reports, and automate time management.\n\n## Authentication\n\nThis API uses OAuth 2.0 for authentication.\n\n### OAuth 2.0 Authorization Code Flow\n\n1. **Create an OAuth Application**: Go to `https://app.timelyapp.com/{account_id}/oauth_applications` (admin access required)\n2. **Authorize**: Redirect users to `/1.1/oauth/authorize` with your `client_id` and `redirect_uri`\n3. **Exchange Code**: POST to `/1.1/oauth/token` with the authorization code to receive access and refresh tokens\n4. **Use Bearer Token**: Include the token in requests: `Authorization: Bearer {access_token}`\n\n## Core Concepts\n\n### Workspace (Account)\n\nEvery resource in Timely belongs to a workspace, identified by `account_id`. Most endpoints require this ID in the path.\n\nTo get your account IDs, call `GET /1.1/accounts` after authentication.\n\n### Key Resources\n\n| Resource         | Description                                                  |\n| ---------------- | ------------------------------------------------------------ |\n| **Time Entries** | Logged time records with duration, date, project, and notes  |\n| **Projects**     | Work containers with budgets, rates, and client associations |\n| **Clients**      | Customer organizations that projects belong to               |\n| **Users**        | Team members who log time and manage projects                |\n| **Tags**         | Labels for categorizing time entries                         |\n| **Teams**        | Groups of users for organization and reporting               |\n\n## External IDs for Integration Mapping\n\nWhen syncing data between Timely and external systems, use the `external_id` field to maintain bidirectional mapping. This allows you to store your system's ID on Timely resources.\n\n### Supported Resources\n\nProjects, Time Entries, Users, Tags, Clients, and Teams all support `external_id` (string, max 512 characters).\n\n### How It Works\n\n1. **When creating resources**: Include `external_id` with your system's identifier\n2. **When receiving webhooks**: The payload includes `entity_external_id` so you can match events to your records\n3. **When syncing**: Query resources and use `external_id` to reconcile with your system\n\n### Example: Jira Integration\n\n```\n1. Import Jira issue JRA-123 → Create Timely project with external_id: \"JRA-123\"\n2. User logs time in Timely → Webhook fires with entity_external_id: \"JRA-123\"\n3. Your integration receives webhook → Matches JRA-123 → Updates Jira worklog\n4. Next sync → external_id prevents duplicate imports\n```\n\n## Project Access & Permissions\n\nUsers must be assigned to a project before they can log time to it.\n\n### Assigning Users to Projects\n\nWhen creating or updating a project, include the `users` array:\n\n```json\n{\n  \"project\": {\n    \"name\": \"Website Redesign\",\n    \"users\": [\n      { \"user_id\": 123, \"hour_rate\": 150.00 },\n      { \"user_id\": 456, \"hour_rate\": 125.00 }\n    ]\n  }\n}\n```\n\nAlternatively, use `team_ids` to assign all members of specified teams:\n\n```json\n{\n  \"project\": {\n    \"name\": \"Website Redesign\",\n    \"team_ids\": [1, 2]\n  }\n}\n```\n\n### What Happens Without Access\n\nIf a user tries to log time to a project they're not assigned to, the API returns:\n\n```\n422 Unprocessable Entity\n\"project_id is invalid. That person isn't a member of the selected project.\"\n```\n\n### Removing Users\n\nWhen you update a project without including a user in the `users` array, they lose access. Their historical time entries remain visible, but they cannot log new time.\n\n## Common Scenarios\n\n### Getting Data Into Timely\n\n#### Sync Projects from External Tools\n\n**Required fields:**\n- `name` - Project name (must be unique per client)\n- `rate_type` - One of: `\"project\"` (single rate), `\"user\"` (per-user rates), or `\"non-billable\"`\n\n**Rate configuration:**\n- If `rate_type: \"project\"`: Set `hour_rate` for all team members\n- If `rate_type: \"user\"`: Provide rates per user in the `users` array\n\n**Budget configuration (optional):**\n- `budget_type`: `\"H\"` (hours) or `\"M\"` (money)\n- `budget`: The budget amount\n\n**Example:**\n\n```json\nPOST /1.1/{account_id}/projects\n{\n  \"project\": {\n    \"name\": \"Q1 Marketing Campaign\",\n    \"rate_type\": \"project\",\n    \"hour_rate\": 150.00,\n    \"company_id\": 123,\n    \"budget_type\": \"M\",\n    \"budget\": 25000,\n    \"external_id\": \"PROJ-001\"\n  }\n}\n```\n\n**Endpoints:**\n- `GET /1.1/{account_id}/projects` - List existing projects\n- `POST /1.1/{account_id}/projects` - Create new projects\n- `PUT /1.1/{account_id}/projects/{id}` - Update project details\n\n#### Log Time from External Systems\n\n**Required fields:**\n- `project_id` - The project to log time against\n- `day` - Date in `YYYY-MM-DD` format\n\n**Duration (one of):**\n- `hours`, `minutes`, `seconds` - Numeric duration\n- `from` and `to` - Time range in `HH:MM` 24-hour format (e.g., `\"09:00\"`, `\"17:30\"`)\n\n**Billing fields:**\n- `billable` - Whether this time can be invoiced (defaults to project setting)\n- `billed` - Whether this time has been invoiced (locks the entry from editing)\n\n**External references:**\n- `external_id` - Your system's ID for this time entry\n- `external_links` - Array of links to tickets, PRs, etc.\n\n**Example:**\n\n```json\nPOST /1.1/{account_id}/hours\n{\n  \"hours\": {\n    \"project_id\": 456,\n    \"day\": \"2024-01-15\",\n    \"hours\": 2,\n    \"minutes\": 30,\n    \"note\": \"Frontend implementation\",\n    \"billable\": true,\n    \"external_id\": \"TICKET-123\",\n    \"external_links\": [\n      {\n        \"external_id\": \"PR-456\",\n        \"uri\": \"https://github.com/org/repo/pull/456\"\n      }\n    ]\n  }\n}\n```\n\n**Endpoints:**\n- `POST /1.1/{account_id}/hours` - Create time entries\n- `POST /1.1/{account_id}/bulk/hours` - Bulk create time entries\n\n#### Import Users\n\n**Required fields:**\n- `name` - User's display name\n- `email` - Must be valid email format\n- `role_id` - Determines permissions\n\n**Project access:**\n- `projects` - Array of `{ project_id, hour_rate }` to grant access\n- `add_to_all_projects: true` - Add to all current projects\n- `team_ids` - Assign to teams (inherits team's project access)\n\n**Example:**\n\n```json\nPOST /1.1/{account_id}/users\n{\n  \"user\": {\n    \"name\": \"Jane Smith\",\n    \"email\": \"jane@company.com\",\n    \"role_id\": 42,\n    \"default_hour_rate\": 150,\n    \"team_ids\": [1],\n    \"external_id\": \"EMP-001\"\n  }\n}\n```\n\nIf the email already exists, the user is re-invited with updated settings.\n\n**Endpoints:**\n- `GET /1.1/{account_id}/users` - List existing users\n- `POST /1.1/{account_id}/users` - Invite new users\n\n### Getting Data Out of Timely\n\n#### Export for Invoicing/Billing\n\nFilter time entries by date range, project, client, or billing status:\n\n```\nGET /1.1/{account_id}/hours?since=2024-01-01&until=2024-01-31&billed=false&billable=true\n```\n\n**Pagination:**\n- `page` - Page number (default: 1)\n- `per_page` - Records per page (default: 100, max: 100)\n\n**Endpoints:**\n- `GET /1.1/{account_id}/hours` - Retrieve time entries with filters\n- `GET /1.1/{account_id}/reports` - Generate summary reports\n\n#### Real-Time Sync with Webhooks\n\nConfigure webhooks to receive notifications when data changes. Webhook payloads include `entity_external_id` so you can match events to your records without additional API calls.\n\n#### Sync to Payroll Systems\n\nCombine user and time entry data:\n\n1. `GET /1.1/{account_id}/users` - Get user list with rates\n2. `GET /1.1/{account_id}/hours?user_id={id}&since=...&until=...` - Get time entries per user\n\n#### Project Management Sync\n\nTrack project progress and budgets:\n\n- `GET /1.1/{account_id}/projects` - Get project hours and budget consumption\n- `GET /1.1/{account_id}/clients` - Get client summaries\n\n## Bulk Operations\n\nFor importing large amounts of data, use bulk endpoints to reduce API calls.\n\n### Bulk Time Entries\n\n```json\nPOST /1.1/{account_id}/bulk/hours\n{\n  \"hours\": [\n    { \"project_id\": 1, \"day\": \"2024-01-15\", \"hours\": 8, \"note\": \"Task A\" },\n    { \"project_id\": 2, \"day\": \"2024-01-15\", \"hours\": 4, \"note\": \"Task B\" }\n  ]\n}\n```\n\n**Limits:**\n- Maximum 100 records per request\n- Requests with >20 records process asynchronously\n\n**Response codes:**\n- `200 OK` - Synchronous completion (<=20 records)\n- `202 Accepted` - Async processing started (>20 records), includes job ID\n\n**Error handling:**\n- Partial success is possible - some records may succeed while others fail\n- Errors are returned per record with the array index\n\n## Date & Time Formats\n\n| Field Type | Format | Example |\n|------------|--------|---------|\n| Date | `YYYY-MM-DD` | `\"2024-01-15\"` |\n| Time | `HH:MM` (24-hour) | `\"09:00\"`, `\"17:30\"` |\n| Timestamp | ISO 8601 | `\"2024-01-15T14:30:00Z\"` |\n\n## Questions?\n\nContact support@timely.com for API assistance.\n",
  "url": "https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/timelyapp.com/main/V1/apis.json",
  "tags": [
    "timelyapp.com",
    "main"
  ],
  "created": "2026-04-11",
  "modified": "2026-04-11",
  "specificationVersion": "0.19",
  "access": "3rd-Party",
  "maintainers": [
    {
      "FN": "Jentic",
      "X-github": "jentic",
      "url": "https://github.com/jentic"
    }
  ],
  "apis": [
    {
      "aid": "timelyapp.com:main-V1",
      "name": "Timely API Docs",
      "description": "The Timely API allows you to integrate time tracking into your applications and workflows. Use it to sync projects, log time entries, export reports, and automate time management.\n\n## Authentication\n\nThis API uses OAuth 2.0 for authentication.\n\n### OAuth 2.0 Authorization Code Flow\n\n1. **Create an OAuth Application**: Go to `https://app.timelyapp.com/{account_id}/oauth_applications` (admin access required)\n2. **Authorize**: Redirect users to `/1.1/oauth/authorize` with your `client_id` and `redirect_uri`\n3. **Exchange Code**: POST to `/1.1/oauth/token` with the authorization code to receive access and refresh tokens\n4. **Use Bearer Token**: Include the token in requests: `Authorization: Bearer {access_token}`\n\n## Core Concepts\n\n### Workspace (Account)\n\nEvery resource in Timely belongs to a workspace, identified by `account_id`. Most endpoints require this ID in the path.\n\nTo get your account IDs, call `GET /1.1/accounts` after authentication.\n\n### Key Resources\n\n| Resource         | Description                                                  |\n| ---------------- | ------------------------------------------------------------ |\n| **Time Entries** | Logged time records with duration, date, project, and notes  |\n| **Projects**     | Work containers with budgets, rates, and client associations |\n| **Clients**      | Customer organizations that projects belong to               |\n| **Users**        | Team members who log time and manage projects                |\n| **Tags**         | Labels for categorizing time entries                         |\n| **Teams**        | Groups of users for organization and reporting               |\n\n## External IDs for Integration Mapping\n\nWhen syncing data between Timely and external systems, use the `external_id` field to maintain bidirectional mapping. This allows you to store your system's ID on Timely resources.\n\n### Supported Resources\n\nProjects, Time Entries, Users, Tags, Clients, and Teams all support `external_id` (string, max 512 characters).\n\n### How It Works\n\n1. **When creating resources**: Include `external_id` with your system's identifier\n2. **When receiving webhooks**: The payload includes `entity_external_id` so you can match events to your records\n3. **When syncing**: Query resources and use `external_id` to reconcile with your system\n\n### Example: Jira Integration\n\n```\n1. Import Jira issue JRA-123 → Create Timely project with external_id: \"JRA-123\"\n2. User logs time in Timely → Webhook fires with entity_external_id: \"JRA-123\"\n3. Your integration receives webhook → Matches JRA-123 → Updates Jira worklog\n4. Next sync → external_id prevents duplicate imports\n```\n\n## Project Access & Permissions\n\nUsers must be assigned to a project before they can log time to it.\n\n### Assigning Users to Projects\n\nWhen creating or updating a project, include the `users` array:\n\n```json\n{\n  \"project\": {\n    \"name\": \"Website Redesign\",\n    \"users\": [\n      { \"user_id\": 123, \"hour_rate\": 150.00 },\n      { \"user_id\": 456, \"hour_rate\": 125.00 }\n    ]\n  }\n}\n```\n\nAlternatively, use `team_ids` to assign all members of specified teams:\n\n```json\n{\n  \"project\": {\n    \"name\": \"Website Redesign\",\n    \"team_ids\": [1, 2]\n  }\n}\n```\n\n### What Happens Without Access\n\nIf a user tries to log time to a project they're not assigned to, the API returns:\n\n```\n422 Unprocessable Entity\n\"project_id is invalid. That person isn't a member of the selected project.\"\n```\n\n### Removing Users\n\nWhen you update a project without including a user in the `users` array, they lose access. Their historical time entries remain visible, but they cannot log new time.\n\n## Common Scenarios\n\n### Getting Data Into Timely\n\n#### Sync Projects from External Tools\n\n**Required fields:**\n- `name` - Project name (must be unique per client)\n- `rate_type` - One of: `\"project\"` (single rate), `\"user\"` (per-user rates), or `\"non-billable\"`\n\n**Rate configuration:**\n- If `rate_type: \"project\"`: Set `hour_rate` for all team members\n- If `rate_type: \"user\"`: Provide rates per user in the `users` array\n\n**Budget configuration (optional):**\n- `budget_type`: `\"H\"` (hours) or `\"M\"` (money)\n- `budget`: The budget amount\n\n**Example:**\n\n```json\nPOST /1.1/{account_id}/projects\n{\n  \"project\": {\n    \"name\": \"Q1 Marketing Campaign\",\n    \"rate_type\": \"project\",\n    \"hour_rate\": 150.00,\n    \"company_id\": 123,\n    \"budget_type\": \"M\",\n    \"budget\": 25000,\n    \"external_id\": \"PROJ-001\"\n  }\n}\n```\n\n**Endpoints:**\n- `GET /1.1/{account_id}/projects` - List existing projects\n- `POST /1.1/{account_id}/projects` - Create new projects\n- `PUT /1.1/{account_id}/projects/{id}` - Update project details\n\n#### Log Time from External Systems\n\n**Required fields:**\n- `project_id` - The project to log time against\n- `day` - Date in `YYYY-MM-DD` format\n\n**Duration (one of):**\n- `hours`, `minutes`, `seconds` - Numeric duration\n- `from` and `to` - Time range in `HH:MM` 24-hour format (e.g., `\"09:00\"`, `\"17:30\"`)\n\n**Billing fields:**\n- `billable` - Whether this time can be invoiced (defaults to project setting)\n- `billed` - Whether this time has been invoiced (locks the entry from editing)\n\n**External references:**\n- `external_id` - Your system's ID for this time entry\n- `external_links` - Array of links to tickets, PRs, etc.\n\n**Example:**\n\n```json\nPOST /1.1/{account_id}/hours\n{\n  \"hours\": {\n    \"project_id\": 456,\n    \"day\": \"2024-01-15\",\n    \"hours\": 2,\n    \"minutes\": 30,\n    \"note\": \"Frontend implementation\",\n    \"billable\": true,\n    \"external_id\": \"TICKET-123\",\n    \"external_links\": [\n      {\n        \"external_id\": \"PR-456\",\n        \"uri\": \"https://github.com/org/repo/pull/456\"\n      }\n    ]\n  }\n}\n```\n\n**Endpoints:**\n- `POST /1.1/{account_id}/hours` - Create time entries\n- `POST /1.1/{account_id}/bulk/hours` - Bulk create time entries\n\n#### Import Users\n\n**Required fields:**\n- `name` - User's display name\n- `email` - Must be valid email format\n- `role_id` - Determines permissions\n\n**Project access:**\n- `projects` - Array of `{ project_id, hour_rate }` to grant access\n- `add_to_all_projects: true` - Add to all current projects\n- `team_ids` - Assign to teams (inherits team's project access)\n\n**Example:**\n\n```json\nPOST /1.1/{account_id}/users\n{\n  \"user\": {\n    \"name\": \"Jane Smith\",\n    \"email\": \"jane@company.com\",\n    \"role_id\": 42,\n    \"default_hour_rate\": 150,\n    \"team_ids\": [1],\n    \"external_id\": \"EMP-001\"\n  }\n}\n```\n\nIf the email already exists, the user is re-invited with updated settings.\n\n**Endpoints:**\n- `GET /1.1/{account_id}/users` - List existing users\n- `POST /1.1/{account_id}/users` - Invite new users\n\n### Getting Data Out of Timely\n\n#### Export for Invoicing/Billing\n\nFilter time entries by date range, project, client, or billing status:\n\n```\nGET /1.1/{account_id}/hours?since=2024-01-01&until=2024-01-31&billed=false&billable=true\n```\n\n**Pagination:**\n- `page` - Page number (default: 1)\n- `per_page` - Records per page (default: 100, max: 100)\n\n**Endpoints:**\n- `GET /1.1/{account_id}/hours` - Retrieve time entries with filters\n- `GET /1.1/{account_id}/reports` - Generate summary reports\n\n#### Real-Time Sync with Webhooks\n\nConfigure webhooks to receive notifications when data changes. Webhook payloads include `entity_external_id` so you can match events to your records without additional API calls.\n\n#### Sync to Payroll Systems\n\nCombine user and time entry data:\n\n1. `GET /1.1/{account_id}/users` - Get user list with rates\n2. `GET /1.1/{account_id}/hours?user_id={id}&since=...&until=...` - Get time entries per user\n\n#### Project Management Sync\n\nTrack project progress and budgets:\n\n- `GET /1.1/{account_id}/projects` - Get project hours and budget consumption\n- `GET /1.1/{account_id}/clients` - Get client summaries\n\n## Bulk Operations\n\nFor importing large amounts of data, use bulk endpoints to reduce API calls.\n\n### Bulk Time Entries\n\n```json\nPOST /1.1/{account_id}/bulk/hours\n{\n  \"hours\": [\n    { \"project_id\": 1, \"day\": \"2024-01-15\", \"hours\": 8, \"note\": \"Task A\" },\n    { \"project_id\": 2, \"day\": \"2024-01-15\", \"hours\": 4, \"note\": \"Task B\" }\n  ]\n}\n```\n\n**Limits:**\n- Maximum 100 records per request\n- Requests with >20 records process asynchronously\n\n**Response codes:**\n- `200 OK` - Synchronous completion (<=20 records)\n- `202 Accepted` - Async processing started (>20 records), includes job ID\n\n**Error handling:**\n- Partial success is possible - some records may succeed while others fail\n- Errors are returned per record with the array index\n\n## Date & Time Formats\n\n| Field Type | Format | Example |\n|------------|--------|---------|\n| Date | `YYYY-MM-DD` | `\"2024-01-15\"` |\n| Time | `HH:MM` (24-hour) | `\"09:00\"`, `\"17:30\"` |\n| Timestamp | ISO 8601 | `\"2024-01-15T14:30:00Z\"` |\n\n## Questions?\n\nContact support@timely.com for API assistance.\n",
      "image": "",
      "baseURL": "https://api.timelyapp.com",
      "humanURL": "https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi/timelyapp.com/main/V1",
      "version": "V1",
      "tags": [
        "timelyapp.com",
        "main"
      ],
      "properties": [
        {
          "type": "OpenAPI",
          "name": "OpenAPI definition",
          "url": "https://raw.githubusercontent.com/jentic/jentic-public-apis/refs/heads/main/apis/openapi/timelyapp.com/main/V1/openapi.json",
          "mediaType": "application/openapi+json"
        },
        {
          "type": "GitHubRepo",
          "url": "https://github.com/jentic/jentic-public-apis/tree/main/apis/openapi/timelyapp.com/main/V1"
        }
      ]
    }
  ]
}