Skip to content

Notion#

Notion is registered for CSV import. It parses a documented Notion task database/data-source CSV export into a reviewable import session, then projects each task into the internal integrations task-create draft for operator review.

Capability Method Status
CSV_IMPORT Upload a Notion task database CSV export Built
SYNC Pull tasks from the Notion API Not built
USER_IMPORT Standalone Notion user-directory import Not built
WEBHOOK Signed Notion event handling Not built

The endpoints below live under /api/v1/providers/notion/.... They are generic - the same routes serve any registered provider by substituting the {provider} path segment. All routes require an organization-scoped user token (see Authentication).

Importing From CSV#

POST /api/v1/providers/notion/imports/csv?organization_id=<id>

curl -X POST "https://<host>/api/v1/providers/notion/imports/csv?organization_id=590789" \
  -H "Authorization: Bearer <user-token>" \
  -F "file=@notion-task-export.csv"

The first Notion CSV capability supports a TeamBoost task-database contract, not arbitrary Notion pages. Export a task database/table from Notion as Markdown & CSV, and include these required properties:

Required field Accepted column names
Stable page/task id or URL Notion Page ID, Page ID, Page URL, URL, Unique ID, Task ID, ID
Title Name, Title, Task, Task Name
Status Status
Created timestamp Created, Created time, Created At, Created Date

Optional fields the parser understands include Updated, Type, Priority, Description, Assignee, Assignee IDs, Assignee Email, Creator, Creator ID, Creator Email, Requester, Requester ID, Requester Email, Due date, Labels, Parent, Depends On, URL, and Data Source. Any exported column is preserved in the lossless source record even when it is not projected into a TeamBoost field.

Malformed rows are returned in rowErrors rather than failing the whole import. A file that does not carry the required column groups fails with invalid_csv_format.

The Import Session#

{
  "status": "success",
  "message": "CSV parsed; review the proposed user mapping.",
  "data": {
    "provider": "notion",
    "capability": "CSV_IMPORT",
    "status": "PENDING_REVIEW",
    "summary": {
      "taskCount": 2,
      "userCount": 4,
      "errorCount": 0,
      "projectionErrorCount": 0,
      "mappingNoteCount": 1
    },
    "taskEntries": [
      {
        "index": 0,
        "projected": {
          "title": "Draft onboarding checklist",
          "type": "OTHER",
          "status": "IN_PROGRESS",
          "priority": "HIGH",
          "creatorId": 501,
          "ownerId": 502,
          "requestedById": 503,
          "projectTitle": "Engineering Tasks",
          "source": "notion",
          "scheduleStage": "PENDING"
        },
        "projectionErrors": [],
        "mappingNotes": [
          "Notion parent relation is preserved in description_json but is not wired as a TeamBoost dependency in the CSV import."
        ]
      }
    ]
  }
}

Projection Field Coverage#

Notion source TeamBoost draft field Notes
Name / Title title Error if shorter than 2 characters
Type / Category / Kind type Common task types map directly; unknowns default to OTHER with a mapping note
Description description
Status status Common to-do names map to NOT_STARTED; in-progress names map to IN_PROGRESS; Blocked maps to BLOCKED; done names map to COMPLETED; canceled names map to CANCELED; unknown names are left unset
Priority priority urgent/critical/high/medium/low map to TeamBoost priority values; missing priority becomes UNKNOWN
Creator id/e-mail, when present creatorId Resolved through the user mapping. If the creator is missing or unmapped, creatorId is left unset with a mapping note; no fallback id is invented
First assignee id/e-mail ownerId Present-but-unmapped assignee is a blocking projectionError
Requester id/e-mail requestedById Optional; unmapped requester is a mapping note
Labels / Tags labels Pass-through; TeamBoost creates/maps labels server-side
Data Source / Project / Database projectTitle
Due date plannedEndDate
Stable id/URL, parent/dependency relations, raw-only columns descriptionJson Context only; parent/dependency relations are not wired as TeamBoost dependencies in this CSV unit

Not Built Yet#

  • Notion API sync. The generic sync endpoint does not yet accept the source-selection and property-map contract Notion needs (data_source_id plus task property mapping).
  • Notion credential verification and API client.
  • Standalone Notion user-directory import.
  • OAuth app install flow.
  • Webhook registration and X-Notion-Signature verification.