> ## Documentation Index
> Fetch the complete documentation index at: https://omniloy.mintlify.site/llms.txt
> Use this file to discover all available pages before exploring further.

# 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.

```bash theme={null}
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:

```bash theme={null}
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:

```json theme={null}
{
  "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`.

```bash theme={null}
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.

```bash theme={null}
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": "+34612345678",
    "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:

```json theme={null}
{
  "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.