---
title: "Copy a template as a new variant"
method: POST
path: "/api/experiments/{experimentId}/variants"
tags: ["experiments"]
---

# Copy a template as a new variant

`POST /api/experiments/{experimentId}/variants`

## Request

- Base URL: `https://api.iterable.com`
- URL: `https://api.iterable.com/api/experiments/{experimentId}/variants`
- Auth: API key in header `Api-Key`

Copies the template you specify into a new variant on a campaign experiment that's in <code>draft</code> or <code>ready</code> status. Each successful request adds another variant, so retrying a successful request creates a duplicate. This endpoint works only with experiments that test message content: the subject line, preheader text, from name and sender, email body, or all content. It doesn't work with send time or Send Time Decisioning experiments. This endpoint doesn't support journey experiments.

## Path parameters

- `experimentId` integer, required

## Request body

- CopyExperimentVariantRequest: Request body for copying a template as a new experiment variant
  - `copyFromTemplateId` integer, required: ID of the template to copy. Iterable creates a new variant from this template.
  - `name` string: Optional display name for the new variant.

## Response `201`

Variant created

- ExperimentResponse: Full experiment details
  - `allocationMode` string, required: Traffic allocation mode
  - `channelType` 'email' | 'push' | 'sms' | 'in_app' | 'web_push', required: Channel type for the experiment.
  - `constraints` ExperimentConstraints: Experiment constraints/targeting
    - `suppressionListIds` integer[]: List IDs to suppress
    - `targetSegment` string: Target segment description
  - `creationDate` string, date-time: Date the experiment was created
  - `experimentType` string, required: Experiment type
  - `finishDate` string, date-time: End date of the experiment
  - `id` integer, required: Experiment ID
  - `meta` ExperimentMeta, required: Experiment metadata
    - `campaignId` integer: Campaign ID
    - `conversionMetrics` string[], required: Conversion metrics being tracked
    - `customConversionId` integer: ID of the custom conversion event the experiment measures. <code>null</code> if the experiment measures a system event, such as <code>opens</code> or <code>clicks</code>.
    - `name` string, required: Experiment name
    - `orgId` integer, required: Organization ID
    - `projectId` integer, required: Project ID
  - `sizing` ExperimentSizingResponse, required: Experiment traffic allocation
    - `attributionPeriodHours` integer: Attribution window in hours for the holdout group. <code>null</code> if the experiment has no holdout group configured.
    - `holdoutPercentage` number, double: Percentage of total audience reserved as a holdout group that does not receive any experiment traffic. <code>null</code> if the experiment has no holdout group configured.
    - `perVariantPercentage` number, double: Percentage of total audience distributed evenly to each variant for experiments with a blast campaign that include all users. <code>null</code> for other experiment types.
    - `sendsPerVariant` integer: Minimum number of sends each variant must receive before the test phase ends and a winner can be selected. Defaults to 1000. Applies only to triggered campaign experiments.
    - `testDurationMinutes` integer: How long the test phase runs before Iterable selects a winner, in minutes. Defaults to 120 minutes. Applies only to experiments with blast campaigns that are not based on a specified send time.
    - `testGroupPercentage` number, double: Percentage of total audience used as the test group, split evenly among variants (defaults to 20%). During the test phase, Iterable sends to this group to determine which variant performs best.
    - `winnerGroupPercentage` number, double: Percentage of total audience (minus the holdout group) that receives the winning variant after the test phase completes (the optimized group). Users who already received a non-winning variant during the test phase do not receive the winner again.
  - `startDate` string, date-time: Start date of the experiment
  - `status` 'draft' | 'ready' | 'running' | 'finished' | 'winner_found', required: Experiment status
  - `variants` ExperimentVariantSummary[], required: Experiment variants
    - `currentPercentage` number, double, required: Percentage of total audience distributed to this variant, allocated based on the type of experiment you're running.
    - `id` integer, required: Variant ID
    - `isControl` boolean, required: Whether this variant is the control variant
    - `isWinner` boolean, required: Whether this variant is the winner
    - `name` string, required: Variant name
    - `value` ExperimentVariantValue, required: Typed variant value payload. Only present fields are serialized.
      - `sendTime` string: When this variant sends, as an ISO 8601 timestamp. Included only for send time experiments.
      - `stoGroup` string: STO group identifier for STO variants
      - `templateId` integer: ID of the template this variant sends. Included only for experiments that test message content.

## Other responses

- `400`: Invalid parameters
- `401`: Invalid API key
- `404`: Experiment or campaign not found
- `409`: Experiment isn't in <code>draft</code> or <code>ready</code> status

## Changes

- **2026-09-30** `cca837e62715`: 1 info
  - endpoint added

[Operation history](https://skmtc.dev/iterable/apis/iterable-api/changes/api/experiments/:experimentId/variants/post.md)

---

[API](https://skmtc.dev/iterable/apis/iterable-api.md) - [All operations](https://skmtc.dev/iterable/apis/iterable-api/llms.txt) - [OpenAPI document](https://skmtc.dev/iterable/apis/iterable-api/revisions/a430ac1d1db7?raw)