{
  "Protocol": "AIXE",
  "Version": "1.0",
  "Endpoint": "/aixe/owner/service-providers/create-provider",
  "DiscoveryRequest": "GET /aixe/owner/service-providers/create-provider/?",
  "CanonicalHelpTrigger": "GET /aixe/owner/service-providers/create-provider/?",
  "ActionRequest": "POST /aixe/owner/service-providers/create-provider",
  "Method": "POST",
  "ContentType": "application/json",
  "Title": "Create Provider",
  "AuthenticationRequired": true,
  "AccessType": "Site Administrator",
  "Purpose": "Create a provider account with name, email and password, or explicitly grant an existing account using ExistingPersonKey and its RowVersion.",
  "ThingsYouCanAsk": [
    "Help me create provider.",
    "Show me the information needed to create provider.",
    "Use this capability for my business."
  ],
  "DocumentationSource": "AIXEEndpointRegistry",
  "ProtocolReference": {
    "ProtocolHome": "http://aixeprotocol.com/",
    "CanonicalUsageContract": "http://aixeprotocol.com/usage/?",
    "Whitepaper": "http://aixeprotocol.com/whitepaper/full-spec.html",
    "Inventor": "Gregory Oglethorpe",
    "IncludeIn": [
      "/aixe.ai starter discovery documents",
      "Every endpoint self-description returned by GET /endpoint/?"
    ],
    "AIInstruction": "Read this live endpoint contract as operational guidance, not merely as a transport schema. Use its purpose, field meanings, business rules, outcomes, and recovery guidance to reason about whether and how to perform the capability."
  },
  "UsageGuidance": {
    "Role": "Read this contract and use the capability only for the human\u0027s authorized request.",
    "CorrectWorkflow": [
      "Read this contract and use the capability only for the human\u0027s authorized request.",
      "Read current public keys and record versions before changing records. Send fields in the JSON body.",
      "Read SuccessCode and the detailed outcome; a saved business action and its email outcome are separate."
    ],
    "DoNotDo": [
      "Do not send business variables, keys, filters, or action inputs in the URL or query string.",
      "Do not infer success from HTTP status alone."
    ]
  },
  "AIUsageGuidance": {
    "ContractRole": "This live document teaches an AI what the capability means and how to use it; it is not merely a list of request fields.",
    "ReasoningInstruction": "Decide whether this capability serves the human\u0027s intent from Purpose and BusinessRules, gather values using each field\u0027s Description and constraints, then interpret the returned SuccessCode before reporting an outcome.",
    "FieldInstruction": "Field names are transport labels. Their Description, source, constraints, and business meaning explain what information the AI should obtain and why."
  },
  "RequiredFields": {
    "PersonAuthenticationToken": {
      "Type": "string",
      "Description": "Temporary secret from account/login. Authorization uses the active account and its current roles; never echo or store it.",
      "Required": true,
      "SubmittedIn": "JSON body"
    }
  },
  "OptionalFields": {
    "ExistingPersonKey": {
      "Type": "string",
      "Description": "Owner-selected existing account UUID to grant provider access. Requires that account RowVersion; do not also submit new-account details.",
      "Required": false,
      "SubmittedIn": "JSON body",
      "Format": "UUID"
    },
    "RowVersion": {
      "Type": "string",
      "Description": "Opaque base64 version returned by the resource read. For order-related operations use the invoice version. Reload after CONFLICT; do not guess or replace it with a freshly fetched version without reviewing changes.",
      "Required": false,
      "SubmittedIn": "JSON body",
      "Format": "base64"
    },
    "FirstName": {
      "Type": "string",
      "Description": "Contact first name; delivery vendors allow 100 characters, accounts allow 120.",
      "Required": false,
      "SubmittedIn": "JSON body"
    },
    "LastName": {
      "Type": "string",
      "Description": "Contact last name; delivery vendors allow 100 characters, accounts allow 120.",
      "Required": false,
      "SubmittedIn": "JSON body"
    },
    "Email": {
      "Type": "string",
      "Description": "Valid unique account email, or delivery vendor email, according to the capability; at most 254 characters.",
      "Required": false,
      "SubmittedIn": "JSON body"
    },
    "Password": {
      "Type": "string",
      "Description": "Write-only password. Customer initial password is optional; administrator creation requires at least eight characters. Mail settings encrypt the SMTP password and never return it.",
      "Required": false,
      "SubmittedIn": "JSON body"
    },
    "Phone": {
      "Type": "string",
      "Description": "Ten-digit contact phone number; formatting punctuation is normalized. Vendor phone may be blank.",
      "Required": false,
      "SubmittedIn": "JSON body"
    }
  },
  "BusinessRules": [
    "Submit the business inputs for the intended action and inspect its returned SuccessCode.",
    "Only active authorized accounts may use protected capabilities. Customer order queries are restricted to the authenticated customer\u0027s orders before filtering. Internal notes, staff activity and vendor details are owner-only.",
    "Dates and text filters can be supplied independently or together. Searches expose all matches through continuation; there is no silent first-50 or first-200 cutoff.",
    "Customer selection is empty without Search or explicit ListAll. The configured customer result limit is disclosed as AppliedLimit.",
    "Payment amounts, identity and invoice relationships are permanent. No payment deletion exists. Update-payment-details accepts only date, method, reference and note in addition to its keys and versions. Negative entries require a note and cannot exceed net collected. Overpayments are retained as credit.",
    "The status endpoint sets any supported status, including backward moves and reopening. Pickup/delivery compatibility applies. It sends no email and does not claim the checklist is complete. Finalize-order requires every current line packed and commits readiness before its immediate email attempt.",
    "Email is attempted immediately with a bounded SMTP timeout. Failed sends log a NOC and stop. No queue, delivery worker or automatic retry exists. A mail failure never reverses a saved order, payment or vendor assignment. Explicit resend-request is a new intentional send.",
    "Customer deletion removes access and preserves invoice history. Referenced vendors must be deactivated. Administrators cannot remove themselves or the last active administrator. Passwords and SMTP secrets are never returned.",
    "Editing a submitted record requires its returned RowVersion. Stale edits fail and must be reviewed before submitting a new request. Unsupported fields are rejected rather than silently accepted."
  ],
  "ResponseFields": {
    "SuccessCode": {
      "Type": "string",
      "Description": "SUCCESS confirms the read or committed business action. Check email acceptance separately. A failed email-only action returns EMAIL_NOT_SENT. HTTP status alone does not establish success.",
      "Required": true,
      "SubmittedIn": "Response body"
    },
    "Item": {
      "Type": "object",
      "Description": "Service occurrence with InvoiceItemKey, InvoiceKey, invoice number, product, customer contact, service address/instructions, UTC start, duration, status, provider key/name, ItemRowVersion, StatusCatalog and AllowedActions. No prices, private notes or secrets in provider responses.",
      "Required": true,
      "SubmittedIn": "Response body"
    },
    "Provider": {
      "Type": "object",
      "Description": "Safe provider contact details, IsActive provider-role state, AccountIsActive, outstanding count, RowVersion and AllowedActions. No authentication or password data.",
      "Required": true,
      "SubmittedIn": "Response body"
    },
    "Items": {
      "Type": "array",
      "Description": "Matching service occurrences for list-items.",
      "Required": true,
      "SubmittedIn": "Response body"
    },
    "Providers": {
      "Type": "array",
      "Description": "Matching providers for list-providers.",
      "Required": true,
      "SubmittedIn": "Response body"
    },
    "Times": {
      "Type": "array",
      "Description": "Available ServiceStartUtc, ServiceEndUtc, LocalStart, TimeZoneId values. No hold is created.",
      "Required": true,
      "SubmittedIn": "Response body"
    },
    "Options": {
      "Type": "object",
      "Description": "TimeZoneId, SlotMinutes and HorizonDays.",
      "Required": true,
      "SubmittedIn": "Response body"
    },
    "TotalMatches": {
      "Type": "integer",
      "Description": "All matches before pagination.",
      "Required": true,
      "SubmittedIn": "Response body"
    },
    "NextCursor": {
      "Type": "string",
      "Description": "Continuation offset for identical filters, null when complete.",
      "Required": true,
      "SubmittedIn": "Response body"
    },
    "HasMore": {
      "Type": "boolean",
      "Description": "Whether more matches exist.",
      "Required": true,
      "SubmittedIn": "Response body"
    },
    "ReturnedCount": {
      "Type": "integer",
      "Description": "Rows in this response.",
      "Required": true,
      "SubmittedIn": "Response body"
    },
    "UnscheduledCount": {
      "Type": "integer",
      "Description": "Undated service count for the text/invoice/provider scope, before date/status filters.",
      "Required": true,
      "SubmittedIn": "Response body"
    },
    "PartiallyScheduledCount": {
      "Type": "integer",
      "Description": "Invoices with both unscheduled and scheduled/progress/completed services.",
      "Required": true,
      "SubmittedIn": "Response body"
    },
    "StatusCatalog": {
      "Type": "array",
      "Description": "Every service status code and description.",
      "Required": true,
      "SubmittedIn": "Response body"
    },
    "AccessRemoved": {
      "Type": "boolean",
      "Description": "Provider access was removed, preserving person and history.",
      "Required": true,
      "SubmittedIn": "Response body"
    },
    "CustomerEmailAccepted": {
      "Type": "boolean",
      "Description": "Null when not requested; true only when SMTP accepted the immediate attempt.",
      "Required": true,
      "SubmittedIn": "Response body"
    },
    "ProviderEmailAccepted": {
      "Type": "boolean",
      "Description": "Null when not requested; true only when SMTP accepted the immediate attempt.",
      "Required": true,
      "SubmittedIn": "Response body"
    }
  },
  "Errors": [
    {
      "SuccessCode": "VALIDATION_FAILED",
      "Meaning": "One or more required request values are missing or malformed.",
      "Recovery": "Use the field descriptions and constraints in this contract, correct the named fields, and retry the same capability.",
      "Recoverable": true
    },
    {
      "SuccessCode": "UNAUTHORIZED",
      "Meaning": "The submitted identity or token does not authorize this capability or record scope.",
      "Recovery": "Use the correct active authentication token and confirm the required account role.",
      "Recoverable": true
    },
    {
      "SuccessCode": "NOT_FOUND",
      "Meaning": "A submitted public key did not identify a record within this capability\u0027s declared scope.",
      "Recovery": "Re-check the key against a current list or creation response; do not treat this as a missing web route.",
      "Recoverable": true
    },
    {
      "SuccessCode": "CONFLICT",
      "Meaning": "The capability could not complete for an execution failure.",
      "Recovery": "Read the returned message and error detail. Retry only when the response identifies a recoverable condition.",
      "Recoverable": false
    },
    {
      "SuccessCode": "EMAIL_NOT_SENT",
      "Meaning": "The capability could not complete for an execution failure.",
      "Recovery": "Read the returned message and error detail. Retry only when the response identifies a recoverable condition.",
      "Recoverable": false
    },
    {
      "SuccessCode": "FAILED",
      "Meaning": "The capability could not complete for an execution failure.",
      "Recovery": "Read the returned message and error detail. Retry only when the response identifies a recoverable condition.",
      "Recoverable": false
    }
  ],
  "ActionResponse": {
    "RequiredResponseFields": [
      "SuccessCode"
    ],
    "SuccessCodes": [
      "SUCCESS"
    ],
    "FailureCodes": [
      "VALIDATION_FAILED",
      "UNAUTHORIZED",
      "NOT_FOUND",
      "CONFLICT",
      "EMAIL_NOT_SENT",
      "FAILED"
    ],
    "NonFinalCodes": [],
    "MissingOrEmptyResponse": "Treat as FAILED.",
    "Rule": "The endpoint response is authoritative. Only an exact SuccessCode value listed in SuccessCodes means the business action succeeded; HTTP status alone does not declare the AIXE outcome."
  },
  "ServiceStatusCatalog": [
    {
      "Code": "Unscheduled",
      "Description": "Needs a service time and provider; the address or provider may already be selected."
    },
    {
      "Code": "Scheduled",
      "Description": "Time, provider and service address are confirmed. This time is reserved."
    },
    {
      "Code": "In Progress",
      "Description": "The provider is performing the service. This time remains reserved."
    },
    {
      "Code": "Completed",
      "Description": "The service is finished; its appointment details remain in the history."
    },
    {
      "Code": "Cancelled",
      "Description": "This service is cancelled and its reservation released. Invoice status and payments are unchanged."
    }
  ],
  "SchedulingRules": "Authenticate using PersonAuthenticationToken. Owners have Administrator or Site Administrator roles; providers must have Service Provider role and their identity is derived from the token. Provider callers cannot submit owner-only fields. Customer self-booking is unavailable. ClearSchedule removes the time and sets Unscheduled; ClearProvider also removes the provider. Reject conflicting clear and set fields. RequiresScheduling lines have quantity one. All time values use UTC Z; available slots include the scheduling time zone. Date searches omit undated work; use QueueState Unscheduled without dates for that queue. Provider status changes are limited to Scheduled/In Progress -\u003E Scheduled/In Progress/Completed. Failed immediate email logs NOC; no queue or retry. Status-only changes do not notify unless the owner explicitly asks."
}