> ## Documentation Index
> Fetch the complete documentation index at: https://docs.firmable.com/llms.txt
> Use this file to discover all available pages before exploring further.

# People search

> Find people matching structured filters, including filters on their employer

People search accepts every people and company filter. Company filters apply to the person's
employer. See [Filters](https://docs.firmable.com/partner/filters.md) for the filters and the forms their codes take.

Records carry contact availability flags only. Pass a record's `id` to
[people enrichment](https://docs.firmable.com/partner/people-enrichment.md) for contact details.

## Contact availability flags

| Flag | Meaning |
| - | - |
| `has_email` | Firmable holds a work email for the person. |
| `has_phone` | Firmable holds a phone number for the person. |
| `has_mobile` | Firmable holds a mobile number for the person. |
| `has_dnd_phone` | A phone number Firmable holds for the person is on a Do Not Call register. |


## OpenAPI

````yaml POST /partner/{partner}/people/search
openapi: 3.0.1
info:
  title: Firmable API
  description: >-
    The Firmable API provides access to company and people data across multiple
    countries including Australia, New Zealand, Singapore, Malaysia, Indonesia,
    Philippines, Hong Kong, Japan, Vietnam, South Korea, Thailand, United
    States, and Canada. Use it to look up company profiles, retrieve contact
    information, and search for people by company, position, seniority, and
    department.
  license:
    name: MIT
  version: 1.0.0
servers:
  - url: https://api.firmable.com
security:
  - bearerAuth: []
paths:
  /partner/{partner}/people/search:
    post:
      description: >-
        Returns people matching people filters. Company filters apply to the
        person's employer. Records carry contact availability flags only.
      parameters:
        - name: partner
          in: path
          required: true
          description: >-
            Your platform's identifier. Firmable gives it to you during
            onboarding.
          schema:
            type: string
      requestBody:
        required: true
        content:
          application/json:
            schema:
              $ref: '#/components/schemas/PartnerSearchRequest'
            example:
              filters:
                seniority:
                  - '3'
                department:
                  - '14'
                industry:
                  - l1:R
                location:
                  - state:VIC, AU:AU
              country:
                - AU
              page:
                from: 0
                size: 25
      responses:
        '200':
          description: Matching people
          content:
            application/json:
              schema:
                $ref: '#/components/schemas/PartnerPeopleSearch'
              example:
                records:
                  - id: fp000000000201
                    name: Jordan Lee
                    position: Chief Financial Officer
                    company_name: Harbourline Logistics
                    company_id: f000000000101
                    has_email: true
                    has_phone: true
                    has_mobile: true
                    has_dnd_phone: false
                total: 41
                page:
                  from: 0
                  size: 25
        '401':
          description: Missing or invalid API key
components:
  schemas:
    PartnerSearchRequest:
      type: object
      properties:
        filters:
          type: object
          description: >-
            An object of filter identifier to an array of 1 to 100 codes. Codes
            within one filter are combined with OR. Different filters are
            combined with AND. Get codes from GET /filter-options. Accepts every
            company and people filter.
          properties:
            industry:
              type: array
              description: 'Industry codes, two levels. Example codes: l1:K, 80'
              minItems: 1
              maxItems: 100
              items:
                type: string
            location:
              type: array
              description: 'Location (Company). State codes. Example codes: state:VIC, AU:AU'
              minItems: 1
              maxItems: 100
              items:
                type: string
            hq_location:
              type: array
              description: >-
                Headquarters (Location). Country or state codes. Example codes:
                country:US:US, state:NSW, AU:AU
              minItems: 1
              maxItems: 100
              items:
                type: string
            company_size:
              type: array
              description: >-
                Employee count (Country). Band codes, or one range, per market.
                Example codes: 3, range:100-
              minItems: 1
              maxItems: 100
              items:
                type: string
            global_company_size:
              type: array
              description: >-
                Employee count (Global). Band codes, or one range, worldwide.
                Example codes: 8, range:10000-
              minItems: 1
              maxItems: 100
              items:
                type: string
            revenue:
              type: array
              description: 'Revenue. List codes. Example codes: 2, 9'
              minItems: 1
              maxItems: 100
              items:
                type: string
            company_type:
              type: array
              description: 'Type. List codes. Example codes: 1, 2'
              minItems: 1
              maxItems: 100
              items:
                type: string
            year_founded:
              type: array
              description: >-
                Year founded. Band codes, or one range. Example codes: 1,
                range:2015-2020
              minItems: 1
              maxItems: 100
              items:
                type: string
            is_mnc:
              type: array
              description: 'Multinational. List codes. Example codes: 1, 2'
              minItems: 1
              maxItems: 100
              items:
                type: string
            b2b_vs_b2c:
              type: array
              description: 'Target customer type. List codes. Example codes: 1, 2'
              minItems: 1
              maxItems: 100
              items:
                type: string
            target_market:
              type: array
              description: 'Target market focus. List codes. Example codes: 1, 2'
              minItems: 1
              maxItems: 100
              items:
                type: string
            multiple_locations:
              type: array
              description: 'Multiple locations. List codes. Example codes: 1, 2'
              minItems: 1
              maxItems: 100
              items:
                type: string
            job_posts:
              type: array
              description: 'Job posts. List codes. Example codes: 4, 7'
              minItems: 1
              maxItems: 100
              items:
                type: string
            keywords:
              type: array
              description: 'Keywords. Free text. Example codes: contains:payroll'
              minItems: 1
              maxItems: 100
              items:
                type: string
            services:
              type: array
              description: 'Services provided. Free text. Example codes: contains:plumbing'
              minItems: 1
              maxItems: 100
              items:
                type: string
            products:
              type: array
              description: 'Products. Free text. Example codes: contains:solar panels'
              minItems: 1
              maxItems: 100
              items:
                type: string
            position:
              type: array
              description: >-
                Job title. Free text. Example codes: contains:chief financial
                officer
              minItems: 1
              maxItems: 100
              items:
                type: string
            seniority:
              type: array
              description: 'Seniority. List codes. Example codes: 3, 4'
              minItems: 1
              maxItems: 100
              items:
                type: string
            department:
              type: array
              description: 'Department. List codes. Example codes: 2, 14'
              minItems: 1
              maxItems: 100
              items:
                type: string
            skills:
              type: array
              description: 'Skills. Free text. Example codes: contains:python'
              minItems: 1
              maxItems: 100
              items:
                type: string
            current_role_duration:
              type: array
              description: 'Job change. List codes. Example codes: 4, 13'
              minItems: 1
              maxItems: 100
              items:
                type: string
            people_location:
              type: array
              description: 'Location (People). State codes. Example codes: state:QLD, AU:AU'
              minItems: 1
              maxItems: 100
              items:
                type: string
        country:
          type: array
          description: The markets to search, as market codes. Every market when omitted.
          items:
            type: string
            enum:
              - AU
              - NZ
              - SG
              - MY
              - ID
              - PH
              - TH
              - VN
              - HK
              - JP
              - KR
              - US
              - CA
        page:
          type: object
          properties:
            from:
              type: integer
              minimum: 0
              maximum: 10000
              default: 0
              description: Offset, 0 to 10,000.
            size:
              type: integer
              minimum: 1
              maximum: 100
              default: 25
              description: Records per page, 1 to 100.
    PartnerPeopleSearch:
      type: object
      properties:
        records:
          type: array
          items:
            type: object
            properties:
              id:
                type: string
                description: >-
                  Firmable person id. Pass it to people enrichment for contact
                  details.
              name:
                type: string
                description: Full name
              position:
                type: string
                description: Current job title
              company_name:
                type: string
                description: Employer name
              company_id:
                type: string
                description: Employer's Firmable company id
              has_email:
                type: boolean
                description: Firmable holds a work email for the person
              has_phone:
                type: boolean
                description: Firmable holds a phone number for the person
              has_mobile:
                type: boolean
                description: Firmable holds a mobile number for the person
              has_dnd_phone:
                type: boolean
                description: >-
                  A phone number Firmable holds for the person is on a Do Not
                  Call register
        total:
          type: integer
          description: Total matching people
        page:
          type: object
          properties:
            from:
              type: integer
              minimum: 0
              maximum: 10000
              default: 0
              description: Offset, 0 to 10,000.
            size:
              type: integer
              minimum: 1
              maximum: 100
              default: 25
              description: Records per page, 1 to 100.
  securitySchemes:
    bearerAuth:
      type: http
      scheme: bearer

````

This documentation is built and hosted on [Mintlify](https://mintlify.com), a developer documentation platform.