{"openapi":"3.1.0","info":{"title":"GetNuans — Canadian NUANS & Business Name Search","version":"1.0.0","contact":{"email":"support@getnuans.com"},"description":"GetNuans provides Canadian NUANS reports and provincial business name search services for incorporation, business registration, and name reservation. Serving Ontario, Alberta, New Brunswick, Nova Scotia, and federal jurisdictions. AI agents can discover products, obtain CAD quotes, pay securely through Stripe Machine Payments (Card or Link), and track orders through digital delivery.","x-guidance":"Use https://api.getnuans.com/api/agent for all requests. First GET /products to discover current prices, product-specific fields and exact localized option values. POST /quotes with valid customer and product details to obtain an immutable 10-minute quote_id and CAD total; quoting creates an unpaid order record but does not charge or start fulfillment. Then POST /orders with only that quote_id and a unique Idempotency-Key to receive the Stripe MPP HTTP 402 Challenge. Obtain a Card or Link Shared Payment Token through an MPP-capable client and retry the same quote_id and key with its Authorization: Payment credential. The runtime Challenge is authoritative. Missing or invalid quotes and missing idempotency keys are rejected before a payment challenge; do not use POST /orders as a health check. After HTTP 202, poll POST /orders/status using order_id and the customer's email, honoring poll_after_seconds. If payment is uncertain, retry the original quote, key and credential; do not create a replacement quote or purchase. See https://getnuans.com/agents for the full workflow."},"servers":[{"url":"https://api.getnuans.com/api/agent"}],"externalDocs":{"description":"Agent ordering guide","url":"https://www.getnuans.com/agents"},"x-service-info":{"categories":["data","search"],"docs":{"homepage":"https://getnuans.com","apiReference":"https://getnuans.com/api/agent/openapi.json","llms":"https://getnuans.com/llms.txt"}},"paths":{"/products":{"get":{"operationId":"agentProducts","summary":"Discover currently purchasable products and current admin pricing","responses":{"200":{"description":"Available catalog.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Products"}}}},"400":{"description":"Invalid input, unavailable product, or missing required parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Honor Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait.","schema":{"type":"string"}}}},"503":{"description":"Temporarily unavailable or MPP not configured. For payment requests retry the SAME quote, key and credential; never assume the payment failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"description":"Call this endpoint before every quote. Existing prices and required_fields are retained; fields describes actual wire parameters. Different jurisdictions have different legal-ending requirements and purpose values. Defaults describe initial Human Checkout selections; required quote values must still be supplied.","parameters":[{"in":"query","name":"locale","required":false,"schema":{"type":"string","enum":["en-CA","fr-CA"],"default":"en-CA"},"description":"Use the same locale in the quote; localized purpose labels are also the submitted values."}]}},"/quotes":{"post":{"operationId":"agentQuote","summary":"Validate an order and snapshot an immutable quote","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteRequest"}}}},"responses":{"201":{"description":"Quote created. Keep its identifier private until payment.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Quote"}}}},"400":{"description":"Invalid input, unavailable product, or missing required parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"JSON body exceeds 64 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Shared Human Checkout field validation failed before quote creation or payment. Field paths match discovery. Invalid dropdowns include allowed_values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/QuoteValidationError"}}}},"429":{"description":"Rate limit exceeded. Honor Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait.","schema":{"type":"string"}}}},"503":{"description":"Temporarily unavailable or MPP not configured. For payment requests retry the SAME quote, key and credential; never assume the payment failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders":{"post":{"operationId":"agentOrder","summary":"Pay once through Stripe MPP Card or Link SPT and accept asynchronous fulfillment","x-payment-info":{"offers":[{"method":"stripe","intent":"charge","currency":"cad","amount":null,"description":"Pay for the validated Canadian NUANS report or business-name-search quote using a Card or Link Shared Payment Token through Stripe. The amount depends on the selected product and its quoted total; the runtime HTTP 402 Challenge is authoritative."}],"price":{"mode":"dynamic","currency":"CAD"},"protocols":[{"mpp":{"method":"stripe","intent":"charge","currency":"cad"}}]},"description":"First submit quote_id plus a unique Idempotency-Key. Receive 402 and WWW-Authenticate: Payment. Let an MPP client obtain a Stripe SPT scoped to the advertised profile/amount, echo the signed challenge with payload.spt and payload.externalId matching challenge.request.externalId, then repeat the same request/key with Authorization: Payment <credential>. Stripe Card and Link SPT payments are supported where enabled for the Stripe account. Card-backed SPTs issued through Link Agent Wallet remain Card payments; SPTs backed by Link use the Link payment method. Both use the same confirmed PaymentIntent workflow, restricted to card and link. A requires_action or otherwise non-final PaymentIntent does not authorize fulfillment. The quote, request scope and hashed idempotency key are bound into the SDK challenge. Exact paid retries return the original receipt. A fresh challenge or SPT cannot purchase the same quote twice. If payment outcome is uncertain, retain and retry the original credential. Do not create a second quote as a recovery strategy.","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"schema":{"type":"string","minLength":1,"maxLength":200},"description":"Unique per quote; reuse unchanged on unpaid/paid retries. A key bound to another quote returns 409."},{"name":"Authorization","in":"header","required":false,"schema":{"type":"string"},"description":"Payment <base64url MPP credential> from an SPT-capable MPP client. No OAuth, JWT or customer account."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderRequest"}}}},"responses":{"202":{"description":"Payment confirmed; report processing is asynchronous.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/AcceptedOrder"}}},"headers":{"Payment-Receipt":{"description":"Unmodified mppx receipt on initial success and exact retries. After a crash, reconciliation uses the SDK receipt serializer with the confirmed PaymentIntent reference.","schema":{"type":"string"}},"Retry-After":{"description":"10 seconds.","schema":{"type":"string"}}}},"400":{"description":"Invalid input, unavailable product, or missing required parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Payment required or invalid MPP credential.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"WWW-Authenticate":{"description":"Official HMAC-bound MPP challenge: Stripe charge, CAD, methodDetails.paymentMethodTypes is [card, link].","schema":{"type":"string"}}}},"409":{"description":"Quote/key/credential conflicts with a previous attempt. Retry the original values.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"410":{"description":"Quote expired. A pending charge may still reconcile through Stripe webhooks. Check the original order before starting another purchase.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"JSON body exceeds 64 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Honor Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait.","schema":{"type":"string"}}}},"503":{"description":"Temporarily unavailable or MPP not configured. For payment requests retry the SAME quote, key and credential; never assume the payment failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/orders/status":{"post":{"operationId":"agentOrderStatus","summary":"Verify Order ID + email and poll at no additional charge","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/StatusRequest"}}}},"responses":{"200":{"description":"Verified order status and existing protected PDF URL if available.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/OrderStatus"}}}},"400":{"description":"Invalid input, unavailable product, or missing required parameters.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Same generic error for all invalid order/email combinations.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"413":{"description":"JSON body exceeds 64 KiB.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit exceeded. Honor Retry-After.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}},"headers":{"Retry-After":{"description":"Seconds to wait.","schema":{"type":"string"}}}},"503":{"description":"Temporarily unavailable or MPP not configured. For payment requests retry the SAME quote, key and credential; never assume the payment failed.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}}},"components":{"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string"}},"required":["error"]},"Product":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"jurisdiction":{"type":"string"},"currency":{"const":"CAD"},"price":{"type":"number","minimum":0},"price_cents":{"type":"integer","minimum":0},"required_fields":{"type":"array","items":{"type":"string"}},"fields":{"type":"object","additionalProperties":{"$ref":"#/components/schemas/ProductField"},"description":"Keyed by accepted quote wire path. Discover exact product-specific enums here rather than using static or inferred values."}},"required":["id","name","jurisdiction","currency","price","price_cents","required_fields","fields"]},"Products":{"type":"object","properties":{"products":{"type":"array","items":{"$ref":"#/components/schemas/Product"}}},"required":["products"]},"QuoteRequest":{"type":"object","properties":{"product_id":{"type":"string"},"proposed_name":{"type":"string"},"customer_email":{"type":"string","format":"email"},"customer":{"type":"object","properties":{"name":{"type":"string"},"phone":{"type":"string"}},"required":["name"]},"request":{"type":"object","properties":{"businessActivity":{"type":"string"},"purpose":{"type":"string","description":"Required for reports. Use the exact product- and locale-specific option value from GET /products; defaults are Human Checkout initial selections, not omitted quote substitutions."},"legalEnding":{"type":"string","description":"Use this product's discovered option value. Include it once in proposed_name. Required designation for Ontario/Alberta; a recognized suffix already in the name satisfies legacy omission of this separate field."},"distinctiveElement":{"type":"string","description":"Required for reports. Must be contained in proposed_name as complete contiguous tokens, excluding the legal ending. Unicode NFKC, case, whitespace and presentation punctuation are normalized for matching; accents are significant. Original customer text is preserved."},"alternateSpellings":{"type":"string"},"notes":{"type":"string"},"province":{"type":"string","description":"Preliminary only: use the discovered jurisdiction values; omitted/blank means All jurisdictions. Report jurisdiction is fixed by the product."}}},"locale":{"type":"string","enum":["en-CA","fr-CA"],"default":"en-CA"}},"required":["product_id","proposed_name","customer_email","customer"],"description":"First call GET /products (with the quote locale) and use its fields and exact option values. Do not invent purpose or legal-ending values. All reports require businessActivity, purpose and distinctiveElement. Distinctive terms must match a contiguous sequence of complete proposed-name tokens before its legal suffix, using the shared case/spacing/punctuation normalization; partial words and unrelated terms fail. Ontario/Alberta require a recognized legal suffix. A supplied legalEnding must match the complete proposed_name; legacy omission is accepted when the suffix is already present. Federal/New Brunswick/Nova Scotia also allow none. Preliminary searches require only customer name/email and proposed name; request.province may be omitted/blank for All jurisdictions, otherwise use its discovered value. No billing address or confirmEmail wire field is required. Validated data is immutable after quoting.","allOf":[{"if":{"properties":{"product_id":{"not":{"const":"preliminary"}}},"required":["product_id"]},"then":{"required":["request"],"properties":{"request":{"required":["businessActivity","purpose","distinctiveElement"]}}}}]},"Quote":{"type":"object","properties":{"quote_id":{"type":"string"},"currency":{"const":"CAD"},"subtotal":{"type":"number","minimum":0},"tax":{"type":"number","minimum":0},"total":{"type":"number","minimum":0},"subtotal_cents":{"type":"integer","minimum":0},"tax_cents":{"type":"integer","minimum":0},"total_cents":{"type":"integer","minimum":0},"expires_at":{"type":"string","format":"date-time"}},"required":["quote_id","currency","subtotal","tax","total","subtotal_cents","tax_cents","total_cents","expires_at"],"description":"Immutable 10-minute quote. Integer cents are authoritative. Current Human Checkout adds no separate tax; tax is zero and total equals the configured product price. Quoting creates the same pre-payment order record as Checkout, but does not charge or start a government report."},"OrderRequest":{"type":"object","properties":{"quote_id":{"type":"string"}},"required":["quote_id"],"additionalProperties":false},"AcceptedOrder":{"type":"object","properties":{"order_id":{"type":"string"},"status":{"const":"processing"},"poll_after_seconds":{"const":10}},"required":["order_id","status","poll_after_seconds"]},"StatusRequest":{"type":"object","properties":{"order_id":{"type":"string","maxLength":120},"email":{"type":"string","format":"email","maxLength":320}},"required":["order_id","email"]},"OrderStatus":{"type":"object","properties":{"order_id":{"type":"string"},"status":{"type":"string","enum":["awaiting_payment","processing","completed","failed"]},"poll_after_seconds":{"const":10},"report":{"type":"object","properties":{"downloadable":{"type":"boolean"},"available_until":{"type":["string","null"],"format":"date-time"},"download_url":{"type":"string","format":"uri"},"cover_letter_url":{"type":"string","format":"uri"}},"required":["downloadable","available_until"]}},"required":["order_id","status"],"description":"Email verification is the existing Customer Portal mechanism and works for human orders too. Download URLs use the existing short-lived report token after verification (no email in URLs). Follow the existing GET PDF URL; no new PDF endpoint. After retention expiry or if a file is absent, completed reports have downloadable=false. Failed orders follow existing support/refund handling."},"ProductField":{"type":"object","properties":{"type":{"const":"string"},"required":{"type":"boolean"},"options":{"type":"array","items":{"type":"object","properties":{"value":{"type":"string"},"label":{"type":"string"}},"required":["value","label"]}},"default":{"type":"string","description":"Initial Human Checkout selection; descriptions distinguish omitted API behavior."},"const":{"type":"string"},"minLength":{"type":"integer","minimum":0},"format":{"type":"string"},"description":{"type":"string"},"normalization":{"type":"string"},"required_when":{"anyOf":[{"type":"null"},{"type":"object","properties":{"field":{"type":"string"},"condition":{"type":"string"}},"required":["field","condition"]}]},"constraints":{"type":"object","description":"Cross-field constraints such as contained_token_sequence with the referenced field, suffix matching, and legal-ending requirements."}},"required":["type","required"]},"QuoteValidationError":{"type":"object","properties":{"error":{"const":"validation_failed"},"message":{"type":"string"},"fields":{"type":"object","additionalProperties":{"type":"object","properties":{"message":{"type":"string"},"allowed_values":{"type":"array","items":{"type":"string"}}},"required":["message"]}}},"required":["error","message","fields"]}}}}