Skip to main content
Veritus Agent provides a powerful API for creating one-off voice calls with built-in compliance checking. The Create Call endpoint gives you full control over initiating individual calls to your customers.

​
How It Works

When you create a call through our API, the system performs the following steps:
  • Compliance Check: Evaluates your configured ruleset to ensure the call meets compliance requirements
  • Call Initiation: If compliance passes, initiates the call through our voice provider
  • Webhook Notification: Sends detailed call information to your webhook endpoint. See the Create Call Webhook endpoint for more information.

​
Compliance-First Approach

Every call goes through automatic compliance checking before being initiated. This ensures:
  • Regulatory Compliance: Calls respect time zones, calling hours, and frequency limits
  • Custom Rules: Organization-specific rules configured by your team
  • Transparency: Clear feedback on which rules passed or failed
If a call doesn’t pass compliance, you’ll receive a detailed response explaining which rules failed and why.

​
API Workflow

​
Step 1: Create a Customer

First, create a customer in our system to get a unique identifier: 
POST /customers
Response: 
{
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "success": true,
  "data": {
    "id": "38E6E4AF-4817-41B5-B70B-12F46D49E74F",
    "externalId": "1234567890",
    "firstName": "John",
    "lastName": "Doe",
    "email": "[email protected]",
    "primaryPhone": "+1234567890",
    "secondaryPhone": "+1234567890",
    "address": {
      "line1": "123 Main St",
      "city": "Anytown",
      "state": "CA",
      "zip": "12345"
    },
    "createdAt": "2024-01-15T10:30:00Z"
  }
}
The returned id will be used to create calls for this customer.

​
Step 2: Create a Call

Once you have a customerId, you can create a call: 
POST /customers/{customerId}/calls
Request Body: 
{
  "agentId": "162c5726-4ad9-4051-9762-fa5f1df21493",
  "customerId": "f9d5f240-e60a-43b6-8e53-b84ad16dced0",
  "webhook": {
    "url": "https://yourserver.com/webhooks/veritus-agent/calls"
  }
}
Parameters:
  • agentId (required): The UUID of the AI agent to use for the call. This will be assigned to you.
  • customerId (required): The UUID of the customer to make the call to. This is returned in the response from the Create Customer endpoint.
  • webhook.url (optional): Your webhook endpoint to receive call updates. See the Create Call Webhook endpoint for more information.
  • webhook.secretId (optional): The UUID of your webhook secret for signing webhooks. When provided, webhooks include X-Webhook-Signature and X-Webhook-Timestamp headers for verification. See the Webhook Security guide for details.
Success Response (200): 
{
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "success": true,
  "data": {
    "id": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
    "toPhoneNumber": "+14152223333",
    "fromPhoneNumber": "+14152224444"
  }
}
Compliance Failed Response (422): 
{
  "requestId": "3c90c3cc-0d44-4b50-8888-8dd25736052a",
  "success": false,
  "publicFacingMessage": "Customer not eligible for call. Failed rules: Respectful Hours Check (Customer local time is 03:00 (outside respectful hours 8am-8:50pm))"
}

​
Step 3: Receive Webhook Notifications

After the call passes compliance and is initiated, you’ll receive detailed call information via your webhook endpoint. The webhook includes:
  • Ended Reason: The reason the call ended
  • Recording URL: A signed URL for the audio recording of the call
  • Call Duration: How long the call lasted
  • Output Variables: The output variables from the call
  • Transcripts: Full conversation transcripts (when available)
  • Metadata: Additional information about the call including compliance results
Configure your webhook endpoint to receive these notifications and track call progress in real-time.

​
Use Cases

The Create Call API is ideal for:
  • On-Demand Outreach: Trigger calls based on specific customer actions
  • Event-Driven Communication: Make calls in response to business events
  • Custom Workflows: Build your own call orchestration logic
  • A/B Testing: Create calls with different agents to test effectiveness
  • Manual Campaigns: Give your team the ability to trigger calls individually

​
Error Handling

The API provides clear error messages for common issues:
  • 404 Not Found: Customer doesn’t exist or doesn’t belong to your organization
  • 400 Bad Request: Invalid phone number or missing required parameters
  • 422 Unprocessable Content: Call failed compliance checks
  • 500 Internal Server Error: System error (contact support with the request ID)

​
Getting Started

To start creating calls:
  1. Get your API credentials from the Authentication Guide
  2. Create a customer using the Create Customer endpoint
  3. Contact our team to configure your AI agents and compliance rules
  4. Make your first call using the endpoint above