Introduction

Welcome to the Romulus API documentation! You can use our API key to access Romulus API endpoints.

Authentication

To authenticate and authorize every request, you must provide a standard authorization HTTP header in every API request:

In this way you can pass the correct header with each request

curl -X GET "https://api.romulus.live/v1/some_call" -H "Authorization: {{apiKey}}"

Validate authentication

To validate your authentication key you can call /me endpoint which will return related organization ID if key is valid, HTTP 401 otherwise.

HTTP Request

POST https://api.romulus.live/v1/me

curl -X GET "https://api.romulus.live/v1/me" -H "Authorization: {{apiKey}}"

It returns JSON structured like this:

{
    "organization_id": "fjjf8-fm1j8-fmqnvnu-71hf6-1vjnvq"
}

Making requests

Pagination

Pageable response:

{
  "content": [],
  "pageable": {
    "page_number": 0,
    "page_size": 20,
    "sort": [],
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "last": true,
  "total_pages": 1,
  "total_elements": 1,
  "size": 20,
  "number": 0,
  "sort": [],
  "first": true,
  "number_of_elements": 1,
  "empty": false
}

Generally endpoints which are used to fetch resources supports pagination.

Pagination request parameters

Property	Required	Description
page	false	page number, default 0
size	false	page size, default 20

Agents

This API section allows fetching AI agents configured in your organization.

List agents

curl -X GET -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
"https://api.romulus.live/v1/ai-agents/agents/search"

It returns paginated JSON with agent objects:

{
  "id": "0a30c0bd-74fe-4712-9121-6e93046a393e",
  "license": null,
  "name": "John Doe",
  "first_message": "{{ end_call }}",
  "prompt": "Agent prompt {{ call_forwarding_a7fb }} 1",
  "max_prompt_size": 15000,
  "language": "EN",
  "default_timezone": "Europe/Rome",
  "type": "OUTBOUND",
  "status": "CONFIGURED",
  "voice_id": "11labs-Dorothy",
  "background_id": "static-noise",
  "outbound_cli": "+380936007771",
  "created_at": "2025-03-03T18:06:48.277770Z",
  "updated_at": "2025-05-19T11:38:46.625600Z"
}

This endpoint allows fetching agent data.

HTTP Request

GET https://api.romulus.live/v1/ai-agents/agents/search

Agent call tasks

This API section describes how to create a call task using AI agent.

List agent call tasks

curl -X GET -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
"https://api.romulus.live/v1/ai-agents/agents/{agentId}/call-tasks"

It returns paginated JSON with an agent call task object:

{
  "id" : "93451f38-5b74-4140-b6d4-8c6ok2aa0ce5",
  "agent_id" : "93451f38-5b74-4140-b6d4-8c6ok2aa0ce5",
  "contact_phone_number" : "+1234567890",
  "contact_data": {
    "email": "[email protected]",
    "name": "John Doe",
    "timezone": "Europe/Rome",
    "custom_1": "Custom Value 1",
    "custom_2": "Custom Value 2",
    "custom_3": "Custom Value 3"
  },
  "attempts" : 0,
  "retry_configuration" : {
    "strategy" : "DYNAMIC_DELAY",
    "attempts" : [
      {
        "attempt" : 1,
        "attempt_delay" : 3600
      },
      {
        "attempt" : 2,
        "attempt_delay" : 7200
      },
      {
        "attempt" : 3,
        "attempt_delay" : 10800
      }
    ]
  },
  "availability_configuration" : {
    "skip_for_first_attempt" : false,
    "days" : [
      {
        "day_of_week" : "MONDAY",
        "time_ranges" : [
          {
            "from" : "09:00",
            "to" : "17:00"
          }
        ]
      },
      {
        "day_of_week" : "TUESDAY",
        "time_ranges" : [
          {
            "from" : "09:00",
            "to" : "17:00"
          }
        ]
      }
    ]
  },
  "metadata": {
    "external_metadata": [
      {
        "key": "key",
        "value": "value"
      }
    ]
  },
  "status" : "PENDING",
  "next_attempt_at" : "2024-03-20T14:30:00Z",
  "created_at" : "2024-03-20T10:00:00.000000Z",
  "updated_at" : "2024-03-20T10:00:00.000000Z"
}

This endpoint allows fetching call tasks of a specified agent. Endpoint supports pagination.

HTTP Request

GET https://api.romulus.live/v1/ai-agents/agents/{agentId}/call-tasks

Start agent call task

This request creates an agent call task with a given configuration

curl --location 'https://api.sandbox.romulus.live/v1/ai-agents/agents/027b07e3-ef64-4667-90be-dabfeef9aa0e/call-tasks' \
--header 'Content-Type: application/json' \
--header 'Authorization: nET4XYI.GccLDllq6fNJgLTKWEUsj5dRLVMBQ2it' \
--data-raw '{
    "contact_phone_number": "+1234567890",
    "retry_configuration": {
        "attempts": [
            {
                "attempt": 1,
                "delay_sec": 60
            },
            {
                "attempt": 2,
                "delay_sec": 200
            }
        ]
    },
    "availability_configuration": {
        "skip_for_first_attempt": true,
        "days": [
            {
                "day_of_week": "MONDAY",
                "timeranges": [
                    {
                        "from": "9:00",
                        "to": "15:00"
                    }
                ]
            },
            {
                "day_of_week": "TUESDAY",
                "timeranges": [
                    {
                        "from": "9:00",
                        "to": "15:00"
                    },
                    {
                        "from": "16:00",
                        "to": "20:00"
                    }
                ]
            }
        ]
    },
    "contact_data": {
        "email": "[email protected]",
        "name": "John Doe",
        "timezone": "Europe/Rome",
        "custom_1": "Custom Value 1",
        "custom_2": "Custom Value 2",
        "custom_3": "Custom Value 3"
    },
    "metadata": [
        {
            "key": "key",
            "value": "value"
        }
    ]
}'

It returns JSON call task object:

{
  "id" : "93451f38-5b74-4140-b6d4-8c6ok2aa0ce5",
  "agent_id" : "93451f38-5b74-4140-b6d4-8c6ok2aa0ce5",
  "contact_phone_number" : "+1234567890",
  "attempts" : 0,
  "retry_configuration" : {
    "strategy" : "DYNAMIC_DELAY",
    "attempts" : [
      {
        "attempt" : 1,
        "attempt_delay" : 60
      },
      {
        "attempt" : 2,
        "attempt_delay" : 200
      }
    ]
  },
  "availability_configuration" : {
    "skip_for_first_attempt" : false,
    "days" : [
      {
        "day_of_week" : "MONDAY",
        "time_ranges" : [
          {
            "from" : "09:00",
            "to" : "15:00"
          }
        ]
      },
      {
        "day_of_week" : "TUESDAY",
        "time_ranges" : [
          {
            "from" : "09:00",
            "to" : "15:00"
          },
          {
            "from" : "16:00",
            "to" : "20:00"
          }
        ]
      }
    ]
  },
  "contact_data": {
    "email": "[email protected]",
    "name": "John Doe",
    "timezone": "Europe/Rome",
    "custom_1": "Custom Value 1",
    "custom_2": "Custom Value 2",
    "custom_3": "Custom Value 3"
  },
  "metadata": {
    "external_metadata": [
      {
        "key": "key",
        "value": "value"
      }
    ]
  },
  "status" : "PENDING",
  "next_attempt_at" : "2024-03-20T14:30:00Z",
  "created_at" : "2024-03-20T10:00:00.000000Z",
  "updated_at" : "2024-03-20T10:00:00.000000Z"
}

This endpoint starts agent call task to specified phone number and using other contact data provided in request for agent context. Generally newly created call tasks are in PENDING status with next_attempt_at execution time.

HTTP Request

POST https://api.romulus.live/v1/ai-agents/agents/{agentId}/call-tasks

Request object

Parameter	Required	Description
contact_phone_number	true	phone number in e164 format which will be called by an agent
retry_configuration	false	section which describes retry configuration
retry_configuration.attempts	true (if retry_configuration is present)	array of retry attempts, first attempt is not considered to be present in this array
retry_configuration.attempts.attempt	true (if retry_configuration is present)	retry attempt index, starts with 1, maximum value 10
retry_configuration.attempts.delay_sec	true (if retry_configuration is present)	delay in seconds before the next retry attempt, minimal value is 60, maximum value is 172800
availability_configuration	false	section which describes availability configuration
availability_configuration.skip_for_first_attempt	false	specifies if to apply availability configuration for first call attempt
availability_configuration.days	true (if availability_configuration is present)	array of availability configuration per day of week
availability_configuration.days.day_of_week	true (if availability_configuration is present)	day of week
availability_configuration.days.timeranges	true (if availability_configuration is present)	array of available time ranges for given day of week
availability_configuration.days.timeranges.from	true (if availability_configuration is present)	availability period start time in format HH:mm (24h format)
availability_configuration.days.timeranges.to	true (if availability_configuration is present)	availability period end time in format HH:mm (24h format)
contact_data	false	ContactData that will be used for the Call

ContactData

Property	Type	Description
name	string, optional	contact's name
email	string, optional	contact's email
timezone	string, optional	contact's timezone
custom_1	string, optional	value for custom property 1
custom_2	string, optional	value for custom property 2
custom_3	string, optional	value for custom property 3

Terminate agent call task

Following endpoints allow terminating active agent call tasks using call task ID or contact phone number. In case of using contact phone number, all active call tasks for that phone number will be terminated.

This request terminates an agent call task by call task ID

curl -X PUT -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
"https://api.romulus.live/v1/ai-agents/agents/call-tasks/{callTaskId}/terminate"

HTTP Request

PUT https://api.romulus.live/v1/ai-agents/agents/call-tasks/{callTaskId}/terminate

This request terminates all active agent call tasks by contact phone number

curl -X PUT -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
-d '{"contact_phone_number":"+1234567890"}'
"https://api.romulus.live/v1/ai-agents/agents/call-tasks/terminate"

HTTP Request

POST https://api.romulus.live/v1/ai-agents/agents/call-tasks/terminate

Request object

Parameter	Required	Description
contact_phone_number	true	phone number in e164 format which will be called by an agent

Calls

Initiate outbound call

Request to initiate call to number +390101010101 with optional parameters filled

curl --location 'https://api.romulus.live/v1/ai-agents/agents/{agentId}/call' \
--header 'Content-Type: application/json' \
--header 'Authorization: {apiKey}' \
--data-raw '{
    "to": "+390101010101",
    "contact_data": {
        "email": "[email protected]",
        "name": "John Smith",
        "timezone": "Europe/Rome",
        "custom_1": "Custom Value 1",
        "custom_2": "Custom Value 2",
        "custom_3": "Custom Value 3"
    },
    "campaign_id": "50713898-5501-467f-b957-31e8247c1ef0"
}'

Success response:

{
  "id": "b126584c-7744-4c5c-9e04-6e438290234b",
  "agent_id": "8c219cfa-75fa-44b4-9d96-3768af3d654b",
  "status": "INITIATED",
  "direction": "OUTBOUND",
  "origination": "+390202020202",
  "destination": "+390101010101",
  "initiated_at": "2025-04-28T20:23:44.847014624Z"
}

Failure response:

{
  "id": "06cf931a-b180-4e52-ac0c-45977e459ee8",
  "agent_id": "8c219cfa-75fa-44b4-9d96-3768af3d654b",
  "status": "FAILED",
  "direction": "OUTBOUND",
  "origination": "+390202020202",
  "destination": "invalid number",
  "error_message": "Phone number is invalid"
}

Initiates outbound call

HTTP Request

POST https://api.romulus.live/v1/ai-agents/agents/{agentId}/call

Request body

Property	Type	Description
to	string, mandatory	phone number in e164 format
contact_data	ContactData, optional	contact data that will be passed to the Agent
campaign_id	string, optional	unique ID of the campaign

ContactData

Property	Type	Description
name	string, optional	contact's name
email	string, optional	contact's email
timezone	string, optional	contact's timezone
custom_1	string, optional	value for custom property 1
custom_2	string, optional	value for custom property 2
custom_3	string, optional	value for custom property 3

Search calls

Request to search calls with filters:

curl --request GET \
  --url 'https://api.romulus.live/v1/pbxes/calls/search?status=COMPLETED&direction=INBOUND&initiated_at_from=2026-05-01T00:00:00Z' \
  --header 'authorization: {token}' \
  --header 'content-type: application/json'

Success response:

{
  "content": [
    {
      "id": "a1b2c3d4e5f6a1b2c3d4e5f6a1b2c3d4",
      "did_label": "Sales",
      "status": "COMPLETED",
      "direction": "INBOUND",
      "origination": "+11234567890",
      "destination": "+19876543210",
      "callee_label": "Sales",
      "duration": 33,
      "has_voicemail": false,
      "agent_id": "00000000-0000-0000-0000-000000000001",
      "call_recording_url": "https://storage.example.com/call-recordings/{tenantId}/{callId}/general.mp3",
      "transcription": "Hello, I'd like to schedule an appointment for next week.",
      "summary": "The customer called to schedule an appointment for the following week.",
      "sentiment": 75,
      "agent_call_recording_url": "https://storage.example.com/call-recordings/{tenantId}/{callId}/agent.mp3",
      "agent_transcription": [
        {
          "ordinal": 0,
          "speaker": "AGENT",
          "text": "Hello, how can I help you today?"
        },
        {
          "ordinal": 1,
          "speaker": "USER",
          "text": "I'd like to schedule an appointment for next week."
        }
      ],
      "agent_summary": "The agent greeted the customer. The customer requested to schedule an appointment for the following week.",
      "initiated_at": "2025-01-15T10:30:00.000000Z"
    }
  ],
  "pageable": {
    "page_number": 0,
    "page_size": 20,
    "sort": [],
    "offset": 0,
    "paged": true,
    "unpaged": false
  },
  "last": false,
  "total_pages": 35,
  "total_elements": 683,
  "first": true,
  "size": 20,
  "number": 0,
  "sort": [],
  "number_of_elements": 20,
  "empty": false
}

Returns a paginated list of calls matching the provided filters.

HTTP Request

GET https://api.romulus.live/v1/pbxes/calls/search

Query Parameters

Parameter	Type	Match	Description
id	string	exact	Filter by call ID
user_id	string	exact	Filter by user ID (caller or callee)
caller_user_id	string	exact	Filter by caller user ID
callee_user_id	string	exact	Filter by callee user ID
agent_id	string	exact	Filter by AI agent ID
endpoint_id	string	exact	Filter by endpoint (DID) ID
did_id	string	exact	Filter by DID ID
campaign_id	string	exact	Filter by campaign ID
origination	string	contains	Filter by origination phone number
destination	string	contains	Filter by destination phone number
caller_label	string	contains (case-insensitive)	Filter by caller label
callee_label	string	contains (case-insensitive)	Filter by callee label
direction	string	exact (case-insensitive)	Filter by call direction: INBOUND, OUTBOUND, INTERNAL
status	string	exact (case-insensitive)	Filter by call status: INITIATED, ANSWERED, BUSY, UNANSWERED, COMPLETED, FAILED, FORWARDED
duration_from	integer	>=	Filter calls with duration (seconds) greater than or equal to value
duration_to	integer	<=	Filter calls with duration (seconds) less than or equal to value
has_voicemail	boolean	not null	When present, filter calls that have a voicemail
initiated_at_from	string	>=	Filter calls initiated at or after this timestamp (ISO 8601)
initiated_at_to	string	<=	Filter calls initiated at or before this timestamp (ISO 8601)
ended_at_from	string	>=	Filter calls ended at or after this timestamp (ISO 8601)
ended_at_to	string	<=	Filter calls ended at or before this timestamp (ISO 8601)

Response

Returns a paginated response containing a list of Call objects.

Call Object

Field	Type	Description
id	string	Unique call identifier
did_label	string	Label of the DID (phone number) involved in the call
status	string	Call status: INITIATED, ANSWERED, BUSY, UNANSWERED, COMPLETED, FAILED, FORWARDED
direction	string	Call direction: INBOUND, OUTBOUND, INTERNAL
origination	string	Originating phone number (E.164 format)
destination	string	Destination phone number (E.164 format)
caller_label	string	Display label for the caller
callee_label	string	Display label for the callee
duration	integer	Call duration in seconds
has_voicemail	boolean	Whether the call has an associated voicemail
agent_id	string	ID of the AI agent that handled the call, if any
caller_user_id	string	User ID of the caller, if applicable
callee_user_id	string	User ID of the callee, if applicable
campaign_id	string	ID of the campaign associated with the call, if any
call_task_id	string	ID of the call task, if applicable
call_recording_url	string	URL of the general call recording
transcription	string	Transcription of the general call audio
summary	string	AI-generated summary of the call
sentiment	integer	Sentiment score of the call (0–100)
agent_call_recording_url	string	URL of the AI agent's call recording
agent_transcription	array of Transcription	Turn-by-turn transcription of the agent interaction
agent_summary	string	AI-generated summary of the agent interaction
initiated_at	string	Timestamp when the call was initiated (ISO 8601)

Note: The fields agent_id, agent_call_recording_url, agent_transcription, and agent_summary are only present in the response when an AI agent participated in the call.

Transcription Object

Field	Type	Description
ordinal	integer	Turn order index (0-based)
speaker	string	Speaker role: AGENT or USER
text	string	Spoken text for this turn

Campaigns

This API section allows to manage call tasks in campaign.

Create call tasks

Example request for creating campaign call tasks

curl -X POST "https://api.romulus.live/v1/call-campaigns/hcn3d8jb-hn3k-ld6g-7ygd-hsnd3d20d8nd/tasks" 
  -H "Authorization: {{apiKey}}" 
  -H "Content-Type: application/json"
  -d '{
    "import_source": "API",
    "recipients": [
      {
        "contact_phone_number": "invalid 123 phone 4567 number",
        "contact_name": "Leonardo",
        "contact_email": "[email protected]",
        "contact_timezone": "Europe/Rome",
        "custom_1": "Custom Value 1",
        "custom_2": "Custom Value 2",
        "custom_3": "Custom Value 3"
      },
      {
        "contact_phone_number": "+123456789012",
        "contact_name": "Tom",
        "contact_email": "[email protected]",
        "contact_timezone": "Europe/Berlin",
        "custom_1": "Custom Value 1",
        "custom_2": "Custom Value 2",
        "custom_3": "Custom Value 3"
      }
    ]
  }'

Add new call tasks to Campaign for each recipient

HTTP Request

POST https://api.romulus.live/v1/call-campaigns/{callCampaignId}/tasks

It returns JSON structured like this:

{
  "call-tasks" : [
    {
      "id" : "84810a2d-64f1-45fa-b607-f8d913497fad",
      "import_row_index" : 0,
      "import_errors" : [
        {
          "code" : 101,
          "message" : "Recipient phone number not specified",
          "raw_value" : "invalid 123 phone 4567 number",
          "substitute" : "Phone number must be in e164 format",
          "reference" : "contact_phone_number"
        }
      ],
      "import_status" : "FAILED",
      "import_source" : "API",
      "call_status" : "FAILED",
      "attempts" : 0,
      "recipient_file_id" : -1,
      "ordinal" : 3,
      "created_at" : "2025-09-14T15:11:30.997234Z",
      "updated_at" : "2025-09-14T15:11:30.997258Z",
      "contact_phone_number" : "",
      "contact_name" : "Leonardo",
      "contact_email" : "[email protected]",
      "contact_timezone" : "Europe/Rome",
      "custom_1": "Custom Value 1",
      "custom_2": "Custom Value 2",
      "custom_3": "Custom Value 3"
    },
    {
      "id" : "4da1e933-bb2a-4662-a379-2b4e213c95d3",
      "import_row_index" : 1,
      "import_errors" : [ ],
      "import_status" : "VALID",
      "import_source" : "API",
      "call_status" : "NEW",
      "attempts" : 0,
      "recipient_file_id" : -1,
      "ordinal" : 4,
      "created_at" : "2025-09-14T15:11:31.005478Z",
      "updated_at" : "2025-09-14T15:11:31.005487Z",
      "contact_phone_number" : "+123456789012",
      "contact_name" : "Tom",
      "contact_email" : "tom@mailcom",
      "contact_timezone" : "Europe/Berlin",
      "custom_1": "Custom Value 1",
      "custom_2": "Custom Value 2",
      "custom_3": "Custom Value 3"
    }
  ]
}

Terminate call tasks

Example request for terminating campaign call tasks

curl -X PUT "https://api.romulus.live/v1/call-campaigns/hcn3d8jb-hn3k-ld6g-7ygd-hsnd3d20d8nd/tasks/terminate" 
  -H "Authorization: {{apiKey}}" 
  -H "Content-Type: application/json"
  -d '{
    "phone_number": "+39123456789012"
  }'

Terminates call task by phone number

HTTP Request

PUT https://api.romulus.live/v1/call-campaigns/{callCampaignId}/tasks/terminate

It returns JSON structured like this:

{
  "call-tasks" : [
    {
      "id" : "15c96d7e-45d2-40c3-bb27-31970d8e73cb",
      "import_row_index" : 1,
      "import_errors" : [ ],
      "import_status" : "VALID",
      "import_source" : "API",
      "call_status" : "TERMINATED",
      "attempts" : 0,
      "recipient_file_id" : -1,
      "ordinal" : 10,
      "created_at" : "2025-09-15T13:10:54.228511Z",
      "updated_at" : "2025-09-17T11:31:33.138454Z",
      "contact_phone_number" : "+39123456789012",
      "contact_name" : "Alice",
      "contact_email" : "[email protected]",
      "contact_timezone" : "Europe/Berlin",
      "custom_1": "Custom Value 1",
      "custom_2": "Custom Value 2",
      "custom_3": "Custom Value 3"
    },
    {
      "id" : "4ea96af7-21d7-4870-b3c8-4eb5875711b6",
      "import_row_index" : 2,
      "import_errors" : [ ],
      "import_status" : "VALID",
      "import_source" : "FILE_UPLOAD",
      "call_status" : "TERMINATED",
      "attempts" : 0,
      "recipient_file_id" : 527,
      "ordinal" : 8,
      "created_at" : "2025-09-15T13:04:30.423560Z",
      "updated_at" : "2025-09-17T11:31:33.146878Z",
      "contact_phone_number" : "+39123456789012",
      "contact_name" : "Alice",
      "contact_email" : "[email protected]",
      "contact_timezone" : "Europe/Berlin",
      "custom_1": "Custom Value 1",
      "custom_2": "Custom Value 2",
      "custom_3": "Custom Value 3"
    }
  ]
}

Contacts

The Contacts API allows you to manage your contact book. You can create, retrieve, update, delete, and search contacts. Each contact can hold personal details, multiple phone numbers, email addresses, and physical addresses.

Get contact

This request retrieves the contact with ID a1b2c3d4-e5f6-7890-ab12-cd34ef567890

curl -X GET -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" \
"https://api.romulus.live/v2/contacts/a1b2c3d4-e5f6-7890-ab12-cd34ef567890"

It returns JSON structured like this:

{
  "id" : "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
  "external_id" : null,
  "first_name" : "John",
  "last_name" : "Doe",
  "emails" : [
    {
      "id" : "e1e2e3e4-e5e6-7890-ab12-cd34ef567890",
      "email" : "[email protected]",
      "label" : "PRIMARY"
    }
  ],
  "phones" : [
    {
      "id" : "p1p2p3p4-e5f6-7890-ab12-cd34ef567890",
      "number" : "+39012345678",
      "label" : "MOBILE"
    }
  ],
  "addresses" : [
    {
      "id" : "d1d2d3d4-e5f6-7890-ab12-cd34ef567890",
      "address_line" : "Via Roma 1",
      "street" : "Via Roma",
      "postal_code" : "00100",
      "city" : "Rome",
      "province" : "RM",
      "country" : "Italy"
    }
  ],
  "job_title" : "Software Engineer",
  "company_name" : "Acme Corp",
  "website" : "https://acme.example.com",
  "crm_name" : null,
  "crm_contact_url" : null,
  "crm_logo" : null,
  "source" : "API",
  "tags" : [],
  "metadata" : {},
  "created_at" : "2024-08-15T10:00:00.000Z",
  "updated_at" : "2024-08-15T10:00:00.000Z"
}

This endpoint retrieves a single contact by its unique identifier.

HTTP Request

GET https://api.romulus.live/v2/contacts/{contactId}

Path parameters

Parameter	Description
contactId	unique identifier of a contact

Response object

Property	Description
id	unique contact identifier
external_id	contact identifier from an external CRM, if synced
first_name	contact first name
last_name	contact last name
emails	list of email address objects
phones	list of phone number objects
addresses	list of physical address objects
job_title	contact job title
company_name	contact company name
website	contact website URL
crm_name	name of the CRM the contact was synced from, if applicable
crm_contact_url	URL to the contact record in the source CRM, if applicable
crm_logo	logo URL of the source CRM, if applicable
source	contact origin: API, INTEGRATION, IMPORT, USER, CHAT, or INTERNAL
tags	list of tag objects associated with this contact
metadata	arbitrary key-value metadata attached to the contact
created_at	contact creation timestamp (UTC)
updated_at	contact last update timestamp (UTC)

Search contacts

This request searches for contacts with the last name "Doe" and a specific tag, returning the first page of 20 results

curl -X POST -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" \
-d '{"last_name":"Doe","tags":["vip"],"page":0,"size":20}' \
"https://api.romulus.live/v2/contacts/search"

It returns paginated JSON structured like this:

{
  "content" : [
    {
      "id" : "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
      "first_name" : "John",
      "last_name" : "Doe",
      "emails" : [
        {
          "id" : "e1e2e3e4-e5e6-7890-ab12-cd34ef567890",
          "email" : "[email protected]",
          "label" : "PRIMARY"
        }
      ],
      "phones" : [
        {
          "id" : "p1p2p3p4-e5f6-7890-ab12-cd34ef567890",
          "number" : "+39012345678",
          "label" : "MOBILE"
        }
      ],
      "addresses" : [],
      "source" : "API",
      "tags" : [
        {
          "id" : "t1t2t3t4-e5f6-7890-ab12-cd34ef567890",
          "name" : "vip",
          "color" : "#FF5733",
          "created_at" : "2024-08-15T10:00:00.000Z",
          "updated_at" : "2024-08-15T10:00:00.000Z"
        }
      ],
      "metadata" : {},
      "created_at" : "2024-08-15T10:00:00.000Z",
      "updated_at" : "2024-08-15T10:00:00.000Z"
    }
  ],
  "page" : 0,
  "size" : 20,
  "total_elements" : 1,
  "total_pages" : 1
}

This endpoint allows you to search contacts using multiple optional filter criteria. All filters are combined with AND logic. Endpoint supports pagination.

HTTP Request

POST https://api.romulus.live/v2/contacts/search

Request object

Parameter	Required	Description
id	false	filter by exact contact ID
ids	false	filter by a list of contact IDs
first_name	false	filter by first name (partial match)
last_name	false	filter by last name (partial match)
phone	false	filter by phone number (partial match from right-to-left)
email	false	filter by email address (partial match)
job_title	false	filter by job title (partial match)
company_name	false	filter by company name (partial match)
website	false	filter by website (partial match)
crm_name	false	filter by CRM name
source	false	filter by source: API, INTEGRATION, IMPORT, USER, CHAT, or INTERNAL
tags	false	filter by tag names (contacts must have at least one matching tag)
tags_ids	false	filter by tag IDs (contacts must have at least one matching tag)
street	false	filter by street (partial match)
postal_code	false	filter by postal code (partial match)
city	false	filter by city (partial match)
province	false	filter by province/region (partial match)
country	false	filter by country (partial match)
created_at_range	false	filter by creation date range — object with from and to ISO 8601 timestamps
updated_at_range	false	filter by last update date range — object with from and to ISO 8601 timestamps
page	true	page number, starting from 0
size	true	number of results per page, between 1 and 200

Create contact

This request creates a new contact

curl -X POST -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" \
-d '{
  "first_name": "John",
  "last_name": "Doe",
  "phones": [{"number": "+39012345678", "label": "MOBILE"}],
  "emails": [{"email": "[email protected]", "label": "PRIMARY"}],
  "company_name": "Acme Corp",
  "job_title": "Software Engineer"
}' \
"https://api.romulus.live/v2/contacts"

It returns JSON with the created contact object:

{
  "id" : "a1b2c3d4-e5f6-7890-ab12-cd34ef567890",
  "external_id" : null,
  "first_name" : "John",
  "last_name" : "Doe",
  "emails" : [
    {
      "id" : "e1e2e3e4-e5e6-7890-ab12-cd34ef567890",
      "email" : "[email protected]",
      "label" : "PRIMARY"
    }
  ],
  "phones" : [
    {
      "id" : "p1p2p3p4-e5f6-7890-ab12-cd34ef567890",
      "number" : "+39012345678",
      "label" : "MOBILE"
    }
  ],
  "addresses" : [],
  "job_title" : "Software Engineer",
  "company_name" : "Acme Corp",
  "website" : null,
  "crm_name" : null,
  "crm_contact_url" : null,
  "crm_logo" : null,
  "source" : "API",
  "tags" : [],
  "metadata" : {},
  "created_at" : "2024-08-26T13:49:28.825Z",
  "updated_at" : "2024-08-26T13:49:28.825Z"
}

This endpoint creates a new contact. The source is automatically set to API for contacts created through this endpoint.

HTTP Request

POST https://api.romulus.live/v2/contacts

Request object

Parameter	Required	Description
first_name	true	contact first name
last_name	false	contact last name
emails	false	list of email address objects (see email object below)
phones	false	list of phone number objects (see phone object below)
addresses	false	list of physical address objects (see address object below)
job_title	false	contact job title
company_name	false	contact company name
website	false	contact website URL
tags	false	set of tag names to associate with the contact
tag_ids	false	set of tag IDs to associate with the contact

Phone object

Parameter	Required	Description
number	true	phone number in E.164 format (e.g. +39012345678)
label	false	phone label: EXTENSION, PRIMARY, SECONDARY, MOBILE, HOME, JOB, OTHER (default)

Email object

Parameter	Required	Description
email	true	valid email address
label	false	email label: PRIMARY, SECONDARY, JOB, HOME, OTHER (default)

Address object

Parameter	Required	Description
address_line	false	full address line
street	false	street name
postal_code	false	postal / ZIP code
city	false	city name
province	false	province or region
country	false	country name

Update contact

This request updates the contact with ID a1b2c3d4-e5f6-7890-ab12-cd34ef567890

curl -X PUT -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" \
-d '{
  "first_name": "John",
  "last_name": "Smith",
  "phones": [{"number": "+39012345678", "label": "MOBILE"}],
  "emails": [{"email": "[email protected]", "label": "PRIMARY"}],
  "company_name": "New Corp"
}' \
"https://api.romulus.live/v2/contacts/a1b2c3d4-e5f6-7890-ab12-cd34ef567890"

It returns JSON with the updated contact object (same structure as the create response).

This endpoint fully replaces the contact's data with the provided values. The request body follows the same structure as the create contact request. Any fields omitted from the request will be cleared.

HTTP Request

PUT https://api.romulus.live/v2/contacts/{contactId}

Path parameters

Parameter	Description
contactId	unique identifier of a contact

Request object

The request body accepts the same fields as Create contact.

Delete contact

This request deletes the contact with ID a1b2c3d4-e5f6-7890-ab12-cd34ef567890

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" \
"https://api.romulus.live/v2/contacts/a1b2c3d4-e5f6-7890-ab12-cd34ef567890"

This endpoint permanently deletes a contact and all its associated phones, emails, and addresses.

HTTP Request

DELETE https://api.romulus.live/v2/contacts/{contactId}

Path parameters

Parameter	Description
contactId	unique identifier of a contact

Messenger

This API section allows to fetch WhatsApp bots configurations and send WhatsApp template messages.

List WhatsApp bots

curl -X GET -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
"https://api.romulus.live/v1/messengers/whatsapp/bots"

It returns paginated JSON with WhatsApp bot objects:

{
  "id" : "4bdad4d3-469a-4633-9f03-634836532303",
  "name" : "My WA bot",
  "templates" : [
    {
      "id" : "fb4e0f8a-5270-42a2-ac5c-06469ec52cd4",
      "name" : "My WA bot template",
      "category" : "marketing",
      "language" : "en",
      "status" : "approved",
      "components" : [
        {
          "type" : "body",
          "format" : "text",
          "text" : "Hello, {{1}}!"
        }
      ]
    }
  ]
}

This endpoint allows to fetch WhatsApp bots data including bot templates. Object structure is pretty similar to WhatsApp API models.

HTTP Request

GET https://api.romulus.live/v1/messengers/whatsapp/bots

Send WhatsApp template message

This request sends WhatsApp template message to number +39012345678

curl -X POST -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
-d '{"bot_id": "93451f38-5b74-4140-b6d4-8c6ok2aa0ce5","template_id": "fb4e0f8a-5270-42a2-ac5c-06469ec52cd4","recipient":"+39012345678","parameters":[]}'
"https://api.romulus.live/v1/messengers/whatsapp/template-message"

Sample request body with single template parameter in template body

{
  "bot_id" : "93451f38-5b74-4140-b6d4-8c6ok2aa0ce5",
  "template_id" : "fb4e0f8a-5270-42a2-ac5c-06469ec52cd4",
  "recipient" : "+39012345678",
  "parameters" : [
    {
      "component" : "body",
      "component_parameters" : [
        {
          "type" : "text",
          "text" : "Marco"
        }
      ]
    }
  ]
}

It returns JSON structured like this:

{
  "success" : true
}

This endpoint allows to send WhatsApp template message. Currently template parameters supported in header and body template components.

HTTP Request

POST https://api.romulus.live/v1/messengers/whatsapp/template-message

Request object

Parameter	Required	Description
bot_id	true	WhatsApp bot ID
template_id	true	WhatsApp bot template ID
parameters	false	WhatsApp bot template parameters

Webhook Subscriptions

Webhook subscription allow you to subscribe to particular event with some additional specifications.

Webhook Subscription Breakdown

Status

Status	Description
ACTIVE	Set by default on creation
DISABLED	Can be set from API, disables webhook subscription

Events

Event	Description
AGENT_CALL_COMPLETED	Sent after AI agent call is concluded
AGENT_ACTION_COMPLETED	Sent after AI agent action is executed

Some events can be customized deeper with entity and specifications settings

Entities

Entity can customize webhooks to subscribe to a specific main subject of the Event

Entity	Description	Supported by Event
AGENT	Allows to subscribe to webhooks for specific agent	AGENT_CALL_COMPLETED, AGENT_ACTION_COMPLETED

Specifications

Specifications allow further customization for webhooks

Specification	Description	Supported by Event
ACTION_ID	Allows to subscribe to specific action by ID	AGENT_ACTION_COMPLETED
ACTION_TYPE	Allows to subscribe to specific action type	AGENT_ACTION_COMPLETED

Webhook Subscription Properties

Property	Type	Description
id	string	unique ID of the webhook subscription
event	Event	event type for webhook subscription
status	Status	current status of subscription
entity_type	Entity	type of entity for customization
entity_id	string	unique ID of entity for customization
url	string	URL that will be used as a target to send webhooks
attempts	number	amount of attempts before giving up
attempts_interval_seconds	number	interval between attempts in seconds
specifications	map, Specification to string	specifications for additional customization

List all Webhook Subscriptions

curl -X GET -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
"https://api.romulus.live/v1/webhook-subscriptions/search"

Response:

{
  "content" : [
    {
      "id" : "143f5506b2a14c8ea3a565d7d1f40c51",
      "status" : "ACTIVE",
      "event" : "AGENT_CALL_COMPLETED",
      "entity_id" : "5128437e-c64e-44e2-8f37-c8ef05530a2b",
      "entity_type" : "AGENT",
      "url" : "https://webhook.site/f9baa4cc-f46d-45b0-a082-927b2e32ffb7",
      "attempts" : 3,
      "attempts_interval_seconds" : 10,
      "specifications" : { },
      "created_at" : "2025-04-17T07:59:35.813396Z",
      "updated_at" : "2025-04-17T07:59:35.813444Z"
    },
    {
      "id" : "1737134378f14367961a35932f440d1f",
      "status" : "ACTIVE",
      "event" : "AGENT_ACTION_COMPLETED",
      "entity_id" : null,
      "entity_type" : null,
      "url" : "https://webhook.site/f9baa4cc-f46d-45b0-a082-927b2e32ffb7",
      "attempts" : 3,
      "attempts_interval_seconds" : 10,
      "specifications" : {
        "ACTION_TYPE" : "CALL_FORWARDING"
      },
      "created_at" : "2025-04-17T08:47:37.322850Z",
      "updated_at" : "2025-04-17T08:47:37.322862Z"
    }
  ],
  "pageable" : {
    "page_number" : 0,
    "page_size" : 20,
    "sort" : [ ],
    "offset" : 0,
    "paged" : true,
    "unpaged" : false
  },
  "total_pages" : 1,
  "total_elements" : 5,
  "last" : true,
  "size" : 20,
  "number" : 0,
  "sort" : [ ],
  "number_of_elements" : 5,
  "first" : true,
  "empty" : false
}

Returns all Webhook Subscriptions on account

HTTP Request

GET https://api.romulus.live/v1/webhook-subscriptions/search

Get Webhook Subscription

curl -X GET -H "Content-Type: application/json" -H "Authorization: {{apiKey}}"
"https://api.romulus.live/v1/webhook-subscriptions/143f5506b2a14c8ea3a565d7d1f40c51"

Response:

{
  "id" : "143f5506b2a14c8ea3a565d7d1f40c51",
  "status" : "ACTIVE",
  "event" : "AGENT_CALL_COMPLETED",
  "entity_id" : null,
  "entity_type" : null,
  "url" : "https://webhook.site/f9baa4cc-f46d-45b0-a082-927b2e32ffb7",
  "attempts" : 3,
  "attempts_interval_seconds" : 10,
  "specifications" : { },
  "created_at" : "2025-04-17T07:59:35.813396Z",
  "updated_at" : "2025-04-17T07:59:35.813444Z"
}

Retrieves a single Webhook Subscription by ID

HTTP Request

GET https://api.romulus.live/v1/webhook-subscriptions/{webhookSubscriptionId}

Create Webhook Subscription

curl -X POST -H "Content-Type: application/json" -H "Authorization: {{apiKey}}"
-d '{ "event": "AGENT_ACTION_COMPLETED", "url": "https://webhook.site/f9baa4cc-f46d-45b0-a082-927b2e32ffb7", "attempts": 3, "entity_id": "5128437e-c64e-44e2-8f37-c8ef05530a2b", "entity_type": "AGENT", "specifications": { "ACTION_TYPE": "CALL_FORWARDING" }, "attempts_interval_seconds": 10 }'
"https://api.romulus.live/v1/webhook-subscriptions"

Response:

{
  "id" : "143f5506b2a14c8ea3a565d7d1f40c51",
  "status" : "ACTIVE",
  "event" : "AGENT_CALL_COMPLETED",
  "entity_id" : "AGENT",
  "entity_type" : "5128437e-c64e-44e2-8f37-c8ef05530a2b",
  "url" : "https://webhook.site/f9baa4cc-f46d-45b0-a082-927b2e32ffb7",
  "attempts" : 3,
  "attempts_interval_seconds" : 10,
  "specifications" : { 
    "ACTION_TYPE" : "CALL_FORWARDING"
  },
  "created_at" : "2025-04-17T07:59:35.813396Z",
  "updated_at" : "2025-04-17T07:59:35.813444Z"
}

Creates Webhook Subscription

HTTP Request

POST https://api.romulus.live/v1/webhook-subscriptions

Request body

Property	Type	Mandatory
event	Event	true
entity_type	Entity	false
entity_id	string	true if entity_type set, otherwise false
url	string	true
attempts	number	false, defaults to 3
attempts_interval_seconds	number	false, defaults to 10
specifications	map, Specification to string	false

Update Webhook Subscription

curl -X PUT -H "Content-Type: application/json" -H "Authorization: {{apiKey}}"
-d '{ "status": "DISABLED", "url": "https://webhook.site/f9baa4cc-f46d-45b0-a082-927b2e32ffb7", "attempts": 3, "entity_id": "5128437e-c64e-44e2-8f37-c8ef05530a2b", "entity_type": "AGENT", "specifications": { "ACTION_TYPE": "CALL_FORWARDING" }, "attempts_interval_seconds": 10 }'
"https://api.romulus.live/v1/webhook-subscriptions/143f5506b2a14c8ea3a565d7d1f40c51"

Response:

{
  "id" : "143f5506b2a14c8ea3a565d7d1f40c51",
  "status" : "DISABLED",
  "event" : "AGENT_CALL_COMPLETED",
  "entity_id" : null,
  "entity_type" : null,
  "url" : "https://webhook.site/f9baa4cc-f46d-45b0-a082-927b2e32ffb7",
  "attempts" : 3,
  "attempts_interval_seconds" : 10,
  "specifications" : {
    "ACTION_TYPE" : "CALL_FORWARDING"
  },
  "created_at" : "2025-04-17T07:59:35.813396Z",
  "updated_at" : "2025-04-17T07:59:35.813444Z"
}

Updates Webhook Subscription by ID

HTTP Request

PUT https://api.romulus.live/v1/webhook-subscriptions/{webhookSubscriptionId}

Request body

Property	Type	Mandatory
status	Status	true
entity_type	Entity	false
entity_id	string	true if entity_type set, otherwise false
url	string	true
attempts	number	false, defaults to 3
attempts_interval_seconds	number	false, defaults to 10
specifications	map, Specification to string	false

Delete Webhook Subscription

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: {{apiKey}}"
"https://api.romulus.live/v1/webhook-subscriptions/143f5506b2a14c8ea3a565d7d1f40c51"

Deletes Webhook Subscription by ID

HTTP Request

DELETE https://api.romulus.live/v1/webhook-subscriptions/{webhookSubscriptionId}

Webhook Event Models

Call completed (AGENT_CALL_COMPLETED)

Example:

 {
  "event" : "AGENT_CALL_COMPLETED",
  "call_id" : "b4d8cb59-a2c0-4424-9201-5e36981c2223",
  "agent_id" : "950c3899-d6b2-45d9-b8df-724a6c614c5e",
  "status" : "COMPLETED",
  "direction" : "OUTBOUND",
  "origination" : "+39----------",
  "destination" : "+39----------",
  "duration" : 70,
  "call_recording_url" : "https://storage.example.com/call-recordings/{tenantId}/{callId}/recording.mp3",
  "general_transcription" : "Hello. Hello, I'm Maya from Tasty Cakes. How can I help you?",
  "general_summary" : "The caller contacted Tasty Cakes to make a table reservation for the following day.",
  "general_sentiment" : 80,
  "agent_transcription" : [
    {
      "speaker" : "USER",
      "text" : "Hello."
    },
    {
      "speaker" : "AGENT",
      "text" : "Hello, I'm an AI assistant. How can I help you?"
    }
  ],
  "agent_summary" : "The caller contacted the assistant to make a table reservation for the following day. The assistant confirmed a reservation for 5:00 PM.",
  "metadata" : {
    "contact_data" : {
      "email" : "[email protected]",
      "name" : "Jonh",
      "timezone" : "Europe/Rome",
      "phone_number" : "+39---------"
    }
  },
  "action_results" : [
    {
      "type" : "CALL_FORWARDING",
      "action_id" : "711c004-d6b3-45f9-baf3-524fsa924c3e",
      "data" : {
        "attempts" : [
          {
            "target" : "39-------",
            "child_call_id" : "05647ef8-50cb-4fa7-93c0-83ce3eddb45c",
            "status" : "INITIATED"
          }
        ]
      }
    },
    {
      "type" : "WHATS_APP_MESSAGE",
      "action_id" : "711c004-d6b3-45f9-baf3-524fsa924c3e",
      "data" : {
        "send_message_result_logs" : [
          {
            "extracted_properties" : [
              {
                "key" : "Sei soddisfatto dell'ultimo intervento di spurgo effettuato?",
                "value" : "Si"
              }
            ],
            "phone_number" : "+39...",
            "success" : true,
            "attempted_at" : "2025-03-31T10:18:47Z",
            "message_components" : [
              {
                "type" : "header",
                "format" : "text",
                "text" : "Grazie per aver visitato il nostro stand Voxloud!"
              },
              {
                "type" : "body",
                "text" : "Siamo entusiasti di aver avuto l'opportunità di conoscerti durante l'evento e di condividere con te come il nostro servizio Voxloud può portare valore alla tua attività.\uD83D\uDE4C\nPer approfondire e discutere delle tue esigenze, clicca sul pulsante qui sotto \"DEMO\" e fissa un appuntamento con uno dei nostri specialisti.\uD83D\uDCC5\nNon vediamo l'ora di sentirti!\uD83D\uDE0A"
              },
              {
                "type" : "footer",
                "text" : "Some text"
              },
              {
                "type" : "buttons",
                "buttons" : [
                  {
                    "type" : "url",
                    "text" : "DEMO",
                    "url" : "https://..."
                  }
                ]
              }
            ]
          }
        ]
      }
    },
    {
      "type" : "APPOINTMENT",
      "action_id" : "711c004-d6b3-45f9-baf3-524fsa924c3e",
      "data" : {
        "appointment_entries" : [
          {
            "step" : "AVAILABILITY",
            "success" : true,
            "attempted_at" : "2025-03-28T12:33:24Z"
          },
          {
            "step" : "SCHEDULING",
            "success" : true,
            "attempted_at" : "2025-03-28T12:33:24Z",
            "event_data" : {
              "id" : "event_id",
              "url" : "https://...",
              "start" : {
                "date" : "2025-03-31",
                "time" : "15:00"
              },
              "end" : {
                "date" : "2025-03-31",
                "time" : "16:00"
              },
              "timezone" : "Europe/Rome"
            }
          }
        ]
      }
    },
    {
      "type" : "DATA_EXTRACTION",
      "action_id" : "711c004-d6b3-45f9-baf3-524fsa924c3e",
      "data" : {
        "extracted_properties" : [
          {
            "description" : "Sei soddisfatto dell'ultimo intervento di spurgo effettuato?",
            "value" : "Si"
          }
        ]
      }
    }
  ],
  "ended_at" : "2025-03-31T10:18:47Z",
  "initiated_at" : "2025-03-31T10:17:36.696603Z"
}

Call Event properties

Property	Type	Description
event	string, [AGENT_CALL_COMPLETED]	event type for webhook subscription, always AGENT_CALL_COMPLETED
call_id	string	unique ID of the call
agent_id	string	unique ID of the agent
status	string	final status of the call
direction	string, [INBOUND, OUTBOUND]	call direction
origination	string	phone number in e164 format of the caller
destination	string	phone number in e164 format of the callee
duration	number	call duration in seconds
call_recording_url	string	call recording URL
general_transcription	string	full text transcription of the call audio
general_summary	string	AI-generated summary of the full call
general_sentiment	integer	sentiment score of the call (0–100)
agent_transcription	array, Transcription	turn-by-turn transcription of the agent interaction
agent_summary	string	AI-generated summary of the agent interaction
transcriptions	array, Transcription	Deprecated. Use agent_transcription instead
summary	string	Deprecated. Use agent_summary instead
metadata	Metadata	call metadata
action_results	array, ActionResult	specifications for additional customization
call_task	CallTask	the call task that initiated this call; present only when the call was initiated by an agent call task
initiated_at	string	date time of the moment call was initiated (not started)
ended_at	string	date time of the moment call was ended

Metadata properties

Property	Type	Description
contact_data	ContactData	metadata of the contact, set before the call started

ContactData properties

Property	Type	Description
email	string	email of the contact
name	string	name of the contact
timezone	string	timezone of the contact
phone_number	string	phone number of the contact in e164 format

Transcription properties

Property	Type	Description
speaker	string, [USER, AGENT]	speaker, can be AI or user who speaks with it
text	string	speech of the speaker

CallTask properties

Present only when the call was initiated by an agent call task.

Property	Type	Description
id	string	unique ID of the call task
status	string	final status of the call task: PENDING, COMPLETED, TERMINATED, FAILED

ActionResult

Property	Type	Description
type	string, [APPOINTMENT, CALL_FORWARDING, DATA_EXTRACTION, WHATS_APP_MESSAGE]	action type
action_id	string	unique ID of the action
data	DataExtractionResult, WhatsAppMessageResult, CallForwardingResult, AppointmentResult	result of the action, based on action type

DataExtractionResult properties:

Property	Type	Description
extracted_properties	array, ExtractedProperty	property extracted during conversation

ExtractedProperty:

Property	Type	Description
description	string	description of the property, set during action creation
value	string	value, set by AI during conversation

WhatsAppMessageResult properties:

Property	Type	Description
send_message_result_logs	array, SendMessageResult	result of send WA message attempt

SendMessageResult:

Property	Type	Description
extracted_properties	array, ExtractedProperty	property extracted during conversation
phone_number	string	phone number in e164 format, that was used as a target for WA message
success	boolean	indicates if attempt was successful or not
attempted_at	string	date time of the moment send WA message attempt happened
message_components	array, MessageComponent	components of WA message

CallForwardingResult properties:

Property	Type	Description
attempts	array, CallForwardingAttempt	array of call forwarding attempts

CallForwardingAttempt:

Property	Type	Description
target	string	call forwarding target phone number
child_call_id	string	unique ID of the call created during forwarding
status	string [INITIATED, FAILED]	status of the attempt

AppointmentResult properties:

Property	Type	Description
appointment_entries	string, AppointmentEntry	list of appointment related actions

AppointmentEntry:

Property	Type	Description
step	string, [AVAILABILITY, SCHEDULING]	appointment step
success	boolean	indicates if step was executed successfully
attempted_at	string	date time of the moment step was attempted
event_data	EventData	data of the created event

EventData:

Property	Type	Description
id	string	external event id
url	string	event URL
start	DateTime	date time of the event start
end	DateTime	date time of the event end
timezone	string	timezone of the start and end time (calendar timezone)

DateTime:

Property	Type	Description
date	string	YYYY-MM-DD
time	string	HH:MM

Action completed (AGENT_ACTION_COMPLETED)

Call Forwarding action completed example:

{
  "event" : "AGENT_ACTION_COMPLETED",
  "action_id" : "b58c4ba0-b6cf-4e3c-8114-ae2c94aa6890",
  "agent_id" : "df08ca35-552c-4e02-b922-d4f9bfbe6213",
  "action_type" : "CALL_FORWARDING",
  "call_id" : "42768ebf-7a3f-4414-9bb4-d7244ff59583",
  "metadata" : {
    "contact_data" : {
      "email" : "[email protected]",
      "name" : "Jonh",
      "timezone" : "Europe/Rome",
      "phone_number" : "+39---------"
    }
  },
  "data" : {
    "target" : "+39--------",
    "child_call_id" : "b3fa49d6-863c-49bd-8774-f65f80dad02b",
    "status" : "INITIATED"
  }
}

Data Extraction action completed example:

{
  "event" : "AGENT_ACTION_COMPLETED",
  "action_id" : "b58c4ba0-b6cf-4e3c-8114-ae2c94aa6890",
  "agent_id" : "df08ca35-552c-4e02-b922-d4f9bfbe6213",
  "action_type" : "DATA_EXTRACTION",
  "call_id" : "42768ebf-7a3f-4414-9bb4-d7244ff59583",
  "metadata" : {
    "contact_data" : {
      "email" : "[email protected]",
      "name" : "Jonh",
      "timezone" : "Europe/Rome",
      "phone_number" : "+39---------"
    }
  },
  "data" : {
    "extracted_properties" : [
      {
        "description" : "Sei soddisfatto dell'ultimo intervento di spurgo effettuato?",
        "value" : "Si"
      }
    ]
  }
}

WhatsApp Message action completed example:

{
  "event" : "AGENT_ACTION_COMPLETED",
  "action_id" : "b58c4ba0-b6cf-4e3c-8114-ae2c94aa6890",
  "agent_id" : "df08ca35-552c-4e02-b922-d4f9bfbe6213",
  "action_type" : "WHATS_APP_MESSAGE",
  "call_id" : "42768ebf-7a3f-4414-9bb4-d7244ff59583",
  "metadata" : {
    "contact_data" : {
      "email" : "[email protected]",
      "name" : "Jonh",
      "timezone" : "Europe/Rome",
      "phone_number" : "+39---------"
    }
  },
  "data" : {
    "extracted_properties" : [
      {
        "key" : "Sei soddisfatto dell'ultimo intervento di spurgo effettuato?",
        "value" : "Si"
      }
    ],
    "phone_number" : "+39...",
    "success" : true,
    "attempted_at" : "2025-03-31T10:18:47Z",
    "message_components" : [
      {
        "type" : "header",
        "format" : "text",
        "text" : "Grazie per aver visitato il nostro stand Voxloud!"
      },
      {
        "type" : "body",
        "text" : "Siamo entusiasti di aver avuto l'opportunità di conoscerti durante l'evento e di condividere con te come il nostro servizio Voxloud può portare valore alla tua attività.\uD83D\uDE4C\nPer approfondire e discutere delle tue esigenze, clicca sul pulsante qui sotto \"DEMO\" e fissa un appuntamento con uno dei nostri specialisti.\uD83D\uDCC5\nNon vediamo l'ora di sentirti!\uD83D\uDE0A"
      },
      {
        "type" : "footer",
        "text" : "Some text"
      },
      {
        "type" : "buttons",
        "buttons" : [
          {
            "type" : "url",
            "text" : "DEMO",
            "url" : "https://..."
          }
        ]
      }
    ]
  }
}

Appointment action completed example:

{
  "event" : "AGENT_ACTION_COMPLETED",
  "action_id" : "b58c4ba0-b6cf-4e3c-8114-ae2c94aa6890",
  "agent_id" : "df08ca35-552c-4e02-b922-d4f9bfbe6213",
  "action_type" : "APPOINTMENT",
  "call_id" : "42768ebf-7a3f-4414-9bb4-d7244ff59583",
  "metadata" : {
    "contact_data" : {
      "email" : "[email protected]",
      "name" : "Jonh",
      "timezone" : "Europe/Rome",
      "phone_number" : "+39---------"
    }
  },
  "data" : {
    "step" : "SCHEDULING",
    "success" : true,
    "attempted_at" : "2025-03-28T12:33:24Z",
    "event_data" : {
      "id" : "event_id",
      "url" : "https://...",
      "start" : {
        "date" : "2025-03-31",
        "time" : "15:00"
      },
      "end" : {
        "date" : "2025-03-31",
        "time" : "16:00"
      },
      "timezone" : "Europe/Rome"
    }
  }
}

Action event properties:

Property	Type	Description
event	string, [AGENT_ACTION_COMPLETED]	event type, always AGENT_ACTION_COMPLETED
action_type	string, [APPOINTMENT, CALL_FORWARDING, DATA_EXTRACTION, WHATS_APP_MESSAGE]	action type
action_id	string	unique ID of the action
call_id	string	unique ID of the call
agent_id	string	unique ID of the agent
metadata	Metadata	call metadata
data	DataExtractionResult, WhatsAppMessageResult, CallForwardingResult, AppointmentResult	result of the action, based on action type

Metadata properties:

Property	Type	Description
contact_data	ContactData	metadata of the contact, set before the call started

ContactData properties:

Property	Type	Description
email	string	email of the contact
name	string	name of the contact
timezone	string	timezone of the contact
phone_number	string	phone number of the contact in e164 format

Action specific data

DataExtractionResult properties:

Property	Type	Description
extracted_properties	array, ExtractedProperty	property extracted during conversation

ExtractedProperty:

Property	Type	Description
description	string	description of the property, set during action creation
value	string	value, set by AI during conversation

WhatsAppMessageResult properties:

Property	Type	Description
extracted_properties	array, ExtractedProperty	property extracted during conversation
phone_number	string	phone number in e164 format, that was used as a target for WA message
success	boolean	indicates if attempt was successful or not
attempted_at	string	date time of the moment send WA message attempt happened
message_components	array, MessageComponent	components of WA message

CallForwardingResult properties:

Property	Type	Description
target	string	call forwarding target phone number
child_call_id	string	unique ID of the call created during forwarding
status	string [INITIATED, FAILED]	status of the attempt

AppointmentResult properties:

Property	Type	Description
step	string, [SCHEDULING]	appointment step, always SCHEDULING
success	boolean	indicates if step was executed successfully
attempted_at	string	date time of the moment step was attempted
event_data	EventData	data of the created event

EventData:

Property	Type	Description
id	string	external event id
url	string	event URL
start	DateTime	date time of the event start
end	DateTime	date time of the event end
timezone	string	timezone of the start and end time (calendar timezone)

DateTime:

Property	Type	Description
date	string	YYYY-MM-DD
time	string	HH:MM

Call tasks

By call tasks we call specific configurable jobs which perform calls connecting telephony rule from your dashboard and provided telephony number. Robocall is a type of call task where the telephony rule is generally an IVR. Currently this API section allows you to fetch robocall configurations, start robocalls and configure webhook on robocall results.

List robocall configurations

curl -X GET -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
"https://api.romulus.live/v1/call-tasks/robocalls/configurations"

It returns paginated JSON with robocall configuration object:

{
  "id" : "93451f38-5b74-4140-b6d4-8c6ok2aa0ce5",
  "name" : "Robocall - IVR with WA",
  "success_criteria" : "call_answered",
  "retry_config" : {
    "strategy" : "dynamic_delay",
    "attempts" : [
      {
        "attempt" : 1,
        "delay_sec" : 0
      }
    ]
  },
  "dnd_config" : {
    "skip_for_first_attempt" : true,
    "ranges" : [
      {
        "from" : "21:00",
        "to" : "9:00"
      }
    ],
    "days" : [
      "sunday"
    ]
  },
  "created_at" : "2024-08-15T16:24:52.434665Z",
  "updated_at" : "2024-08-15T16:24:52.434694Z"
}

This endpoint allows to fetch robocall configurations previously created in your dashboard. Endpoint supports pagination.

HTTP Request

GET https://api.romulus.live/v1/call-tasks/robocalls/configurations

Response object

Property	Description
id	unique object identifier, used to start robocall tasks
name	human readable robocall name
success_criteria	criteria to consider call task as finalized
retry_config	section which describes robocall retry configuration
dnd_config	section which describes robocall DND (Do Not Disturb) configuration

Start robocall

This request starts robocall with given configuration ID and calling +39012345678

curl -X POST -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
-d '{"robocall_configuration_id": "93451f38-5b74-4140-b6d4-8c6ok2aa0ce5","phone_number":"+39012345678"}'
"https://api.romulus.live/v1/call-tasks/robocalls"

It returns JSON structured like this:

{
  "robocall_configuration_id" : "93451f38-5b14-4140-b6d4-8c6ee6aa0ce5",
  "phone_number" : "+39012345678"
}

It returns JSON call task object:

{
  "id" : 6158,
  "phone_number" : "+34697394631",
  "attempts" : 0,
  "success_criteria" : "call_answered",
  "retry_config" : {
    "strategy" : "dynamic_delay",
    "max_attempts" : 1,
    "attempts" : [
      {
        "attempt" : 1,
        "delay_sec" : 0
      }
    ]
  },
  "dnd_config" : {
    "skip_for_first_attempt" : true,
    "ranges" : [
      {
        "from" : "22:01",
        "to" : "8:59"
      }
    ],
    "days" : [
      "sunday"
    ]
  },
  "status" : "PENDING",
  "next_attempt_at" : "2024-08-26T13:49:28.823Z",
  "created_at" : "2024-08-26T13:49:28.825Z",
  "updated_at" : "2024-08-26T13:49:28.825Z"
}

This endpoint starts robocall task to specified phone number and using robocall configuration which ID provided in request. Generally newly created call tasks are in PENDING status with next_attempt_at execution time.

HTTP Request

POST https://api.romulus.live/v1/call-tasks/robocalls

Response object

Property	Description
id	unique call task identifier
phone_number	destination phone number
attempts	current number of attempts
success_criteria	criteria to consider call task as finalized
retry_config	section which describes robocall retry configuration
dnd_config	section which describes robocall DND (Do Not Disturb) configuration
status	call task status
next_attempt_at	next attempt execution time

Create call task webhook subscription

This request create call task webhook subscription

curl -X POST -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
-d '{"entity_type": "93451f38-5b74-4140-b6d4-8c6ok2aa0ce5","entity_type":"robocall","url":"https://your.domain.com/webhook"}'
"https://api.romulus.live/v1/call-tasks/webhook-subscriptions"

It returns JSON structured like this:

{
  "id" : "9da94929-f88f-4f9d-a5e6-3a2689b784e8",
  "entity_id" : "93451f38-5b14-4140-b6d4-8c6ee6aa0ce5",
  "entity_type" : "robocall",
  "url" : "https://your.domain.com/webhook",
  "created_at" : "2024-08-26T13:49:28.825Z",
  "updated_at" : "2024-08-26T13:49:28.825Z"
}

Call task webhook body:

{
  "robocall_id" : "12347",
  "robocall_name" : "Robocall - IVR with WA",
  "robocall_configuration_id" : "93451f38-5b14-4140-b6d4-8c6ee6aa0ce5",
  "phone_number" : "+39012345678",
  "robocall_status" : "completed",
  "attempts" : [
    {
      "duration" : 17,
      "call_status" : "answered",
      "rule_names" : [ "Office opening" ],
      "labels" : [ "Option 1" ],
      "timestamp" : "2024-08-26T13:49:28.825Z"
    }
  ]
}

This endpoint allow to create subscription to call task results webhook. It is allowed to subscribe to all robocalls or to particular ones.

HTTP Request

POST https://api.romulus.live/v1/call-tasks/webhook-subscriptions

Request object

Parameter	Required	Description
entity_id	false	robocall configuration ID if you want to receive webhooks only for particular robocall
entity_type	true	currently the value is always robocall
url	true	URL where you want the webhooks to be sent to

Response object

Property	Description
id	unique webhook subscription identifier
entity_id	robocall configuration ID if you want to receive webhooks only for particular robocall
entity_type	currently the value is always robocall
url	URL where you want the webhooks to be sent to
created_at	webhook subscription creation time
updated_at	webhook subscription last update time

List call task webhook subscriptions

curl -X GET -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
"https://api.romulus.live/v1/call-tasks/webhook-subscriptions"

It returns paginated JSON with webhook subscription object:

{
  "id" : "9da94929-f88f-4f9d-a5e6-3a2689b784e8",
  "entity_id" : "93451f38-5b14-4140-b6d4-8c6ee6aa0ce5",
  "entity_type" : "robocall",
  "url" : "https://your.domain.com/webhook",
  "created_at" : "2024-08-26T13:49:28.825Z",
  "updated_at" : "2024-08-26T13:49:28.825Z"
}

This endpoint allows to fetch webhook subscriptions present in your account. Endpoint supports pagination.

HTTP Request

GET https://api.romulus.live/v1/call-tasks/webhook-subscriptions

Delete call task webhook subscription

This request will delete call task webhook subscription with ID 9da94929-f88f-4f9d-a5e6-3a2689b784e8

curl -X DELETE -H "Content-Type: application/json" -H "Authorization: {{apiKey}}" 
"https://api.romulus.live/v1/call-tasks/webhook-subscriptions/9da94929-f88f-4f9d-a5e6-3a2689b784e8"

HTTP Request

DELETE https://api.romulus.live/v1/call-tasks/webhook-subscriptions/{webhookSubscriptionId}

Errors

The Romulus API uses the following error codes:

Error Code	Meaning
400	Bad Request -- Your request is not well-formed.
401	Unauthorized -- Your API key is wrong.
403	Forbidden -- The requested resource is not accessible with your credentials.
404	Not Found -- The specified resource could not be found.
405	Method Not Allowed -- You tried to access an endpoint with an invalid method.
406	Not Acceptable -- You requested a format that isn't JSON.
429	Too Many Requests -- You're doing too many requests! Slow down!
500	Internal Server Error -- We had a problem with our server. Try again later.
503	Service Unavailable -- We're temporarily offline for maintenance. Please try again later.