Airtable#

Airtable is registered for CSV import. It parses a documented Airtable TeamBoost task-view grid 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 an Airtable TeamBoost task-view CSV export	Built
`SYNC`	Pull tasks from the Airtable API	Not built
`USER_IMPORT`	Standalone Airtable user-directory import	Not built
`WEBHOOK`	Signed Airtable event handling	Not built

The endpoints below live under /api/v1/providers/airtable/.... 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/airtable/imports/csv?organization_id=<id>

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

The first Airtable CSV capability supports a TeamBoost task-view contract, not arbitrary Airtable tables. Export the Airtable grid view selected for TeamBoost import and include these required columns:

Required field	Accepted column names
Stable Airtable record id	`Airtable Record ID`
Title	`Title`, `Task`, `Task Name`, `Name`
Status	`Status`
Created timestamp	`Created Time`, `Created`, `Created At`, `Created Date`
Updated timestamp	`Last Modified Time`, `Updated`, `Updated Time`, `Updated At`

Optional fields the parser understands include Task ID, Identifier, Type, Priority, Description, Notes, Assignee, Assignee Airtable User ID, Assignee Email, Creator, Creator Airtable User ID, Creator Email, Due Date, Start Date, Labels, Tags, Project, Base, Task Group, and Parent Record ID. 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": "airtable",
    "capability": "CSV_IMPORT",
    "status": "PENDING_REVIEW",
    "summary": {
      "taskCount": 2,
      "userCount": 4,
      "errorCount": 0,
      "projectionErrorCount": 0,
      "mappingNoteCount": 2
    },
    "taskEntries": [
      {
        "index": 0,
        "projected": {
          "title": "Prepare Airtable import",
          "type": "NEW_FEATURE",
          "description": "Map a TeamBoost task-view export.",
          "status": "IN_PROGRESS",
          "priority": "HIGH",
          "creatorId": 9,
          "ownerId": 7,
          "labels": ["integration", "airtable"],
          "projectTitle": "Integrations",
          "taskGroupTitle": "Airtable",
          "source": "airtable",
          "scheduleStage": "PENDING"
        },
        "projectionErrors": [],
        "mappingNotes": [
          "Airtable row has 2 assignees/owners; only the first is mapped to owner_id and all raw assignee values are preserved in description_json.",
          "Airtable parent record is preserved in description_json but is not wired as a TeamBoost dependency in the CSV import."
        ]
      }
    ]
  }
}

Projection Field Coverage#

Airtable source	TeamBoost draft field	Notes
`Title` / `Task` / `Task Name` / `Name`	`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` / `Notes` / `Summary` / `Details`	`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`
Additional assignees	`descriptionJson`	The first assignee is mapped to `ownerId`; all raw assignee values are preserved
`Labels` / `Tags`	`labels`	Pass-through; TeamBoost creates/maps labels server-side
`Project` / `Base`	`projectTitle`
`Task Group`	`taskGroupTitle`
`Due Date` / `Due`	`plannedEndDate`
Stable record id, source URL, parent/dependency records, raw-only columns	`descriptionJson`	Context only; parent/dependency relations are not wired as TeamBoost dependencies in this CSV unit

Not Built Yet#

Airtable API sync. The generic sync endpoint does not yet accept Airtable base/table/view selection or field mapping.
Airtable credential verification and API client.
Standalone Airtable user-directory import.
OAuth app install flow.
Webhook registration and X-Airtable-Content-MAC verification.