{"components":{"schemas":{"AdverseMediaHit":{"description":"A single adverse media hit","properties":{"analysis":{"$ref":"#/components/schemas/HitAnalysis"},"entities":{"description":"The screened entities this mention relates to. A single source may mention more than one screened party (e.g. two board members named in the same article). The engine currently returns a single entity per hit, so this array usually holds exactly one element.","items":{"$ref":"#/components/schemas/HitEntity"},"type":"array"},"id":{"description":"Opaque hit identifier, unique within an analysis run.","example":"OqD3UJde","type":"string"},"source":{"$ref":"#/components/schemas/HitSource"}},"type":"object"},"AdverseMediaJobCreated":{"description":"Response when a new adverse media job is created","properties":{"jobId":{"description":"Unique job identifier","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"},"status":{"description":"Job status","enum":["pending"],"example":"pending","type":"string"}},"type":"object"},"AdverseMediaJobStatus":{"description":"Lightweight job-lifecycle status. Does not include records or summary — call /result/... once status = completed.","properties":{"error":{"description":"Failure description; present when status = failed.","nullable":true,"type":"string"},"jobId":{"description":"Unique job identifier","example":"550e8400-e29b-41d4-a716-446655440000","type":"string"},"progress":{"allOf":[{"$ref":"#/components/schemas/JobProgress"}],"description":"Progress of the screening, suitable for showing a progress bar while the job runs. Present across the lifecycle; reaches 100% when status = completed."},"status":{"description":"Current job-lifecycle state.","enum":["pending","processing","completed","failed"],"example":"completed","type":"string"}},"type":"object"},"AdverseMediaRecord":{"description":"Per-company adverse media record","properties":{"analyzedAt":{"description":"When the analysis completed (ISO 8601)","example":"2026-05-28T09:33:28Z","type":"string"},"companyId":{"description":"Swedish organisationsnummer","example":"5569679656","type":"string"},"hits":{"description":"Adverse media hits, ordered by: score desc, direct over indirect (hops=0 first), authority desc, relevance desc, severity desc","items":{"$ref":"#/components/schemas/AdverseMediaHit"},"type":"array"},"hitsCount":{"description":"Total length of hits","example":3,"format":"int32","type":"integer"},"hitsCountConnected":{"description":"Number of hits where entities[].hops >= 1.","example":0,"format":"int32","type":"integer"},"hitsCountDirect":{"description":"Number of hits where entities[].hops == 0.","example":3,"format":"int32","type":"integer"},"stats":{"$ref":"#/components/schemas/RecordStats"},"summary":{"$ref":"#/components/schemas/AdverseMediaSummary"}},"type":"object"},"AdverseMediaResultEnvelope":{"description":"Standard Roaring multi-record envelope (status + records). For single-company endpoints records.length is always 1.","properties":{"records":{"description":"Adverse media records, one per analysed company","items":{"$ref":"#/components/schemas/AdverseMediaRecord"},"type":"array"},"status":{"$ref":"#/components/schemas/SearchResultStatus"}},"type":"object"},"AdverseMediaSummary":{"description":"AI-generated narrative summary, two flavours","properties":{"markdown":{"description":"Plain markdown narrative","type":"string"},"structured":{"$ref":"#/components/schemas/AdverseMediaSummaryStructured"}},"type":"object"},"AdverseMediaSummaryStructured":{"description":"Structured summary fields","properties":{"assessment":{"description":"Single-sentence risk assessment. Plain text — no markdown.","example":"Risknivån bedöms som begränsad givet att fyndet härrör från en källa med måttlig auktoritet.","type":"string"},"summary":{"description":"2–4 sentence narrative summary of findings. Plain text — no markdown.","example":"Tre källor med potentiellt negativ medierapportering har identifierats avseende CGA Holding AB.","type":"string"},"title":{"description":"Display title — typically entity name and identification number","example":"CGA Holding AB (5569679656)","type":"string"}},"type":"object"},"AuthorityFeatures":{"description":"Per-axis breakdown of source authority","properties":{"credibility":{"example":0.85,"format":"double","maximum":1,"minimum":0,"nullable":true,"type":"number"},"expertise":{"example":0.7,"format":"double","maximum":1,"minimum":0,"nullable":true,"type":"number"},"frequency":{"example":1,"format":"double","maximum":1,"minimum":0,"nullable":true,"type":"number"},"objectivity":{"example":0.7,"format":"double","maximum":1,"minimum":0,"nullable":true,"type":"number"},"origin":{"example":0.95,"format":"double","maximum":1,"minimum":0,"nullable":true,"type":"number"},"quality":{"example":0.9,"format":"double","maximum":1,"minimum":0,"nullable":true,"type":"number"}},"type":"object"},"BadRequest":{"description":"Returned when something is wrong in the request, e.g. failed argument validation or missed argument","properties":{"attributes":{"description":"Invalid attributes","items":{"$ref":"#/components/schemas/RequestAttribute"},"type":"array"},"error":{"default":"BadRequest","description":"Error name","type":"string"},"message":{"default":"Required arguments are missing in the request","description":"Description of the request error","type":"string"}},"type":"object"},"HitAnalysis":{"description":"Engine scoring and classification for the hit","properties":{"authorityFeatures":{"$ref":"#/components/schemas/AuthorityFeatures"},"authorityScore":{"description":"Source authority (credibility of source.site). 0.5 indicates the engine did not score this source; in that case all authorityFeatures properties are null.","example":0.87,"format":"double","maximum":1,"minimum":0,"type":"number"},"matchedName":{"description":"The name variant that produced the match (e.g. \"CGA Holding AB\"). Useful for explaining why a hit surfaced.","example":"CGA Holding AB","nullable":true,"type":"string"},"relevanceScore":{"description":"Confidence that the matched name actually refers to the queried entity in this source.","example":0.92,"format":"double","maximum":1,"minimum":0,"type":"number"},"riskClasses":{"description":"Risk categories assigned to this hit. Common values include \"Financial\" and \"Legal\".","example":["Financial"],"items":{"description":"Risk categories assigned to this hit. Common values include \"Financial\" and \"Legal\".","example":"[\"Financial\"]","type":"string"},"type":"array"},"score":{"description":"Compound adverse media score combining severity, authority, relevance and connection approximity.","example":0.78,"format":"double","maximum":1,"minimum":0,"type":"number"},"severityScore":{"description":"Adverse-media severity score of the source content. 0.5 indicates the engine did not score this source.","example":0.85,"format":"double","maximum":1,"minimum":0,"type":"number"}},"type":"object"},"HitEntity":{"description":"The screened entity that this hit relates to","properties":{"country":{"description":"ISO 3166-1 alpha-2 country code.","example":"SE","nullable":true,"type":"string"},"hops":{"description":"Distance in the connection graph from the queried company. 0 = the queried company itself. 1 = direct connection. >=2 = indirect.","example":0,"format":"int32","minimum":0,"type":"integer"},"id":{"description":"Swedish identification number — orgnr (10 digits) for companies or persnr (12 digits) for persons.","example":"197207315024","pattern":"^\\d{10}(\\d{2})?$","type":"string"},"isCurrent":{"description":"True if the relation to the queried company is current; false if it lies within the 2-year historical lookback window (e.g. a former board member). Always true for the queried company itself.","example":true,"type":"boolean"},"name":{"description":"Display name of the entity","example":"Eriksson, Mia","type":"string"},"relation":{"description":"Free-text Swedish label describing the relation to the queried company. Null for the queried company itself. Examples: \"Styrelseledamot\", \"Verklig huvudman\", \"Likvidator\".","nullable":true,"type":"string"},"relationType":{"description":"Machine-readable relation category. Null for the queried company itself. Values include `board_member`, `beneficial_owner`, `likvidator`, `signing_combination`, `related_company`. Open enum.","example":"board_member","nullable":true,"type":"string"},"type":{"description":"Entity type.","enum":["person","company"],"example":"person","type":"string"}},"type":"object"},"HitSource":{"description":"The mention itself — article / post / registry entry","properties":{"language":{"description":"ISO 639-1 language code detected on the source","example":"sv","nullable":true,"type":"string"},"link":{"description":"URL of the source","example":"https://www.newsworthy.se/artikel/102287/omsatte-2-9-miljoner","format":"uri","type":"string"},"searchProvider":{"description":"Which search provider returned this source. Currently always \"google\"; may include other providers in the future.","example":"google","type":"string"},"searchType":{"description":"Which search tab the source was returned from. \"web\" covers regular web search (including custom search engines); \"news\" is the news tab.","enum":["web","news"],"example":"news","type":"string"},"site":{"description":"Base domain of `link`. Authority is attributed against this site.","example":"newsworthy.se","type":"string"},"snippet":{"description":"Short preview text from the source, when available","nullable":true,"type":"string"},"title":{"description":"Title of the source","example":"Omsatte 2,9 miljoner – nu går EBT Halmstad AB i konkurs i Göteborg","type":"string"}},"type":"object"},"JobProgress":{"description":"Progress of a running screening, for showing a progress bar","nullable":true,"properties":{"documentsAnalyzed":{"description":"Number of web and news pages reviewed so far — a live indicator that the screening is making progress. This counts pages looked at, not adverse media findings. Not present until reviewing has begun.","example":21,"format":"int32","nullable":true,"type":"integer"},"label":{"description":"A ready-to-display description of the current stage (for example \"Searching the internet\"). This is display text only — its exact wording may change and may be returned in a different language, so do not switch on it; use `stage` for that. Show it directly, or map `stage` to your own translated text.","example":"Searching the internet","nullable":true,"type":"string"},"percent":{"description":"Approximate progress from 0 to 100, suitable for a progress bar. The value only ever increases as the screening advances, and is an estimate based on the current stage rather than an exact measurement. Reaches 100 once the screening has completed.","example":30,"format":"int32","maximum":100,"minimum":0,"nullable":true,"type":"integer"},"stage":{"description":"Current stage of the screening, as a stable key your application can switch on to choose what to show the user. This value is fixed and does not change with language or wording, so base any logic on it rather than on `label`. Stages advance in order: queued → searching → analysing → assembling → done (or failed).","enum":["queued","searching","analysing","assembling","done","failed","processing"],"example":"searching","type":"string"}},"type":"object"},"RecordStats":{"description":"Coverage stats for the analysis","properties":{"sourcesFlagged":{"description":"Funnel stage 2: number of scanned sources that received a risk score from the text-classifier or LLM analyser. These are candidates the engine considered worth analysing; the subset surviving the relevance/risk thresholds becomes the actual hits.","example":40,"format":"int32","type":"integer"},"sourcesScanned":{"description":"Total candidate sources scanned before filtering. Funnel stage 1: sources retrieved from web + news search.","example":120,"format":"int32","type":"integer"},"sourcesScannedNews":{"description":"Candidate sources scanned from the news search tab.","example":30,"format":"int32","type":"integer"},"sourcesScannedWeb":{"description":"Candidate sources scanned from web search (including custom search).","example":90,"format":"int32","type":"integer"}},"type":"object"},"RequestAttribute":{"description":"Incorrect attribute of request","properties":{"attribute":{"description":"Parameter name","type":"string"},"value":{"description":"Parameter value, subject for validation","type":"string"}},"type":"object"},"SearchResultStatus":{"description":"Roaring-standard lookup outcome","properties":{"code":{"description":"0 = found, 1 = not found","example":0,"format":"int32","type":"integer"},"text":{"description":"Human-readable outcome label","example":"Found","type":"string"}},"type":"object"},"ServerError":{"description":"Internal server error","properties":{"error":{"default":"InternalServerError","description":"Error name","type":"string"},"message":{"default":"An internal server error occurred, please contact the system administrator with information on the error","description":"Description of the request error","type":"string"}},"type":"object"}},"securitySchemes":{"OAuth2":{"description":"All requests require authentication via OAuth2 client credentials.\n\nBase URL: https://api.roaring.io\n\n1. Obtain a Consumer key and Consumer secret from https://developer.roaring.io/keys\n   (separate sandbox and production pairs).\n2. Request an access token by POSTing to the token endpoint:\n\n   POST https://api.roaring.io/token\n   Content-Type: application/x-www-form-urlencoded\n   Authorization: Basic base64(consumer-key:consumer-secret)\n\n   body: grant_type=client_credentials\n\n   Tokens are valid for 3600 seconds. The response contains an access_token of\n   type Bearer.\n3. Send the access token on every API call:\n\n   Authorization: Bearer <access_token>","flows":{"clientCredentials":{"tokenUrl":"https://api.roaring.io/token","scopes":{}}},"type":"oauth2"}}},"info":{"description":"Adverse media screening for Swedish companies. Submit via POST /{companyId} (default scope: single; pass ?type=extended for broader analysis). Poll status via GET /status/{jobId}. Fetch billed result via GET /result/{jobId} (single) or GET /result/extended/{jobId}.\n\nAll requests require authentication via OAuth2 client credentials.\n\nBase URL: https://api.roaring.io\n\n1. Obtain a Consumer key and Consumer secret from https://developer.roaring.io/keys\n   (separate sandbox and production pairs).\n2. Request an access token by POSTing to the token endpoint:\n\n   POST https://api.roaring.io/token\n   Content-Type: application/x-www-form-urlencoded\n   Authorization: Basic base64(consumer-key:consumer-secret)\n\n   body: grant_type=client_credentials\n\n   Tokens are valid for 3600 seconds. The response contains an access_token of\n   type Bearer.\n3. Send the access token on every API call:\n\n   Authorization: Bearer <access_token>","title":"Adverse Media - Company","version":"1.0","x-logo":{"url":"https://assets.roaring.io/svg/adverse_media.svg"}},"openapi":"3.0.1","paths":{"/{companyId}":{"post":{"description":"Submits an adverse media analysis for the given company. Use ?type=extended for company + connected entities. Default (no param or ?type=single) analyses only the queried company.","operationId":"submitJob","parameters":[{"in":"path","name":"companyId","required":true,"schema":{"type":"string"}},{"description":"Scope of the adverse media analysis. **single**: Analyses only the queried company (default). **extended**: Analyses the company and all connected entities (board members, beneficial owners, etc.). ","example":"single","in":"query","name":"type","schema":{"default":"single","enum":["single","extended"],"type":"string"}}],"responses":{"202":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdverseMediaJobCreated"}}}},"400":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/BadRequest"}}}},"429":{"description":"Service at capacity — too many concurrent investigations. Retry later."},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerError"}}}}},"summary":"Submit an adverse media analysis","tags":["submit"]}},"/status/{jobId}":{"get":{"description":"Returns current job-lifecycle status. Cheap; does NOT include records or summary. Shared across all scopes — the jobId already encodes which analysis was submitted.","operationId":"getJobStatus","parameters":[{"in":"path","name":"jobId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdverseMediaJobStatus"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerError"}}}}},"summary":"Poll job status","tags":["status"]}},"/result/{jobId}":{"get":{"description":"Returns the adverse media result for a single-scope analysis. **Billed.** Returns 409 if the job is not yet completed.","operationId":"getResult","parameters":[{"in":"path","name":"jobId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdverseMediaResultEnvelope"}}}},"404":{"description":"Job not found or expired, or the job was run with a different scope (error \"ScopeMismatch\" — fetch it from the matching result endpoint)."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdverseMediaJobStatus"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerError"}}}}},"summary":"Fetch the completed result (single/default)","tags":["result"]}},"/result/extended/{jobId}":{"get":{"description":"Returns adverse media result with direct + connected entity hits. **Billed.** Returns 409 if the job is not yet completed.","operationId":"getExtendedResult","parameters":[{"in":"path","name":"jobId","required":true,"schema":{"type":"string"}}],"responses":{"200":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdverseMediaResultEnvelope"}}}},"404":{"description":"Job not found or expired, or the job was run with a different scope (error \"ScopeMismatch\" — fetch it from the matching result endpoint)."},"409":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/AdverseMediaJobStatus"}}}},"500":{"content":{"application/json":{"schema":{"$ref":"#/components/schemas/ServerError"}}}}},"summary":"Fetch the completed result (extended)","tags":["result"]}}},"security":[{"OAuth2":[]}],"servers":[{"url":"https://api.roaring.io/se/company/adverse-media/1.0"}],"x-category":"company","x-countries":["se"],"x-id":"AdverseMediaCompanySe"}