Smartsheet#

Smartsheet is registered for CSV import and API-token sync. Both paths expect a TeamBoost task-template-shaped Smartsheet grid: rows become reviewable import session entries, then each row is projected into the internal integrations task-create draft for operator review.

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

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

The first Smartsheet CSV capability supports a TeamBoost task-template-shaped grid export, not arbitrary Smartsheet column mapping. The CSV must include a title column.

Optional fields the parser understands include Row ID, Task ID, Type, Status, Priority, Description, Notes, Assignee, Assignee Email, Assignee ID, Creator, Creator Email, Creator ID, Due Date, Labels, Project, Task Group, Created Time, Last Modified Time, Attachments, and Attachment Summary. Any exported column is preserved in the lossless source record; unknown non-empty columns are also surfaced in descriptionJson as unmappedColumns.

Rows without a stable row id use an import-local identifier like smartsheet-row-1 and carry a non-blocking mapping note. Malformed rows are returned in rowErrors rather than failing the whole import. A file that does not carry a title column fails with invalid_csv_format.

API Sync#

PUT /api/v1/providers/smartsheet/credentials?organization_id=<id>
POST /api/v1/providers/smartsheet/credentials/verify?organization_id=<id>
POST /api/v1/providers/smartsheet/imports/sync?organization_id=<id>

The stored secret is encrypted at rest and must be a JSON object:

{
  "token": "smartsheet-access-token",
  "sheet_id": "4567890123456788",
  "base_url": "https://api.smartsheet.com/2.0"
}

base_url must be one of the supported Smartsheet API region hosts ending in /2.0: https://api.smartsheet.com/2.0, https://api.smartsheet.eu/2.0, or https://api.smartsheet.au/2.0. Tokens are sent as Authorization: Bearer <token>. Verification makes a cheap read-only sheet probe; rejected tokens, missing permissions, or an inaccessible sheet return invalid_api_key.

curl -X PUT "https://<host>/api/v1/providers/smartsheet/credentials?organization_id=590789" \
  -H "Authorization: Bearer <user-token>" \
  -H "Content-Type: application/json" \
  -d '{"secret":"{\"token\":\"smartsheet-access-token\",\"sheet_id\":\"4567890123456788\",\"base_url\":\"https://api.smartsheet.com/2.0\"}"}'

curl -X POST "https://<host>/api/v1/providers/smartsheet/imports/sync?organization_id=590789" \
  -H "Authorization: Bearer <user-token>"

API sync fetches the configured sheet with object values and row permalinks. The same column aliases as CSV import are used. Contact cells are converted into imported users for the proposed TeamBoost mapping; this is why Smartsheet declares USER_IMPORT, but there is no standalone user-directory endpoint.

The Import Session#

{
  "status": "success",
  "message": "CSV parsed; review the proposed user mapping.",
  "data": {
    "provider": "smartsheet",
    "capability": "CSV_IMPORT",
    "status": "PROJECTION_ERRORS",
    "summary": {
      "taskCount": 2,
      "userCount": 4,
      "errorCount": 0,
      "projectionErrorCount": 1,
      "mappingNoteCount": 2
    },
    "taskEntries": [
      {
        "index": 0,
        "projected": {
          "title": "Draft launch checklist",
          "type": "OTHER",
          "status": "IN_PROGRESS",
          "priority": "HIGH",
          "projectTitle": "Platform",
          "taskGroupTitle": "Launch",
          "source": "smartsheet",
          "scheduleStage": "PENDING"
        },
        "projectionErrors": [
          "Assignee 'aziz@example.com' is not mapped to a TeamBoost member; resolve the user mapping before confirming."
        ],
        "mappingNotes": [
          "Smartsheet attachment columns are preserved in description_json but are not uploaded into TeamBoost by CSV import."
        ]
      }
    ]
  }
}

Projection Field Coverage#

Not Built Yet#

• Arbitrary Smartsheet column mapping.
• Standalone Smartsheet user-directory import.
• OAuth app install flow.
• Webhook registration, callback challenge handling, and callback authenticity verification.