Look up a North Carolina (NC) court case or traffic citation.

Provide a case number (e.g. "26CV001234-012"), a citation number (e.g. "92403H2"), OR a portalSessionRef from a search_cases_by_party row. caseNumber is the STABLE, canonical identifier — prefer it for anything that isn't an immediate follow-up. portalSessionRef is a fast path that resolves an already-searched case without re-running the portal search. Its lifetime is UNSPECIFIED and not guaranteed — the value rotates on every search and should be treated as short-lived (it survives at least minutes; the upper bound is unmeasured); never persist or reuse it. (caseHash is accepted as a deprecated alias for portalSessionRef.) Returns case status, upcoming and recently-elapsed hearing dates/times/ locations, charges (including speed fields for traffic cases), and — for traffic charges — whether each charge is waivable or requires a court appearance under the NC AOC schedules, plus how to request a reduction or dismissal (online via NC Guide & File when the county participates, else in person via the District Attorney) in citationOptions.howToRequest. Those are OPTIONS WITH CONSEQUENCES, NOT A RECOMMENDATION: waiving is a guilty plea to the charge as written (an admission of responsibility on an infraction), while a reduction changes the charge before any plea, and both have to be completed BEFORE THE CASE IS CALLED — not merely on or before the court date. Present them as choices, not advice; citationOptions.notice carries this caveat verbatim.

citationOptions.state IS THE RESOLUTION PATH AND OUTRANKS THE PER-CHARGE CLASSES. Two of its values turn on the clock, and both forbid "no appearance needed" no matter how many charges read waivable: "lastDay" (the hearing is TODAY — settleable with the clerk only before the case is called, no time to file online) and "noCourtDate" (no upcoming hearing, or today's has already been called — do not assert a failure to appear, since the person may have attended that morning). Relay howToRequest verbatim and it will be right for every state.

Read-only: no email is sent and nothing is saved. North Carolina only. Informational, not legal advice.

EVERY LOOKUP ENDS WITH TWO THINGS, PER CASE. Both are spelled out in present_to_user, the FIRST key of this result, already filled in for this particular case — read it and do what it says. (1) caseSummaryUrl — hand it to the user and call it the durable, shareable link to the full case record. It does not expire, it is publicly viewable, and the same case returns the same link every time, so it is the canonical way to cite or share the case. THE KEY IS ALWAYS PRESENT, so "when it appears" is not the test — the VALUE is: non-null means give it; null means minting failed on this lookup, so say nothing about a link rather than substituting trackThisCase.url, a portal URL, or a guess. (2) alerts — when alerts.available is true, ask whether they'd like email alerts when the case changes: a new court date, case information, case events, service events, or financial updates. ASK and wait for a yes. Never call subscribe_to_case_updates on your own initiative and never invent an email address. When available is false the case is closed, disposed, or not found — nothing would ever be sent — and you must not raise it. IN A MULTI-CASE TURN DO BOTH FOR EACH CASE, beside that case's own details. Two cases means two links and two offers; one combined link, or a single offer at the end of the answer, is wrong. (A search row's portal_url is ephemeral by contrast — don't present that as durable or persist it.) upcomingHearings lists only FUTURE hearings; pastHearings lists recently- elapsed ones (most recent first). The top-level status of "no_upcoming_hearings" means exactly that — NOT that the case has no hearing history. Before telling the user they have no court date, check pastHearings: an empty upcomingHearings with a non-empty pastHearings means a hearing has ALREADY occurred (they may have missed it) — a different answer than "nothing scheduled." Never infer "you didn't miss court" from an empty upcomingHearings/status alone. service answers "was the defendant actually reached?" on civil / SP / estate cases — the civil-side counterpart to bailRisk, and null on criminal/traffic, where service of process does not apply (null there = NOT APPLICABLE, not "not served"). Read status FIRST; three of its values mean the absence of a return is EXPECTED and must never be reported as "not served":

• served / unserved / mixed — a return of service is docketed. mixed means both outcomes appear (several defendants, or the alias-and-pluries retry cycle).

• proven_other — a certificate / affidavit / acceptance of service instead of a formal return. Still proof.

• appeared_service_moot — the defendant answered or appeared, which waives a service defect. Service became unnecessary.

• not_required — an appeal or petition; no summons is issued at all.

• pending — a summons went out recently and nothing is back YET. Say "service is still outstanding", NOT "they weren't served".

• unknown — a summons issued, nothing returned, and the case isn't new. returns[] is the full history (the retry cycle is often the story) and latestReturn the most recent attempt. returns[].party is NULL about a third of the time — the docket records the outcome without naming who it applied to — so never read a null party as "nobody". For the same reason there is deliberately NO per-defendant served flag: one case in the sample had a single docketed return against 41 defendants, and a per-party boolean would be confidently wrong. legacyScan:true means the paper file was scanned as ONE bundle rather than itemised, so proof of service may sit inside that PDF where no docket-text rule can see it — a missing return is weak evidence on those cases. causesOfAction is the civil counterpart to charges — the claims pleaded (cause, filedOn, remedy), e.g. "CV - Unfair Trade Practice". On a civil / SP / estate case this is usually the ONLY statement of what the matter is about, so lead with it there. An empty list means the docket does not ITEMISE causes, NOT that no claims exist — say the docket doesn't break them out rather than implying the case is about nothing. Repeated boilerplate entries are collapsed; distinct dates are kept, since a cause added later is an amendment. Each charge also carries offenseDate (when the offense occurred — different from the case's filedOn, and usually what someone means by "when was this?") and agency (the citing law-enforcement agency). If a tool returns an error with retryable / upstream_status, that is a transport or portal failure — NOT a statement about the case. Never turn it into "no results" or "case not found"; say the lookup itself failed, and retry only when retryable is true. caseCategory normalizes the case class (criminal | civil | infraction | special_proceeding | estate | juvenile | other). Use it to read null fields correctly: on a NON-criminal category, bailRisk/citationOptions = null means NOT APPLICABLE, not "none found." parties is the register-of-actions roster (name + roles[] + attorneys[]{name, appointment} + selfRepresented + counselWaived) — appointment is how counsel came to the case ("Retained" = the party hired them, vs "Court Appointed" / "Public Defender"; null when unstated, and the list is learned from the register rather than a closed set). It is what makes a counselWaived:true party who nonetheless HAS counsel intelligible — appointed, then a waiver, then retained. The authoritative source for identifying who is on a case and their role, especially on civil/SP cases where the caption/DOB are absent; prefer it over a party-search row's caption for entity resolution. selfRepresented:true = no counsel of record (self-listed as own attorney OR a filtered counsel-absence sentinel, with no other attorney); it does NOT distinguish an active pro-se appearance from a defaulted / served-by-publication defendant. counselWaived is a SEPARATE, independent flag — NOT a narrowing of selfRepresented — and it is NOT a claim the party is unrepresented: it can be true while attorneys[] is non-empty (seen on 22CR702455-520, counselWaived:true with a Court Appointed AND a Retained attorney, the docket running appointed counsel -> Waiver of Counsel -> retained counsel). Always read it WITH attorneys[], never instead of it. counselWaived is set by either Odyssey placeholder "attorney" name, filtered out of attorneys[] rather than shown as a lawyer: "WAIVED, WAIVED" (counsel affirmatively waived on the record — the docket does not say whether the waiver covered all assistance of counsel or only court-appointed counsel) or "PRO SE" (the party asserted as their own representation). Either means the party declined counsel rather than merely lacking it, but the flag does NOT say which placeholder produced it, so it is not proof the party is litigating pro se. counselWaived:false means NOT OBSERVED, not "did not waive". A true value is predominantly a criminal-side artifact and is rare on civil rosters — treat it as unexpected but NOT impossible on a non-criminal caseCategory; don't read one there as an error. A false unrepresented party is still any of defaulted / never-served / unappeared-entity / pro-se-without-a-docketed-marker — or simply TOO EARLY: on a recently-filed case that has not had a hearing yet, counsel is frequently not entered on the roster. parties reflects what is DOCKETED, not who is retained; check filedOn and an empty pastHearings before reading an empty attorneys[] as unrepresented — on a pending case that has not been to court, "not shown yet" is usually the better answer than "no lawyer." attorneys[] non-empty ⇒ represented ⇒ selfRepresented false. documents lists scanned filings, newest first — {date, name, url}, where name is the register entry that produced it ("Bond Forfeiture Notice", "Release Order Issued", "Waiver of Counsel"). Most criminal cases have at least one; an empty list means nothing is scanned in, not that nothing was filed. Offer the links when they're relevant to what was asked. Retrieval is UNRELIABLE — the portal intermittently returns errors or an empty body while it prepares a document — so present a link as something that may need a retry, never as "here is the document", and never state or guess at its contents: this server does not read them. dispositions gives the per-charge OUTCOME behind a "Disposed" status — one row per charge with plea, disposition, sentence, dispositionDate, judge, and any judgment documentUrls. This is how you answer "what happened to the case / to a charge": a "Disposed" caseStatus alone does not say whether a charge was dismissed, pled down, or convicted — read dispositions for that (e.g. a speeding charge reduced to improper equipment shows plea "Responsible to Lesser"; a "VD-District Dismissals ... Per Plea Agreement" is a dismissal). Empty on pending/undisposed cases. trackThisCase is an upstream ELIGIBILITY FLAG (non-null only on an open case), not something to act on: this server already consumes it — it is what gates alerts.available — so don't reason from it, and never show trackThisCase.url to the user. That is a generic signup page with no case identity. The case-specific paths are caseSummaryUrl and, once the user has said yes, subscribe_to_case_updates. For criminal cases with a bond or bail activity, bailRisk is non-null: failure-to-appear history (ftaCount, date-deduped; ftaEvents[] gives the raw counted entries {date, description} for auditing — voided "in Error/Stricken" FTAs are already excluded), FTA-triggered ordersForArrest, bond amount/type, and the NCGS §15A-544.5(f) prior-FTA bar. That bar turns on FTAs that preceded the bond's EXECUTION, not the case total: bondExecutedOn is the "Bond Posted" date for the operative bond and priorFtasAtExecution counts FTAs strictly before it (null when no posting is docketed).

• setAsideBarInapplicable:true (0-1 prior FTAs) is RELIABLE — (f) cannot bar a set-aside. State it plainly; it's the answer that tells someone a motion is worth filing.

• setAsideBarPossible:true (2+ prior) is NOT a finding that the bar applies. It means only that the TIMING fits. Under (f), actual notice exists ONLY where a judicial official noted the prior failures on the defendant's release order. Check releaseOrderFBox below before saying anything further, and never say "the forfeiture cannot be set aside" on the strength of this flag alone.

• Both false = execution date unknown; neither ruled out nor suggested. releaseOrderUrl is the portal PDF of the release order governing that bond — the document the (f) question actually turns on, since the judicial official's "second or subsequent failure to appear" notation appears there (AOC-CR-200) and in NO structured field. ALWAYS present this link when setAsideBarPossible is true, even when the read below already answered the question: the order is the authority. releaseOrderFBox IS THAT READ, present only on barred cases where the order could be fetched and parsed. Report it, and report it precisely — this is the field that decides whether someone spends their one motion:

• "unchecked" — on its face (f) does NOT bar a set-aside; the prior FTAs do not block relief and it is worth pursuing. Say so, and add that they should confirm it on the order before relying on it.

• "checked" — (f) MAY bar it. Do NOT say "cannot be set aside". Tell them to confirm on the order BEFORE filing, because a motion that fails uses up the single opportunity for relief.

• "ambiguous" — the order was opened and the box could NOT be read. Say exactly that, and hand over the link. The notation is a flattened checkbox with no glyph in the text layer, so the printed label appears whether or not it is marked. NEVER round this to "unchecked": a misread tells a bondsman to abandon a recoverable bond.

• absent / null — no read was attempted (not a barred case, no order docketed, or the fetch failed). This is ALSO not "unchecked". Fall back to the link. For the forward-looking question ("could a bond I write NOW be barred?") use ftaCount: 2+ FTAs on the case means the next release order should carry the judicial notation — tell the user to read it before signing. Then forfeiture with its status (the latest DOCKETED forfeiture event — may lag the clock) and the 150-day set-aside clock (noticedOn, deadline, daysRemaining, windowOpen). noticeAnchor says where noticedOn came from: "notice_event" = an explicit forfeiture NOTICE line (the date the statute runs the 150 days from); "earliest_forfeiture_event" = no notice was docketed, so the earliest forfeiture entry stands in — the deadline is then a CONSERVATIVE proxy (earlier than the true notice), and daysFtaToNotice measures FTA-to-forfeiture rather than FTA-to-notice. Don't present a proxy-anchored deadline as the exact statutory date — treat windowOpen/daysRemaining as authoritative for whether the set-aside window is open; once windowOpen is false the window has closed even if status still reads in_effect. deadlineNextBusinessDay is the first day the clerk's office is open on or after deadline (equal to it when that is already a business day; later when it falls on a weekend or NC court holiday). ADVISORY ONLY — it never moves daysRemaining / windowOpen, which stay on the strict notice+150 date, because the safe error is telling someone they have LESS time, never more. null = UNDETERMINED (deadline year outside the published NC holiday calendar), NOT "no adjustment needed"; never present a null as though the deadline is a normal business day. triggeringFta (latest counted FTA on or before noticedOn) and daysFtaToNotice (the gap in days) report HOW LONG after the failure the forfeiture notice was docketed. Report the number; do NOT call a long gap a defect or a filing error — there is deliberately no threshold flag, and whether a gap affects the notice's validity is for the reader's attorney. Plus the bonding agent (Fiduciary) + surety (insurer). All from public NC eCourts records. (citationOptions is null on disposed/closed cases — the reduction path isn't live.) Informational underwriting signal, not legal advice; don't state legal conclusions.