Create a collection module

Spin up a new collection module on Root and pull it to your machine, ready to develop.

Prerequisites

Before you start, make sure you have:

A Root API key with workbench access for collection modules. Generate one in the Root dashboard under Settings → API keys, or ask your Root administrator.
Your organisation ID (UUID), if you create the module with the API. Find it in the Root dashboard URL or under Settings → Organisation.
The Root API host for your tenant, if you create the module with the API: api.rootplatform.com (South Africa multi-tenant) or api.uk.rootplatform.com (UK multi-tenant).
The rp CLI installed — see Install the Workbench CLI.

Step 1: Create the collection module in the dashboard

Create the collection module from the Root dashboard. Use the v2 starter template when you create the module, and make a note of the collection module key — you'll use it in step 2.

Optional: Create the module with the API

If you prefer to script module creation, create the collection module with the Root API and clone the v2 starter template:

curl -X POST -u '<api-key>:' \
  -H 'Content-Type: application/json' \
  -d '{
    "key": "cm_stripe",
    "name": "Stripe collections",
    "key_of_collection_module_to_clone": "blank_starter_template_v2"
  }' \
  'https://api.rootplatform.com/v1/apps/<org-id>/insurance/collection-modules'

The -u '<api-key>:' form sends Basic auth with your API key as the username and no password — Root's standard API auth scheme.

A successful call returns 200 with the new collection module payload, including the key you provided.

Naming rules for the collection module key

The key field uniquely identifies your module across Root and is permanent. It must:

Start with a lowercase letter
Contain only lowercase letters, digits, and underscores
Be unique within your organisation

Conventional shape: cm_<provider>_<purpose> — for example, cm_stripe_main or cm_paystack_recurring.

Step 2: Pull the module to your machine

Clone the newly-created module to your local machine:

rp clone -cm <api-key> cm_stripe

This creates a cm_stripe/ directory with the full v2 layout — code, tests, AI assistant context, scaffolding scripts, and in-repo docs. It also writes a .root-auth file containing your API key so subsequent rp commands work without re-supplying credentials.

See File and folder structure for what each file is for.

Available starter templates

List every template available to your organisation:

curl -u '<api-key>:' \
  'https://api.rootplatform.com/v1/apps/<org-id>/insurance/template-collection-modules'

Common templates:

Template key	Description
`blank_starter_template_v2`	Recommended. Provider-agnostic v2 wrapper with AI assistant context, scaffolding scripts, and the layered architecture documented in `docs/`.
`blank_starter_template`	Legacy. Minimal layout without the v2 wrapper. Kept for backward compatibility.

Pick the v2 template unless you have a specific reason to start from the legacy layout.

Common API errors

Status	Likely cause	Fix
400	`key` doesn't match the token pattern	Use lowercase letters, digits, and underscores; start with a letter.
401	API key is invalid or expired	Regenerate the API key in the Root dashboard.
403	API key lacks workbench-create permissions	Ask your Root administrator to grant collection-module workbench permissions.
404	`key_of_collection_module_to_clone` not found	List available templates and use one of those keys.
409	A collection module with this `key` already exists	Pick a different key, or delete the existing module first.

What's next

File and folder structure — what each file in the v2 layout is for.
Workbench CLI commands — rp push, rp pull, rp publish, and rp logs.
Linking a collection module to a product module — wire your new collection module into a product.
Collection module environments — sandbox vs live behaviour.