REST API

The Clorvia REST API lets you automate everything in your account with plain HTTPS requests and JSON — no GraphQL needed. List, create, update and delete any of your business records, and read back the full details so you can drive your own systems.

• Base URL: https://api.clorvia.com/api/v1
• Auth: your API key in the Authorization: Bearer <key> header (or X-API-Key: <key>)
• Format: JSON request and response bodies

The API only exposes your own business data (customers, items, invoices, payments, accounting, tickets…). It never exposes another customer’s data or any internal/admin objects.

Authentication

Create an API key in Settings → APIs & Webhooks, then send it on every request:

curl https://api.clorvia.com/api/v1/parties \
  -H "Authorization: Bearer YOUR_API_KEY_TOKEN"

Requests without a valid key get 401 Unauthorized.

Subscription required

All data endpoints require an active subscription or trial. If your trial or plan has expired, every call returns:

{
  "error": "Subscription Not active",
  "subscriptionActive": false,
  "status": "expired",
  "message": "Your trial or subscription has expired. Renew your plan to continue using the API."
}

with HTTP status 402 Payment Required. Renew your plan to restore access. You can always check your status at GET /api/v1/me.

Discover your data

Your account has a set of objects (record types). List them:

curl https://api.clorvia.com/api/v1/objects \
  -H "Authorization: Bearer YOUR_API_KEY_TOKEN"

{
  "count": 21,
  "data": [
    { "nameSingular": "party",   "namePlural": "parties",  "labelPlural": "Customers & Suppliers", "endpoint": "/api/v1/parties" },
    { "nameSingular": "invoice", "namePlural": "invoices", "labelPlural": "Invoices", "endpoint": "/api/v1/invoices" },
    { "nameSingular": "item",    "namePlural": "items",    "labelPlural": "Items", "endpoint": "/api/v1/items" }
  ]
}

See the exact fields of any object:

curl https://api.clorvia.com/api/v1/objects/invoices \
  -H "Authorization: Bearer YOUR_API_KEY_TOKEN"

Each field lists its name, label, type, and whether it’s required/unique.

List records

GET /api/v1/{objectPlural}

Query parameters:

curl "https://api.clorvia.com/api/v1/invoices?limit=20&status=UNPAID" \
  -H "Authorization: Bearer YOUR_API_KEY_TOKEN"

{
  "data": [ { "id": "…", "number": "INV-2026-0042", "total": { "amountMicros": "53690000000", "currencyCode": "INR" } } ],
  "pageInfo": { "hasNextPage": true, "endCursor": "…" },
  "totalCount": 134
}

To get the next page, pass ?after=<endCursor>.

Get one record

curl https://api.clorvia.com/api/v1/invoices/{id} \
  -H "Authorization: Bearer YOUR_API_KEY_TOKEN"

Returns { "data": { …the record… } }, or 404 if it doesn’t exist.

Create a record

curl -X POST https://api.clorvia.com/api/v1/parties \
  -H "Authorization: Bearer YOUR_API_KEY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "name": "Acme Traders", "gstin": "27ABCDE1234F1Z5", "city": "Mumbai" }'

Returns 201 Created with { "data": { "id": "…", … } }.

Update a record

curl -X PATCH https://api.clorvia.com/api/v1/parties/{id} \
  -H "Authorization: Bearer YOUR_API_KEY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "city": "Pune" }'

Send only the fields you want to change.

Delete a record

curl -X DELETE https://api.clorvia.com/api/v1/parties/{id} \
  -H "Authorization: Bearer YOUR_API_KEY_TOKEN"

By default this is a soft delete (the record is moved to trash, returns deletedAt). To permanently remove it, add ?hard=true.

Bulk import

Create many records in one call:

curl -X POST https://api.clorvia.com/api/v1/parties/bulk \
  -H "Authorization: Bearer YOUR_API_KEY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{ "records": [ { "name": "Acme Traders" }, { "name": "Globex" } ] }'

Up to 500 records per request. Returns { "created": N, "data": [ … ] }.

Recurring documents

Schedule a record (e.g. a monthly invoice) to be created automatically:

curl -X POST https://api.clorvia.com/api/v1/recurring \
  -H "Authorization: Bearer YOUR_API_KEY_TOKEN" \
  -H "Content-Type: application/json" \
  -d '{
        "object": "invoices",
        "frequency": "monthly",
        "startDate": "2026-07-01",
        "data": { … the same fields you would POST to create one … }
      }'

• frequency: daily, weekly, monthly or yearly.
• startDate: when the first one is created (defaults to now).
• data: the record to create each cycle.

List schedules with GET /api/v1/recurring; remove one with DELETE /api/v1/recurring/{id}. Clorvia creates the document on each due date and advances the schedule automatically.

Field types

Most fields are plain values (text, number, true/false, dates). A few are structured:

• Money (e.g. an invoice total): { "amountMicros": "53690000000", "currencyCode": "INR" } — divide amountMicros by 1,000,000 to get rupees.
• Name: { "firstName": "...", "lastName": "..." }
• Address: { "addressStreet1": "...", "addressCity": "...", "addressState": "...", "addressPostcode": "..." }
• Links / Emails / Phones: objects with a primary… field.
• Relations to another record appear as {relation}Id (e.g. an invoice’s partyId). Set them by passing the related record’s id.

Call GET /api/v1/objects/{objectPlural} to see every field and its type.

Errors

Errors return a JSON body with an error code and a message:

Security & good practice

• Keep your API key secret; treat it like a password. Rotate/revoke it any time in Settings → APIs & Webhooks.
• Give each integration the least‑privileged role it needs (read‑only where possible).
• All requests must use HTTPS.
• Every request is strictly scoped to your workspace.

→ Next: Webhooks to get real‑time push notifications.