> For clean Markdown of any page, append .md to the page URL.
> For a complete documentation index, see https://docs.feryrides.co.in/llms.txt.
> For AI client integration (Claude Code, Cursor, etc.), connect to the MCP server at https://docs.feryrides.co.in/_mcp/server.

# Endpoints

> DMRC-facing Fery API endpoints

# Endpoints

All endpoints require:

```http
x-api-key: <API_KEY>
Content-Type: application/json
```

Base URL (UAT): `https://uat.feryrides.co.in/dmrc`

Use the **API Reference** for full schemas. This page summarizes each endpoint.

---

## Health check

`GET /health`

Returns service status, dependency checks, and the list of available APIs.

### Headers

```http
x-api-key: <API_KEY>
```

### Response `200`

```json
{
  "statusCode": 200,
  "data": {
    "service": "operational",
    "environment": "production",
    "timestamp": "2026-08-31T06:44:00.000Z",
    "dependencies": {
      "mongodb": "connected",
      "firestore": "connected",
      "sqs": "configured"
    },
    "apis": [
      {
        "method": "GET",
        "path": "/health",
        "description": "Service and API status check",
        "status": "active"
      },
      {
        "method": "POST",
        "path": "/ride/fare-estimate",
        "description": "Fare estimate",
        "status": "active"
      }
    ]
  },
  "message": "All systems operational.",
  "success": true
}
```

---

## Fare estimate

`POST /ride/fare-estimate`

Returns trip distance, duration, and fare quotes.

### Request body

```json
{
  "pickupLocation": {
    "lat": 28.459119,
    "lng": 77.072912,
    "address": "Metro Station Exit A"
  },
  "dropLocation": {
    "lat": 28.475482,
    "lng": 77.088265,
    "address": "Destination"
  }
}
```

| Field                    | Required | Description                                                                         |
| ------------------------ | -------- | ----------------------------------------------------------------------------------- |
| `pickupLocation.lat`     | yes      | Latitude                                                                            |
| `pickupLocation.lng`     | yes      | Longitude                                                                           |
| `pickupLocation.address` | no       | Address text                                                                        |
| `dropLocation.lat`       | yes      | Latitude                                                                            |
| `dropLocation.lng`       | yes      | Longitude                                                                           |
| `dropLocation.address`   | no       | Address text                                                                        |
| `serviceType`            | no       | `scooty`, `cab`, or an array of those values. If omitted, both quotes are returned. |

### Response `200`

| Field                       | Description                               |
| --------------------------- | ----------------------------------------- |
| `data.requestId`            | Fare estimate id                          |
| `data.rideTime`             | Estimated trip duration                   |
| `data.timeUnit`             | Always `minute`                           |
| `data.rideDistance`         | Estimated trip distance                   |
| `data.distanceUnit`         | Always `km`                               |
| `data.quotes[]`             | Fare quote(s)                             |
| `data.quotes[].serviceType` | `scooty` or `cab`                         |
| `data.quotes[].totalAmount` | Total fare                                |
| `data.quotes[].eta`         | Estimated partner arrival time in minutes |
| `data.quotes[].fareBreakup` | Fare breakup details                      |

---

## Create order

`POST /ride/create-order`

Creates a ride. Rider details must be sent in this request. Fery creates or updates the rider from the `user` object.

### Request body

```json
{
  "user": {
    "mobile": "9999999999",
    "firstName": "Asha",
    "lastName": "Sharma",
    "gender": "female"
  },
  "pickupLocation": {
    "lat": 28.459119,
    "lng": 77.072912,
    "address": "Metro Station Exit A"
  },
  "dropLocation": {
    "lat": 28.475482,
    "lng": 77.088265,
    "address": "Destination"
  },
  "serviceType": "scooty",
  "paymentMode": "Cash",
  "pickupOtp": "1234",
  "webhookURL": "https://your-domain.com/fery/updates",
  "metadata": {
    "partnerOrderId": "DMRC-ORDER-1001"
  }
}
```

| Field            | Required | Description                                                |
| ---------------- | -------- | ---------------------------------------------------------- |
| `user.mobile`    | yes      | 10-digit mobile number                                     |
| `user.firstName` | yes      | First name                                                 |
| `user.lastName`  | yes      | Last name                                                  |
| `user.gender`    | no       | Rider gender                                               |
| `pickupLocation` | yes      | Same location shape as fare estimate                       |
| `dropLocation`   | yes      | Same location shape as fare estimate                       |
| `serviceType`    | no       | `scooty` (default) or `cab`                                |
| `paymentMode`    | no       | Cash only for now. Defaults to `Cash` if omitted           |
| `pickupOtp`      | no       | 4-digit OTP. If omitted, Fery generates one and returns it |
| `webhookURL`     | yes      | HTTPS URL for status and location webhooks                 |
| `metadata`       | no       | Your reference data. Echoed in webhooks when present       |
| `couponCode`     | no       | Coupon code, if applicable                                 |

### Response `201`

```json
{
  "statusCode": 201,
  "data": {
    "orderId": "1717235676225158",
    "requestId": "1717235676225158",
    "status": "notStarted",
    "otp": "1234",
    "price": 52,
    "serviceType": "scooty",
    "code": "RIDE_CREATED"
  },
  "message": "Ride order created successfully.",
  "success": true
}
```

### Response `200` — active ride already exists

If the rider already has an active ride, Fery returns the existing order with `code: USER_HAVE_ACTIVE_RIDE`.

---

## Cancel order

`POST /ride/cancel`

Cancels an active ride. Fery also sends webhook status `customer_cancelled` to your saved `webhookURL`.

### Request body

```json
{
  "orderId": "1717235676225158",
  "cancelReason": "Customer changed plans"
}
```

| Field          | Required | Description                                              |
| -------------- | -------- | -------------------------------------------------------- |
| `orderId`      | yes      | Order id from create order. `requestId` is also accepted |
| `cancelReason` | no       | Cancellation reason. `reason` is also accepted           |

### Response `200`

`code: RIDE_CANCELLED`

---

## Feedback

`POST /ride/feedback`

Optional endpoint to submit feedback after a completed ride.

### Request body

```json
{
  "orderId": "1717235676225158",
  "rating": 5,
  "feedback": "Smooth ride, on time"
}
```

| Field      | Required | Description                            |
| ---------- | -------- | -------------------------------------- |
| `orderId`  | yes      | Order id. `requestId` is also accepted |
| `rating`   | yes      | Integer from 1 to 5                    |
| `feedback` | yes      | Feedback text                          |

### Response `200`

`code: FEEDBACK_SUBMITTED`