API Documentation - RevRag.ai

Base URLs

Production: https://api.revrag.ai/v1
Sandbox: https://sandbox-api.revrag.ai/v1

Authentication

All API requests require an API key to be included in the request headers:

Authorization: Bearer YOUR_API_KEY

Campaign Management APIs

1. Create Campaign

POST /campaigns/create Creates a new user campaign with an associated AI agent.

Request Body

{
  "agent_id": "string",
  "campaign_name": "string",
  "description": "string",
  "metadata": {
    "campaign_type": "string",
    "target_audience": "string",
    "created_by": "string"
  }
}

Request Parameters

Parameter	Type	Required	Description
`agent_id`	string	Yes	ID of the AI agent to associate with this campaign
`campaign_name`	string	Yes	Unique name for the campaign
`description`	string	No	Description of the campaign purpose
`metadata`	object	No	Additional metadata for the campaign

Response

Success (201 Created)

{
  "success": true,
  "campaign_id": "campaign_abc123def456",
  "campaign_name": "Q4_Onboarding_Dropouts",
  "agent_id": "agent_abc123def456",
  "created_at": "2024-08-20T10:30:00Z",
  "status": "active",
  "user_count": 0
}

2. Attach Data to Campaign

POST /campaigns/{campaign_id}/data Attaches user data to an existing campaign via JSON or CSV upload.

Path Parameters

Parameter	Type	Required	Description
`campaign_id`	string	Yes	The campaign ID to attach data to

Request Body (JSON Mode)

{
  "mode": "prefer_original",
  "data_format": "json",
  "users": [
    {
      "user_id": "string",
      "phone_number": "string",
      "user_name": "string",
      "email": "string",
      "custom_fields": {
        "signup_date": "string",
        "plan_type": "string",
        "drop_off_stage": "string"
      }
    }
  ]
}

Request Body (CSV Mode)

{
  "mode": "prefer_new",
  "data_format": "csv",
  "csv_data": "base64_encoded_csv_content",
  "csv_headers": ["user_id", "phone_number", "user_name", "email", "signup_date"],
  "mapping": {
    "user_id": "user_id",
    "phone_number": "phone",
    "user_name": "name"
  }
}

Request Parameters

Parameter	Type	Required	Description
`mode`	string	Yes	Data merge mode: `prefer_original`, `prefer_new`, `prefer_none`
`data_format`	string	Yes	Format of input data: `json` or `csv`
`users`	array	Yes (JSON)	Array of user objects
`csv_data`	string	Yes (CSV)	Base64 encoded CSV content
`csv_headers`	array	Yes (CSV)	Column headers in the CSV
`mapping`	object	No	Field mapping for CSV columns

Mode Descriptions

prefer_original: Keep existing data, only add new fields
prefer_new: Overwrite existing data with new data
prefer_none: Skip users that already exist

Response

Success (200 OK)

{
  "success": true,
  "campaign_id": "campaign_abc123def456",
  "processed_users": 150,
  "new_users": 120,
  "updated_users": 25,
  "skipped_users": 5,
  "errors": [
    {
      "row": 45,
      "user_id": "user_invalid123",
      "error": "Invalid phone number format"
    }
  ],
  "total_users_in_campaign": 1275
}

3. Get Campaign

GET /campaigns/{campaign_id} Retrieves campaign information and user data with optional filtering.

Path Parameters

Parameter	Type	Required	Description
`campaign_id`	string	Yes	The campaign ID to retrieve

Query Parameters

Parameter	Type	Required	Description
`filters`	string	No	JSON-encoded filter criteria
`page`	integer	No	Page number for pagination (default: 1)
`limit`	integer	No	Number of users per page (default: 100, max: 1000)
`include_user_data`	boolean	No	Whether to include user data (default: true)

Filter Examples

?filters={"signup_date":{"gte":"2024-01-01"},"plan_type":"premium"}
?filters={"phone_number":{"exists":true},"drop_off_stage":"payment"}

Response

Success (200 OK)

{
  "success": true,
  "campaign_id": "campaign_abc123def456",
  "campaign_name": "Q4_Onboarding_Dropouts",
  "agent_id": "agent_abc123def456",
  "description": "Users who dropped off during Q4 onboarding",
  "created_at": "2024-08-20T10:30:00Z",
  "updated_at": "2024-08-20T15:45:00Z",
  "total_users": 1275,
  "filtered_users": 856,
  "pagination": {
    "page": 1,
    "limit": 100,
    "total_pages": 9
  },
  "users": [
    {
      "user_id": "user_abc123def456",
      "phone_number": "+1234567890",
      "user_name": "John Doe",
      "email": "john@example.com",
      "custom_fields": {
        "signup_date": "2024-08-15",
        "plan_type": "premium",
        "drop_off_stage": "payment_setup"
      },
      "added_at": "2024-08-20T11:00:00Z"
    }
  ]
}

4. Update Campaign

PUT /campaigns/{campaign_id} Updates campaign information, including changing the associated agent.

Request Body

{
  "agent_id": "string",
  "campaign_name": "string",
  "description": "string",
  "status": "string",
  "metadata": object
}

Request Parameters

Parameter	Type	Required	Description
`agent_id`	string	No	New agent ID to associate with campaign
`campaign_name`	string	No	Updated campaign name
`description`	string	No	Updated description
`status`	string	No	Campaign status: `active`, `inactive`, `archived`
`metadata`	object	No	Updated metadata

Response

Success (200 OK)

{
  "success": true,
  "campaign_id": "campaign_abc123def456",
  "updated_fields": ["agent_id", "description"],
  "updated_at": "2024-08-20T16:30:00Z"
}

Single Call APIs

5. Trigger Single Call

POST /calls/trigger Triggers an immediate AI voice call to a specific user without requiring campaign setup.

Request Body

{
  "user_id": "string",
  "phone_number": "string",
  "agent_id": "string",
  "workflow_id": "string",
  "call_type": "string",
  "priority": "string",
  "metadata": {
    "user_name": "string",
    "custom_fields": "object"
  },
  "scheduling": {
    "immediate": boolean,
    "scheduled_time": "string",
    "timezone": "string"
  },
  "configuration": {
    "max_attempts": integer,
    "retry_interval": integer,
    "telephony_provider": "string"
  }
}

Request Parameters

Parameter	Type	Required	Description
`user_id`	string	Yes	Unique identifier for the user
`phone_number`	string	Yes	User’s phone number in E.164 format
`agent_id`	string	Yes	ID of the AI agent to use
`workflow_id`	string	Yes	ID of the workflow/prompt set to use
`call_type`	string	No	Type of call: `onboarding`, `retention`, `support`, `custom`
`priority`	string	No	Call priority: `low`, `medium`, `high` (default: `medium`)
`metadata`	object	No	User-specific data for personalization
`scheduling.immediate`	boolean	No	Trigger immediately (default: `true`)
`scheduling.scheduled_time`	string	No	ISO 8601 datetime for scheduled calls
`configuration.max_attempts`	integer	No	Max retry attempts (default: 3)
`configuration.telephony_provider`	string	No	Provider: `plivo`, `jio` (default: `plivo`)

Response

Success (201 Created)

{
  "success": true,
  "call_id": "call_abc123def456",
  "user_id": "user_abc123def456",
  "phone_number": "+1234567890",
  "status": "queued",
  "agent_id": "agent_abc123def456",
  "workflow_id": "workflow_support_v1",
  "estimated_start_time": "2024-08-20T10:30:00Z",
  "telephony_provider": "plivo",
  "created_at": "2024-08-20T10:25:00Z"
}

6. Get Single Call Status

GET /calls/{call_id}/status Retrieves the current status of a single triggered call.

Path Parameters

Parameter	Type	Required	Description
`call_id`	string	Yes	The call ID to retrieve status for

Response

Success (200 OK)

{
  "success": true,
  "call_id": "call_abc123def456",
  "user_id": "user_abc123def456",
  "phone_number": "+1234567890",
  "status": "completed",
  "agent_id": "agent_abc123def456",
  "workflow_id": "workflow_support_v1",
  "call_type": "support",
  "created_at": "2024-08-20T10:25:00Z",
  "started_at": "2024-08-20T10:30:00Z",
  "completed_at": "2024-08-20T10:34:30Z",
  "duration": "4m 30s",
  "outcome": "completed_successfully",
  "telephony_provider": "plivo",
  "attempt_number": 1,
  "max_attempts": 3,
  "call_summary": {
    "connected": true,
    "conversation_length": "4m 15s",
    "ai_sentiment": "positive",
    "resolution_status": "resolved"
  }
}

Trigger Management APIs

7. Create Trigger

POST /triggers/create Creates a new trigger with AI-generated columns for campaign execution.

Request Body

{
  "trigger_name": "string",
  "campaign_id": "string",
  "workflow_id": "string",
  "ai_columns": [
    {
      "column_name": "string",
      "ai_prompt": "string",
      "data_type": "string"
    }
  ],
  "call_configuration": {
    "telephony_provider": "string",
    "max_attempts": integer,
    "retry_interval": integer
  },
  "scheduling": {
    "timezone": "string",
    "business_hours_only": boolean,
    "excluded_days": array
  }
}

Request Parameters

Parameter	Type	Required	Description
`trigger_name`	string	Yes	Name for the trigger
`campaign_id`	string	Yes	ID of the campaign to target
`workflow_id`	string	Yes	ID of the AI workflow to use
`ai_columns`	array	No	AI-generated columns configuration
`ai_columns[].column_name`	string	Yes	Name of the AI column
`ai_columns[].ai_prompt`	string	Yes	Prompt for AI to generate column data
`ai_columns[].data_type`	string	Yes	Data type: `string`, `number`, `boolean`, `date`
`call_configuration`	object	No	Call-specific configuration
`scheduling`	object	No	Scheduling constraints

Response

Success (201 Created)

{
  "success": true,
  "trigger_id": "trigger_xyz789abc123",
  "trigger_name": "Q4_Recovery_Campaign",
  "campaign_id": "campaign_abc123def456",
  "workflow_id": "workflow_recovery_v2",
  "ai_columns_count": 3,
  "estimated_processing_time": "15-30 minutes",
  "status": "created",
  "created_at": "2024-08-20T17:00:00Z"
}

8. Update Trigger

PUT /triggers/{trigger_id} Updates trigger configuration, including adding or modifying AI columns.

Path Parameters

Parameter	Type	Required	Description
`trigger_id`	string	Yes	The trigger ID to update

Request Body

{
  "trigger_name": "string",
  "workflow_id": "string",
  "ai_columns": [
    {
      "action": "string",
      "column_id": "string",
      "column_name": "string",
      "ai_prompt": "string",
      "data_type": "string"
    }
  ],
  "call_configuration": object
}

AI Column Actions

add: Add new AI column
update: Update existing AI column
delete: Remove AI column

Response

Success (200 OK)

{
  "success": true,
  "trigger_id": "trigger_xyz789abc123",
  "updated_fields": ["ai_columns", "workflow_id"],
  "ai_columns_updated": 2,
  "reprocessing_required": true,
  "updated_at": "2024-08-20T17:30:00Z"
}

9. Run Trigger

POST /triggers/{trigger_id}/run Executes the trigger to start the calling campaign.

Path Parameters

Parameter	Type	Required	Description
`trigger_id`	string	Yes	The trigger ID to execute

Request Body

{
  "concurrency": integer,
  "max_concurrent_calls": integer,
  "priority": "string",
  "filters": object,
  "test_mode": boolean,
  "notification_settings": {
    "email_on_completion": boolean,
    "webhook_url": "string"
  }
}

Request Parameters

Parameter	Type	Required	Description
`concurrency`	integer	No	Concurrency level: 1, 2, 3, or max (default: 1)
`max_concurrent_calls`	integer	No	Maximum simultaneous calls (overrides concurrency)
`priority`	string	No	Execution priority: `low`, `medium`, `high`
`filters`	object	No	Additional filters to apply to campaign
`test_mode`	boolean	No	Run in test mode (no actual calls made)
`notification_settings`	object	No	Notification preferences

Response

Success (200 OK)

{
  "success": true,
  "trigger_id": "trigger_xyz789abc123",
  "execution_id": "exec_456def789ghi",
  "status": "running",
  "target_users": 856,
  "concurrency_level": 2,
  "estimated_completion": "2024-08-20T20:30:00Z",
  "started_at": "2024-08-20T18:00:00Z"
}

10. Get Trigger Data

GET /triggers/{trigger_id}/status Retrieves current status and execution data for a trigger.

Path Parameters

Parameter	Type	Required	Description
`trigger_id`	string	Yes	The trigger ID to get status for

Query Parameters

Parameter	Type	Required	Description
`include_details`	boolean	No	Include detailed execution data
`include_user_status`	boolean	No	Include per-user call status

Response

Success (200 OK)

{
  "success": true,
  "trigger_id": "trigger_xyz789abc123",
  "trigger_name": "Q4_Recovery_Campaign",
  "status": "running",
  "execution_id": "exec_456def789ghi",
  "progress": {
    "total_users": 856,
    "processed_users": 342,
    "successful_calls": 198,
    "failed_calls": 89,
    "in_progress_calls": 12,
    "queued_users": 514,
    "completion_percentage": 40
  },
  "performance": {
    "calls_per_minute": 4.2,
    "average_call_duration": "3m 45s",
    "success_rate": 68.9,
    "estimated_completion": "2024-08-20T20:15:00Z"
  },
  "concurrency": {
    "current_concurrent_calls": 12,
    "max_concurrent_calls": 15,
    "concurrency_level": 2
  },
  "started_at": "2024-08-20T18:00:00Z",
  "last_updated": "2024-08-20T18:45:00Z"
}

Analysis and Export APIs

11. Export Trigger as CSV

GET /triggers/{trigger_id}/export Exports trigger data and results as a CSV file.

Path Parameters

Parameter	Type	Required	Description
`trigger_id`	string	Yes	The trigger ID to export data for

Query Parameters

Parameter	Type	Required	Description
`format`	string	No	Export format: `csv`, `xlsx` (default: `csv`)
`include_fields`	string	No	Comma-separated list of fields to include
`include_call_logs`	boolean	No	Include detailed call logs
`include_ai_columns`	boolean	No	Include AI-generated column data

Response

Success (200 OK)

Content-Type: text/csv
Content-Disposition: attachment; filename="trigger_xyz789abc123_export.csv"

user_id,phone_number,user_name,call_status,call_duration,ai_sentiment_score,ai_engagement_level,custom_field_1
user_abc123def456,+1234567890,John Doe,completed,245,0.8,high,premium
user_def456ghi789,+1234567891,Jane Smith,failed,0,null,null,basic
...

Status Codes and Error Handling

HTTP Status Codes

Status Code	Description	When Used
`200 OK`	Request successful	GET, PUT requests
`201 Created`	Resource created successfully	POST requests
`400 Bad Request`	Invalid request parameters	Validation errors
`401 Unauthorized`	Invalid or missing API key	Authentication errors
`404 Not Found`	Resource not found	Invalid IDs
`409 Conflict`	Resource already exists	Duplicate resources
`422 Unprocessable Entity`	Validation errors	Data format issues
`429 Too Many Requests`	Rate limit exceeded	Too many requests
`500 Internal Server Error`	Server error	System failures

Error Response Format

All error responses follow this consistent format:

{
  "success": false,
  "error": {
    "code": "string",
    "message": "string",
    "details": object
  }
}

Common Error Examples

400 Bad Request

{
  "success": false,
  "error": {
    "code": "INVALID_PARAMETER",
    "message": "Invalid phone number format",
    "details": {
      "parameter": "phone_number",
      "value": "123456789",
      "expected_format": "E.164 format (+1234567890)"
    }
  }
}

401 Unauthorized

{
  "success": false,
  "error": {
    "code": "UNAUTHORIZED",
    "message": "Invalid API key",
    "details": {
      "hint": "Include 'Authorization: Bearer YOUR_API_KEY' in headers"
    }
  }
}

404 Not Found

{
  "success": false,
  "error": {
    "code": "RESOURCE_NOT_FOUND",
    "message": "Campaign not found",
    "details": {
      "resource_type": "campaign",
      "resource_id": "campaign_nonexistent123"
    }
  }
}

Call Status Values

Status	Description
`queued`	Call is queued for execution
`dialing`	Currently dialing the number
`connected`	Call is connected and in progress
`completed`	Call completed successfully
`failed`	Call failed (no answer, busy, etc.)
`cancelled`	Call was cancelled

Trigger Statuses

Status	Description
`created`	Trigger created but not yet executed
`processing_ai`	AI columns are being generated
`ready`	Ready to run
`running`	Currently executing calls
`paused`	Execution paused
`completed`	All calls completed
`failed`	Execution failed
`cancelled`	Execution cancelled by user

Support

If you encounter any issues or need assistance with the API, please contact our support team: Email: contact@revrag.ai Our team will respond to your inquiries and help resolve any technical issues you may experience while using the API.

Endpoints

​Base URLs

​Authentication

​Campaign Management APIs

​1. Create Campaign

​Request Body

​Request Parameters

​Response

​2. Attach Data to Campaign

​Path Parameters

​Request Body (JSON Mode)

​Request Body (CSV Mode)

​Request Parameters

​Mode Descriptions

​Response

​3. Get Campaign

​Path Parameters

​Query Parameters

​Filter Examples

​Response

​4. Update Campaign

​Request Body

​Request Parameters

​Response

​Single Call APIs

​5. Trigger Single Call

​Request Body

​Request Parameters

​Response

​6. Get Single Call Status

​Path Parameters

​Response

​Trigger Management APIs

​7. Create Trigger

​Request Body

​Request Parameters

​Response

​8. Update Trigger

​Path Parameters

​Request Body

​AI Column Actions

​Response

​9. Run Trigger

​Path Parameters

​Request Body

​Request Parameters

​Response

​10. Get Trigger Data

​Path Parameters

​Query Parameters

​Response

​Analysis and Export APIs

​11. Export Trigger as CSV

​Path Parameters

​Query Parameters

​Response

​Status Codes and Error Handling

​HTTP Status Codes

​Error Response Format

​Common Error Examples

​Call Status Values

​Trigger Statuses

​Support

Base URLs

Authentication

Campaign Management APIs

1. Create Campaign

Request Body

Request Parameters

Response

2. Attach Data to Campaign

Path Parameters

Request Body (JSON Mode)

Request Body (CSV Mode)

Request Parameters

Mode Descriptions

Response

3. Get Campaign

Path Parameters

Query Parameters

Filter Examples

Response

4. Update Campaign

Request Body

Request Parameters

Response

Single Call APIs

5. Trigger Single Call

Request Body

Request Parameters

Response

6. Get Single Call Status

Path Parameters

Response

Trigger Management APIs

7. Create Trigger

Request Body

Request Parameters

Response

8. Update Trigger

Path Parameters

Request Body

AI Column Actions

Response

9. Run Trigger

Path Parameters

Request Body

Request Parameters

Response

10. Get Trigger Data

Path Parameters

Query Parameters

Response

Analysis and Export APIs

11. Export Trigger as CSV

Path Parameters

Query Parameters

Response

Status Codes and Error Handling

HTTP Status Codes

Error Response Format

Common Error Examples

Call Status Values

Trigger Statuses

Support