# Integrations Integrations connect external services to your Zaphiri Inbox. Each integration generates a unique webhook token that external services use to send data into Zaphiri. > [!quote] One integration per source > Create a separate integration for each external service or automation. Each source then has its own token, template config and delivery log. All integration endpoints require [[API-Reference/Authentication|JWT authentication]]. --- ## The Integration Object ```json { "id": "7de5dbca-a75d-485c-989e-ddc17b30192f", "user_id": "7f703dd2-4b68-4118-803e-9618d22f2578", "name": "Todoist Import", "description": "Daily task sync from Todoist", "token": "9fbc...e32c", "is_active": true, "template_config": { "date_mode": "today", "label": "imported", "project": "", "estimated_minutes": 15, "energy": "medium", "priority": "medium", "auto_convert": false, "group_items": false, "group_title_template": "", "list_style": "bullet" }, "trigger_url": null, "trigger_secret": null, "created_at": "2026-02-18T17:42:01Z", "updated_at": "2026-02-18T17:42:01Z", "last_received_at": "2026-02-18T18:15:30Z" } ``` ### Fields | Field | Type | Description | |-------|------|-------------| | `id` | UUID | Unique integration identifier | | `user_id` | UUID | Owner's user ID | | `name` | string | Display name for the integration | | `description` | string or null | Optional description | | `token` | string | Webhook token (masked in GET responses, full in create/rotate) | | `is_active` | boolean | Whether the integration accepts incoming webhooks | | `template_config` | object | Default values applied to incoming items (see below) | | `trigger_url` | string or null | Optional external URL to ping when testing the integration | | `trigger_secret` | string or null | Optional bearer token sent with trigger URL requests | | `created_at` | datetime | When the integration was created (ISO 8601) | | `updated_at` | datetime | When the integration was last modified (ISO 8601) | | `last_received_at` | datetime or null | When the last webhook was received (ISO 8601) | ### Template Config Object Template config defines default values applied to every item received through this integration. You can override these defaults per request with the `overrides` field in the [[API-Reference/Webhooks|webhook payload]]. | Field | Type | Default | Description | |-------|------|---------|-------------| | `date_mode` | string | `""` | How to assign dates: `"today"`, `"tomorrow"`, `"next_available"`, or `"none"` | | `label` | string | `""` | Default label to apply to items | | `project` | string | `""` | Default project to assign items to | | `estimated_minutes` | integer | `0` | Default time estimate in minutes | | `energy` | string | `""` | Default energy level: `"low"`, `"medium"`, or `"high"` | | `priority` | string | `""` | Default priority: `"low"`, `"medium"`, `"high"`, or `"urgent"` | | `auto_convert` | boolean | `false` | Automatically create Zaphiri tasks on receive (skip the Inbox) | | `group_items` | boolean | `false` | When auto-converting, group all items into a single task | | `group_title_template` | string | `""` | Title template for grouped tasks (supports `{{date}}`, `{{count}}`, `{{source}}`) | | `list_style` | string | `"bullet"` | List format for grouped items: `"bullet"` or `"checklist"` | --- ## List Integrations Returns all integrations for the authenticated account, ordered by creation date (newest first). ``` GET /api/v1/integrations ``` ### Headers | Header | Required | Value | |--------|----------|-------| | `Authorization` | Yes | `Bearer <jwt>` | ### Response `200 OK` ```json [ { "id": "7de5dbca-a75d-485c-989e-ddc17b30192f", "user_id": "7f703dd2-4b68-4118-803e-9618d22f2578", "name": "Todoist Import", "description": "Daily task sync from Todoist", "token": "9fbc...e32c", "is_active": true, "template_config": { "date_mode": "today", "label": "imported" }, "created_at": "2026-02-18T17:42:01Z", "updated_at": "2026-02-18T17:42:01Z", "last_received_at": "2026-02-18T18:15:30Z" } ] ``` Returns an empty array `[]` if no integrations exist. > [!note] Token masking > Tokens are masked in every list and get response. Only the [[#Create Integration|create]] and [[#Rotate Integration Token|rotate]] endpoints return the full token. ### curl ```bash curl -X GET https://tickup-api.mytickup.com/api/v1/integrations \ -H "Authorization: Bearer <jwt>" ``` --- ## Create Integration Creates a new integration and returns the full webhook token. Store this token securely, because it is masked in later requests. ``` POST /api/v1/integrations ``` ### Headers | Header | Required | Value | |--------|----------|-------| | `Authorization` | Yes | `Bearer <jwt>` | | `Content-Type` | Yes | `application/json` | ### Request Body | Field | Type | Required | Description | |-------|------|----------|-------------| | `name` | string | **Yes** | Display name for the integration | | `description` | string | No | Optional description | | `template_config` | object | No | Default values for incoming items | | `trigger_url` | string | No | External URL to ping when testing | | `trigger_secret` | string | No | Bearer token for trigger URL requests | ### Example Request ```bash curl -X POST https://tickup-api.mytickup.com/api/v1/integrations \ -H "Authorization: Bearer <jwt>" \ -H "Content-Type: application/json" \ -d '{ "name": "Todoist Import", "description": "Daily task sync from Todoist", "template_config": { "date_mode": "today", "label": "imported", "energy": "medium", "priority": "medium", "estimated_minutes": 15 } }' ``` ### Response `201 Created` ```json { "id": "7de5dbca-a75d-485c-989e-ddc17b30192f", "user_id": "7f703dd2-4b68-4118-803e-9618d22f2578", "name": "Todoist Import", "description": "Daily task sync from Todoist", "token": "9fbc5ae758ae351091a5a61cdfacfeed02941e490a939112ace299423e39e32c", "is_active": true, "template_config": { "date_mode": "today", "label": "imported", "energy": "medium", "priority": "medium", "estimated_minutes": 15 }, "created_at": "2026-02-18T17:42:01Z", "updated_at": "2026-02-18T17:42:01Z" } ``` > [!warning] Save your token > The full token is only returned in this response and when you [[#Rotate Integration Token|rotate it]]. Copy and store it securely before you leave the page. ### Errors | Code | Error | Cause | |------|-------|-------| | `400` | `invalid request body` | Malformed JSON | | `422` | `name is required` | Empty or missing `name` field | | `400` | `integration limit reached (10/10)` | Maximum 10 integrations per account | --- ## Get Integration Returns a single integration by ID. The token is masked. ``` GET /api/v1/integrations/{id} ``` ### Path Parameters | Parameter | Type | Description | |-----------|------|-------------| | `id` | UUID | Integration ID | ### Response `200 OK` ```json { "id": "7de5dbca-a75d-485c-989e-ddc17b30192f", "user_id": "7f703dd2-4b68-4118-803e-9618d22f2578", "name": "Todoist Import", "token": "9fbc...e32c", "is_active": true, "template_config": { ... }, "created_at": "2026-02-18T17:42:01Z", "updated_at": "2026-02-18T17:42:01Z", "last_received_at": "2026-02-18T18:15:30Z" } ``` ### Errors | Code | Error | Cause | |------|-------|-------| | `400` | `invalid integration ID` | Path parameter is not a valid UUID | | `404` | `not found` | Integration does not exist or belongs to another account | ### curl ```bash curl -X GET https://tickup-api.mytickup.com/api/v1/integrations/7de5dbca-a75d-485c-989e-ddc17b30192f \ -H "Authorization: Bearer <jwt>" ``` --- ## Update Integration Updates an existing integration. Only include the fields you want to change. Omitted fields stay unchanged. ``` PUT /api/v1/integrations/{id} ``` ### Path Parameters | Parameter | Type | Description | |-----------|------|-------------| | `id` | UUID | Integration ID | ### Request Body All fields are optional. Include only the fields you want to update. | Field | Type | Description | |-------|------|-------------| | `name` | string | New display name | | `description` | string | New description | | `is_active` | boolean | Enable or disable the integration | | `template_config` | object | New template configuration (replaces entire object) | | `trigger_url` | string | New trigger URL | | `trigger_secret` | string | New trigger secret | ### Example Request ```bash curl -X PUT https://tickup-api.mytickup.com/api/v1/integrations/7de5dbca-a75d-485c-989e-ddc17b30192f \ -H "Authorization: Bearer <jwt>" \ -H "Content-Type: application/json" \ -d '{ "name": "Updated Integration Name", "is_active": false }' ``` ### Response `200 OK` Returns the full updated integration object (token masked). ### Errors | Code | Error | Cause | |------|-------|-------| | `400` | `invalid integration ID` | Path parameter is not a valid UUID | | `400` | `invalid request body` | Malformed JSON | | `404` | `not found` | Integration does not exist or belongs to another account | | `400` | `update failed` | Update error (validation or database failure) | > [!tip] Turning off an integration > Set `is_active` to `false` to temporarily stop accepting webhooks without deleting the integration. Webhooks sent to a disabled integration return `401 invalid_token`. --- ## Delete Integration Permanently deletes an integration. This cannot be undone. The webhook token is invalidated straight away. ``` DELETE /api/v1/integrations/{id} ``` ### Path Parameters | Parameter | Type | Description | |-----------|------|-------------| | `id` | UUID | Integration ID | ### Response `200 OK` ```json { "status": "deleted" } ``` ### Errors | Code | Error | Cause | |------|-------|-------| | `400` | `invalid integration ID` | Path parameter is not a valid UUID | | `404` | `not found` | Integration does not exist or belongs to another account | ### curl ```bash curl -X DELETE https://tickup-api.mytickup.com/api/v1/integrations/7de5dbca-a75d-485c-989e-ddc17b30192f \ -H "Authorization: Bearer <jwt>" ``` --- ## Rotate Integration Token Generates a new webhook token for an integration. The old token is invalidated straight away. Update your external services with the new token. ``` POST /api/v1/integrations/{id}/rotate ``` ### Path Parameters | Parameter | Type | Description | |-----------|------|-------------| | `id` | UUID | Integration ID | ### Response `200 OK` Returns the full integration object with the **new unmasked token**. ```json { "id": "7de5dbca-a75d-485c-989e-ddc17b30192f", "token": "a1b2c3d4e5f6...new_token_here", "is_active": true, ... } ``` > [!warning] Update external services > After rotating, the old token stops working straight away. Update all services using this integration's webhook URL before they send their next request. ### Errors | Code | Error | Cause | |------|-------|-------| | `400` | `invalid integration ID` | Path parameter is not a valid UUID | | `400` | `token rotation failed` | Integration not found or rotation error | ### curl ```bash curl -X POST https://tickup-api.mytickup.com/api/v1/integrations/7de5dbca-a75d-485c-989e-ddc17b30192f/rotate \ -H "Authorization: Bearer <jwt>" ``` --- ## Get Integration History Returns Inbox items received through a specific integration, ordered by received date (newest first). ``` GET /api/v1/integrations/{id}/history ``` ### Path Parameters | Parameter | Type | Description | |-----------|------|-------------| | `id` | UUID | Integration ID | ### Query Parameters | Parameter | Type | Default | Max | Description | |-----------|------|---------|-----|-------------| | `limit` | integer | 50 | 100 | Number of items to return | | `offset` | integer | 0 | - | Number of items to skip | ### Response `200 OK` Returns an array of [[API-Reference/Inbox#The Inbox Item Object|Inbox item objects]]. ```json [ { "id": "537059f9-5f06-44c7-9098-7b72b5cc629e", "integration_id": "7de5dbca-a75d-485c-989e-ddc17b30192f", "user_id": "7f703dd2-4b68-4118-803e-9618d22f2578", "title": "Sprint Backlog Import", "body": "Review pull request #42", "source": "github", "external_id": "GH-42", "metadata": {"repo": "your-api", "pr_number": 42}, "resolved_date": "2026-02-18", "resolved_label": "imported", "resolved_priority": "medium", "status": "pending", "received_at": "2026-02-18T18:15:30Z" } ] ``` ### curl ```bash curl -X GET "https://tickup-api.mytickup.com/api/v1/integrations/7de5dbca-a75d-485c-989e-ddc17b30192f/history?limit=20" \ -H "Authorization: Bearer <jwt>" ``` --- ## Get Webhook Logs Returns delivery logs for a specific integration, ordered by creation date (newest first). Useful for debugging webhook deliveries and finding failures. ``` GET /api/v1/integrations/{id}/logs ``` ### Path Parameters | Parameter | Type | Description | |-----------|------|-------------| | `id` | UUID | Integration ID | ### Query Parameters | Parameter | Type | Default | Max | Description | |-----------|------|---------|-----|-------------| | `limit` | integer | 10 | 100 | Number of logs to return | | `offset` | integer | 0 | - | Number of logs to skip | ### Response `200 OK` ```json [ { "id": "c4a12f8e-9b3d-4e6a-8f1c-2d5e7a9b0c3f", "integration_id": "7de5dbca-a75d-485c-989e-ddc17b30192f", "items_received": 3, "items_deduplicated": 1, "task_id": null, "status": "success", "error_message": null, "source": "github", "created_at": "2026-02-18T18:15:30Z" } ] ``` ### Webhook Log Fields | Field | Type | Description | |-------|------|-------------| | `id` | UUID | Log entry ID | | `integration_id` | UUID | Integration that received the webhook | | `items_received` | integer | Number of items in the request | | `items_deduplicated` | integer | Number of items skipped due to deduplication | | `task_id` | string or null | Zaphiri task ID if auto-convert created a task | | `status` | string | Delivery status: `"success"`, `"validation_failed"`, or `"error"` | | `error_message` | string or null | Error details if status is not `"success"` | | `source` | string or null | Source identifier from the first item in the payload | | `created_at` | datetime | When the webhook was received (ISO 8601) | ### curl ```bash curl -X GET "https://tickup-api.mytickup.com/api/v1/integrations/7de5dbca-a75d-485c-989e-ddc17b30192f/logs?limit=5" \ -H "Authorization: Bearer <jwt>" ``` --- ## Test Webhook Sends a test payload through the integration's webhook pipeline. If the integration has a `trigger_url` configured, the API POSTs to that URL first. Otherwise, a dummy test item is processed through the normal webhook flow. ``` POST /api/v1/integrations/{id}/test ``` ### Path Parameters | Parameter | Type | Description | |-----------|------|-------------| | `id` | UUID | Integration ID | ### Rate Limit This endpoint has a cooldown of **30 seconds per integration** to prevent abuse. ### Response `200 OK` **Without trigger URL** (test item processed through pipeline): ```json { "status": "accepted", "items_received": 1, "items_deduplicated": 0 } ``` **With trigger URL** (external service pinged): ```json { "status": "triggered" } ``` ### Errors | Code | Error | Cause | |------|-------|-------| | `404` | `not found` | Integration does not exist or belongs to another account | | `429` | `please wait before testing again` | Cooldown period has not elapsed (30 seconds) | | `400` | `invalid trigger URL` | Trigger URL is malformed or points to a private address | | `502` | `trigger returned {status}` | External trigger URL returned an error | | `502` | `trigger request failed` | External trigger URL was unreachable | > [!note] Trigger URL safety > Trigger URLs must use `http` or `https` and cannot point to private IP addresses, `localhost`, or internal hostnames. The API resolves hostnames and checks that every resolved IP is public, to prevent SSRF attacks. ### curl ```bash curl -X POST https://tickup-api.mytickup.com/api/v1/integrations/7de5dbca-a75d-485c-989e-ddc17b30192f/test \ -H "Authorization: Bearer <jwt>" ``` --- **Next:** Send data into Zaphiri with [[API-Reference/Webhooks|Webhooks]]