Business API · v1

Nuvex Nova API Documentation

Programmatically create service tasks, track their status, and receive real-time webhooks — built for property managers, facilities teams, and enterprise platforms.

Request API Access Enterprise Overview

Getting Started

Apply for a business account from the contact page. Once ops-approved with an active API subscription, generate API keys from your Business Hub. All requests are JSON over HTTPS.

Access requirements: API keys are hidden unless you have an active, ops-approved subscription. Webhooks are locked behind the same gate. Live key management stays in your Business Hub — this page is documentation only and never exposes real keys.

Base URL

text

https://staging.nuvexnova.com/functions

Authentication

Authenticate every request with your API key in the Authorization header. Keys are shown once at creation — store them securely and never expose them in client-side code. Revoke and rotate keys anytime from your Business Hub.

http

Authorization: Bearer nvx_live_xxxxxxxxxxxxxxxx

Rate Limits

Limits apply per key, per minute, based on your plan. Exceeding them returns 429.

Plan	Requests / minute
Starter	60
Professional	300
Enterprise	1000

Sandbox Mode

Generate a sandbox key to test your integration safely. Sandbox requests are fully validated and return realistic responses, but never create real tasks, dispatch taskers, or count against your quota. Sandbox responses include "sandbox": true.

Endpoints

POST/apiTasks

Create a new task request. The task enters ops review, gets priced, and is dispatched to a verified tasker. Sandbox keys simulate the request without creating a real task.

titlestringRequired

Short title of the work needed

servicestringRequired

Service key from GET /apiServices, e.g. "Plumber"

addressstring

Full service address (required unless business_address_id is set)

business_address_idstring

ID of a saved address from your Business Hub

descriptionstring

Details of the work

prioritystring

low | medium | high | urgent (default: medium)

scheduled_datestring

Preferred ISO 8601 date-time

Parameter	Type	Required	Description
`title`	string	Yes	Short title of the work needed
`service`	string	Yes	Service key from GET /apiServices, e.g. "Plumber"
`address`	string	No	Full service address (required unless business_address_id is set)
`business_address_id`	string	No	ID of a saved address from your Business Hub
`description`	string	No	Details of the work
`priority`	string	No	low \| medium \| high \| urgent (default: medium)
`scheduled_date`	string	No	Preferred ISO 8601 date-time

Example request

bash

curl -X POST https://staging.nuvexnova.com/functions/apiTasks \
  -H "Authorization: Bearer nvx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "title": "Fix leaking kitchen faucet",
    "service": "Plumber",
    "address": "123 Main St, Boston, MA 02108",
    "priority": "high"
  }'

Example response

json

{
  "task": {
    "id": "665f1c...",
    "title": "Fix leaking kitchen faucet",
    "service": "Plumber",
    "status": "ops_review",
    "priority": "high",
    "created_at": "2026-07-05T14:03:00Z"
  },
  "quota": { "used": 13, "included": 50, "overage": false }
}

GET/apiTasks

List your tasks, newest first. Pass ?id= to fetch a single task, or ?status= to filter by lifecycle status.

idstring

Fetch one task by ID

statusstring

Filter by status, e.g. in_progress

limitnumber

Max results, up to 100 (default 50)

Parameter	Type	Required	Description
`id`	string	No	Fetch one task by ID
`status`	string	No	Filter by status, e.g. in_progress
`limit`	number	No	Max results, up to 100 (default 50)

Example request

bash

curl "https://staging.nuvexnova.com/functions/apiTasks?status=in_progress&limit=20" \
  -H "Authorization: Bearer nvx_live_..."

Example response

json

{
  "tasks": [
    {
      "id": "665f1c...",
      "title": "Fix leaking kitchen faucet",
      "service": "Plumber",
      "status": "in_progress",
      "price_estimate": 245.00,
      "created_at": "2026-07-05T14:03:00Z"
    }
  ],
  "count": 1
}

GET/apiServices

The catalog of bookable service categories and their pricing model. Use the service key when creating tasks.

Example request

bash

curl https://staging.nuvexnova.com/functions/apiServices \
  -H "Authorization: Bearer nvx_live_..."

Example response

json

{
  "services": [
    {
      "key": "Plumber",
      "category": "licensed_trade",
      "description": "Plumbing repairs, fixtures, leaks...",
      "pricing": "hourly"
    }
  ],
  "count": 14
}

GET/apiInvoices

List invoices and receipts for your completed tasks, newest first.

limitnumber

Max results, up to 100 (default 50)

Parameter	Type	Required	Description
`limit`	number	No	Max results, up to 100 (default 50)

Example request

bash

curl https://staging.nuvexnova.com/functions/apiInvoices \
  -H "Authorization: Bearer nvx_live_..."

Example response

json

{
  "invoices": [
    {
      "id": "664a9b...",
      "task_id": "665f1c...",
      "amount": 245.00,
      "status": "paid",
      "created_at": "2026-07-01T10:00:00Z"
    }
  ],
  "count": 1
}

GET/apiSubscription

Get your current API subscription status, tier, quota usage, and billing cycle. Returns 403 if no active subscription exists — keys are hidden until a subscription is active and ops-approved.

Example request

bash

curl https://staging.nuvexnova.com/functions/apiSubscription \
  -H "Authorization: Bearer nvx_live_..."

Example response

json

{
  "subscription": {
    "tier": "professional",
    "status": "active",
    "quota": { "used": 42, "included": 250, "overage": false },
    "cycle_start": "2026-09-01",
    "next_billing_date": "2026-10-01"
  }
}

POST/apiSubscription

Upgrade your API tier or cancel your subscription. Upgrades take effect immediately and are prorated. Cancellations stop the next billing cycle — existing quota remains usable until the cycle ends.

actionstringRequired

upgrade or cancel

tierstring

Target tier for upgrades: starter | professional | enterprise

Parameter	Type	Required	Description
`action`	string	Yes	upgrade or cancel
`tier`	string	No	Target tier for upgrades: starter \| professional \| enterprise

Example request

bash

curl -X POST https://staging.nuvexnova.com/functions/apiSubscription \
  -H "Authorization: Bearer nvx_live_..." \
  -H "Content-Type: application/json" \
  -d '{
    "action": "upgrade",
    "tier": "professional"
  }'

Example response

json

{
  "subscription": {
    "tier": "professional",
    "status": "active",
    "quota": { "used": 42, "included": 250, "overage": false },
    "next_billing_date": "2026-10-01"
  }
}

Code Examples

JavaScript (fetch) examples for the two most common operations — task creation and status lookup.

Create a task

javascript

// Create a task — JavaScript (fetch)
const response = await fetch("https://staging.nuvexnova.com/functions/apiTasks", {
  method: "POST",
  headers: {
    "Authorization": "Bearer nvx_live_...",
    "Content-Type": "application/json",
  },
  body: JSON.stringify({
    title: "Fix leaking kitchen faucet",
    service: "Plumber",
    address: "123 Main St, Boston, MA 02108",
    priority: "high",
  }),
});
const data = await response.json();
console.log(data.task.id);

Get task status

javascript

// Get task status — JavaScript (fetch)
const taskId = "665f1c...";
const response = await fetch(
  "https://staging.nuvexnova.com/functions/apiTasks?id=" + taskId,
  { headers: { "Authorization": "Bearer nvx_live_..." } }
);
const data = await response.json();
console.log(data.task.status);

Webhooks

Register a webhook URL in your Business Hub to receive task lifecycle events as POST requests. Each delivery includes an X-Nuvex-Signature header — the HMAC-SHA256 hex digest of the raw body using your signing secret — and an X-Nuvex-Event header with the event name.

Event	Fires when
`task.created`	A task was created through the API
`task.scheduled`	A tasker was assigned to the task
`task.started`	The tasker checked in and began work
`task.completed`	The work was approved and completed
`task.cancelled`	The task was cancelled or expired

Example payload

json

{
  "event": "task.completed",
  "task_id": "665f1c...",
  "status": "approved",
  "title": "Fix leaking kitchen faucet",
  "service": "Plumber",
  "timestamp": "2026-07-05T18:22:00Z"
}

Errors

Errors return a JSON body with an error message and standard HTTP status codes:

Status	Meaning
401	Missing, invalid, or revoked API key
403	Business account is pending, rejected, or suspended
404	Resource not found
405	HTTP method not supported on this endpoint
422	Validation failed — see the details array in the response
429	Rate limit exceeded — slow down and retry
500	Something went wrong on our side

Plans

Starter

$99/mo

50 tasks / month included
60 requests / minute
$5/task overage

Professional

$299/mo

250 tasks / month included
300 requests / minute
$4/task overage

Enterprise

1000 tasks / month included
1000 requests / minute

Ready to integrate?

Apply for a business account and get your API keys within one business day.

Request API Access