Trigger Calls | Gradii API Documentation

curl -X POST https://gradii.ai/api/v2/iris \
     -H "Authorization: Bearer <token>" \
     -H "Content-Type: application/json" \
     -d '{
  "candidateName": "John Doe",
  "phone": "1234567890",
  "campaignId": "campaign-uuid-789",
  "dynamicVariables": {
    "position": "Senior Developer",
    "company": "Tech Corp",
    "experience_years": 5,
    "salary_expected": 120000
  },
  "metadata": {
    "source": "manual_trigger",
    "priority": "high",
    "interview_round": 1,
    "score_threshold": 75.5
  }
}'

{
  "success": true,
  "processed": 1,
  "failed": 0,
  "total": 1,
  "calls": [
    {
      "callId": "call-uuid-123",
      "candidateName": "John Doe",
      "status": "registered",
      "retellCallId": "retell_abc123",
      "dbCallId": "db-call-uuid",
      "phone": "1234567890",
      "fromNumber": "+1234567890",
      "agentId": "agent-uuid-123",
      "agentName": "Sales Agent",
      "estimatedDuration": 300,
      "timestamp": "2024-01-28T10:00:00Z",
      "campaignId": "campaign-uuid-789"
    }
  ]
}

Trigger AI-powered phone calls for candidate screening. Supports both single and bulk operations.

Authentication

AuthorizationBearer

Bearer authentication of the form Bearer <token>, where token is your auth token.

Request

This endpoint expects an object.

candidateNamestringRequired

Candidate full name

phonestringRequired

Phone number

agentIdstringOptional

Iris agent ID to use for the call. Optional if campaignId is provided with IRIS-enabled interview setup.

campaignIdstringOptional

Job campaign ID. If provided without agentId, will use agent from campaign's IRIS interview setup.

dynamicVariablesmap from strings to anyOptional

Retell LLM dynamic variables for personalization. Accepts any data type (string, number, object, etc.)

metadatamap from strings to anyOptional

Custom metadata for the call. Accepts any data type.

Response

Call initiated successfully

successbooleanOptional

processedintegerOptional

failedintegerOptional

totalintegerOptional

callslist of objectsOptional

Errors

400

Bad Request Error