Writing data

Version 1 offers a small set of controlled writes. It is not full CRUD: there are no deletes, and nothing that moves money.

The key's role needs both the action permission and the matching view permission, because every write returns the same record representation as the read endpoints.

Rules that apply to every write

• Send Content-Type: application/json.
• The contract is strict. A field that is not listed for the endpoint is rejected with 422 validation_failed naming the field. Nothing is silently ignored.
• Ownership is decided by the server. Tenant, company and the owning place in the hierarchy come from your key. On create you may send the optional node (a node reference, nd_…) to place the record under a descendant of your key's node; an unreachable node returns 404. A record cannot be moved to another node by an update.
• PATCH is a partial update. Send only the fields you want to change. An empty body is 422.
• Records are addressed by public id, and a record outside your key's reach is a 404.
• Responses use the same representation as the read endpoints: { "data": { ... } }. A create returns 201 with a Location header pointing to the new record.

Create a lead

POST /crm/leads

curl -X POST "https://api.nextorex.com/api/public/v1/crm/leads" \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxx_YOUR_SECRET_HERE" \
  -H "Content-Type: application/json" \
  -H "Idempotency-Key: signup-form-8f3a1c2e-0001" \
  -d '{
    "first_name": "Ayesha",
    "last_name": "Khan",
    "email": "[email protected]",
    "phone": "+923001234567",
    "source": "Website",
    "company_name": "Example Traders"
  }'

A 201 response contains the new lead (see Reading data for the fields).

Specific conflicts: 409 duplicate_lead when a lead with that email or phone already exists in your key's part of the hierarchy, and 409 lead_locked when a lead is locked by its business flow and cannot be edited. Stage, assignee, score and status transitions cannot be changed through the API.

PATCH /crm/leads/{id} accepts the same fields except source, status and node.

Create a customer

POST /erp/customers

PATCH /erp/customers/{id} accepts name, email, phone, address, is_active. No opening balance can be set, and system-managed customer records cannot be updated.

Admit a student

POST /education/students

Admission follows the same rules as the NEXTOREx screen: the student is created together with the finance and portal records the product normally creates. A portal password is never returned. If your plan's active-student limit is exhausted the call fails with 422 resource_limit_reached and nothing is written.

PATCH /education/students/{id} accepts the profile fields (name, email, phone, address, guardian_*, is_active). Academic placement, status transitions, deletion and restoration are not available.

Get a payment link for an invoice

POST /billing/invoices/{id}/payment-link

Asks NEXTOREx for the hosted checkout URL of an invoice's remaining balance so you can send it to your customer. This call accepts no body and no query parameters: you can never supply an amount, currency, price or payment provider. NEXTOREx works those out from the invoice itself.

curl -X POST "https://api.nextorex.com/api/public/v1/billing/invoices/inv_0123456789abcdef01234567/payment-link" \
  -H "Authorization: Bearer nx_live_xxxxxxxxxxxx_YOUR_SECRET_HERE" \
  -H "Idempotency-Key: invoice-link-INV-1042-v1"

{
  "data": {
    "invoice_id": "inv_0123456789abcdef01234567",
    "url": "https://checkout.example.com/invoice/EXAMPLE-TOKEN",
    "expires_at": "2026-11-17T09:00:00+00:00"
  }
}

• It does not charge anyone and does not record a payment.
• An unexpired link is reused, so a retry never invalidates a link you have already sent.
• 409 invoice_not_payable: the invoice is not in a payable state or has nothing due.
• 409 payment_not_available: no online payment option is enabled for the invoice.

Idempotency on writes

Every POST requires an Idempotency-Key. PATCH accepts one but does not require it, because sending the same partial update twice leaves the record in the same state. See Idempotency.

Deliberately not supported in version 1

There is no delete, and no way to change or cancel a subscription, record a payment, refund, void or credit an invoice, start a checkout, write products, stock, orders, accounting entries, payroll or staff, or manage API keys and webhook endpoints with an API key. Deals, CRM contacts and stock levels have no endpoints yet. These are left out on purpose to keep version 1 safe; they are not oversights.