Reference

API reference

Base URL https://fieldnova.in/api/v1. Every request needs Authorization: Bearer <key>. Test keys see sandbox data only; live keys see live data only.

GET

Check your key

/ping

Returns the mode (test or live) of the key you sent.

Response 200

{
  "ok": true,
  "mode": "test",
  "company_id": 12
}

Request

curl https://fieldnova.in/api/v1/ping \
  -H "Authorization: Bearer fn_test_YOUR_TEST_KEY"

Try it sandbox · test key only

Test key

POST

Get a price

/quotes

Price for each drop before booking. Uses your company rate card when one is set. Sandbox prices are simulated.

Body

Field	Type	Description
`service_id`required	integer	Parcel / delivery, ride, rental or outstation service of the zone
`service_category_id`	integer
`vehicle_type_id`required	integer
`pickup`required	object
`pickup.address`required	string	max 500 chars
`pickup.lat`required	number
`pickup.lng`required	number
`pickup.contact_name`	string
`pickup.contact_phone`	string
`drops`required	array of object	max 20 items
`drops[].address`required	string	max 500 chars
`drops[].lat`required	number
`drops[].lng`required	number
`drops[].name`	string	Recipient name
`drops[].phone`	string	Recipient phone (gets the delivery PIN by SMS)
`drops[].country_code`	string
`drops[].note`	string
`for`	object	Who the order is for (as your company settings allow)
`pay`	"wallet" \| "credit" \| "cash"
`start_time`	string	Schedule for later (India time). Omit = now.
`hourly_package_id`	integer	Rental (hourly) package
`weight`	number	kg
`description`	string
`cost_centre_id`	integer
`branch_id`	integer
`reference`	string	Your own reference (searchable) · max 60 chars

Response 200

{
  "mode": "test",
  "sandbox": true,
  "legs": [
    {
      "drop_index": 0,
      "distance_km": 2.4,
      "duration": "7 mins",
      "amount": "69.00",
      "rate_card": false
    }
  ],
  "total": "69.00",
  "rate_card": false,
  "available": "100000.00",
  "shortfall": "0.00"
}

Request

curl -X POST https://fieldnova.in/api/v1/quotes \
  -H "Authorization: Bearer fn_test_YOUR_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{
  "service_id": 1,
  "service_category_id": 1,
  "vehicle_type_id": 1,
  "pickup": {
    "address": "MG Road, Vijayawada",
    "lat": 16.5089,
    "lng": 80.6717,
    "contact_name": "Front desk",
    "contact_phone": "9876543210"
  },
  "drops": [
    {
      "address": "Benz Circle, Vijayawada",
      "lat": 16.4994,
      "lng": 80.6566,
      "name": "Ravi Kumar",
      "phone": "9123456780"
    }
  ],
  "reference": "INV-1042",
  "pay": "wallet"
}'

Try it sandbox · test key only

Test key

Body (JSON)

POST

Create an order

/orders

Books one order per drop. Several drops = linked orders sharing route_id (one pickup, many drops). Live orders are paid from your wallet / credit (or cash if allowed) and dispatched to Partners. Test orders never reach a Partner and never move money.

Parameters

Name	In	Description
`Idempotency-Key`	header	Any unique string (e.g. a UUID). Retrying with the same key returns the first answer and never books twice. Kept 24 hours.

Body

Field	Type	Description
`service_id`required	integer	Parcel / delivery, ride, rental or outstation service of the zone
`service_category_id`	integer
`vehicle_type_id`required	integer
`pickup`required	object
`pickup.address`required	string	max 500 chars
`pickup.lat`required	number
`pickup.lng`required	number
`pickup.contact_name`	string
`pickup.contact_phone`	string
`drops`required	array of object	max 20 items
`drops[].address`required	string	max 500 chars
`drops[].lat`required	number
`drops[].lng`required	number
`drops[].name`	string	Recipient name
`drops[].phone`	string	Recipient phone (gets the delivery PIN by SMS)
`drops[].country_code`	string
`drops[].note`	string
`for`	object	Who the order is for (as your company settings allow)
`pay`	"wallet" \| "credit" \| "cash"
`start_time`	string	Schedule for later (India time). Omit = now.
`hourly_package_id`	integer	Rental (hourly) package
`weight`	number	kg
`description`	string
`cost_centre_id`	integer
`branch_id`	integer
`reference`	string	Your own reference (searchable) · max 60 chars

Response 201

{
  "orders": [
    {
      "id": "string",
      "mode": "test",
      "reference": "string",
      "ride_number": "string",
      "status": "searching",
      "route_id": "string",
      "batch_id": "string",
      "amount": "69.00",
      "pay_mode": "string",
      "pickup": null,
      "drop": null,
      "recipient": {},
      "partner": {
        "name": "string",
        "phone": "string",
        "vehicle_no": "string"
      },
      "partner_location": {
        "lat": 1.5,
        "lng": 1.5,
        "at": "string"
      },
      "eta_minutes": 1,
      "eta_to": "pickup",
      "created_at": "string"
    }
  ],
  "route_id": "string",
  "total": "string"
}

Request

curl -X POST https://fieldnova.in/api/v1/orders \
  -H "Authorization: Bearer fn_test_YOUR_TEST_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "service_id": 1,
  "service_category_id": 1,
  "vehicle_type_id": 1,
  "pickup": {
    "address": "MG Road, Vijayawada",
    "lat": 16.5089,
    "lng": 80.6717,
    "contact_name": "Front desk",
    "contact_phone": "9876543210"
  },
  "drops": [
    {
      "address": "Benz Circle, Vijayawada",
      "lat": 16.4994,
      "lng": 80.6566,
      "name": "Ravi Kumar",
      "phone": "9123456780"
    }
  ],
  "reference": "INV-1042",
  "pay": "wallet"
}'

Try it sandbox · test key only

Test key

Body (JSON)

send a new Idempotency-Key

GET

List orders

/orders

Newest first. A test key lists test orders, a live key live orders.

Parameters

Name	In	Description
`status`	query	One of active, searching, accepted, arrived, started, completed, cancelled
`reference`	query	string
`batch_id`	query	string
`from`	query	string
`to`	query	string
`page`	query	integer
`per_page`	query	integer

Response 200

{
  "data": [
    {
      "id": "string",
      "mode": "test",
      "reference": "string",
      "ride_number": "string",
      "status": "searching",
      "route_id": "string",
      "batch_id": "string",
      "amount": "69.00",
      "pay_mode": "string",
      "pickup": null,
      "drop": null,
      "recipient": {},
      "partner": {
        "name": "string",
        "phone": "string",
        "vehicle_no": "string"
      },
      "partner_location": {
        "lat": 1.5,
        "lng": 1.5,
        "at": "string"
      },
      "eta_minutes": 1,
      "eta_to": "pickup",
      "created_at": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 1
}

Request

curl https://fieldnova.in/api/v1/orders \
  -H "Authorization: Bearer fn_test_YOUR_TEST_KEY"

Try it sandbox · test key only

Test key

status (query)

reference (query)

batch_id (query)

from (query)

to (query)

page (query)

per_page (query)

POST

Create many orders

/orders/batch

Up to 100 orders. Every order is checked first: any invalid order = nothing is booked (422 batch_invalid). Live: if the wallet cannot pay for the whole batch nothing is booked (422 business_wallet_low with the shortfall).

Parameters

Name	In	Description
`Idempotency-Key`	header	Any unique string (e.g. a UUID). Retrying with the same key returns the first answer and never books twice. Kept 24 hours.

Body

Field	Type	Description
`orders`required	array of object	max 100 items
`orders[].service_id`required	integer	Parcel / delivery, ride, rental or outstation service of the zone
`orders[].service_category_id`	integer
`orders[].vehicle_type_id`required	integer
`orders[].pickup`required	object
`orders[].drops`required	array of object	max 20 items
`orders[].for`	object	Who the order is for (as your company settings allow)
`orders[].pay`	"wallet" \| "credit" \| "cash"
`orders[].start_time`	string	Schedule for later (India time). Omit = now.
`orders[].hourly_package_id`	integer	Rental (hourly) package
`orders[].weight`	number	kg
`orders[].description`	string
`orders[].cost_centre_id`	integer
`orders[].branch_id`	integer
`orders[].reference`	string	Your own reference (searchable) · max 60 chars

Response 201

{
  "batch_id": "string",
  "orders": [
    {
      "id": "string",
      "mode": "test",
      "reference": "string",
      "ride_number": "string",
      "status": "searching",
      "route_id": "string",
      "batch_id": "string",
      "amount": "69.00",
      "pay_mode": "string",
      "pickup": null,
      "drop": null,
      "recipient": {},
      "partner": {
        "name": "string",
        "phone": "string",
        "vehicle_no": "string"
      },
      "partner_location": {
        "lat": 1.5,
        "lng": 1.5,
        "at": "string"
      },
      "eta_minutes": 1,
      "eta_to": "pickup",
      "created_at": "string"
    }
  ],
  "failed": [
    {
      "index": 1,
      "code": "string",
      "message": "string"
    }
  ]
}

Request

curl -X POST https://fieldnova.in/api/v1/orders/batch \
  -H "Authorization: Bearer fn_test_YOUR_TEST_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "orders": [
    {
      "service_id": 1,
      "service_category_id": 1,
      "vehicle_type_id": 1,
      "pickup": {
        "address": "MG Road, Vijayawada",
        "lat": 16.5089,
        "lng": 80.6717,
        "contact_name": "Front desk",
        "contact_phone": "9876543210"
      },
      "drops": [
        {
          "address": "Benz Circle, Vijayawada",
          "lat": 16.4994,
          "lng": 80.6566,
          "name": "Ravi Kumar",
          "phone": "9123456780"
        }
      ],
      "reference": "INV-1042",
      "pay": "wallet"
    },
    {
      "service_id": 1,
      "service_category_id": 1,
      "vehicle_type_id": 1,
      "pickup": {
        "address": "MG Road, Vijayawada",
        "lat": 16.5089,
        "lng": 80.6717,
        "contact_name": "Front desk",
        "contact_phone": "9876543210"
      },
      "drops": [
        {
          "address": "Benz Circle, Vijayawada",
          "lat": 16.4994,
          "lng": 80.6566,
          "name": "Ravi Kumar",
          "phone": "9123456780"
        }
      ],
      "reference": "INV-1043",
      "pay": "wallet"
    }
  ]
}'

Try it sandbox · test key only

Test key

Body (JSON)

send a new Idempotency-Key

GET

Order status

/orders/{id}

Status, Partner, live Partner location and ETA.

Parameters

Name	In	Description
`id`required	path	Order id from create (ord_test_... or ord_live_...)

Response 200

{
  "id": "string",
  "mode": "test",
  "reference": "string",
  "ride_number": "string",
  "status": "searching",
  "route_id": "string",
  "batch_id": "string",
  "amount": "69.00",
  "pay_mode": "string",
  "pickup": null,
  "drop": null,
  "recipient": {},
  "partner": {
    "name": "string",
    "phone": "string",
    "vehicle_no": "string"
  },
  "partner_location": {
    "lat": 1.5,
    "lng": 1.5,
    "at": "string"
  },
  "eta_minutes": 1,
  "eta_to": "pickup",
  "created_at": "string"
}

Request

curl https://fieldnova.in/api/v1/orders/ord_test_8fK2mQ9xLp3RtV7aB1cD \
  -H "Authorization: Bearer fn_test_YOUR_TEST_KEY"

Try it sandbox · test key only

Test key

id required

GET

Live Partner location + ETA

/orders/{id}/tracking

Light-weight; poll every 10-15 seconds while the order is active.

Parameters

Name	In	Description
`id`required	path	Order id from create (ord_test_... or ord_live_...)

Response 200

{
  "id": "ord_test_8fK2mQ9xLp3RtV7aB1cD",
  "status": "accepted",
  "partner": {
    "name": "Test Partner",
    "phone": "9000000000",
    "vehicle_no": "TEST 0000"
  },
  "partner_location": {
    "lat": 16.5109,
    "lng": 80.6737,
    "at": "2026-10-07T10:15:02.000Z"
  },
  "eta_minutes": 4,
  "eta_to": "pickup"
}

Request

curl https://fieldnova.in/api/v1/orders/ord_test_8fK2mQ9xLp3RtV7aB1cD/tracking \
  -H "Authorization: Bearer fn_test_YOUR_TEST_KEY"

Try it sandbox · test key only

Test key

id required

POST

Cancel an order

/orders/{id}/cancel

A cancellation fee may apply after the Partner has arrived (returned as fee).

Parameters

Name	In	Description
`id`required	path	Order id from create (ord_test_... or ord_live_...)
`Idempotency-Key`	header	Any unique string (e.g. a UUID). Retrying with the same key returns the first answer and never books twice. Kept 24 hours.

Body

Field	Type	Description
`reason`	string	max 191 chars

Response 200

{
  "id": "string",
  "status": "string",
  "fee": "0.00"
}

Request

curl -X POST https://fieldnova.in/api/v1/orders/ord_test_8fK2mQ9xLp3RtV7aB1cD/cancel \
  -H "Authorization: Bearer fn_test_YOUR_TEST_KEY" \
  -H "Idempotency-Key: $(uuidgen)" \
  -H "Content-Type: application/json" \
  -d '{
  "reason": "Customer not available"
}'

Try it sandbox · test key only

Test key

id required

Body (JSON)

send a new Idempotency-Key

POST

Move a test order one step

test keys only

/sandbox/orders/{id}/advance

Test keys only. searching -> accepted -> arrived -> started -> completed (each step also sends its webhook). Test orders also move by themselves within about 2 minutes.

Parameters

Name	In	Description
`id`required	path	Order id from create (ord_test_... or ord_live_...)

Response 200

{
  "id": "string",
  "mode": "test",
  "reference": "string",
  "ride_number": "string",
  "status": "searching",
  "route_id": "string",
  "batch_id": "string",
  "amount": "69.00",
  "pay_mode": "string",
  "pickup": null,
  "drop": null,
  "recipient": {},
  "partner": {
    "name": "string",
    "phone": "string",
    "vehicle_no": "string"
  },
  "partner_location": {
    "lat": 1.5,
    "lng": 1.5,
    "at": "string"
  },
  "eta_minutes": 1,
  "eta_to": "pickup",
  "created_at": "string"
}

Request

curl -X POST https://fieldnova.in/api/v1/sandbox/orders/ord_test_8fK2mQ9xLp3RtV7aB1cD/advance \
  -H "Authorization: Bearer fn_test_YOUR_TEST_KEY" \
  -H "Content-Type: application/json" \
  -d '{}'

Try it sandbox · test key only

Test key

id required

Body (JSON)

GET

Wallet balance

/wallet

available = balance - amounts held for orders in progress. Sandbox shows a fixed test balance.

Response 200

{
  "mode": "live",
  "balance": "25000.00",
  "held": "420.00",
  "available": "24580.00",
  "low_balance_alert": "5000.00",
  "currency": "INR"
}

Request

curl https://fieldnova.in/api/v1/wallet \
  -H "Authorization: Bearer fn_test_YOUR_TEST_KEY"

Try it sandbox · test key only

Test key

GET

Wallet statement

/wallet/statements

Every money step: top-ups, order charges, refunds, cancellation fees, adjustments.

Parameters

Name	In	Description
`month`	query	string
`page`	query	integer
`per_page`	query	integer

Response 200

{
  "data": [
    {
      "id": 1,
      "type": "topup",
      "amount": "string",
      "balance_after": "string",
      "ride_number": "string",
      "note": "string",
      "at": "string"
    }
  ],
  "total": 1,
  "page": 1,
  "per_page": 1
}

Request

curl https://fieldnova.in/api/v1/wallet/statements \
  -H "Authorization: Bearer fn_test_YOUR_TEST_KEY"

Try it sandbox · test key only

Test key

month (query)

page (query)

per_page (query)

GET

Monthly invoices

/invoices

Response 200

{
  "data": [
    {
      "month": "string",
      "orders": 1,
      "amount": "string",
      "pdf": "string"
    }
  ]
}

Request

curl https://fieldnova.in/api/v1/invoices \
  -H "Authorization: Bearer fn_test_YOUR_TEST_KEY"

Try it sandbox · test key only

Test key

GET

Download an invoice (PDF)

/invoices/{month}

Parameters

Name	In	Description
`month`required	path	string

Response 200

"(PDF file)"

Request

curl https://fieldnova.in/api/v1/invoices/2026-09 \
  -H "Authorization: Bearer fn_test_YOUR_TEST_KEY"

Try it sandbox · test key only

Test key

month required

GET

Employees

/employees

People you can book for (for.type = "employee").

Response 200

{
  "data": [
    {
      "id": 1,
      "name": "string",
      "phone": "string",
      "email": "string",
      "cost_centre_id": 1,
      "status": "string"
    }
  ]
}

Request

curl https://fieldnova.in/api/v1/employees \
  -H "Authorization: Bearer fn_test_YOUR_TEST_KEY"

Try it sandbox · test key only

Test key

GET

Cost centres

/cost-centres

Response 200

{
  "data": [
    {
      "id": 1,
      "code": "string",
      "name": "string",
      "status": 1
    }
  ]
}

Request

curl https://fieldnova.in/api/v1/cost-centres \
  -H "Authorization: Bearer fn_test_YOUR_TEST_KEY"

Try it sandbox · test key only

Test key