{"openapi":"3.1.0","info":{"title":"NAIC API (Bowmark)","version":"e833508f87ff","description":"The insurance regulators' own consumer record on a carrier — complaint index, licensing by state and financial condition — plus the directory of state insurance departments and the charts of what each state's insurance law actually requires.\n\nEvery function Bowmark has for NAIC (naic.org) as one HTTP call. Each runs on Bowmark's infrastructure with the same billing, rules and response envelope as `POST /v1/run`. The whole API: https://api.bowmark.ai/openapi.json. Guide: https://bowmark.ai/docs/api.","contact":{"email":"support@bowmark.ai","url":"https://bowmark.ai/docs/api"}},"servers":[{"url":"https://api.bowmark.ai"}],"security":[{"bearer":[]},{"apiKeyHeader":[]}],"paths":{"/v1/sites/naic/searchCompanies":{"post":{"operationId":"searchCompanies","summary":"Searches the NAIC Consumer Information Source register and returns matching companies with their NAIC company code, legal name, HQ contact details, the states each is LICENSED in, and a link to its CI","description":"Searches the NAIC Consumer Information Source register and returns matching companies with their NAIC company code, legal name, HQ contact details, the states each is LICENSED in, and a link to its CIS report page. `name` is a case-insensitive substring (\"geico\" → the ten GEICO underwriting entities) and `homeState` is the two-letter state a company is HEADQUARTERED in — the register's own filter, which is NOT where it may sell. Both are optional and an empty query returns the whole register (~1.9 MB in one request), so pass a filter unless you genuinely want every licensed insurer in the country. `reportCategories` names which CIS reports exist for a company, not the lines it writes.\n\nCalls `bowmark.providers.naic.searchCompanies`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<naicRow[]>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"$ref":"#/components/schemas/naicCompanyQuery","description":"TypeScript: `naicCompanyQuery`"},"limit":{"type":"number","description":"TypeScript: `number`"}},"required":["query"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/naic/getComplaintIndex":{"post":{"operationId":"getComplaintIndex","summary":"Reads the insurance regulators' own complaint record for ONE company, keyed on the NAIC company code `searchCompanies` returns.","description":"Reads the insurance regulators' own complaint record for ONE company, keyed on the NAIC company code `searchCompanies` returns. `complaintIndex` is the number the report exists for: **1.0 is the national baseline**, so 2.23 means roughly twice the closed-confirmed complaints this company's share of premium would predict, and `comparison` is NAIC's own above/below verdict rather than one we compute. `byCode` splits those complaints by coverage line and NAIC's numeric complaint code (\"Private Passenger\" under Auto, \"Fire - Real Property\" under Homeowners), largest first. Two things a caller must not misread: `complaintIndex: null` is NAIC publishing no computed index, which is NOT the same as `0` (no complaints recorded); and `hasReport: false` does NOT mean the company does not exist — an invented company code and a real licensed carrier with no complaint record return byte-identical empty bodies on this surface, so confirm the code against `searchCompanies` if that distinction matters. NAIC does not state anywhere on this surface which period the index covers.\n\nCalls `bowmark.providers.naic.getComplaintIndex`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<naicComplaintIndexReport>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cocode":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"TypeScript: `string | number`"}},"required":["cocode"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/naic/listStateDepartments":{"post":{"operationId":"listStateDepartments","summary":"Returns the directory of every US insurance regulator — 57 rows across NAIC's own 56 jurisdictions (50 states, DC and five territories; Florida has two, the CFO's department and the Office of Insuranc","description":"Returns the directory of every US insurance regulator — 57 rows across NAIC's own 56 jurisdictions (50 states, DC and five territories; Florida has two, the CFO's department and the Office of Insurance Regulation) — each with the department name and website, the sitting regulator and their title, every published phone number with the department's own label, the office addresses, and **the URL a complaint is actually filed at**, which is the department's own intake page rather than anything on naic.org (a `mailto:` for the three Pacific territories that publish no web intake). Pass `{ jurisdiction }` as NAIC's name (\"Texas\") or the two-letter code (\"TX\") for one jurisdiction; omit it for the whole directory. `regulator` is null when the post is vacant — the site writes \"Pending\" and that must never reach a caller as a person's name — and `consumerHotline` is DERIVED from the department's own phone labels, so it is null when none of them names consumers or a toll-free line rather than falling back to the switchboard. THROWS rather than returning an empty list when the directory reads as empty, because a national regulator directory has no legitimate empty case and a silent [] would be a site re-skin reported as an answer.\n\nCalls `bowmark.providers.naic.listStateDepartments`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<naicStateDepartmentRow[]>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"query":{"$ref":"#/components/schemas/naicStateDepartmentQuery","description":"TypeScript: `naicStateDepartmentQuery`"}},"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/naic/getCompanyProfile":{"post":{"operationId":"getCompanyProfile","summary":"Reads the regulators' own financial report on ONE insurer, keyed on the NAIC company code `searchCompanies` returns — who owns it (`groupName`, the holding group NAIC records, which a carrier's own br","description":"Reads the regulators' own financial report on ONE insurer, keyed on the NAIC company code `searchCompanies` returns — who owns it (`groupName`, the holding group NAIC records, which a carrier's own branding routinely does not give), which regulator actually supervises it (`stateOfDomicile`, commonly neither where it is headquartered nor where it sells: GEICO Secure is domiciled in NE and headquartered in MD), when it was first authorized, what kind of insurer it is by the annual-statement blank it files, and the balance sheet behind the promises — assets, liabilities and `capitalAndSurplus`, plus three years of net income and the lines of business it actually writes by direct premium. Read `financialYear` before comparing two carriers: every figure is as of that statement year and two companies can be on different ones. Two things a caller must not misread: `hasReport: false` does NOT mean the company does not exist — an invented code and a real carrier NAIC files nothing for are indistinguishable on this surface, so confirm the code against `searchCompanies` if that matters — and `complaintCountByYear` is a raw count rather than the market-share-normalized complaint index, which is what `getComplaintIndex` returns.\n\nCalls `bowmark.providers.naic.getCompanyProfile`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<naicCompanyProfile>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cocode":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"TypeScript: `string | number`"}},"required":["cocode"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}},"/v1/sites/naic/getLicensing":{"post":{"operationId":"getLicensing","summary":"Reads the regulators' own licensing record for ONE insurer, keyed on the NAIC company code `searchCompanies` returns — the authoritative answer to whether a carrier may legally write the policy it is ","description":"Reads the regulators' own licensing record for ONE insurer, keyed on the NAIC company code `searchCompanies` returns — the authoritative answer to whether a carrier may legally write the policy it is quoting you, and in which lines. Returns ALL 56 jurisdictions NAIC tracks (the 50 states, DC, and PR/GU/VI/MP/AS), each with `licensed`, the report's own `status` wording, and `insuranceTypes` — the lines it may write THERE (\"Auto\", \"Homeowners\", \"Flood\", \"Earthquake\", \"Commercial Auto\", \"Aircraft\", \"Other\"), which is the half `searchCompanies.licensedStates` does not carry: that field answers WHERE, this one answers where AND what. Licensure is per state and per line, so a carrier licensed for Auto in a state is not thereby licensed for Homeowners there. Two things a caller must not misread: `insuranceTypes` at the top level is a union across every jurisdiction and is never a statement about one of them — read `states[].insuranceTypes` for that; and `hasReport: false` does NOT mean the company does not exist, since an invented code and a real carrier with no licensing record return byte-identical empty dashboards, so confirm the code against `searchCompanies` if that distinction matters. Finally, this `licensedStates` is deliberately a LONGER list than the field of the same name on `searchCompanies`: measured on 14137, the CSV register lists 36 jurisdictions and this report lists 42, and the six it adds (AL, DE, LA, MN, NJ, NM) are exactly the six whose only licence is the residual \"Other\" line — the register enumerates the six named CIS report categories and drops anything outside them. The register is a strict subset and never claims a jurisdiction this report denies, so for \"may this carrier write here at all\", this is the field that answers it.\n\nCalls `bowmark.providers.naic.getLicensing`. The body is the function's arguments, keyed by parameter name. `result` in the response is what it returns: `Promise<naicLicensingReport>`.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"cocode":{"anyOf":[{"type":"string"},{"type":"number"}],"description":"TypeScript: `string | number`"}},"required":["cocode"],"additionalProperties":false}}}},"responses":{"200":{"description":"The call ran. That includes a call that failed (`status: error`) or paused for a sign-in (`status: needs_user`), so branch on `status`.","content":{"application/json":{"schema":{"allOf":[{"$ref":"#/components/schemas/RunEnvelope"},{"type":"object","properties":{"result":{}}}]}}}},"400":{"description":"The body was malformed. `error` says what to send.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"401":{"description":"No API key, or a key that was refused.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"402":{"description":"The account is out of free usage, at its spend cap, or its card was declined. Fix billing at https://bowmark.ai/dashboard/billing.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}},"404":{"$ref":"#/components/responses/NotFound"},"429":{"description":"Too many runs in flight on this account. Nothing was started or charged.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}},"headers":{"Retry-After":{"schema":{"type":"integer"},"description":"Seconds to wait."}}},"503":{"description":"A failure on Bowmark's side. Retry.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}}}}},"components":{"securitySchemes":{"bearer":{"type":"http","scheme":"bearer","description":"Your Bowmark API key."},"apiKeyHeader":{"type":"apiKey","in":"header","name":"X-Bowmark-Key"}},"responses":{"NotFound":{"description":"No such site or function.","content":{"application/json":{"schema":{"$ref":"#/components/schemas/RunEnvelope"}}}}},"schemas":{"RunEnvelope":{"type":"object","description":"What a run returns. `status` says whether the SCRIPT succeeded. A script that threw or paused for a login is still HTTP 200. Branch on `status`, not on the HTTP code.","required":["ok","status","result","logs","error","ms"],"properties":{"runId":{"type":"string","description":"Stable id for this run. Quote it in a support or `report` message."},"ok":{"type":"boolean","description":"False only when the run produced nothing usable."},"status":{"type":"string","enum":["ok","error","partial","needs_user"],"description":"`partial`: the result is real but some calls failed (see `incomplete`); `ok` stays true. `needs_user`: a person must sign in to a site first. Relay `meta.handoff.url` to them, then run again."},"egress":{"type":"string","enum":["default","link"],"description":"The egress the run was given, present only when the request asked for one. `link`: every request went through the caller's own Chrome (Bowmark Buddy)."},"result":{"description":"Whatever the script `return`ed. Any JSON value."},"logs":{"type":"array","items":{"type":"string"},"description":"Lines the script wrote with `log(...)`."},"error":{"type":["string","null"],"description":"Why the run failed, in plain words. Null on success."},"ms":{"type":"integer","description":"How long the script itself ran, in milliseconds."},"queuedMs":{"type":"integer","description":"How long the run waited for a worker before starting. Present only when it was a second or more."},"needs":{"type":"array","description":"The sign-ins this script is waiting on. Present when `status` is `needs_user`.","items":{"type":"object","required":["capability","provider","providerTitle","kind"],"properties":{"capability":{"type":"string"},"provider":{"type":"string"},"providerTitle":{"type":"string","description":"The site's name, to show a person."},"kind":{"type":"string"}}}},"incomplete":{"type":"object","description":"Present only when `status` is `partial`: which calls did not answer.","properties":{"summary":{"type":"string"},"totalCalls":{"type":"integer"}},"additionalProperties":true},"emptyHanded":{"type":"object","description":"Present when the script returned nothing while its calls returned rows, usually a filter that matched none of the site's own labels. Lists the label values the calls actually returned.","additionalProperties":true},"notes":{"type":"array","description":"Caveats a call attached to a complete answer. Never changes `status`.","items":{"type":"object","properties":{"path":{"type":"string"},"notes":{"type":"array","items":{"type":"string"}}}}},"meta":{"type":"object","properties":{"handoff":{"type":"object","description":"A single-use sign-in link for a person to open. Expires at `expiresAt`.","properties":{"ref":{"type":"string"},"url":{"type":"string","format":"uri"},"expiresAt":{"type":"string","format":"date-time"}}},"concurrency":{"type":"object","description":"On a 429: how many runs are in flight and when to retry.","properties":{"limit":{"type":"integer"},"inFlight":{"type":"integer"},"retryAfterSeconds":{"type":"integer"}}}},"additionalProperties":true},"notice":{"type":"object","description":"Set when the account owner has not accepted the current Terms. Relay it to them.","additionalProperties":true}}},"naicCompanyQuery":{"type":"object","properties":{"name":{"type":"string"},"homeState":{"type":"string"}},"additionalProperties":true},"naicStateDepartmentQuery":{"type":"object","properties":{"jurisdiction":{"type":"string"}},"additionalProperties":true}}}}