# Inbox
Inbox items are created when external services send data through the [[API-Reference/Webhooks|webhook endpoint]]. Items arrive as pending, and you can review them, convert them to Zaphiri tasks or dismiss them.
> [!quote] Your triage queue for external items
> The Inbox is a staging area. Items arrive from integrations, and you decide what becomes a task and what gets dismissed.
All Inbox endpoints require [[API-Reference/Authentication|JWT authentication]].
---
## The Inbox Item Object
```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": "Fix login redirect bug",
"source": "jira",
"external_id": "PROJ-142",
"metadata": {"sprint": "2026-Q1-3"},
"resolved_date": "2026-02-18",
"resolved_label": "imported",
"resolved_project": null,
"resolved_estimated_minutes": 15,
"resolved_energy": "medium",
"resolved_priority": "medium",
"status": "pending",
"received_at": "2026-02-18T18:15:30Z",
"processed_at": null
}
```
### Fields
| Field | Type | Description |
|-------|------|-------------|
| `id` | UUID | Unique inbox item identifier |
| `integration_id` | UUID | The integration that created this item |
| `user_id` | UUID | Owner's user ID |
| `title` | string or null | Batch title from the webhook request |
| `body` | string or null | Item text content |
| `source` | string or null | Source identifier (for example `"github"`, `"todoist"`) |
| `external_id` | string or null | External system ID (used for deduplication) |
| `metadata` | object or null | Arbitrary JSON metadata from the webhook request |
| `resolved_date` | string or null | Computed date in `YYYY-MM-DD` format (from template config or override) |
| `resolved_label` | string or null | Computed label (from template config or override) |
| `resolved_project` | string or null | Computed project (from template config or override) |
| `resolved_estimated_minutes` | integer or null | Computed time estimate in minutes |
| `resolved_energy` | string or null | Computed energy level: `"low"`, `"medium"`, or `"high"` |
| `resolved_priority` | string or null | Computed priority: `"low"`, `"medium"`, `"high"`, or `"urgent"` |
| `status` | string | Item status: `"pending"`, `"converted"`, or `"dismissed"` |
| `task_id` | UUID (only present when converted) | Zaphiri task ID if the item has been converted. This field is omitted when the item has not been converted. |
| `received_at` | datetime | When the item was created (ISO 8601) |
| `processed_at` | datetime or null | When the item was converted or dismissed (ISO 8601) |
### Item Status Lifecycle
```
pending → converted (item became a Zaphiri task)
pending → dismissed (item was discarded)
```
Items cannot be reverted once converted or dismissed.
---
## List Pending Items
Returns Inbox items with `status: "pending"` for the authenticated account, ordered by received date (newest first).
```
GET /api/v1/inbox
```
### Headers
| Header | Required | Value |
|--------|----------|-------|
| `Authorization` | Yes | `Bearer <jwt>` |
### 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`
```json
[
{
"id": "537059f9-5f06-44c7-9098-7b72b5cc629e",
"integration_id": "7de5dbca-a75d-485c-989e-ddc17b30192f",
"user_id": "7f703dd2-4b68-4118-803e-9618d22f2578",
"body": "Fix login redirect bug",
"source": "jira",
"external_id": "PROJ-142",
"resolved_date": "2026-02-18",
"resolved_label": "imported",
"resolved_priority": "medium",
"status": "pending",
"received_at": "2026-02-18T18:15:30Z"
}
]
```
Returns an empty array `[]` if no pending items exist.
### curl
```bash
curl -X GET "https://tickup-api.mytickup.com/api/v1/inbox?limit=20&offset=0" \
-H "Authorization: Bearer <jwt>"
```
---
## Convert Item
Converts a pending Inbox item into a Zaphiri task. The item's resolved values (date, label, priority, energy and so on) are applied to the new task.
```
POST /api/v1/inbox/{id}/convert
```
### Path Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | UUID | Inbox item ID |
### Headers
| Header | Required | Value |
|--------|----------|-------|
| `Authorization` | Yes | `Bearer <jwt>` |
### Response `200 OK`
Returns the updated Inbox item with `status: "converted"` and the new `task_id`:
```json
{
"id": "537059f9-5f06-44c7-9098-7b72b5cc629e",
"integration_id": "7de5dbca-a75d-485c-989e-ddc17b30192f",
"user_id": "7f703dd2-4b68-4118-803e-9618d22f2578",
"body": "Fix login redirect bug",
"source": "jira",
"status": "converted",
"task_id": "a1b2c3d4-e5f6-7890-abcd-ef1234567890",
"received_at": "2026-02-18T18:15:30Z",
"processed_at": "2026-02-18T19:30:00Z"
}
```
### Task Creation Details
When an item is converted, a task is created in the main Zaphiri app with these mappings:
| Inbox Item Field | Zaphiri Task Field |
|------------------|-------------------|
| `title` or `body` (first 100 chars) | Task name |
| `body` | Task description |
| `resolved_priority` | Priority (`"medium"` maps to `"normal"`) |
| `resolved_energy` | Energy (`"low"` → `"recharge"`, `"medium"` → `"steady"`, `"high"` → `"peak"`) |
| `resolved_date` | Panel date |
### Errors
| Code | Error | Cause |
|------|-------|-------|
| `400` | `invalid item ID` | Path parameter is not a valid UUID |
| `400` | `conversion failed` | Item not found, already processed, or task creation failed |
### curl
```bash
curl -X POST https://tickup-api.mytickup.com/api/v1/inbox/537059f9-5f06-44c7-9098-7b72b5cc629e/convert \
-H "Authorization: Bearer <jwt>"
```
---
## Dismiss Item
Dismisses a pending Inbox item. The item is marked as dismissed and no longer appears in the pending list.
```
POST /api/v1/inbox/{id}/dismiss
```
### Path Parameters
| Parameter | Type | Description |
|-----------|------|-------------|
| `id` | UUID | Inbox item ID |
### Headers
| Header | Required | Value |
|--------|----------|-------|
| `Authorization` | Yes | `Bearer <jwt>` |
### Response `200 OK`
```json
{
"status": "dismissed"
}
```
### Errors
| Code | Error | Cause |
|------|-------|-------|
| `400` | `invalid item ID` | Path parameter is not a valid UUID |
| `400` | `dismiss failed` | Item not found or already processed |
### curl
```bash
curl -X POST https://tickup-api.mytickup.com/api/v1/inbox/537059f9-5f06-44c7-9098-7b72b5cc629e/dismiss \
-H "Authorization: Bearer <jwt>"
```
---
## Bulk Action
Perform the same action on several Inbox items in a single request. Supports bulk dismiss and bulk convert.
```
POST /api/v1/inbox/bulk
```
### Headers
| Header | Required | Value |
|--------|----------|-------|
| `Authorization` | Yes | `Bearer <jwt>` |
| `Content-Type` | Yes | `application/json` |
### Request Body
| Field | Type | Required | Description |
|-------|------|----------|-------------|
| `ids` | array of UUIDs | **Yes** | Item IDs to act on (1–100 items) |
| `action` | string | **Yes** | Action to perform: `"convert"` or `"dismiss"` |
### Example Request: Bulk Dismiss
```bash
curl -X POST https://tickup-api.mytickup.com/api/v1/inbox/bulk \
-H "Authorization: Bearer <jwt>" \
-H "Content-Type: application/json" \
-d '{
"ids": [
"537059f9-5f06-44c7-9098-7b72b5cc629e",
"63f75b47-da37-4e35-8511-a9fd0bb3ba29",
"8d66ad8f-c012-4837-9821-df54b55c0e2c"
],
"action": "dismiss"
}'
```
### Example Request: Bulk Convert
```bash
curl -X POST https://tickup-api.mytickup.com/api/v1/inbox/bulk \
-H "Authorization: Bearer <jwt>" \
-H "Content-Type: application/json" \
-d '{
"ids": [
"537059f9-5f06-44c7-9098-7b72b5cc629e",
"63f75b47-da37-4e35-8511-a9fd0bb3ba29"
],
"action": "convert"
}'
```
### Response `200 OK`
```json
{
"processed": 3,
"failed": 0
}
```
| Field | Type | Description |
|-------|------|-------------|
| `processed` | integer | Number of items successfully processed |
| `failed` | integer | Number of items that failed |
> [!note] Partial success
> For bulk convert, partial failures return the result with both `processed` and `failed` counts. Individual item errors are included in an `errors` object keyed by item ID.
### Errors
| Code | Error | Cause |
|------|-------|-------|
| `400` | `no IDs provided` | Empty IDs array |
| `400` | `maximum 100 items per bulk action` | Too many IDs |
| `400` | `invalid action: X (must be 'convert' or 'dismiss')` | Unknown action |
| `400` | `all conversions failed: ...` | Every item in bulk convert failed |
### Validation Rules
| Rule | Limit |
|------|-------|
| Minimum items | 1 |
| Maximum items | 100 |
| Valid actions | `"convert"`, `"dismiss"` |
---
## Common Workflows
### Triage Workflow
1. External services send data via [[API-Reference/Webhooks|webhooks]]
2. Items appear in your pending Inbox
3. Review items with `GET /api/v1/inbox`
4. Convert actionable items with `POST /api/v1/inbox/{id}/convert`
5. Dismiss noise with `POST /api/v1/inbox/{id}/dismiss`
6. Use bulk actions for batch processing
### Auto-Convert Workflow
1. Configure the integration with `auto_convert: true` in the template config
2. External services send data via webhooks
3. Items are converted to Zaphiri tasks automatically (skipping the Inbox)
4. Check the [[API-Reference/Integrations#Get Webhook Logs|webhook logs]] to confirm delivery
5. Find created tasks by `task_id` in the webhook response
> [!tip] Start manual, then automate
> Begin with manual triage to understand what each integration sends. Once you trust the data quality, turn on auto-convert to skip the Inbox entirely.
---
**Next:** [[API-Reference/Examples|Examples & Scenarios]] | **Start:** [[API-Reference/API-Reference|API Reference]]