Using the platform API, you can import large quantities of items into a monday.com board through an asynchronous, three-step workflow:

1. Start an import job (ingest_items or backfill_items) and receive a pre-signed upload_url and job_id
2. Upload the CSV file to the upload_url
3. Poll job status with fetch_job_status

The API exposes two ways to start an import. ingest_items is the default for almost every use case. backfill_items is intended for a one-time, account-admin-only initial load - for example, seeding a board before it goes into day-to-day use.

Choose how to import

Supported column types

Both endpoints support the following column types:

• Board Relation
• Checkbox
• Date
• Dropdown
• Email
• Link
• Location
• Long Text
• Number
• People
• Phone
• Status
• Text
• Timeline

Rows that include unsupported column types may fail validation. See Column type validation for the per-type CSV format.

Limitations

Notes

• File size is enforced after upload by the import service (not by the upload URL itself). Oversized files are rejected with failure_reason: FILE_TOO_LARGE.
• Cancellation of a running job is not supported.
• Hierarchy import item caps apply in addition to the maximum rows per file.
• The per-parent subitem limit varies by plan and matches the limit that applies in the UI. An item whose subitems exceed it is rejected along with its subitem rows.

Getting started

Pre-requisites

• API authentication token
• CSV file with valid headers and values (see CSV format)
• Requests must include the API-Version: 2026-07 header

Step 1: Start the import job

1. Retrieve the board_id and group_id where newly created items should be inserted by querying boards and groups.
2. Call ingest_items unless you specifically need a one-time admin-only initial load via backfill_items.
3. Save the returned job_id and upload_url. The upload_url is only valid for 10 minutes.

Ingest example (default path)

mutation {
  ingest_items(
    board_id: "1234567890"
    group_id: "topics"
    on_match: { behaviour: UPSERT, match_column_id: "email" }
  ) {
    job_id
    upload_url
  }
}

When on_match is provided, matching is evaluated across the whole board. group_id only controls where newly created rows are inserted; it does not scope matching or move matched items.

Backfill example (one-time initial load only)

mutation {
  backfill_items(board_id: "1234567890", group_id: "topics") {
    job_id
    upload_url
  }
}

Step 2: Upload the CSV file

Upload your CSV to the upload_url returned in Step 1.

PUT <upload_url>
Content-Type: text/csv

<CSV file content>

A successful upload returns HTTP 200 with an ETag header.

HTTP/1.1 200 OK
ETag: "abc123def456"

Do not include x-amz-checksum-crc32 as a request header when uploading to the pre-signed URL. The URL may include checksum query parameters, but forwarding the checksum as an unsigned request header can cause S3 to reject the upload with HTTP 403.

Step 3: Monitor the import status

Poll fetch_job_status every ~10 seconds until the job reaches a terminal state (COMPLETED, FAILED, or REJECTED).

query {
  fetch_job_status(job_id: "7c9e6679-7425-40de-944b-e07fc1f90ae7") {
    ... on ItemsJobStatus {
      status
      counts {
        submitted
        invalid
        skipped
        created
        updated
        failed
      }
      progress_percentage
      failure_reason
      failure_message
      fully_imported
      report_created
      report_url
    }
  }
}

When report_created is true, download report_url promptly. The report URL expires after 10 minutes.

Reference

CSV format

• UTF-8 encoding is required.
• Use comma (,) as the column separator.
• Wrap values that contain commas, double quotes, or newlines in double quotes. Escape an embedded double quote by doubling it ("").

Headers

For regular item imports:

• The first header value must be name.
• The remaining header values must be exact board column_id values (case-sensitive).
• Query columns to retrieve the correct column IDs for the target board.

CSV headers must use the exact column IDs returned by the board's columns query, not display titles. Column IDs are board-specific, so don't infer them from the column type or title.

For imports that include subitems, see Classic subitems boards. Subitem headers use a .subitem suffix.

For multi-level subitems boards, see Multi-level subitems boards. MLS hierarchy imports use name.l1, name.l2, and deeper level headers up to name.l5 to represent the hierarchy.

Rows

• In regular item imports, the first value in each row is the item name.
• The remaining values map to the column IDs in the header.
• Empty values are allowed. Whitespace-only values are treated as empty.
• In UPSERT mode (ingest_items only), an empty cell on a matched row is ignored - the existing column value is preserved.
• In UPSERT mode, a cell containing exactly the string <NULL> clears the column value on the matched item.

Example

name,text,status,date,email,numeric,dropdown
Task 1,Description text,Working on it,2025-12-31,[email protected],100,"Option A, Option B"
Task 2,Another task,Done,2026-01-15,[email protected],200,Option C
Task 3,Third task,Stuck,2026-02-28,[email protected],300,
Task 4,,,,,,

Classic subitems boards

Bulk item import supports creating items together with their subitems. A .subitem suffix marks which headers and which rows belong to subitems. For boards that use multi-level subitems, see Multi-level subitems boards instead.

Use these headers:

• name - item name. Required, and only one name header is allowed.
• <column_id> - a column on the item.
• name.subitem - subitem name. Include it only when the file contains subitem rows.
• <column_id>.subitem - a column on the subitem. Requires a name.subitem header to be present.

name,status,name.subitem,text.subitem
Parent A,Done,,
,,Sub 1,First subitem of Parent A
,,Sub 2,Second subitem of Parent A
Parent B,Working on it,,
,,Sub 3,First subitem of Parent B

Rules for classic subitems imports:

• Each row represents one item. An item row fills name and leaves the subitem columns empty. A subitem row leaves name empty and fills name.subitem. A row that fills both is rejected, and a row that fills neither is skipped.
• Parent-child relationships are inferred from row order. A subitem row attaches to the closest item row above it. A subitem row that appears before any item row is rejected.
• Classic subitems support exactly one level of nesting. Level headers such as name.l1 and name.l2 are not accepted, and the whole file is rejected if they are present.
• .subitem headers must use subitem column IDs. Query columns on the subitems board to retrieve them.
• A value placed on the wrong kind of row is ignored. A .subitem value on an item row, or an unsuffixed column value on a subitem row, is not written.
• group_id controls where new items are inserted. It does not apply to subitems.
• Classic subitems imports are create-only. Do not use on_match, UPSERT, or SKIP for a file that contains .subitem headers.
• If an item row is rejected or fails, its subitem rows are not created, and the report points back to the item row that caused it.
• Headers are matched case-insensitively, including the .subitem suffix.
• A file with no name.subitem header is treated as a regular item import.
• The board must already have a subitems column.
• In the job report, subitem columns keep their .subitem suffix.

Multi-level subitems boards

Bulk item import supports creating items on boards that use multi-level subitems. On these boards, the CSV represents hierarchy with level columns instead of a single item-name column.

Use name.l1 for top-level items, name.l2 for their children, name.l3 for grandchildren, continuing up to name.l5. MLS boards currently support a maximum of 5 hierarchy levels. The header name is also accepted as the top-level item column, but name.l1 is recommended for clarity in MLS files.

name.l1,name.l2,name.l3,status,text
Project A,,,,Top-level item
,Phase 1,,,Child item
,,Task 1,Stuck,Grandchild item
,,Task 2,Working on it,Another grandchild
,Phase 2,,Done,Another child
Project B,,,Working on it,Second top-level item

Rules for MLS hierarchy imports:

• Each row represents one item. Put that item's name in the column for its hierarchy level, and leave the other level columns empty.
• Parent-child relationships are inferred from row order. A row's parent is the most recent earlier row at the previous level.
• Regular column values can be included in the same row using the board's column IDs.
• MLS hierarchy imports are create-only. Do not use on_match, UPSERT, or SKIP for MLS hierarchy imports.
• For rows that create parent items, do not provide values for rollup-enabled columns. Parent values are calculated from child items, and rows that provide parent rollup values may be rejected.

Column type validation

Best practices

1. Prefer ingest_items for integrations and any import that should behave like normal board activity.
2. Use backfill_items only for a planned, one-time initial load.
3. Poll job status about every 10 seconds - not faster.
4. Validate the CSV header against the board schema before uploading.
5. Handle GraphQL errors from the API separately from HTTP errors from the file upload step.
6. Download the report as soon as report_created is true.
7. On RATE_LIMIT_EXCEEDED, wait using extensions.retryAfterMs instead of retrying immediately.
8. For ingest, spread large volumes across the hour where possible to reduce ACCOUNT_CAPACITY_EXCEEDED rejections.
9. For MLS hierarchy imports, order rows top-to-bottom so each child appears after its parent.
10. For classic subitems imports, order rows so each subitem follows the item it belongs to.

Troubleshooting

Related reference pages

• Ingest items API reference (default)
• Backfill items API reference
• Bulk import other types