​
Generate Evaluators API

Generate new evaluators automatically with specified configurations.

​
API Endpoint

MethodEndpoint
POSThttps://new-prod.vocera.ai/test_framework/v1/scenarios-external/generate/

​
Authentication

Include your API key in the request headers:

HeaderDescription
X-VOCERA-API-KEYYour API key obtained from the dashboard

​
Request Parameters

ParameterTypeRequiredDescription
agent_idintegerYes*ID of the agent to generate evaluators for
assistant_idstringYes*The assistant ID associated with agent to generate evaluators for
num_scenariosintegerYesNumber of evaluators to generate
extra_instructionsstringNoAdditional instructions for scenario generation
information_fieldsobjectNoKey-value pairs of information to include in scenarios
personalitiesarrayNoArray of personality IDs to use
first_messagestringNoInitial message for the conversation
inbound_phone_numberintegerNoID of the inbound phone number (See inbound numbers)

* Only either of agent_id or assistant_id is required

​
Example Request Body

{

    "agent_id": 123,

    "num_scenarios": 2,

    "extra_instructions": "About order complaints",

    "information_fields": {

        "customer_name": "John Smith",

        "order_number": "ORD-12345",

        "product_type": "Premium Package"

    },

    "personalities": [1, 4, 7],

    "first_message": "Hi, I'm calling about my recent order",

    "inbound_phone_number": 42

}

​
Response Format

The API returns an array of generated evaluator objects.

​
Response Fields

FieldTypeDescription
idintegerUnique identifier for the evaluator
namestringName of the evaluator
agentintegerID of the associated agent
personalityintegerID of the personality used
personality_namestringName of the personality
tagsarrayList of tags associated with the evaluator
runsarrayList of evaluator run IDs
metricsarrayList of metric IDs
metric_namesarrayList of human-readable metric names
first_messagestringInitial message for the conversation
inbound_phone_numberinteger|nullID of the inbound phone number
inbound_phone_number_dataobject|nullDetails about the inbound phone number (see below)
instructionsstringGenerated evaluator instructions

​
Inbound Phone Number Data Fields

FieldTypeDescription
idintegerInternal ID of the phone number record
numberstringThe phone number in E.164 format
phone_number_idstringExternal reference ID for the phone number

​
Example Response

[

    {

        "id": 60,

        "name": "Interruptive Purchase Verification Call",

        "agent": 123,

        "personality": 1,

        "personality_name": "Highly Interruptive American Man",

        "tags": ["verification", "high_priority", "english"],

        "runs": [],

        "metrics": [1, 3, 20, 21, 28, 31],

        "metric_names": [

            "Customer Satisfaction",

            "Response Accuracy",

            "Resolution Time",

            "Empathy Score",

            "Interruption Handling",

            "Information Clarity"

        ],

        "first_message": "Hi, I'm calling about my recent order",

        "inbound_phone_number": 42,

        "inbound_phone_number_data": {

            "id": 42,

            "number": "+1-555-0123",

            "phone_number_id": "PN-789"

        },

        "instructions": "Act as John Smith, an impatient customer calling about order ORD-12345. Frequently interrupt the agent while discussing the Premium Package. Express confusion about the verification process but eventually cooperate. Use a direct American communication style."

    },

    // addtional scenarios...

]

​
Code Examples

curl -X POST https://new-prod.vocera.ai/test_framework/v1/scenarios-external/generate/ \

  -H "X-VOCERA-API-KEY: <your-api-key-here>" \

  -H "Content-Type: application/json" \

  -d '{

    "agent_id": 123,

    "num_scenarios": 2,

    "extra_instructions": "Include scenarios with different customer personalities and languages",

    "information_fields": {

        "customer_name": "John Smith",

        "order_number": "ORD-12345",

        "product_type": "Premium Package"

    },

    "personalities": [1, 4, 7],

    "first_message": "Hi, I'm calling about my recent order"

  }'