{"openapi":"3.1.0","paths":{"/v1/webhook/linked-helper/person/create":{"post":{"description":"Inbound webhook used by the LinkedHelper integration to create a Person in RUBINLAKE. Authenticated via a scoped `token`; trial users are rejected. Returns 202 immediately and processes the payload fire-and-forget.","operationId":"WebhookController_postLinkedHelperPersonCreate","parameters":[{"name":"token","required":true,"in":"query","description":"Scoped token for LinkedHelper webhook","schema":{"pattern":"^scto_live_[a-f0-9]{64}$","type":"string"}}],"requestBody":{"required":true,"content":{"application/json":{"schema":{"$ref":"#/components/schemas/LinkedHelperPersonPayload"}}}},"responses":{"202":{"description":"LinkedHelper payload accepted; person creation runs asynchronously after the response is sent."},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"summary":"Create a person for LinkedHelper","tags":["webhook"]}},"/v1/api/companies/{companyId}":{"get":{"description":"Returns a company's base data. Requires the `read` scope; costs 0.5 credits per call.","operationId":"PublicApiController_getCompany","parameters":[{"name":"companyId","required":true,"in":"path","description":"The company ID (`comp:` prefixed)","schema":{"minLength":1,"maxLength":128,"type":"string"}}],"responses":{"200":{"description":"The company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearer":[]}],"summary":"Get a company by ID","tags":["public-api"],"x-credits":0.5}},"/v1/api/companies/{companyId}/people":{"get":{"description":"Cursor-paginated list of people working at the given company. Requires the `search` scope; costs 0.5 credits per page.","operationId":"PublicApiController_listCompanyPeople","parameters":[{"name":"companyId","required":true,"in":"path","description":"The company ID (`comp:` prefixed)","schema":{"minLength":1,"maxLength":128,"type":"string"}},{"name":"limit","required":false,"in":"query","description":"Items per page","schema":{"minimum":1,"maximum":100,"type":"integer"}},{"name":"searchAfter","required":false,"in":"query","description":"Cursor from a previous response to fetch the next page","schema":{"minLength":1,"type":"string"}}],"responses":{"200":{"description":"People at the company","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearer":[]}],"summary":"List a company's people","tags":["public-api"],"x-credits":0.5}},"/v1/api/people/{personId}":{"get":{"description":"Returns a person's base data. Requires the `read` scope; costs 0.5 credits per call.","operationId":"PublicApiController_getPerson","parameters":[{"name":"personId","required":true,"in":"path","description":"The person ID","schema":{"pattern":"^[0-9a-fA-F]{24}$","type":"string"}}],"responses":{"200":{"description":"The person","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"404":{"description":"Not Found","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearer":[]}],"summary":"Get a person by ID","tags":["public-api"],"x-credits":0.5}},"/v1/api/search/companies":{"get":{"description":"Cursor-paginated company search. Requires the `search` scope; costs 0.5 credits per page.","operationId":"PublicApiController_searchCompanies","parameters":[{"name":"query","required":false,"in":"query","description":"Free-text search query","schema":{"minLength":1,"maxLength":200,"type":"string"}},{"name":"countries","required":false,"in":"query","description":"Comma-separated ISO-3166 alpha-2 country codes","schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","enum":["AF","AL","DZ","AS","AD","AO","AI","AQ","AG","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BA","BW","BV","BR","IO","BN","BG","BF","BI","KH","CM","CA","CV","KY","CF","TD","CL","CN","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GN","GW","GY","HT","HM","VA","HN","HK","HU","IS","IN","ID","IR","IQ","IE","IL","IT","JM","JP","JO","KZ","KE","KI","KP","KR","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MO","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","MS","MA","MZ","MM","NA","NR","NP","NL","NC","NZ","NI","NE","NG","NU","NF","MK","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","SH","KN","LC","PM","VC","WS","SM","ST","SA","SN","SC","SL","SG","SK","SI","SB","SO","ZA","GS","ES","LK","SD","SR","SJ","SZ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VG","VI","WF","EH","YE","ZM","ZW","AX","BQ","CW","GG","IM","JE","ME","BL","MF","RS","SX","SS","XK"]}}},{"name":"size","required":false,"in":"query","description":"Comma-separated company size buckets (1–8)","schema":{"minItems":1,"maxItems":8,"type":"array","items":{"type":"integer","minimum":1,"maximum":8}}},{"name":"employeesMin","required":false,"in":"query","description":"Minimum headcount","schema":{"minimum":0,"type":"number"}},{"name":"employeesMax","required":false,"in":"query","description":"Maximum headcount","schema":{"minimum":0,"type":"number"}},{"name":"revenueMin","required":false,"in":"query","description":"Minimum annual revenue","schema":{"minimum":0,"type":"number"}},{"name":"revenueMax","required":false,"in":"query","description":"Maximum annual revenue","schema":{"minimum":0,"type":"number"}},{"name":"ebitdaMarginMin","required":false,"in":"query","description":"Minimum EBITDA margin","schema":{"type":"number"}},{"name":"ebitdaMarginMax","required":false,"in":"query","description":"Maximum EBITDA margin","schema":{"type":"number"}},{"name":"cashFlowMin","required":false,"in":"query","description":"Minimum cash flow","schema":{"type":"number"}},{"name":"cashFlowMax","required":false,"in":"query","description":"Maximum cash flow","schema":{"type":"number"}},{"name":"equityRatioMin","required":false,"in":"query","description":"Minimum equity ratio","schema":{"type":"number"}},{"name":"equityRatioMax","required":false,"in":"query","description":"Maximum equity ratio","schema":{"type":"number"}},{"name":"totalAssetsMin","required":false,"in":"query","description":"Minimum total assets","schema":{"minimum":0,"type":"number"}},{"name":"totalAssetsMax","required":false,"in":"query","description":"Maximum total assets","schema":{"minimum":0,"type":"number"}},{"name":"foundedYearMin","required":false,"in":"query","description":"Earliest founding year","schema":{"minimum":-9007199254740991,"maximum":9007199254740991,"type":"integer"}},{"name":"foundedYearMax","required":false,"in":"query","description":"Latest founding year","schema":{"minimum":-9007199254740991,"maximum":9007199254740991,"type":"integer"}},{"name":"legalForms","required":false,"in":"query","description":"Comma-separated legal-form codes","schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},{"name":"status","required":false,"in":"query","description":"Comma-separated company statuses","schema":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":1}}},{"name":"businessTypes","required":false,"in":"query","description":"Comma-separated business-type classifications","schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1}}},{"name":"domain","required":false,"in":"query","description":"Filter by company web domain","schema":{"minLength":1,"maxLength":253,"type":"string"}},{"name":"rlc","required":false,"in":"query","description":"Comma-separated RUBINLAKE industry codes","schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},{"name":"wz","required":false,"in":"query","description":"Comma-separated German WZ industry codes","schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1}}},{"name":"isic","required":false,"in":"query","description":"Comma-separated ISIC industry codes","schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","minLength":1}}},{"name":"tags","required":false,"in":"query","description":"Comma-separated exact tags","schema":{"minItems":1,"maxItems":12,"type":"array","items":{"type":"string","minLength":1}}},{"name":"semanticTags","required":false,"in":"query","description":"Comma-separated tag phrases matched semantically","schema":{"minItems":1,"maxItems":12,"type":"array","items":{"type":"string","minLength":1}}},{"name":"limit","required":false,"in":"query","description":"Items per page","schema":{"minimum":1,"maximum":100,"type":"integer"}},{"name":"searchAfter","required":false,"in":"query","description":"Cursor from a previous response to fetch the next page","schema":{"minLength":1,"type":"string"}}],"responses":{"200":{"description":"Matching companies","content":{"application/json":{"schema":{"$ref":"#/components/schemas/CompanyListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearer":[]}],"summary":"Search companies","tags":["public-api"],"x-credits":0.5}},"/v1/api/search/people":{"get":{"description":"Cursor-paginated people search over structured filters: skills, job titles, seniority, function, languages, countries, tags, and current or past company. At least one filter is required. There is no name search, because public people carry no name to match on. Requires the `search` scope; costs 0.5 credits per page.","operationId":"PublicApiController_searchPeople","parameters":[{"name":"skills","required":false,"in":"query","description":"Comma-separated exact skills, e.g. `react,kubernetes`","schema":{"minItems":1,"maxItems":12,"type":"array","items":{"type":"string","minLength":1}}},{"name":"semanticSkills","required":false,"in":"query","description":"Comma-separated skill phrases matched semantically (vector search)","schema":{"minItems":1,"maxItems":12,"type":"array","items":{"type":"string","minLength":1}}},{"name":"semanticJobTitles","required":false,"in":"query","description":"Comma-separated job-title phrases matched semantically (vector search)","schema":{"minItems":1,"maxItems":12,"type":"array","items":{"type":"string","minLength":1}}},{"name":"jobTitles","required":false,"in":"query","description":"Comma-separated exact job titles","schema":{"minItems":1,"maxItems":12,"type":"array","items":{"type":"string","minLength":1}}},{"name":"seniorities","required":false,"in":"query","description":"Comma-separated seniority levels (junior, midLevel, senior, manager, director, vp, partner, cxo, owner, expert)","schema":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","enum":["junior","midLevel","senior","manager","director","vp","partner","cxo","owner","expert"]}}},{"name":"jobFunctions","required":false,"in":"query","description":"Comma-separated job-function codes","schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},{"name":"yearsExperience","required":false,"in":"query","description":"Minimum inferred years of experience","schema":{"minimum":0,"maximum":9007199254740991,"type":"integer"}},{"name":"knowsLanguages","required":false,"in":"query","description":"Comma-separated languages, e.g. `de,en`","schema":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":1}}},{"name":"countries","required":false,"in":"query","description":"Comma-separated ISO-3166 alpha-2 country codes","schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","enum":["AF","AL","DZ","AS","AD","AO","AI","AQ","AG","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BA","BW","BV","BR","IO","BN","BG","BF","BI","KH","CM","CA","CV","KY","CF","TD","CL","CN","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GN","GW","GY","HT","HM","VA","HN","HK","HU","IS","IN","ID","IR","IQ","IE","IL","IT","JM","JP","JO","KZ","KE","KI","KP","KR","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MO","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","MS","MA","MZ","MM","NA","NR","NP","NL","NC","NZ","NI","NE","NG","NU","NF","MK","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","SH","KN","LC","PM","VC","WS","SM","ST","SA","SN","SC","SL","SG","SK","SI","SB","SO","ZA","GS","ES","LK","SD","SR","SJ","SZ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VG","VI","WF","EH","YE","ZM","ZW","AX","BQ","CW","GG","IM","JE","ME","BL","MF","RS","SX","SS","XK"]}}},{"name":"profileTypes","required":false,"in":"query","description":"Comma-separated social-profile types the person must have (e.g. `linkedin,github`)","schema":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","enum":["facebook","linkedin","xing","instagram","x","github","stackoverflow","medium","youtube","twitch","reddit","soundcloud","spotify","website","blog"]}}},{"name":"companyId","required":false,"in":"query","description":"Restrict results to people currently at this company","schema":{"minLength":1,"maxLength":128,"type":"string"}},{"name":"pastCompanyIds","required":false,"in":"query","description":"Comma-separated companies the person previously worked at","schema":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":1}}},{"name":"tags","required":false,"in":"query","description":"Comma-separated exact tags","schema":{"minItems":1,"maxItems":12,"type":"array","items":{"type":"string","minLength":1}}},{"name":"sortBy","required":false,"in":"query","description":"Sort field for browse mode (createdAt, modifiedAt)","schema":{"type":"string","enum":["createdAt","modifiedAt"]}},{"name":"limit","required":false,"in":"query","description":"Items per page","schema":{"minimum":1,"maximum":100,"type":"integer"}},{"name":"searchAfter","required":false,"in":"query","description":"Cursor from a previous response to fetch the next page","schema":{"minLength":1,"type":"string"}}],"responses":{"200":{"description":"Matching people","content":{"application/json":{"schema":{"$ref":"#/components/schemas/PersonListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearer":[]}],"summary":"Search people","tags":["public-api"],"x-credits":0.5}},"/v1/api/search/jobs":{"get":{"description":"Cursor-paginated search over public job postings by free-text and structured filters (status, company, function, seniority, skills, country, language). Requires the `search` scope; costs 0.5 credits per page.","operationId":"PublicApiController_searchJobs","parameters":[{"name":"query","required":false,"in":"query","description":"Free-text search over job postings","schema":{"minLength":1,"maxLength":200,"type":"string"}},{"name":"status","required":false,"in":"query","description":"Comma-separated statuses (draft, active, paused, closed, archived)","schema":{"minItems":1,"maxItems":5,"type":"array","items":{"type":"string","enum":["draft","active","paused","closed","archived"]}}},{"name":"companyId","required":false,"in":"query","description":"Restrict to postings owned by this company","schema":{"minLength":1,"maxLength":128,"type":"string"}},{"name":"functions","required":false,"in":"query","description":"Comma-separated job-function codes","schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}}},{"name":"seniorities","required":false,"in":"query","description":"Comma-separated seniority levels","schema":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","enum":["junior","midLevel","senior","manager","director","vp","partner","cxo","owner","expert"]}}},{"name":"skills","required":false,"in":"query","description":"Comma-separated required skills","schema":{"minItems":1,"maxItems":12,"type":"array","items":{"type":"string","minLength":1}}},{"name":"countries","required":false,"in":"query","description":"Comma-separated ISO-3166 alpha-2 country codes","schema":{"minItems":1,"maxItems":20,"type":"array","items":{"type":"string","enum":["AF","AL","DZ","AS","AD","AO","AI","AQ","AG","AR","AM","AW","AU","AT","AZ","BS","BH","BD","BB","BY","BE","BZ","BJ","BM","BT","BO","BA","BW","BV","BR","IO","BN","BG","BF","BI","KH","CM","CA","CV","KY","CF","TD","CL","CN","CX","CC","CO","KM","CG","CD","CK","CR","CI","HR","CU","CY","CZ","DK","DJ","DM","DO","EC","EG","SV","GQ","ER","EE","ET","FK","FO","FJ","FI","FR","GF","PF","TF","GA","GM","GE","DE","GH","GI","GR","GL","GD","GP","GU","GT","GN","GW","GY","HT","HM","VA","HN","HK","HU","IS","IN","ID","IR","IQ","IE","IL","IT","JM","JP","JO","KZ","KE","KI","KP","KR","KW","KG","LA","LV","LB","LS","LR","LY","LI","LT","LU","MO","MG","MW","MY","MV","ML","MT","MH","MQ","MR","MU","YT","MX","FM","MD","MC","MN","MS","MA","MZ","MM","NA","NR","NP","NL","NC","NZ","NI","NE","NG","NU","NF","MK","MP","NO","OM","PK","PW","PS","PA","PG","PY","PE","PH","PN","PL","PT","PR","QA","RE","RO","RU","RW","SH","KN","LC","PM","VC","WS","SM","ST","SA","SN","SC","SL","SG","SK","SI","SB","SO","ZA","GS","ES","LK","SD","SR","SJ","SZ","SE","CH","SY","TW","TJ","TZ","TH","TL","TG","TK","TO","TT","TN","TR","TM","TC","TV","UG","UA","AE","GB","US","UM","UY","UZ","VU","VE","VN","VG","VI","WF","EH","YE","ZM","ZW","AX","BQ","CW","GG","IM","JE","ME","BL","MF","RS","SX","SS","XK"]}}},{"name":"languages","required":false,"in":"query","description":"Comma-separated required languages","schema":{"minItems":1,"maxItems":10,"type":"array","items":{"type":"string","minLength":1}}},{"name":"limit","required":false,"in":"query","description":"Items per page","schema":{"minimum":1,"maximum":100,"type":"integer"}},{"name":"searchAfter","required":false,"in":"query","description":"Cursor from a previous response to fetch the next page","schema":{"minLength":1,"type":"string"}}],"responses":{"200":{"description":"Matching job postings","content":{"application/json":{"schema":{"$ref":"#/components/schemas/JobPostingListResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearer":[]}],"summary":"Search job postings","tags":["public-api"],"x-credits":0.5}},"/v1/api/verify/email":{"get":{"description":"Reports whether the email's domain is a disposable-email provider, a free webmail provider, and whether it has valid MX records. Requires the `read` scope; costs 0.5 credits per call.","operationId":"PublicApiController_verifyEmail","parameters":[{"name":"email","required":true,"in":"query","description":"The email address to verify","schema":{"maxLength":254,"example":"john.doe@example.com","type":"string"}}],"responses":{"200":{"description":"Email deliverability signals","content":{"application/json":{"schema":{"$ref":"#/components/schemas/EmailVerificationResponse"}}}},"400":{"description":"Bad Request","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"401":{"description":"Unauthorized","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"403":{"description":"Forbidden","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}},"422":{"description":"Unprocessable Entity","content":{"application/json":{"schema":{"$ref":"#/components/schemas/ErrorResponse"}}}}},"security":[{"bearer":[]}],"summary":"Verify an email address","tags":["public-api"],"x-credits":0.5}}},"info":{"title":"RUBINLAKE Developer API","description":"REST API for programmatic access to RUBINLAKE company and people data.\n\n## Authentication\nCreate an API key under **Account → API tokens** in the app. Send it as\n`Authorization: Bearer scto_…` on every request. Keys are scoped — a key\nonly works for the scopes selected when it was created. The LinkedHelper\nwebhook instead takes the key as a `token` query parameter.\n\n## Credits\nMetered endpoints charge credits per call (see the `x-credits` badge on\neach operation). Responses from metered endpoints report\n`X-Credits-Charged` and `X-Credits-Remaining` headers; requests rejected\nbefore metering (invalid key, missing scope, plan without API access)\ncarry no credit headers, and `X-Credits-Remaining` is best-effort.\nFailed calls are never billed. Inbound webhooks are free.\n\n## Errors\n`401` invalid key or missing scope · `403` plan without API access or\ntrial account · `402` insufficient credits or key cap reached (top up in\n**Account → Billing**) · `422` request validation, with `validationErrors[]`.\n\n## Pagination\nSearch endpoints use cursor pagination: pass the `searchAfter` value from\nthe previous response to fetch the next page.","version":"1.96.0","contact":{"name":"RUBINLAKE | Support","url":"https://www.rubinlake.com","email":"support@rubinlake.com"},"license":{"name":"UNLICENSED – © RUBINLAKE GmbH. All rights reserved.","url":"https://rubinlake.com/en/terms?tab=terms"}},"tags":[{"name":"public-api","description":"Credit-metered data endpoints for API-key consumers."},{"name":"webhook","description":"Inbound webhooks (free; key via `token` query param)."}],"servers":[{"url":"https://api.rubinlake.com","description":"Production"},{"url":"https://api-dev.rubinlake.com","description":"Development / testing"}],"components":{"securitySchemes":{"bearer":{"scheme":"bearer","bearerFormat":"JWT","type":"http","description":"API key from Account → API tokens (`scto_…`). Scoped and revocable."}},"schemas":{"Company":{"type":"object","properties":{"id":{"type":"string","description":"The company ID (`comp:` prefixed)"},"name":{"description":"The company name, when known","type":"string"},"domain":{"description":"The company's primary domain","type":"string"},"websiteUrl":{"description":"The company's website URL","type":"string"},"legalForm":{"description":"The company's legal form","type":"string"},"size":{"description":"The company size bucket","type":"string"},"status":{"description":"The company status","type":"string"},"foundedYear":{"description":"The year the company was founded","type":"number"},"description":{"description":"The company description, when known","type":"string"},"tags":{"description":"Tags associated with the company","type":"array","items":{"type":"string"}},"locations":{"description":"Known company locations","type":"array","items":{"$ref":"#/components/schemas/CompanyLocation"}}},"required":["id"],"additionalProperties":false,"description":"A company as exposed by the public API."},"CompanyLocation":{"type":"object","properties":{"city":{"description":"City","type":"string"},"country":{"description":"ISO country code","type":"string"},"postalCode":{"description":"Postal code","type":"string"}}},"EmailVerification":{"type":"object","properties":{"isDisposable":{"type":"boolean","description":"Whether the domain is a known disposable-email provider"},"isWebmail":{"type":"boolean","description":"Whether the domain is a free webmail provider"},"hasMxRecords":{"type":"boolean","description":"Whether the domain has valid MX records"}},"required":["isDisposable","isWebmail","hasMxRecords"],"additionalProperties":false,"description":"Deliverability signals for an email address."},"Job":{"type":"object","properties":{"title":{"description":"Job title","type":"string"},"companyName":{"description":"Employer name","type":"string"},"companyId":{"description":"Employer company ID","type":"string"},"isActive":{"description":"Whether this is a current job","type":"boolean"}}},"JobPosting":{"type":"object","properties":{"id":{"type":"string","description":"The job-posting ID"},"title":{"description":"Job title","type":"string"},"status":{"description":"Job-posting status","type":"string"},"description":{"description":"Job description, when available","type":"string"},"skills":{"description":"Required skills, when available","type":"array","items":{"type":"string"}}},"required":["id"],"additionalProperties":false,"description":"A job posting as exposed by the public API."},"LinkedHelperPersonPayload":{"type":"object","properties":{"id":{"type":"string","description":"LinkedIn username/slug (e.g. `hinrich-völcker-33089192`); mapped to `username` on the persisted record."},"lhId":{"description":"Numeric LinkedIn member ID provided by LinkedHelper.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"externalIds":{"description":"Array of external identifiers (member-id, public-id, etc.); entries whose `type` contains `hash` are filtered out.","anyOf":[{"type":"array","items":{"type":"object","properties":{"type":{"type":"string","description":"Identifier scheme (e.g. member-id, public-id)."},"externalId":{"type":"string","description":"External identifier value from LinkedIn."},"memberId":{"description":"Numeric member id when provided separately.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991}},"required":["type","externalId"],"description":"LinkedIn external identifier tuple."}},{"type":"null"}]},"miniProfile":{"description":"Compact LinkedIn mini-profile block.","anyOf":[{"type":"object","properties":{"firstName":{"description":"Given name from the LinkedIn mini profile.","anyOf":[{"type":"string"},{"type":"null"}]},"lastName":{"description":"Family name from the LinkedIn mini profile.","anyOf":[{"type":"string"},{"type":"null"}]},"headline":{"description":"Profile headline or tagline.","anyOf":[{"type":"string"},{"type":"null"}]},"avatar":{"description":"URL of the profile picture.","anyOf":[{"type":"string","format":"uri"},{"type":"null"}]}}},{"type":"null"}]},"profileUrl":{"description":"Canonical URL of the person's LinkedIn profile.","type":"string","format":"uri"},"currentPosition":{"description":"Current employer and title pair from LinkedIn.","anyOf":[{"type":"object","properties":{"company":{"description":"Employer name for the current role.","anyOf":[{"type":"string"},{"type":"null"}]},"position":{"description":"Job title for the current role.","anyOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]},"positions":{"description":"Full work history extracted from the LinkedIn profile.","anyOf":[{"type":"array","items":{"description":"Work history position; `companyId` is mapped to `companyLinkedinId` after parse.","type":"object","properties":{"title":{"description":"Job title for this position.","anyOf":[{"type":"string"},{"type":"null"}]},"companyName":{"description":"Employer display name.","anyOf":[{"type":"string"},{"type":"null"}]},"companyId":{"description":"LinkedIn company identifier for the employer.","anyOf":[{"type":"string"},{"type":"null"}]},"dateRange":{"description":"LinkedIn-style start/end window for jobs or education.","anyOf":[{"type":"object","properties":{"start":{"description":"Beginning of a LinkedIn date range (year with optional month).","type":"object","properties":{"year":{"type":"integer","minimum":1900,"maximum":2100,"description":"Start year of the interval."},"month":{"description":"Start month (1–12) when known.","type":"integer","minimum":1,"maximum":12}},"required":["year"]},"end":{"description":"End of the interval; null if ongoing or unspecified.","anyOf":[{"type":"object","properties":{"year":{"type":"integer","minimum":1900,"maximum":2100,"description":"End year of the interval."},"month":{"description":"End month (1–12) when known.","type":"integer","minimum":1,"maximum":12}},"required":["year"]},{"type":"null"}]}}},{"type":"null"}]},"locationName":{"description":"Location string associated with the role.","anyOf":[{"type":"string"},{"type":"null"}]},"description":{"description":"Role description or summary text.","anyOf":[{"type":"string"},{"type":"null"}]},"website":{"description":"Related website URL for the role or company.","anyOf":[{"type":"string"},{"type":"null"}]},"domain":{"description":"Company or property domain extracted from LinkedIn.","anyOf":[{"type":"string"},{"type":"null"}]}}}},{"type":"null"}]},"educations":{"description":"Education entries extracted from the LinkedIn profile.","anyOf":[{"type":"array","items":{"type":"object","properties":{"schoolName":{"description":"Educational institution name.","anyOf":[{"type":"string"},{"type":"null"}]},"degreeName":{"description":"Degree or qualification name.","anyOf":[{"type":"string"},{"type":"null"}]},"fieldOfStudy":{"description":"Major or subject area.","anyOf":[{"type":"string"},{"type":"null"}]},"description":{"description":"Additional notes for the education entry.","anyOf":[{"type":"string"},{"type":"null"}]},"dateRange":{"description":"LinkedIn-style start/end window for jobs or education.","anyOf":[{"type":"object","properties":{"start":{"description":"Beginning of a LinkedIn date range (year with optional month).","type":"object","properties":{"year":{"type":"integer","minimum":1900,"maximum":2100,"description":"Start year of the interval."},"month":{"description":"Start month (1–12) when known.","type":"integer","minimum":1,"maximum":12}},"required":["year"]},"end":{"description":"End of the interval; null if ongoing or unspecified.","anyOf":[{"type":"object","properties":{"year":{"type":"integer","minimum":1900,"maximum":2100,"description":"End year of the interval."},"month":{"description":"End month (1–12) when known.","type":"integer","minimum":1,"maximum":12}},"required":["year"]},{"type":"null"}]}}},{"type":"null"}]}},"description":"Education history entry from LinkedIn."}},{"type":"null"}]},"skills":{"description":"Skill entries with optional endorsement counts.","anyOf":[{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Skill label as shown on LinkedIn."},"endorsementsCount":{"description":"Number of endorsements, when provided.","anyOf":[{"type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},{"type":"null"}]}},"required":["name"],"description":"Skill entry from a LinkedIn profile."}},{"type":"null"}]},"languages":{"description":"Languages spoken with their proficiency level.","anyOf":[{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Language name."},"proficiency":{"description":"Self-reported proficiency label.","anyOf":[{"type":"string"},{"type":"null"}]}},"required":["name"],"description":"Language proficiency row from LinkedIn."}},{"type":"null"}]},"location":{"description":"Geographic location summary from the profile.","anyOf":[{"type":"object","properties":{"name":{"description":"Free-text location label.","anyOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]},"industry":{"description":"Industry classification attached to the person.","anyOf":[{"type":"object","properties":{"name":{"description":"Industry label.","anyOf":[{"type":"string"},{"type":"null"}]}}},{"type":"null"}]},"currentOrganizationIndustries":{"description":"Industries assigned to the person's current organization.","anyOf":[{"type":"array","items":{"type":"object","properties":{"name":{"type":"string","description":"Industry name for the current organization."}},"required":["name"],"description":"Industry assigned to the person's current company."}},{"type":"null"}]},"birthday":{"description":"Birth day and month (year intentionally omitted).","anyOf":[{"type":"object","properties":{"month":{"description":"Birth month (1–12).","type":"integer","minimum":1,"maximum":12},"day":{"description":"Birth day of month.","type":"integer","minimum":1,"maximum":31}}},{"type":"null"}]},"thirdPartyEmails":{"description":"Email addresses sourced from third parties together with validation/source metadata.","anyOf":[{"type":"array","items":{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","example":"contact@external-source.com","description":"Email address from a third-party source."},"type":{"type":"string","description":"Classification of the email record."},"isValid":{"type":"boolean","description":"Whether the source marks the email as valid."},"source":{"type":"string","description":"Origin system or vendor for this email."}},"required":["email","type","isValid","source"],"description":"Email discovered via third-party enrichment."}},{"type":"null"}]},"email":{"description":"Primary email address attached to the LinkedIn profile.","anyOf":[{"type":"object","properties":{"email":{"type":"string","format":"email","pattern":"^(?:[A-Za-z0-9_'+\\-]+\\.)*[A-Za-z0-9_'+\\-]*[A-Za-z0-9_+-]@(?:[A-Za-z0-9][A-Za-z0-9\\-]*\\.)+[A-Za-z]{2,}$","example":"person@company.com","description":"Primary email on the LinkedIn profile."},"type":{"type":"string","description":"Email type label from LinkedIn."}},"required":["email","type"],"description":"Primary email object from LinkedIn."},{"type":"null"}]}},"required":["id"],"description":"Inbound payload from the LinkedHelper integration used to create a Person in RUBINLAKE; only fields useful for person creation are kept and unknown properties are stripped."},"PageInfo":{"type":"object","properties":{"itemCount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The number of items returned in the current response."},"totalItems":{"description":"The total number of items matching the query.","type":"integer","minimum":0,"maximum":9007199254740991},"itemsPerPage":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The maximum number of items requested per page."},"nextToken":{"description":"Opaque cursor token to retrieve the next page; `null`/absent on the last page.","anyOf":[{"type":"string","minLength":1},{"type":"null"}]}},"required":["itemCount","itemsPerPage"],"additionalProperties":false,"description":"Cursor-style pagination `meta` block. `nextToken` should be passed back to retrieve the following page; it is null/absent on the last page."},"Person":{"type":"object","properties":{"id":{"type":"string","description":"The person ID"},"firstName":{"description":"First name","type":"string"},"lastName":{"description":"Last name","type":"string"},"jobs":{"description":"Known employments","type":"array","items":{"$ref":"#/components/schemas/Job"}},"linkedinUsername":{"description":"LinkedIn username, when known","type":"string"},"seniority":{"description":"Inferred seniority level, when known","type":"string"},"skills":{"description":"Known skills, when available","type":"array","items":{"type":"string"}}},"required":["id"],"additionalProperties":false,"description":"A person as exposed by the public API."},"SearchIndexingMeta":{"type":"object","properties":{"pending":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"Records matching these filters that are not yet in the semantic index."},"complete":{"type":"boolean","description":"True when nothing is outstanding and these results are the whole set."}},"required":["pending","complete"],"additionalProperties":false,"description":"How far the semantic index has caught up with the records matching this query."},"SearchPageInfo":{"type":"object","properties":{"itemCount":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The number of items returned in the current response."},"totalItems":{"description":"The total number of items matching the query.","type":"integer","minimum":0,"maximum":9007199254740991},"itemsPerPage":{"type":"integer","minimum":0,"maximum":9007199254740991,"description":"The maximum number of items requested per page."},"nextToken":{"description":"Opaque cursor token to retrieve the next page; `null`/absent on the last page.","anyOf":[{"type":"string","minLength":1},{"type":"null"}]},"indexing":{"description":"Present while the search index is still catching up with the records matching this query. Absent once it is current, and absent on searches that do not read a derived index. Poll `complete` before treating a page as the whole answer.","$ref":"#/components/schemas/SearchIndexingMeta"}},"required":["itemCount","itemsPerPage"],"additionalProperties":false,"description":"Cursor-style pagination `meta` for search endpoints, with the index-freshness block. Pass `nextToken` back to retrieve the following page."},"CompanyList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Company"}},"meta":{"$ref":"#/components/schemas/SearchPageInfo","description":"Cursor-style pagination `meta` for search endpoints, with the index-freshness block. Pass `nextToken` back to retrieve the following page."}},"required":["items","meta"],"additionalProperties":false},"JobPostingList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/JobPosting"}},"meta":{"$ref":"#/components/schemas/PageInfo","description":"Cursor-style pagination `meta` block. `nextToken` should be passed back to retrieve the following page; it is null/absent on the last page."}},"required":["items","meta"],"additionalProperties":false},"PersonList":{"type":"object","properties":{"items":{"type":"array","items":{"$ref":"#/components/schemas/Person"}},"meta":{"$ref":"#/components/schemas/SearchPageInfo","description":"Cursor-style pagination `meta` for search endpoints, with the index-freshness block. Pass `nextToken` back to retrieve the following page."}},"required":["items","meta"],"additionalProperties":false},"CompanyListResponse":{"type":"object","properties":{"apiVersion":{"type":"string","description":"RUBINLAKE service version that produced this response (semver).","example":"1.87.0"},"data":{"$ref":"#/components/schemas/CompanyList"}},"required":["apiVersion","data"],"description":"Response envelope. The `data` property contains a `CompanyList`.","additionalProperties":false},"CompanyResponse":{"type":"object","properties":{"apiVersion":{"type":"string","description":"RUBINLAKE service version that produced this response (semver).","example":"1.87.0"},"data":{"$ref":"#/components/schemas/Company","description":"A company as exposed by the public API."}},"required":["apiVersion","data"],"description":"Response envelope. The `data` property contains: A company as exposed by the public API.","additionalProperties":false},"EmailVerificationResponse":{"type":"object","properties":{"apiVersion":{"type":"string","description":"RUBINLAKE service version that produced this response (semver).","example":"1.87.0"},"data":{"$ref":"#/components/schemas/EmailVerification","description":"Deliverability signals for an email address."}},"required":["apiVersion","data"],"description":"Response envelope. The `data` property contains: Deliverability signals for an email address.","additionalProperties":false},"JobPostingListResponse":{"type":"object","properties":{"apiVersion":{"type":"string","description":"RUBINLAKE service version that produced this response (semver).","example":"1.87.0"},"data":{"$ref":"#/components/schemas/JobPostingList"}},"required":["apiVersion","data"],"description":"Response envelope. The `data` property contains a `JobPostingList`.","additionalProperties":false},"PersonListResponse":{"type":"object","properties":{"apiVersion":{"type":"string","description":"RUBINLAKE service version that produced this response (semver).","example":"1.87.0"},"data":{"$ref":"#/components/schemas/PersonList"}},"required":["apiVersion","data"],"description":"Response envelope. The `data` property contains a `PersonList`.","additionalProperties":false},"PersonResponse":{"type":"object","properties":{"apiVersion":{"type":"string","description":"RUBINLAKE service version that produced this response (semver).","example":"1.87.0"},"data":{"$ref":"#/components/schemas/Person","description":"A person as exposed by the public API."}},"required":["apiVersion","data"],"description":"Response envelope. The `data` property contains: A person as exposed by the public API.","additionalProperties":false},"AccountNotActivatedContext":{"type":"object","properties":{"userId":{"type":"string","description":"User identifier when credentials are valid but the account is not yet activated (error code 328)."}},"required":["userId"],"additionalProperties":false,"description":"Optional context returned with account-not-activated errors."},"Error":{"type":"object","properties":{"errorId":{"description":"Unique error id to be used in support requests.","type":"string"},"userMessage":{"type":"string","description":"A message that would suitable to show the end user for UI based applications."},"developerMessage":{"description":"Technical error information suitable for developer debugging.","type":"string"},"errorCode":{"example":10001,"description":"RUBINLAKE error code that corresponds to the error message.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"httpStatusCode":{"example":400,"description":"Identical to the http status code response header.","type":"integer","minimum":-9007199254740991,"maximum":9007199254740991},"validationErrors":{"description":"Validation error details.","type":"array","items":{"anyOf":[{"$ref":"#/components/schemas/ValidationError"},{"$ref":"#/components/schemas/ValidationIssue"}]}},"details":{"description":"Additional structured error context.","type":"object","propertyNames":{"type":"string"},"additionalProperties":{}}},"required":["userMessage"],"additionalProperties":false,"description":"RUBINLAKE error envelope body. Combines a user-facing message, optional developer details, error and HTTP status codes, and structured validation errors."},"ErrorResponse":{"type":"object","properties":{"apiVersion":{"type":"string","description":"RUBINLAKE service version."},"data":{"description":"Optional payload alongside the error (e.g. `userId` on POST /auth/token when error code 328).","$ref":"#/components/schemas/AccountNotActivatedContext"},"error":{"description":"Error details.","$ref":"#/components/schemas/Error"}},"required":["apiVersion","error"],"description":"Top-level error response envelope returned by the API. Mirrors the shape of successful responses with `apiVersion` plus an `error` payload, and may include optional `data`.","additionalProperties":false},"ValidationError":{"type":"object","properties":{"errorType":{"description":"Validation error discriminator.","type":"string","const":"validation"},"propertyName":{"type":"string","description":"The property of the object in the request that did not pass validation."},"developerMessage":{"type":"string","description":"Technical error information suitable for developer debugging."}},"required":["propertyName","developerMessage"],"additionalProperties":false,"description":"Single validation error item describing one request property that failed validation."},"ValidationIssue":{"type":"object","properties":{"errorType":{"description":"Validation error discriminator.","type":"string","const":"validation"},"propertyName":{"type":"string","description":"The property of the object in the request that did not pass validation."},"developerMessage":{"type":"string","description":"Technical error information suitable for developer debugging."},"code":{"type":"string","description":"Validation error code (e.g., 'invalid_value', 'invalid_type')."},"values":{"type":"array","items":{"type":"string"},"description":"Array of values that caused the error."},"path":{"type":"array","items":{"type":"string"},"description":"Path to the field that failed validation."},"message":{"type":"string","description":"Human-readable error message."}},"required":["propertyName","developerMessage","code","values","path","message"],"additionalProperties":false,"description":"Detailed validation error item with the failing path, error code, offending values, and a human-readable message."}}}}