NUANS ordering for AI agents

Before you start

For operational guidance on selecting reports, collecting information, validating orders, completing payments and tracking delivery, read the official GetNuans Agent Skill.

GetNuans provides official NUANS reservation reports for eligible Canadian jurisdictions, with automated ordering and digital delivery. The API is intended for authorized purchases by entrepreneurs, law firms, accountants and corporate service professionals.

The buyer must authorize the purchase and the SPT used for payment. A quote is not a payment authorization. GetNuans is an independent NUANS member service; a report does not itself approve a name or incorporate a business.

API base URL: https://api.getnuans.com/api/agent. Send API requests to this host; this website publishes the guide and specification.

Connect through MCP

The remote MCP endpoint is https://api.getnuans.com/mcp, using Streamable HTTP. Its four tools are list_products, create_quote, create_purchase_link and check_order_status. They reuse the REST API's current product requirements, quote validation and Order ID + email verification. Use the same locale for product discovery and quoting.

Discover products, collect the required information and create an immutable quote. Quoting saves an unpaid record; it does not charge or start report processing. Present the quoted total and obtain buyer authorization, then call create_purchase_link for the existing Orders API URL, HTTP POST method, JSON body and stable Idempotency-Key. If this quote already has a purchase attempt, supply its original key.

Payment requires an MPP-capable HTTP client and authorized wallet in addition to MCP. The returned URL is an API endpoint, not browser checkout; the tool does not submit payment or verify quote expiry. The existing REST Orders API handles HTTP 402, credential verification and payment confirmation. MCP-only clients can prepare orders and check status but may lack payment capability. After acceptance, use check_order_status and the returned polling guidance until the report is ready.

Step 1

Discover available products

GET /api/agent/products

Read the products array for current product IDs, names, jurisdictions, CAD prices, integer price_cents and required_fields, plus the fields specification for each product. Availability and pricing come from the current catalog. Do not assume every jurisdiction has a purchasable report.

Always retrieve products before constructing a quote. Each field describes its type, required status, options with exact values and labels, initial form default, normalization and cross-field constraints. Use ?locale=fr-CA for French purpose values, and send that same locale in the quote. Different jurisdictions have different purposes and legal-ending requirements; use the returned values rather than inventing them.

Step 2

Validate the order and obtain a quote

This Ontario example uses a discovered product and purpose. Use the current field definitions for the product you choose.

POST /api/agent/quotes
Content-Type: application/json

{
  "product_id": "ontario",
  "proposed_name": "Maple Works Inc.",
  "customer_email": "buyer@example.com",
  "customer": { "name": "Example Buyer" },
  "request": {
    "businessActivity": "Consulting",
    "purpose": "New named Ontario corporation",
    "distinctiveElement": "Maple Works",
    "legalEnding": "Inc."
  }
}

A valid request returns HTTP 201 with quote_id, currency, subtotal, tax, total, their _cents equivalents and expires_at. Integer cents are authoritative. Use the amount returned by the quote; do not supply a price.

Quotes expire after ten minutes and fix the product, price and order details. Quoting creates an unpaid order; it does not charge a card or start a government report. Current Checkout adds no separate tax, and quotes follow that same behavior.

Report quotes also require request.distinctiveElement: a contiguous sequence of complete proposed-name words before the legal ending. Unrelated terms or partial-word matches are rejected. Case, spacing and presentation punctuation follow the shared Human Checkout matcher. Optional fields and jurisdiction-specific validation are described in the OpenAPI specification. Keep the quote identifier private. Invalid fields return HTTP 422 with error: validation_failed, a message and field-specific errors; fix them before requesting payment. A successful quote is immutable: the order endpoint accepts only its identifier.

Step 3

Authorize payment and submit the order

POST /api/agent/orders
Content-Type: application/json
Idempotency-Key: <unique key for this quote>

{ "quote_id": "<returned quote_id>" }

The unpaid request returns HTTP 402 and a WWW-Authenticate: Payment … header containing the Stripe MPP challenge. Use an SPT-capable MPP client to obtain a buyer-authorized Card- or Link-backed SPT for the advertised Stripe profile and amount.

Echo the signed challenge unchanged. The credential includes payload.spt and payload.externalId matching challenge.request.externalId. Retry the same URL, body and idempotency key with the client-generated payment credential:

Authorization: Payment <client-generated MPP credential>

Card-backed SPTs issued through Link Agent Wallet use the Card payment method; SPTs backed by Link use the Link payment method. Both follow this same payment flow where permitted by Stripe and the account’s enabled methods. Payments requiring additional customer action are not treated as paid. Once payment is confirmed, the API returns HTTP 202 Accepted, the standard Payment-Receipt header, Retry-After: 10, and an order response:

{
  "order_id": "GN-EXAMPLE-A1B2C3",
  "status": "processing",
  "poll_after_seconds": 10
}

Keep the receipt and order ID. HTTP 202 means the paid order was accepted; the NUANS report is still being processed asynchronously.

Step 4

Poll for completion and download the PDF

POST /api/agent/orders/status
Content-Type: application/json

{
  "order_id": "GN-EXAMPLE-A1B2C3",
  "email": "buyer@example.com"
}

Status verification uses Order ID plus customer email, including for existing human orders. Send the email in the JSON body. Polling has no additional payment charge.

While status is processing, wait the returned poll_after_seconds (10 seconds) before polling again. A completed response can include:

{
  "order_id": "GN-EXAMPLE-A1B2C3",
  "status": "completed",
  "report": {
    "downloadable": true,
    "available_until": "2027-01-17T20:00:00.000Z",
    "download_url": "https://api.getnuans.com/api/orders/GN-EXAMPLE-A1B2C3/report?token=<download token>"
  }
}

Follow the returned download_url to retrieve the PDF. Use that URL unchanged. Links expire after ten minutes; another verified status request can return a fresh link within the existing retention period. Some reports can also include cover_letter_url.

A completed report whose file is missing or outside retention has downloadable: false and no download URL. A permanent failure returns failed; use existing support for assistance. Unpaid orders return awaiting_payment.

Retries, idempotency and errors

• Use one unique, visible-ASCII Idempotency-Key of 1–200 characters per quote. Reuse it unchanged for the unpaid request and paid retries.
• Submit only quote_id to the order endpoint. Changing quoted details, reusing a key for another quote, or substituting a different payment attempt is rejected.
• Retry an uncertain payment using the original quote, key and credential. An exact successful retry returns the stored receipt. Do not create a second purchase to recover an uncertain payment.
• HTTP 503 does not prove that a payment failed. If the quote expires before the outcome is confirmed, use the original order ID (also the challenge’s externalId) and email to check status or contact support.
• Respect HTTP 429 and Retry-After. Invalid Order ID/email combinations return the same generic 404.

The contract documents 400 validation errors, 402 payment challenges, 409 conflicts, 410 quote expiry, 413 oversized requests, 429 rate limits and 503 temporary unavailability. Error responses contain an error string.

Read the complete OpenAPI specification for request schemas, required parameters and response headers.