nextX

API documentation

The NextX Open Platform lets partner apps / AI agents access workspace data via REST API, authenticated with OAuth2 client_credentials. Gateway: https://api.nextx.vn.

🚀 Quickstart (5 steps)Push leads with an API keyPlug into an AI agent (MCP)WebhooksAI tools

Downloads: OpenAPI · Postman · llms.txt · SDK Node · Python · Changelog

1. Overview

Each integration is an OAuth app (with a client_id + client_secret). The app represents your AI agent / service, acts on behalf of an installed workspace, and is strictly limited to the scopes that workspace consented to.

Lifecycle:

  1. You create an app in the console (pick permissions, get credentials instantly, no review).
  2. You Publish yourself: the Publish checklist runs automatically; all green means Live on the App Marketplace — no manual review.
  3. A customer workspace installs the app + consents to a set of scopes.
  4. The app exchanges client_credentials → an agent token (bound to that workspace) → calls the API.

Tokens are short-lived (1 hour), workspace-scoped, and revocable when the workspace uninstalls the app — safer than a static API key.

2. Calling the API

curl https://api.nextx.vn/api/v1/crm/contacts?page=1 \
  -H "Authorization: Bearer <ACCESS_TOKEN>"
  • Every request goes through the gateway https://api.nextx.vn with an Authorization: Bearer header.
  • Scopes are enforced at two layers. The gateway blocks about 25 routes (Office, CRM contacts, Sales…): missing → 403 with a body holding error: insufficient_scope and required (the scope needed). All other routes are checked by the service: missing → 403 with a detail like Permission required: <scope>. A missing/expired/invalid token is a 401 problem+json with errorCode: gateway.unauthorized.
  • Rate limit: 600 requests/minute per app by default → exceeding it returns 429 (read Retry-After).
  • Pagination: ?page=&pageSize= (default pageSize 20; the maximum depends on the endpoint — 1000 in general, 200 for /crm/integrations/contacts).

Apps & OAuth · Error codes · Rate limit

3. API reference (62 endpoints)

Each endpoint = 1 MCP tool = 1 scope. Click a service for details: parameters, curl example, response.

CRM

9 endpoints →

Contacts, opportunities/deals, activities — core customer data.

crm.contacts.viewcrm.contacts.createcrm.opportunities.viewcrm.opportunities.manage+2

Omnichannel chat

1 endpoints →

Send messages to conversation channels (Zalo OA, …).

comm.conversations.handle

Sales

6 endpoints →

Orders, products, stock, customers (POS/sales).

sales.orders.viewsales.products.viewsales.customers.view

Office

10 endpoints →

No-code data tables (Base/Bitable) and approval flows (Approval).

office.base.record.viewoffice.base.record.manageoffice.approval.instance.viewoffice.approval.instance.manage

HR

5 endpoints →

Attendance devices, punches and staff time history.

hrm.attendance_devices.viewhrm.attendance_raw_punches.view

DMS

7 endpoints →

Catalog, visits (check-in), daily plans, outlets, orders and routes.

dms.catalog.viewdms.checkins.viewdms.daily_plans.viewdms.outlets.view+2

Call center

7 endpoints →

Call center agents, campaigns, call/IVR flows, phone numbers, calls and queues.

call.agents.viewcall.campaigns.viewcall.call_flows.viewcall.ivr_flows.view+3

Marketing

6 endpoints →

Email campaigns, email templates, Google integrations, reports and sender profiles.

marketing.email_campaigns.viewmarketing.email_templates.viewmarketing.integrations.viewmarketing.reports.view+1

Payments

6 endpoints →

Read-only — payment intents, refunds, transactions, subscriptions and payment reports.

payment.intents.viewpayment.refunds.viewpayment.transactions.viewpayment.subscriptions.view+1

E-invoice

5 endpoints →

Read-only — e-invoices, series, summary reports and settings.

einvoice.invoices.vieweinvoice.series.vieweinvoice.reports.vieweinvoice.settings.view

4. Webhooks

Receive 33 event types in realtime via HTTP push — one webhook per service (CRM/Sales/Office…) — with a standard payload envelope signed using HMAC-SHA256 (X-NextX-Signature-256) and up to 8 delivery attempts (1 + 7 retries over ~24 hours).

contact.identifiedconversation.attribution_resolvedcontact.createdcontact.deletedcontact.updateddeal.woninvoice.cancelledinvoice.failed+25
Full webhook docs → register · payload · signature · retry

5. MCP — plug into an AI agent

Use nextx-mcp (a Model Context Protocol server) so any MCP-capable AI assistant can call NextX's 62 tools. Configure credentials once (like pasting an API key); token exchange is handled automatically.

Full MCP guide → install · per-client configuration · 62 tools

6. Create an app & Publish

Create your app yourself in My apps (sign in with a NextX account). You get the App ID + App Secret instantly — the App Secret is shown only once. Apps start in Development mode (only you can install, up to 3 workspaces); pass the automatic Publish checklist and press Publish so any customer can install. No manual review.