{"openapi":"3.1.0","info":{"title":"LookupYou API","version":"1.0.0","description":"Programmatic access to LookupYou people search. Authentication with an API key from the dashboard. Searches run sequentially at the source, so use `mode: \"async\"` with a webhook for batches."},"servers":[{"url":"https://lookupyou.com/api/v1"}],"security":[{"bearerAuth":[]}],"tags":[{"name":"search","description":"Run searches and read results"},{"name":"account","description":"Balance, packages and limits"}],"paths":{"/search":{"post":{"tags":["search"],"summary":"Run a search","description":"Sync mode holds the connection until the source answers (usually 6–12 seconds, longer under queue). Async mode returns 202 immediately; the result is delivered to your webhook and stays available via GET /requests/{id}. Only a completed search is charged: a validation error, an unavailable source or a rate-limit rejection cost nothing.","requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/SearchInput"}}}},"responses":{"200":{"description":"Search finished (found or not found)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"202":{"description":"Accepted into the queue (async mode)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Accepted"}}}},"401":{"description":"Missing, invalid, revoked or expired API key","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"402":{"description":"Not enough funds: no package requests left and balance is below the product price","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"403":{"description":"IP address is not allowed for this key, or the account is suspended","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"422":{"description":"Validation error — the search was not sent to the source","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"429":{"description":"Rate limit: 60 requests per minute per account, or too many requests running at once","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"503":{"description":"Source did not answer; nothing was charged","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/requests":{"get":{"tags":["search"],"summary":"List recent requests","parameters":[{"name":"limit","in":"query","schema":{"type":"integer","minimum":1,"maximum":100,"default":25}},{"name":"before","in":"query","description":"Return requests created before this ISO timestamp (pagination)","schema":{"type":"string","format":"date-time"}},{"name":"status","in":"query","schema":{"type":"string","enum":["queued","running","completed","not_found","failed","rejected"]}}],"responses":{"200":{"description":"Requests without result bodies","content":{"application/json":{"schema":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Request"}},"next_before":{"type":["string","null"]}}}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/requests/{id}":{"get":{"tags":["search"],"summary":"Get a request with its result","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string","example":"req_8f21c4"}}],"responses":{"200":{"description":"Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown request id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/requests/{id}/report":{"get":{"tags":["search"],"summary":"Full report as plain text","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"responses":{"200":{"description":"text/plain report","content":{"text/plain":{"schema":{"type":"string"}}}},"404":{"description":"No result for this request (not finished, failed, or expired)","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/requests/{id}/addons":{"post":{"tags":["search"],"summary":"Buy an add-on from a saved result","description":"Driver licence or MVR taken from the record already found — no second call to the source, so it is cheaper and instant. If the record has no such data, the answer is `not_found` and nothing is charged. Already bought add-ons are returned again for free.","parameters":[{"name":"id","in":"path","required":true,"schema":{"type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["addon"],"properties":{"addon":{"type":"string","enum":["dl_after_ssn","mvr_after_ssn","mvr_after_dl"]}}}}}},"responses":{"200":{"description":"Add-on result","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Request"}}}},"402":{"description":"Balance is below the add-on price","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"404":{"description":"Unknown request id","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}},"409":{"description":"Add-on is not applicable to this request, or the credit report is not available via API yet","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/account":{"get":{"tags":["account"],"summary":"Balance, packages and prices","responses":{"200":{"description":"Account state","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Account"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/Error"}}}}}}},"/queue":{"get":{"tags":["account"],"summary":"Queue length at the source","responses":{"200":{"description":"Queue","content":{"application/json":{"schema":{"type":"object","properties":{"waiting":{"type":"integer"},"eta_seconds":{"type":"integer"},"running":{"type":"integer","description":"your requests in progress"}}}}}}}}}},"components":{"securitySchemes":{"bearerAuth":{"type":"http","scheme":"bearer","description":"API key from the dashboard: `Authorization: Bearer lp_live_…`"}},"schemas":{"Error":{"type":"object","properties":{"error":{"type":"string","example":"payment_required"},"message":{"type":"string"},"charged":{"type":"boolean","const":false},"retry_after":{"type":"integer","description":"seconds, only with 429"}}},"SearchInput":{"type":"object","required":["product","first_name","last_name"],"properties":{"product":{"type":"string","enum":["ssn_bg","dl","mvr"],"description":"ssn_bg — SSN + DOB (package or balance), dl / mvr — balance only"},"first_name":{"type":"string","example":"John"},"last_name":{"type":"string","example":"Miller"},"hint":{"type":"string","description":"Street without ZIP, city or state. Required unless dob is given","example":"1026 Maple Lane"},"dob":{"type":"string","description":"MM/DD/YYYY. Required unless hint is given","example":"03/14/1979"},"mode":{"type":"string","enum":["sync","async"],"default":"sync"},"client_ref":{"type":"string","maxLength":120,"description":"Your identifier, echoed back in responses and webhooks"}}},"Accepted":{"type":"object","properties":{"request_id":{"type":"string","example":"req_8f21c4"},"status":{"type":"string","const":"queued"},"queue_position":{"type":"integer"},"eta_seconds":{"type":"integer"}}},"Request":{"type":"object","properties":{"request_id":{"type":"string"},"client_ref":{"type":["string","null"]},"product":{"type":"string"},"mode":{"type":"string","enum":["sync","async"]},"status":{"type":"string","enum":["queued","running","completed","not_found","failed","rejected"]},"query":{"type":"object","properties":{"first_name":{"type":"string"},"last_name":{"type":"string"},"hint":{"type":["string","null"]},"dob":{"type":["string","null"]}}},"charged":{"type":"boolean"},"charge":{"type":"object","properties":{"source":{"type":"string","enum":["package","balance","none"]},"amount_cents":{"type":"integer"},"requests":{"type":"integer"},"reason":{"type":["string","null"]}}},"cached":{"type":"boolean","description":"Same query within 5 minutes — served from the saved answer for free"},"error":{"type":["object","null"],"properties":{"code":{"type":"string"},"message":{"type":["string","null"]}}},"queue_position":{"type":["integer","null"]},"duration_ms":{"type":["integer","null"]},"created_at":{"type":"string","format":"date-time"},"finished_at":{"type":["string","null"],"format":"date-time"},"result_expires_at":{"type":["string","null"],"format":"date-time","description":"Results are kept for 90 days"},"result":{"anyOf":[{"$ref":"#/components/schemas/Result"},{"type":"null"}]}}},"Result":{"type":"object","properties":{"found":{"type":"boolean"},"matches_count":{"type":"integer"},"records":{"type":"array","items":{"$ref":"#/components/schemas/Person"}}}},"Person":{"type":"object","description":"For ssn_bg: identity, addresses, phones, emails, relatives, civil records. For dl: name and licence numbers. For mvr: licences with dates.","properties":{"full_name":{"type":"string"},"ssn":{"type":["string","null"]},"dob":{"type":["string","null"],"example":"3/14/1979"},"age":{"type":["integer","null"]},"gender":{"type":["string","null"]},"aka":{"type":"array","items":{"type":"string"}},"addresses":{"type":"array","items":{"type":"object","properties":{"raw":{"type":"string"},"city":{"type":["string","null"]},"state":{"type":["string","null"]},"zip_code":{"type":["string","null"]},"date_from":{"type":["string","null"]},"date_to":{"type":["string","null"]},"is_current":{"type":"boolean"}}}},"phones":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string"},"formatted":{"type":"string"},"phone_type":{"type":["string","null"]},"carrier":{"type":["string","null"]}}}},"emails":{"type":"array","items":{"type":"string"}},"relatives":{"type":"array","items":{"type":"object","properties":{"full_name":{"type":"string"},"relationship_type":{"type":["string","null"]},"dob_year":{"type":["string","null"]},"current_age":{"type":["integer","null"]}}}},"civil_records":{"type":["object","null"],"properties":{"bankruptcies":{"type":"integer"},"liens":{"type":"integer"},"judgments":{"type":"integer"}}},"driver_licenses":{"type":"array","items":{"type":"object","properties":{"number":{"type":"string"},"state":{"type":["string","null"]},"issue_date":{"type":["string","null"]},"expiration_date":{"type":["string","null"]},"gender":{"type":["string","null"]},"race":{"type":["string","null"]},"height":{"type":["string","null"]}}}}}},"Account":{"type":"object","properties":{"nickname":{"type":"string"},"balance_cents":{"type":"integer"},"available_cents":{"type":"integer","description":"balance minus reservations of running searches"},"package_requests_left":{"type":"integer"},"packages":{"type":"array","items":{"type":"object","properties":{"id":{"type":"string"},"name":{"type":"string"},"requests_left":{"type":"integer"},"requests_total":{"type":"integer"},"expires_at":{"type":"string","format":"date-time"}}}},"prices":{"type":"object","additionalProperties":{"type":"integer"},"description":"your price per product/add-on, cents"},"limits":{"type":"object","properties":{"requests_per_minute":{"type":"integer"},"concurrent_requests":{"type":"integer"}}}}}}}}