APIs: Outbound Calls

Real MarIA Core contracts for outbound questionnaire campaigns

This page documents the MarIA Core endpoints used for outbound call campaigns with questionnaires.

Authentication

All endpoints require X-Api-Key. In the interactive reference, replace your-prod-endpoint with the real host before trying a request.

curl -X GET "https://{your-prod-endpoint}/api/v1/questionnaires" \
  -H "accept: application/json" \
  -H "X-Api-Key: <your-api-key>"

Questionnaires

Method	Route	Usage
GET	/api/v1/questionnaires	List questionnaires. Accepts `?status=draft	active	archived`.
POST	/api/v1/questionnaires	Create a questionnaire.
GET	/api/v1/questionnaires/{id}	Get a questionnaire by UUID.
PUT	/api/v1/questionnaires/{id}	Update title, questions, webhooks, scheduling, or metadata.
DELETE	/api/v1/questionnaires/{id}	Delete the questionnaire. Returns 204 with no body.
GET	/api/v1/questionnaires/external/{externalId}	Get a questionnaire by external identifier.

Create example:

curl -X POST "https://{your-prod-endpoint}/api/v1/questionnaires" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your-api-key>" \
  -d '{
    "title": { "en": "Post-visit follow up" },
    "defaultLanguage": "en",
    "externalId": "post-visit-2026",
    "questions": [
      {
        "questionText": { "en": "How are you feeling today?" },
        "questionType": "text",
        "isRequired": true,
        "displayOrder": 1,
        "metadata": {}
      }
    ]
  }'

Abbreviated 201 response:

{
  "success": true,
  "data": {
    "id": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "post-visit-2026",
    "title": { "en": "Post-visit follow up" },
    "defaultLanguage": "en",
    "status": "draft",
    "version": 1,
    "questions": [
      {
        "id": "770e8400-e29b-41d4-a716-446655440000",
        "questionnaireId": "550e8400-e29b-41d4-a716-446655440000",
        "questionText": { "en": "How are you feeling today?" },
        "questionType": "text",
        "isRequired": true,
        "displayOrder": 1,
        "metadata": {}
      }
    ]
  }
}

Webhooks

Method	Route	Usage
GET	/api/v1/webhooks	List configured webhooks.
POST	/api/v1/webhooks	Create a webhook.
PUT	/api/v1/webhooks/{webhookId}	Update a webhook.
DELETE	/api/v1/webhooks/{webhookId}	Delete a webhook. Returns 204 with no body.

Valid types: generic, whatsapp_incoming, whatsapp_status, voice_incoming, voice_status, questionnaire_completion, voice_shutdown, voice_tool_call.

curl -X POST "https://{your-prod-endpoint}/api/v1/webhooks" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your-api-key>" \
  -d '{
    "name": "Outbound results",
    "url": "https://your-backend.com/webhooks/maria",
    "webhookType": "questionnaire_completion",
    "auth": { "type": "bearer", "token": "<token>" },
    "params": { "timeout": 30 }
  }'

The response returns success: true and the webhook in data; when auth.token is present, it is masked as ***.

Outbound Calls

To create a call tied to an external questionnaire, use POST /api/v1/calls/external-questionnaire. Use schedulingWindow when you need to constrain the date or time.

curl -X POST "https://{your-prod-endpoint}/api/v1/calls/external-questionnaire" \
  -H "Content-Type: application/json" \
  -H "X-Api-Key: <your-api-key>" \
  -d '{
    "name": "Ana",
    "surname1": "Garcia",
    "phone": "[phone]",
    "questionnaireId": "550e8400-e29b-41d4-a716-446655440000",
    "externalId": "case-123",
    "schedulingWindow": {
      "date": "2026-05-12",
      "startTime": "10:00",
      "endTime": "12:00"
    },
    "metadata": { "source": "ehr" }
  }'

Abbreviated 201 response:

{
  "success": true,
  "data": {
    "callId": "660e8400-e29b-41d4-a716-446655440000",
    "call": {
      "id": "660e8400-e29b-41d4-a716-446655440000",
      "callDirection": "outbound",
      "status": "pending",
      "schedulingWindow": {
        "date": "2026-05-12",
        "startTime": "10:00",
        "endTime": "12:00"
      }
    }
  }
}

Reading Calls

For external integrations, use the read routes:

Method	Route	Usage
GET	/api/v1/calls?page=1&limit=100	List paginated calls.
GET	/api/v1/calls/{id}	Get one call by ID.

The list response returns success, data, and pagination. The detail response returns success and data.call. Calls include id, endUserId, questionnaireInstanceId, callDirection, status, timestamps, schedulingWindow, transcription, events, and result fields when available.