{
  "Protocol": "AIXE",
  "Version": "1.0",
  "ProtocolReference": {
    "ProtocolHome": "http://aixeprotocol.com/",
    "CanonicalUsageContract": "http://aixeprotocol.com/usage/?",
    "Whitepaper": "http://aixeprotocol.com/whitepaper/full-spec.html",
    "Inventor": "Gregory Oglethorpe"
  },
  "Endpoint": "/aixe/businesses/create-contact-request",
  "Method": "POST",
  "DiscoveryRequest": "GET /aixe/businesses/create-contact-request/?",
  "ContentType": "application/json; charset=utf-8",
  "AccessType": "Public",
  "Purpose": "Creates one contact request for an active Internet of Doing business and alerts the business at its configured alert email address.",
  "RequiredFields": {
    "BusinessKey": {
      "Type": "string",
      "Required": true,
      "SubmittedIn": "JSON body",
      "MaxLength": 50,
      "Description": "Public key of the active business that should receive the contact request. Obtain it from the IOD directory or the selected business manifest."
    },
    "Title": {
      "Type": "string",
      "Required": true,
      "SubmittedIn": "JSON body",
      "MaxLength": 200,
      "Description": "Short subject that identifies what the sender wants to discuss."
    },
    "ContactName": {
      "Type": "string",
      "Required": true,
      "SubmittedIn": "JSON body",
      "MaxLength": 100,
      "Description": "Name of the person submitting the request."
    },
    "ContactEmail": {
      "Type": "string",
      "Required": true,
      "SubmittedIn": "JSON body",
      "MaxLength": 254,
      "Description": "Valid email address where the business can reach the submitter and where status-change notices will be sent."
    },
    "ContactBody": {
      "Type": "string",
      "Required": true,
      "SubmittedIn": "JSON body",
      "MaxLength": 4000,
      "Description": "Complete contact message for the business."
    }
  },
  "OptionalFields": {},
  "BusinessRules": [
    "Use this public endpoint only after the human has selected the intended business and approved the complete request.",
    "The request is stored before the owner alert email is attempted. A notification failure never removes the stored request.",
    "Every new request starts with status New. The business may later change it to In Progress, Resolved, or Closed.",
    "SUCCESS means the request was stored. Inspect EmailNotificationAccepted separately; provider acceptance does not guarantee final inbox delivery.",
    "This action is not idempotent. Do not resubmit after SUCCESS because doing so creates a duplicate contact request."
  ],
  "ExampleRequest": {
    "BusinessKey": "00000000-0000-0000-0000-000000000000",
    "Title": "Question About Service Availability",
    "ContactName": "Jordan Lee",
    "ContactEmail": "jordan@example.com",
    "ContactBody": "I would like to discuss availability for next month."
  },
  "ResponseMeaning": {
    "BusinessKey": "The selected public business key.",
    "BusinessName": "Display name of the selected business.",
    "ContactRequestKey": "Public key of the stored request.",
    "EmailNotificationAccepted": "True when the business alert email was accepted for sending.",
    "Message": "Plain-language outcome guidance."
  },
  "ActionResponse": {
    "RequiredResponseFields": [
      "SuccessCode"
    ],
    "SuccessCodes": [
      "SUCCESS"
    ],
    "FailureCodes": [
      "VALIDATION_FAILED",
      "NOT_FOUND",
      "FAILED"
    ],
    "MissingOrEmptyResponse": "Treat as FAILED. Never infer success from HTTP status alone."
  },
  "Errors": [
    {
      "SuccessCode": "VALIDATION_FAILED",
      "Meaning": "A required field is missing, malformed, or longer than its declared limit.",
      "Recovery": "Correct every field identified in Errors and retry only if the human still wants to submit the request."
    },
    {
      "SuccessCode": "NOT_FOUND",
      "Meaning": "No active business matches BusinessKey.",
      "Recovery": "Obtain the current BusinessKey from the directory or selected business manifest."
    },
    {
      "SuccessCode": "FAILED",
      "Meaning": "The request could not be stored.",
      "Recovery": "Do not claim that the request exists. Report the failure and retry later only with user intent."
    }
  ]
}