# 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]]