{"openapi":"3.1.0","info":{"title":"AdverseSearch API","version":"1.0.0","description":"Source-backed adverse media screening for business workflows."},"servers":[{"url":"https://adversesearch.com/api/v1"}],"security":[{"bearerAuth":[]}],"paths":{"/screenings":{"post":{"operationId":"createScreening","summary":"Create an adverse media screening","parameters":[{"name":"Idempotency-Key","in":"header","required":true,"description":"Unique opaque key for this request body. Do not include personal data.","schema":{"type":"string","minLength":8,"maxLength":160,"pattern":"^[\\x21-\\x7E]+$"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/CreateScreening"}}}},"responses":{"200":{"description":"Existing screening replayed","headers":{"Location":{"description":"URL of the screening resource.","schema":{"type":"string"}},"Idempotent-Replay":{"description":"True when an earlier response was replayed.","schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Screening"}}}},"202":{"description":"Screening accepted","headers":{"Location":{"description":"URL of the screening resource.","schema":{"type":"string"}},"Idempotent-Replay":{"description":"True when an earlier response was replayed.","schema":{"type":"string","enum":["true","false"]}}},"content":{"application/json":{"schema":{"$ref":"#/components/schemas/Screening"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"413":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"},"503":{"$ref":"#/components/responses/Error"}}}},"/screenings/{screeningId}":{"get":{"operationId":"getScreening","summary":"Get a screening","parameters":[{"$ref":"#/components/parameters/ScreeningId"}],"responses":{"200":{"description":"Screening","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Screening"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"410":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}},"delete":{"operationId":"deleteScreening","summary":"Delete a screening and its findings","parameters":[{"$ref":"#/components/parameters/ScreeningId"}],"responses":{"204":{"description":"Deleted"},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/screenings/{screeningId}/cancel":{"post":{"operationId":"cancelScreening","summary":"Request cancellation","parameters":[{"$ref":"#/components/parameters/ScreeningId"}],"responses":{"202":{"description":"Cancellation requested","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Accepted"}}}},"400":{"$ref":"#/components/responses/Error"},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"409":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}},"/usage":{"get":{"operationId":"getUsage","summary":"Get workspace usage","responses":{"200":{"description":"Usage window","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Usage"}}}},"401":{"$ref":"#/components/responses/Error"},"403":{"$ref":"#/components/responses/Error"},"404":{"$ref":"#/components/responses/Error"},"429":{"$ref":"#/components/responses/Error"}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","bearerFormat":"API key"}},"parameters":{"ScreeningId":{"name":"screeningId","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}},"responses":{"Error":{"description":"Error","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}},"schemas":{"Subject":{"type":"object","additionalProperties":false,"required":["firstName","lastName"],"properties":{"firstName":{"type":"string","minLength":1,"maxLength":120},"middleName":{"type":"string","minLength":1,"maxLength":120},"lastName":{"type":"string","minLength":1,"maxLength":120},"dateOfBirth":{"type":"string","format":"date"},"country":{"type":"string","enum":["AD","ad","AE","ae","AF","af","AG","ag","AI","ai","AL","al","AM","am","AO","ao","AQ","aq","AR","ar","AS","as","AT","at","AU","au","AW","aw","AX","ax","AZ","az","BA","ba","BB","bb","BD","bd","BE","be","BF","bf","BG","bg","BH","bh","BI","bi","BJ","bj","BL","bl","BM","bm","BN","bn","BO","bo","BQ","bq","BR","br","BS","bs","BT","bt","BV","bv","BW","bw","BY","by","BZ","bz","CA","ca","CC","cc","CD","cd","CF","cf","CG","cg","CH","ch","CI","ci","CK","ck","CL","cl","CM","cm","CN","cn","CO","co","CR","cr","CU","cu","CV","cv","CW","cw","CX","cx","CY","cy","CZ","cz","DE","de","DJ","dj","DK","dk","DM","dm","DO","do","DZ","dz","EC","ec","EE","ee","EG","eg","EH","eh","ER","er","ES","es","ET","et","FI","fi","FJ","fj","FK","fk","FM","fm","FO","fo","FR","fr","GA","ga","GB","gb","GD","gd","GE","ge","GF","gf","GG","gg","GH","gh","GI","gi","GL","gl","GM","gm","GN","gn","GP","gp","GQ","gq","GR","gr","GS","gs","GT","gt","GU","gu","GW","gw","GY","gy","HK","hk","HM","hm","HN","hn","HR","hr","HT","ht","HU","hu","ID","id","IE","ie","IL","il","IM","im","IN","in","IO","io","IQ","iq","IR","ir","IS","is","IT","it","JE","je","JM","jm","JO","jo","JP","jp","KE","ke","KG","kg","KH","kh","KI","ki","KM","km","KN","kn","KP","kp","KR","kr","KW","kw","KY","ky","KZ","kz","LA","la","LB","lb","LC","lc","LI","li","LK","lk","LR","lr","LS","ls","LT","lt","LU","lu","LV","lv","LY","ly","MA","ma","MC","mc","MD","md","ME","me","MF","mf","MG","mg","MH","mh","MK","mk","ML","ml","MM","mm","MN","mn","MO","mo","MP","mp","MQ","mq","MR","mr","MS","ms","MT","mt","MU","mu","MV","mv","MW","mw","MX","mx","MY","my","MZ","mz","NA","na","NC","nc","NE","ne","NF","nf","NG","ng","NI","ni","NL","nl","NO","no","NP","np","NR","nr","NU","nu","NZ","nz","OM","om","PA","pa","PE","pe","PF","pf","PG","pg","PH","ph","PK","pk","PL","pl","PM","pm","PN","pn","PR","pr","PS","ps","PT","pt","PW","pw","PY","py","QA","qa","RE","re","RO","ro","RS","rs","RU","ru","RW","rw","SA","sa","SB","sb","SC","sc","SD","sd","SE","se","SG","sg","SH","sh","SI","si","SJ","sj","SK","sk","SL","sl","SM","sm","SN","sn","SO","so","SR","sr","SS","ss","ST","st","SV","sv","SX","sx","SY","sy","SZ","sz","TC","tc","TD","td","TF","tf","TG","tg","TH","th","TJ","tj","TK","tk","TL","tl","TM","tm","TN","tn","TO","to","TR","tr","TT","tt","TV","tv","TW","tw","TZ","tz","UA","ua","UG","ug","UM","um","US","us","UY","uy","UZ","uz","VA","va","VC","vc","VE","ve","VG","vg","VI","vi","VN","vn","VU","vu","WF","wf","WS","ws","YE","ye","YT","yt","ZA","za","ZM","zm","ZW","zw"],"description":"Valid ISO 3166-1 alpha-2 country code. Lowercase input is accepted and normalized to uppercase."},"state":{"type":"string","minLength":1,"maxLength":120},"city":{"type":"string","minLength":1,"maxLength":120},"gender":{"type":"string","minLength":1,"maxLength":50},"phone":{"type":"string","pattern":"^\\+[1-9]\\d{6,14}$","description":"E.164 phone number."},"email":{"type":"string","format":"email","maxLength":320}}},"CreateScreening":{"type":"object","additionalProperties":false,"required":["subject"],"properties":{"subject":{"$ref":"#/components/schemas/Subject"},"referenceId":{"type":"string","minLength":1,"maxLength":120,"description":"Opaque customer reference. Do not include personal data."},"searchDepth":{"type":"string","enum":["standard","enhanced"],"default":"standard"}}},"Screening":{"type":"object","additionalProperties":false,"required":["id","object","status","outcome","failureCode","referenceId","searchDepth","createdAt","completedAt","expiresAt","subject","findings","coverage","limitations"],"properties":{"id":{"type":"string","format":"uuid"},"object":{"type":"string","const":"screening"},"status":{"$ref":"#/components/schemas/ScreeningStatus"},"outcome":{"oneOf":[{"$ref":"#/components/schemas/ScreeningOutcome"},{"type":"null"}]},"failureCode":{"oneOf":[{"$ref":"#/components/schemas/ScreeningFailureCode"},{"type":"null"}],"description":"Stable diagnostic code for a terminal infrastructure or processing failure. A non-null value is not permission to retry automatically."},"referenceId":{"type":["string","null"],"maxLength":120},"searchDepth":{"type":"string","enum":["standard","enhanced"]},"createdAt":{"type":"string","format":"date-time"},"completedAt":{"type":["string","null"],"format":"date-time"},"expiresAt":{"type":"string","format":"date-time"},"subject":{"$ref":"#/components/schemas/Subject"},"findings":{"type":"array","items":{"$ref":"#/components/schemas/Finding"}},"coverage":{"$ref":"#/components/schemas/Coverage"},"limitations":{"type":"array","items":{"type":"string"}}}},"ScreeningStatus":{"type":"string","enum":["queued","searching","completed","incomplete","failed","cancelled"]},"ScreeningOutcome":{"type":"string","enum":["potential_match","no_verified_matches","inconclusive","search_incomplete"]},"ScreeningFailureCode":{"type":"string","enum":["PROVIDER_TEMPORARILY_UNAVAILABLE","PROVIDER_ACTION_REQUIRED","PROVIDER_QUOTA_EXHAUSTED","SCREENING_PROCESSING_FAILED","WORKER_INTERRUPTED"]},"Finding":{"type":"object","additionalProperties":false,"required":["id","category","eventStage","severity","title","summary","eventDate","identity","adverseRelevance","sources"],"properties":{"id":{"type":"string","format":"uuid"},"category":{"type":"string","enum":["corruption","cybercrime","financial_crime","fraud","legal","organized_crime","regulatory","terrorism","trafficking","violence","other"]},"eventStage":{"type":"string","enum":["allegation","investigation","charge","conviction","enforcement","acquittal","dismissal","other"]},"severity":{"type":"string","enum":["low","medium","high","critical"]},"title":{"type":"string"},"summary":{"type":"string"},"eventDate":{"type":["string","null"],"format":"date"},"identity":{"$ref":"#/components/schemas/IdentityAssessment"},"adverseRelevance":{"$ref":"#/components/schemas/Confidence"},"sources":{"type":"array","items":{"$ref":"#/components/schemas/Source"}}}},"IdentityAssessment":{"type":"object","additionalProperties":false,"required":["confidence","matchedAttributes","conflictingAttributes"],"properties":{"confidence":{"$ref":"#/components/schemas/Confidence"},"matchedAttributes":{"type":"array","items":{"type":"string"}},"conflictingAttributes":{"type":"array","items":{"type":"string"}}}},"Confidence":{"type":"string","enum":["low","medium","high"]},"Source":{"type":"object","additionalProperties":false,"required":["title","url","domain","publishedAt","excerpt"],"properties":{"title":{"type":"string"},"url":{"type":"string","format":"uri"},"domain":{"type":"string"},"publishedAt":{"type":["string","null"],"format":"date"},"excerpt":{"type":"string"}}},"Coverage":{"type":"object","additionalProperties":false,"required":["complete","searchesCompleted","sourcesReviewed"],"properties":{"complete":{"type":"boolean","description":"True only when the planned search finished without material coverage gaps."},"searchesCompleted":{"type":"integer","minimum":0,"description":"Distinct search queries with at least one successful upstream response."},"sourcesReviewed":{"type":"integer","minimum":0}}},"Usage":{"type":"object","additionalProperties":false,"required":["used","limit","remaining","resetsAt"],"properties":{"used":{"type":"integer","minimum":0},"limit":{"type":"integer","minimum":0},"remaining":{"type":"integer","minimum":0},"resetsAt":{"type":"string","format":"date-time"}}},"Accepted":{"type":"object","additionalProperties":false,"required":["accepted"],"properties":{"accepted":{"type":"boolean","const":true}}},"Error":{"type":"object","additionalProperties":false,"required":["error"],"properties":{"error":{"type":"object","additionalProperties":false,"required":["code","message","requestId"],"properties":{"code":{"type":"string"},"message":{"type":"string"},"requestId":{"type":"string"},"details":{"type":"object","additionalProperties":true}}}}}}}}