Persona classification over a fixed set of up to 25 named accounts — labels each returned contact decision_maker, potential_champion or end_user with a relevance score. Released 2026-08-12 as the replacement for the retired Decision Makers endpoint.
Each operation below carries the questions people ask an LLM about it and the instructions they give an agent to run it. Generated by API Evangelist overlay
Every API here is available over the APIs.io API and to AI agents over MCP.
One button, every client — Claude, Cursor, VS Code and the rest.
https://apis.io/mcp
find_apisBrowse and filter every API in the catalog.get_api_artifactsOne API's artifacts, grouped by type.get_openapiThe primary OpenAPI for this API.find_similar_apisAPIs that look like this one.apis_io_searchSTART HERE — APIs, providers and tags for one query, each with its total.resolveTurn a domain, URL or GitHub org into the provider it belongs to.find_cohortsEvery scored population of providers in the catalog.curl "https://apis.io/api/v1/apis/lusha:lusha-buying-group-api"curl "https://apis.io/api/v1/apis?limit=25"Discovery needs no key. Ratings and market analysis are Pro.
Free tier, no form to fill in. Signing in shares your email address with us — we store it to create your key and to recognise you if you sign in with another provider. See our Privacy Policy and Terms.
A second provider on the same verified email joins the account you already have.
openapi: 3.2.0
info:
title: Lusha API Documentation Buying Group API
version: ''
x-logo:
url: https://www.lusha.com/logo.png
license:
name: Proprietary
url: https://lusha.com/legal/terms
description: '**This is the Lusha API V3 documentation.**
V3 introduces a new search-then-enrich pattern, bulk operations, AI-powered lookalikes, and richer filter capabilities.'
contact:
name: Lusha Support
url: https://api.lusha.com
email: support@lusha.com
termsOfService: https://lusha.com/legal/terms
x-privacy-policy:
name: Privacy Policy
url: https://lusha.com/legal/privacy-notice/
servers:
- url: https://api.lusha.com
description: Production server
security:
- ApiKeyAuth: []
tags:
- name: Buying Group
description: '**Buying Group API:** Identify and prioritize the buying committee within a set of target companies.'
x-tag-expanded: true
paths:
/v3/contacts/buying-group:
post:
tags:
- Buying Group
summary: Get Buying Group Contacts
operationId: getContactsBuyingGroup
description: 'Identify the buying group within a set of target companies. Supply companies by `domain` or Lusha company `id` - the model scores and labels each returned contact with a persona role.
**Personas:**
- `decision_maker` — has budget or sign-off authority
- `potential_champion` — likely internal advocate for the purchase
- `end_user` — likely day-to-day user of the product
Pass `personas` to filter to specific roles, or omit it to get all three. Use `contactsLimit` to cap how many contacts are returned per company (default 60).
Results are lightweight previews grouped by company. Each contact includes a `has` field listing available data points, a `canReveal` field showing what can be unlocked via Enrich, a `roles` array with the assigned persona(s), and a `score` (0-1) reflecting relevance to the assigned role.
Use Enrich Contacts with the returned contact `id` to reveal emails and phones.
> **Billing:** Charged per contact returned via the `buyingGroupContact` action.'
requestBody:
required: true
content:
application/json:
schema:
$ref: '#/components/schemas/V3BuyingGroupRequest'
example:
companies:
- clientReferenceId: comp-ref-1
domain: acme.com
- clientReferenceId: comp-ref-2
id: v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345
personas:
- decision_maker
- potential_champion
contactsLimit: 20
responses:
'200':
description: Successful response
content:
application/json:
schema:
$ref: '#/components/schemas/V3BuyingGroupResponse'
example:
requestId: 951d46da-24f9-4608-84bf-5e70a10bf851
results:
- companyId: v1.ocoj3UrkPqHcR8yAEosYFTuVXTH282LP
contacts:
- id: v1.VdKU4HkaDb7CE4CEImoUcm7bxUGUUz-aOQ
firstName: Mohammed
lastName: Alam
jobTitle:
title: RF/Analog IC Design Engineer
departments:
- Engineering & Technical
seniority: Non-Manager
company:
id: v1.ocoj3UrkPqHcR8yAEosYFTuVXTH282LP
name: Intel
domain: www.intel.com
location:
country: United States
state: Arizona
city: Chandler
socialLinks:
linkedin: https://www.linkedin.com/in/mohammed-alam-83759111
has:
- firstName
- lastName
- jobTitle
- company
- location
- socialLinks
- phones
- previousEmployment
- jobStartDate
canReveal:
- field: phones
credits: 5
roles:
- potential_champion
score: 0.8872673511505127
pagination:
page: 0
size: 100
total: 1
billing:
creditsCharged: 1
resultsReturned: 1
'400':
$ref: '#/components/responses/BadRequest'
'401':
$ref: '#/components/responses/Unauthorized'
'402':
$ref: '#/components/responses/PaymentRequired'
'403':
$ref: '#/components/responses/Forbidden'
'429':
$ref: '#/components/responses/TooManyRequests'
components:
schemas:
V3PaginationResponse:
type: object
properties:
page:
type: integer
example: 0
size:
type: integer
example: 25
total:
type: integer
ErrorResponse:
type: object
required:
- statusCode
- message
properties:
statusCode:
type: integer
description: HTTP status code
example: 400
message:
type: string
description: Error message
example: Validation failed
errors:
type: array
items:
type: string
description: Detailed error messages (optional, only for validation errors)
example:
- 'entityType must be one of: contact, company'
V3ItemError:
type: object
description: Per-item error in a batch response
properties:
code:
type: string
enum:
- NOT_FOUND
- COMPLIANCE_RESTRICTED
- ENRICH_FAILED
- NO_SCORE
example: NOT_FOUND
message:
type: string
example: Contact not found
V3CanRevealItem:
type: object
description: Indicates a data type that can be revealed and its credit cost
properties:
field:
type: string
enum:
- emails
- phones
example: emails
credits:
type: integer
description: Credit cost (0 when already revealed for this account)
example: 1
V3BuyingGroupRequest:
type: object
required:
- companies
properties:
companies:
type: array
items:
$ref: '#/components/schemas/V3BuyingGroupCompanyItem'
minItems: 1
maxItems: 25
personas:
type: array
description: Filter results to specific persona roles. Omit to return all three.
items:
type: string
enum:
- decision_maker
- potential_champion
- end_user
example:
- decision_maker
- potential_champion
contactsLimit:
type: integer
description: Maximum number of contacts returned per company.
default: 60
minimum: 1
example: 20
pagination:
type: object
description: Optional. If omitted, defaults to page 0, size 100.
properties:
page:
type: integer
minimum: 0
default: 0
example: 0
size:
type: integer
minimum: 10
maximum: 100
default: 100
example: 100
V3BuyingGroupResponse:
type: object
properties:
requestId:
type: string
format: uuid
example: 951d46da-24f9-4608-84bf-5e70a10bf851
results:
type: array
items:
$ref: '#/components/schemas/V3BuyingGroupCompanyResult'
pagination:
$ref: '#/components/schemas/V3PaginationResponse'
billing:
$ref: '#/components/schemas/V3Billing'
V3BuyingGroupCompanyResult:
type: object
properties:
clientReferenceId:
type: string
example: comp-ref-1
companyId:
type: string
example: v1.ocoj3UrkPqHcR8yAEosYFTuVXTH282LP
contacts:
type: array
items:
$ref: '#/components/schemas/V3BuyingGroupContact'
error:
$ref: '#/components/schemas/V3ItemError'
V3Billing:
type: object
description: Credit usage summary for a V3 API request
properties:
creditsCharged:
type: integer
description: Total credits charged for this request
example: 3
resultsReturned:
type: integer
description: Number of successful results returned
example: 1
V3BuyingGroupCompanyItem:
type: object
description: Identifies one target company. Provide exactly one of domain or id.
properties:
clientReferenceId:
type: string
description: Optional caller-supplied token, echoed back on the matching result.
example: comp-ref-1
domain:
type: string
example: acme.com
id:
type: string
description: Lusha company ID.
example: v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345
V3BuyingGroupContact:
type: object
properties:
id:
type: string
example: v1.VdKU4HkaDb7CE4CEImoUcm7bxUGUUz-aOQ
firstName:
type: string
example: Mohammed
lastName:
type: string
example: Alam
jobTitle:
type: object
properties:
title:
type: string
example: RF/Analog IC Design Engineer
departments:
type: array
items:
type: string
example:
- Engineering & Technical
seniority:
type: string
example: Non-Manager
company:
type: object
properties:
id:
type: string
example: v1.ocoj3UrkPqHcR8yAEosYFTuVXTH282LP
name:
type: string
example: Intel
domain:
type: string
example: www.intel.com
location:
type: object
properties:
country:
type: string
example: United States
state:
type: string
example: Arizona
city:
type: string
example: Chandler
socialLinks:
type: object
properties:
linkedin:
type: string
example: https://www.linkedin.com/in/mohammed-alam-83759111
has:
type: array
items:
type: string
example:
- firstName
- lastName
- jobTitle
- company
- location
- socialLinks
- phones
- previousEmployment
- jobStartDate
canReveal:
type: array
items:
$ref: '#/components/schemas/V3CanRevealItem'
roles:
type: array
description: Persona role(s) the model assigned to this contact.
items:
type: string
enum:
- decision_maker
- potential_champion
- end_user
example:
- potential_champion
score:
type: number
minimum: 0
maximum: 1
description: Relevance score for the assigned role(s).
example: 0.8872673511505127
error:
$ref: '#/components/schemas/V3ItemError'
responses:
Forbidden:
description: Forbidden - account inactive, V3 access not enabled, or plan does not include this feature
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
examples:
accountInactive:
summary: Account inactive
value:
statusCode: 403
message: Your account is not active. Please reach out to support at support@lusha.com
v3NotEnabled:
summary: V3 access not enabled
value:
statusCode: 403
message: V3 API access is not enabled for your account
Unauthorized:
description: Unauthorized - invalid or missing API key
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 401
message: Invalid API key
TooManyRequests:
description: Too many requests - rate limit exceeded
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 429
message: Too many requests. Please wait before making another request.
headers:
x-rate-limit-daily:
description: Total requests allowed per day
schema:
type: integer
x-daily-requests-left:
description: Requests remaining in daily quota
schema:
type: integer
x-rate-limit-hourly:
description: Total requests allowed per hour
schema:
type: integer
x-hourly-requests-left:
description: Requests remaining in hourly quota
schema:
type: integer
x-rate-limit-minute:
description: Total requests allowed per minute
schema:
type: integer
x-minute-requests-left:
description: Requests remaining in current minute window
schema:
type: integer
BadRequest:
description: Bad request - invalid input data
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 400
message: Invalid request parameters
PaymentRequired:
description: Payment required - insufficient credits
content:
application/json:
schema:
$ref: '#/components/schemas/ErrorResponse'
example:
statusCode: 402
message: Insufficient credits for this operation
securitySchemes:
ApiKeyAuth:
type: apiKey
in: header
name: api_key
description: 'Your Lusha API key. You can find this in your Lusha dashboard under API settings.
Include this key in the `api_key` header for all requests.
'