Skip to main content
POST
/
api
/
roleplay
Create Roleplay
curl --request POST \
  --url https://app.replay.sale/api/roleplay \
  --header 'Content-Type: application/json' \
  --header 'x-api-key: <api-key>' \
  --data @- <<EOF
{
  "title": "Cold Call Discovery Practice",
  "customerPersona": {
    "id": "550e8400-e29b-41d4-a716-446655440000"
  },
  "scorecard": {
    "id": "550e8400-e29b-41d4-a716-446655440002"
  },
  "passingScore": 70,
  "language": "en",
  "isBlind": false,
  "conversationStarters": [
    "Hi, I'm calling about your recent inquiry...",
    "Hello! I'd like to discuss how we can help..."
  ],
  "roleplayType": "Train",
  "shouldActAsCustomer": true,
  "instructions": "You are a busy VP of Sales who is skeptical of new tools but open to hearing a quick pitch.",
  "objective": "Successfully qualify the prospect and book a follow-up demo",
  "tags": [
    "sales",
    "discovery",
    "cold-call"
  ],
  "keyterms": [
    "ROI",
    "integration",
    "onboarding"
  ],
  "timerInSeconds": 300,
  "interviewMaxAttempts": 3,
  "coachShowSolutionBeforeFirstRoleplay": true,
  "coachShowSolutionBeforeSubsequentRoleplays": true,
  "coachShowScorecardBeforeFirstRoleplay": true,
  "coachShowScorecardBeforeSubsequentRoleplays": true,
  "coachShowCustomerBeforeFirstRoleplay": true,
  "coachShowCustomerBeforeSubsequentRoleplays": true,
  "variables": [
    {
      "variableId": "550e8400-e29b-41d4-a716-446655440003",
      "variantId": "550e8400-e29b-41d4-a716-446655440004"
    }
  ]
}
EOF
{
  "success": true,
  "data": {
    "roleplayId": "550e8400-e29b-41d4-a716-446655440010",
    "customerPersonaId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "scorecardId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "variables": [
      {
        "variableId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
        "variantId": "3c90c3cc-0d44-4b50-8888-8dd25736052a"
      }
    ]
  }
}

Authorizations

​
x-api-key
string
header
required

API key for authentication. Get your API key from your company settings.

Body

application/json
​
title
string
required

Title of the roleplay

Minimum string length: 1
Example:

"Cold Call Discovery Practice"

​
customerPersona
object
required

Customer persona configuration. Pass { id } to reference an existing persona, or { name, ttsProvider, defaultVoiceId } to create a new one.

​
scorecard
object
required

Scorecard configuration. Pass { id } to reference an existing scorecard, or { title, sections } to create a new one. Weights are auto-calculated.

​
passingScore
integer
default:70

Minimum score to pass (0-100). Defaults to 70.

Required range: 0 <= x <= 100
Example:

70

​
language
enum<string>
default:en

Language code for the roleplay. Options: en, es, fr-CA, pt-BR, cs. Defaults to 'en'.

Available options:
en,
es,
fr-CA,
pt-BR,
cs
Example:

"en"

​
isBlind
boolean
default:false

If true, the user does not see AI feedback during the session. Defaults to false.

Example:

false

​
conversationStarters
string[]

Opening conversation prompts shown to the user. Defaults to empty.

Example:
[
  "Hi, I'm calling about your recent inquiry...",
  "Hello! I'd like to discuss how we can help..."
]
​
roleplayType
enum<string>
default:Train

Type of roleplay. 'Train' for practice, 'Interview' for assessment. Defaults to 'Train'.

Available options:
Train,
Interview
Example:

"Train"

​
shouldActAsCustomer
boolean
default:true

If true, AI acts as the customer. If false, AI acts as the rep. Defaults to true.

Example:

true

​
instructions
string

Instructions for the AI persona during the conversation

Example:

"You are a busy VP of Sales who is skeptical of new tools but open to hearing a quick pitch."

​
objective
string

Objective description shown to the user

Example:

"Successfully qualify the prospect and book a follow-up demo"

​
tags
string[]

Tags for categorization

Example:
["sales", "discovery", "cold-call"]
​
keyterms
string[]

Key terms relevant to the roleplay

Example:
["ROI", "integration", "onboarding"]
​
timerInSeconds
integer

Time limit for the roleplay session in seconds

Required range: x > 0
Example:

300

​
interviewMaxAttempts
integer

Maximum number of attempts for Interview-type roleplays

Required range: x > 0
Example:

3

​
coachShowSolutionBeforeFirstRoleplay
boolean
default:true

Show solution info before the first attempt. Defaults to true.

​
coachShowSolutionBeforeSubsequentRoleplays
boolean
default:true

Show solution info before retry attempts. Defaults to true.

​
coachShowScorecardBeforeFirstRoleplay
boolean
default:true

Show scorecard before the first attempt. Defaults to true.

​
coachShowScorecardBeforeSubsequentRoleplays
boolean
default:true

Show scorecard before retry attempts. Defaults to true.

​
coachShowCustomerBeforeFirstRoleplay
boolean
default:true

Show customer persona before the first attempt. Defaults to true.

​
coachShowCustomerBeforeSubsequentRoleplays
boolean
default:true

Show customer persona before retry attempts. Defaults to true.

​
variables
object[]

Variables to attach to the roleplay. Each can reference existing variable/variant by IDs, or define new ones inline.

Response

Roleplay created successfully. Returns the IDs of all created/referenced entities.

​
success
enum<boolean>
required

Indicates the roleplay was created successfully

Available options:
true
​
data
object
required