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",
  "customerPersonaId": "550e8400-e29b-41d4-a716-446655440000",
  "scorecardId": "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..."
  ],
  "shouldActAsCustomer": true,
  "instructions": "You are a busy VP of Sales who is skeptical of new tools but open to hearing a quick pitch.",
  "coverImageUrl": "companies/company-id/images/premade-roleplay/cover.png",
  "objective": "Successfully qualify the prospect and book a follow-up demo",
  "keyterms": [
    "ROI",
    "integration",
    "onboarding"
  ],
  "timerInSeconds": 300,
  "requireVideoRecording": false,
  "showResults": true,
  "maxAttempts": 3,
  "coachShowSolutionBeforeFirstRoleplay": true,
  "coachShowSolutionBeforeSubsequentRoleplays": true,
  "coachShowScorecardBeforeFirstRoleplay": true,
  "coachShowScorecardBeforeSubsequentRoleplays": true,
  "coachShowCustomerBeforeFirstRoleplay": true,
  "coachShowCustomerBeforeSubsequentRoleplays": true,
  "isLive": true,
  "customAttributes": {
    "scorecard_id": "sc_789",
    "fs_category": "customer_service",
    "difficulty": "intermediate"
  },
  "variables": [
    {
      "variableId": "550e8400-e29b-41d4-a716-446655440003",
      "variantId": "550e8400-e29b-41d4-a716-446655440004"
    }
  ]
}
EOF
{
  "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"
      }
    ]
  }
}

Documentation Index

Fetch the complete documentation index at: https://docs.replay.sale/llms.txt

Use this file to discover all available pages before exploring further.

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"

​
customerPersonaId
string<uuid>
required

UUID of an existing customer persona

Example:

"550e8400-e29b-41d4-a716-446655440000"

​
scorecardId
string<uuid>
required

UUID of an existing scorecard

Example:

"550e8400-e29b-41d4-a716-446655440002"

​
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..."
]
​
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."

​
coverImageUrl
string

GCS path for the roleplay cover image

Example:

"companies/company-id/images/premade-roleplay/cover.png"

​
objective
string

Objective description shown to the user

Example:

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

​
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

​
requireVideoRecording
boolean
default:false

If true, camera access is required and video will be recorded. Defaults to false.

Example:

false

​
showResults
boolean
default:true

If true, shows analysis results after roleplay completion. If false, shows a simple completion message. Defaults to true.

Example:

true

​
maxAttempts
integer

Maximum number of attempts allowed for this roleplay. When set, users cannot exceed this limit.

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.

​
isLive
boolean
default:true

Whether the roleplay is live and accessible to users (true) or in draft mode (false). Defaults to true.

Example:

true

​
customAttributes
object

Custom key-value pairs for external integrations (LMS systems, analytics, etc.)

Example:
{
  "scorecard_id": "sc_789",
  "fs_category": "customer_service",
  "difficulty": "intermediate"
}
​
variables
object[]

Optional variable-variant pairs to attach to the roleplay

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