> ## Documentation Index
> Fetch the complete documentation index at: https://docs.wellapp.ai/llms.txt
> Use this file to discover all available pages before exploring further.
# Collect
> A `Collect` represents a single data-collection run initiated by an authenticated user, typically driven by the browser extension (popup, side panel, or bluepri
A `Collect` represents a single data-collection run initiated by an authenticated user, typically driven by the browser extension (popup, side panel, or blueprint automation). Each run is bound to one `People` (the subject being enriched), one `Workspace` (stamped at creation from `req.workspace` and never re-derived), and optionally one `Task` (the automation trigger). The `status` lifecycle progresses from `todo` through `in_progress` to `finalized` or `error`. Workspace binding is nullable on legacy rows to handle orphaned people records; all workspace-scoped queries silently exclude those rows via Hasura RLS.
| Naming | Value |
| ------------------------------- | --------------------------------- |
| Object | Collect |
| Resource type (JSON:API `type`) | `collect` |
| Collection / records root | โ (not a records root) |
| REST base | `/v1/collects` |
| Entity class | `Collect` |
**Internal object.** Not currently exposed on the public REST API. The operations below describe the intended contract.
## API operations
| Operation | Method & path | Status |
| --------- | -------------------------- | ---------- |
| List | `GET /v1/collects` | ๐ก Planned |
| Retrieve | `GET /v1/collects/{id}` | ๐ก Planned |
| Create | `POST /v1/collects` | ๐ก Planned |
| Update | `PATCH /v1/collects/{id}` | ๐ก Planned |
| Delete | `DELETE /v1/collects/{id}` | ๐ก Planned |
## Data model
### Attributes
| Field | Type | Required | Constraints | Allowed values | Description |
| ----------- | ---------------------------- | -------- | ------------------------------------------------- | ------------------------------------------ | ----------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| collect\_id | string (UUID) | โ
Yes | unique | โ | Public stable identifier for the collect run. Generated server-side via gen\_random\_uuid(); never user-supplied. |
| provider | string | โช No | varchar(255), nullable | โ | Slug identifying the data-collection provider or browser extension surface that initiated the run (e.g. 'linkedin', 'popup'). Null for manual or legacy rows. |
| status | enum (collect\_status\_enum) | โ
Yes | native enum collect\_status\_enum, default 'todo' | todo \| in\_progress \| finalized \| error | Lifecycle state of the collection run. Defaults to 'todo' at creation; transitions to 'in\_progress', then 'finalized' (success) or 'error' (terminal failure). Terminal statuses trigger a workspace\_connector\_sync\_logs entry. |
| started\_at | ๐ system โ timestamptz | โช No | nullable, timestamptz | โ | Timestamp when the run began active processing. Set by the client via PATCH; null until the extension begins extraction. |
| ended\_at | ๐ system โ timestamptz | โช No | nullable, timestamptz | โ | Timestamp when the run reached a terminal state (finalized or error). Set by the client via PATCH alongside status update. |
| created\_at | ๐ system โ timestamptz | โ
Yes | not null, set once on insert | โ | Row creation timestamp. Set via onCreate hook; never user-editable. |
| updated\_at | ๐ system โ timestamptz | โช No | nullable, set on insert and every update | โ | Last modification timestamp. Automatically set on every update via onUpdate hook. |
| deleted\_at | ๐ system โ timestamptz | โช No | nullable | โ | Soft-delete timestamp. When set, the row is excluded from all workspace-scoped queries and Hasura RLS filters. Set via DELETE endpoint (CollectService.deleteCollect). |
### Relationships
| Name | Type | Required | Description |
| --------- | ------------------ | ---------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- |
| people | to-one (ManyToOne) | โ
Yes | The People record being enriched during this collection run. Resolved at creation from the authenticated user's associated person. FK: collects.people\_pk โ peoples.pk. Indexed via idx\_collects\_people (partial, deleted\_at IS NULL). |
| workspace | to-one (ManyToOne) | โช No (nullable; required on all new rows by service-layer enforcement) | The Workspace this collect run belongs to. Stamped once at creation from req.workspace and never re-derived from subsequent JWT calls, ensuring cross-workspace switches cannot reroute writes mid-flight. Nullable to absorb legacy orphan rows; all workspace-scoped queries (Hasura RLS, service layer) exclude null rows automatically. FK: collects.workspace\_pk โ workspaces.pk (cascade update+delete). Indexed via idx\_collects\_workspace\_status. |
| task | to-one (ManyToOne) | โช No | Optional link to the Task that triggered this collection run (blueprint automation). Null for manual/popup/side-panel collections and legacy rows. FK: collects.task\_pk โ tasks.pk. On Task deletion the FK is set to null (deleteRule: 'set null'). |
### System-computed
* collect\_id โ generated server-side via gen\_random\_uuid() defaultRaw; never accepted from client input
* created\_at โ set once on insert via MikroORM onCreate hook (new Date())
* updated\_at โ refreshed on every update via onUpdate hook (new Date())
* deleted\_at โ soft-delete; set to current timestamp by CollectService.deleteCollect; null on active rows
* workspace (workspace\_pk) โ stamped at creation time from req.workspace by CollectService.createCollect and never subsequently overwritten, even on PATCH calls; this immutability is the tenant-safety guarantee for in-flight runs
* status default โ CollectStatusEnum.TODO at row creation unless overridden by the POST body
* idx\_collects\_status โ partial index on status WHERE deleted\_at IS NULL
* idx\_collects\_people โ partial index on people\_pk WHERE deleted\_at IS NULL
* idx\_collects\_workspace\_status โ composite index on (workspace\_pk, status) for active-run queries
## Example
```json theme={null}
{
"data": {
"type": "collect",
"id": "a3f7c2e1-84b0-4d9e-9c12-1e8f7a3b5d22",
"attributes": {
"collect_id": "a3f7c2e1-84b0-4d9e-9c12-1e8f7a3b5d22",
"provider": "linkedin",
"status": "in_progress",
"started_at": "2026-06-02T09:15:00.000Z",
"ended_at": null,
"created_at": "2026-06-02T09:14:58.123Z",
"updated_at": "2026-06-02T09:15:01.450Z",
"deleted_at": null
},
"relationships": {
"people": {
"data": { "type": "people", "id": "d8b1a4f2-11cc-4e77-b933-abc123456789" }
},
"workspace": {
"data": { "type": "workspace", "id": "7e91cd02-0a3b-4f55-8811-fedcba987654" }
},
"task": {
"data": null
}
}
}
}
```
Source: `/Users/maximechampoux/platform/apps/api/src/database/entities/Collect.ts` ยท domain: ingestion ยท tier: Infrastructure