RollStamp APIv1 sandbox

Developer guide

RollStamp API covers the compliance book, the Maker Console, source catalogs and order routing, and dealer vetting. One key opens the routes for the account. Most routes answer with JSON; the file exports return the format they name.

Getting startedKeys, IPs and limitsCompliance bookMaker ConsoleSources and configurationCatalogAnalyticsDealer directoryRestrictionsQuotes and ordersTrackingFraud reportsRouting and carrier ratesVetting checksWebhooksEDI and ERPVendors and the portalSupport chatMCP connectorErrorsThe sandbox

Getting started

Send requests to /v1/... with the key in x-api-key. A successful call returns data; a failed call returns an error code and a readable message.

{ "success": true, "data": { ... } }
{ "success": false, "error": { "code": "invalid_parameter", "message": "...", "details": ... } }

Branch on error.code. The message can change; the code does not. Check the key first:

curl https://api.rollstamp.example/v1/ping -H 'x-api-key: fflsbx_std_9f3k2m7q4t'

The API tester sends a request from the browser. openapi.json is the field-level schema, and llms.txt is a short route map for coding agents.

Keys, IPs and limits

A key can read records and make writes. Keep it on a server. A browser or mobile app should call your server, not hold the key. Each key also has an IP allowlist, so a request is checked twice: a valid key, from an allowed address.

Send x-api-key: <key> or Authorization: Bearer <key>. A missing key returns 401; an address outside the allowlist returns 403. Repeated bad keys from one address can return 429.

TierRequests per minuteRequests per day
standard6010,000
pro300100,000
enterprise10001,000,000

A successful request made with an account key carries X-RateLimit-Limit and X-RateLimit-Remaining. A 429 carries Retry-After; wait that long before retrying. GET /v1/usage shows today's calls by endpoint.

Sample keys

KeyAccountTierAllowed IPsWhat it shows
fflsbx_std_9f3k2m7q4tDemo Storefrontstandard127.0.0.1 ::1Ready to go: four validated distributors, store pickup configured.
fflsbx_pro_4h8w1z6c2rNew Integrationpro127.0.0.1 ::1 203.0.113.25Fresh account with no distributors: walk through setup.
fflsbx_ent_7x2n5b8v1kEnterprise Partnerenterprise198.51.100.7Only allowed from 198.51.100.7, so calls from 127.0.0.1 get ip_not_allowed.
fflsbx_new_3c6y9u2p5ePending EnrollmentstandardnoneNo registered server IPs yet, so every call gets ip_whitelist_required.

Compliance book

Each license has its own book. Create a license with POST /v1/compliance/licenses; the license number determines the type. Every acquisition, disposition, hold and correction stores recorded_by. Every correction keeps the earlier version.

The FastBound adapter in api/src/integrations/fastbound drains that queue and acknowledges each entry. It is off unless the FastBound account number, FastBound API key, FastBound audit user and a RollStamp API key are set. No live FastBound account is connected in this build.

POST /v1/compliance/acquisitions
{ "license_id": "lic_...", "type": "RECEIVE", "recorded_by": "[email protected]",
  "item": { "type": "PISTOL", "manufacturer": "Example Arms", "model": "Stamp", "serial": "EX-000418", "caliber": "9mm" } }

A second open line for the same manufacturer and serial on one license is refused. A disposition can carry form4473_ref, nfa_form_ref and the NICS status; the book stores what you send. A retail 4473 needs a form4473_ref. Form 3 and Form 5 each need an nfa_form_ref. A Form 4 needs both a form4473_ref and an nfa_form_ref.

Recording rules and deadlines come from a data table with a citation. A citation marked (verify) is waiting on a legal review. Do not treat a guide value as legal advice. FastBound remains the legal system of record by default; switching a license to RollStamp needs a recorded counsel sign-off and no FastBound change still waiting to sync.

Maker Console

Serial series are for Type 07 and Type 10 manufacturers. A product template describes the firearm and names an excise category; it can carry an importer when one applies. A series needs a width. A prefix, the current-year segment and a suffix are optional, and the series issues values in order.

A new reservation skips any value that already has a serial record or an open book line, up to 10,000 skipped values in one request. Past that it returns reservation_skip_limit instead of guessing. A completed build calls the book with a MANUFACTURE acquisition and moves the serial from marked to acquired. If the book refuses, the serial stays marked and no build is created.

The excise worksheet groups rows by category and shows units, gross receipts, tax and the citation behind each line, plus the year-to-date manufactured count. Rates, the small-manufacturer threshold and quarterly due dates sit in a data table whose citations are marked (verify). The worksheet is not a filed return.

Sources and configuration

The account keeps one configuration document: active sources, credentials, pricing, product restrictions and pickup settings. Read it, edit it, write it back whole.

  1. GET /v1/distributors lists each source, its config_schema and a default_config.
  2. GET /v1/config, edit, then PUT /v1/config. The PUT replaces the whole document, so start from a fresh read. Masked secrets read as ********; send them back unchanged to keep them.
  3. POST /v1/config/validate with an empty body checks the saved credentials. A product route only serves a validated source. Send a configuration in the body for a dry run that saves nothing.
PUT /v1/config?validate=true
{ "configuration": { "distributors": { "Lipseys": { "active": true, ... } }, ... } }

A schema failure returns 400 schema_validation_failed with {path, message} for every problem. With ?validate=true, a save that would remove more of the live catalog than the account threshold is refused with 409 validation_failed before anything changes. The setup page in the tester performs the same three steps with a form.

Catalog

The catalog holds every offer from an active, validated source after your restrictions and pricing. unit_price is your cost; retail_price follows your markup; with respect_map on, it does not go below MAP.

GET /v1/products/search?q=9mm&in_stock=true&sort=price&page_size=10
GET /v1/products/643740108515
GET /v1/products/catalog?last_version=v=20261117T130000-...

Analytics

Reports are built from daily stock and price movement across sources: top-products, on-sale, margin-opportunities, trending, new-arrivals, newly-available, price-gaps. Each takes window (7d, 30d, 60d, 90d), limit (up to 200), product_class and category_id.

GET /v1/analytics/trending?window=30d&product_class=FA&limit=20

Dealer directory

GET /v1/ffls?zip=37201&radius=25 requires a 5-digit ZIP; name is optional. It returns up to 150 dealers, best first: a license already on file in the exact ZIP, then an on-file nearby license, then an exact ZIP with no file, then the rest. GET /v1/ffls/{license_number} reads one dealer; an X in the license matches any character. For a dealer used by one of your own orders, the license and SOT copies are at /v1/ffls/{license_number}/documents/ffl and /v1/ffls/{license_number}/documents/sot when the document is on file.

Restrictions

POST /v1/restrictions/check tests 1 to 100 items against the account rule list: states, counties, cities and ZIPs against UPCs, SKUs, classes, categories and attributes such as magazine capacity. For a US destination, shipping.state is required. The result returns approved, the blocking rules, the warnings and the manual review matches. Each hit carries a message you can show a customer.

POST /v1/restrictions/check
{ "shipping": { "state": "CA", "zip": "94105" }, "items": [ { "upc": "760310155875" }, { "product_class": "AO" } ] }

Quotes and orders

POST /v1/orders/quote finds the cheapest in-stock source for each item, counting estimated shipping unless the account ignores it, and returns up to five alternatives. POST /v1/orders places the order.

POST /v1/orders
{ "order_id": 10021,
  "customer": { "name": "Jane Sample", "email": "[email protected]", "address1": "1 Main St", "city": "Nashville", "state": "TN", "zip": "37201" },
  "items": [ { "distid": "LIP", "distsku": "LP108515", "upc": "643740108515", "qty": 1, "ffl_req": true } ],
  "ffl": { "licenseNumber": "4-37-201-01-8K-70207" } }

Tracking

An order starts as submitted, submitted_by_email or sent_to_vendor, moves to processing, then to shipped. The shipment moves from awaiting_shipment to in_transit to delivered, with a carrier and tracking number. Read one order with GET /v1/orders/{order_id}, page through GET /v1/orders, or search GET /v1/fulfillment/history by PO number, distributor order number or tracking number. Failed placements appear under errors.

Fraud reports

POST /v1/fraud/check takes an address, email or phone. A match means hold for review, not cancel. An address matches addresses, an email matches emails and a phone matches phones; a shipping address does not count when the order ships to an FFL. A name, IP address or item overlap only adds weight. You see counts and dates, never another dealer's raw record. Report a confirmed fraud with POST /v1/fraud/reports; a destination marked as an FFL cannot be reported. Remove your own report with DELETE /v1/fraud/reports.

POST /v1/fraud/check
{ "shipping_address_1": "123 Main St Apt 4", "shipping_postcode": "30301", "email": "[email protected]" }

Routing and carrier rates

GET /v1/orders/{order_id}/routing shows, for each line of an order, the source that was chosen, the rule that chose it (exact_source, lowest_landed_cost or lowest_cost_consolidated), a sentence explaining it, and a candidate list with stock and landed cost. GET /v1/inventory/{sku} takes a UPC or a source SKU and lists stock and cost at each source that carries it, cheapest first.

POST /v1/shipping/rates compares carrier services for one parcel. Add "carrier_rates": true and "destination_zip" to a quote to get the same comparison for each order in the plan.

POST /v1/shipping/rates
{ "origin_zip": "37201", "destination_zip": "98101", "weight_lb": 4, "contents": "handgun" }

Rates come from sample tables (zone by distance, price by billable weight), with an estimated weight and a sample warehouse ZIP when quoting. Live carrier accounts are not connected. Services that cannot carry the contents are listed under excluded with the reason.

Vetting checks

A check verifies a dealer license (ffl_dealer), an order's destination against the licensed premise (ship_to) or a vendor's business registration (vendor). It is created as processing and finishes a few seconds later as verified, needs_review or failed, with a confidence score, flags and which fields each source matched.

POST /v1/vetting/checks
{ "type": "ffl_dealer", "license_number": "4-37-201-01-8K-70207", "business_name": "Hollow Pawn & Gun",
  "premise_address": { "line1": "4409 Highway 41", "state": "TN", "postal_code": "37201" }, "reference": "dealer-8812", "recheck": true }

Names are compared without "LLC", "Inc" and word order; addresses without suite numbers and with standard abbreviations, so 410 Market Street, Suite 200 matches 410 MARKET ST. Flags include license_not_found, license_expired, license_expiring_soon, name_mismatch, premise_mismatch and premise_partial_match. With "recheck": true the license is looked up again every day and you get vetting.license.expiring 60 days before it expires.

The license listing is this sandbox's sample dealer directory and the business registry is generated sample data. A result helps you decide; it does not replace the transfer and record-keeping rules that apply to you.

Webhooks

POST /v1/webhooks with an https url (http only when the server operator allows private testing) and a list of events: vetting.check.completed, vetting.license.expiring, order.submitted, order.shipped, order.delivered, vendor.inventory.updated, support.message.created. The response carries the signing secret once. Each delivery is a JSON POST:

{ "id": "evt_...", "event": "vetting.check.completed", "created_at": "2026-11-17T15:04:11.000Z",
  "data": { "id": "chk_...", "status": "needs_review", "flags": ["premise_mismatch"], "reference": "dealer-8812" } }

Check the signature header before trusting a delivery. It reads t=<unix seconds>,v1=<signature>, where the signature is the hex HMAC-SHA256 of t + "." + body keyed with your secret. Compare in constant time and reject timestamps more than a few minutes old. The public header name is RollStamp-Signature.

const [t, v1] = header.split(',').map((p) => p.split('=')[1]);
const expected = crypto.createHmac('sha256', secret).update(t + '.' + rawBody).digest('hex');
const got = Buffer.from(v1 || '');
const ok = got.length === Buffer.byteLength(expected) && crypto.timingSafeEqual(got, Buffer.from(expected)) && Math.abs(Date.now() / 1000 - Number(t)) < 300;

Answer with any 2xx within 8 seconds. Anything else is retried after 1 minute, 5 minutes, 30 minutes and 2 hours, then marked failed. Redirects are not followed, and URLs that resolve to private or local addresses are refused unless the operator turns on the private-address allowance. GET /v1/webhooks/{id}/deliveries shows the attempt count, latest status code and last error for each delivery; POST /v1/webhooks/{id}/test queues a test delivery.

EDI and ERP

GET /v1/orders/{order_id}/edi returns an ANSI X12 004010 850 purchase order for each distributor or vendor order. POST /v1/edi/inbound reads what a partner sends back, as {"x12": "..."}:

SetWhat happens
855The order is marked acknowledged, or rejected by the partner.
856Carrier and tracking number go onto the order; it becomes shipped and order.shipped fires.
810The invoice is recorded; its total is compared with the order's product subtotal.
846A portal vendor's inventory is replaced (the sender id must match the vendor's id or edi_id).

The response lists a result per transaction set and the 997 acknowledgment to send back. Set your interchange ids with PUT /v1/edi/settings. Documents move over this API. An AS2, SFTP or VAN connection to the partner is not part of this build and is set up separately.

For an ERP or accounting system, GET /v1/erp/export?type=orders|purchase_order_lines|shipments|invoices&format=json|csv&since=2026-11-01 returns flat rows you can import into your system. since is optional. Values that a spreadsheet could read as a formula are prefixed with an apostrophe in the CSV.

Vendors and the portal

Add your own vendors with POST /v1/vendors. The response carries a portal token (shown once) for the vendor to sign in at /portal/, where they upload an inventory CSV with sku and qty columns (optional upc, cost and name), see their purchase orders and add tracking. The same actions are available to them as /v1/portal/* routes with Authorization: Bearer <portal token>.

Vendor items whose UPC is in the master catalog and that carry a positive cost become one more source in your catalog: search, quotes and sourcing_mode: "optimal" orders can choose the vendor, the purchase order appears in its portal with status sent_to_vendor, and the tracking it enters flows back to the order. Items with an unknown UPC are stored but not listed, because their product class and restrictions are not known. Disable a vendor with PUT /v1/vendors/{id} and replace its token with POST /v1/vendors/{id}/token.

Support chat

Open a conversation with POST /v1/support/conversations ({"message": "..."}), add to it with POST .../{id}/messages, and read replies with GET .../{id}. The page at /support/ does this for you: sign in with your API key. Support staff use the same page with the admin token (or /__sandbox/support). A staff reply raises support.message.created.

MCP connector

The connector at /mcp speaks the Model Context Protocol. An MCP client can call a fixed set of tools. Most read account records: orders, why an order was routed where it was, a side-by-side comparison of your sources, catalog search, dealer lookups, restriction checks, carrier rates and vetting checks. One tool starts a vetting check, and one previews and applies a bulk catalog change when writes are allowed. For browser approval, the client must support a remote HTTP MCP server and OAuth 2.1 with PKCE. A client that can set request headers can use an API key instead. This build has not tested every client.

  1. Switch it on: PUT /v1/mcp/settings {"enabled": true}. It is off by default.
  2. In the client, add a remote MCP server and give it this server's address followed by /mcp.
  3. Your browser opens an approval page here. Enter an API key to approve.

A client that can set request headers can skip the approval page. Send Authorization: Bearer <API key> or x-api-key: <API key> from an address on the key's allowlist. That path has no connection record, and writes follow only the account setting.

Bulk changes (activating or deactivating sources, or changing the minimum quantity to list) need "allow_writes": true in the settings. An OAuth link also needs the box ticked on its approval page. Each change returns a preview first, with the number of catalog offers before and after, and is applied only when the client sends the preview's confirmation token back. A change that would remove more of the catalog than your delete threshold cannot be applied this way. GET /v1/mcp/settings lists OAuth links and DELETE /v1/mcp/connections/{id} removes one; it does not revoke a key used directly. Tool calls count against your rate limits.

Errors

StatusCodeWhat to do
400invalid_parameter / invalid_request / invalid_json / invalid_upcThe body or a field is missing or malformed. The request is rejected before any change.
400schema_validation_failedConfiguration rejected; details lists every {path, message}. Nothing was saved.
400missing_strong_signalA fraud call needs an address line, an email or a phone.
401missing_api_keySend the x-api-key header.
403invalid_api_key / key_disabledUnknown, disabled or cancelled key.
403ip_whitelist_requiredThe key has no registered server IPs yet.
403ip_not_allowedThis caller address is not on the key allowlist.
403ffl_not_associated_with_orderLicense documents are only for FFLs used by your own orders.
404not_found / product_not_found / ffl_not_found / order_not_found / report_not_foundNo match: an unknown path, a missing image, or a record not on this account.
409no_active_distributors / no_validated_distributorsActivate sources, then check their credentials.
409duplicate_orderThat order_id was already placed. Do not retry with a new id.
400invalid_fflThe dealer license is malformed, unknown or inactive.
409sourcing_unavailableThe named source cannot fill a line.
409restricted_destination / fulfillment_not_configuredThe order cannot ship as requested.
409validation_failedA save would remove too much of the catalog.
413payload_too_largeBodies are capped at 1 MB.
429rate_limitedWait Retry-After seconds, then retry with backoff.
429catalog_request_cooldownOne catalog download per 20 minutes; send last_version to poll for free.
429order_volume_limit / fraud_limit_exceededThe order or fraud cap was reached.
401invalid_vendor_token / unauthorized / invalid_tokenPortal or connector credentials are missing, wrong or expired.
403vendor_disabled / mcp_disabled / bulk_changes_not_allowedThe vendor, the connector or bulk changes are switched off for the account.
404check_not_found / webhook_not_found / vendor_not_found / conversation_not_found / connection_not_foundNothing with that id on your account.
400invalid_ediThe X12 text could not be read (ISA segment or ST/SE pairs).
409webhook_limit / vendor_limit / too_many_open_conversations / conversation_closed / preview_staleA limit was reached, or the thing changed since you looked.
500internal_errorRetry with backoff.

The sandbox

This sandbox uses generated sample data: sources, products, dealers, rules and reports are made up, and orders are simulated. Nothing ships. When the site is opened as plain pages the API runs in the browser and keeps data there; run it with Node (npm run api) to serve the same routes to another program.