MedBridge Sales Ops API
Quick start
The runner provides the API base URL as BASE_URL. Start every task with a health ping to confirm connectivity:
curl -s "${BASE_URL}/api"
The response lists all collections and endpoints. All endpoints are GET only and return JSON.
Three task types
This skill covers three distinct task patterns. Identify which one applies from the prompt:
| Signal in prompt | Task type | See |
|---|---|---|
quote_id starting with Q-, freight options, transport comparison |
Quote revision with freight | Quote + freight workflow |
rfq_id starting with RFQ-, module-level quote, EXW only, no freight |
Indicative module quote | Module quote workflow |
opportunity_id starting with OPP-, milestones, invoices, payments, revenue recognition, events, vouchers |
Engagement reconciliation | Reconciliation workflow |
Shared rules for all tasks
- Return only valid JSON matching the answer template in
input/payloads/answer_template.json. No markdown, no explanatory text. - Money values always have exactly two decimal places (
50000.00, not50000). - Dates use ISO
YYYY-MM-DDformat. - Use stable record IDs exactly as the API returns them.
- Use only the controlled enum values declared in the template; do not invent new status strings.
- All policy records come from
GET /api/policies(list endpoint). Match policies byapplies_to,policy_area, orterms_codedescriptor.
API navigation
Start with the list endpoint for a collection, then filter by ID or foreign key. The list endpoints return all records; there is no server-side filtering except /api/search?q=. Do client-side filtering of the full response array.
Key cross-collection links:
quotes[].customer_id->/api/customers/{customer_id}quotes[].primary_product_code->/api/products/{product_code}freight-quotes[].quote_id-> the quote being costedrfqs[].customer_id->/api/customers/{customer_id}rfqs[].requested_modules[].product_code->/api/products/{product_code}opportunities[].customer_id->/api/customers/{customer_id}invoices[].opportunity_id-> the parent opportunitypayments[].opportunity_id-> the parent opportunity;payments[].invoice_id-> the invoicerevenue-journals[].opportunity_id-> the parent opportunity;revenue-journals[].invoice_id-> the invoiceevents[].opportunity_id-> the parent opportunityvouchers[].event_id-> the parent event;vouchers[].code-> use in/api/vouchers/{code}
For detailed field schemas of every collection, see references/api_reference.md.
Quote + freight workflow
Use when the prompt names a quote_id (e.g., Q-TR-WC-1187) and asks for freight comparison, transport options, or risk flags.
Step 1: Gather source records
QUOTE=$(curl -s "${BASE_URL}/api/quotes/<quote_id>")
CUSTOMER_ID=$(echo "$QUOTE" | python3 -c "import sys,json; print(json.load(sys.stdin)['customer_id'])")
PRODUCT_CODE=$(echo "$QUOTE" | python3 -c "import sys,json; print(json.load(sys.stdin)['primary_product_code'])")
CUSTOMER=$(curl -s "${BASE_URL}/api/customers/${CUSTOMER_ID}")
PRODUCT=$(curl -s "${BASE_URL}/api/products/${PRODUCT_CODE}")
FREIGHT=$(curl -s "${BASE_URL}/api/freight-quotes")
POLICIES=$(curl -s "${BASE_URL}/api/policies")
Filter FREIGHT to records where .quote_id matches the target quote. Present in order: AIR, SEA, ROAD.
Step 2: Resolve catalog pricing tier
The product record has a price_tiers array. Each tier has min_qty, max_qty (nullable), unit_price_usd, and lead_time_days. Match: min_qty <= confirmed_quantity <= max_qty (treat null max_qty as unlimited). Use the tier's unit_price_usd and lead_time_days.
exw_total_usd = confirmed_quantity * unit_price_usd
Note: shelf_life_months comes from the product root, not the tier.
Step 3: Evaluate freight options
For each freight record tied to the quote:
grand_total_usd = exw_total + freight.cost_usdtransit_days: usetransit_days_textvalid_until: compare against the quote datevalidity_status:"VALID"whenvalid_until >= quote_date,"STALE"otherwisesource_is_stale:truewhen stale,falsewhen valid- Route risk: map
route_risk-> uppercase for risk level; derive risk_flag fromroute_riskandrisk_noteslow-> risk_levelLOW, risk_flagNONEmedium-> risk_levelMEDIUM, risk_flagMEDIUM_BORDER_RISKhigh-> risk_levelHIGH, risk_flagHIGH_CUSTOMS_RISK(orHIGH_BORDER_RISKdepending on risk_notes)
Step 4: Policy decisions
See references/decision_rules.md for the complete decision table.
Summary:
- Recommended mode: Prefer SEA when valid and low risk. If SEA is risky or the customer needs speed, recommend AIR. Flag ROAD when stale or medium/high risk.
- Payment terms: From customer
payment_profile. New NGO (NEW_CLIENT_REVIEW,new_ngosegment) ->PREPAY_100. Recurring NGO/commercial ->NET_30_AFTER_PO. Milestone billing -> check opportunity. - Freight reconfirmation: Always
trueperPOL-FREIGHT-RECONFIRM. - All freight valid on quote date:
trueonly if every freight record'svalid_until >= quote_date. - Customer policy: Derive from customer
segmentfield (e.g.,recurring_ngo,new_ngo,recurring_commercial). Map directly or uppercase. - Offer validity: 30 days per
POL-QUOTE-VALIDITY.
Module quote workflow
Use when the prompt names an rfq_id (e.g., RFQ-TR-IEHK-204) and says EXW only, module level, indicative, or no freight.
Step 1: Gather source records
RFQ=$(curl -s "${BASE_URL}/api/rfqs/<rfq_id>")
CUSTOMER_ID=$(echo "$RFQ" | python3 -c "import sys,json; print(json.load(sys.stdin)['customer_id'])")
CUSTOMER=$(curl -s "${BASE_URL}/api/customers/${CUSTOMER_ID}")
POLICIES=$(curl -s "${BASE_URL}/api/policies")
Step 2: Quote each requested module
For each entry in rfq.requested_modules[]:
PRODUCT=$(curl -s "${BASE_URL}/api/products/<product_code>")
When a product has a single price tier (min_qty: 1, max_qty: null), use it directly. Use article_number, lead_time_days, and shelf_life_months from the product/tier.
line_total = quantity * unit_price_usd
Critical: module granularity. Per POL-MODULE-GRANULARITY, quote at module line level only. Ignore component_composition_distractors in the RFQ -- do not split modules into component SKUs.
Step 3: Controls
freight_excluded:trueperPOL-INDICATIVE-EXW(no destination -> EXW only)grand_total: sum of allline_totalvaluespayment_terms:PREPAY_100for new NGO clients perPOL-NEW-CLIENT-PAYMENT; verify against customerpayment_profileoffer_validity_days: 30 perPOL-QUOTE-VALIDITYwho_documentation_required:truefor IEHK / emergency health kit productsquote_basis:"EXW_ONLY"
Reconciliation workflow
Use when the prompt names an opportunity_id (e.g., OPP-TR-HELIOS) and asks for milestone reconciliation, revenue recognition, collections, or event follow-ups.
Step 1: Gather all related records
OPPORTUNITY=$(curl -s "${BASE_URL}/api/opportunities/<opportunity_id>")
CUSTOMER_ID=$(echo "$OPPORTUNITY" | python3 -c "import sys,json; print(json.load(sys.stdin)['customer_id'])")
CUSTOMER=$(curl -s "${BASE_URL}/api/customers/${CUSTOMER_ID}")
INVOICES=$(curl -s "${BASE_URL}/api/invoices")
PAYMENTS=$(curl -s "${BASE_URL}/api/payments")
REVJOURNALS=$(curl -s "${BASE_URL}/api/revenue-journals")
EVENTS=$(curl -s "${BASE_URL}/api/events")
POLICIES=$(curl -s "${BASE_URL}/api/policies")
Filter invoices, payments, revenue journals, and events by opportunity_id. Map each milestone to its invoice via phase_id / invoice_id cross-reference.
Step 2: Build milestone table
For each phase in opportunity.phases[] (ascending by phase_id):
- Find the matching invoice via
invoice_idfrom the phase record - Find the matching payment via
invoice_idfrom the invoice record - Check for a revenue journal entry via
invoice_id
Step 3: Revenue recognition status
For each milestone:
| Payment state | Revenue journal exists | Recognition status |
|---|---|---|
| PAID | Yes | RECOGNIZED |
| PAID | No | MISSING_REVENUE_JOURNAL |
| UNPAID | -- | NOT_REQUIRED_UNPAID |
Per POL-REVREC: only paid completed milestones need revenue journals.
Step 4: Accounting and collection actions
See references/decision_rules.md for the full decision matrix.
Summary:
- Accounting: If any paid milestone lacks a revenue journal ->
RECORD_REVENUE_MS{N}. Accounts: debitDEFERRED_REVENUE, creditIMPLEMENTATION_SERVICES_REVENUE. Owner:ACCOUNTING. - Collection: If unpaid milestone past due ->
SEND_COLLECTION_NOTICE. If unpaid but not yet due ->MONITOR_UNPAID_NOT_DUE. Everything paid ->NO_COLLECTION_ACTION. Owner:ACCOUNT_MANAGEMENTwith the opportunity contact. - Invite: If event status is
scheduled->SEND_BRIEFING_INVITE. Fetch full voucher withGET /api/vouchers/{code}. Owner:ACCOUNT_MANAGEMENT.
Step 5: Voucher handling
Voucher records use discount_percent. The template may ask for a discount value -- use the percent as-is (e.g., 50 from discount_percent: 50). Max uses comes from max_redemptions. Event status from the event record; expected values are scheduled, confirmed, live, completed, tentative. Map as needed to template enums.
Validation checklist
Before returning JSON, verify:
- All IDs match the API response exactly (case-sensitive)
- Monetary sums:
exw_total = quantity * unit_price,grand_total = exw_total + freight_cost,phase_total_amount= sum of all phaseamount_usd opportunity_matches_phase_total: comparewon_amountagainst sum of all phase amounts- Dates are not in the future for staleness checks relative to the quote date or current business date
- No markdown wrapping, no trailing commas, valid JSON