{"openapi":"3.1.0","info":{"title":"Substation’s Business People Finder","version":"1.4.0","description":"Substation’s Business People Finder lets you search a database of 47M+ companies and 811M+ business contacts for free. Find a verified work email or mobile number, or verify a list of business email addresses you already have.","x-guidance":"Create a free session, then use its returned search request with at least one relevant filter. Filters combine with AND; each page contains up to 25 results. Search never reveals email addresses or phones. For single or list verification, use email_verification. A saved business email also includes a verification_request. Only a valid or invalid mailbox verdict settles the verification price. Reopening the original result is free. Assess the profiles, source observations and match warnings. Provider-reported email availability is not an independent guarantee of current employment or deliverability. For a business email, follow enrichment_request. For one mobile number, follow phone_enrichment_request. Each request selects a single contact detail. The returned quote and HTTP 402 challenge state the current amount, asset, network and recipient. Use only an existing authorized spending budget; a free search never authorizes payment. Substation settles only after the requested detail is found. A mobile quote pays for one number for that person. No usable result means no Substation settlement. Wait at most one minute; Substation makes at most two provider attempts, each bounded to 30 seconds. If delivery is interrupted, check the existing job status. A completed purchase can be retrieved free using the original session’s result_request; no new wallet call or payment signature is needed. Do not start another payment if settlement is uncertain."},"servers":[{"url":"https://substation.sh"}],"paths":{"/business/sessions":{"post":{"operationId":"createSession","summary":"Start free access without an invitation","requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"responses":{"201":{"description":"Private session and callable search instructions; no payment"},"429":{"description":"Shared or network session limit; respect Retry-After"}}}},"/business/{session}/search":{"post":{"operationId":"search","summary":"Search professional profiles for free","parameters":[{"name":"session","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"},"description":"Private access returned by POST /business/sessions. Never publish it."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false,"properties":{"type":{"type":"string","enum":["people","companies"],"default":"people"},"person_name":{"type":"string","maxLength":200},"job_title":{"type":"string","maxLength":200},"company_name":{"type":"string","maxLength":200},"company_domain":{"type":"string","maxLength":200},"location":{"type":"string","maxLength":200},"page":{"type":"integer","minimum":1,"maximum":10}},"description":"Supply at least one filter; all filters combine with AND."}}}},"responses":{"200":{"description":"Free profiles, source metadata, match warnings and scoped email quote requests. Null indicates an unknown field.","content":{"application/json":{"schema":{"type":"object","properties":{"results":{"type":"array","items":{"oneOf":[{"type":"object","required":["primary_position"],"properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]},"profile_url":{"type":["string","null"],"description":"Personal LinkedIn"},"location":{"type":"object","properties":{"city":{"type":["string","null"]},"state":{"type":["string","null"]},"country":{"type":["string","null"]},"time_zone":{"type":["string","null"]}}},"primary_position":{"type":"object","properties":{"job_title":{"type":["string","null"]},"normalized_job_title":{"type":["string","null"]},"seniority":{"type":["string","null"]},"departments":{"type":["array","null"],"items":{"type":"string"}},"start_month":{"type":["string","null"],"pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"company":{"type":"object","required":["website"],"properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]},"website":{"type":["string","null"],"description":"Company website"},"profile_url":{"type":["string","null"],"description":"Company LinkedIn"},"description":{"type":["string","null"]},"industry":{"type":["string","null"]},"specialties":{"type":["array","null"],"items":{"type":"string"}},"employee_range":{"type":["string","null"]},"employee_count":{"type":["integer","null"]},"location":{"type":"object","properties":{"city":{"type":["string","null"]},"state":{"type":["string","null"]},"country":{"type":["string","null"]}}}}}}},"other_positions":{"type":"array","items":{"type":"object","properties":{"job_title":{"type":["string","null"]},"normalized_job_title":{"type":["string","null"]},"seniority":{"type":["string","null"]},"departments":{"type":["array","null"],"items":{"type":"string"}},"start_month":{"type":["string","null"],"pattern":"^\\d{4}-(0[1-9]|1[0-2])$"},"company":{"type":"object","required":["website"],"properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]},"website":{"type":["string","null"],"description":"Company website"},"profile_url":{"type":["string","null"],"description":"Company LinkedIn"},"description":{"type":["string","null"]},"industry":{"type":["string","null"]},"specialties":{"type":["array","null"],"items":{"type":"string"}},"employee_range":{"type":["string","null"]},"employee_count":{"type":["integer","null"]},"location":{"type":"object","properties":{"city":{"type":["string","null"]},"state":{"type":["string","null"]},"country":{"type":["string","null"]}}}}}}}},"email_available":{"type":["boolean","null"]},"email_status":{"type":"string"},"phone_enrichment_request":{"type":"object","description":"Follow this request for a separate quote for one mobile number."},"enrichment_request":{"type":"object","description":"Follow this request for the current business email quote."}}},{"type":"object","required":["website"],"properties":{"id":{"type":["string","null"]},"name":{"type":["string","null"]},"website":{"type":["string","null"],"description":"Company website"},"profile_url":{"type":["string","null"],"description":"Company LinkedIn"},"description":{"type":["string","null"]},"industry":{"type":["string","null"]},"specialties":{"type":["array","null"],"items":{"type":"string"}},"employee_range":{"type":["string","null"]},"employee_count":{"type":["integer","null"]},"location":{"type":"object","properties":{"city":{"type":["string","null"]},"state":{"type":["string","null"]},"country":{"type":["string","null"]}}}}}]}}}},"examples":{"person":{"summary":"Selected fields from a fictional free search","value":{"results":[{"name":"Example Person","profile_url":"https://www.linkedin.com/in/example-person","location":{"city":null,"state":null,"country":"United States","time_zone":"America/Chicago"},"primary_position":{"job_title":"Director of Product Design","normalized_job_title":"Product Design Director","seniority":"Director","departments":["Design"],"start_month":null,"company":{"name":"Example Studio","website":"https://example.org","profile_url":"https://www.linkedin.com/company/example-studio","industry":"Design","description":"Designs digital products.","specialties":["Product design"],"employee_count":null,"employee_range":"11-50"}},"email_status":"unknown","email_available":null}]}}}}}},"429":{"description":"Search allowance reached"}}}},"/business/{session}/quotes":{"post":{"operationId":"quoteEnrichment","summary":"Quote a contact lookup, replacement, single address or list","parameters":[{"name":"session","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"},"description":"Private access returned by POST /business/sessions. Never publish it."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"oneOf":[{"type":"object","required":["candidate_id"],"properties":{"candidate_id":{"type":"string"},"lookup_type":{"enum":["email","phone"],"default":"email"}},"additionalProperties":false},{"type":"object","required":["candidate_id","lookup_type","replaces_verification_id"],"properties":{"candidate_id":{"type":"string"},"lookup_type":{"const":"email"},"replaces_verification_id":{"type":"string","format":"uuid"}},"additionalProperties":false},{"type":"object","required":["lookup_type","email"],"properties":{"lookup_type":{"const":"verify_email"},"email":{"type":"string","format":"email","maxLength":254},"check_key":{"type":"string","format":"uuid"}},"additionalProperties":false},{"type":"object","required":["lookup_type","emails"],"properties":{"lookup_type":{"const":"verify_email"},"emails":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"string","maxLength":254}}},"additionalProperties":false},{"type":"object","required":["lookup_type","purchased_job_id","check_key"],"properties":{"lookup_type":{"const":"verify_email"},"purchased_job_id":{"type":"string","format":"uuid"},"check_key":{"type":"string","format":"uuid"}},"additionalProperties":false}]}}}},"responses":{"200":{"description":"Free quote. For a list, entries follow input order and maximum_usdc caps new charges. Each payable job includes its payment_request and free result_request."}}}},"/business/{session}/verify-list":{"post":{"operationId":"runSignedVerificationList","summary":"Run up to 100 individually authorized verifications and resume unfinished jobs","parameters":[{"name":"session","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"},"description":"Private access returned by POST /business/sessions. Never publish it."}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","required":["items"],"properties":{"items":{"type":"array","minItems":1,"maxItems":100,"items":{"type":"object","required":["job_id","payment_signature"],"properties":{"job_id":{"type":"string","format":"uuid"},"payment_signature":{"type":"string","maxLength":20000}},"additionalProperties":false}}},"additionalProperties":false}}}},"responses":{"200":{"description":"Per-job outcomes. Conclusive and inconclusive verdicts include the checked address. Check interrupted jobs individually before retrying."}}}},"/enrichment/{job_id}":{"get":{"operationId":"enrichmentStatus","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"State and payment receipt, without the private result"}}},"post":{"operationId":"payEnrichment","summary":"Pay the existing quote and receive the selected contact detail","parameters":[{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}},{"name":"PAYMENT-SIGNATURE","in":"header","required":false,"schema":{"type":"string"},"description":"x402 payment authorization matching this job and its quote"}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"type":"object","additionalProperties":false}}}},"responses":{"200":{"description":"Completed paid result, or explicit no-result with no settlement"},"202":{"description":"Processing or uncertain settlement; check existing status"},"402":{"description":"x402 payment requirements for this existing job"},"429":{"description":"Capacity limit; no new payment"},"504":{"description":"Provider deadline; no settlement"}}}},"/business/{session}/results/{job_id}":{"get":{"operationId":"retrievePaidResult","summary":"Retrieve the original paid result and receipt without another charge","parameters":[{"name":"session","in":"path","required":true,"schema":{"type":"string","pattern":"^[A-Za-z0-9_-]{43}$"},"description":"Private access returned by POST /business/sessions. Never publish it."},{"name":"job_id","in":"path","required":true,"schema":{"type":"string","format":"uuid"}}],"responses":{"200":{"description":"Saved result; replayed=true, charged_again=false"},"403":{"description":"Expired or revoked access"},"404":{"description":"No job owned by this session"},"409":{"description":"No completed paid result"}}}},"/business/status":{"get":{"operationId":"serviceStatus","summary":"Current price and capacity signals","responses":{"200":{"description":"Current business email, verification and mobile USDC prices, network and capacity warnings"}}}}}}