{ "openapi": "3.1.0", "info": { "title": "Airscale Public API", "version": "2026-09-11", "description": "Search, enrich, and resolve public business data with Airscale.", "x-airscale-source-repository": "ViceScale/airscale-code", "x-airscale-source-sha": "1de19e1b70a052a4b8d9c2075021a7e5e7a94d51" }, "servers": [ { "url": "https://api.airscale.io", "description": "Production" } ], "tags": [ { "name": "Search and discovery", "description": "Search people, companies, and the web." }, { "name": "Contact data", "description": "Find professional and personal contact data." }, { "name": "Profiles and reverse lookup", "description": "Extract profiles or resolve a person from known contact data." }, { "name": "Post engagement", "description": "Retrieve and enrich people who liked or commented on LinkedIn posts." }, { "name": "LinkedIn content", "description": "Search LinkedIn posts, read profile and company feeds, and retrieve profile comments and comment reactions." }, { "name": "Account", "description": "Inspect workspace account state." }, { "name": "Miscellaneous", "description": "Check WhatsApp availability, Meta ads, and email deliverability." } ], "security": [ { "bearerAuth": [] } ], "paths": { "/v1/credits": { "post": { "operationId": "getCredits", "tags": [ "Account" ], "summary": "Get workspace credit balance", "description": "Returns the current Airscale credit balance for the authenticated workspace.", "x-airscale-rate-limit": "No endpoint-specific rate limit is documented.", "x-airscale-credit-cost": "No charge; checking the balance does not debit Airscale credits.", "responses": { "200": { "description": "The current workspace credit balance.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "response" ], "additionalProperties": false, "properties": { "status": { "type": "string", "const": "success" }, "response": { "type": "object", "required": [ "credits" ], "additionalProperties": false, "properties": { "credits": { "type": "number" } } } } }, "examples": { "success": { "summary": "Credit balance", "value": { "status": "success", "response": { "credits": 1200 } } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "500": { "description": "The credit balance could not be retrieved because of an unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The credit balance is temporarily unavailable. Try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/email": { "post": { "operationId": "findProfessionalEmail", "tags": [ "Contact data" ], "summary": "Find a professional email", "description": "Finds a professional email from a recognized person profile or from a complete name and company identifier. The JSON request body is limited to 256 KiB.", "x-airscale-rate-limit": "3,000 requests per minute per workspace.", "x-airscale-credit-cost": "2 credits only when the response has status success; not_found is not charged.", "requestBody": { "required": true, "description": "Provide either a recognized non-empty person profile, or first and last name with a domain or company name. Both complete forms may be supplied together. The JSON body must not exceed 256 KiB.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "properties": { "linkedin_profile_url": { "$ref": "#/components/schemas/LinkedInPersonUrl" }, "first_name": { "type": "string", "minLength": 1 }, "last_name": { "type": "string", "minLength": 1 }, "domain": { "type": "string", "minLength": 1 }, "company_name": { "type": "string", "minLength": 1 } }, "if": { "not": { "required": [ "linkedin_profile_url" ] } }, "then": { "required": [ "first_name", "last_name" ], "anyOf": [ { "required": [ "domain" ] }, { "required": [ "company_name" ] } ] } }, "examples": { "allKnownFields": { "summary": "Combine all known fields", "value": { "linkedin_profile_url": "https://www.linkedin.com/in/example-person-000000", "first_name": "Example", "last_name": "Person", "domain": "example.org", "company_name": "Example Company" } }, "byCompanyName": { "summary": "Name and company name", "value": { "first_name": "Example", "last_name": "Person", "company_name": "Example Company" } }, "byProfile": { "summary": "LinkedIn profile URL alone", "value": { "linkedin_profile_url": "https://www.linkedin.com/in/example-person-000000" } }, "byName": { "summary": "Identify by name and domain", "value": { "first_name": "Example", "last_name": "Person", "domain": "example.org" } } } } } }, "responses": { "200": { "description": "A professional email result or a not-found result.", "content": { "application/json": { "schema": { "oneOf": [ { "$ref": "#/components/schemas/SuccessEmail" }, { "$ref": "#/components/schemas/NotFoundEmail" } ] }, "examples": { "success": { "summary": "Email found", "value": { "status": "success", "email": "example.person@example.org", "email_status": "valid", "provider": "", "verifier": "", "catch_all": "no", "linkedin_profile_url": "https://www.linkedin.com/in/example-person-000000" } }, "notFound": { "summary": "No email found", "value": { "status": "not_found", "email": null } } } } } }, "400": { "description": "The JSON body is invalid or required identification fields are missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The workspace cannot complete this request because access or available credits are insufficient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the 256 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The workspace rate limit has been exceeded. Try again after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request could not be completed because of an unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The request could not be completed because a required service returned an unsuccessful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The request is temporarily unavailable. Try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/email-bulk": { "post": { "operationId": "findProfessionalEmailsBulk", "tags": [ "Contact data" ], "summary": "Submit a professional email batch", "description": "Accepts up to 100 professional-email inputs and sends results to the supplied HTTP webhook URL after processing.", "x-airscale-rate-limit": "3,000 input items per minute per workspace.", "x-airscale-credit-cost": "2 credits per item with status success; misses and timeouts are not charged.", "requestBody": { "required": true, "description": "Provide a webhook URL and between 1 and 100 inputs. Each input may include an optional custom_id and must identify a person by profile or by complete name and company information.", "content": { "application/json": { "schema": { "type": "object", "required": [ "webhook_url", "inputs" ], "additionalProperties": false, "properties": { "webhook_url": { "type": "string", "minLength": 1, "pattern": "^http" }, "inputs": { "type": "array", "minItems": 1, "maxItems": 100, "items": { "type": "object", "additionalProperties": false, "properties": { "custom_id": { "description": "If omitted or null, the item's zero-based array index is used; any other JSON value is echoed unchanged." }, "linkedin_profile_url": { "$ref": "#/components/schemas/LinkedInPersonUrl" }, "first_name": { "type": "string", "minLength": 1 }, "last_name": { "type": "string", "minLength": 1 }, "domain": { "type": "string", "minLength": 1 }, "company_name": { "type": "string", "minLength": 1 } }, "if": { "not": { "required": [ "linkedin_profile_url" ] } }, "then": { "required": [ "first_name", "last_name" ], "anyOf": [ { "required": [ "domain" ] }, { "required": [ "company_name" ] } ] } } } } }, "examples": { "batch": { "summary": "Two synthetic contacts", "value": { "webhook_url": "https://webhook.example.org/email-results", "inputs": [ { "custom_id": "contact-001", "linkedin_profile_url": "https://www.linkedin.com/in/example-person-000000" }, { "custom_id": 2002, "first_name": "Sample", "last_name": "Contact", "company_name": "Example Company" } ] } } } } } }, "responses": { "202": { "description": "The batch was accepted for asynchronous processing.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "count" ], "additionalProperties": false, "properties": { "status": { "type": "string", "const": "accepted" }, "count": { "type": "integer", "minimum": 1, "maximum": 100 } } }, "examples": { "accepted": { "summary": "Batch accepted", "value": { "status": "accepted", "count": 2 } } } } } }, "400": { "description": "The JSON body is invalid or required identification fields are missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The workspace cannot complete this request because access or available credits are insufficient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the 256 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The workspace rate limit has been exceeded. Try again after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request could not be completed because of an unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The request could not be completed because a required service returned an unsuccessful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/phone": { "post": { "operationId": "findMobilePhone", "x-airscale-source-sha": "9bc50ab50731f1793c4ed794776b2fee821d67ca", "tags": [ "Contact data" ], "summary": "Find a mobile phone number", "description": "Finds a primary mobile phone number and all available normalized phone numbers for a recognized person profile.", "x-airscale-rate-limit": "3,000 requests per minute per workspace.", "x-airscale-credit-cost": "40 credits only when the response has status success; not_found is not charged.", "requestBody": { "required": true, "description": "Provide the recognized person profile to search.", "content": { "application/json": { "schema": { "type": "object", "required": [ "linkedin_profile_url" ], "additionalProperties": false, "properties": { "linkedin_profile_url": { "$ref": "#/components/schemas/LinkedInPersonUrl" } } }, "examples": { "profile": { "summary": "Person profile", "value": { "linkedin_profile_url": "https://www.linkedin.com/in/example-person-000000" } } } } } }, "responses": { "200": { "description": "A mobile phone result or a not-found result.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "status", "linkedin_profile_url", "phone_numbers", "all_phone_numbers", "provider" ], "additionalProperties": true, "properties": { "status": { "type": "string", "const": "success" }, "linkedin_profile_url": { "$ref": "#/components/schemas/LinkedInPersonUrl" }, "phone_numbers": { "type": "string", "description": "The primary phone number, returned as a single string." }, "all_phone_numbers": { "type": "array", "minItems": 1, "uniqueItems": true, "items": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$" }, "description": "All available normalized phone numbers, with duplicates removed and the primary number first. May contain only the primary number." }, "provider": { "type": [ "string", "null" ], "description": "The name of the source that returned the number. Present on successful results." } } }, { "type": "object", "required": [ "status", "linkedin_profile_url", "phone_numbers", "all_phone_numbers", "provider" ], "additionalProperties": true, "properties": { "status": { "type": "string", "const": "not_found" }, "linkedin_profile_url": { "$ref": "#/components/schemas/LinkedInPersonUrl" }, "phone_numbers": { "type": "null" }, "all_phone_numbers": { "type": "array", "maxItems": 0, "items": { "type": "string" }, "description": "An empty array when no phone number is found." }, "provider": { "type": [ "string", "null" ] } } } ] }, "examples": { "success": { "summary": "Primary and additional mobile phones found", "value": { "status": "success", "linkedin_profile_url": "https://www.linkedin.com/in/example-person-000000", "phone_numbers": "+12025550147", "all_phone_numbers": [ "+12025550147", "+12025550148" ], "provider": "" } }, "notFound": { "summary": "No mobile phone found", "value": { "status": "not_found", "linkedin_profile_url": "https://www.linkedin.com/in/example-person-000000", "phone_numbers": null, "all_phone_numbers": [], "provider": null } } } } } }, "400": { "description": "The JSON body is invalid or required identification fields are missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The workspace cannot complete this request because access or available credits are insufficient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the 256 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The workspace rate limit has been exceeded. Try again after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request could not be completed because of an unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The request could not be completed because a required service returned an unsuccessful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The request is temporarily unavailable. Try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/personal-email": { "post": { "operationId": "findPersonalEmail", "tags": [ "Contact data" ], "summary": "Find a personal email", "description": "Finds a personal email for a recognized person profile, with optional verification behavior.", "x-airscale-rate-limit": "2,000 requests per minute per workspace.", "x-airscale-credit-cost": "3–12 credits for a successful result; not_found is not charged.", "requestBody": { "required": true, "description": "Provide the recognized person profile. Verification is enabled only for boolean true or the case-insensitive string \"yes\"; all other values leave verification disabled.", "content": { "application/json": { "schema": { "type": "object", "required": [ "linkedin_profile_url" ], "additionalProperties": false, "properties": { "linkedin_profile_url": { "description": "A LinkedIn person-profile input accepted and canonicalized after trimming whitespace. Valid URL user info, numeric ports, queries, and fragments are accepted but omitted from the canonical profile URL.", "allOf": [ { "$ref": "#/components/schemas/LinkedInPersonUrl" }, { "pattern": "^\\s*(?:[Hh][Tt][Tt][Pp][Ss]?:\\/\\/)?(?:[^\\s\\/@:]+(?::[^\\s\\/@]*)?@)?(?:[Ww]{3}\\.)?[Ll][Ii][Nn][Kk][Ee][Dd][Ii][Nn]\\.[Cc][Oo][Mm](?::(?:0*[0-9]{1,4}|0*(?:[1-5][0-9]{4}|6[0-4][0-9]{3}|65[0-4][0-9]{2}|655[0-2][0-9]|6553[0-5])))?\\/in\\/(?:[A-Za-z0-9_-]|%[0-9A-Fa-f]{2})+\\/?(?:\\?[^\\s#]*)?(?:#[^\\s]*)?\\s*$" } ] }, "verification": { "description": "Verification is enabled only for boolean true or the case-insensitive string \"yes\"; all other values leave verification disabled.", "oneOf": [ { "type": "boolean" }, { "type": "string" } ] } } }, "examples": { "profile": { "summary": "Person profile with verification enabled", "value": { "linkedin_profile_url": "https://www.linkedin.com/in/example-person-000000", "verification": true } } } } } }, "responses": { "200": { "description": "A personal email result or a not-found result.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "status", "email" ], "additionalProperties": true, "properties": { "status": { "type": "string", "const": "success" }, "email": { "type": "string", "format": "email" } } }, { "$ref": "#/components/schemas/NotFoundEmail" } ] }, "examples": { "success": { "summary": "Personal email found", "value": { "status": "success", "email": "personal.example@example.org" } }, "notFound": { "summary": "No personal email found", "value": { "status": "not_found", "email": null } } } } } }, "400": { "description": "The JSON body is invalid or required identification fields are missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The workspace cannot complete this request because access or available credits are insufficient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the 256 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The workspace rate limit has been exceeded. Try again after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request could not be completed because of an unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The request could not be completed because a required service returned an unsuccessful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The request is temporarily unavailable. Try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/url-search-people": { "post": { "operationId": "findPeopleProfileUrl", "tags": [ "Contact data" ], "summary": "Find a person's profile URL", "description": "Finds a person's public profile URL from their name and company name.", "x-airscale-rate-limit": "6 requests per second per workspace.", "x-airscale-credit-cost": "0.5 credits only when the response has status success; not_found is not charged.", "requestBody": { "required": true, "description": "Provide the person's first name, last name, and company name.", "content": { "application/json": { "schema": { "type": "object", "required": [ "first_name", "last_name", "company_name" ], "additionalProperties": false, "properties": { "first_name": { "type": "string", "minLength": 1 }, "last_name": { "type": "string", "minLength": 1 }, "company_name": { "type": "string", "minLength": 1 } } }, "examples": { "person": { "summary": "Synthetic person and company", "value": { "first_name": "Example", "last_name": "Person", "company_name": "Example Company" } } } } } }, "responses": { "200": { "description": "A profile URL result or a not-found result.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "required": [ "status", "url" ], "additionalProperties": true, "properties": { "status": { "type": "string", "const": "success" }, "url": { "type": "string" } } }, { "type": "object", "required": [ "status" ], "additionalProperties": true, "properties": { "status": { "type": "string", "const": "not_found" } } } ] }, "examples": { "success": { "summary": "Profile URL found", "value": { "status": "success", "url": "https://www.linkedin.com/in/example-person-000000" } }, "notFound": { "summary": "No profile URL found", "value": { "status": "not_found" } } } } } }, "400": { "description": "The JSON body is invalid or required identification fields are missing.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The workspace cannot complete this request because access or available credits are insufficient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the 256 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The workspace rate limit has been exceeded. Try again after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request could not be completed because of an unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The request could not be completed because a required service returned an unsuccessful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The request is temporarily unavailable. Try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/profile": { "post": { "operationId": "extractPersonProfile", "tags": [ "Profiles and reverse lookup" ], "summary": "Extract a person profile", "description": "Extracts public profile data. The submitted URL determines whether the successful response is a person or company object.", "x-airscale-rate-limit": "3,000 requests per minute per workspace.", "x-airscale-credit-cost": "URL-selected: /in/ successes cost 1 credit by default (workspace-specific pricing may differ); /company/ or /school/ successes cost 0.5 credits; unsuccessful requests are not charged.", "requestBody": { "required": true, "description": "The LinkedIn URL is trimmed and a missing scheme is normalized. The hostname must be linkedin.com or a subdomain, and the first path segment must be /in/, /company/, or /school/. Query and extra path segments are canonicalized away. The submitted URL type chooses the person or company response and successful credit cost, regardless of which of these two routes receives it. Response fields and their types can vary; check for missing or null values before using them.", "content": { "application/json": { "schema": { "type": "object", "required": [ "linkedin_profile_url" ], "additionalProperties": false, "properties": { "linkedin_profile_url": { "type": "string", "minLength": 1 } } }, "examples": { "profile": { "summary": "Extract a LinkedIn profile", "value": { "linkedin_profile_url": "linkedin.com/in/example-person-000000?source=synthetic" } } } } } }, "responses": { "200": { "description": "The submitted URL selects a person or company profile response.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/VariablePersonProfile" }, { "$ref": "#/components/schemas/VariableCompanyProfile" } ] }, "examples": { "success": { "summary": "Example profile", "value": { "url": "https://www.linkedin.com/in/example-person-000000", "identifier": "example-person-000000", "entityUrn": "EXAMPLE000000", "objectUrn": 100000001, "firstname": "Example", "lastname": "Person", "middleName": null, "birthDate": null, "headline": "Founder at Example Company", "picture": "https://www.example.org/images/example-person.png", "background": "https://www.example.org/images/example-background.png", "summary": null, "openToWork": false, "influencer": false, "premium": true, "creator": false, "hiring": false, "verified": null, "industry": "Software Development", "location": { "country": "United States", "city": "Example City", "state": "Example State", "defaultValue": "Example City, Example State, United States", "shortValue": "Example City, United States" }, "organizations": { "totalElements": 0, "page": 0, "size": 0, "contents": [] }, "educations": { "totalElements": 1, "page": 0, "size": 1, "contents": [ { "school": { "id": 100001, "name": "Example University", "logo": "https://www.example.org/images/example-university.png", "url": "https://www.linkedin.com/school/example-university/", "profileType": "SCHOOL" }, "degreeName": "Master of Science", "fieldOfStudy": "Computer Science", "grade": null, "date": { "start": "2014-01-01T00:00:00.000Z", "end": "2016-01-01T00:00:00.000Z" } } ] }, "patents": { "totalElements": 0, "page": 0, "size": 0, "contents": [] }, "awards": { "totalElements": 0, "page": 0, "size": 0, "contents": [] }, "certifications": { "totalElements": 1, "page": 0, "size": 1, "contents": [ { "name": "Example Certification", "authority": "Example Institute", "url": "https://www.example.org/certificates/example", "licenseNumber": "EX-000001", "displaySource": "example.org", "company": { "id": 100003, "name": "Example Institute", "logo": "https://www.example.org/images/example-institute.png", "url": "https://www.linkedin.com/company/example-institute/", "profileType": "COMPANY" }, "date": { "start": "2022-01-01T00:00:00.000Z", "end": null } } ] }, "projects": { "totalElements": 0, "page": 0, "size": 0, "contents": [] }, "publications": { "totalElements": 0, "page": 0, "size": 0, "contents": [] }, "courses": { "totalElements": 0, "page": 0, "size": 0, "contents": [] }, "testScores": { "totalElements": 0, "page": 0, "size": 0, "contents": [] }, "positionGroups": { "totalElements": 1, "page": 0, "size": 1, "contents": [ { "company": { "id": 100002, "name": "Example Company", "logo": "https://www.example.org/images/example-company.png", "url": "https://www.linkedin.com/company/example-company-000000", "domain": "example.org", "profileType": "COMPANY" }, "date": { "start": "2021-03-01T00:00:00.000Z", "end": null }, "profilePositions": [ { "company": "Example Company", "description": null, "title": "Founder", "employmentType": "Permanent", "location": "Example City, United States", "date": { "start": "2021-03-01T00:00:00.000Z", "end": null } } ] } ] }, "volunteerExperiences": { "totalElements": 0, "page": 0, "size": 0, "contents": [] }, "languages": { "totalElements": 1, "page": 0, "size": 1, "contents": [ { "name": "English", "proficiency": "NATIVE_OR_BILINGUAL" } ] }, "skills": { "totalElements": 2, "page": 0, "size": 2, "contents": [ "Sales prospecting", "Data enrichment" ] } } } } } } }, "400": { "description": "The JSON body is invalid or a required input is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The workspace cannot complete this request because access or available credits are insufficient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No profile could be extracted for the submitted LinkedIn URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the 256 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The workspace rate limit has been exceeded. Try again after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request could not be completed because of an unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The request could not be completed because a required service returned an unsuccessful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The request is temporarily unavailable. Try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/company": { "post": { "operationId": "extractCompanyProfile", "tags": [ "Profiles and reverse lookup" ], "summary": "Extract a company profile", "description": "Extracts public profile data. The submitted URL determines whether the successful response is a person or company object.", "x-airscale-rate-limit": "3,000 requests per minute per workspace.", "x-airscale-credit-cost": "URL-selected: /in/ successes cost 1 credit by default (workspace-specific pricing may differ); /company/ or /school/ successes cost 0.5 credits; unsuccessful requests are not charged.", "requestBody": { "required": true, "description": "The LinkedIn URL is trimmed and a missing scheme is normalized. The hostname must be linkedin.com or a subdomain, and the first path segment must be /in/, /company/, or /school/. Query and extra path segments are canonicalized away. The submitted URL type chooses the person or company response and successful credit cost, regardless of which of these two routes receives it. Response fields and their types can vary; check for missing or null values before using them.", "content": { "application/json": { "schema": { "type": "object", "required": [ "linkedin_profile_url" ], "additionalProperties": false, "properties": { "linkedin_profile_url": { "type": "string", "minLength": 1 } } }, "examples": { "profile": { "summary": "Extract a LinkedIn profile", "value": { "linkedin_profile_url": "https://www.linkedin.com/company/example-company-000000/about/" } } } } } }, "responses": { "200": { "description": "The submitted URL selects a person or company profile response.", "content": { "application/json": { "schema": { "anyOf": [ { "$ref": "#/components/schemas/VariablePersonProfile" }, { "$ref": "#/components/schemas/VariableCompanyProfile" } ] }, "examples": { "success": { "summary": "Example profile", "value": { "url": "https://www.linkedin.com/company/example-company-000000", "name": "Example Company", "universalName": "example-company-000000", "type": "Privately Held", "objectUrn": 100000002, "description": "Synthetic company profile for API documentation.", "phone": null, "followers": 1200, "website": "https://www.example.org", "logo": "https://www.example.org/images/example-company.png", "cover": "https://www.example.org/images/example-cover.png", "tagline": "Example tagline", "foundedYear": 2021, "staff": { "total": 120, "range": { "start": 51, "end": 200 } }, "locations": { "headquarter": { "country": "US", "geographicArea": "Example State", "city": "Example City", "postalCode": "00000", "line1": null, "line2": null, "isPrimary": null }, "other": [ { "country": "US", "geographicArea": "Example State", "city": "Second Example City", "postalCode": "00001", "line1": null, "line2": null, "isPrimary": null } ] }, "fundingData": null, "specialities": [ "Synthetic data" ], "industries": [ "Software Development" ], "hashtags": null } } } } } }, "400": { "description": "The JSON body is invalid or a required input is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The workspace cannot complete this request because access or available credits are insufficient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "No profile could be extracted for the submitted LinkedIn URL.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the 256 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The workspace rate limit has been exceeded. Try again after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request could not be completed because of an unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The request could not be completed because a required service returned an unsuccessful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The request is temporarily unavailable. Try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/domain-to-linkedin": { "post": { "operationId": "findCompanyLinkedinUrl", "tags": [ "Profiles and reverse lookup" ], "summary": "Find a LinkedIn company URL from a domain", "description": "Accepts only a company domain and returns only its LinkedIn company URL. Use a current workspace API key from Airscale Settings; keys from the previous dashboard are not supported. The lookup deadline is 120 seconds; allow 130 seconds in the client. The charge may appear after the result, including after a top-up if your balance is insufficient.", "x-airscale-rate-limit": "180 requests per minute per workspace.", "x-airscale-credit-cost": "0.5 credits on success; the charge may appear later, including after a top-up. No-result and failed lookups cost zero.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Use the same key for transport retries of the same domain. Stored responses replay for seven days without another lookup or charge. In-flight duplicates return 409 with Retry-After: 2. Reusing a key with a different domain or after expiry returns 409. A new key starts a new operation. Without a key every request is a new operation.", "schema": { "type": "string", "minLength": 1, "maxLength": 200, "pattern": "^[!-~]+$" }, "example": "company-lookup-001" } ], "requestBody": { "required": true, "description": "Exactly one domain field. Maximum JSON body size: 4 KiB.", "content": { "application/json": { "schema": { "type": "object", "required": [ "domain" ], "additionalProperties": false, "properties": { "domain": { "type": "string", "minLength": 1, "description": "A company hostname without scheme, path, port, or credentials. Case and a leading www. are normalized." } } }, "examples": { "domain": { "summary": "Company domain", "value": { "domain": "example.org" } } } } } }, "responses": { "200": { "description": "A canonical LinkedIn company URL. Costs 0.5 credits; the charge may appear later.", "content": { "application/json": { "schema": { "type": "object", "required": [ "linkedin_company_url" ], "additionalProperties": false, "properties": { "linkedin_company_url": { "type": "string", "format": "uri", "pattern": "^https://www\\.linkedin\\.com/company/[^/?#]+$" } } }, "examples": { "success": { "summary": "Illustrative company match", "value": { "linkedin_company_url": "https://www.linkedin.com/company/example-company-000000" } } } } } }, "400": { "description": "Invalid JSON, domain, extra body fields, or Idempotency-Key.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "No matching LinkedIn company URL found. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "409": { "description": "Operation in progress, key reused for a different domain, or expired key. Retry in-flight operations with the same key; use a new key for conflicts or expiry.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Present for an in-flight duplicate: retry after 2 seconds.", "schema": { "type": "string" }, "example": "2" } } }, "413": { "description": "JSON request body exceeds 4 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "180 requests per minute per workspace exceeded. Retry with bounded backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lookup is temporarily unavailable. Retry according to the idempotency guidance.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "Lookup deadline exhausted. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reverse-email": { "post": { "operationId": "reverseEmailLookup", "tags": [ "Profiles and reverse lookup" ], "summary": "Find a profile from an email", "description": "Resolves a public person profile from an email address, or returns the JSON string \"not found\" when no profile is available. A match usually returns a nested person record with camelCase keys: names are under profile (profile.firstName, profile.lastName), not at the top level. A match from a fallback lookup uses the flat fields of POST /v1/profile instead, or contains only url and identifier.", "x-airscale-rate-limit": "25 requests per second per workspace.", "x-airscale-credit-cost": "2 credits only when a profile is returned; \"not found\" and errors are not charged.", "requestBody": { "required": true, "description": "The email is trimmed and lowercased before lookup. It must have a non-empty local part, an @ sign, and a domain containing a dot.", "content": { "application/json": { "schema": { "type": "object", "required": [ "email" ], "additionalProperties": false, "properties": { "email": { "type": "string", "pattern": "^\\s*[^\\s@]+@[^\\s@]+\\.[^\\s@]+\\s*$" } } }, "examples": { "email": { "summary": "Synthetic email", "value": { "email": " Example.Person@Example.Org " } } } } } }, "responses": { "200": { "description": "A public person profile or the exact JSON string \"not found\".", "content": { "application/json": { "schema": { "oneOf": [ { "anyOf": [ { "$ref": "#/components/schemas/ReverseLookupPerson" }, { "$ref": "#/components/schemas/VariablePersonProfile" } ] }, { "type": "string", "enum": [ "not found" ] } ] }, "examples": { "success": { "summary": "Profile found", "value": { "id": "00000000-0000-0000-0000-000000000000", "identifier": "example-person-000000", "profile": { "firstName": "Example", "middleName": null, "lastName": "Person", "fullName": "Example Person", "headline": "Founder at Example Company", "title": "Founder", "summary": "Synthetic profile summary for API documentation.", "birthDate": null, "background": { "source": "https://www.example.org/images/example-background.png" }, "picture": { "source": "https://www.example.org/images/example-person.png" } }, "link": { "linkedin": "https://www.linkedin.com/in/example-person-000000", "twitter": null, "github": null, "facebook": null }, "location": { "default": "Example City, Example State, United States", "short": "Example City, United States", "country": "United States", "state": "Example State", "city": "Example City", "position": null }, "languages": { "primaryLocale": { "country": "US", "language": "en" }, "supportedLocales": [ { "country": "US", "language": "en" } ], "profileLanguages": [ { "name": "English", "proficiency": "NATIVE_OR_BILINGUAL" } ] }, "industry": "Software Development", "educations": [ { "school": { "id": "100001", "name": "Example University", "url": "https://www.linkedin.com/school/example-university/", "logo": "https://www.example.org/images/example-logo.png" }, "degreeName": "Master of Science", "fieldOfStudy": "Computer Science", "grade": null, "date": { "start": "2014", "end": "2016" } } ], "certifications": [ { "name": "Example Certification", "authority": "Example Institute", "url": "https://www.example.org/certificates/example", "licenseNumber": "EX-000001", "displaySource": "example.org", "company": { "id": "100003", "name": "Example Institute", "url": "https://www.linkedin.com/company/example-institute/", "logo": "https://www.example.org/images/example-logo.png" }, "date": { "start": "2022-01", "end": null } } ], "positionGroups": [ { "company": { "id": "100002", "name": "Example Company", "url": "https://www.linkedin.com/company/example-company-000000", "employees": { "start": 11, "end": 50 }, "logo": "https://www.example.org/images/example-logo.png" }, "date": { "start": "2021-03", "end": null }, "profilePositions": [ { "company": "Example Company", "description": null, "title": "Founder", "employmentType": "Full-time", "location": "Example City, United States", "date": { "start": "2021-03", "end": null } } ] } ], "skills": [ "Sales prospecting", "Data enrichment" ], "memberBadges": { "premium": true, "creator": false, "openToWork": false, "hiring": false, "verified": true, "influencer": false }, "company": { "id": "100002", "summary": { "name": "Example Company", "legalName": "Example Company Inc.", "description": "Synthetic company description for API documentation.", "foundedYear": 2021, "type": "PRIVATELY_HELD", "industry": "Software Development", "staff": { "total": 24, "range": { "start": 11, "end": 50 } }, "logo": { "source": "https://www.example.org/images/example-company.png" } }, "link": { "website": "https://www.example.org", "domain": "example.org", "linkedin": "https://www.linkedin.com/company/example-company-000000", "crunchbase": null }, "financial": { "revenue": { "annual": { "start": 1000000, "end": 5000000 } } }, "location": { "headquarter": { "continent": "North America", "country": "United States", "state": "Example State", "city": "Example City", "postalCode": "00000", "rawAddress": "1 Example Street, Example City, Example State 00000", "position": { "lng": -74, "lat": 40 } }, "locations": [ { "continent": "North America", "country": "United States", "state": "Example State", "city": "Example City", "postalCode": "00000", "rawAddress": "1 Example Street, Example City, Example State 00000", "position": { "lng": -74, "lat": 40 } } ] }, "technologies": [ { "name": "Example CRM", "category": "CRM" } ], "industries": [ "Software Development" ], "languages": [ "English" ] }, "department": { "departments": [ "founder" ], "subDepartments": [ "founder" ], "functions": [ "executive" ], "seniority": "founder" }, "url": "https://www.linkedin.com/in/example-person-000000" } }, "notFound": { "summary": "No profile found", "value": "not found" } } } } }, "400": { "description": "The JSON body is invalid or a required input is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The workspace cannot complete this request because access or available credits are insufficient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the 256 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The workspace rate limit has been exceeded. Try again after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request could not be completed because of an unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The request could not be completed because a required service returned an unsuccessful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The request is temporarily unavailable. Try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/reverse-phone": { "post": { "operationId": "reversePhoneLookup", "tags": [ "Profiles and reverse lookup" ], "summary": "Find a profile from a phone number", "description": "Resolves a public person profile from a phone-number string, or returns a not_found status when no profile is available. A match returns the same nested person record as reverse email, plus a body field holding a copy of it.", "x-airscale-rate-limit": "2,000 requests per minute per workspace.", "x-airscale-credit-cost": "10 credits only when a profile is returned; not_found and errors are not charged.", "requestBody": { "required": true, "description": "The mobile_phone value is trimmed before lookup and must contain at least one non-whitespace character. The exact trimmed lowercase strings \"null\" and \"undefined\" are treated as missing input.", "content": { "application/json": { "schema": { "type": "object", "required": [ "mobile_phone" ], "additionalProperties": false, "properties": { "mobile_phone": { "type": "string", "minLength": 1, "pattern": "^(?!\\s*(?:null|undefined)\\s*$)(?=.*\\S)[\\s\\S]+$" } } }, "examples": { "phone": { "summary": "Synthetic phone number", "value": { "mobile_phone": "+12025550147" } } } } } }, "responses": { "200": { "description": "A public person profile in a body envelope, or an exact not_found status.", "content": { "application/json": { "schema": { "oneOf": [ { "allOf": [ { "anyOf": [ { "$ref": "#/components/schemas/ReverseLookupPerson" }, { "$ref": "#/components/schemas/VariablePersonProfile" } ] }, { "type": "object", "required": [ "body" ], "properties": { "body": { "anyOf": [ { "$ref": "#/components/schemas/ReverseLookupPerson" }, { "$ref": "#/components/schemas/VariablePersonProfile" } ], "description": "A copy of the same profile object. It is kept at the top level too for existing integrations." } } } ] }, { "$ref": "#/components/schemas/NotFoundStatus" } ] }, "examples": { "success": { "summary": "Profile found", "value": { "id": "00000000-0000-0000-0000-000000000000", "identifier": "example-person-000000", "profile": { "firstName": "Example", "middleName": null, "lastName": "Person", "fullName": "Example Person", "headline": "Founder at Example Company", "title": "Founder", "summary": "Synthetic profile summary for API documentation.", "birthDate": null, "background": { "source": "https://www.example.org/images/example-background.png" }, "picture": { "source": "https://www.example.org/images/example-person.png" } }, "link": { "linkedin": "https://www.linkedin.com/in/example-person-000000", "twitter": null, "github": null, "facebook": null }, "location": { "default": "Example City, Example State, United States", "short": "Example City, United States", "country": "United States", "state": "Example State", "city": "Example City", "position": null }, "languages": { "primaryLocale": { "country": "US", "language": "en" }, "supportedLocales": [ { "country": "US", "language": "en" } ], "profileLanguages": [ { "name": "English", "proficiency": "NATIVE_OR_BILINGUAL" } ] }, "industry": "Software Development", "educations": [ { "school": { "id": "100001", "name": "Example University", "url": "https://www.linkedin.com/school/example-university/", "logo": "https://www.example.org/images/example-logo.png" }, "degreeName": "Master of Science", "fieldOfStudy": "Computer Science", "grade": null, "date": { "start": "2014", "end": "2016" } } ], "certifications": [ { "name": "Example Certification", "authority": "Example Institute", "url": "https://www.example.org/certificates/example", "licenseNumber": "EX-000001", "displaySource": "example.org", "company": { "id": "100003", "name": "Example Institute", "url": "https://www.linkedin.com/company/example-institute/", "logo": "https://www.example.org/images/example-logo.png" }, "date": { "start": "2022-01", "end": null } } ], "positionGroups": [ { "company": { "id": "100002", "name": "Example Company", "url": "https://www.linkedin.com/company/example-company-000000", "employees": { "start": 11, "end": 50 }, "logo": "https://www.example.org/images/example-logo.png" }, "date": { "start": "2021-03", "end": null }, "profilePositions": [ { "company": "Example Company", "description": null, "title": "Founder", "employmentType": "Full-time", "location": "Example City, United States", "date": { "start": "2021-03", "end": null } } ] } ], "skills": [ "Sales prospecting", "Data enrichment" ], "memberBadges": { "premium": true, "creator": false, "openToWork": false, "hiring": false, "verified": true, "influencer": false }, "company": { "id": "100002", "summary": { "name": "Example Company", "legalName": "Example Company Inc.", "description": "Synthetic company description for API documentation.", "foundedYear": 2021, "type": "PRIVATELY_HELD", "industry": "Software Development", "staff": { "total": 24, "range": { "start": 11, "end": 50 } }, "logo": { "source": "https://www.example.org/images/example-company.png" } }, "link": { "website": "https://www.example.org", "domain": "example.org", "linkedin": "https://www.linkedin.com/company/example-company-000000", "crunchbase": null }, "financial": { "revenue": { "annual": { "start": 1000000, "end": 5000000 } } }, "location": { "headquarter": { "continent": "North America", "country": "United States", "state": "Example State", "city": "Example City", "postalCode": "00000", "rawAddress": "1 Example Street, Example City, Example State 00000", "position": { "lng": -74, "lat": 40 } }, "locations": [ { "continent": "North America", "country": "United States", "state": "Example State", "city": "Example City", "postalCode": "00000", "rawAddress": "1 Example Street, Example City, Example State 00000", "position": { "lng": -74, "lat": 40 } } ] }, "technologies": [ { "name": "Example CRM", "category": "CRM" } ], "industries": [ "Software Development" ], "languages": [ "English" ] }, "department": { "departments": [ "founder" ], "subDepartments": [ "founder" ], "functions": [ "executive" ], "seniority": "founder" }, "url": "https://www.linkedin.com/in/example-person-000000", "body": { "id": "00000000-0000-0000-0000-000000000000", "identifier": "example-person-000000", "profile": { "firstName": "Example", "middleName": null, "lastName": "Person", "fullName": "Example Person", "headline": "Founder at Example Company", "title": "Founder", "summary": "Synthetic profile summary for API documentation.", "birthDate": null, "background": { "source": "https://www.example.org/images/example-background.png" }, "picture": { "source": "https://www.example.org/images/example-person.png" } }, "link": { "linkedin": "https://www.linkedin.com/in/example-person-000000", "twitter": null, "github": null, "facebook": null }, "location": { "default": "Example City, Example State, United States", "short": "Example City, United States", "country": "United States", "state": "Example State", "city": "Example City", "position": null }, "languages": { "primaryLocale": { "country": "US", "language": "en" }, "supportedLocales": [ { "country": "US", "language": "en" } ], "profileLanguages": [ { "name": "English", "proficiency": "NATIVE_OR_BILINGUAL" } ] }, "industry": "Software Development", "educations": [ { "school": { "id": "100001", "name": "Example University", "url": "https://www.linkedin.com/school/example-university/", "logo": "https://www.example.org/images/example-logo.png" }, "degreeName": "Master of Science", "fieldOfStudy": "Computer Science", "grade": null, "date": { "start": "2014", "end": "2016" } } ], "certifications": [ { "name": "Example Certification", "authority": "Example Institute", "url": "https://www.example.org/certificates/example", "licenseNumber": "EX-000001", "displaySource": "example.org", "company": { "id": "100003", "name": "Example Institute", "url": "https://www.linkedin.com/company/example-institute/", "logo": "https://www.example.org/images/example-logo.png" }, "date": { "start": "2022-01", "end": null } } ], "positionGroups": [ { "company": { "id": "100002", "name": "Example Company", "url": "https://www.linkedin.com/company/example-company-000000", "employees": { "start": 11, "end": 50 }, "logo": "https://www.example.org/images/example-logo.png" }, "date": { "start": "2021-03", "end": null }, "profilePositions": [ { "company": "Example Company", "description": null, "title": "Founder", "employmentType": "Full-time", "location": "Example City, United States", "date": { "start": "2021-03", "end": null } } ] } ], "skills": [ "Sales prospecting", "Data enrichment" ], "memberBadges": { "premium": true, "creator": false, "openToWork": false, "hiring": false, "verified": true, "influencer": false }, "company": { "id": "100002", "summary": { "name": "Example Company", "legalName": "Example Company Inc.", "description": "Synthetic company description for API documentation.", "foundedYear": 2021, "type": "PRIVATELY_HELD", "industry": "Software Development", "staff": { "total": 24, "range": { "start": 11, "end": 50 } }, "logo": { "source": "https://www.example.org/images/example-company.png" } }, "link": { "website": "https://www.example.org", "domain": "example.org", "linkedin": "https://www.linkedin.com/company/example-company-000000", "crunchbase": null }, "financial": { "revenue": { "annual": { "start": 1000000, "end": 5000000 } } }, "location": { "headquarter": { "continent": "North America", "country": "United States", "state": "Example State", "city": "Example City", "postalCode": "00000", "rawAddress": "1 Example Street, Example City, Example State 00000", "position": { "lng": -74, "lat": 40 } }, "locations": [ { "continent": "North America", "country": "United States", "state": "Example State", "city": "Example City", "postalCode": "00000", "rawAddress": "1 Example Street, Example City, Example State 00000", "position": { "lng": -74, "lat": 40 } } ] }, "technologies": [ { "name": "Example CRM", "category": "CRM" } ], "industries": [ "Software Development" ], "languages": [ "English" ] }, "department": { "departments": [ "founder" ], "subDepartments": [ "founder" ], "functions": [ "executive" ], "seniority": "founder" }, "url": "https://www.linkedin.com/in/example-person-000000" } } }, "notFound": { "summary": "No profile found", "value": { "status": "not_found" } } } } } }, "400": { "description": "The JSON body is invalid or a required input is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The workspace cannot complete this request because access or available credits are insufficient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the 256 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The workspace rate limit has been exceeded. Try again after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request could not be completed because of an unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The request could not be completed because a required service returned an unsuccessful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The request is temporarily unavailable. Try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/find-people": { "post": { "operationId": "findPeople", "tags": [ "Search and discovery" ], "summary": "Find people", "description": "Searches for people who match structured person, role, and company filters. The JSON request body is limited to 256 KiB.", "x-airscale-rate-limit": "6 requests per second per workspace.", "x-airscale-credit-cost": "0.1 credits per returned lead; no charge when no leads are returned.", "requestBody": { "required": true, "description": "Provide at least one supported query filter. Search pagination accepts a page size from 1 to 100 and an optional opaque cursor.", "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "additionalProperties": false, "properties": { "query": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "firstname": { "description": "Matches a person's first name.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "lastname": { "description": "Matches a person's last name.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "jobTitle": { "description": "Matches the person's current role or job title.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "school": { "description": "Matches a school name on the person's profile.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "languages": { "description": "Matches a language name or code on the person's profile.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "skills": { "description": "Matches a skill name on the person's profile.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "location": { "description": "Matches the person or current-role location. Country names and ISO alpha-2 codes are accepted.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "keyword": { "description": "Matches text on the person's profile.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "currentCompanyName": { "description": "Matches the person's current company name.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "companyDomain": { "description": "Matches a current company domain; URL input is normalized to its hostname. Values from companyDomain and companyLinkedinUrl are combined as OR alternatives into one current-company identifier filter.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "companyLinkedinUrl": { "description": "Matches a current company profile URL or identifier. Values from companyDomain and companyLinkedinUrl are combined as OR alternatives into one current-company identifier filter.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "currentCompany.type": { "description": "Matches the current company type.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "currentCompany.industry": { "description": "Matches the current company industry.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "currentCompany.location": { "description": "Matches the current company headquarters location.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "currentCompany.keyword": { "description": "Matches text on the current company profile.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "pastJobTitle": { "description": "Matches a title in a previous position. All past-experience filters must match the same prior role.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "pastCompanyName": { "description": "Matches a previous company name. All past-experience filters must match the same prior role.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "pastCompanyId": { "description": "Matches a previous company identifier.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "pastCompanyWebsite": { "description": "Matches a previous company website or domain.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "pastCompanyUrn": { "description": "Matches a previous company URN.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "pastCompany.type": { "description": "Matches a previous company type.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "pastCompany.industry": { "description": "Matches a previous company industry.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "pastCompany.location": { "description": "Matches a previous company headquarters location.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "pastCompany.keyword": { "description": "Matches text on a previous company profile.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "totalYearsOfExperience": { "description": "Matches the person's total years of experience.", "allOf": [ { "$ref": "#/components/schemas/IntegerRangeFilter" } ] }, "timeInCurrentCompany": { "description": "Matches years spent at the current company.", "allOf": [ { "$ref": "#/components/schemas/IntegerRangeFilter" } ] }, "currentCompany.headcount": { "description": "Matches current company employee count.", "allOf": [ { "$ref": "#/components/schemas/IntegerRangeFilter" } ] }, "currentCompany.revenue": { "description": "Matches current company revenue.", "allOf": [ { "$ref": "#/components/schemas/IntegerRangeFilter" } ] }, "pastCompany.headcount": { "description": "Matches previous company employee count.", "allOf": [ { "$ref": "#/components/schemas/IntegerRangeFilter" } ] }, "pastCompany.revenue": { "description": "Matches previous company revenue.", "allOf": [ { "$ref": "#/components/schemas/IntegerRangeFilter" } ] }, "currentCompany.headcountGrowth": { "description": "Matches current company headcount growth for a supported timespan.", "allOf": [ { "$ref": "#/components/schemas/GrowthFilter" } ] }, "pastCompany.headcountGrowth": { "description": "Matches previous company headcount growth for a supported timespan.", "allOf": [ { "$ref": "#/components/schemas/GrowthFilter" } ] } } }, "size": { "description": "A page size from 1 through 100 supplied as an integer JSON number or one of the equivalent canonical decimal strings. OpenAPI intentionally uses canonical decimal strings even though runtime Number() accepts additional JS-coercible spellings.", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "string", "pattern": "^(?:[1-9]|[1-9][0-9]|100)$" } ], "default": 100 }, "cursor": { "type": "string", "minLength": 1, "description": "An opaque value returned as next_cursor by the preceding page. Send it unchanged." } } }, "examples": { "audience": { "summary": "Synthetic audience", "value": { "query": { "jobTitle": { "include": [ "Revenue Operations Manager" ] }, "location": { "include": [ "Example Country" ] } }, "size": 50 } } } } } }, "responses": { "200": { "description": "A page of matching public lead records.", "content": { "application/json": { "schema": { "type": "object", "required": [ "total", "leads", "next_cursor" ], "additionalProperties": false, "properties": { "total": { "type": "number" }, "leads": { "type": "array", "items": { "$ref": "#/components/schemas/PeopleLead" } }, "next_cursor": { "type": [ "string", "null" ] } } }, "examples": { "page": { "summary": "Synthetic lead page", "value": { "total": 124, "leads": [ { "firstname": "Example", "lastname": "Person", "headline": "Revenue Operations Manager at Example Company", "description": "Synthetic profile summary for API documentation.", "profileUrl": "https://www.linkedin.com/in/example-person-000000", "jobTitle": "Revenue Operations Manager", "jobDescription": "Synthetic role description.", "jobStartDate": "03-2021", "address": "Example City, Example State, United States", "companyName": "Example Company", "companyUrn": "urn:li:fsd_company:100000002", "companyUrl": "https://www.linkedin.com/company/example-company-000000", "companyWebsite": "https://www.example.com", "companyDescription": "Synthetic company description for API documentation.", "companySize": 4, "companyIndustry": "Software Development", "companyAddress": "1 Example Street, Example City, Example State, United States" } ], "next_cursor": "fp_synthetic_cursor" } } } } } }, "400": { "description": "The request is invalid or contains an unsupported field or value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The workspace cannot complete this request because access or available credits are insufficient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The HTTP method or path does not match this public endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the 256 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The workspace rate limit has been exceeded. Try again after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The request could not be completed because a required service returned an unsuccessful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The request is temporarily unavailable. Try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/find-people/count": { "post": { "operationId": "countPeople", "tags": [ "Search and discovery" ], "summary": "Count people", "description": "Counts people using the exact same structured query contract as Find People, without retrieving or paginating lead records.", "x-airscale-rate-limit": "6 requests per second per workspace.", "x-airscale-credit-cost": "No charge; Count does not debit Airscale credits.", "requestBody": { "required": true, "description": "Provide at least one supported query filter. Count has no size or cursor fields.", "content": { "application/json": { "schema": { "type": "object", "required": [ "query" ], "additionalProperties": false, "properties": { "query": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "firstname": { "description": "Matches a person's first name.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "lastname": { "description": "Matches a person's last name.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "jobTitle": { "description": "Matches the person's current role or job title.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "school": { "description": "Matches a school name on the person's profile.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "languages": { "description": "Matches a language name or code on the person's profile.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "skills": { "description": "Matches a skill name on the person's profile.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "location": { "description": "Matches the person or current-role location. Country names and ISO alpha-2 codes are accepted.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "keyword": { "description": "Matches text on the person's profile.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "currentCompanyName": { "description": "Matches the person's current company name.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "companyDomain": { "description": "Matches a current company domain; URL input is normalized to its hostname. Values from companyDomain and companyLinkedinUrl are combined as OR alternatives into one current-company identifier filter.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "companyLinkedinUrl": { "description": "Matches a current company profile URL or identifier. Values from companyDomain and companyLinkedinUrl are combined as OR alternatives into one current-company identifier filter.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "currentCompany.type": { "description": "Matches the current company type.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "currentCompany.industry": { "description": "Matches the current company industry.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "currentCompany.location": { "description": "Matches the current company headquarters location.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "currentCompany.keyword": { "description": "Matches text on the current company profile.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "pastJobTitle": { "description": "Matches a title in a previous position. All past-experience filters must match the same prior role.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "pastCompanyName": { "description": "Matches a previous company name. All past-experience filters must match the same prior role.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "pastCompanyId": { "description": "Matches a previous company identifier.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "pastCompanyWebsite": { "description": "Matches a previous company website or domain.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "pastCompanyUrn": { "description": "Matches a previous company URN.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "pastCompany.type": { "description": "Matches a previous company type.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "pastCompany.industry": { "description": "Matches a previous company industry.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "pastCompany.location": { "description": "Matches a previous company headquarters location.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "pastCompany.keyword": { "description": "Matches text on a previous company profile.", "allOf": [ { "$ref": "#/components/schemas/IncludeExcludeFilter" } ] }, "totalYearsOfExperience": { "description": "Matches the person's total years of experience.", "allOf": [ { "$ref": "#/components/schemas/IntegerRangeFilter" } ] }, "timeInCurrentCompany": { "description": "Matches years spent at the current company.", "allOf": [ { "$ref": "#/components/schemas/IntegerRangeFilter" } ] }, "currentCompany.headcount": { "description": "Matches current company employee count.", "allOf": [ { "$ref": "#/components/schemas/IntegerRangeFilter" } ] }, "currentCompany.revenue": { "description": "Matches current company revenue.", "allOf": [ { "$ref": "#/components/schemas/IntegerRangeFilter" } ] }, "pastCompany.headcount": { "description": "Matches previous company employee count.", "allOf": [ { "$ref": "#/components/schemas/IntegerRangeFilter" } ] }, "pastCompany.revenue": { "description": "Matches previous company revenue.", "allOf": [ { "$ref": "#/components/schemas/IntegerRangeFilter" } ] }, "currentCompany.headcountGrowth": { "description": "Matches current company headcount growth for a supported timespan.", "allOf": [ { "$ref": "#/components/schemas/GrowthFilter" } ] }, "pastCompany.headcountGrowth": { "description": "Matches previous company headcount growth for a supported timespan.", "allOf": [ { "$ref": "#/components/schemas/GrowthFilter" } ] } } } } }, "examples": { "audience": { "summary": "Synthetic audience count", "value": { "query": { "jobTitle": { "include": [ "Revenue Operations Manager" ] }, "location": { "include": [ "Example Country" ] } } } } } } } }, "responses": { "200": { "description": "The number of people matching the query.", "content": { "application/json": { "schema": { "type": "object", "required": [ "total" ], "additionalProperties": false, "properties": { "total": { "type": "number" } } }, "examples": { "count": { "summary": "Synthetic audience count", "value": { "total": 124 } } } } } }, "400": { "description": "The request is invalid or contains an unsupported field or value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The workspace cannot complete this request because access or available credits are insufficient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "The HTTP method or path does not match this public endpoint.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the 256 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The workspace rate limit has been exceeded. Try again after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The request could not be completed because a required service returned an unsuccessful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The request is temporarily unavailable. Try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/find-companies": { "post": { "operationId": "findCompanies", "tags": [ "Search and discovery" ], "summary": "Find companies", "description": "Searches for companies using firmographic, geographic, event, intent, technology, and website filters. The JSON request body is limited to 256 KiB.", "x-airscale-rate-limit": "6 requests per second per workspace.", "x-airscale-credit-cost": "0.1 credits per returned company; no charge when no companies are returned.", "requestBody": { "required": true, "description": "Provide at least one real company filter. Defaults such as eventWindow and locationMatch do not count as filters.", "content": { "application/json": { "schema": { "type": "object", "required": [ "filters" ], "additionalProperties": false, "properties": { "filters": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "country": { "description": "Matches a recognized country name or ISO alpha-2 code.", "allOf": [ { "$ref": "#/components/schemas/StringOrStringArray" } ] }, "region": { "description": "Matches a canonical region code, Region|Country value, or a region name scoped by country. Discover canonical values with GET /v1/find-companies/filter-values.", "allOf": [ { "$ref": "#/components/schemas/StringOrStringArray" } ] }, "city": { "description": "Matches a resolvable city value. Discover accepted values with GET /v1/find-companies/filter-values.", "allOf": [ { "$ref": "#/components/schemas/StringOrStringArray" } ] }, "industry": { "description": "Matches a canonical company industry. Discover accepted values with GET /v1/find-companies/filter-values.", "allOf": [ { "$ref": "#/components/schemas/StringOrStringArray" } ] }, "size": { "description": "Matches a fixed employee-count range.", "oneOf": [ { "type": "string", "enum": [ "1-10", "11-50", "51-200", "201-500", "501-1000", "1001-5000", "5001-10000", "10001+" ] }, { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "1-10", "11-50", "51-200", "201-500", "501-1000", "1001-5000", "5001-10000", "10001+" ] } } ] }, "revenue": { "description": "Matches a fixed company revenue range.", "oneOf": [ { "type": "string", "enum": [ "0-500K", "500K-1M", "1M-5M", "5M-10M", "10M-25M", "25M-75M", "75M-200M", "200M-500M", "500M-1B", "1B-10B", "10B-100B", "100B-1T", "1T-10T", "10T+" ] }, { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "0-500K", "500K-1M", "1M-5M", "5M-10M", "10M-25M", "25M-75M", "75M-200M", "200M-500M", "500M-1B", "1B-10B", "10B-100B", "100B-1T", "1T-10T", "10T+" ] } } ] }, "age": { "description": "Matches a fixed company age range.", "oneOf": [ { "type": "string", "enum": [ "0-3", "3-6", "6-10", "10-20", "20+" ] }, { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "0-3", "3-6", "6-10", "10-20", "20+" ] } } ] }, "techStack": { "description": "Matches a technology used by the company. Discover accepted values with GET /v1/find-companies/filter-values.", "allOf": [ { "$ref": "#/components/schemas/StringOrStringArray" } ] }, "keywords": { "description": "Matches text found on the company website.", "allOf": [ { "$ref": "#/components/schemas/StringOrStringArray" } ] }, "topics": { "description": "Matches a canonical business-intent topic. Discover accepted values with GET /v1/find-companies/filter-values.", "allOf": [ { "$ref": "#/components/schemas/StringOrStringArray" } ] }, "events": { "description": "Matches a fixed recent company event.", "oneOf": [ { "type": "string", "enum": [ "increase_in_customer_service_department", "hiring_in_finance_department", "hiring_in_support_department", "increase_in_engineering_department", "decrease_in_customer_service_department", "hiring_in_operations_department", "hiring_in_creative_department", "decrease_in_engineering_department", "hiring_in_sales_department", "increase_in_operations_department", "hiring_in_trade_department", "decrease_in_marketing_department", "increase_in_marketing_department", "hiring_in_marketing_department", "hiring_in_health_department", "hiring_in_education_department", "increase_in_all_departments", "decrease_in_all_departments", "decrease_in_sales_department", "decrease_in_operations_department", "hiring_in_professional_service_department", "hiring_in_human_resources_department", "increase_in_sales_department", "hiring_in_legal_department", "hiring_in_unknown_department", "hiring_in_engineering_department", "company_award", "new_product", "employee_joined_company", "merger_and_acquisitions", "lawsuits_and_legal_issues", "outages_and_security_breaches", "closing_office", "new_investment", "new_office", "new_partnership", "cost_cutting", "new_funding_round", "award", "ipo_announcement" ] }, { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "increase_in_customer_service_department", "hiring_in_finance_department", "hiring_in_support_department", "increase_in_engineering_department", "decrease_in_customer_service_department", "hiring_in_operations_department", "hiring_in_creative_department", "decrease_in_engineering_department", "hiring_in_sales_department", "increase_in_operations_department", "hiring_in_trade_department", "decrease_in_marketing_department", "increase_in_marketing_department", "hiring_in_marketing_department", "hiring_in_health_department", "hiring_in_education_department", "increase_in_all_departments", "decrease_in_all_departments", "decrease_in_sales_department", "decrease_in_operations_department", "hiring_in_professional_service_department", "hiring_in_human_resources_department", "increase_in_sales_department", "hiring_in_legal_department", "hiring_in_unknown_department", "hiring_in_engineering_department", "company_award", "new_product", "employee_joined_company", "merger_and_acquisitions", "lawsuits_and_legal_issues", "outages_and_security_breaches", "closing_office", "new_investment", "new_office", "new_partnership", "cost_cutting", "new_funding_round", "award", "ipo_announcement" ] } } ] }, "locations": { "description": "Matches a fixed range for the number of company locations.", "oneOf": [ { "type": "string", "enum": [ "0-1", "2-5", "6-20", "21-50", "51-100", "101-1000", "1001+" ] }, { "type": "array", "minItems": 1, "items": { "type": "string", "enum": [ "0-1", "2-5", "6-20", "21-50", "51-100", "101-1000", "1001+" ] } } ] }, "companyName": { "description": "Matches the company name.", "allOf": [ { "$ref": "#/components/schemas/StringOrStringArray" } ] }, "eventWindow": { "description": "Sets the recent-event window. Null or blank values use the default 30 days.", "oneOf": [ { "type": "string", "enum": [ "30 days", "60 days", "90 days", "120 days" ] }, { "type": "null" }, { "type": "string", "pattern": "^\\s*$" } ], "default": "30 days" }, "locationMatch": { "description": "Controls whether location filters match headquarters only or headquarters and operating locations. Null or blank values use the default hqOnly.", "oneOf": [ { "type": "string", "enum": [ "hqOnly", "hqOperating" ] }, { "type": "null" }, { "type": "string", "pattern": "^\\s*$" } ], "default": "hqOnly" }, "hasWebsite": { "type": [ "boolean", "null" ], "description": "Matches companies by whether a website is present; null leaves this criterion unset." }, "isPublicCompany": { "type": [ "boolean", "null" ], "description": "Matches companies by public-company status; null leaves this criterion unset." } }, "if": { "not": { "anyOf": [ { "required": [ "country" ] }, { "required": [ "region" ] }, { "required": [ "city" ] }, { "required": [ "industry" ] }, { "required": [ "techStack" ] }, { "required": [ "keywords" ] }, { "required": [ "topics" ] }, { "required": [ "companyName" ] }, { "required": [ "size" ] }, { "required": [ "revenue" ] }, { "required": [ "age" ] }, { "required": [ "events" ] }, { "required": [ "locations" ] }, { "required": [ "hasWebsite" ], "properties": { "hasWebsite": { "type": "boolean" } } }, { "required": [ "isPublicCompany" ], "properties": { "isPublicCompany": { "type": "boolean" } } } ] } }, "then": { "not": {} } }, "page": { "description": "A zero-based page supplied as an integer JSON number or one of the equivalent canonical decimal strings. OpenAPI intentionally uses canonical decimal strings even though runtime Number() accepts additional spellings.", "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" } ], "default": 0 }, "size": { "description": "A page size from 1 through 100 supplied as an integer JSON number or one of the equivalent canonical decimal strings. OpenAPI intentionally uses canonical decimal strings even though runtime Number() accepts additional spellings.", "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "string", "pattern": "^(?:[1-9]|[1-9][0-9]|100)$" } ], "default": 50 }, "cursor": { "type": "string", "pattern": "^fc_", "description": "An opaque fc_ cursor returned by the preceding page. When supplied, its saved page size takes precedence over new page or size values." } } }, "examples": { "audience": { "summary": "Synthetic company audience", "value": { "filters": { "country": [ "FR" ], "size": [ "11-50" ], "keywords": [ "workflow automation" ] }, "size": 25 } } } } } }, "responses": { "200": { "description": "A page of matching sanitized public company records.", "content": { "application/json": { "schema": { "type": "object", "required": [ "rows", "total", "page", "size", "next_cursor" ], "additionalProperties": false, "properties": { "rows": { "type": "array", "items": { "$ref": "#/components/schemas/CompanyRow" } }, "total": { "type": "number" }, "page": { "type": "number" }, "size": { "type": "number" }, "next_cursor": { "type": [ "string", "null" ] } } }, "examples": { "reservedData": { "summary": "Synthetic company page using reserved example data", "value": { "rows": [ { "name": "Example Company", "domain": "example.com", "logo": "https://example.com/logo.png", "website": "https://example.com", "countryName": "Example Country", "cityName": "Example City", "region": null, "location": "Example City, Example Country", "industry": null, "linkedinProfile": null, "employeeRange": null, "revenueRange": null, "description": null, "naics": null, "naicsDescription": null, "sicCode": null, "sicDescription": null, "businessIntentTopics": null, "events": null } ], "total": 240, "page": 0, "size": 25, "next_cursor": "fc_eyJ2IjoxLCJtb2RlIjoicGFnZSIsInBhZ2UiOjEsInBhZ2VTaXplIjoyNSwicHJvdmlkZXJTaXplIjoxMDAwMH0" } } } } } }, "400": { "description": "The request is invalid or contains an unsupported field or value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The workspace cannot complete this request because access or available credits are insufficient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the 256 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The workspace rate limit has been exceeded. Try again after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request could not be completed because of an unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The request could not be completed because a required service returned an unsuccessful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The request is temporarily unavailable. Try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/find-companies/filter-values": { "get": { "operationId": "listFindCompanyFilterValues", "tags": [ "Search and discovery" ], "summary": "List Find Companies filter values", "description": "Discovers normalized values accepted by location, industry, intent-topic, and technology filters.", "x-airscale-rate-limit": "6 requests per second per workspace.", "x-airscale-credit-cost": "No charge; Filter-values does not debit Airscale credits.", "x-codeSamples": [ { "label": "cURL", "lang": "bash", "source": "curl --request GET \\\n --url 'https://api.airscale.io/v1/find-companies/filter-values?filter=industry&q=example' \\\n --header \"Authorization: Bearer $AIRSCALE_API_KEY\"" }, { "label": "Node.js", "lang": "node", "source": "const url = new URL(\"https://api.airscale.io/v1/find-companies/filter-values\");\nurl.searchParams.set(\"filter\", \"industry\");\nurl.searchParams.set(\"q\", \"example\");\n\nconst response = await fetch(url, {\n headers: {\n Authorization: `Bearer ${process.env.AIRSCALE_API_KEY}`\n }\n});\nconst data = await response.json();\nconsole.log(data);" }, { "label": "Python", "lang": "python", "source": "import os\nimport requests\n\nresponse = requests.get(\n \"https://api.airscale.io/v1/find-companies/filter-values\",\n headers={\"Authorization\": f'Bearer {os.environ[\"AIRSCALE_API_KEY\"]}'},\n params={\"filter\": \"industry\", \"q\": \"example\"},\n timeout=30,\n)\nresponse.raise_for_status()\nprint(response.json())" } ], "parameters": [ { "name": "filter", "in": "query", "required": true, "description": "The Find Companies filter whose accepted values should be discovered.", "schema": { "type": "string", "enum": [ "city", "region", "industry", "topics", "techStack" ] } }, { "name": "q", "in": "query", "required": false, "description": "At least one of q or query is required and must contain 2 to 120 characters after trimming. When q is present it is read first; a blank q suppresses query and returns 400.", "schema": { "type": "string", "pattern": "^\\s*\\S[\\s\\S]{0,118}\\S\\s*$" } }, { "name": "query", "in": "query", "required": false, "description": "At least one of q or query is required and must contain 2 to 120 characters after trimming. query is used only when q is absent.", "schema": { "type": "string", "pattern": "^\\s*\\S[\\s\\S]{0,118}\\S\\s*$" } }, { "name": "limit", "in": "query", "required": false, "description": "Omitted, non-numeric, or non-integer values default to 20; an explicit empty value becomes 0 then clamps to 1; integers below 1 clamp to 1; integers above 100 clamp to 100.", "schema": { "oneOf": [ { "type": "integer" }, { "type": "string" } ], "default": 20, "example": 20 } }, { "name": "country", "in": "query", "required": false, "description": "Optional country context supplied as repeat or comma-separated values.", "style": "form", "explode": true, "schema": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } }, { "name": "region", "in": "query", "required": false, "description": "Optional region context supplied as repeat or comma-separated values; a bare region name needs country context.", "style": "form", "explode": true, "schema": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ] } } ], "responses": { "200": { "description": "Normalized filter values matching the query and optional location context.", "content": { "application/json": { "schema": { "type": "object", "required": [ "filter", "query", "values" ], "additionalProperties": false, "properties": { "filter": { "type": "string", "enum": [ "city", "region", "industry", "topics", "techStack" ] }, "query": { "type": "string" }, "values": { "type": "array", "items": { "type": "object", "required": [ "label", "value" ], "additionalProperties": false, "properties": { "label": { "type": "string" }, "value": { "type": "string" }, "query": { "type": "string" }, "city": { "type": "string" }, "region": { "type": "string" }, "countryCode": { "type": "string" }, "regionCode": { "type": "string" } } } } } }, "examples": { "industry": { "summary": "Synthetic industry values", "value": { "filter": "industry", "query": "example", "values": [ { "label": "example industry", "value": "example industry" } ] } }, "city": { "summary": "Synthetic city values", "value": { "filter": "city", "query": "exa", "values": [ { "query": "exa", "label": "Example City", "value": "Example City, EX, XX", "city": "Example City", "region": "EX", "countryCode": "xx", "regionCode": "xx-ex" } ] } } } } } }, "400": { "description": "The request is invalid or contains an unsupported field or value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The workspace cannot complete this request because access or available credits are insufficient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the 256 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The workspace rate limit has been exceeded. Try again after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request could not be completed because of an unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The request could not be completed because a required service returned an unsuccessful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The request is temporarily unavailable. Try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/company-lookalikes": { "post": { "operationId": "findCompanyLookalikes", "tags": [ "Search and discovery" ], "summary": "Find company lookalikes", "description": "Finds companies similar to 1–10 reference domains and returns all results in a single response. Use your workspace API key and allow at least 100 seconds for the client timeout. Do not automatically retry this request. A search may complete even when you receive an error or no response, and repeating it can cause another charge.", "x-airscale-rate-limit": "15 requests per rolling minute per workspace. Maximum 5 active searches per workspace.", "x-airscale-credit-cost": "0.5 credits per unique returned company. Reserves limit × 0.5 credits before searching and refunds the unused amount. Empty results cost zero credits.", "x-codeSamples": [ { "label": "cURL", "lang": "bash", "source": "curl --request POST \\\n --url https://api.airscale.io/v1/company-lookalikes \\\n --max-time 100 \\\n --header \"Authorization: Bearer $AIRSCALE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --data '{\"domains\":[\"example.com\"],\"limit\":10}'" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "domains" ], "additionalProperties": false, "properties": { "domains": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string", "minLength": 1, "maxLength": 2048 }, "description": "Reference company websites, normalized to domains and deduplicated. Accepts domains or website URLs, not LinkedIn URLs or IP addresses. Reference companies are excluded from results." }, "limit": { "type": "integer", "minimum": 1, "maximum": 5000, "default": 2000, "description": "Total unique results across all references, not per domain. Maximum min(5000, 2000 × distinct normalized reference domains): 2000 for one, 4000 for two, 5000 for three through ten. Searches may return fewer results." }, "include": { "type": "object", "additionalProperties": false, "properties": { "country": { "type": "array", "maxItems": 100, "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "Country names or ISO alpha-2 codes. Codes are normalized before searching." }, "city": { "type": "array", "maxItems": 100, "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "City names. A location filter that cannot be resolved can return HTTP 422." }, "size": { "type": "array", "maxItems": 8, "items": { "type": "string", "enum": [ "1-10", "11-50", "51-200", "201-500", "501-1000", "1001-5000", "5001-10000", "10001+" ] }, "description": "Employee size bands." } }, "description": "Optional company filters to include." }, "exclude": { "type": "object", "additionalProperties": false, "properties": { "country": { "type": "array", "maxItems": 100, "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "Country names or ISO alpha-2 codes. Codes are normalized before searching." }, "city": { "type": "array", "maxItems": 100, "items": { "type": "string", "minLength": 1, "maxLength": 120 }, "description": "City names. A location filter that cannot be resolved can return HTTP 422." }, "size": { "type": "array", "maxItems": 8, "items": { "type": "string", "enum": [ "1-10", "11-50", "51-200", "201-500", "501-1000", "1001-5000", "5001-10000", "10001+" ] }, "description": "Employee size bands." }, "domains": { "type": "array", "maxItems": 900, "items": { "type": "string", "minLength": 1, "maxLength": 2048 }, "description": "Company websites to omit, normalized to domains." } }, "description": "Optional company filters and domains to exclude." }, "founded": { "type": "object", "additionalProperties": false, "properties": { "min": { "type": "integer", "minimum": 1000, "maximum": 9999 }, "max": { "type": "integer", "minimum": 1000, "maximum": 9999 } }, "description": "Optional founding-year bounds. min cannot exceed max." } } }, "examples": { "simple": { "summary": "Find up to ten similar companies", "value": { "domains": [ "example.com" ], "limit": 10 } }, "filtered": { "summary": "Filter a combined search", "value": { "domains": [ "example.com", "example.org" ], "limit": 100, "include": { "country": [ "France" ], "size": [ "51-200" ] }, "exclude": { "domains": [ "excluded.example.com" ] }, "founded": { "min": 2000, "max": 2026 } } } } } } }, "responses": { "200": { "description": "Completed search. Companies are unique by domain. Partial reference failures can return remaining results with warnings. Empty results cost zero credits.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "total_results", "credits_used", "data", "warnings" ], "properties": { "status": { "type": "string", "const": "success" }, "total_results": { "type": "integer", "minimum": 0, "maximum": 5000, "description": "Number of companies in data." }, "credits_used": { "type": "number", "minimum": 0, "maximum": 2500, "description": "Actual charge: total_results × 0.5 credits." }, "data": { "type": "array", "maxItems": 5000, "items": { "type": "object", "additionalProperties": false, "required": [ "domain", "name", "description", "employee_count", "country", "city", "founded_year", "linkedin_url", "relevance_score", "matched_domains" ], "properties": { "domain": { "type": "string", "description": "Normalized company domain." }, "name": { "type": "string", "description": "Company name; falls back to the domain when missing." }, "description": { "type": "string", "description": "Company description, or an empty string." }, "employee_count": { "type": "string", "description": "Available employee size, commonly a range; not an exact headcount. Empty string when missing." }, "country": { "type": "string", "description": "Country, or an empty string." }, "city": { "type": "string", "description": "City, or an empty string." }, "founded_year": { "type": [ "integer", "null" ], "description": "Founding year, or null when missing." }, "linkedin_url": { "type": "string", "description": "LinkedIn company URL, or an empty string." }, "relevance_score": { "type": [ "number", "null" ], "description": "Available relevance score, or null. Not a confidence percentage and not guaranteed to be between 0 and 1." }, "matched_domains": { "type": "array", "minItems": 1, "maxItems": 10, "items": { "type": "string" }, "description": "Normalized reference domains that matched this company." } } } }, "warnings": { "type": "array", "items": { "type": "string" }, "description": "Partial reference failures or omitted invalid websites. Empty when no warnings occurred." } } }, "examples": { "success": { "summary": "Synthetic company match", "value": { "status": "success", "total_results": 1, "credits_used": 0.5, "data": [ { "domain": "match.example.com", "name": "Example Company", "description": "Software for sales teams.", "employee_count": "51-200", "country": "France", "city": "Paris", "founded_year": 2018, "linkedin_url": "https://www.linkedin.com/company/example", "relevance_score": 0.87, "matched_domains": [ "example.com" ] } ], "warnings": [] } }, "empty": { "summary": "No matching companies", "value": { "status": "success", "total_results": 0, "credits_used": 0, "data": [], "warnings": [] } } } } } }, "400": { "description": "Invalid JSON, unsupported content type, unknown fields, or invalid filters or limits.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "additionalProperties": false, "properties": { "error": { "type": "string", "description": "Safe error message." }, "code": { "type": "string", "description": "Stable error code." } } } } } }, "401": { "description": "Missing, invalid, or revoked workspace API key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "additionalProperties": false, "properties": { "error": { "type": "string", "description": "Safe error message." }, "code": { "type": "string", "description": "Stable error code." } } } } } }, "402": { "description": "Not enough available credits to reserve limit × 0.5 credits.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "additionalProperties": false, "properties": { "error": { "type": "string", "description": "Safe error message." }, "code": { "type": "string", "description": "Stable error code." } } } } } }, "404": { "description": "None of the reference companies could be found (reference_company_not_found).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "additionalProperties": false, "properties": { "error": { "type": "string", "description": "Safe error message." }, "code": { "type": "string", "description": "Stable error code." } } } } } }, "422": { "description": "A location filter could not be resolved.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "additionalProperties": false, "properties": { "error": { "type": "string", "description": "Safe error message." }, "code": { "type": "string", "description": "Stable error code." } } } } } }, "429": { "description": "The workspace has reached 15 starts per rolling minute, already has 5 active searches, or search capacity is temporarily unavailable. Inspect Retry-After when present.", "headers": { "Retry-After": { "description": "Seconds to wait when present. A later POST starts a new search.", "schema": { "type": "integer", "minimum": 1 } } }, "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "additionalProperties": false, "properties": { "error": { "type": "string", "description": "Safe error message." }, "code": { "type": "string", "description": "Stable error code." } } } } } }, "502": { "description": "The search could not be completed.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "additionalProperties": false, "properties": { "error": { "type": "string", "description": "Safe error message." }, "code": { "type": "string", "description": "Stable error code." } } } } } }, "503": { "description": "Company search is temporarily unavailable.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "additionalProperties": false, "properties": { "error": { "type": "string", "description": "Safe error message." }, "code": { "type": "string", "description": "Stable error code." } } } } } }, "504": { "description": "The search deadline was exceeded (company_lookalikes_timeout).", "content": { "application/json": { "schema": { "type": "object", "required": [ "error", "code" ], "additionalProperties": false, "properties": { "error": { "type": "string", "description": "Safe error message." }, "code": { "type": "string", "description": "Stable error code." } } } } } } } } }, "/v1/airsearch": { "post": { "operationId": "airsearch", "tags": [ "Search and discovery" ], "summary": "Research the web with Airsearch", "description": "Researches a public question and returns a sourced answer with optional requested output fields. The JSON request body is limited to 256 KiB.", "x-airscale-rate-limit": "300 requests per minute per workspace.", "x-airscale-credit-cost": "1 credit only for status success; not_found and timeout are not charged.", "requestBody": { "required": true, "description": "Provide a non-empty prompt and, optionally, a map of requested output names to type keywords or descriptions.", "content": { "application/json": { "schema": { "type": "object", "required": [ "prompt" ], "additionalProperties": false, "properties": { "prompt": { "type": "string", "minLength": 1, "pattern": "\\S", "description": "A research question or instruction that remains non-empty after surrounding whitespace is trimmed." }, "schema": { "type": "object", "propertyNames": { "minLength": 1, "pattern": "\\S", "not": { "enum": [ "status", "response", "reasoning", "sources", "confidence_score", "certainty_tag", "duration_ms" ] } }, "additionalProperties": { "type": "string", "minLength": 1, "pattern": "\\S" }, "description": "Maps arbitrary requested output names to non-empty type keywords or plain-language descriptions. Stable envelope names are reserved because dynamic requested fields must not collide with status, response, reasoning, sources, confidence_score, certainty_tag, or duration_ms." } } }, "examples": { "structuredResearch": { "summary": "Research a synthetic company", "value": { "prompt": "What category does Example Company use to describe its service at https://example.com?", "schema": { "category": "string" } } } } } } }, "responses": { "200": { "description": "A completed research result, including successful, not-found, and soft-timeout outcomes.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "response", "reasoning", "sources", "confidence_score", "certainty_tag", "duration_ms" ], "properties": { "status": { "$ref": "#/components/schemas/Status" }, "response": { "oneOf": [ { "type": "string" }, { "type": "object", "additionalProperties": true } ] }, "reasoning": { "type": [ "string", "null" ] }, "sources": { "type": "array", "items": { "type": "string", "description": "A public source URL, public source label such as serp_snippets, or an empty string forwarded from the upstream result." } }, "confidence_score": { "type": "number", "minimum": 0, "maximum": 1 }, "certainty_tag": { "type": [ "string", "null" ], "enum": [ "low", "medium", "high", null ], "description": "Null when no certainty tag could be derived." }, "duration_ms": { "type": "number", "minimum": 0 } }, "additionalProperties": { "type": [ "string", "null" ] } }, "examples": { "success": { "summary": "Synthetic successful research", "value": { "status": "success", "response": "Example Company describes its service as workflow automation.", "category": "workflow automation", "reasoning": "The public example page and search snippets agree.", "sources": [ "https://example.com", "serp_snippets" ], "confidence_score": 0.92, "certainty_tag": "high", "duration_ms": 8420 } }, "notFound": { "summary": "No usable result", "value": { "status": "not_found", "response": "No relevant information found.", "category": null, "reasoning": null, "sources": [], "confidence_score": 0.1, "certainty_tag": "low", "duration_ms": 6900 } }, "timeout": { "summary": "Soft timeout", "value": { "status": "timeout", "response": "No relevant information found.", "category": null, "reasoning": null, "sources": [], "confidence_score": 0, "certainty_tag": "low", "duration_ms": 150000 } } } } } }, "400": { "description": "The request is invalid or contains an unsupported field or value.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The workspace cannot complete this request because access or available credits are insufficient.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the 256 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The workspace rate limit has been exceeded. Try again after the current window resets.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "The request could not be completed because of an unexpected server error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The request could not be completed because a required service returned an unsuccessful response.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The request is temporarily unavailable. Try again later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "504": { "description": "The initial research stage exceeded its time limit. Narrow the prompt before retrying.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/post-likers": { "post": { "operationId": "listPostLikers", "tags": [ "Post engagement" ], "summary": "List LinkedIn post likers", "description": "Retrieves one synchronous, cursor-paginated page of people who liked a LinkedIn post and enriches each returned profile.", "x-airscale-source-sha": "1dc01c0dcf5f10f0d24626fd2e669e3fc1138d98", "x-airscale-rate-limit": "180 requests per fixed minute per workspace, shared by post-likers and post-commenters; pagination requests and retries count.", "x-airscale-credit-cost": "Default enrichment: reserve limit × 0.2 credits, charge 0.2 per successful profile and refund unused or definitive failed slots. Extraction-only: 1 credit per fresh native provider page, including empty terminal pages; cached slices and identical retries are free.", "x-codeSamples": [ { "label": "firstPage", "lang": "bash", "source": "curl --request POST \\\n --url 'https://api.airscale.io/v1/post-likers' \\\n --header \"Authorization: Bearer $AIRSCALE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --header \"Idempotency-Key: ${AIRSCALE_PAGE_KEY:?Set a UUID for this page and retain it for retries}\" \\\n --data '{\n \"post_url\": \"https://example.com/linkedin-post-example\",\n \"limit\": 25\n}'" }, { "label": "nextPage", "lang": "bash", "source": "curl --request POST \\\n --url 'https://api.airscale.io/v1/post-likers' \\\n --header \"Authorization: Bearer $AIRSCALE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --header \"Idempotency-Key: ${AIRSCALE_PAGE_KEY:?Set a UUID for this page and retain it for retries}\" \\\n --data '{\n \"post_url\": \"https://example.com/linkedin-post-example\",\n \"limit\": 25,\n \"cursor\": \"pje1.synthetic_cursor\"\n}'" }, { "label": "firstPage", "lang": "node", "source": "const response = await fetch(\"https://api.airscale.io/v1/post-likers\", {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.AIRSCALE_API_KEY}`,\n \"Content-Type\": \"application/json\",\n \"Idempotency-Key\": process.env.AIRSCALE_PAGE_KEY\n },\n body: JSON.stringify({\n \"post_url\": \"https://example.com/linkedin-post-example\",\n \"limit\": 25\n})\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "label": "nextPage", "lang": "node", "source": "const response = await fetch(\"https://api.airscale.io/v1/post-likers\", {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.AIRSCALE_API_KEY}`,\n \"Content-Type\": \"application/json\",\n \"Idempotency-Key\": process.env.AIRSCALE_PAGE_KEY\n },\n body: JSON.stringify({\n \"post_url\": \"https://example.com/linkedin-post-example\",\n \"limit\": 25,\n \"cursor\": \"pje1.synthetic_cursor\"\n})\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "label": "firstPage", "lang": "python", "source": "import os\nimport requests\n\nresponse = requests.post(\"https://api.airscale.io/v1/post-likers\",\n headers={\n \"Authorization\": f'Bearer {os.environ[\"AIRSCALE_API_KEY\"]}',\n \"Content-Type\": \"application/json\",\n \"Idempotency-Key\": os.environ[\"AIRSCALE_PAGE_KEY\"]\n },\n json={\n \"post_url\": \"https://example.com/linkedin-post-example\",\n \"limit\": 25\n}\n)\nprint(response.json()) # Retain any returned retry key before handling errors.\nresponse.raise_for_status()" }, { "label": "nextPage", "lang": "python", "source": "import os\nimport requests\n\nresponse = requests.post(\"https://api.airscale.io/v1/post-likers\",\n headers={\n \"Authorization\": f'Bearer {os.environ[\"AIRSCALE_API_KEY\"]}',\n \"Content-Type\": \"application/json\",\n \"Idempotency-Key\": os.environ[\"AIRSCALE_PAGE_KEY\"]\n },\n json={\n \"post_url\": \"https://example.com/linkedin-post-example\",\n \"limit\": 25,\n \"cursor\": \"pje1.synthetic_cursor\"\n}\n)\nprint(response.json()) # Retain any returned retry key before handling errors.\nresponse.raise_for_status()" } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Create a UUID for this page and reuse it with the identical endpoint, post_url, limit, cursor and enrich_profiles mode on every retry. Use a new key for the next page. Completed results are replayable for 24 hours after completion. Omitting the header is supported, but an independent retry without the original key can reserve credits again." } ], "requestBody": { "required": true, "description": "Provide a LinkedIn post URL, an optional page size from 1 to 25, and the opaque cursor when continuing pagination. The JSON body must not exceed 128 KiB.", "content": { "application/json": { "schema": { "type": "object", "required": [ "post_url" ], "additionalProperties": false, "properties": { "post_url": { "type": "string", "format": "uri", "minLength": 1, "maxLength": 2048, "description": "An HTTP(S) LinkedIn post URL containing an activity identifier." }, "limit": { "type": "integer", "minimum": 1, "maximum": 25, "default": 25, "description": "Number of engagements to request on this page." }, "enrich_profiles": { "type": "boolean", "default": true, "description": "Omitted or true enriches profiles at 0.2 credits per successful profile. False returns available engagement fields without profile lookups and costs 1 credit per fresh native provider page, including empty terminal pages; cached slices and identical retries are free. Keep the mode unchanged when continuing a cursor." }, "cursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 8192, "description": "An opaque cursor returned by the preceding page. Send it unchanged." } } }, "examples": { "firstPage": { "summary": "First page", "value": { "post_url": "https://www.linkedin.com/posts/example_activity-7376356221991178240", "limit": 25 } }, "nextPage": { "summary": "Next page", "value": { "post_url": "https://www.linkedin.com/posts/example_activity-7376356221991178240", "limit": 25, "cursor": "pje1.synthetic_cursor" } } } } } }, "responses": { "200": { "description": "A page of LinkedIn post engagements with profile enrichment or extraction-only fields, depending on enrich_profiles.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "pagination", "billing" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "profile_status", "linkedin_url", "first_name", "last_name", "full_name", "company_name", "job_title", "location", "domain", "linkedin_company_url", "headline", "reaction_type", "comment", "post_url" ], "additionalProperties": false, "properties": { "profile_status": { "type": "string", "enum": [ "success", "not_found", "error", "not_enriched" ], "description": "Profile enrichment outcome; not_enriched means extraction-only mode." }, "linkedin_url": { "type": [ "string", "null" ] }, "profile_picture_url": { "type": [ "string", "null" ], "description": "Profile picture URL, or null when unavailable." }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "full_name": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "job_title": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "linkedin_company_url": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "reaction_type": { "type": [ "string", "null" ] }, "comment": { "type": [ "string", "null" ] }, "post_url": { "type": [ "string", "null" ] } } }, "description": "The requested engagements with public profile fields and enrichment status." }, "pagination": { "type": "object", "required": [ "next_cursor", "has_more" ], "additionalProperties": false, "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or null when no further page is available. This does not prove complete LinkedIn coverage." }, "has_more": { "type": "boolean" } } }, "retrieval": { "type": "object", "required": [ "reported_total", "returned_count", "status", "stop_reason" ], "additionalProperties": false, "description": "Optional pagination details. Reaching the last available page does not guarantee that every LinkedIn engagement was accessible.", "properties": { "reported_total": { "type": [ "integer", "null" ], "minimum": 0 }, "returned_count": { "type": "integer", "minimum": 0 }, "retrieved_total": { "type": [ "integer", "null" ], "minimum": 0, "description": "Engagements retrieved so far, when reported." }, "status": { "type": "string", "enum": [ "more_available", "provider_exhausted", "partial" ], "description": "partial means fewer engagements could be retrieved than the post reports." }, "stop_reason": { "type": "string", "enum": [ "page_limit", "provider_exhausted", "request_budget", "provider_total_mismatch", "insufficient_credits", "provider_failure" ] } } }, "billing": { "type": "object", "required": [ "credits_consumed", "credits_refunded", "outcomes" ], "additionalProperties": false, "properties": { "credits_consumed": { "type": "number", "minimum": 0, "description": "Credit amount, rounded to two decimals. Raw mode counts paid native pages, not returned people." }, "credits_refunded": { "type": "number", "minimum": 0, "description": "Credit amount refunded, rounded to two decimals." }, "outcomes": { "type": "object", "required": [ "success", "not_found", "error" ], "additionalProperties": false, "properties": { "success": { "type": "integer", "minimum": 0, "maximum": 25 }, "not_found": { "type": "integer", "minimum": 0, "maximum": 25 }, "error": { "type": "integer", "minimum": 0, "maximum": 25 }, "not_enriched": { "type": "integer", "minimum": 0, "maximum": 25, "description": "Returned extraction-only rows; not the number of paid native pages." } } } } } } }, "examples": { "page": { "summary": "Synthetic enriched engagement page", "value": { "items": [ { "profile_status": "success", "linkedin_url": "https://www.linkedin.com/in/example-person-000000", "profile_picture_url": "https://www.example.org/images/example-person.png", "first_name": "Example", "last_name": "Person", "full_name": "Example Person", "company_name": "Example Company", "job_title": "Example role", "location": "Example City", "domain": "example.org", "linkedin_company_url": "https://www.linkedin.com/company/example-company", "headline": "Example role at Example Company", "reaction_type": "LIKE", "comment": null, "post_url": "https://www.linkedin.com/posts/example_activity-7376356221991178240" } ], "pagination": { "next_cursor": "pje1.synthetic_cursor", "has_more": true }, "retrieval": { "reported_total": 120, "returned_count": 1, "retrieved_total": 1, "status": "more_available", "stop_reason": "page_limit" }, "billing": { "credits_consumed": 0.2, "credits_refunded": 4.8, "outcomes": { "success": 1, "not_found": 0, "error": 0 } } } } } } } }, "202": { "description": "The request did not finish within 90 seconds. Its outcome is unconfirmed; retry the identical page with the returned key after Retry-After. This is not a completed result or a guarantee that processing started.", "headers": { "Retry-After": { "description": "Wait this many seconds before retrying (15 for page_pending).", "schema": { "type": "string" }, "example": "15" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "idempotency_key", "retry_after_ms", "message" ], "properties": { "status": { "type": "string", "enum": [ "pending" ] }, "code": { "type": "string", "enum": [ "page_pending" ] }, "idempotency_key": { "type": "string", "format": "uuid" }, "retry_after_ms": { "type": "integer", "minimum": 0 }, "message": { "type": "string" } } }, "examples": { "pending": { "summary": "Unconfirmed page outcome", "value": { "status": "pending", "code": "page_pending", "idempotency_key": "00000000-0000-4000-8000-000000000001", "retry_after_ms": 15000, "message": "Retry the identical page with this Idempotency-Key to retrieve its result." } } } } } }, "400": { "description": "The JSON body, LinkedIn post URL, or cursor is invalid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string", "description": "Use the documented code to distinguish waiting, invalid reuse, and restarting pagination." }, "idempotency_key": { "type": "string", "format": "uuid", "description": "Retain this key and the original request body for safe recovery." }, "retry_after_ms": { "type": "integer", "minimum": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "The workspace does not have enough credits to reserve profile enrichment or a fresh extraction page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string", "description": "Use the documented code to distinguish waiting, invalid reuse, and restarting pagination." }, "idempotency_key": { "type": "string", "format": "uuid", "description": "Retain this key and the original request body for safe recovery." }, "retry_after_ms": { "type": "integer", "minimum": 0 } } } } } }, "409": { "description": "replay_in_progress: wait and retry the identical page with the same key. replay_request_mismatch: the key was already used with different request fields.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string", "description": "Use the documented code to distinguish waiting, invalid reuse, and restarting pagination." }, "idempotency_key": { "type": "string", "format": "uuid", "description": "Retain this key and the original request body for safe recovery." }, "retry_after_ms": { "type": "integer", "minimum": 0 } } } } } }, "413": { "description": "The JSON request body exceeds the 128 KiB limit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string", "description": "Use the documented code to distinguish waiting, invalid reuse, and restarting pagination." }, "idempotency_key": { "type": "string", "format": "uuid", "description": "Retain this key and the original request body for safe recovery." }, "retry_after_ms": { "type": "integer", "minimum": 0 } } } } } }, "429": { "description": "The workspace has exceeded the 180 requests per minute limit shared by post-likers and post-commenters. Wait until the next minute boundary, then retry the identical page with the same idempotency key using bounded backoff.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string", "description": "Use the documented code to distinguish waiting, invalid reuse, and restarting pagination." }, "idempotency_key": { "type": "string", "format": "uuid", "description": "Retain this key and the original request body for safe recovery." }, "retry_after_ms": { "type": "integer", "minimum": 0 } } } } } }, "500": { "description": "The request could not be completed because of an unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string", "description": "Use the documented code to distinguish waiting, invalid reuse, and restarting pagination." }, "idempotency_key": { "type": "string", "format": "uuid", "description": "Retain this key and the original request body for safe recovery." }, "retry_after_ms": { "type": "integer", "minimum": 0 } } } } } }, "502": { "description": "The page could not be retrieved. Retry the identical page with the same idempotency key and increasing delays.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string", "description": "Use the documented code to distinguish waiting, invalid reuse, and restarting pagination." }, "idempotency_key": { "type": "string", "format": "uuid", "description": "Retain this key and the original request body for safe recovery." }, "retry_after_ms": { "type": "integer", "minimum": 0 } } } } } }, "503": { "description": "The page is temporarily unavailable. Follow the response code guidance and keep the original request body and idempotency key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string", "description": "Use the documented code to distinguish waiting, invalid reuse, and restarting pagination." }, "idempotency_key": { "type": "string", "format": "uuid", "description": "Retain this key and the original request body for safe recovery." }, "retry_after_ms": { "type": "integer", "minimum": 0 } } } } } } } } }, "/v1/post-commenters": { "post": { "operationId": "listPostCommenters", "tags": [ "Post engagement" ], "summary": "List LinkedIn post commenters", "description": "Retrieves one synchronous, cursor-paginated page of people who commented on a LinkedIn post and enriches each returned profile.", "x-airscale-source-sha": "1dc01c0dcf5f10f0d24626fd2e669e3fc1138d98", "x-airscale-rate-limit": "180 requests per fixed minute per workspace, shared by post-likers and post-commenters; pagination requests and retries count.", "x-airscale-credit-cost": "Default enrichment: reserve limit × 0.2 credits, charge 0.2 per successful profile and refund unused or definitive failed slots. Extraction-only: 1 credit per fresh native provider page, including empty terminal pages; cached slices and identical retries are free.", "x-codeSamples": [ { "label": "firstPage", "lang": "bash", "source": "curl --request POST \\\n --url 'https://api.airscale.io/v1/post-commenters' \\\n --header \"Authorization: Bearer $AIRSCALE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --header \"Idempotency-Key: ${AIRSCALE_PAGE_KEY:?Set a UUID for this page and retain it for retries}\" \\\n --data '{\n \"post_url\": \"https://example.com/linkedin-post-example\",\n \"limit\": 25\n}'" }, { "label": "nextPage", "lang": "bash", "source": "curl --request POST \\\n --url 'https://api.airscale.io/v1/post-commenters' \\\n --header \"Authorization: Bearer $AIRSCALE_API_KEY\" \\\n --header \"Content-Type: application/json\" \\\n --header \"Idempotency-Key: ${AIRSCALE_PAGE_KEY:?Set a UUID for this page and retain it for retries}\" \\\n --data '{\n \"post_url\": \"https://example.com/linkedin-post-example\",\n \"limit\": 25,\n \"cursor\": \"pje1.synthetic_cursor\"\n}'" }, { "label": "firstPage", "lang": "node", "source": "const response = await fetch(\"https://api.airscale.io/v1/post-commenters\", {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.AIRSCALE_API_KEY}`,\n \"Content-Type\": \"application/json\",\n \"Idempotency-Key\": process.env.AIRSCALE_PAGE_KEY\n },\n body: JSON.stringify({\n \"post_url\": \"https://example.com/linkedin-post-example\",\n \"limit\": 25\n})\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "label": "nextPage", "lang": "node", "source": "const response = await fetch(\"https://api.airscale.io/v1/post-commenters\", {\n method: \"POST\",\n headers: {\n Authorization: `Bearer ${process.env.AIRSCALE_API_KEY}`,\n \"Content-Type\": \"application/json\",\n \"Idempotency-Key\": process.env.AIRSCALE_PAGE_KEY\n },\n body: JSON.stringify({\n \"post_url\": \"https://example.com/linkedin-post-example\",\n \"limit\": 25,\n \"cursor\": \"pje1.synthetic_cursor\"\n})\n});\n\nconst data = await response.json();\nconsole.log(data);" }, { "label": "firstPage", "lang": "python", "source": "import os\nimport requests\n\nresponse = requests.post(\"https://api.airscale.io/v1/post-commenters\",\n headers={\n \"Authorization\": f'Bearer {os.environ[\"AIRSCALE_API_KEY\"]}',\n \"Content-Type\": \"application/json\",\n \"Idempotency-Key\": os.environ[\"AIRSCALE_PAGE_KEY\"]\n },\n json={\n \"post_url\": \"https://example.com/linkedin-post-example\",\n \"limit\": 25\n}\n)\nprint(response.json()) # Retain any returned retry key before handling errors.\nresponse.raise_for_status()" }, { "label": "nextPage", "lang": "python", "source": "import os\nimport requests\n\nresponse = requests.post(\"https://api.airscale.io/v1/post-commenters\",\n headers={\n \"Authorization\": f'Bearer {os.environ[\"AIRSCALE_API_KEY\"]}',\n \"Content-Type\": \"application/json\",\n \"Idempotency-Key\": os.environ[\"AIRSCALE_PAGE_KEY\"]\n },\n json={\n \"post_url\": \"https://example.com/linkedin-post-example\",\n \"limit\": 25,\n \"cursor\": \"pje1.synthetic_cursor\"\n}\n)\nprint(response.json()) # Retain any returned retry key before handling errors.\nresponse.raise_for_status()" } ], "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "schema": { "type": "string", "format": "uuid" }, "description": "Create a UUID for this page and reuse it with the identical endpoint, post_url, limit, cursor and enrich_profiles mode on every retry. Use a new key for the next page. Completed results are replayable for 24 hours after completion. Omitting the header is supported, but an independent retry without the original key can reserve credits again." } ], "requestBody": { "required": true, "description": "Provide a LinkedIn post URL, an optional page size from 1 to 25, and the opaque cursor when continuing pagination. The JSON body must not exceed 128 KiB.", "content": { "application/json": { "schema": { "type": "object", "required": [ "post_url" ], "additionalProperties": false, "properties": { "post_url": { "type": "string", "format": "uri", "minLength": 1, "maxLength": 2048, "description": "An HTTP(S) LinkedIn post URL containing an activity identifier." }, "limit": { "type": "integer", "minimum": 1, "maximum": 25, "default": 25, "description": "Number of engagements to request on this page." }, "enrich_profiles": { "type": "boolean", "default": true, "description": "Omitted or true enriches profiles at 0.2 credits per successful profile. False returns available engagement fields without profile lookups and costs 1 credit per fresh native provider page, including empty terminal pages; cached slices and identical retries are free. Keep the mode unchanged when continuing a cursor." }, "cursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 8192, "description": "An opaque cursor returned by the preceding page. Send it unchanged." } } }, "examples": { "firstPage": { "summary": "First page", "value": { "post_url": "https://www.linkedin.com/posts/example_activity-7376356221991178240", "limit": 25 } }, "nextPage": { "summary": "Next page", "value": { "post_url": "https://www.linkedin.com/posts/example_activity-7376356221991178240", "limit": 25, "cursor": "pje1.synthetic_cursor" } } } } } }, "responses": { "200": { "description": "A page of LinkedIn post engagements with profile enrichment or extraction-only fields, depending on enrich_profiles.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "pagination", "billing" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "profile_status", "linkedin_url", "first_name", "last_name", "full_name", "company_name", "job_title", "location", "domain", "linkedin_company_url", "headline", "reaction_type", "comment", "post_url" ], "additionalProperties": false, "properties": { "profile_status": { "type": "string", "enum": [ "success", "not_found", "error", "not_enriched" ], "description": "Profile enrichment outcome; not_enriched means extraction-only mode." }, "linkedin_url": { "type": [ "string", "null" ] }, "profile_picture_url": { "type": [ "string", "null" ], "description": "Profile picture URL, or null when unavailable." }, "first_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "full_name": { "type": [ "string", "null" ] }, "company_name": { "type": [ "string", "null" ] }, "job_title": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "linkedin_company_url": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "reaction_type": { "type": [ "string", "null" ] }, "comment": { "type": [ "string", "null" ] }, "post_url": { "type": [ "string", "null" ] } } }, "description": "The requested engagements with public profile fields and enrichment status." }, "pagination": { "type": "object", "required": [ "next_cursor", "has_more" ], "additionalProperties": false, "properties": { "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or null when no further page is available. This does not prove complete LinkedIn coverage." }, "has_more": { "type": "boolean" } } }, "retrieval": { "type": "object", "required": [ "reported_total", "returned_count", "status", "stop_reason" ], "additionalProperties": false, "description": "Optional pagination details. Reaching the last available page does not guarantee that every LinkedIn engagement was accessible.", "properties": { "reported_total": { "type": [ "integer", "null" ], "minimum": 0 }, "returned_count": { "type": "integer", "minimum": 0 }, "retrieved_total": { "type": [ "integer", "null" ], "minimum": 0, "description": "Engagements retrieved so far, when reported." }, "status": { "type": "string", "enum": [ "more_available", "provider_exhausted", "partial" ], "description": "partial means fewer engagements could be retrieved than the post reports." }, "stop_reason": { "type": "string", "enum": [ "page_limit", "provider_exhausted", "request_budget", "provider_total_mismatch", "insufficient_credits", "provider_failure" ] } } }, "billing": { "type": "object", "required": [ "credits_consumed", "credits_refunded", "outcomes" ], "additionalProperties": false, "properties": { "credits_consumed": { "type": "number", "minimum": 0, "description": "Credit amount, rounded to two decimals. Raw mode counts paid native pages, not returned people." }, "credits_refunded": { "type": "number", "minimum": 0, "description": "Credit amount refunded, rounded to two decimals." }, "outcomes": { "type": "object", "required": [ "success", "not_found", "error" ], "additionalProperties": false, "properties": { "success": { "type": "integer", "minimum": 0, "maximum": 25 }, "not_found": { "type": "integer", "minimum": 0, "maximum": 25 }, "error": { "type": "integer", "minimum": 0, "maximum": 25 }, "not_enriched": { "type": "integer", "minimum": 0, "maximum": 25, "description": "Returned extraction-only rows; not the number of paid native pages." } } } } } } }, "examples": { "page": { "summary": "Synthetic enriched engagement page", "value": { "items": [ { "profile_status": "success", "linkedin_url": "https://www.linkedin.com/in/example-person-000000", "profile_picture_url": "https://www.example.org/images/example-person.png", "first_name": "Example", "last_name": "Person", "full_name": "Example Person", "company_name": "Example Company", "job_title": "Example role", "location": "Example City", "domain": "example.org", "linkedin_company_url": "https://www.linkedin.com/company/example-company", "headline": "Example role at Example Company", "reaction_type": "COMMENT", "comment": "Example comment", "post_url": "https://www.linkedin.com/posts/example_activity-7376356221991178240" } ], "pagination": { "next_cursor": "pje1.synthetic_cursor", "has_more": true }, "retrieval": { "reported_total": 120, "returned_count": 1, "retrieved_total": 1, "status": "more_available", "stop_reason": "page_limit" }, "billing": { "credits_consumed": 0.2, "credits_refunded": 4.8, "outcomes": { "success": 1, "not_found": 0, "error": 0 } } } } } } } }, "202": { "description": "The request did not finish within 90 seconds. Its outcome is unconfirmed; retry the identical page with the returned key after Retry-After. This is not a completed result or a guarantee that processing started.", "headers": { "Retry-After": { "description": "Wait this many seconds before retrying (15 for page_pending).", "schema": { "type": "string" }, "example": "15" } }, "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "required": [ "status", "code", "idempotency_key", "retry_after_ms", "message" ], "properties": { "status": { "type": "string", "enum": [ "pending" ] }, "code": { "type": "string", "enum": [ "page_pending" ] }, "idempotency_key": { "type": "string", "format": "uuid" }, "retry_after_ms": { "type": "integer", "minimum": 0 }, "message": { "type": "string" } } }, "examples": { "pending": { "summary": "Unconfirmed page outcome", "value": { "status": "pending", "code": "page_pending", "idempotency_key": "00000000-0000-4000-8000-000000000001", "retry_after_ms": 15000, "message": "Retry the identical page with this Idempotency-Key to retrieve its result." } } } } } }, "400": { "description": "The JSON body, LinkedIn post URL, or cursor is invalid.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string", "description": "Use the documented code to distinguish waiting, invalid reuse, and restarting pagination." }, "idempotency_key": { "type": "string", "format": "uuid", "description": "Retain this key and the original request body for safe recovery." }, "retry_after_ms": { "type": "integer", "minimum": 0 } } } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "402": { "description": "The workspace does not have enough credits to reserve profile enrichment or a fresh extraction page.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string", "description": "Use the documented code to distinguish waiting, invalid reuse, and restarting pagination." }, "idempotency_key": { "type": "string", "format": "uuid", "description": "Retain this key and the original request body for safe recovery." }, "retry_after_ms": { "type": "integer", "minimum": 0 } } } } } }, "409": { "description": "replay_in_progress: wait and retry the identical page with the same key. replay_request_mismatch: the key was already used with different request fields.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string", "description": "Use the documented code to distinguish waiting, invalid reuse, and restarting pagination." }, "idempotency_key": { "type": "string", "format": "uuid", "description": "Retain this key and the original request body for safe recovery." }, "retry_after_ms": { "type": "integer", "minimum": 0 } } } } } }, "413": { "description": "The JSON request body exceeds the 128 KiB limit.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string", "description": "Use the documented code to distinguish waiting, invalid reuse, and restarting pagination." }, "idempotency_key": { "type": "string", "format": "uuid", "description": "Retain this key and the original request body for safe recovery." }, "retry_after_ms": { "type": "integer", "minimum": 0 } } } } } }, "429": { "description": "The workspace has exceeded the 180 requests per minute limit shared by post-likers and post-commenters. Wait until the next minute boundary, then retry the identical page with the same idempotency key using bounded backoff.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string", "description": "Use the documented code to distinguish waiting, invalid reuse, and restarting pagination." }, "idempotency_key": { "type": "string", "format": "uuid", "description": "Retain this key and the original request body for safe recovery." }, "retry_after_ms": { "type": "integer", "minimum": 0 } } } } } }, "500": { "description": "The request could not be completed because of an unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string", "description": "Use the documented code to distinguish waiting, invalid reuse, and restarting pagination." }, "idempotency_key": { "type": "string", "format": "uuid", "description": "Retain this key and the original request body for safe recovery." }, "retry_after_ms": { "type": "integer", "minimum": 0 } } } } } }, "502": { "description": "The page could not be retrieved. Retry the identical page with the same idempotency key and increasing delays.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string", "description": "Use the documented code to distinguish waiting, invalid reuse, and restarting pagination." }, "idempotency_key": { "type": "string", "format": "uuid", "description": "Retain this key and the original request body for safe recovery." }, "retry_after_ms": { "type": "integer", "minimum": 0 } } } } } }, "503": { "description": "The page is temporarily unavailable. Follow the response code guidance and keep the original request body and idempotency key.", "content": { "application/json": { "schema": { "type": "object", "required": [ "error" ], "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "code": { "type": "string", "description": "Use the documented code to distinguish waiting, invalid reuse, and restarting pagination." }, "idempotency_key": { "type": "string", "format": "uuid", "description": "Retain this key and the original request body for safe recovery." }, "retry_after_ms": { "type": "integer", "minimum": 0 } } } } } } } } }, "/v1/post-search": { "post": { "operationId": "searchLinkedinPosts", "tags": [ "LinkedIn content" ], "summary": "Search LinkedIn posts", "description": "Returns one page of up to 50 LinkedIn posts matching keywords, author, mention, group, content-type, and date filters. Costs 1 credit per successful non-empty request; empty pages are free.", "x-airscale-source-sha": "1dc01c0dcf5f10f0d24626fd2e669e3fc1138d98", "x-airscale-rate-limit": "180 requests per fixed minute per workspace, counted separately for each LinkedIn content endpoint; pagination requests and retries count.", "x-airscale-credit-cost": "1 credit per successful non-empty request; empty pages, invalid input and failed requests are not charged.", "requestBody": { "required": true, "description": "Search filters and an optional cursor. The JSON body must not exceed 16 KiB.", "content": { "application/json": { "schema": { "type": "object", "additionalProperties": false, "description": "Provide `keywords` or at least one author, mention, or group filter. All provided filters combine.", "properties": { "keywords": { "type": [ "string", "null" ], "maxLength": 200, "description": "Words to search for in posts." }, "author_keywords": { "type": [ "string", "null" ], "maxLength": 200, "description": "Words in the authors' profiles." }, "author_profile_urls": { "description": "Posts written by these LinkedIn profiles (linkedin.com/in/...). A string or an array of up to 10 values.", "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "maxItems": 10, "items": { "type": "string", "minLength": 1 } } ] }, "author_company_urls": { "description": "Posts published by these company pages, as LinkedIn company URLs or numeric company IDs. A string or an array of up to 10 values.", "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "maxItems": 10, "items": { "type": "string", "minLength": 1 } } ] }, "author_employer_company_urls": { "description": "Posts whose authors work at these companies, as LinkedIn company URLs or numeric company IDs. A string or an array of up to 10 values.", "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "maxItems": 10, "items": { "type": "string", "minLength": 1 } } ] }, "author_industry_ids": { "description": "Authors' company industry, as numeric LinkedIn industry IDs. A value or an array of up to 10 values.", "oneOf": [ { "type": [ "string", "integer" ] }, { "type": "array", "maxItems": 10, "items": { "type": [ "string", "integer" ] } } ] }, "mentioning_profile_urls": { "description": "Posts that mention these LinkedIn profiles. A string or an array of up to 10 values.", "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "maxItems": 10, "items": { "type": "string", "minLength": 1 } } ] }, "mentioning_company_urls": { "description": "Posts that mention these companies, as LinkedIn company URLs or numeric company IDs. A string or an array of up to 10 values.", "oneOf": [ { "type": "string", "minLength": 1 }, { "type": "array", "maxItems": 10, "items": { "type": "string", "minLength": 1 } } ] }, "group_url": { "type": [ "string", "integer", "null" ], "description": "Posts inside one LinkedIn group, as a group URL (linkedin.com/groups/...) or numeric group ID." }, "content_type": { "type": [ "string", "null" ], "enum": [ "videos", "images", "live_videos", "documents", "collaborative_articles", "jobs", null ] }, "sort_by": { "type": [ "string", "null" ], "enum": [ "date", "relevance", null ], "default": "date" }, "posted_within": { "type": [ "string", "null" ], "enum": [ "1h", "24h", "week", "month", "3months", "6months", "year", null ], "description": "24h, week, and month are filtered by LinkedIn. 1h, 3months, 6months, and year are applied to each fetched page, so pages can hold fewer than 50 posts; they require sort_by date." }, "cursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 2048, "description": "The opaque `pagination.next_cursor` from the previous page. Send it unchanged with the same filters as the first page." } } }, "examples": { "firstPage": { "summary": "First page", "value": { "keywords": "sales automation", "author_employer_company_urls": [ "https://www.linkedin.com/company/example-company" ], "posted_within": "week" } }, "nextPage": { "summary": "Next page", "value": { "keywords": "sales automation", "author_employer_company_urls": [ "https://www.linkedin.com/company/example-company" ], "posted_within": "week", "cursor": "eyJ2IjoxLCJyIjoiZXhhbXBsZSJ9" } } } } } }, "responses": { "200": { "description": "A page of LinkedIn posts.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "pagination", "billing" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "post_url", "post_id", "content", "posted_at", "author", "likes", "comments", "shares", "feed_context", "image_urls" ], "additionalProperties": false, "properties": { "post_url": { "type": "string" }, "post_id": { "type": [ "string", "null" ] }, "content": { "type": [ "string", "null" ] }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "author": { "type": [ "object", "null" ], "required": [ "type", "name", "linkedin_url", "headline", "picture_url" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "person", "company" ] }, "name": { "type": [ "string", "null" ] }, "linkedin_url": { "type": [ "string", "null" ], "description": "Canonical LinkedIn profile or company URL." }, "headline": { "type": [ "string", "null" ] }, "picture_url": { "type": [ "string", "null" ] } } }, "likes": { "type": [ "integer", "null" ], "minimum": 0 }, "comments": { "type": [ "integer", "null" ], "minimum": 0 }, "shares": { "type": [ "integer", "null" ], "minimum": 0 }, "feed_context": { "type": [ "string", "null" ], "description": "LinkedIn's feed label when the row is not a plain post by the author, such as \"Example Person reposted this\" or \"Example Company collaborated on this\". Null for a plain post." }, "image_urls": { "type": "array", "items": { "type": "string" } } } }, "description": "Posts matching the filters." }, "pagination": { "type": "object", "required": [ "has_more", "next_cursor", "total" ], "additionalProperties": false, "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or null when no further page is available." }, "total": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total matching posts reported by LinkedIn, or null when unavailable." } } }, "billing": { "type": "object", "required": [ "credits_consumed" ], "additionalProperties": false, "properties": { "credits_consumed": { "type": "integer", "enum": [ 0, 1 ] } } } } }, "examples": { "page": { "summary": "Synthetic page", "value": { "items": [ { "post_url": "https://www.linkedin.com/posts/example-person_sales-activity-7511035039397339136-8myb", "post_id": "7511035039397339136", "content": "Example post about sales automation.", "posted_at": "2026-09-30T12:11:41.675Z", "author": { "type": "person", "name": "Example Person", "linkedin_url": "https://www.linkedin.com/in/example-person", "headline": "Head of Sales at Example Company", "picture_url": "https://www.example.org/images/example-person.png" }, "likes": 4, "comments": 1, "shares": 0, "feed_context": null, "image_urls": [ "https://www.example.org/images/example-post.png" ] } ], "pagination": { "has_more": true, "next_cursor": "eyJ2IjoxLCJyIjoiZXhhbXBsZSJ9", "total": 178 }, "billing": { "credits_consumed": 1 } } } } } } }, "400": { "description": "The JSON body is invalid, contains an unsupported field, or carries a cursor that is malformed or belongs to a different request. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The workspace does not have enough credits for this request. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the 16 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The workspace has exceeded 180 requests per minute for this endpoint. Each LinkedIn content endpoint has its own counter. Wait until the next minute boundary, then retry with bounded backoff. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The LinkedIn content lookup failed. Not charged; retry with increasing delays.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lookup is busy (the response includes Retry-After: 5) or a required service is unavailable. Not charged; wait and retry with bounded backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying when the lookup is busy.", "schema": { "type": "string" }, "example": "5" } } }, "504": { "description": "The LinkedIn content lookup timed out. Not charged; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/profile-comments": { "post": { "operationId": "listLinkedinProfileComments", "tags": [ "LinkedIn content" ], "summary": "List a LinkedIn profile's comments", "description": "Returns one page of comments written by a LinkedIn profile, each with the post it was left on. Costs 1 credit per successful non-empty request; empty pages are free.", "x-airscale-source-sha": "1dc01c0dcf5f10f0d24626fd2e669e3fc1138d98", "x-airscale-rate-limit": "180 requests per fixed minute per workspace, counted separately for each LinkedIn content endpoint; pagination requests and retries count.", "x-airscale-credit-cost": "1 credit per successful non-empty request; empty pages, invalid input and failed requests are not charged.", "requestBody": { "required": true, "description": "A LinkedIn profile URL, an optional period, and an optional cursor. The JSON body must not exceed 16 KiB.", "content": { "application/json": { "schema": { "type": "object", "required": [ "profile_url" ], "additionalProperties": false, "properties": { "profile_url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "LinkedIn profile URL (linkedin.com/in/...)." }, "posted_within": { "type": [ "string", "null" ], "enum": [ "24h", "week", "month", null ], "description": "Only return comments from this period." }, "cursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 2048, "description": "The opaque `pagination.next_cursor` from the previous page. Send it unchanged with the same filters as the first page." } } }, "examples": { "firstPage": { "summary": "First page", "value": { "profile_url": "https://www.linkedin.com/in/example-person", "posted_within": "month" } }, "nextPage": { "summary": "Next page", "value": { "profile_url": "https://www.linkedin.com/in/example-person", "posted_within": "month", "cursor": "eyJ2IjoxLCJyIjoiZXhhbXBsZSJ9" } } } } } }, "responses": { "200": { "description": "A page of comments written by the profile.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "pagination", "billing" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "comment_url", "comment_id", "comment", "commented_at", "likes", "replies", "post" ], "additionalProperties": false, "properties": { "comment_url": { "type": "string", "description": "URL of the comment. Use it as `comment_url` for Comment likers." }, "comment_id": { "type": [ "string", "null" ] }, "comment": { "type": "string" }, "commented_at": { "type": [ "string", "null" ], "format": "date-time" }, "likes": { "type": [ "integer", "null" ], "minimum": 0 }, "replies": { "type": [ "integer", "null" ], "minimum": 0 }, "post": { "type": [ "object", "null" ], "description": "The post the comment was left on, or null when unavailable.", "required": [ "post_url", "post_id", "content", "posted_at", "author" ], "additionalProperties": false, "properties": { "post_url": { "type": "string" }, "post_id": { "type": [ "string", "null" ] }, "content": { "type": [ "string", "null" ] }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "author": { "type": [ "object", "null" ], "required": [ "type", "name", "linkedin_url", "headline", "picture_url" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "person", "company" ] }, "name": { "type": [ "string", "null" ] }, "linkedin_url": { "type": [ "string", "null" ], "description": "Canonical LinkedIn profile or company URL." }, "headline": { "type": [ "string", "null" ] }, "picture_url": { "type": [ "string", "null" ] } } } } } } }, "description": "Comments written by the profile." }, "pagination": { "type": "object", "required": [ "has_more", "next_cursor", "total" ], "additionalProperties": false, "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or null when no further page is available." }, "total": { "type": [ "integer", "null" ], "minimum": 0, "description": "Always null: no reliable total is reported for profile comments." } } }, "billing": { "type": "object", "required": [ "credits_consumed" ], "additionalProperties": false, "properties": { "credits_consumed": { "type": "integer", "enum": [ 0, 1 ] } } } } }, "examples": { "page": { "summary": "Synthetic page", "value": { "items": [ { "comment_url": "https://www.linkedin.com/posts/example-person_sales-activity-7511035039397339136-8myb?commentUrn=urn%3Ali%3Acomment%3A%28activity%3A7511035039397339136%2C7511040000000000000%29", "comment_id": "7511040000000000000", "comment": "Great point, thanks for sharing.", "commented_at": "2026-09-30T14:03:41.169Z", "likes": 12, "replies": 2, "post": { "post_url": "https://www.linkedin.com/posts/example-person_sales-activity-7511035039397339136-8myb", "post_id": "7511035039397339136", "content": "Example post about sales automation.", "posted_at": "2026-09-30T12:11:41.675Z", "author": { "type": "person", "name": "Example Person", "linkedin_url": "https://www.linkedin.com/in/example-person", "headline": "Head of Sales at Example Company", "picture_url": "https://www.example.org/images/example-person.png" } } } ], "pagination": { "has_more": true, "next_cursor": "eyJ2IjoxLCJyIjoiZXhhbXBsZSJ9", "total": null }, "billing": { "credits_consumed": 1 } } } } } } }, "400": { "description": "The JSON body is invalid, contains an unsupported field, or carries a cursor that is malformed or belongs to a different request. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The workspace does not have enough credits for this request. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the 16 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The workspace has exceeded 180 requests per minute for this endpoint. Each LinkedIn content endpoint has its own counter. Wait until the next minute boundary, then retry with bounded backoff. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The LinkedIn content lookup failed. Not charged; retry with increasing delays.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lookup is busy (the response includes Retry-After: 5) or a required service is unavailable. Not charged; wait and retry with bounded backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying when the lookup is busy.", "schema": { "type": "string" }, "example": "5" } } }, "504": { "description": "The LinkedIn content lookup timed out. Not charged; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/comment-likers": { "post": { "operationId": "listLinkedinCommentLikers", "tags": [ "LinkedIn content" ], "summary": "List LinkedIn comment likers", "description": "Returns one page of up to 100 people who reacted to one LinkedIn comment. Costs 1 credit per successful non-empty request; empty pages are free.", "x-airscale-source-sha": "1dc01c0dcf5f10f0d24626fd2e669e3fc1138d98", "x-airscale-rate-limit": "180 requests per fixed minute per workspace, counted separately for each LinkedIn content endpoint; pagination requests and retries count.", "x-airscale-credit-cost": "1 credit per successful non-empty request; empty pages, invalid input and failed requests are not charged.", "requestBody": { "required": true, "description": "A LinkedIn comment URL and an optional cursor. The JSON body must not exceed 16 KiB.", "content": { "application/json": { "schema": { "type": "object", "required": [ "comment_url" ], "additionalProperties": false, "properties": { "comment_url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "LinkedIn URL that identifies one comment (it contains urn:li:comment:(...)), such as a comment_url returned by Profile comments." }, "cursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 2048, "description": "The opaque `pagination.next_cursor` from the previous page. Send it unchanged with the same filters as the first page." } } }, "examples": { "firstPage": { "summary": "First page", "value": { "comment_url": "https://www.linkedin.com/posts/example-person_sales-activity-7511035039397339136-8myb?commentUrn=urn%3Ali%3Acomment%3A%28activity%3A7511035039397339136%2C7511040000000000000%29" } }, "nextPage": { "summary": "Next page", "value": { "comment_url": "https://www.linkedin.com/posts/example-person_sales-activity-7511035039397339136-8myb?commentUrn=urn%3Ali%3Acomment%3A%28activity%3A7511035039397339136%2C7511040000000000000%29", "cursor": "eyJ2IjoxLCJyIjoiZXhhbXBsZSJ9" } } } } } }, "responses": { "200": { "description": "A page of people who reacted to the comment.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "pagination", "billing" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "linkedin_url", "full_name", "headline", "profile_picture_url", "reaction_type" ], "additionalProperties": false, "properties": { "linkedin_url": { "type": [ "string", "null" ], "description": "LinkedIn profile or company URL. It can be a member-ID URL (`/in/ACoAA...`) rather than a vanity URL." }, "full_name": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "profile_picture_url": { "type": [ "string", "null" ] }, "reaction_type": { "type": [ "string", "null" ], "description": "LinkedIn reaction, such as LIKE or PRAISE." } } }, "description": "People who reacted to the comment." }, "pagination": { "type": "object", "required": [ "has_more", "next_cursor", "total" ], "additionalProperties": false, "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or null when no further page is available." }, "total": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total reactions reported by LinkedIn, or null when unavailable." } } }, "billing": { "type": "object", "required": [ "credits_consumed" ], "additionalProperties": false, "properties": { "credits_consumed": { "type": "integer", "enum": [ 0, 1 ] } } } } }, "examples": { "page": { "summary": "Synthetic page", "value": { "items": [ { "linkedin_url": "https://www.linkedin.com/in/example-person", "full_name": "Example Person", "headline": "Head of Sales at Example Company", "profile_picture_url": "https://www.example.org/images/example-person.png", "reaction_type": "LIKE" } ], "pagination": { "has_more": true, "next_cursor": "eyJ2IjoxLCJyIjoiZXhhbXBsZSJ9", "total": 104 }, "billing": { "credits_consumed": 1 } } } } } } }, "400": { "description": "The JSON body is invalid, contains an unsupported field, or carries a cursor that is malformed or belongs to a different request. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The workspace does not have enough credits for this request. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the 16 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The workspace has exceeded 180 requests per minute for this endpoint. Each LinkedIn content endpoint has its own counter. Wait until the next minute boundary, then retry with bounded backoff. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The LinkedIn content lookup failed. Not charged; retry with increasing delays.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lookup is busy (the response includes Retry-After: 5) or a required service is unavailable. Not charged; wait and retry with bounded backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying when the lookup is busy.", "schema": { "type": "string" }, "example": "5" } } }, "504": { "description": "The LinkedIn content lookup timed out. Not charged; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/profile-posts": { "post": { "operationId": "listLinkedinProfilePosts", "tags": [ "LinkedIn content" ], "summary": "List a LinkedIn profile's posts", "description": "Returns one page of up to 50 posts from a LinkedIn profile's feed, newest first, including the person's posts and reposts. Costs 1 credit per successful non-empty request; empty pages are free.", "x-airscale-source-sha": "1dc01c0dcf5f10f0d24626fd2e669e3fc1138d98", "x-airscale-rate-limit": "180 requests per fixed minute per workspace, counted separately for each LinkedIn content endpoint; pagination requests and retries count.", "x-airscale-credit-cost": "1 credit per successful non-empty request; empty pages, invalid input and failed requests are not charged.", "requestBody": { "required": true, "description": "A LinkedIn profile URL, an optional period, and an optional cursor. The JSON body must not exceed 16 KiB.", "content": { "application/json": { "schema": { "type": "object", "required": [ "profile_url" ], "additionalProperties": false, "properties": { "profile_url": { "type": "string", "minLength": 1, "maxLength": 2048, "description": "LinkedIn profile URL (linkedin.com/in/...)." }, "posted_within": { "type": [ "string", "null" ], "enum": [ "1h", "24h", "week", "month", "3months", "6months", "year", null ], "description": "Only return posts from this period. The period is applied to each fetched page, so pages can hold fewer than 50 posts, and pagination stops at the first page with no post inside the period." }, "cursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 2048, "description": "The opaque `pagination.next_cursor` from the previous page. Send it unchanged with the same filters as the first page." } } }, "examples": { "firstPage": { "summary": "First page", "value": { "profile_url": "https://www.linkedin.com/in/example-person", "posted_within": "3months" } }, "nextPage": { "summary": "Next page", "value": { "profile_url": "https://www.linkedin.com/in/example-person", "posted_within": "3months", "cursor": "eyJ2IjoxLCJyIjoiZXhhbXBsZSJ9" } } } } } }, "responses": { "200": { "description": "A page of posts from the profile's feed, newest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "pagination", "billing" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "post_url", "post_id", "content", "posted_at", "author", "likes", "comments", "shares", "feed_context", "image_urls" ], "additionalProperties": false, "properties": { "post_url": { "type": "string" }, "post_id": { "type": [ "string", "null" ] }, "content": { "type": [ "string", "null" ] }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "author": { "type": [ "object", "null" ], "required": [ "type", "name", "linkedin_url", "headline", "picture_url" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "person", "company" ] }, "name": { "type": [ "string", "null" ] }, "linkedin_url": { "type": [ "string", "null" ], "description": "Canonical LinkedIn profile or company URL." }, "headline": { "type": [ "string", "null" ] }, "picture_url": { "type": [ "string", "null" ] } } }, "likes": { "type": [ "integer", "null" ], "minimum": 0 }, "comments": { "type": [ "integer", "null" ], "minimum": 0 }, "shares": { "type": [ "integer", "null" ], "minimum": 0 }, "feed_context": { "type": [ "string", "null" ], "description": "LinkedIn's feed label when the row is not a plain post by the author, such as \"Example Person reposted this\" or \"Example Company collaborated on this\". Null for a plain post." }, "image_urls": { "type": "array", "items": { "type": "string" } } } }, "description": "Posts and reposts from the profile's feed, newest first." }, "pagination": { "type": "object", "required": [ "has_more", "next_cursor", "total" ], "additionalProperties": false, "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or null when no further page is available." }, "total": { "type": [ "integer", "null" ], "minimum": 0, "description": "Always null: no reliable total is reported for profile posts." } } }, "billing": { "type": "object", "required": [ "credits_consumed" ], "additionalProperties": false, "properties": { "credits_consumed": { "type": "integer", "enum": [ 0, 1 ] } } } } }, "examples": { "page": { "summary": "Synthetic page", "value": { "items": [ { "post_url": "https://www.linkedin.com/posts/example-person_sales-activity-7511035039397339136-8myb", "post_id": "7511035039397339136", "content": "Example post about sales automation.", "posted_at": "2026-09-30T12:11:41.675Z", "author": { "type": "person", "name": "Example Person", "linkedin_url": "https://www.linkedin.com/in/example-person", "headline": "Head of Sales at Example Company", "picture_url": "https://www.example.org/images/example-person.png" }, "likes": 4, "comments": 1, "shares": 0, "feed_context": null, "image_urls": [ "https://www.example.org/images/example-post.png" ] }, { "post_url": "https://www.linkedin.com/posts/example-company_launch-activity-7511035039397339137-abcd", "post_id": "7511035039397339137", "content": "Launch day", "posted_at": "2026-09-30T11:00:00.000Z", "author": { "type": "company", "name": "Example Company", "linkedin_url": "https://www.linkedin.com/company/example-company", "headline": "1,117 followers", "picture_url": "https://www.example.org/images/example-company.png" }, "likes": 0, "comments": 0, "shares": 0, "feed_context": "Example Person reposted this", "image_urls": [] } ], "pagination": { "has_more": true, "next_cursor": "eyJ2IjoxLCJyIjoiZXhhbXBsZSJ9", "total": null }, "billing": { "credits_consumed": 1 } } } } } } }, "400": { "description": "The JSON body is invalid, contains an unsupported field, or carries a cursor that is malformed or belongs to a different request. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The workspace does not have enough credits for this request. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the 16 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The workspace has exceeded 180 requests per minute for this endpoint. Each LinkedIn content endpoint has its own counter. Wait until the next minute boundary, then retry with bounded backoff. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The LinkedIn content lookup failed. Not charged; retry with increasing delays.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lookup is busy (the response includes Retry-After: 5) or a required service is unavailable. Not charged; wait and retry with bounded backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying when the lookup is busy.", "schema": { "type": "string" }, "example": "5" } } }, "504": { "description": "The LinkedIn content lookup timed out. Not charged; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/company-posts": { "post": { "operationId": "listLinkedinCompanyPosts", "tags": [ "LinkedIn content" ], "summary": "List a LinkedIn company's posts", "description": "Returns one page of up to 50 posts from a LinkedIn company page's feed, newest first. Costs 1 credit per successful non-empty request; empty pages are free.", "x-airscale-source-sha": "1dc01c0dcf5f10f0d24626fd2e669e3fc1138d98", "x-airscale-rate-limit": "180 requests per fixed minute per workspace, counted separately for each LinkedIn content endpoint; pagination requests and retries count.", "x-airscale-credit-cost": "1 credit per successful non-empty request; empty pages, invalid input and failed requests are not charged.", "requestBody": { "required": true, "description": "A LinkedIn company URL or numeric company ID, an optional period, and an optional cursor. The JSON body must not exceed 16 KiB.", "content": { "application/json": { "schema": { "type": "object", "required": [ "company_url" ], "additionalProperties": false, "properties": { "company_url": { "type": [ "string", "integer" ], "description": "LinkedIn company URL (linkedin.com/company/...) or numeric company ID." }, "posted_within": { "type": [ "string", "null" ], "enum": [ "1h", "24h", "week", "month", "3months", "6months", "year", null ], "description": "Only return posts from this period. The period is applied to each fetched page, so pages can hold fewer than 50 posts, and pagination stops at the first page with no post inside the period." }, "cursor": { "type": [ "string", "null" ], "minLength": 1, "maxLength": 2048, "description": "The opaque `pagination.next_cursor` from the previous page. Send it unchanged with the same filters as the first page." } } }, "examples": { "firstPage": { "summary": "First page", "value": { "company_url": "https://www.linkedin.com/company/example-company", "posted_within": "week" } }, "nextPage": { "summary": "Next page", "value": { "company_url": "https://www.linkedin.com/company/example-company", "posted_within": "week", "cursor": "eyJ2IjoxLCJyIjoiZXhhbXBsZSJ9" } } } } } }, "responses": { "200": { "description": "A page of posts from the company page's feed, newest first.", "content": { "application/json": { "schema": { "type": "object", "required": [ "items", "pagination", "billing" ], "additionalProperties": false, "properties": { "items": { "type": "array", "items": { "type": "object", "required": [ "post_url", "post_id", "content", "posted_at", "author", "likes", "comments", "shares", "feed_context", "image_urls" ], "additionalProperties": false, "properties": { "post_url": { "type": "string" }, "post_id": { "type": [ "string", "null" ] }, "content": { "type": [ "string", "null" ] }, "posted_at": { "type": [ "string", "null" ], "format": "date-time" }, "author": { "type": [ "object", "null" ], "required": [ "type", "name", "linkedin_url", "headline", "picture_url" ], "additionalProperties": false, "properties": { "type": { "type": "string", "enum": [ "person", "company" ] }, "name": { "type": [ "string", "null" ] }, "linkedin_url": { "type": [ "string", "null" ], "description": "Canonical LinkedIn profile or company URL." }, "headline": { "type": [ "string", "null" ] }, "picture_url": { "type": [ "string", "null" ] } } }, "likes": { "type": [ "integer", "null" ], "minimum": 0 }, "comments": { "type": [ "integer", "null" ], "minimum": 0 }, "shares": { "type": [ "integer", "null" ], "minimum": 0 }, "feed_context": { "type": [ "string", "null" ], "description": "LinkedIn's feed label when the row is not a plain post by the author, such as \"Example Person reposted this\" or \"Example Company collaborated on this\". Null for a plain post." }, "image_urls": { "type": "array", "items": { "type": "string" } } } }, "description": "Posts from the company page's feed, newest first." }, "pagination": { "type": "object", "required": [ "has_more", "next_cursor", "total" ], "additionalProperties": false, "properties": { "has_more": { "type": "boolean" }, "next_cursor": { "type": [ "string", "null" ], "description": "Opaque cursor for the next page, or null when no further page is available." }, "total": { "type": [ "integer", "null" ], "minimum": 0, "description": "Total posts reported by LinkedIn for the company page, or null when unavailable." } } }, "billing": { "type": "object", "required": [ "credits_consumed" ], "additionalProperties": false, "properties": { "credits_consumed": { "type": "integer", "enum": [ 0, 1 ] } } } } }, "examples": { "page": { "summary": "Synthetic page", "value": { "items": [ { "post_url": "https://www.linkedin.com/posts/example-company_launch-activity-7511035039397339137-abcd", "post_id": "7511035039397339137", "content": "Launch day", "posted_at": "2026-09-30T11:00:00.000Z", "author": { "type": "company", "name": "Example Company", "linkedin_url": "https://www.linkedin.com/company/example-company", "headline": "1,117 followers", "picture_url": "https://www.example.org/images/example-company.png" }, "likes": 12, "comments": 3, "shares": 1, "feed_context": null, "image_urls": [ "https://www.example.org/images/example-post.png" ] } ], "pagination": { "has_more": true, "next_cursor": "eyJ2IjoxLCJyIjoiZXhhbXBsZSJ9", "total": 500 }, "billing": { "credits_consumed": 1 } } } } } } }, "400": { "description": "The JSON body is invalid, contains an unsupported field, or carries a cursor that is malformed or belongs to a different request. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "The workspace does not have enough credits for this request. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "The JSON request body exceeds the 16 KiB limit.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "The workspace has exceeded 180 requests per minute for this endpoint. Each LinkedIn content endpoint has its own counter. Wait until the next minute boundary, then retry with bounded backoff. Not charged.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "The LinkedIn content lookup failed. Not charged; retry with increasing delays.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "The lookup is busy (the response includes Retry-After: 5) or a required service is unavailable. Not charged; wait and retry with bounded backoff.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } }, "headers": { "Retry-After": { "description": "Seconds to wait before retrying when the lookup is busy.", "schema": { "type": "string" }, "example": "5" } } }, "504": { "description": "The LinkedIn content lookup timed out. Not charged; retry later.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/whatsapp-check": { "post": { "tags": [ "Miscellaneous" ], "x-airscale-source-sha": "282e64878898b4f7082e6ce00b740d76aca787f1", "operationId": "checkWhatsapp", "summary": "Check WhatsApp availability", "description": "Check one phone number. Definitive yes and no outcomes both cost one credit. An optional Idempotency-Key makes retries of the same phone reuse the operation; a different phone with the same key returns 409. When omitted, the server generates an operation ID. Save the returned ID for reconciliation.", "x-airscale-rate-limit": "60 requests per minute per workspace for POST, including replays.", "x-airscale-credit-cost": "1 credit for a definitive yes or no. Pending and unknown responses do not report a final charge.", "parameters": [ { "name": "Idempotency-Key", "in": "header", "required": false, "description": "Optional UUID (versions 1–5). Reuse the same key and phone for retries of one logical check. The server trims whitespace and normalizes UUID case.", "schema": { "type": "string", "pattern": "^\\s*[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}\\s*$" }, "example": "00000000-0000-4000-8000-000000000001" } ], "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$", "description": "Strict E.164 number, with no spaces or punctuation other than the leading +." } }, "required": [ "phone" ], "additionalProperties": false }, "examples": { "request": { "value": { "phone": "+12025550147" } } } } } }, "responses": { "200": { "description": "Definitive WhatsApp result.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation_id": { "type": "string", "format": "uuid", "description": "Operation UUID." }, "phone": { "type": "string", "pattern": "^\\+[1-9]\\d{6,14}$", "description": "Strict E.164 number, with no spaces or punctuation other than the leading +." }, "whatsapp": { "type": "string", "enum": [ "yes", "no" ] }, "credits_consumed": { "type": "integer", "const": 1 } }, "required": [ "operation_id", "phone", "whatsapp", "credits_consumed" ], "additionalProperties": false }, "examples": { "yes": { "value": { "operation_id": "00000000-0000-4000-8000-000000000001", "phone": "+12025550147", "whatsapp": "yes", "credits_consumed": 1 } }, "no": { "value": { "operation_id": "00000000-0000-4000-8000-000000000001", "phone": "+12025550147", "whatsapp": "no", "credits_consumed": 1 } } } } } }, "202": { "description": "The operation is pending or its outcome is uncertain. Look up this operation ID before retrying; do not infer a yes/no result or final charge.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation_id": { "type": "string", "format": "uuid", "description": "Operation UUID." }, "status": { "type": "string", "enum": [ "pending", "unknown" ] } }, "required": [ "operation_id", "status" ], "additionalProperties": false }, "examples": { "pending": { "value": { "operation_id": "00000000-0000-4000-8000-000000000001", "status": "pending" } }, "unknown": { "value": { "operation_id": "00000000-0000-4000-8000-000000000001", "status": "unknown" } } } } } }, "400": { "description": "Invalid request or UUID. POST requires exactly one strict E.164 phone field and a JSON body of at most 16 KiB; oversized bodies also return 400.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "operation_id": { "type": "string", "format": "uuid", "description": "Operation UUID." } }, "required": [ "error" ], "additionalProperties": true }, "examples": {} } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Insufficient credits. A durably recorded rejection includes operation_id.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "operation_id": { "type": "string", "format": "uuid", "description": "Operation UUID." } }, "required": [ "error" ], "additionalProperties": true }, "examples": {} } } }, "409": { "description": "The idempotency key belongs to a different request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "operation_id": { "type": "string", "format": "uuid", "description": "Operation UUID." } }, "required": [ "error" ], "additionalProperties": true }, "examples": {} } } }, "429": { "description": "Workspace POST rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "operation_id": { "type": "string", "format": "uuid", "description": "Operation UUID." } }, "required": [ "error" ], "additionalProperties": true }, "examples": {} } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "operation_id": { "type": "string", "format": "uuid", "description": "Operation UUID." } }, "required": [ "error" ], "additionalProperties": true }, "examples": {} } } }, "503": { "description": "Authentication, rate limiting, operation storage, or WhatsApp checking is unavailable. A recorded unavailable operation includes operation_id. Reuse the same key when reconciling a request.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "operation_id": { "type": "string", "format": "uuid", "description": "Operation UUID." } }, "required": [ "error" ], "additionalProperties": true }, "examples": {} } } } } } }, "/v1/whatsapp-check/operations/{operation_id}": { "get": { "tags": [ "Miscellaneous" ], "x-airscale-source-sha": "282e64878898b4f7082e6ce00b740d76aca787f1", "operationId": "getWhatsappCheckOperation", "summary": "Get WhatsApp check status", "description": "Read a previously submitted operation in the authenticated workspace. This lookup does not start another check or charge credits. A completed result omits the phone; unavailable and rejected are terminal states returned with HTTP 200. Pending or unknown states return HTTP 202.", "x-airscale-rate-limit": "No endpoint-specific GET throttle.", "x-airscale-credit-cost": "No additional charge for this read-only lookup.", "parameters": [ { "name": "operation_id", "in": "path", "required": true, "schema": { "type": "string", "format": "uuid", "description": "Operation UUID.", "pattern": "^[0-9a-fA-F]{8}-[0-9a-fA-F]{4}-[1-5][0-9a-fA-F]{3}-[89aAbB][0-9a-fA-F]{3}-[0-9a-fA-F]{12}$" }, "example": "00000000-0000-4000-8000-000000000001" } ], "responses": { "200": { "description": "Completed check or terminal unavailable/rejected operation.", "content": { "application/json": { "schema": { "oneOf": [ { "type": "object", "properties": { "operation_id": { "type": "string", "format": "uuid", "description": "Operation UUID." }, "status": { "type": "string", "const": "completed" }, "whatsapp": { "type": "string", "enum": [ "yes", "no" ] }, "credits_consumed": { "type": "integer", "const": 1 } }, "required": [ "operation_id", "status", "whatsapp", "credits_consumed" ], "additionalProperties": false }, { "type": "object", "properties": { "operation_id": { "type": "string", "format": "uuid", "description": "Operation UUID." }, "status": { "type": "string", "enum": [ "unavailable", "rejected", "completed" ], "description": "A completed state without result fields means a definitive stored result could not be confirmed." } }, "required": [ "operation_id", "status" ], "additionalProperties": false } ] }, "examples": { "completed": { "value": { "operation_id": "00000000-0000-4000-8000-000000000001", "status": "completed", "whatsapp": "yes", "credits_consumed": 1 } }, "unavailable": { "value": { "operation_id": "00000000-0000-4000-8000-000000000001", "status": "unavailable" } }, "rejected": { "value": { "operation_id": "00000000-0000-4000-8000-000000000001", "status": "rejected" } } } } } }, "202": { "description": "The operation is pending or its outcome is uncertain. Look up this operation ID before retrying; do not infer a yes/no result or final charge.", "content": { "application/json": { "schema": { "type": "object", "properties": { "operation_id": { "type": "string", "format": "uuid", "description": "Operation UUID." }, "status": { "type": "string", "enum": [ "pending", "unknown" ] } }, "required": [ "operation_id", "status" ], "additionalProperties": false }, "examples": { "pending": { "value": { "operation_id": "00000000-0000-4000-8000-000000000001", "status": "pending" } }, "unknown": { "value": { "operation_id": "00000000-0000-4000-8000-000000000001", "status": "unknown" } } } } } }, "400": { "description": "Invalid request or UUID. POST requires exactly one strict E.164 phone field and a JSON body of at most 16 KiB; oversized bodies also return 400.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "operation_id": { "type": "string", "format": "uuid", "description": "Operation UUID." } }, "required": [ "error" ], "additionalProperties": true }, "examples": {} } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "404": { "description": "Operation not found in this workspace.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "operation_id": { "type": "string", "format": "uuid", "description": "Operation UUID." } }, "required": [ "error" ], "additionalProperties": true }, "examples": {} } } }, "500": { "description": "Unexpected server error.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "operation_id": { "type": "string", "format": "uuid", "description": "Operation UUID." } }, "required": [ "error" ], "additionalProperties": true }, "examples": {} } } }, "503": { "description": "Authentication or operation storage is unavailable.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "operation_id": { "type": "string", "format": "uuid", "description": "Operation UUID." } }, "required": [ "error" ], "additionalProperties": true }, "examples": {} } } } } } }, "/v1/meta-ads": { "post": { "tags": [ "Miscellaneous" ], "x-airscale-source-sha": "282e64878898b4f7082e6ce00b740d76aca787f1", "operationId": "lookupMetaAds", "summary": "Look up Meta ads", "description": "Look up ads for one company domain. Only a finite numeric number_of_ads greater than zero costs one credit; zero, missing, nonnumeric, or nonpositive counts cost zero. A balance of at least one credit is required before lookup. No caller idempotency key is supported; retrying a successful lookup can incur another charge.", "x-airscale-rate-limit": "60 requests per minute per workspace.", "x-airscale-credit-cost": "1 credit for a positive finite numeric ad count; otherwise 0.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "domain": { "type": "string", "minLength": 1, "description": "Bare company hostname or HTTP(S) URL. Whitespace is trimmed; hostname is lowercased and leading www. and trailing dot are removed. Paths and queries are ignored. IP literals, credentials, non-default ports, and invalid domain labels are rejected. Maximum JSON body size: 16 KiB (oversize returns 400)." } }, "required": [ "domain" ], "additionalProperties": false }, "examples": { "request": { "value": { "domain": "example.com" } } } } } }, "responses": { "200": { "description": "Ad lookup result and credit cost. Ad fields are optional and their types can vary.", "content": { "application/json": { "schema": { "type": "object", "properties": { "page_id": { "description": "Meta page identifier, when present." }, "number_of_ads": { "description": "Ad count, when present. Only a positive finite number is billable." }, "credits_consumed": { "type": "integer", "enum": [ 0, 1 ] }, "country_code": {}, "continuation_token": {}, "platform": {}, "media_types": {}, "sort_data": {}, "active_status": {}, "is_result_complete": {}, "count_landing_pages": {}, "unique_landing_pages": {}, "start_min_date": {}, "start_max_date": {}, "results": { "type": "array", "description": "Ads found for the page, when there are any. Ad fields vary; check for missing or null values before using them.", "items": { "type": "object", "properties": { "ad_archive_id": {}, "collation_id": {}, "page_id": {}, "is_active": {}, "page_name": {}, "categories": {}, "publisher_platform": {}, "total_active_time": {}, "entity_type": {}, "url": {}, "start_date": { "description": "Start time as a Unix timestamp in seconds." }, "end_date": { "description": "End time as a Unix timestamp in seconds." }, "start_date_string": { "description": "Start time as text." }, "end_date_string": { "description": "End time as text." }, "snapshot": { "type": "object", "properties": { "page_id": {}, "page_profile_uri": {}, "page_name": {}, "page_profile_picture_url": {}, "caption": {}, "cta_text": {}, "cta_type": {}, "display_format": {}, "link_description": {}, "link_url": {}, "images": {}, "page_categories": {}, "page_like_count": {}, "title": {}, "videos": {}, "extra_links": {}, "extra_texts": {}, "extra_images": {}, "extra_videos": {}, "current_page_name": {}, "page_entity_type": {}, "page_is_profile_page": {}, "body": { "description": "Ad text, as { text }.", "properties": { "text": {} } }, "cards": { "type": "array", "description": "Carousel cards, when the ad has several.", "items": { "type": "object", "properties": { "body": {}, "cta_type": {}, "caption": {}, "link_description": {}, "link_url": {}, "title": {}, "cta_text": {}, "video_hd_url": {}, "video_preview_image_url": {}, "video_sd_url": {}, "watermarked_video_hd_url": {}, "watermarked_video_sd_url": {}, "image_crops": {}, "original_image_url": {}, "resized_image_url": {}, "watermarked_resized_image_url": {} } } } } } } } } }, "required": [ "credits_consumed" ], "additionalProperties": true }, "examples": { "ads": { "value": { "page_id": "100000000000001", "country_code": null, "continuation_token": "example-continuation-token", "platform": [ "FACEBOOK", "INSTAGRAM" ], "media_types": "all", "sort_data": "SORT_BY_TOTAL_IMPRESSIONS", "active_status": "active", "is_result_complete": false, "number_of_ads": 4, "count_landing_pages": 1, "unique_landing_pages": [ "https://www.example.com/" ], "start_min_date": "2026-01-01", "start_max_date": "2026-03-01", "results": [ { "ad_archive_id": "200000000000001", "collation_id": null, "page_id": "100000000000001", "is_active": true, "page_name": "Example Company", "categories": [ "UNKNOWN" ], "start_date": 1767225600, "end_date": 1772323200, "start_date_string": "2026-01-01", "end_date_string": "2026-03-01", "publisher_platform": [ "FACEBOOK", "INSTAGRAM" ], "total_active_time": null, "entity_type": null, "url": "https://www.example.com/ads/200000000000001", "snapshot": { "page_id": "100000000000001", "page_profile_uri": "https://www.example.com/example-company", "page_name": "Example Company", "page_profile_picture_url": "https://www.example.com/images/example-company.png", "caption": "example.com", "title": "Example ad title", "body": { "text": "Synthetic ad text for API documentation." }, "cta_text": "Learn more", "cta_type": "LEARN_MORE", "display_format": "DCO", "link_description": null, "link_url": "https://www.example.com/", "page_categories": [ "Software" ], "page_like_count": 1200, "images": [], "videos": [], "extra_links": [], "extra_texts": [], "extra_images": [], "extra_videos": [], "current_page_name": null, "page_entity_type": null, "page_is_profile_page": null, "cards": [ { "body": "Synthetic card text.", "caption": "example.com", "title": "Example card title", "cta_text": "Learn more", "cta_type": "LEARN_MORE", "link_description": null, "link_url": "https://www.example.com/", "original_image_url": "https://www.example.com/images/example-ad.png", "resized_image_url": "https://www.example.com/images/example-ad-small.png", "watermarked_resized_image_url": null, "video_hd_url": null, "video_sd_url": null, "video_preview_image_url": null, "watermarked_video_hd_url": null, "watermarked_video_sd_url": null, "image_crops": [] } ] } } ], "credits_consumed": 1 } }, "noAds": { "value": { "number_of_ads": 0, "credits_consumed": 0 } } } } } }, "400": { "description": "Invalid JSON, domain, extra fields, or body larger than 16 KiB.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "operation_id": { "type": "string", "format": "uuid", "description": "Operation UUID." } }, "required": [ "error" ], "additionalProperties": true }, "examples": {} } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Insufficient credits.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "operation_id": { "type": "string", "format": "uuid", "description": "Operation UUID." } }, "required": [ "error" ], "additionalProperties": true }, "examples": {} } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "operation_id": { "type": "string", "format": "uuid", "description": "Operation UUID." } }, "required": [ "error" ], "additionalProperties": true }, "examples": {} } } }, "502": { "description": "The ad lookup failed. Retry with increasing delays and a fixed retry limit.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "operation_id": { "type": "string", "format": "uuid", "description": "Operation UUID." } }, "required": [ "error" ], "additionalProperties": true }, "examples": {} } } }, "503": { "description": "The request is temporarily unavailable. Retry with increasing delays and a fixed retry limit; contact support if errors persist.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "operation_id": { "type": "string", "format": "uuid", "description": "Operation UUID." } }, "required": [ "error" ], "additionalProperties": true }, "examples": {} } } }, "504": { "description": "The lookup exceeded its 90-second timeout. No debit is made for this timeout.", "content": { "application/json": { "schema": { "type": "object", "properties": { "error": { "type": "string" }, "message": { "type": "string" }, "operation_id": { "type": "string", "format": "uuid", "description": "Operation UUID." } }, "required": [ "error" ], "additionalProperties": true }, "examples": {} } } } } } }, "/v1/email-verifier": { "post": { "tags": [ "Miscellaneous" ], "x-airscale-source-sha": "282e64878898b4f7082e6ce00b740d76aca787f1", "operationId": "verifyEmail", "summary": "Verify an email address", "description": "Verify one email address for 0.5 credits. Allow at least 135 seconds plus a network margin for the response. Inconclusive verification returns risky without another charge. Read the result from body when present, otherwise from the top level. The legacy /email-verifier route is also available. No caller idempotency key is supported.", "x-airscale-rate-limit": "No endpoint-specific throttle.", "x-airscale-credit-cost": "0.5 credits reserved per request. Failed verification requests are eligible for a refund; 503 can mean the charge or refund could not be confirmed.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "email": { "type": "string", "pattern": "^\\s*[^\\s@]+@[^\\s@]+\\.[^\\s@]+\\s*$", "description": "One email address. Surrounding whitespace is trimmed; the trimmed value must be at most 320 characters. Maximum JSON body size: 16 KiB." } }, "required": [ "email" ], "additionalProperties": false }, "examples": { "request": { "value": { "email": "person@example.com" } } } } } }, "responses": { "200": { "description": "A verification result, either at the top level or inside body. JSON object results include credits_consumed; other fields are optional and their types can vary. Successful responses can also contain non-object JSON or non-JSON content without a credits_consumed field.", "content": { "application/json": { "schema": { "anyOf": [ { "not": { "type": "object" } }, { "type": "object", "properties": { "email": { "description": "Email address, when present. Validate the value type before using it." }, "status": { "description": "Verification status, when present." }, "result": { "description": "Deliverability result, when present; risky means verification remained inconclusive." }, "credits_consumed": { "type": "number", "const": 0.5 }, "score": { "description": "Deliverability score from 0 to 100, when present." }, "is_accept_all": { "description": "Whether the domain accepts all addresses (catch-all), when present." }, "is_disposable": { "description": "Whether the address is disposable, when present." }, "is_free": { "description": "Whether the address uses a free email provider, when present." }, "is_role": { "description": "Whether the address is a role address such as sales@, when present." }, "mx_records": { "description": "Mail servers for the domain, when present." }, "smtp_provider": { "description": "Mail hosting service for the domain, when present." }, "mode": { "description": "Verification mode, when present." }, "id": { "description": "Verification identifier, when present." }, "verify_at": { "description": "Verification time, when present." }, "credits_remaining": { "description": "Balance reported by the verification service, when present. This is not your Airscale credit balance; use POST /v1/credits for that." } }, "required": [ "credits_consumed" ], "additionalProperties": true }, { "type": "object", "properties": { "body": { "type": "object", "properties": { "email": { "description": "Email address, when present. Validate the value type before using it." }, "status": { "description": "Verification status, when present." }, "result": { "description": "Deliverability result, when present; risky means verification remained inconclusive." }, "credits_consumed": { "type": "number", "const": 0.5 }, "score": { "description": "Deliverability score from 0 to 100, when present." }, "is_accept_all": { "description": "Whether the domain accepts all addresses (catch-all), when present." }, "is_disposable": { "description": "Whether the address is disposable, when present." }, "is_free": { "description": "Whether the address uses a free email provider, when present." }, "is_role": { "description": "Whether the address is a role address such as sales@, when present." }, "mx_records": { "description": "Mail servers for the domain, when present." }, "smtp_provider": { "description": "Mail hosting service for the domain, when present." }, "mode": { "description": "Verification mode, when present." }, "id": { "description": "Verification identifier, when present." }, "verify_at": { "description": "Verification time, when present." }, "credits_remaining": { "description": "Balance reported by the verification service, when present. This is not your Airscale credit balance; use POST /v1/credits for that." } }, "required": [ "credits_consumed" ], "additionalProperties": true }, "returned_an_error": { "type": "boolean", "const": false } }, "required": [ "body", "returned_an_error" ], "additionalProperties": true } ] }, "examples": { "direct": { "value": { "email": "person@example.com", "status": "success", "result": "deliverable", "score": 100, "is_accept_all": false, "is_disposable": false, "is_free": false, "is_role": false, "mx_records": [ "mx1.example.com" ], "smtp_provider": "Example Mail", "mode": "regular", "id": "example-verification-000001", "verify_at": "2026-01-01T00:00:00Z", "credits_remaining": 1000, "credits_consumed": 0.5 } }, "wrapped": { "value": { "body": { "email": "person@example.com", "status": "success", "result": "risky", "credits_consumed": 0.5 }, "returned_an_error": false } } } }, "*/*": { "schema": {} } } }, "201": { "description": "The same result as 200. The success status code and Content-Type are passed through from the verification service, so a successful verification can also arrive as 201.", "content": { "application/json": { "schema": { "anyOf": [ { "not": { "type": "object" } }, { "type": "object", "properties": { "email": { "description": "Email address, when present. Validate the value type before using it." }, "status": { "description": "Verification status, when present." }, "result": { "description": "Deliverability result, when present; risky means verification remained inconclusive." }, "credits_consumed": { "type": "number", "const": 0.5 }, "score": { "description": "Deliverability score from 0 to 100, when present." }, "is_accept_all": { "description": "Whether the domain accepts all addresses (catch-all), when present." }, "is_disposable": { "description": "Whether the address is disposable, when present." }, "is_free": { "description": "Whether the address uses a free email provider, when present." }, "is_role": { "description": "Whether the address is a role address such as sales@, when present." }, "mx_records": { "description": "Mail servers for the domain, when present." }, "smtp_provider": { "description": "Mail hosting service for the domain, when present." }, "mode": { "description": "Verification mode, when present." }, "id": { "description": "Verification identifier, when present." }, "verify_at": { "description": "Verification time, when present." }, "credits_remaining": { "description": "Balance reported by the verification service, when present. This is not your Airscale credit balance; use POST /v1/credits for that." } }, "required": [ "credits_consumed" ], "additionalProperties": true }, { "type": "object", "properties": { "body": { "type": "object", "properties": { "email": { "description": "Email address, when present. Validate the value type before using it." }, "status": { "description": "Verification status, when present." }, "result": { "description": "Deliverability result, when present; risky means verification remained inconclusive." }, "credits_consumed": { "type": "number", "const": 0.5 }, "score": { "description": "Deliverability score from 0 to 100, when present." }, "is_accept_all": { "description": "Whether the domain accepts all addresses (catch-all), when present." }, "is_disposable": { "description": "Whether the address is disposable, when present." }, "is_free": { "description": "Whether the address uses a free email provider, when present." }, "is_role": { "description": "Whether the address is a role address such as sales@, when present." }, "mx_records": { "description": "Mail servers for the domain, when present." }, "smtp_provider": { "description": "Mail hosting service for the domain, when present." }, "mode": { "description": "Verification mode, when present." }, "id": { "description": "Verification identifier, when present." }, "verify_at": { "description": "Verification time, when present." }, "credits_remaining": { "description": "Balance reported by the verification service, when present. This is not your Airscale credit balance; use POST /v1/credits for that." } }, "required": [ "credits_consumed" ], "additionalProperties": true }, "returned_an_error": { "type": "boolean", "const": false } }, "required": [ "body", "returned_an_error" ], "additionalProperties": true } ] }, "examples": { "direct": { "value": { "email": "person@example.com", "status": "success", "result": "deliverable", "score": 100, "is_accept_all": false, "is_disposable": false, "is_free": false, "is_role": false, "mx_records": [ "mx1.example.com" ], "smtp_provider": "Example Mail", "mode": "regular", "id": "example-verification-000001", "verify_at": "2026-01-01T00:00:00Z", "credits_remaining": 1000, "credits_consumed": 0.5 } }, "wrapped": { "value": { "body": { "email": "person@example.com", "status": "success", "result": "risky", "credits_consumed": 0.5 }, "returned_an_error": false } } } }, "*/*": { "schema": {} } } }, "400": { "description": "Invalid JSON or body does not contain exactly one valid email field. Error bodies may vary. A failed verification is eligible for a refund; a 503 can mean the charge or refund could not be confirmed.", "content": { "application/json": { "schema": {} }, "*/*": { "schema": {} } } }, "401": { "description": "Missing or invalid bearer API key. Error bodies may vary. A failed verification is eligible for a refund; a 503 can mean the charge or refund could not be confirmed.", "content": { "application/json": { "schema": {} }, "*/*": { "schema": {} } } }, "403": { "description": "Insufficient credits. Error bodies may vary. A failed verification is eligible for a refund; a 503 can mean the charge or refund could not be confirmed.", "content": { "application/json": { "schema": {} }, "*/*": { "schema": {} } } }, "413": { "description": "JSON body exceeds 16 KiB. Error bodies may vary. A failed verification is eligible for a refund; a 503 can mean the charge or refund could not be confirmed.", "content": { "application/json": { "schema": {} }, "*/*": { "schema": {} } } }, "500": { "description": "An unexpected server error occurred. Error bodies may vary. A failed verification is eligible for a refund; a 503 can mean the charge or refund could not be confirmed.", "content": { "application/json": { "schema": {} }, "*/*": { "schema": {} } } }, "502": { "description": "The verification request could not be completed. Error bodies may vary. A failed verification is eligible for a refund; a 503 can mean the charge or refund could not be confirmed.", "content": { "application/json": { "schema": {} }, "*/*": { "schema": {} } } }, "503": { "description": "The charge or refund could not be confirmed. Do not assume credits have been returned. Error bodies may vary. A failed verification is eligible for a refund; a 503 can mean the charge or refund could not be confirmed.", "content": { "application/json": { "schema": {} }, "*/*": { "schema": {} } } }, "default": { "description": "Other errors, such as 422, can have varying bodies. Failed verification requests are eligible for a refund. Successful responses can also contain non-object JSON or non-JSON content without a credits_consumed field.", "content": { "application/json": { "schema": {} }, "*/*": { "schema": {} } } } } } }, "/v1/leads-finder": { "post": { "operationId": "searchLeadsFinder", "tags": [ "Search and discovery" ], "summary": "Search Leads Finder", "description": "Search with Leads Finder filters and zero-based page pagination. This filter model is different from Find people's query model.", "x-airscale-rate-limit": "5 requests per second per workspace.", "x-airscale-credit-cost": "0.1 credits per returned lead. At least 0.1 credits are required to start.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "required": [ "filters" ], "additionalProperties": false, "properties": { "filters": { "type": "object", "minProperties": 1, "additionalProperties": false, "description": "At least one non-empty filter other than searchMode is required. Use only the documented fields; some malformed legacy values are ignored by the runtime rather than rejected.", "properties": { "job": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "One value or multiple values." }, "jobExclude": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "One value or multiple values." }, "company": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Company names, domains, or LinkedIn organization URLs. Invalid LinkedIn company URLs are rejected." }, "companyUrl": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Company names, domains, or LinkedIn organization URLs. Invalid LinkedIn company URLs are rejected." }, "peopleLocation": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "One value or multiple values." }, "peopleLocationExclude": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "One value or multiple values." }, "jobFunction": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Job functions; at most 300 non-empty values after splitting." }, "jobFunctionExclude": { "oneOf": [ { "type": "string" }, { "type": "array", "items": { "type": "string" } } ], "description": "Job functions; at most 300 non-empty values after splitting." }, "seniority": { "type": "string", "description": "Seniority values, separated by newlines." }, "seniorityExclude": { "type": "string", "description": "Seniority values to exclude." }, "yearsCurrentRole": { "type": "string", "description": "Current-role tenure, for example 1 to 2 years." }, "yearsCurrentCompany": { "type": "string", "description": "Current-company tenure, for example 3 to 5 years." }, "yearsWorkExperience": { "type": "string", "description": "Total experience, for example More than 10 years." }, "skills": { "type": "string", "description": "Skills to include." }, "skillsExclude": { "type": "string", "description": "Skills to exclude." }, "language": { "type": "string", "description": "Languages to include." }, "languageExclude": { "type": "string", "description": "Languages to exclude." }, "certification": { "type": "string", "description": "Certifications to include." }, "certificationExclude": { "type": "string", "description": "Certifications to exclude." }, "profileKeywords": { "type": "string", "description": "Profile keywords to include." }, "profileKeywordsExclude": { "type": "string", "description": "Profile keywords to exclude." }, "profileBadge": { "type": "string", "description": "Profile badge values." }, "industry": { "type": "string", "description": "Company industries to include." }, "industryExclude": { "type": "string", "description": "Company industries to exclude." }, "size": { "type": "string", "description": "Company headcount range, for example 11-50." }, "hq": { "type": "string", "description": "Company headquarters locations to include." }, "hqExclude": { "type": "string", "description": "Headquarters locations to exclude." }, "type": { "type": "string", "description": "Company types, for example PRIVATELY_HELD." }, "typeExclude": { "type": "string", "description": "Company types to exclude." }, "revenue": { "type": "string", "description": "Company revenue range, for example 1000000-10000000." }, "companyKeywords": { "type": "string", "description": "Company keywords to include." }, "companyKeywordsExclude": { "type": "string", "description": "Company keywords to exclude." }, "founded": { "type": "string", "description": "Founding-year range, for example 2015-2022." }, "funding": { "type": "string", "description": "Funding rounds, for example SEED or SERIES_A." }, "fundingAmount": { "type": "string", "description": "Last funding amount range, for example 1000000-5000000." }, "fundingDateMonths": { "type": "string", "description": "Funding lookback in months, for example 12." }, "department": { "type": "string", "description": "Department and headcount range on separate lines, for example sales followed by 10-100." }, "growth": { "type": "string", "description": "Department, growth range, and period on separate lines, for example sales, 20-80, and 3 months." }, "duration": { "type": "object", "additionalProperties": false, "description": "Structured tenure bounds override the matching textual tenure field. Use non-negative integer years and months from 0 through 11.", "properties": { "latestCompany": { "type": "object", "minProperties": 1, "additionalProperties": false, "description": "When both bounds are present, min must not exceed max in total months.", "properties": { "min": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "year": { "type": "integer", "minimum": 0 }, "month": { "type": "integer", "minimum": 0, "maximum": 11 } } }, "max": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "year": { "type": "integer", "minimum": 0 }, "month": { "type": "integer", "minimum": 0, "maximum": 11 } } } } }, "currentCompany": { "type": "object", "minProperties": 1, "additionalProperties": false, "description": "When both bounds are present, min must not exceed max in total months.", "properties": { "min": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "year": { "type": "integer", "minimum": 0 }, "month": { "type": "integer", "minimum": 0, "maximum": 11 } } }, "max": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "year": { "type": "integer", "minimum": 0 }, "month": { "type": "integer", "minimum": 0, "maximum": 11 } } } } }, "previousCompany": { "type": "object", "minProperties": 1, "additionalProperties": false, "description": "When both bounds are present, min must not exceed max in total months.", "properties": { "min": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "year": { "type": "integer", "minimum": 0 }, "month": { "type": "integer", "minimum": 0, "maximum": 11 } } }, "max": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "year": { "type": "integer", "minimum": 0 }, "month": { "type": "integer", "minimum": 0, "maximum": 11 } } } } }, "latestJob": { "type": "object", "minProperties": 1, "additionalProperties": false, "description": "When both bounds are present, min must not exceed max in total months.", "properties": { "min": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "year": { "type": "integer", "minimum": 0 }, "month": { "type": "integer", "minimum": 0, "maximum": 11 } } }, "max": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "year": { "type": "integer", "minimum": 0 }, "month": { "type": "integer", "minimum": 0, "maximum": 11 } } } } }, "currentJob": { "type": "object", "minProperties": 1, "additionalProperties": false, "description": "When both bounds are present, min must not exceed max in total months.", "properties": { "min": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "year": { "type": "integer", "minimum": 0 }, "month": { "type": "integer", "minimum": 0, "maximum": 11 } } }, "max": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "year": { "type": "integer", "minimum": 0 }, "month": { "type": "integer", "minimum": 0, "maximum": 11 } } } } }, "previousJob": { "type": "object", "minProperties": 1, "additionalProperties": false, "description": "When both bounds are present, min must not exceed max in total months.", "properties": { "min": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "year": { "type": "integer", "minimum": 0 }, "month": { "type": "integer", "minimum": 0, "maximum": 11 } } }, "max": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "year": { "type": "integer", "minimum": 0 }, "month": { "type": "integer", "minimum": 0, "maximum": 11 } } } } }, "total": { "type": "object", "minProperties": 1, "additionalProperties": false, "description": "When both bounds are present, min must not exceed max in total months.", "properties": { "min": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "year": { "type": "integer", "minimum": 0 }, "month": { "type": "integer", "minimum": 0, "maximum": 11 } } }, "max": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { "year": { "type": "integer", "minimum": 0 }, "month": { "type": "integer", "minimum": 0, "maximum": 11 } } } } } } }, "searchMode": { "type": "string", "enum": [ "SMART", "WORD", "STRICT" ], "default": "SMART", "description": "Matching mode. Runtime falls back to SMART for an unrecognized value; use an explicit supported mode." } } }, "page": { "oneOf": [ { "type": "integer", "minimum": 0 }, { "type": "string", "pattern": "^(?:0|[1-9][0-9]*)$" } ], "default": 0 }, "size": { "oneOf": [ { "type": "integer", "minimum": 1, "maximum": 100 }, { "type": "string", "pattern": "^(?:[1-9]|[1-9][0-9]|100)$" } ], "default": 50 } } }, "examples": { "example": { "value": { "filters": { "job": [ "Founder" ], "company": "example.com", "peopleLocation": [ "United States" ], "searchMode": "SMART" }, "page": 0, "size": 25 } } } } } }, "responses": { "200": { "description": "A page of public lead records. No cursor is returned.", "content": { "application/json": { "schema": { "type": "object", "required": [ "rows", "total", "page", "size" ], "properties": { "rows": { "type": "array", "description": "Nested person records with snake_case keys (for example profile.first_name, link.linkedin, position_groups). Fields vary per record and may be null.", "items": { "$ref": "#/components/schemas/LeadsFinderPerson" } }, "total": { "type": [ "number", "null" ], "description": "May be null when a reliable total is unavailable or company/title correlation removes rows." }, "page": { "type": "integer" }, "size": { "type": "integer" } } }, "examples": { "example": { "value": { "rows": [ { "profile": { "first_name": "Example", "middle_name": null, "last_name": "Person", "full_name": "Example Person", "headline": "Founder at Example Company", "title": "Founder", "summary": "Synthetic profile summary for API documentation.", "birth_date": null, "background": { "source": "https://www.example.org/images/example-background.png" }, "profilePictureUrl": "https://www.example.org/images/example-person.png" }, "link": { "linkedin": "https://www.linkedin.com/in/example-person-000000", "twitter": null, "github": null, "facebook": null }, "location": { "default": "Example City, Example State, United States", "short": "Example City, United States", "country": "United States", "state": "Example State", "city": "Example City", "position": null }, "languages": { "primary_locale": { "country": "US", "language": "en" }, "supported_locales": [ { "country": "US", "language": "en" } ], "profile_languages": [ { "name": "English", "proficiency": "NATIVE_OR_BILINGUAL" } ] }, "industry": "Software Development", "educations": [ { "school": { "name": "Example University", "url": "https://www.linkedin.com/school/example-university/" }, "degree_name": "Master of Science", "field_of_study": "Computer Science", "grade": null, "date": { "start": "2014", "end": "2016" } } ], "certifications": [ { "name": "Example Certification", "authority": "Example Institute", "url": "https://www.example.org/certificates/example", "license_number": "EX-000001", "display_source": "example.org", "company": { "name": "Example Institute", "url": "https://www.linkedin.com/company/example-institute/" }, "date": { "start": "2022-01", "end": null } } ], "position_groups": [ { "company": { "name": "Example Company", "url": "https://www.linkedin.com/company/example-company-000000", "employees": { "start": 11, "end": 50 } }, "date": { "start": "2021-03", "end": null }, "profile_positions": [ { "company": "Example Company", "description": null, "title": "Founder", "employment_type": "Full-time", "location": "Example City, United States", "date": { "start": "2021-03", "end": null } } ] } ], "skills": [ "Sales prospecting", "Data enrichment" ], "member_badges": { "premium": true, "creator": false, "open_to_work": false, "hiring": false, "verified": true, "influencer": false }, "company": { "summary": { "name": "Example Company", "legal_name": "Example Company Inc.", "description": "Synthetic company description for API documentation.", "founded_year": 2021, "type": "PRIVATELY_HELD", "industry": "Software Development", "staff": { "total": 24, "range": { "start": 11, "end": 50 } }, "logo": { "source": "https://www.example.org/images/example-company.png" } }, "link": { "website": "https://www.example.org", "domain": "example.org", "linkedin": "https://www.linkedin.com/company/example-company-000000", "crunchbase": null }, "financial": { "revenue": { "annual": { "start": 1000000, "end": 5000000, "amount": "1M-5M" } } }, "location": { "headquarter": { "continent": "North America", "country": "United States", "state": "Example State", "city": "Example City", "postal_code": "00000", "raw_address": "1 Example Street, Example City, Example State 00000", "position": { "lng": -74, "lat": 40 } }, "locations": [ { "continent": "North America", "country": "United States", "state": "Example State", "city": "Example City", "postal_code": "00000", "raw_address": "1 Example Street, Example City, Example State 00000", "position": { "lng": -74, "lat": 40 } } ] }, "technologies": [ { "name": "Example CRM", "category": "CRM" } ], "industries": [ "Software Development" ], "languages": [ "English" ], "last_updated": "2026-01-01T00:00:00Z" }, "department": { "departments": [ "founder" ], "sub_departments": [ "founder" ], "functions": [ "executive" ], "seniority": "founder" }, "statistics": { "network": { "influencer": false, "followable": null, "followers_count": 1200, "connections_count": 500 }, "experience": { "prev_job_titles": null, "tenure": { "company": "Example Company", "start": "2021-03", "title": "Founder" } } }, "last_updated": "2026-01-01T00:00:00Z" } ], "total": 1, "page": 0, "size": 25 } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Insufficient credits or access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown path or method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 256 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Service configuration error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream service failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication or credit service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }, "/v1/dnc-check": { "post": { "operationId": "checkDnc", "tags": [ "Miscellaneous" ], "summary": "Check a US phone number against DNC", "description": "Checks a US phone number. A successful check costs one credit whether the number is listed or not. Non-US and malformed numbers are rejected before the provider request.", "x-airscale-rate-limit": "5 requests per second per workspace.", "x-airscale-credit-cost": "1 credit per successful check; validation and provider failures are not charged.", "requestBody": { "required": true, "content": { "application/json": { "schema": { "type": "object", "properties": { "phone": { "type": "string", "minLength": 1, "description": "Recommended phone field. A US phone number, normalized to +1 format." }, "phone_number": { "type": "string", "description": "Alias used only if phone is null or absent." }, "mobile_phone": { "type": "string", "description": "Alias used only if phone and phone_number are null or absent." } }, "anyOf": [ { "required": [ "phone" ] }, { "required": [ "phone_number" ] }, { "required": [ "mobile_phone" ] } ] }, "examples": { "example": { "value": { "phone": "+12025550147" } } } } } }, "responses": { "200": { "description": "The result of a completed DNC check.", "content": { "application/json": { "schema": { "type": "object", "required": [ "status", "phone", "listed", "result", "credits_used", "credits_remaining" ], "properties": { "status": { "type": "string", "const": "success" }, "phone": { "type": "string" }, "listed": { "type": "boolean" }, "result": { "type": "string", "enum": [ "Listed on DNC", "Not listed on DNC" ] }, "credits_used": { "type": "number" }, "credits_remaining": { "type": [ "number", "null" ] } } }, "examples": { "example": { "value": { "status": "success", "phone": "+12025550147", "listed": false, "result": "Not listed on DNC", "credits_used": 1, "credits_remaining": 99 } } } } } }, "400": { "description": "Invalid request.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "401": { "$ref": "#/components/responses/Unauthorized" }, "403": { "description": "Insufficient credits or access.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "404": { "description": "Unknown path or method.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "413": { "description": "Request body exceeds 256 KiB.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "422": { "description": "Invalid or unsupported US phone number.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "429": { "description": "Workspace rate limit exceeded.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "500": { "description": "Service configuration error.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "502": { "description": "Upstream service failed.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } }, "503": { "description": "Authentication or credit service temporarily unavailable.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } } }, "components": { "securitySchemes": { "bearerAuth": { "type": "http", "scheme": "bearer", "bearerFormat": "API key", "description": "Use an Airscale workspace API key. Never expose the key in client-side code." } }, "schemas": { "Status": { "type": "string", "enum": [ "success", "not_found", "timeout" ] }, "IncludeExcludeFilter": { "type": "object", "description": "Use include, exclude, or both. Empty arrays and empty string values are accepted by the runtime, but meaningful non-empty values are recommended.", "additionalProperties": false, "properties": { "include": { "type": "array", "maxItems": 200, "items": { "type": "string" } }, "exclude": { "type": "array", "maxItems": 200, "items": { "type": "string" } } }, "anyOf": [ { "required": [ "include" ] }, { "required": [ "exclude" ] } ] }, "IntegerRangeFilter": { "type": "object", "minProperties": 1, "additionalProperties": false, "properties": { ">": { "type": "integer" }, ">=": { "type": "integer" }, "<": { "type": "integer" }, "<=": { "type": "integer" } } }, "GrowthFilter": { "type": "object", "description": "Headcount growth bounds for one supported timespan. When both bounds are present, min must be less than or equal to max.", "x-airscale-runtime-constraint": "When both are present, min must be less than or equal to max.", "additionalProperties": false, "required": [ "timespan" ], "properties": { "min": { "type": "number", "minimum": -100, "maximum": 10000 }, "max": { "type": "number", "minimum": -100, "maximum": 10000 }, "timespan": { "type": "string", "enum": [ "6months", "12months", "24months" ] } }, "anyOf": [ { "required": [ "min" ] }, { "required": [ "max" ] } ] }, "StringOrStringArray": { "oneOf": [ { "type": "string", "minLength": 1, "pattern": "\\S" }, { "type": "array", "minItems": 1, "items": { "type": "string", "minLength": 1, "pattern": "\\S" } } ] }, "LeadsFinderPerson": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "string", "null" ], "description": "Record identifier, when available." }, "identifier": { "type": [ "string", "null" ], "description": "Public profile identifier, when available." }, "url": { "type": [ "string", "null" ], "description": "Public profile URL, when available." }, "profile": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Name, headline, and profile media.", "properties": { "first_name": { "type": [ "string", "null" ] }, "middle_name": { "type": [ "string", "null" ] }, "last_name": { "type": [ "string", "null" ] }, "full_name": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "birth_date": {}, "picture": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "source": { "type": [ "string", "null" ] } } }, "background": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "source": { "type": [ "string", "null" ] } } }, "profilePictureUrl": { "type": [ "string", "null" ], "description": "Profile picture URL, when available." } } }, "link": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Public profile links.", "properties": { "linkedin": { "type": [ "string", "null" ] }, "twitter": { "type": [ "string", "null" ] }, "github": { "type": [ "string", "null" ] }, "facebook": { "type": [ "string", "null" ] } } }, "location": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Person location.", "properties": { "default": { "type": [ "string", "null" ] }, "short": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "position": {} } }, "languages": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "primary_locale": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "country": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] } } }, "supported_locales": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "country": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] } } } }, "profile_languages": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "name": { "type": [ "string", "null" ] }, "proficiency": { "type": [ "string", "null" ] } } } } } }, "industry": { "type": [ "string", "null" ] }, "educations": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "school": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "logo": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } } }, "degree_name": { "type": [ "string", "null" ] }, "field_of_study": { "type": [ "string", "null" ] }, "grade": {}, "date": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "start": { "type": [ "string", "null" ] }, "end": { "type": [ "string", "null" ], "description": "Null while the role or credential is current." } } } } } }, "certifications": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "name": { "type": [ "string", "null" ] }, "authority": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "license_number": { "type": [ "string", "null" ] }, "display_source": { "type": [ "string", "null" ] }, "company": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "logo": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } } }, "date": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "start": { "type": [ "string", "null" ] }, "end": { "type": [ "string", "null" ], "description": "Null while the role or credential is current." } } } } } }, "position_groups": { "type": [ "array", "null" ], "description": "Work history grouped by company, most recent first.", "items": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "company": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "logo": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "employees": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "start": { "type": [ "integer", "null" ] }, "end": { "type": [ "integer", "null" ] } } } } }, "date": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "start": { "type": [ "string", "null" ] }, "end": { "type": [ "string", "null" ], "description": "Null while the role or credential is current." } } }, "profile_positions": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "company": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "employment_type": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "date": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "start": { "type": [ "string", "null" ] }, "end": { "type": [ "string", "null" ], "description": "Null while the role or credential is current." } } } } } } } } }, "skills": { "type": [ "array", "null" ], "items": { "type": "string" } }, "member_badges": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "premium": { "type": [ "boolean", "null" ] }, "creator": { "type": [ "boolean", "null" ] }, "open_to_work": { "type": [ "boolean", "null" ] }, "hiring": { "type": [ "boolean", "null" ] }, "verified": { "type": [ "boolean", "null" ] }, "influencer": { "type": [ "boolean", "null" ] } } }, "statistics": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "network": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "influencer": { "type": [ "boolean", "null" ] }, "followable": {}, "followers_count": { "type": [ "integer", "null" ] }, "connections_count": { "type": [ "integer", "null" ] } } }, "experience": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "prev_job_titles": {}, "tenure": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "company": { "type": [ "string", "null" ] }, "start": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] } } } } } } }, "company": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Current company.", "properties": { "id": { "type": [ "string", "null" ] }, "summary": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "name": { "type": [ "string", "null" ] }, "legal_name": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "founded_year": { "type": [ "integer", "null" ] }, "type": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "staff": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "total": { "type": [ "integer", "null" ] }, "range": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "start": { "type": [ "integer", "null" ] }, "end": { "type": [ "integer", "null" ] } } } } }, "logo": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "source": { "type": [ "string", "null" ] } } } } }, "link": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "website": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "linkedin": { "type": [ "string", "null" ] }, "crunchbase": { "type": [ "string", "null" ] } } }, "financial": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "revenue": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "annual": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "start": { "type": [ "integer", "null" ] }, "end": { "type": [ "integer", "null" ] }, "amount": { "type": [ "string", "null" ] } } } } } } }, "location": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "headquarter": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "continent": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "raw_address": { "type": [ "string", "null" ] }, "position": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "lng": { "type": [ "number", "null" ] }, "lat": { "type": [ "number", "null" ] } } } } }, "locations": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "continent": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "postal_code": { "type": [ "string", "null" ] }, "raw_address": { "type": [ "string", "null" ] }, "position": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "lng": { "type": [ "number", "null" ] }, "lat": { "type": [ "number", "null" ] } } } } } } } }, "technologies": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "name": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] } } } }, "industries": { "type": [ "array", "null" ], "items": { "type": "string" } }, "languages": { "type": [ "array", "null" ], "items": { "type": "string" } }, "last_updated": { "type": [ "string", "null" ] } } }, "department": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "departments": { "type": [ "array", "null" ], "items": { "type": "string" } }, "sub_departments": { "type": [ "array", "null" ], "items": { "type": "string" } }, "functions": { "type": [ "array", "null" ], "items": { "type": "string" } }, "seniority": { "type": [ "string", "null" ] } } }, "last_updated": { "type": [ "string", "null" ] } }, "description": "A Leads Finder person record with nested snake_case keys. Fields vary per record and may be null; records can include fields not listed here." }, "ReverseLookupPerson": { "type": "object", "additionalProperties": true, "properties": { "id": { "type": [ "string", "null" ], "description": "Record identifier, when available." }, "identifier": { "type": [ "string", "null" ], "description": "Public profile identifier, when available." }, "url": { "type": [ "string", "null" ], "description": "Public profile URL, when available." }, "profile": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Name, headline, and profile media.", "properties": { "firstName": { "type": [ "string", "null" ] }, "middleName": { "type": [ "string", "null" ] }, "lastName": { "type": [ "string", "null" ] }, "fullName": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "summary": { "type": [ "string", "null" ] }, "birthDate": {}, "picture": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "source": { "type": [ "string", "null" ] } } }, "background": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "source": { "type": [ "string", "null" ] } } }, "profilePictureUrl": { "type": [ "string", "null" ], "description": "Profile picture URL, when available." } } }, "link": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Public profile links.", "properties": { "linkedin": { "type": [ "string", "null" ] }, "twitter": { "type": [ "string", "null" ] }, "github": { "type": [ "string", "null" ] }, "facebook": { "type": [ "string", "null" ] } } }, "location": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Person location.", "properties": { "default": { "type": [ "string", "null" ] }, "short": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "position": {} } }, "languages": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "primaryLocale": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "country": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] } } }, "supportedLocales": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "country": { "type": [ "string", "null" ] }, "language": { "type": [ "string", "null" ] } } } }, "profileLanguages": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "name": { "type": [ "string", "null" ] }, "proficiency": { "type": [ "string", "null" ] } } } } } }, "industry": { "type": [ "string", "null" ] }, "educations": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "school": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "logo": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } } }, "degreeName": { "type": [ "string", "null" ] }, "fieldOfStudy": { "type": [ "string", "null" ] }, "grade": {}, "date": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "start": { "type": [ "string", "null" ] }, "end": { "type": [ "string", "null" ], "description": "Null while the role or credential is current." } } } } } }, "certifications": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "name": { "type": [ "string", "null" ] }, "authority": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "licenseNumber": { "type": [ "string", "null" ] }, "displaySource": { "type": [ "string", "null" ] }, "company": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "logo": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] } } }, "date": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "start": { "type": [ "string", "null" ] }, "end": { "type": [ "string", "null" ], "description": "Null while the role or credential is current." } } } } } }, "positionGroups": { "type": [ "array", "null" ], "description": "Work history grouped by company, most recent first.", "items": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "company": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "id": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "logo": { "type": [ "string", "null" ] }, "url": { "type": [ "string", "null" ] }, "employees": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "start": { "type": [ "integer", "null" ] }, "end": { "type": [ "integer", "null" ] } } } } }, "date": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "start": { "type": [ "string", "null" ] }, "end": { "type": [ "string", "null" ], "description": "Null while the role or credential is current." } } }, "profilePositions": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "company": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] }, "employmentType": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ] }, "date": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "start": { "type": [ "string", "null" ] }, "end": { "type": [ "string", "null" ], "description": "Null while the role or credential is current." } } } } } } } } }, "skills": { "type": [ "array", "null" ], "items": { "type": "string" } }, "memberBadges": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "premium": { "type": [ "boolean", "null" ] }, "creator": { "type": [ "boolean", "null" ] }, "openToWork": { "type": [ "boolean", "null" ] }, "hiring": { "type": [ "boolean", "null" ] }, "verified": { "type": [ "boolean", "null" ] }, "influencer": { "type": [ "boolean", "null" ] } } }, "statistics": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "network": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "influencer": { "type": [ "boolean", "null" ] }, "followable": {}, "followersCount": { "type": [ "integer", "null" ] }, "connectionsCount": { "type": [ "integer", "null" ] } } }, "experience": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "prevJobTitles": {}, "tenure": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "company": { "type": [ "string", "null" ] }, "start": { "type": [ "string", "null" ] }, "title": { "type": [ "string", "null" ] } } } } } } }, "company": { "type": [ "object", "null" ], "additionalProperties": true, "description": "Current company.", "properties": { "id": { "type": [ "string", "null" ] }, "summary": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "name": { "type": [ "string", "null" ] }, "legalName": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "foundedYear": { "type": [ "integer", "null" ] }, "type": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "staff": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "total": { "type": [ "integer", "null" ] }, "range": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "start": { "type": [ "integer", "null" ] }, "end": { "type": [ "integer", "null" ] } } } } }, "logo": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "source": { "type": [ "string", "null" ] } } } } }, "link": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "website": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "linkedin": { "type": [ "string", "null" ] }, "crunchbase": { "type": [ "string", "null" ] } } }, "financial": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "revenue": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "annual": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "start": { "type": [ "integer", "null" ] }, "end": { "type": [ "integer", "null" ] }, "amount": { "type": [ "string", "null" ] } } } } } } }, "location": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "headquarter": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "continent": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "postalCode": { "type": [ "string", "null" ] }, "rawAddress": { "type": [ "string", "null" ] }, "position": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "lng": { "type": [ "number", "null" ] }, "lat": { "type": [ "number", "null" ] } } } } }, "locations": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "continent": { "type": [ "string", "null" ] }, "country": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "postalCode": { "type": [ "string", "null" ] }, "rawAddress": { "type": [ "string", "null" ] }, "position": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "lng": { "type": [ "number", "null" ] }, "lat": { "type": [ "number", "null" ] } } } } } } } }, "technologies": { "type": [ "array", "null" ], "items": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "name": { "type": [ "string", "null" ] }, "category": { "type": [ "string", "null" ] } } } }, "industries": { "type": [ "array", "null" ], "items": { "type": "string" } }, "languages": { "type": [ "array", "null" ], "items": { "type": "string" } }, "lastUpdated": { "type": [ "string", "null" ] } } }, "department": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "departments": { "type": [ "array", "null" ], "items": { "type": "string" } }, "subDepartments": { "type": [ "array", "null" ], "items": { "type": "string" } }, "functions": { "type": [ "array", "null" ], "items": { "type": "string" } }, "seniority": { "type": [ "string", "null" ] } } }, "lastUpdated": { "type": [ "string", "null" ] } }, "description": "A reverse-lookup person record with nested camelCase keys. Names are under profile (profile.firstName), not at the top level. Fields vary per record and may be null; records can include fields not listed here." }, "PeopleLead": { "type": "object", "additionalProperties": true, "description": "A public person record. Other public profile fields may be included; check for missing or null values before using them.", "properties": { "firstname": { "type": [ "string", "null" ] }, "lastname": { "type": [ "string", "null" ] }, "profileUrl": { "type": [ "string", "null" ] }, "headline": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ], "description": "Profile summary." }, "address": { "type": [ "string", "null" ], "description": "Person location." }, "jobTitle": { "type": [ "string", "null" ] }, "jobDescription": { "type": [ "string", "null" ] }, "jobStartDate": { "type": [ "string", "null" ] }, "companyName": { "type": [ "string", "null" ] }, "companyUrn": { "type": [ "string", "null" ] }, "companyUrl": { "type": [ "string", "null" ], "description": "LinkedIn company URL." }, "companyWebsite": { "type": [ "string", "null" ] }, "companyDescription": { "type": [ "string", "null" ] }, "companySize": { "type": [ "integer", "string", "null" ] }, "companyIndustry": { "type": [ "string", "null" ] }, "companyAddress": { "type": [ "string", "null" ] } } }, "CompanyRow": { "type": "object", "additionalProperties": true, "description": "A public company record. Other public company fields may be included; check for missing or null values before using them.", "properties": { "name": { "type": [ "string", "null" ] }, "domain": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "logo": { "type": [ "string", "null" ] }, "countryName": { "type": [ "string", "null" ] }, "cityName": { "type": [ "string", "null" ] }, "linkedinProfile": { "type": [ "string", "null" ] }, "employeeRange": { "type": [ "string", "null" ] }, "revenueRange": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "naicsDescription": { "type": [ "string", "null" ] }, "sicCode": { "type": [ "string", "number", "null" ] }, "sicDescription": { "type": [ "string", "null" ] }, "location": { "type": [ "string", "null" ], "description": "Location text." }, "region": { "type": [ "string", "null" ] }, "industry": { "type": [ "string", "null" ] }, "naics": { "type": [ "string", "number", "null" ] }, "events": { "description": "Company events, when requested and available." }, "businessIntentTopics": { "description": "Business-intent topics, when requested and available." } } }, "LinkedInPersonUrl": { "type": "string", "minLength": 1, "description": "A recognized LinkedIn person-profile URL or identifier. Airscale normalizes supported profile inputs.", "example": "https://www.linkedin.com/in/example-person-000000" }, "SuccessEmail": { "type": "object", "required": [ "status", "email" ], "additionalProperties": true, "properties": { "status": { "type": "string", "const": "success" }, "email": { "type": "string", "format": "email" }, "email_status": { "type": "string", "description": "The value is \"valid\" on a successful result." }, "provider": { "type": "string" }, "verifier": { "type": "string" }, "catch_all": { "type": "string", "enum": [ "yes", "no" ] }, "linkedin_profile_url": { "$ref": "#/components/schemas/LinkedInPersonUrl" } } }, "NotFoundEmail": { "type": "object", "required": [ "status", "email" ], "additionalProperties": true, "properties": { "status": { "type": "string", "const": "not_found" }, "email": { "type": "null" } } }, "VariablePersonProfile": { "type": "object", "additionalProperties": true, "description": "A flat person profile. Field types can vary by data source; check for missing or null values before using them. List sections are paginated objects with totalElements, page, size, and contents.", "properties": { "url": { "type": [ "string", "null" ] }, "identifier": { "type": [ "string", "null" ] }, "entityUrn": { "description": "Profile URN, when available." }, "objectUrn": { "description": "Numeric profile identifier, when available." }, "firstname": { "description": "First name, when available." }, "lastname": { "description": "Last name, when available." }, "middleName": { "description": "Middle name, when available." }, "birthDate": { "description": "Birth date, when public." }, "headline": { "description": "Profile headline, when available." }, "summary": { "description": "Profile summary, when available." }, "picture": { "description": "Profile picture URL, when available." }, "background": { "description": "Background image URL, when available." }, "industry": { "description": "Industry, when available." }, "openToWork": { "description": "Open-to-work badge, when available." }, "influencer": { "description": "Influencer badge, when available." }, "premium": { "description": "Premium badge, when available." }, "creator": { "description": "Creator badge, when available." }, "hiring": { "description": "Hiring badge, when available." }, "verified": { "description": "Verified badge, when available." }, "location": { "description": "Location information, when available.", "properties": { "country": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "state": { "type": [ "string", "null" ] }, "defaultValue": { "type": [ "string", "null" ], "description": "Full location text." }, "shortValue": { "type": [ "string", "null" ], "description": "Short location text." } } }, "positionGroups": { "description": "Work history grouped by company, most recent first.", "properties": { "totalElements": {}, "page": {}, "size": {}, "contents": { "type": "array", "items": { "properties": { "company": { "properties": { "id": {}, "name": {}, "logo": {}, "url": {}, "domain": {}, "profileType": {} } }, "date": { "properties": { "start": {}, "end": {} } }, "profilePositions": { "type": "array", "items": { "properties": { "company": {}, "description": {}, "title": {}, "employmentType": {}, "location": {}, "date": { "properties": { "start": {}, "end": {} } } } } } } } } } }, "educations": { "description": "Paginated list section, when available.", "properties": { "totalElements": {}, "page": {}, "size": {}, "contents": { "type": "array", "items": { "properties": { "school": { "properties": { "id": {}, "name": {}, "logo": {}, "url": {}, "profileType": {} } }, "degreeName": {}, "fieldOfStudy": {}, "grade": {}, "date": { "properties": { "start": {}, "end": {} } } } } } } }, "certifications": { "description": "Paginated list section, when available.", "properties": { "totalElements": {}, "page": {}, "size": {}, "contents": { "type": "array", "items": { "properties": { "name": {}, "authority": {}, "url": {}, "licenseNumber": {}, "displaySource": {}, "company": { "properties": { "id": {}, "name": {}, "logo": {}, "url": {}, "profileType": {} } }, "date": { "properties": { "start": {}, "end": {} } } } } } } }, "languages": { "description": "Paginated list section, when available.", "properties": { "totalElements": {}, "page": {}, "size": {}, "contents": { "type": "array", "items": { "properties": { "name": {}, "proficiency": {} } } } } }, "skills": { "description": "Paginated list section, when available.", "properties": { "totalElements": {}, "page": {}, "size": {}, "contents": { "type": "array", "items": { "type": "string" } } } }, "organizations": { "description": "Paginated list section, when available.", "properties": { "totalElements": {}, "page": {}, "size": {}, "contents": { "type": "array", "items": {} } } }, "patents": { "description": "Paginated list section, when available.", "properties": { "totalElements": {}, "page": {}, "size": {}, "contents": { "type": "array", "items": {} } } }, "awards": { "description": "Paginated list section, when available.", "properties": { "totalElements": {}, "page": {}, "size": {}, "contents": { "type": "array", "items": {} } } }, "projects": { "description": "Paginated list section, when available.", "properties": { "totalElements": {}, "page": {}, "size": {}, "contents": { "type": "array", "items": {} } } }, "publications": { "description": "Paginated list section, when available.", "properties": { "totalElements": {}, "page": {}, "size": {}, "contents": { "type": "array", "items": {} } } }, "courses": { "description": "Paginated list section, when available.", "properties": { "totalElements": {}, "page": {}, "size": {}, "contents": { "type": "array", "items": {} } } }, "testScores": { "description": "Paginated list section, when available.", "properties": { "totalElements": {}, "page": {}, "size": {}, "contents": { "type": "array", "items": {} } } }, "volunteerExperiences": { "description": "Paginated list section, when available.", "properties": { "totalElements": {}, "page": {}, "size": {}, "contents": { "type": "array", "items": {} } } }, "profile": { "description": "Additional profile data, when available." }, "link": { "description": "Profile links, when available." } } }, "VariableCompanyProfile": { "type": "object", "additionalProperties": true, "description": "A company profile. Field types can vary by data source; check for missing or null values before using them.", "properties": { "url": { "type": [ "string", "null" ] }, "name": { "type": [ "string", "null" ] }, "universalName": { "type": [ "string", "null" ] }, "website": { "type": [ "string", "null" ] }, "description": { "type": [ "string", "null" ] }, "type": { "description": "Company type, for example Public Company." }, "objectUrn": { "description": "Numeric company identifier, when available." }, "phone": { "description": "Company phone, when public." }, "followers": { "description": "Follower count, when available." }, "logo": { "description": "Logo URL, when available." }, "cover": { "description": "Cover image URL, when available." }, "tagline": { "description": "Tagline, when available." }, "foundedYear": { "description": "Founding year, when available." }, "staff": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "total": { "description": "Employee count on the profile." }, "range": { "description": "Headcount band.", "properties": { "start": {}, "end": {} } } } }, "locations": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "headquarter": { "$ref": "#/components/schemas/CompanyAddress" }, "other": { "type": [ "array", "null" ], "items": { "$ref": "#/components/schemas/CompanyAddress" } } } }, "fundingData": { "description": "Funding details, when available." }, "industries": { "type": [ "array", "null" ], "items": {} }, "specialities": { "type": [ "array", "null" ], "items": {} }, "hashtags": { "description": "Company hashtags, when available." } } }, "CompanyAddress": { "type": [ "object", "null" ], "additionalProperties": true, "properties": { "country": { "type": [ "string", "null" ] }, "geographicArea": { "type": [ "string", "null" ] }, "city": { "type": [ "string", "null" ] }, "postalCode": { "type": [ "string", "null" ] }, "line1": { "type": [ "string", "null" ] }, "line2": { "type": [ "string", "null" ] }, "isPrimary": { "type": [ "boolean", "null" ] } } }, "NotFoundStatus": { "type": "object", "required": [ "status" ], "additionalProperties": false, "properties": { "status": { "type": "string", "const": "not_found" } } }, "Error": { "type": "object", "additionalProperties": true, "properties": { "error": { "type": "string" }, "message": { "type": "string" } } } }, "responses": { "Unauthorized": { "description": "The Bearer token is missing or invalid.", "content": { "application/json": { "schema": { "$ref": "#/components/schemas/Error" } } } } } } }