# Admissions Concierge Operator API

Admissions Concierge Operator API is the protected sales-workflow surface for the paid consultation product.

## Public schema

- /api/admissions-concierge/operator-openapi: OpenAPI 3.1 schema for assistant integration

## Protected endpoints

These endpoints require Authorization Bearer credentials:

- GET /api/admissions-concierge/operator-leads
- POST /api/admissions-concierge/operator-actions
- POST /api/commercial/operator-send-buyer-reply
- POST /api/commercial/operator-send-follow-up
- GET /api/commercial/operator-inbound-replies
- POST /api/commercial/operator-reply-intake-record
- POST /api/commercial/operator-payment-evidence-record
- POST /api/commercial/operator-payment-evidence-import

## Assistant workflow

The assistant should:

1. Fetch operator leads.
2. Use nextOperatorAction to choose the next reply.
3. Build the shared commercial queue itemId as admissions_concierge:{leadId}.
4. Use dryRun before a real send with POST /api/commercial/operator-send-buyer-reply.
5. Use follow-up only after the first buyer reply or missing-info request. POST /api/commercial/operator-send-follow-up sends only the queue item's followUpDraft, does not accept arbitrary recipient email, and does not automatically record recommendedActionPayload.
6. Use operator-inbound-replies as the provider-agnostic inbox before reply intake. GET /api/commercial/operator-inbound-replies returns sanitized text replies. Load matched inbound replies into replyIntakeText before calling operator-reply-intake-record.
7. Use operator-reply-intake-record when a buyer replies by email and you want the server to analyze and record one safe action. POST /api/commercial/operator-reply-intake-record uses itemId admissions_concierge:{leadId}. Does not accept arbitrary record endpoints or recordBody. Will not record payment_confirmed from buyer email alone.
8. Use operator-payment-evidence-record only after external payment provider evidence exists. POST /api/commercial/operator-payment-evidence-record uses itemId admissions_concierge:{leadId}, provider evidence, amountJPY, and evidenceNote. Do not use buyer email claims as payment evidence. It does not accept arbitrary record endpoints or recordBody.
9. Use operator-payment-evidence-import for payment provider webhook or import automation. POST /api/commercial/operator-payment-evidence-import accepts generic or Stripe-like payloads with itemId in metadata.itemId, metadata.commercialItemId, or client_reference_id. Auth uses x-commercial-payment-evidence-secret; Do not give payment providers the operator cockpit token.
10. Use assistantReplyDrafts and salesReplyChecklist as the reply basis; the shared send endpoint does not accept arbitrary recipient email.
11. Never promise admission results.
12. Never imply university referral compensation.
13. After report_delivered, use post_report_growth once: send one proof request, one second-school mini-plan offer, and one referral ask; then record post_report_follow_up_sent.
14. Record the operator action after a reply is sent.

## Operator action sequence

The intended sales workflow is:

send_first_reply -> request_missing_info -> send_payment_nudge -> watch_payment -> deliver_report -> post_report_growth

Use first_reply_sent, missing_info_sent, payment_requested, payment_confirmed, report_delivered,
post_report_follow_up_sent, or closed_lost as the recorded operator action state.

## Payment and fallback behavior

- If CONCIERGE_PAYMENT_URL, CONCIERGE_PAYMENT_URL_ACTION_PLAN, CONCIERGE_PAYMENT_URL_PARENT_MEETING, or
  CONCIERGE_PAYMENT_URL_URGENT is configured, paymentRequestPack can send the buyer to a direct payment URL.
- If payment URLs are missing, use the manual_invoice fallback. The public success UI exposes
  paymentRequestPack.confirmationText and fallbackMailto so the buyer can confirm purchase by email.
- If the primary CRM table is missing or unavailable, accepted leads are still recoverable from
  admissions_concierge_lead_backup in analytics_events.

## Commercial purpose

This API exists so OpenClaw, Hermes, or another sales assistant can handle most first reply, missing-information,
payment-request, payment-confirmation, and delivery-status work without reading internal database tables.