Create Event

POST /api/v1/events

Submits a compliance event from your system into MidLyr. Each accepted event creates (or idempotently matches) a ticket in the team’s workspace. Use this to forward customer messages, agent transcripts, dispute notices, complaints, or any signal that should land in compliance review.

Submit an Event

Request Body — text content

{
  "scenario": "complaint",
  "content": {
    "type": "text",
    "text": "Customer states that their account was charged twice for the same transaction and the first dispute was closed without explanation."
  },
  "externalRef": "case-2026-04-15-00427"
}

Request Body — JSON content

{
  "scenario": "dispute",
  "content": {
    "type": "json",
    "json": {
      "channel": "email",
      "subject": "Reg E dispute — provisional credit not applied",
      "body": "...",
      "customerId": "cust_9123"
    }
  },
  "externalRef": "case-2026-04-15-00427"
}

Fields

Name	Type	Required	Description
scenario	string	yes	One of marketing_asset, dispute, debt_collection, complaint, generic. See Scenario Enum.
content.type	string	yes	text or json. Selects the variant below.
content.text	string	conditional	Required when content.type is text. Plain-text body of the event. Min 1 character.
content.json	object	conditional	Required when content.type is json. Free-form key–value payload describing the event.
externalRef	string	no	Customer idempotency key (1–128 chars). Replays with the same value return the original ticket.

Idempotency

When externalRef is provided, the first accepted event creates a ticket and subsequent replays with the same externalRef return the same ticketId without creating a duplicate. The created flag distinguishes the two cases.

If externalRef is omitted, every call creates a new ticket.

Response

Returns 201 Created:

{
  "ticketId": "tkt_01HY3K4M7QR9VP2N8WYJF5GTB",
  "externalRef": "case-2026-04-15-00427",
  "created": true
}

Field	Type	Description
ticketId	string	The ticket id that was created or matched on idempotent replay.
externalRef	string	Echoed only when the request supplied an externalRef.
created	boolean	true when a new ticket was persisted; false on idempotent replay.

Errors

Status	Code	Meaning
400	invalid_request	Missing or malformed fields.
401	unauthorized	Missing or invalid API key.

See Errors for the shared error envelope.