# Get Buying Group Contacts

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.

Endpoint: POST /v3/contacts/buying-group
Security: ApiKeyAuth

## Request fields (application/json):

  - `companies` (array, required)

  - `companies.clientReferenceId` (string)
    Optional caller-supplied token, echoed back on the matching result.
    Example: "comp-ref-1"

  - `companies.domain` (string)
    Example: "acme.com"

  - `companies.id` (string)
    Lusha company ID.
    Example: "v1.AbCdEfGhIjKlMnOpQrStUvWxYz012345"

  - `personas` (array)
    Filter results to specific persona roles. Omit to return all three.
    Enum: "decision_maker", "potential_champion", "end_user"

  - `contactsLimit` (integer)
    Maximum number of contacts returned per company.
    Example: 20

  - `pagination` (object)
    Optional. If omitted, defaults to page 0, size 100.

  - `pagination.page` (integer)

  - `pagination.size` (integer)
    Example: 100

## Response 200 fields (application/json):

  - `requestId` (string)
    Example: "951d46da-24f9-4608-84bf-5e70a10bf851"

  - `results` (array)

  - `results.clientReferenceId` (string)
    Example: "comp-ref-1"

  - `results.companyId` (string)
    Example: "v1.ocoj3UrkPqHcR8yAEosYFTuVXTH282LP"

  - `results.contacts` (array)

  - `results.contacts.id` (string)
    Example: "v1.VdKU4HkaDb7CE4CEImoUcm7bxUGUUz-aOQ"

  - `results.contacts.firstName` (string)
    Example: "Mohammed"

  - `results.contacts.lastName` (string)
    Example: "Alam"

  - `results.contacts.jobTitle` (object)

  - `results.contacts.jobTitle.title` (string)
    Example: "RF/Analog IC Design Engineer"

  - `results.contacts.jobTitle.departments` (array)
    Example: ["Engineering & Technical"]

  - `results.contacts.jobTitle.seniority` (string)
    Example: "Non-Manager"

  - `results.contacts.company` (object)

  - `results.contacts.company.id` (string)
    Example: "v1.ocoj3UrkPqHcR8yAEosYFTuVXTH282LP"

  - `results.contacts.company.name` (string)
    Example: "Intel"

  - `results.contacts.company.domain` (string)
    Example: "www.intel.com"

  - `results.contacts.location` (object)

  - `results.contacts.location.country` (string)
    Example: "United States"

  - `results.contacts.location.state` (string)
    Example: "Arizona"

  - `results.contacts.location.city` (string)
    Example: "Chandler"

  - `results.contacts.socialLinks` (object)

  - `results.contacts.socialLinks.linkedin` (string)
    Example: "https://www.linkedin.com/in/mohammed-alam-83759111"

  - `results.contacts.has` (array)
    Example: ["firstName","lastName","jobTitle","company","location","socialLinks","phones","previousEmployment","jobStartDate"]

  - `results.contacts.canReveal` (array)

  - `results.contacts.canReveal.field` (string)
    Enum: "emails", "phones"

  - `results.contacts.canReveal.credits` (integer)
    Credit cost (0 when already revealed for this account)
    Example: 1

  - `results.contacts.roles` (array)
    Persona role(s) the model assigned to this contact.
    Enum: "decision_maker", "potential_champion", "end_user"

  - `results.contacts.score` (number)
    Relevance score for the assigned role(s).
    Example: 0.8872673511505127

  - `results.contacts.error` (object)
    Per-item error in a batch response

  - `results.contacts.error.code` (string)
    Enum: "NOT_FOUND", "COMPLIANCE_RESTRICTED", "ENRICH_FAILED", "NO_SCORE"

  - `results.contacts.error.message` (string)
    Example: "Contact not found"

  - `results.error` (object)
    Per-item error in a batch response

  - `pagination` (object)

  - `pagination.page` (integer)

  - `pagination.size` (integer)
    Example: 25

  - `pagination.total` (integer)

  - `billing` (object)
    Credit usage summary for a V3 API request

  - `billing.creditsCharged` (integer)
    Total credits charged for this request
    Example: 3

  - `billing.resultsReturned` (integer)
    Number of successful results returned
    Example: 1

## Response 400 fields (application/json):

  - `statusCode` (integer, required)
    HTTP status code
    Example: 400

  - `message` (string, required)
    Error message
    Example: "Validation failed"

  - `errors` (array)
    Detailed error messages (optional, only for validation errors)
    Example: ["entityType must be one of: contact, company"]