{"openapi":"3.1.0","info":{"title":"api-tradecheck","version":"0.1.0","description":"Contractor license verification for Oregon and Washington, from state open data. Not a consumer report: do not use it for FCRA purposes.","contact":{"email":"support@elysianintelligence.com","url":"https://elysianintelligence.com"}},"servers":[{"url":"https://api.elysianintelligence.com/tradecheck"}],"components":{"securitySchemes":{"ApiKey":{"type":"http","scheme":"bearer","description":"Send 'x-api-key: <key>' instead if you prefer."}},"schemas":{},"parameters":{}},"paths":{"/status":{"get":{"summary":"Dataset freshness","responses":{"200":{"description":"When each dataset last updated","content":{"application/json":{"schema":{"type":"object","properties":{"api":{"type":"string"},"version":{"type":"string"},"datasets":{"type":"array","items":{"type":"object","properties":{"name":{"type":"string"},"last_success_at":{"type":["string","null"]},"row_count":{"type":["number","null"]},"last_error":{"type":["string","null"]}},"required":["name","last_success_at","row_count","last_error"]}},"notes":{"type":"array","items":{"type":"string"}}},"required":["api","version","datasets"]}}}}}}},"/v1/keys":{"post":{"summary":"Get a free API key","description":"The key is shown once. Store it; only a hash is kept. Sign up on https://elysianintelligence.com/signup/, which solves the bot check (Cloudflare Turnstile) for you.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"email":{"type":"string","maxLength":254},"turnstile_token":{"type":"string","maxLength":2048},"accept_terms":{"type":"string","maxLength":16,"description":"The version of the API Terms of Service (https://elysianintelligence.com/terms/) you accept. Must be \"1.0\"."},"certify_tradecheck":{"type":"string","maxLength":32,"description":"Send \"tradecheck-fcra-v1\" to certify that you will use TradeCheck data only for permitted purposes and never as a factor in eligibility for credit, insurance, employment, housing or any purpose under 15 U.S.C. § 1681b (FCRA). TradeCheck serves no data without it."}},"required":["email"]}}}},"responses":{"201":{"description":"Key created","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"prefix":{"type":"string"},"plan":{"type":"string","enum":["free","starter","pro","payg","lapsed"]}},"required":["key","prefix","plan"]}}}}}}},"/v1/keys/rotate":{"post":{"security":[{"ApiKey":[]}],"summary":"Rotate your API key","description":"Makes a new key for the same account and revokes the key you send, in one step. The plan, prepaid calls, subscription, usage, terms acceptance and TradeCheck certification move to the new key. The new key is shown once. Apps connected over OAuth must sign in again with the new key. We email the account about every rotation.","responses":{"201":{"description":"Key rotated","content":{"application/json":{"schema":{"type":"object","properties":{"key":{"type":"string"},"prefix":{"type":"string"},"plan":{"type":"string","enum":["free","starter","pro","payg","lapsed"]}},"required":["key","prefix","plan"]}}}}}}},"/v1/keys/revoke":{"post":{"security":[{"ApiKey":[]}],"summary":"Revoke your API key","description":"Stops the key you send at once, for good. A key with a live subscription or prepaid calls left cannot be revoked: rotate it instead, so they move to a new key. We email the account about every revoke. After the last key of an account is revoked, a new key needs a new sign-up or a request to support.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm":{"type":"string","maxLength":32,"description":"Send \"revoke\" to confirm. This cannot be undone."}},"required":["confirm"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"revoked":{"type":"boolean","enum":[true]},"active_keys_left":{"type":"integer"},"message":{"type":"string"}},"required":["revoked","active_keys_left","message"]}}}}}}},"/v1/keys/close-account":{"post":{"security":[{"ApiKey":[]}],"summary":"Close your account","description":"Revokes every key of the account (the email of the key you send) and closes the account. Cancel any subscription first. Prepaid calls that are left end with the account. We email the account, delete its email address and key records 30 days after closure, and keep billing records for seven years without the email address, as the privacy policy (https://elysianintelligence.com/privacy/) says.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"confirm":{"type":"string","maxLength":32,"description":"Send \"close-account\" to confirm. This cannot be undone."}},"required":["confirm"]}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"closed":{"type":"boolean","enum":[true]},"keys_closed":{"type":"integer"},"message":{"type":"string"}},"required":["closed","keys_closed","message"]}}}}}}},"/v1/keys/accept-terms":{"post":{"security":[{"ApiKey":[]}],"summary":"Accept the API Terms of Service","description":"For a key made before the terms, or before their current version. Billing sells nothing to a key until it accepts the current version.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"accept_terms":{"type":"string","maxLength":16,"description":"The version of the API Terms of Service (https://elysianintelligence.com/terms/) you accept. Must be \"1.0\"."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"terms_version":{"type":"string"}},"required":["terms_version"]}}}}}}},"/v1/keys/certify-tradecheck":{"post":{"security":[{"ApiKey":[]}],"summary":"Certify the TradeCheck FCRA terms","description":"TradeCheck serves no data to a key until it certifies section 6.1(c) of the terms.","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"certify":{"type":"string","maxLength":32,"description":"Send \"tradecheck-fcra-v1\" to certify that you will use TradeCheck data only for permitted purposes and never as a factor in eligibility for credit, insurance, employment, housing or any purpose under 15 U.S.C. § 1681b (FCRA). TradeCheck serves no data without it."}}}}}},"responses":{"200":{"description":"OK","content":{"application/json":{"schema":{"type":"object","properties":{"tradecheck_certified":{"type":"boolean","enum":[true]}},"required":["tradecheck_certified"]}}}}}}},"/v1/license":{"get":{"summary":"Returns the license records for one license number in one state, with days until expiration and warning flags.","tags":["get_license"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","enum":["OR","WA"],"description":"Two letter state code: OR or WA."},"required":true,"description":"Two letter state code: OR or WA.","name":"state","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":40,"description":"The license number, as the state prints it."},"required":true,"description":"The license number, as the state prints it.","name":"number","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"disclaimer":{"type":"string"},"refreshed_at":{"type":"object","additionalProperties":{"type":["string","null"]},"description":"When the data of each state was last checked against the state."},"count":{"type":"number"},"results":{"type":"array","items":{"type":"object","properties":{"state":{"type":"string"},"license_number":{"type":"string"},"license_type":{"type":"string"},"classification":{"type":["string","null"]},"business_name":{"type":"string"},"principal":{"type":["string","null"]},"status":{"type":"string","enum":["active","inactive","expired","suspended","revoked","other","removed"],"description":"Status today. A license past its expiration date is shown as expired. 'removed' means the state no longer lists it."},"status_raw":{"type":["string","null"],"description":"The state's own wording, when the state gives one."},"issue_date":{"type":["string","null"]},"expiration_date":{"type":["string","null"]},"bond":{"type":"object","properties":{"company":{"type":["string","null"]},"amount":{"type":["number","null"]},"expiration":{"type":["string","null"]}},"required":["company","amount","expiration"]},"insurance":{"type":"object","properties":{"company":{"type":["string","null"]},"amount":{"type":["number","null"]},"expiration":{"type":["string","null"]}},"required":["company","amount","expiration"]},"days_until_expiration":{"type":"object","properties":{"license":{"type":["number","null"]},"bond":{"type":["number","null"]},"insurance":{"type":["number","null"]}},"required":["license","bond","insurance"],"description":"Negative when the date has passed."},"flags":{"type":"array","items":{"type":"string","enum":["expired","expiring_30d","bond_expired","bond_expiring_30d","insurance_expired","insurance_expiring_30d","not_active"]}},"address":{"type":"object","properties":{"street":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"zip":{"type":["string","null"]}},"required":["street","city","state","zip"]},"phone":{"type":["string","null"]},"county":{"type":["string","null"]},"source":{"type":"object","properties":{"agency":{"type":"string"},"terms_url":{"type":"string"},"last_seen_at":{"type":"string","description":"The start of the last pass in which the state listed this license."}},"required":["agency","terms_url","last_seen_at"]},"verify_at":{"type":"string","description":"The state's own license lookup."}},"required":["state","license_number","license_type","classification","business_name","principal","status","status_raw","issue_date","expiration_date","bond","insurance","days_until_expiration","flags","address","phone","county","source","verify_at"]}}},"required":["disclaimer","refreshed_at","count","results"]}}}}}}},"/v1/search":{"get":{"summary":"Finds contractors by business name (starts with, or contains), city, zip, license type or status. City, zip and 'contains' need a state.","tags":["search_contractors"],"security":[{"ApiKey":[]}],"parameters":[{"schema":{"type":"string","minLength":1,"maxLength":100,"description":"Business name. Case and punctuation do not matter."},"required":false,"description":"Business name. Case and punctuation do not matter.","name":"name","in":"query"},{"schema":{"type":"string","enum":["prefix","contains"],"default":"prefix","description":"'contains' needs a state and at least 3 characters, and it is slower."},"required":false,"description":"'contains' needs a state and at least 3 characters, and it is slower.","name":"match","in":"query"},{"schema":{"type":"string","enum":["OR","WA"],"description":"Two letter state code: OR or WA."},"required":false,"description":"Two letter state code: OR or WA.","name":"state","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":60,"description":"Needs a state."},"required":false,"description":"Needs a state.","name":"city","in":"query"},{"schema":{"type":"string","pattern":"^\\d{5}$","description":"Needs a state."},"required":false,"description":"Needs a state.","name":"zip","in":"query"},{"schema":{"type":"string","minLength":1,"maxLength":60,"description":"The license type code or name, for example RGC, CC or 'Electrical Contractor'."},"required":false,"description":"The license type code or name, for example RGC, CC or 'Electrical Contractor'.","name":"type","in":"query"},{"schema":{"type":"string","enum":["active","inactive","expired","suspended","revoked","other","removed"]},"required":false,"name":"status","in":"query"},{"schema":{"type":"integer","minimum":1,"maximum":100,"default":25},"required":false,"name":"limit","in":"query"},{"schema":{"type":"string","maxLength":400,"description":"The next_cursor of the last page."},"required":false,"description":"The next_cursor of the last page.","name":"cursor","in":"query"}],"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"disclaimer":{"type":"string"},"refreshed_at":{"type":"object","additionalProperties":{"type":["string","null"]},"description":"When the data of each state was last checked against the state."},"results":{"type":"array","items":{"type":"object","properties":{"state":{"type":"string"},"license_number":{"type":"string"},"license_type":{"type":"string"},"classification":{"type":["string","null"]},"business_name":{"type":"string"},"principal":{"type":["string","null"]},"status":{"type":"string","enum":["active","inactive","expired","suspended","revoked","other","removed"],"description":"Status today. A license past its expiration date is shown as expired. 'removed' means the state no longer lists it."},"status_raw":{"type":["string","null"],"description":"The state's own wording, when the state gives one."},"issue_date":{"type":["string","null"]},"expiration_date":{"type":["string","null"]},"bond":{"type":"object","properties":{"company":{"type":["string","null"]},"amount":{"type":["number","null"]},"expiration":{"type":["string","null"]}},"required":["company","amount","expiration"]},"insurance":{"type":"object","properties":{"company":{"type":["string","null"]},"amount":{"type":["number","null"]},"expiration":{"type":["string","null"]}},"required":["company","amount","expiration"]},"days_until_expiration":{"type":"object","properties":{"license":{"type":["number","null"]},"bond":{"type":["number","null"]},"insurance":{"type":["number","null"]}},"required":["license","bond","insurance"],"description":"Negative when the date has passed."},"flags":{"type":"array","items":{"type":"string","enum":["expired","expiring_30d","bond_expired","bond_expiring_30d","insurance_expired","insurance_expiring_30d","not_active"]}},"address":{"type":"object","properties":{"street":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"zip":{"type":["string","null"]}},"required":["street","city","state","zip"]},"phone":{"type":["string","null"]},"county":{"type":["string","null"]},"source":{"type":"object","properties":{"agency":{"type":"string"},"terms_url":{"type":"string"},"last_seen_at":{"type":"string","description":"The start of the last pass in which the state listed this license."}},"required":["agency","terms_url","last_seen_at"]},"verify_at":{"type":"string","description":"The state's own license lookup."}},"required":["state","license_number","license_type","classification","business_name","principal","status","status_raw","issue_date","expiration_date","bond","insurance","days_until_expiration","flags","address","phone","county","source","verify_at"]}},"next_cursor":{"type":["string","null"]}},"required":["disclaimer","refreshed_at","results","next_cursor"]}}}}}}},"/v1/verify":{"post":{"summary":"Checks one contractor and gives a verdict: active, restricted, inactive, not_found or ambiguous. Send a license number (best), or the full business name. One license number can hold several license types. The verdict is active when any is active, and `records` has every license. It is restricted when one type is active but another is suspended, revoked, or recently removed (the state stopped listing it). `disciplinary` is true when any type is suspended or revoked, or was when it was removed; `type_removed` is true when any type was removed in the last 12 months (older removals appear only in the reason). Both look at every type of the number, even when license_type narrows the verdict. Oregon lists only active licenses, so it cannot show a suspension directly: a suspended or revoked Oregon type just disappears and shows as a removed type. Send license_type to check one type only. A name must match exactly (case and punctuation do not matter), and only one license number may have that name. A name shared by several businesses, or that only starts the same, gives 'ambiguous' with candidates. The name is ignored when a number is sent.","tags":["verify_contractor"],"security":[{"ApiKey":[]}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","properties":{"state":{"type":"string","enum":["OR","WA"],"description":"Two letter state code: OR or WA."},"number":{"type":"string","minLength":1,"maxLength":40},"name":{"type":"string","minLength":1,"maxLength":100},"license_type":{"type":"string","minLength":1,"maxLength":60,"description":"Check only this license type, for example RGC or CC."}},"required":["state"]}}}},"responses":{"200":{"description":"Success","content":{"application/json":{"schema":{"type":"object","properties":{"disclaimer":{"type":"string"},"refreshed_at":{"type":"object","additionalProperties":{"type":["string","null"]},"description":"When the data of each state was last checked against the state."},"verdict":{"type":"string","enum":["active","restricted","inactive","not_found","ambiguous"]},"reason":{"type":"string"},"match":{"type":["object","null"],"properties":{"state":{"type":"string"},"license_number":{"type":"string"},"license_type":{"type":"string"},"classification":{"type":["string","null"]},"business_name":{"type":"string"},"principal":{"type":["string","null"]},"status":{"type":"string","enum":["active","inactive","expired","suspended","revoked","other","removed"],"description":"Status today. A license past its expiration date is shown as expired. 'removed' means the state no longer lists it."},"status_raw":{"type":["string","null"],"description":"The state's own wording, when the state gives one."},"issue_date":{"type":["string","null"]},"expiration_date":{"type":["string","null"]},"bond":{"type":"object","properties":{"company":{"type":["string","null"]},"amount":{"type":["number","null"]},"expiration":{"type":["string","null"]}},"required":["company","amount","expiration"]},"insurance":{"type":"object","properties":{"company":{"type":["string","null"]},"amount":{"type":["number","null"]},"expiration":{"type":["string","null"]}},"required":["company","amount","expiration"]},"days_until_expiration":{"type":"object","properties":{"license":{"type":["number","null"]},"bond":{"type":["number","null"]},"insurance":{"type":["number","null"]}},"required":["license","bond","insurance"],"description":"Negative when the date has passed."},"flags":{"type":"array","items":{"type":"string","enum":["expired","expiring_30d","bond_expired","bond_expiring_30d","insurance_expired","insurance_expiring_30d","not_active"]}},"address":{"type":"object","properties":{"street":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"zip":{"type":["string","null"]}},"required":["street","city","state","zip"]},"phone":{"type":["string","null"]},"county":{"type":["string","null"]},"source":{"type":"object","properties":{"agency":{"type":"string"},"terms_url":{"type":"string"},"last_seen_at":{"type":"string","description":"The start of the last pass in which the state listed this license."}},"required":["agency","terms_url","last_seen_at"]},"verify_at":{"type":"string","description":"The state's own license lookup."}},"required":["state","license_number","license_type","classification","business_name","principal","status","status_raw","issue_date","expiration_date","bond","insurance","days_until_expiration","flags","address","phone","county","source","verify_at"],"description":"The active license if there is one, else the first."},"records":{"type":"array","items":{"type":"object","properties":{"state":{"type":"string"},"license_number":{"type":"string"},"license_type":{"type":"string"},"classification":{"type":["string","null"]},"business_name":{"type":"string"},"principal":{"type":["string","null"]},"status":{"type":"string","enum":["active","inactive","expired","suspended","revoked","other","removed"],"description":"Status today. A license past its expiration date is shown as expired. 'removed' means the state no longer lists it."},"status_raw":{"type":["string","null"],"description":"The state's own wording, when the state gives one."},"issue_date":{"type":["string","null"]},"expiration_date":{"type":["string","null"]},"bond":{"type":"object","properties":{"company":{"type":["string","null"]},"amount":{"type":["number","null"]},"expiration":{"type":["string","null"]}},"required":["company","amount","expiration"]},"insurance":{"type":"object","properties":{"company":{"type":["string","null"]},"amount":{"type":["number","null"]},"expiration":{"type":["string","null"]}},"required":["company","amount","expiration"]},"days_until_expiration":{"type":"object","properties":{"license":{"type":["number","null"]},"bond":{"type":["number","null"]},"insurance":{"type":["number","null"]}},"required":["license","bond","insurance"],"description":"Negative when the date has passed."},"flags":{"type":"array","items":{"type":"string","enum":["expired","expiring_30d","bond_expired","bond_expiring_30d","insurance_expired","insurance_expiring_30d","not_active"]}},"address":{"type":"object","properties":{"street":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"zip":{"type":["string","null"]}},"required":["street","city","state","zip"]},"phone":{"type":["string","null"]},"county":{"type":["string","null"]},"source":{"type":"object","properties":{"agency":{"type":"string"},"terms_url":{"type":"string"},"last_seen_at":{"type":"string","description":"The start of the last pass in which the state listed this license."}},"required":["agency","terms_url","last_seen_at"]},"verify_at":{"type":"string","description":"The state's own license lookup."}},"required":["state","license_number","license_type","classification","business_name","principal","status","status_raw","issue_date","expiration_date","bond","insurance","days_until_expiration","flags","address","phone","county","source","verify_at"]},"description":"Every license of the matched license number, one per type."},"disciplinary":{"type":"boolean","description":"True when any license of the matched number (every type, even if license_type narrowed the verdict) is suspended or revoked, or was when the state stopped listing it in the last 12 months."},"type_removed":{"type":"boolean","description":"True when the state stopped listing any license type of the matched number (every type, even if license_type narrowed the verdict) in the last 12 months. Oregon shows a suspension or revocation only this way."},"candidates":{"type":"array","items":{"type":"object","properties":{"state":{"type":"string"},"license_number":{"type":"string"},"license_type":{"type":"string"},"classification":{"type":["string","null"]},"business_name":{"type":"string"},"principal":{"type":["string","null"]},"status":{"type":"string","enum":["active","inactive","expired","suspended","revoked","other","removed"],"description":"Status today. A license past its expiration date is shown as expired. 'removed' means the state no longer lists it."},"status_raw":{"type":["string","null"],"description":"The state's own wording, when the state gives one."},"issue_date":{"type":["string","null"]},"expiration_date":{"type":["string","null"]},"bond":{"type":"object","properties":{"company":{"type":["string","null"]},"amount":{"type":["number","null"]},"expiration":{"type":["string","null"]}},"required":["company","amount","expiration"]},"insurance":{"type":"object","properties":{"company":{"type":["string","null"]},"amount":{"type":["number","null"]},"expiration":{"type":["string","null"]}},"required":["company","amount","expiration"]},"days_until_expiration":{"type":"object","properties":{"license":{"type":["number","null"]},"bond":{"type":["number","null"]},"insurance":{"type":["number","null"]}},"required":["license","bond","insurance"],"description":"Negative when the date has passed."},"flags":{"type":"array","items":{"type":"string","enum":["expired","expiring_30d","bond_expired","bond_expiring_30d","insurance_expired","insurance_expiring_30d","not_active"]}},"address":{"type":"object","properties":{"street":{"type":["string","null"]},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"zip":{"type":["string","null"]}},"required":["street","city","state","zip"]},"phone":{"type":["string","null"]},"county":{"type":["string","null"]},"source":{"type":"object","properties":{"agency":{"type":"string"},"terms_url":{"type":"string"},"last_seen_at":{"type":"string","description":"The start of the last pass in which the state listed this license."}},"required":["agency","terms_url","last_seen_at"]},"verify_at":{"type":"string","description":"The state's own license lookup."}},"required":["state","license_number","license_type","classification","business_name","principal","status","status_raw","issue_date","expiration_date","bond","insurance","days_until_expiration","flags","address","phone","county","source","verify_at"]}},"verify_at":{"type":"string"}},"required":["disclaimer","refreshed_at","verdict","reason","match","records","disciplinary","type_removed","candidates","verify_at"]}}}}}}}},"webhooks":{}}