> ## Documentation Index
> Fetch the complete documentation index at: https://docs.nova.galaxa.in/llms.txt
> Use this file to discover all available pages before exploring further.

# REST API Reference (v1)

> Complete endpoint reference for Nova's public v1 developer API: WhatsApp messaging, contact ingestion, and GMV attribution.

# REST API Reference (v1)

Base URL for all v1 developer API endpoints:

```text theme={null}
https://nova.galaxa.in/api/v1
```

All requests must be transmitted over HTTPS and include a valid Bearer token in the `Authorization` header.

***

## 1. Send WhatsApp Notification

**POST /api/v1/whatsapp/send** `endpoint`

Dispatches a pre-approved Meta WhatsApp template or transactional notification directly to a customer's phone number.

### Required Scope

`whatsapp:send`

### Request Body

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `to` | string | Yes | Customer's phone number formatted in E.164 notation (e.g. `+919876543210` or `919876543210`). |
| `templateName` | string | Yes | Pre-approved Meta WhatsApp template name configured in your account (e.g. `order_shipped_v1`, `delhivery_out_for_delivery`). |
| `languageCode` | string | No | Two-letter ISO language code for the template (default: `en`). |
| `parameters` | array | No | Positional replacement parameters corresponding to `{{1}}`, `{{2}}`, etc. in the template body. |
| `body` | string | No | Fallback text representation of the notification. |

### Example Request

```bash theme={null}
curl -X POST https://nova.galaxa.in/api/v1/whatsapp/send \
  -H "Authorization: Bearer nova_live_9f83a4c281e05d7b3a9482f102c9381e4b82d7c01a93e84f" \
  -H "Content-Type: application/json" \
  -d '{
    "to": "+919876543210",
    "templateName": "order_shipped_v1",
    "languageCode": "en",
    "parameters": ["Aman", "#10991", "Bluedart", "BD982736192IN"]
  }'
```

### Example Response (`200 OK`)

```json theme={null}
{
  "success": true,
  "messageId": "wamid.HBgMOTE5ODc2NTQzMjEwFQIAERgSMzE1RjhDQzBGRTQ0MTg2NUJDAA==",
  "status": "sent",
  "recipient": "+919876543210",
  "timestamp": 1729868400000
}
```

***

## 2. Upsert Customer Contact

**POST /api/v1/contacts/upsert** `endpoint`

Ingests or updates customer profile metadata, acquisition channels, and custom tags from third-party CRMs or ERPs.

### Required Scope

`contacts:write`

### Request Body

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `phone` | string | Yes | Primary customer phone number formatted in E.164. |
| `name` | string | No | Full customer name. |
| `email` | string | No | Customer email address. |
| `acquisitionTouchpoint` | string | No | First-touch landing page or product URL (e.g. `/products/zeb-juke-bar-9900`). |
| `tags` | array | No | String array of segment tags (e.g. `["VIP", "Delhivery-RTO-Low", "Audio-Enthusiast"]`). |
| `customAttributes` | object | No | Key-value dictionary of external attributes (e.g. `{"loyaltyPoints": 450, "erpId": "CUST-9921"}`). |

### Example Request

```bash theme={null}
curl -X POST https://nova.galaxa.in/api/v1/contacts/upsert \
  -H "Authorization: Bearer nova_live_9f83a4c281e05d7b3a9482f102c9381e4b82d7c01a93e84f" \
  -H "Content-Type: application/json" \
  -d '{
    "phone": "+919876543210",
    "name": "Aman Sharma",
    "email": "aman.sharma@example.com",
    "acquisitionTouchpoint": "/products/zeb-juke-bar-9900",
    "tags": ["VIP-Shopper", "Home-Audio"],
    "customAttributes": {
      "loyaltyTier": "Gold",
      "preferredChannel": "whatsapp"
    }
  }'
```

### Example Response (`200 OK`)

```json theme={null}
{
  "success": true,
  "contactId": "cnt_8f93e2b10a4c",
  "phone": "+919876543210",
  "action": "upserted",
  "updatedAt": "2026-10-25T15:00:00.000Z"
}
```

***

## 3. Query Real-Time GMV Attribution

**GET /api/v1/analytics/attribution** `endpoint`

Retrieves real-time gross merchandise value (GMV), order counts, and conversion metrics attributed to Nova interactions.

### Required Scope

`analytics:read`

### Query Parameters

| Parameter | Type | Required | Description |
| :- | :- | :- | :- |
| `from` | string | No | ISO 8601 start date (e.g. `2026-10-01T00:00:00Z`). Defaults to 30 days ago. |
| `to` | string | No | ISO 8601 end date (e.g. `2026-10-25T23:59:59Z`). Defaults to current timestamp. |
| `channel` | string | No | Filter by interaction channel: `all`, `broadcast`, `conversational`, `sequences`. |

### Example Request

```bash theme={null}
curl -X GET "https://nova.galaxa.in/api/v1/analytics/attribution?from=2026-10-01T00:00:00Z&to=2026-10-25T23:59:59Z&channel=all" \
  -H "Authorization: Bearer nova_live_9f83a4c281e05d7b3a9482f102c9381e4b82d7c01a93e84f"
```

### Example Response (`200 OK`)

```json theme={null}
{
  "success": true,
  "period": {
    "from": "2026-10-01T00:00:00.000Z",
    "to": "2026-10-25T23:59:59.000Z"
  },
  "attributionWindowHours": 72,
  "totalGmvAttributed": 482500,
  "currency": "INR",
  "totalOrdersAttributed": 124,
  "averageOrderValue": 3891.13,
  "channels": {
    "broadcasts": {
      "gmv": 245000,
      "orders": 64,
      "metaMessageCost": 16420.50,
      "roas": 14.92
    },
    "conversationalAgent": {
      "gmv": 158000,
      "orders": 41
    },
    "postPurchaseSequences": {
      "gmv": 79500,
      "orders": 19
    }
  }
}
```

***

## Error Handling

Nova returns standard HTTP status codes:

| Code | Status | Meaning |
| :- | :- | :- |
| `200` | OK | The request succeeded. |
| `400` | Bad Request | Missing required parameters or invalid JSON body. |
| `401` | Unauthorized | Missing, expired, or invalid API key Bearer token. |
| `403` | Forbidden | API key lacks the required scope for this endpoint. |
| `404` | Not Found | Requested resource or endpoint does not exist. |
| `429` | Too Many Requests | Rate limit exceeded. Back off and retry. |
| `500` | Internal Server Error | An error occurred on Nova's servers. Contact support. |

All error responses return a structured JSON payload:

```json theme={null}
{
  "error": "Forbidden: Insufficient API key scope. Required: whatsapp:send",
  "code": "INSUFFICIENT_SCOPE",
  "documentation": "https://docs.nova.galaxa.in/developer/overview"
}
```


This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.