Skip to main content

Contracts API, Events & Troubleshooting

Endpoints, errors/idempotency, SSE events, search/reporting, and fast fixes.

C
Written by Catalin Fetean
Updated over 2 weeks ago

Audience: Developers, Support, Ops
​Outcomes: Working clients; reliable sync; quick incident resolution

API (endpoints)

  • POST /api/contracts/draft

  • GET /api/contracts/draft/:draftId

  • GET /api/contract-drafts

  • DELETE /api/contract-drafts/:draftId

  • POST /api/contracts/draft/:draftId/respond

  • POST /api/contracts/blockchain

Activate (curl)

curl -X POST $API_BASE/api/contracts/blockchain -b cookies.txt \ -H 'Content-Type: application/json' \ -d '{"title":"SOW","amount":150000,"currency":"USD","buyerEmail":"[email protected]"}'

Sample response

{ "contractId": 123, "contractNumber": "NXT-1723814950-k49a7d", "requiresSignature": true, "signatureRequest": { "type": "contract_creation", "requiresUserSignature": true } }

Errors, idempotency & retries

  • Errors: UNAUTHORIZED (401), FORBIDDEN (403 incl. KYC/partner link), VALIDATION_ERROR (400), NOT_FOUND (404), INTERNAL_ERROR (500)

  • Error schema:

{"code":"VALIDATION_ERROR","message":"Invalid payload","issues":[{"path":["currency"],"message":"Must be a 3-letter code"}]}

  • Provide a stable reference for idempotency; dedupe by reference/eventID

  • Retries: network/5xx ⇒ exponential backoff; 4xx ⇒ fix payload/permissions

Events, emails & SSE

  • SSE: contract.draft.created, contract.review.requested, contract.approved, contract.rejected, contract.signature.requested, contract.fully_signed

const es = new EventSource('/api/events/stream', { withCredentials: true }); ['contract.fully_signed','contract.review.requested'].forEach(n => es.addEventListener(n, e => console.log(n, JSON.parse(e.data))));

  • Email templates: contract_message, contract_change_request, contract_change_reviewed, contract_fully_signed

  • Provider webhooks: not for contract content; deposits/payments handled in Payments collection

Search, filters, tags & reporting

Filters: status, counterparty, effective date, amount range, tags
Tags: msa, nda, vip, urgent
Saved views: e.g., Pending signature > 7 days
Exports: CSV/JSON with number, counterparty, value, status

Troubleshooting & runbooks (quick map)

  • “buyerId or buyerEmail required” → Provide one (not both)

  • “Partner link required” → Admin → Partners → create/accept link

  • KYC required → Settings → Compliance; complete verification

  • Draft won’t approve → Resolve blocking changes; verify mandatory clauses

  • Signature link expired → Resend; extend deadline

  • Counterparty can’t see draft → Share for review; drafts are org-scoped

  • SSE not updating → Check connection, auth cookie, server events

Support debug checklist

  • Confirm org context

  • Capture x-correlation-id, timestamp, route

  • Inspect server logs for validation/permission errors

Did this answer your question?