Writing data

Write endpoints accept the same bearer token used for reads. They delegate to the same domain services that power the organizer UI, so business rules (validation, side effects, idempotency) apply uniformly. There is no separate "API mode." The public write surface is currently intentionally narrow: use it for resources listed with write methods in the API reference, and keep multi-step workflows on their dedicated organizer, participant, exhibitor, or MCP surfaces.

Naming the tenant in the body

Writes require you to explicitly name the clientCode (and usually eventCode) in the request body. The server checks both against your token's scope before any service code runs — out-of-scope values return 403 without revealing which one was wrong.

POST /api/v1/companies
Authorization: Bearer jdo_xxx
Content-Type: application/json

{
  "clientCode": "acme",
  "eventCode": "acme-2026",
  "name": "Acme Corp",
  "boothNumber": "B-104"
}

Idempotency for financial documents

Orders, payments, refunds, and credit memos carry a required idempotencyKey field that's unique-indexed per client. Send the same key on retry to make duplicate requests resolve to the same document.

• Derive the key from the logical operation, not a random UUID — a random key defeats deduplication on retry.
• Example: order_init_{groupId} for an order create.
• Keys are URL-safe tokens, 8–128 characters. [A-Za-z0-9_-] only.

Optimistic concurrency (409 Conflict)

Aggregates with concurrent writers carry a revision counter that increments on each successful write. If your update races another write, the server returns 409 Conflict: re-fetch the entity, reapply your change to the latest state, and retry. 409 means "your client-side copy is stale," not "user error."

What's writable today

See the API reference for the authoritative list — entities with POST / PATCH / DELETE methods listed have write support. The current /v1 write surface includes Companies (exhibitors) and Attendance records. Most other resources are read-only because their writes trigger workflow-specific side effects such as payments, emails, approvals, invite materialization, participant sessions, or sourcing/contract state transitions.

Soft delete vs hard delete

DELETE archives the entity by setting lifecycle.deletedAt — it is not gone, just hidden from default listings. Audit trails remain intact. Hard deletion is reserved for GDPR-erasure workflows and is not exposed through this API.

Responses & PII

Create and update endpoints return the resulting entity. DELETE returns 204 No Content. PII redaction follows the same rules as reads — see PII & scope for the categories that are stripped when your account doesn't have PII access.