Input Data

Input data tables, lists, groups, and variant generation for crowd task customization.

Input data allows you to structure the information presented to crowd workers in a reusable, parameterised way. Rather than creating one crowd task per content item by hand, you define input data tables containing lists of values and let Crowdee generate task variants automatically. This is particularly useful for review campaigns that span many content items, where you want to ensure systematic coverage across a defined set of criteria without manually constructing each task.

Data Hierarchy

Input data is organised in three tiers. Each tier adds a layer of structure that enables progressively more sophisticated variant generation.

Input data table — The top-level container. An input data table has a name, an optional description, and a scope ("project" or "organization"). It groups together all the lists and groups that belong to a single review campaign or data collection effort. An input data table scoped to an organisation can be shared across projects; a project-scoped input data table is only accessible within that project.

List — An ordered sequence of records within an input data table. Each list item is a JSON object whose fields represent the values you want available in a task variant — for example, a list of article snippets might have fields headline, url, and publication_date. An input data table can contain multiple lists representing different categories of input (such as a list of articles and a separate list of review criteria).

Group — A cross-list combination that defines which lists should be paired together to produce variants. A group uses a Cartesian product to combine its member lists: for example, a group containing a list of 10 articles and a list of 4 review criteria produces 40 task variants — one per (article, criterion) pair. Groups are how you express "for each item in list A, apply every item from list B."

Creating an Input Data Table

Input data tables are created at the project level. The scope field controls whether the input data table is available only within the project or across the entire organisation.

curl -X POST https://api.crowdee.ai/v2/projects/{projectId}/input-data \
  -H "X-API-Key: crw_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "News Article Review Campaign — Q3 2025",
    "description": "Articles selected for systematic manipulation analysis across three categories",
    "scope": "project"
  }'

The response includes the input data table id, which you will need to create lists and groups within it.

Adding Lists and Groups

Once an input data table exists, add lists to it by posting records to the list endpoint. Each record is a JSON object; all records in a list should share the same field names, though the schema is flexible.

curl -X POST https://api.crowdee.ai/v2/input-data/{dataSetId}/lists \
  -H "X-API-Key: crw_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Articles",
    "records": [
      { "headline": "Central bank raises rates", "url": "https://example.com/article-1" },
      { "headline": "Election results disputed", "url": "https://example.com/article-2" }
    ]
  }'

After creating the lists you want to combine, define a group that references them:

curl -X POST https://api.crowdee.ai/v2/input-data/{dataSetId}/groups \
  -H "X-API-Key: crw_YOUR_API_KEY" \
  -H "Content-Type: application/json" \
  -d '{
    "name": "Articles × Review Criteria",
    "listIds": ["{articlesListId}", "{criteriaListId}"]
  }'

Groups must reference at least two lists. The Cartesian product is computed at variant-generation time, not at group creation time, so you can add records to a list after the group is created and the new variants will be available immediately on the next variants request.

Variant Generation

Variants are computed on demand by the variants endpoint:

GET https://api.crowdee.ai/v2/input-data/{dataSetId}/variants
X-API-Key: crw_YOUR_API_KEY

The response is a paginated list of variant objects. Each variant contains the merged fields from all lists in the group, keyed by list name to avoid collisions. For the articles × criteria example above, each variant would look something like:

{
  "variantId": "v_abc123",
  "groupId": "grp_xyz",
  "fields": {
    "Articles": { "headline": "Central bank raises rates", "url": "https://example.com/article-1" },
    "Review Criteria": { "criterion": "Source credibility", "weight": "high" }
  }
}

Variants are computed on demand — updating a list's records automatically changes the variants available for future tasks. No rebuild or re-indexing step is required. This means you can progressively extend an input data table during an ongoing campaign and new crowd tasks will incorporate the latest records.

CSV Import

For large input data tables, Crowdee supports CSV import to populate a list in a single request. The CSV file's first row must be the header row; column names become the field names of each record.

curl -X POST https://api.crowdee.ai/v2/projects/{projectId}/input-data/from-csv \
  -H "X-API-Key: crw_YOUR_API_KEY" \
  -F "name=Batch Article Import" \
  -F "scope=project" \
  -F "file=@articles.csv"

The import endpoint creates a new input data table and a single list within it from the CSV contents. If you need multiple lists within the same input data table, create the input data table first via the standard endpoint and then import each list separately using POST /v2/input-data/{dataSetId}/lists/from-csv.

Imported records are validated for UTF-8 encoding. Files larger than 10 MB should be split into chunks; Crowdee does not currently support streaming imports for very large files. Contact support@crowdee.ai if you need to import input data tables with more than 100,000 records.

Data Hierarchy

Creating an Input Data Table

Adding Lists and Groups

Variant Generation

CSV Import

On this page