{ "openapi": "3.1.0", "info": { "title": "Kooperativa API", "version": "1.0.0", "description": "B2B data enrichment API for developers.\n\nLook up profiles and companies, and search our data lake by any attribute, all with a single HTTP request.\n\n## Base URL\n```\nhttps://kooperativa.io/api/v1\n```\nAll requests must be made over HTTPS.\n\n## Authentication\nEvery request requires an API key passed as a Bearer token:\n```\nAuthorization: Bearer ik_live_...\n```\nGenerate keys from your [dashboard](https://kooperativa.io/dashboard/api-keys). Keys start with `ik_live_`.\n\n## License\nKooperativa is licensed at a flat rate. There is no allowance that runs out with use: every endpoint is included and unlimited, for as long as your workspace has an active license. The one exception is the pair of realtime endpoints, [Enrich Person (Realtime)](#tag/people) and [Enrich Company (Realtime)](#tag/companies), which query a live source instead of our own data and are metered at $0.001 per call on top of the license. The only ceiling is the shared rate limit. If your workspace has no active license, requests return `402` with code `LICENSE_INACTIVE`. Check your status any time with [Account Info](#tag/account).\n\n## Data freshness\nAll data is served from our own data lake, continuously refreshed in the background. Every record exposes a `fetched_at` timestamp so you can tell how recent it is. When a background-refreshed record is not current enough, the two realtime endpoints fetch from the live source on demand and write the result back, so subsequent cached reads return the fresh copy.\n\n### On every response\nEvery response, successful or not, carries a `quotas` object with your rate limit state, and a `metadata` object with a `request_id` and the server-side duration. You never have to call another endpoint to check the rate limit window. Errors also carry a stable `code`: switch on that rather than on the human-readable `error` string.", "contact": { "email": "support@kooperativa.io", "url": "https://kooperativa.io" }, "license": { "name": "Proprietary" } }, "servers": [ { "url": "https://kooperativa.io/api/v1", "description": "Production" }, { "url": "/api/v1", "description": "Current origin (use this to test from the docs page itself)" } ], "security": [ { "BearerAuth": [] } ], "components": { "securitySchemes": { "BearerAuth": { "type": "http", "scheme": "bearer", "description": "API key from your dashboard. Keys start with `ik_live_`." } }, "schemas": { "Error": { "type": "object", "properties": { "error": { "type": "string", "example": "Profile not found" }, "code": { "type": "string", "description": "Stable, machine-readable error code. Switch on this rather than on `error`, whose wording may change.", "example": "NOT_FOUND" } } }, "PersonResult": { "type": "object", "properties": { "id": { "type": "string", "description": "Kooperativa profile ID" }, "full_name": { "type": "string" }, "first_name": { "type": "string" }, "last_name": { "type": "string" }, "username": { "type": "string", "description": "Profile slug (the part after /in/)." }, "current_title": { "type": "string" }, "current_company": { "type": "string" }, "current_company_id": { "type": "string" }, "current_company_username": { "type": "string" }, "current_company_industry": { "type": "string" }, "current_company_staff_range": { "type": "string", "example": "2 - 10" }, "seniority": { "type": "string", "description": "Inferred seniority band.", "enum": [ "c-level", "vp", "director", "manager" ] }, "education_schools": { "type": "array", "description": "School names (search results only).", "items": { "type": "string" } }, "past_companies": { "type": "array", "description": "Previous employer names (search results only).", "items": { "type": "string" } }, "headline": { "type": "string" }, "summary": { "type": "string" }, "geo_city": { "type": "string" }, "geo_country": { "type": "string" }, "geo_country_code": { "type": "string" }, "linkedin_url": { "type": "string" }, "profile_picture_url": { "type": "string" }, "is_premium": { "type": "boolean" }, "is_top_voice": { "type": "boolean" }, "is_creator": { "type": "boolean" }, "fetched_at": { "type": "string", "format": "date-time", "description": "When we last verified this profile against its public source. All data comes from our data lake, use this to gauge freshness." }, "skills_count": { "type": "integer" }, "skills_preview": { "type": "array", "items": { "type": "string" } }, "certifications_count": { "type": "integer" }, "positions_count": { "type": "integer" }, "educations_count": { "type": "integer" }, "positions": { "type": "array", "description": "Full work history, newest first.", "items": { "$ref": "#/components/schemas/Position" } }, "educations": { "type": "array", "items": { "$ref": "#/components/schemas/Education" } }, "skills": { "type": "array", "items": { "$ref": "#/components/schemas/Skill" } }, "certifications": { "type": "array", "items": { "$ref": "#/components/schemas/Certification" } }, "honors": { "type": "array", "items": { "$ref": "#/components/schemas/Honor" } }, "publications": { "type": "array", "items": { "$ref": "#/components/schemas/Publication" } }, "volunteering": { "type": "array", "items": { "$ref": "#/components/schemas/Volunteering" } }, "languages": { "type": "array", "nullable": true, "description": "Languages listed on the profile, in the order shown on LinkedIn.", "items": { "$ref": "#/components/schemas/Language" } }, "featured": { "type": "array", "nullable": true, "description": "Featured content pinned to the profile (posts, articles, links).", "items": { "$ref": "#/components/schemas/Featured" } }, "courses": { "type": "array", "nullable": true, "items": { "$ref": "#/components/schemas/Course" } }, "is_open_to_work": { "type": "boolean", "nullable": true, "description": "True only when the person has explicitly enabled LinkedIn's Open to Work signal. Absent (null) means the signal was not set, not that it is false." }, "is_hiring": { "type": "boolean", "nullable": true, "description": "True only when the person displays the Hiring badge on their profile. Absent (null) means the badge was not set, not that they are not hiring." }, "linkedin_id": { "type": "string", "description": "LinkedIn's own numeric profile ID." }, "linkedin_urn": { "type": "string", "description": "LinkedIn's opaque profile URN." }, "background_image_url": { "type": "array", "nullable": true, "description": "Profile background/cover image, one entry per rendition LinkedIn generated (typically two sizes).", "items": { "type": "object", "properties": { "url": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" } } } }, "primary_locale_country": { "type": "string", "description": "ISO 2-letter country code of the profile's LinkedIn locale." }, "primary_locale_language": { "type": "string", "description": "2-letter language code of the profile's LinkedIn locale." }, "projects": { "type": "object", "nullable": true, "description": "Projects listed on the profile." } } }, "Language": { "type": "object", "properties": { "name": { "type": "string" }, "proficiency": { "type": "string", "description": "LinkedIn's proficiency band, e.g. NATIVE_OR_BILINGUAL, FULL_PROFESSIONAL. Empty string when not specified." } } }, "Featured": { "type": "object", "properties": { "title": { "type": "string" }, "url": { "type": "string" }, "providerName": { "type": "string", "nullable": true }, "previewImage": { "nullable": true, "description": "One or more renditions of the preview image. A single URL string is possible; an array of {url, width, height} is what the source normally returns.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" } } } } ] } } }, "Course": { "type": "object", "properties": { "name": { "type": "string" }, "number": { "type": "string", "nullable": true } } }, "DateParts": { "type": "object", "description": "Partial date. A value of 0 means the component is unknown.", "properties": { "year": { "type": "integer" }, "month": { "type": "integer" }, "day": { "type": "integer" } } }, "Position": { "type": "object", "properties": { "title": { "type": "string" }, "companyName": { "type": "string" }, "companyId": { "type": "string" }, "companyUsername": { "type": "string" }, "companyURL": { "type": "string", "nullable": true }, "companyLogo": { "type": "string", "nullable": true }, "companyIndustry": { "type": "string" }, "companyStaffCountRange": { "type": "string", "example": "11 - 50" }, "location": { "type": "string" }, "locationType": { "type": "string", "nullable": true, "description": "e.g. \"Remote\", \"Hybrid\", when stated." }, "employmentType": { "type": "string", "nullable": true, "description": "e.g. \"Full-time\", \"Contract\", when stated." }, "isCurrent": { "type": "boolean" }, "startYear": { "type": "integer" }, "startMonth": { "type": "integer" }, "endYear": { "type": "integer", "nullable": true }, "endMonth": { "type": "integer", "nullable": true }, "description": { "type": "string", "nullable": true } } }, "Education": { "type": "object", "properties": { "schoolName": { "type": "string" }, "schoolId": { "type": "string", "nullable": true }, "degree": { "type": "string", "nullable": true }, "fieldOfStudy": { "type": "string", "nullable": true }, "grade": { "type": "string", "nullable": true }, "startYear": { "type": "integer", "nullable": true }, "startMonth": { "type": "integer", "nullable": true }, "endYear": { "type": "integer", "nullable": true }, "endMonth": { "type": "integer", "nullable": true }, "activities": { "type": "string", "nullable": true, "description": "Societies, sports, and other activities, as one free-text string." }, "description": { "type": "string", "nullable": true }, "url": { "type": "string", "nullable": true }, "logo": { "nullable": true, "description": "One or more renditions of the school's logo, when LinkedIn provided one. Some schools return a single URL string, others an array of {url, width, height} — shape is passed through as received.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" } } } } ] } } }, "Skill": { "type": "object", "properties": { "name": { "type": "string" }, "endorsementsCount": { "type": "integer" }, "passedSkillAssessment": { "type": "boolean" } } }, "Certification": { "type": "object", "properties": { "name": { "type": "string" }, "authority": { "type": "string", "nullable": true, "description": "Issuing body as free text. Present far more often than the resolved company page." }, "company": { "type": "object", "properties": { "name": { "type": "string" }, "universalName": { "type": "string" } } }, "companyId": { "type": "string", "nullable": true, "description": "Part of the shape but not currently populated by our source." }, "start": { "$ref": "#/components/schemas/DateParts" }, "end": { "$ref": "#/components/schemas/DateParts" }, "timePeriod": { "type": "object", "nullable": true, "description": "Validity window, when the source reports one separately from start and end.", "properties": { "start": { "$ref": "#/components/schemas/DateParts" }, "end": { "$ref": "#/components/schemas/DateParts" } } }, "credentialId": { "type": "string", "nullable": true, "description": "Part of the shape but not currently populated by our source." }, "credentialUrl": { "type": "string", "nullable": true, "description": "Part of the shape but not currently populated by our source." } } }, "Honor": { "type": "object", "properties": { "title": { "type": "string" }, "issuer": { "type": "string" }, "issuerLogo": { "type": "string", "nullable": true }, "issuedOn": { "$ref": "#/components/schemas/DateParts" }, "description": { "type": "string", "nullable": true } } }, "Publication": { "type": "object", "properties": { "name": { "type": "string" }, "publisher": { "type": "string" }, "url": { "type": "string", "nullable": true }, "publishedOn": { "$ref": "#/components/schemas/DateParts" } } }, "Volunteering": { "type": "object", "properties": { "title": { "type": "string" }, "company": { "type": "string", "nullable": true }, "companyId": { "type": "string", "nullable": true }, "companyUrl": { "type": "string", "nullable": true }, "companyLogo": { "type": "string", "nullable": true }, "start": { "$ref": "#/components/schemas/DateParts" }, "end": { "$ref": "#/components/schemas/DateParts" }, "description": { "type": "string", "nullable": true } } }, "CompanyResult": { "type": "object", "properties": { "id": { "type": "string" }, "company_id": { "type": "string", "description": "Numeric company ID (use with /company/current-employees and /company/past-employees)." }, "name": { "type": "string" }, "tagline": { "type": "string" }, "description": { "type": "string" }, "website": { "type": "string" }, "linkedin_url": { "type": "string" }, "company_type": { "type": "string" }, "founded_year": { "type": "integer" }, "staff_count": { "type": "integer" }, "follower_count": { "type": "integer" }, "hq_city": { "type": "string" }, "hq_country": { "type": "string", "nullable": true, "description": "Full country name of the headquarters. hq_country_code carries the ISO 2-letter form." }, "hq_country_code": { "type": "string" }, "hq_geographic_area": { "type": "string", "description": "State / region of the HQ." }, "hq_postal_code": { "type": "string" }, "hq_line1": { "type": "string" }, "hq_line2": { "type": "string", "nullable": true }, "hq_description": { "type": "string", "nullable": true, "description": "Label the company gives its headquarters, e.g. \"Headquarters\"." }, "phone": { "type": "string", "nullable": true }, "is_verified": { "type": "boolean", "nullable": true }, "page_verification": { "type": "object", "nullable": true, "description": "Verification state with its timestamp. is_verified is the same boolean on its own.", "properties": { "verified": { "type": "boolean" }, "lastModifiedAt": { "type": "integer", "description": "Unix timestamp in milliseconds. 0 when never verified." } } }, "industries": { "type": "array", "items": { "type": "string" } }, "specialities": { "type": "array", "items": { "type": "string" } }, "locations": { "type": "array", "description": "All known office locations.", "items": { "$ref": "#/components/schemas/Location" } }, "logo_url": { "type": "string" }, "cover_image_url": { "type": "string", "nullable": true, "description": "Cover / banner image shown on the company's LinkedIn page." }, "username": { "type": "string", "description": "Company slug after /company/ in the LinkedIn URL. Same value accepted by the username parameter on this endpoint." }, "crunchbase_url": { "type": "string", "nullable": true }, "call_to_action_url": { "type": "string", "nullable": true, "description": "Destination of the call-to-action button on the company's LinkedIn page (e.g. \"Visit website\")." }, "call_to_action": { "type": "object", "nullable": true, "description": "The whole call-to-action button. call_to_action_url is the same destination on its own, kept for existing integrations.", "properties": { "type": { "type": "string", "description": "e.g. \"LEARN_MORE\", \"VIEW_WEBSITE\"." }, "url": { "type": "string" }, "displayText": { "type": "string" }, "visible": { "type": "boolean" }, "callToActionMessage": { "type": "object", "nullable": true } } }, "is_claimable": { "type": "boolean", "nullable": true, "description": "Whether the LinkedIn page is unclaimed and open for an admin to take over." }, "affiliated_pages": { "type": "array", "nullable": true, "description": "Other LinkedIn company pages affiliated with this one (subsidiaries, related brands).", "items": { "type": "object", "properties": { "id": { "type": "string" }, "name": { "type": "string" }, "universalName": { "type": "string" }, "linkedinURL": { "type": "string" }, "logo": { "nullable": true, "description": "One or more renditions of the affiliated page logo.", "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "object", "properties": { "url": { "type": "string" }, "width": { "type": "integer" }, "height": { "type": "integer" } } } } ] } } } }, "featured_customers": { "nullable": true, "description": "Customer logos the company features on its page. Rarely populated; the structure is passed through from the source unchanged." }, "fetched_at": { "type": "string", "format": "date-time", "description": "When we last verified this company against its public source. All data comes from our data lake, use this to gauge freshness." } } }, "Location": { "type": "object", "properties": { "city": { "type": "string" }, "description": { "type": "string", "nullable": true, "description": "Label for this office, e.g. \"Headquarters\" or a city-specific name." }, "line1": { "type": "string", "nullable": true }, "line2": { "type": "string", "nullable": true }, "country": { "type": "string", "description": "ISO 2-letter country code." }, "countryCode": { "type": "string", "nullable": true, "description": "ISO 2-letter code. country carries the full name." }, "postalCode": { "type": "string", "nullable": true }, "geographicArea": { "type": "string", "nullable": true }, "isHeadquarter": { "type": "boolean" } } }, "Pagination": { "type": "object", "properties": { "total": { "type": "integer" }, "page": { "type": "integer" }, "per_page": { "type": "integer" } } }, "Monitor": { "type": "object", "properties": { "id": { "type": "string", "format": "uuid" }, "type": { "type": "string", "enum": [ "person", "company" ] }, "subject_url": { "type": "string", "description": "The profile or company URL being monitored." }, "label": { "type": "string", "nullable": true, "description": "Optional human-readable label for this monitor." }, "webhook_url": { "type": "string", "description": "HTTPS URL that receives change events." }, "events": { "type": "array", "items": { "type": "string" }, "description": "Event types subscribed to. See event reference below." }, "active": { "type": "boolean" }, "created_at": { "type": "string", "format": "date-time" } } }, "WebhookPayload": { "type": "object", "description": "Payload sent to your webhook_url on each change event.", "properties": { "id": { "type": "string", "format": "uuid", "description": "Unique delivery ID." }, "event": { "type": "string", "example": "person.job_changed", "description": "Event type that fired." }, "monitor_id": { "type": "string", "format": "uuid" }, "timestamp": { "type": "string", "description": "Unix timestamp (seconds) of the delivery." }, "diff": { "type": "object", "description": "What changed. Fields vary by event type.", "example": { "old_company": "Acme Corp", "new_company": "Stripe", "old_company_id": "12345", "new_company_id": "2135371", "old_title": "Engineer", "new_title": "Senior Engineer" } } } }, "WebhookDeliveryExample": { "type": "object", "description": "Example webhook payload for person.job_changed event.", "example": { "id": "c1c882c8-f172-4c00-8efc-be6fa9e3add4", "event": "person.job_changed", "monitor_id": "45e0bba8-196d-4f5e-aecc-52332ca832e2", "timestamp": "1752918000", "diff": { "old_company": "Microsoft", "new_company": "OpenAI", "old_company_id": "1035", "new_company_id": "157240", "old_title": "CEO", "new_title": "Board Member" } } }, "RateLimitWindow": { "type": "object", "properties": { "limit": { "type": "integer", "example": 500 }, "remaining": { "type": "integer", "example": 497 }, "reset_at": { "type": "string", "format": "date-time", "description": "When the window resets. Absolute, so a scheduler can act on it." } } }, "Quotas": { "type": "object", "description": "Where you stand, returned on every response including errors. There is no need to call another endpoint to read your balance.", "properties": { "rate_limit": { "type": "object", "properties": { "workspace": { "$ref": "#/components/schemas/RateLimitWindow" }, "member": { "allOf": [ { "$ref": "#/components/schemas/RateLimitWindow" } ], "description": "Only present when the workspace owner gave your account its own allowance out of the workspace total. Whichever window is tighter is the one that will stop you." } } } } }, "Metadata": { "type": "object", "description": "Returned on every response.", "properties": { "request_id": { "type": "string", "description": "Also returned as an `x-request-id` header. Quote it when contacting support and the request can be found immediately.", "example": "req_62412932b02349b08a179f69" }, "execution_ms": { "type": "integer", "example": 74 } } } }, "responses": { "Unauthorized": { "description": "Invalid or missing API key", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Invalid or missing API key" } } } }, "NotFound": { "description": "Not found", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Profile not found" } } } }, "BadRequest": { "description": "Missing or invalid parameters", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "company_id is required" } } } }, "RateLimited": { "description": "Rate limit exceeded. Wait for the number of seconds in `Retry-After`.", "headers": { "Retry-After": { "description": "Seconds until the window resets.", "schema": { "type": "integer", "example": 53 } } }, "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Rate limit exceeded. Max 500 requests per minute per workspace.", "code": "RATE_LIMIT_EXCEEDED" } } } }, "DataSubjectBlocked": { "description": "Unavailable due to privacy protection. Different from `404` on purpose: a `404` may be worth retrying later or with another identifier, while this record has been withdrawn under a privacy request and no identifier will reach it.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Unavailable due to privacy protection (GDPR / CCPA).", "code": "DATA_SUBJECT_BLOCKED" } } } }, "LicenseInactive": { "description": "Workspace has no active license", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" }, "example": { "error": "Your workspace has no active license. Subscribe at kooperativa.io/pricing to restore access.", "code": "LICENSE_INACTIVE" } } } } } }, "tags": [ { "name": "People", "x-scalar-icon": "users", "description": "Enrich and search individual profiles. Access is unlimited." }, { "name": "Companies", "x-scalar-icon": "buildings", "description": "Enrich and search companies and their employees. Access is unlimited." }, { "name": "Account", "x-scalar-icon": "user-circle", "description": "Account details, license status, and usage, always unlimited." }, { "name": "Status", "x-scalar-icon": "signal", "description": "API liveness check, **free**, no authentication required." }, { "name": "Monitors", "x-scalar-icon": "bell", "description": "Monitor a profile or company for changes. When a change is detected, Kooperativa sends a signed webhook to your endpoint. Unlimited, like every other endpoint." } ], "paths": { "/health": { "get": { "tags": [ "Status" ], "summary": "Health Check", "description": "Simple liveness probe for the API. Does not require authentication and is unlimited. Use this to verify connectivity before running a batch job.", "operationId": "getHealth", "security": [], "x-codeSamples": [ { "lang": "js", "label": "JavaScript", "source": "const res = await fetch(\"https://kooperativa.io/api/v1/health\");\nconst { ok } = await res.json();" }, { "lang": "shell", "label": "cURL", "source": "curl \"https://kooperativa.io/api/v1/health\"" } ], "responses": { "200": { "description": "Service is up", "content": { "application/json": { "schema": { "type": "object", "properties": { "ok": { "type": "boolean" } } }, "example": { "ok": true } } } }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/person": { "get": { "tags": [ "People" ], "summary": "Enrich Person", "description": "Return a person's full professional profile from our data lake, by any single identifier you already have.\n\nProvide **one** of `linkedin_url`, `username`, or `id`, they are checked in that order (linkedin_url, then username, then id). The payload comes back with positions, educations, skills, certifications, honors, publications, and volunteering all expanded, plus a `fetched_at` timestamp showing how recently we verified the profile.\n\n### Tips\n- `username` is the fastest lookup (the slug after `/in/`).\n- Use the returned `current_company_id` to feed [Company Employees](#tag/companies).\n- This looks up our existing data lake only. If the profile hasn't been indexed yet, you'll get a `404`. To fetch it from the live source instead, use [Enrich Person (Realtime)](#tag/people), which is metered at $0.001 per call.", "operationId": "enrichPerson", "x-codeSamples": [ { "lang": "js", "label": "JavaScript", "source": "const res = await fetch(\n \"https://kooperativa.io/api/v1/person?username=daniel-goettenauer\",\n { headers: { Authorization: `Bearer ${process.env.KOOPERATIVA_API_KEY}` } }\n);\nconst { data } = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os, requests\n\nres = requests.get(\n \"https://kooperativa.io/api/v1/person\",\n params={\"username\": \"daniel-goettenauer\"},\n headers={\"Authorization\": f\"Bearer {os.environ['KOOPERATIVA_API_KEY']}\"},\n)\ndata = res.json()[\"data\"]" }, { "lang": "shell", "label": "cURL", "source": "curl \"https://kooperativa.io/api/v1/person?username=daniel-goettenauer\" \\\n -H \"Authorization: Bearer $KOOPERATIVA_API_KEY\"" }, { "lang": "php", "label": "PHP", "source": " \"VP of Sales\",\n \"location\" => \"US\",\n \"industry\" => \"Computer Software\",\n \"per_page\" => 10,\n]));\n$payload = json_decode(curl_exec($ch), true);" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Full-text search across name, title, and company (used when no other filters narrow the result set)" }, "title": { "type": "string", "description": "Job title keywords. Multiple space-separated words are matched independently (OR) against the title.", "example": "VP of Sales" }, "company": { "type": "string", "description": "Current company name, matched exactly. Prefer company_id when available." }, "company_id": { "type": "string", "description": "Company ID (exact match, preferred over `company`)" }, "location": { "description": "ISO 2-letter country code (e.g. \"US\", \"DE\", \"GB\"). Must be the ISO code, full country names such as \"United States\" will return 0 results. Pass an array to match any of several countries.", "oneOf": [ { "type": "string", "example": "US" }, { "type": "array", "items": { "type": "string" }, "example": [ "US", "CA", "GB" ] } ] }, "city": { "type": "string" }, "industry": { "description": "Industry name as stored on the profile. Must be an exact match. Pass an array to match any of several industries. Common values: \"Computer Software\", \"Information Technology & Services\", \"Financial Services\", \"Hospital & Health Care\", \"Higher Education\", \"Management Consulting\", \"Marketing & Advertising\", \"Real Estate\", \"Banking\", \"Insurance\", \"Retail\", \"Pharmaceuticals\", \"Telecommunications\".", "oneOf": [ { "type": "string", "example": "Computer Software" }, { "type": "array", "items": { "type": "string" }, "example": [ "Computer Software", "Information Technology & Services" ] } ] }, "seniority": { "type": "string", "enum": [ "c-level", "vp", "director", "manager" ] }, "headcount": { "type": "string", "description": "Current company's employee-count range, matched exactly against one of the ranges returned by the API (e.g. `current_company_staff_range` on a PersonResult).", "example": "51 - 200" }, "is_premium": { "type": "boolean", "description": "Only Premium members" }, "is_top_voice": { "type": "boolean", "description": "Only Top Voices" }, "is_creator": { "type": "boolean", "description": "Only Creators" }, "skills": { "type": "array", "items": { "type": "string" }, "description": "Match people who list any of these skills (OR).", "example": [ "Python", "Salesforce" ] }, "tenure_min_months": { "type": "integer", "description": "Only people who have been in their current role for at least this many months, targets stable, established employees." }, "job_changed_after": { "type": "integer", "description": "Unix timestamp (seconds). Only people who started their current role after this time, useful for \"recently changed jobs\" outreach timing." }, "exclude_companies": { "type": "array", "items": { "type": "string" }, "description": "Hide people currently working at any of these companies (exact name match)." }, "exclude_industries": { "type": "array", "items": { "type": "string" }, "description": "Hide people whose current company is in any of these industries." }, "past_company": { "type": "string", "description": "Match people who previously worked at this company" }, "education": { "type": "string", "description": "School/university name" }, "linkedin_url": { "type": "string", "description": "Exact profile URL, resolves to a single person via their username" }, "page": { "type": "integer", "default": 1 }, "per_page": { "type": "integer", "default": 10, "maximum": 50 } } }, "example": { "title": "VP of Sales", "location": "US", "industry": "Computer Software", "seniority": "vp", "per_page": 10 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/PersonResult" } } } } ] }, "example": { "results": [ { "id": "b9847f21-9764-4903-8087-1be343fdaa5c", "full_name": "Isaac Simpson", "current_title": "Chief", "current_company": "WILL", "current_company_id": "65621360", "current_company_industry": "Marketing and Advertising", "current_company_staff_range": "2 - 10", "headline": "Brander. Believer.", "geo_city": "Los Angeles, California", "geo_country": "United States", "geo_country_code": "US", "seniority": "c-level", "is_premium": false, "education_schools": [ "Tulane University Law School", "ESADE Business & Law School", "The George Washington University" ], "past_companies": [ "72andSunny", "Influential", "NVE Experience Agency" ], "linkedin_url": "https://www.linkedin.com/in/isaacsimpson" } ], "total": 68496, "page": 1, "per_page": 10 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/companies/search": { "post": { "tags": [ "Companies" ], "summary": "Search Companies", "description": "Search our data lake of companies by name, location, industry, and headcount range. All filters are optional and combine with AND logic.\n\nUse `min_staff` / `max_staff` to target a company size band, both bounds are inclusive and either can be omitted.\n\n> **At least one filter is required.** Requests with an empty body are rejected with HTTP 400.", "operationId": "searchCompanies", "x-codeSamples": [ { "lang": "js", "label": "JavaScript", "source": "const res = await fetch(\n \"https://kooperativa.io/api/v1/companies/search\",\n {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.KOOPERATIVA_API_KEY}`,\n \"Content-Type\": \"application/json\",\n },\n body: JSON.stringify({\n industry: \"Software Development\",\n country: \"US\",\n min_staff: 50,\n max_staff: 500,\n }),\n }\n);\nconst { results, total } = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os, requests\n\nres = requests.post(\n \"https://kooperativa.io/api/v1/companies/search\",\n headers={\"Authorization\": f\"Bearer {os.environ['KOOPERATIVA_API_KEY']}\"},\n json={\n \"industry\": \"Software Development\",\n \"country\": \"US\",\n \"min_staff\": 50,\n \"max_staff\": 500,\n },\n)\npayload = res.json()" }, { "lang": "shell", "label": "cURL", "source": "curl -X POST \"https://kooperativa.io/api/v1/companies/search\" \\\n -H \"Authorization: Bearer $KOOPERATIVA_API_KEY\" \\\n -H \"Content-Type: application/json\" \\\n -d '{\"industry\":\"Software Development\",\"country\":\"US\",\"min_staff\":50,\"max_staff\":500}'" }, { "lang": "php", "label": "PHP", "source": " \"Software Development\",\n \"country\" => \"US\",\n \"min_staff\" => 50,\n \"max_staff\" => 500,\n]));\n$payload = json_decode(curl_exec($ch), true);" } ], "requestBody": { "content": { "application/json": { "schema": { "type": "object", "properties": { "query": { "type": "string", "description": "Full-text search across company name and tagline" }, "country": { "type": "string", "description": "HQ country code, must be ISO 2-letter (e.g. \"US\", \"DE\", \"GB\"). Full country names will return 0 results.", "example": "US" }, "city": { "type": "string", "description": "HQ city name" }, "industry": { "type": "string", "description": "Industry label using the newer company taxonomy. Must be an exact match. Common values: \"Software Development\", \"IT Services and IT Consulting\", \"Technology, Information and Internet\", \"Advertising Services\", \"Business Consulting and Services\", \"Financial Services\", \"Non-profit Organizations\", \"Real Estate\", \"Higher Education\", \"Hospitals and Health Care\", \"Staffing and Recruiting\", \"Retail\", \"Marketing Services\", \"Venture Capital and Private Equity Principals\", \"Construction\", \"Telecommunications\". Note: this taxonomy differs from the industry values used in /people/search.", "example": "Software Development" }, "min_staff": { "type": "integer", "description": "Minimum employee count (inclusive)" }, "max_staff": { "type": "integer", "description": "Maximum employee count (inclusive)" }, "page": { "type": "integer", "default": 1 }, "per_page": { "type": "integer", "default": 10, "maximum": 50 } } }, "example": { "industry": "Software Development", "country": "US", "min_staff": 50, "max_staff": 500 } } } }, "responses": { "200": { "description": "Success", "content": { "application/json": { "schema": { "allOf": [ { "$ref": "#/components/schemas/Pagination" }, { "type": "object", "properties": { "results": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyResult" } } } } ] }, "example": { "results": [ { "id": "86b4082f-a047-4c1d-ae92-774168095705", "company_id": "23676", "name": "MAK Technologies", "tagline": "Open Systems. Open Standards. Open APIs.", "website": "http://www.mak.com", "linkedin_url": "https://www.linkedin.com/company/mak", "founded_year": 1990, "staff_count": 259, "follower_count": 5803, "hq_city": "Cambridge", "hq_country_code": "US", "industries": [ "Software Development" ], "logo_url": "https://api-origin.kooperativa.io/img/c/86b4082f-a047-4c1d-ae92-774168095705" }, { "id": "37c41c0f-0c58-49ee-8403-30faa6e3239e", "company_id": "71610067", "name": "Infinity Soft Systems", "tagline": "Transforming businesses with innovative IT and digital marketing solutions", "website": "https://www.infinitysoftsystems.com/", "linkedin_url": "https://www.linkedin.com/company/infinitysoftsystems", "founded_year": 2020, "staff_count": 172, "follower_count": 9698, "hq_city": "Austin", "hq_country_code": "US", "industries": [ "Software Development" ], "logo_url": "https://api-origin.kooperativa.io/img/c/37c41c0f-0c58-49ee-8403-30faa6e3239e" } ], "total": 3674, "page": 1, "per_page": 10 } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "429": { "$ref": "#/components/responses/RateLimited" } } } }, "/company/current-employees": { "get": { "tags": [ "Companies" ], "summary": "Current Employees", "description": "List the people **currently** working at a company, by its numeric `company_id`.\n\nEach result is a lightweight profile preview, pass a result's `id` to [Enrich Person](#tag/people) for the full record. Paginated up to 100 per page, with `total` and `pages` for offset pagination.", "operationId": "companyCurrentEmployees", "x-codeSamples": [ { "lang": "js", "label": "JavaScript", "source": "const res = await fetch(\n \"https://kooperativa.io/api/v1/company/current-employees?company_id=31420&per_page=25\",\n { headers: { Authorization: `Bearer ${process.env.KOOPERATIVA_API_KEY}` } }\n);\nconst { employees, total, pages } = await res.json();" }, { "lang": "python", "label": "Python", "source": "import os, requests\n\nres = requests.get(\n \"https://kooperativa.io/api/v1/company/current-employees\",\n params={\"company_id\": \"31420\", \"per_page\": 25},\n headers={\"Authorization\": f\"Bearer {os.environ['KOOPERATIVA_API_KEY']}\"},\n)\npayload = res.json()" }, { "lang": "shell", "label": "cURL", "source": "curl \"https://kooperativa.io/api/v1/company/current-employees?company_id=31420&per_page=25\" \\\n -H \"Authorization: Bearer $KOOPERATIVA_API_KEY\"" }, { "lang": "php", "label": "PHP", "source": "